DBFullService

DBFullService es una librería privada escrita en TypeScript que facilita la realización de operaciones CRUD y consultas SQL dinámicas sobre bases de datos de forma remota. Aprovecha Axios para las peticiones HTTP y CryptoJS para encriptar la información, ofreciendo seguridad y flexibilidad en cada operación.

Tabla de Contenidos

• Instalación
• Uso
  • Uso de dbFull (Servicio Core)
  • Uso de dbFullDataBase (Servicio de Base de Datos)
  • Uso de dbFullTable (Servicio de Tabla)
• Descripción de la API
• Consideraciones de Seguridad
• Contribución
• Licencia

Instalación

Dado que DBFullService es una librería privada, no se encuentra publicada en el registro público de npm. Puedes instalarla directamente desde GitHub utilizando el siguiente comando:

npm install jermsoft-dbfullservice

Nota: Asegúrate de contar con los permisos necesarios para acceder al repositorio si es privado.

Inicio Rápido

La librería organiza las operaciones en tres niveles jerárquicos:

• dbFull: La clase base que maneja operaciones generales.
• dbFullDataBase: Especializada en interactuar con una única base de datos, inyectando el contexto db en cada petición.
• dbFullTable: Especializada en trabajar sobre una tabla específica de una base de datos, inyectando tanto el db como el table en cada petición.

Uso de dbFull (Servicio Core)

La clase dbFull proporciona métodos para ejecutar operaciones GET, POST, PUT, consultas arbitrarias, conteo de registros y SELECT de forma dinámica. Por ejemplo:

import { dbFull } from 'jermsoft-dbfullservice';

// Crear una instancia del servicio global
const service = new dbFull();

// Ejemplo de petición GET para obtener todos los registros de una tabla:
service.GET({
  db: "myDatabase",
  table: "myTable",
  type: "find-all-info"
})
.then(data => console.log("Registros:", data))
.catch(error => console.error("Error en GET:", error));

Uso de dbFullDataBase (Servicio de Base de Datos)

Con dbFullDataBase puedes fijar el contexto de la base de datos, por lo que no tendrás que especificar el parámetro db en cada petición:

import { dbFullDataBase } from 'jermsoft-dbfullservice';

// Crear una instancia para una base de datos específica
const myDatabase = new dbFullDataBase("myDatabase");

// Ejemplo de petición GET para obtener registros de una tabla en esa base:
myDatabase.GET({
  table: "myTable",
  type: "find-any-info",
  campo: "name",
  valor: "John Doe"
})
.then(data => console.log("Registros en la base:", data))
.catch(err => console.error("Error:", err));

Uso de dbFullTable (Servicio de Tabla)

La clase dbFullTable inyecta automáticamente tanto el contexto de la base de datos como el de la tabla, simplificando las peticiones a ese nivel:

import { dbFullTable } from 'jermsoft-dbfullservice';

// Crear una instancia para una tabla específica en una base de datos
const myTable = new dbFullTable("myDatabase", "myTable");

// Ejemplo de petición SELECT para obtener columnas específicas:
myTable.SELECT({
  select: ["id", "name"],
  where: { active: true }
})
.then(result => console.log("Datos seleccionados:", result))
.catch(error => console.error("Error en SELECT:", error));

Descripción de la API

Clase: dbFull

• GET: Recupera registros según la petición y contexto (db y table) proporcionados.
• POST: Inserta nuevos registros en una tabla, permitiendo incluir información adicional como claves especiales o relaciones.
• PUT: Actualiza registros ya existentes en la base de datos.
• GET_ANY_QUERY: Ejecuta una consulta SQL arbitraria (únicamente SELECT) con precaución.
• GET_LENGTH: Realiza un conteo de registros que cumplen condiciones especificadas.
• SELECT: Realiza una consulta SELECT para obtener un subconjunto de columnas o registros.

Clase: dbFullDataBase

• Extiende las funcionalidades de dbFull inyectando el contexto de base de datos (db) en cada petición.
• Reutiliza métodos GET, POST, PUT, GET_ANY_QUERY, GET_LENGTH y SELECT sin tener que especificar el db en cada llamada.

Clase: dbFullTable

• Extiende dbFullDataBase inyectando además el contexto de la tabla (table) en cada operación.
• Permite realizar operaciones específicas a una única tabla dentro de una base de datos, manteniendo una configuración centralizada.

Consideraciones de Seguridad

• Encriptación:
  La librería utiliza AES (modo ECB) a través de CryptoJS para encriptar datos y cabeceras. Si manejas información altamente sensible, evalúa la posibilidad de usar modos más seguros como CBC o GCM.

• Construcción de Queries:
  Las consultas SQL se generan de forma dinámica concatenando strings. Asegúrate de validar y sanitizar los datos que se usan en las condiciones para evitar inyecciones SQL.

• Configuración:
  Los datos de configuración (como tokens y claves) se definen en el código (variable __privateData), pero se recomienda externalizarlos a variables de entorno para producción.

Ejemplo de uso de los métodos disponibles

A continuación se presentan ejemplos de uso para los métodos más utilizados de la librería, junto con detalles relevantes en cada caso:

GET

Ejemplo con find-all-info

Este ejemplo obtiene todos los registros de una tabla sin aplicar ningún filtro.

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.GET({
  db: "myDatabase",
  table: "myTable",
  type: "find-all-info"
})
.then(data => console.log("Registros (find-all-info):", data))
.catch(error => console.error("Error en GET (find-all-info):", error));

Información:

• El tipo "find-all-info" se utiliza para recuperar todos los registros sin filtrar.
• Útil para obtener el conjunto completo de datos o para procesos de respaldo.

Ejemplo con find-any-info

Este ejemplo obtiene registros que cumplen con una condición (y opcionalmente paginados).

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.GET({
  db: "myDatabase",
  table: "myTable",
  type: "find-any-info",
  campo: "status",
  valor: "active",
  limit: 10,
  page: 1
})
.then(data => console.log("Registros (find-any-info):", data))
.catch(error => console.error("Error en GET (find-any-info):", error));

Información:

• Permite especificar filtros mediante pares campo/valor.
• Los parámetros limit y page facilitan la paginación de resultados.

POST

Ejemplo con create-info

Inserta un nuevo registro en la tabla utilizando el tipo "create-info".

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.POST({
  db: "myDatabase",
  table: "myTable",
  type: "create-info",
  "x-keys-to-add-id": ["id"]
}, {
  name: "Juan Pérez",
  email: "[email protected]",
  status: "active"
})
.then(newRecord => console.log("Registro insertado (create-info):", newRecord))
.catch(error => console.error("Error en POST (create-info):", error));

Información:

• Con "x-keys-to-add-id" se indica que se debe asignar un ID automáticamente.
• Es ideal para operaciones de inserción cuando se necesita un identificador único generado en el servidor.

Ejemplo con create-or-find

Este ejemplo intenta crear un registro, o si ya existe (según el filtro), lo retorna para evitar duplicados.

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.POST({
  db: "myDatabase",
  table: "myTable",
  type: "create-or-find",
  campo: "email",
  valor: "[email protected]",
  "x-keys-of-arrays": ["roles"]
}, {
  name: "María Gómez",
  email: "[email protected]",
  roles: ["admin", "editor"]
})
.then(record => console.log("Registro retornado (create-or-find):", record))
.catch(error => console.error("Error en POST (create-or-find):", error));

Información:

• Si ya existe un registro con el email especificado, se retorna en lugar de crear un duplicado.
• Útil para mantener la integridad de datos en campos únicos.

PUT

Ejemplo con update-info

Actualiza campos específicos de un registro. En este ejemplo se actualiza el estado de un usuario a "inactive".

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.PUT({
  db: "myDatabase",
  table: "myTable",
  type: "update-info",
  campo: "id",
  valor: 123
}, {
  id: 123,
  status: "inactive"
})
.then(result => console.log("Resultado de la actualización (update-info):", result))
.catch(error => console.error("Error en PUT (update-info):", error));

Información:

• Actualiza el registro identificado por el campo "id".
• Permite actualizar uno o varios campos del registro de forma flexible.

GET_ANY_QUERY

Ejemplo de consulta arbitraria

Ejecuta una consulta SQL arbitraria (solo SELECT) sobre la base de datos.

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.GET_ANY_QUERY({
  db: "myDatabase",
  query: "SELECT * FROM myTable WHERE status='active'"
})
.then(result => console.log("Resultado de GET_ANY_QUERY:", result))
.catch(error => console.error("Error en GET_ANY_QUERY:", error));

Información:

• Permite ejecutar consultas personalizadas.
• Se debe usar con precaución y sanitizar la query para evitar inyecciones SQL.

GET_LENGTH

Ejemplo para contar registros

Cuenta el número de registros que cumplen una condición (por ejemplo, los usuarios activos).

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.GET_LENGTH({
  db: "myDatabase",
  table: "myTable",
  where: { status: "active" }
})
.then(count => console.log("Cantidad de registros activos:", count))
.catch(error => console.error("Error en GET_LENGTH:", error));

Información:

• Utiliza internamente una consulta COUNT(*) para obtener el total.
• Es fundamental para tareas de paginación y análisis de datos.

SELECT

Ejemplo para seleccionar columnas específicas

Recupera únicamente las columnas id y name de los registros que cumplan con la condición status = "active".

import { dbFull } from 'jermsoft-dbfullservice';

const service = new dbFull();

service.SELECT({
  db: "myDatabase",
  table: "myTable",
  select: ["id", "name"],
  where: { status: "active" }
})
.then(result => console.log("Datos seleccionados:", result))
.catch(error => console.error("Error en SELECT:", error));

Información:

• Útil para minimizar la cantidad de datos transferidos, recuperando solo la información necesaria.
• La condición WHERE ayuda a filtrar los registros de forma precisa.

Contribución

Al tratarse de una librería privada, las contribuciones deben seguir las directrices internas del proyecto. Sin embargo, si encuentras mejoras o errores:

1. Haz un fork del repositorio.
2. Crea una rama para la feature o corrección.
3. Envía un pull request asegurándote de que las pruebas se ejecuten correctamente.

Consulta la documentación interna para más detalles sobre el proceso de contribución.

Licencia

Este proyecto se distribuye bajo la licencia [Your License Name] (actualiza este campo según corresponda). Revisa el archivo LICENSE en el repositorio para más información.