@gecosuy/angular-dynconfig v16.0.0

1. Introducción

Librería Angular para el manejo de configuraciones dinámicas que son obtenidas de un origen y procesadas para luego poder ser consultadas de diferentes formas.

Maneja 2 tipos de configuraciones:

Configuración de ambiente

Esta configuración NO depende del usuario logueado.
La librería la obtiene invocando a la función fetchers.environment() que se le pasa en su configuración.

Configuración general

Esta es la configuración general de la app ya obtenida para el usuario logueado.
Esisten 2 formas de obtener configuración general, la primera cuando el usuario está logueado pero aún no está trabajando con ninguna empresa (por ejemplo está en otras pantallas que no correpsonden al trabajo con una empresa determinada), en cuyo caso la configuración se obtiene invocando a la función fetchers.fetchSessionConfiguration(), y la segunda corresponde a cuando se selecciona una empresa con la cual trabajar, en cuyo caso la configuración se obtiene invocando a la función fetchers.fetchActiveCompanyConfiguration(). Este último caso puede no aplicar si la app cliente de esta librería no utiliza el concepto del trabajo con empresa activa.

2. Instalación

npm i @gecosuy/angular-dynconfig

Luego se deberán realizar los siguientes pasos:

Proveer la configuración al módulo

{
    provide: DYNCONFIG_CONFIG,
    useFactory: getDynConfigurationConfig
}

export function getDynConfigurationConfig(): DynConfigurationModuleConfig<Configuration> {
    // construir un objeto DynConfigurationModuleConfig con la configuración necesaria
    // 'Configuration' se refiere a la clase del objeto tipado de configuración definido por la app cliente (ver siguientes secciones)
    // ver el JSDoc de los campos del DynConfigurationModuleConfig para mas info
}

Otros pasos

• invocar a la funcionalidad fetchEnvironmentConfiguration() con await durante el LOAD de la app (APP_INITIALIZER de Angular) para que la configuración de ambiente sea cargada en cada load
• invocar a la funcionalidad initialize() con await en 3 puntos:
  • durante el LOAD de la app (APP_INITIALIZER de Angular) pero solamente cuando hay un usuario logueado (actualización de la página por ejemplo)
  • durante el login del usuario, posterior a que el login fue hecho en backend y el token JWT guardado
  • cuando el usuario modifica (o limpia) la empresa con la cual trabajar (se recomiendo el llamado en un Resolver aplicado en todas las rutas que puedan provocar cambio de empresa activa), este punto no aplica si la app cliente de esta librería no utiliza el concepto del trabajo con empresa activa
• definir el objeto tipado donde se cargarán los valores de las variables segun el path dado por su key (opcional según uso, ver siguientes secciones para mas detalle)

3. Uso

3.1 Configuración de ambiente

Este tipo de configuración se accede mediante el pedido de variables individualmente por key o por ID.

• inyectar el servicio DynConfigurationService
• pedir una variable de ambiente individual por key o ID ´de alguna de las siguientes formas:
  • mediante getEnvironmentVariableMemorySync(keyOrId): buscando la variable en memoria solamente, lo que permite que se retorne su valor de forma síncrona
  • mediante getEnvironmentVariable(keyOrId): buscando (segun se desee) que la variable se busque en servidor y/o en memoria, pero su resultado es asíncrono

3.2 Configuración general

3.2.1 Objeto síncrono

Una de las opciones de la librería es crear, a partir del conjunto de variables de configuración entrada, un objeto de configuración tipado y de acceso síncrono para que pueda ser utilizado fácilmente como fuente de la configuración.
Para tener esta opción se debe definir en la app cliente una clase para este objeto con la estructura y tipado deseados de cada propiedad. Este objeto será poblado por esta librería a partir del conjunto de variables segun el path dado por sus keys.

Para acceder al objeto desde algún punto del código se debe:

• inyectar el DynConfigurationService (supongamos con nombre 'configService')
• acceder al valor de una variable de configuración mediante mediante this.configService.configuration.x.y.z. Con esto estamos accediendo al valor de la variable cuyo key es 'x.y.z'

Ventajas

• acceso síncrono a la configuración
• se accede directamente a campos nombrados y tipados de un objeto de configuración en lugar de pedir valores de variables por nombre

Desventajas

• se requiere definir la clase del objeto y mantener siempre en sincronía sus propiedades y tipos con las keys y types de las variables de configuración que maneja el sistema. Igualmente en el caso de uso siguiente donde se piden individualmente por key/ID, se debe mantener un conjunto de constantes con las keys/IDs de las variables a acceder asi como el conocimiento del tipo de datos que cada una tiene para su uso en el código.

3.2.2 Pedido de variables por key/ID

Otro forma de uso alternativa al objeto síncrono es mediante el pedido de variables individuales por key o ID, para ello:

• inyectar el servicio DynConfigurationService

• pedir una variable de configuración individual por key o ID de alguna de las siguientes formas:

  • mediante getConfigurationVariableMemorySync(keyOrId): buscando la variable en memoria solamente, lo que permite que se retorne su valor de forma síncrona
  • mediante getConfigurationVariable(keyOrId): buscando (segun se desee) que la variable se busque en servidor y/o en memoria, pero su resultado es asíncrono

4. Construcción del objeto síncrono y tipado

4.1 Keys

Como se mencionó en secciones anteriores, el campo key de las variables de configuración es el usado para determinar la propiedad dentro del objeto de configuración donde se va a cargar el valor. Las keys se interpretan como paths que definen la ubicación en el objeto, asi por ejemplo al procesar una variable de configuración con key 'x.y.z', su valor será cargado en el campo que se muestra:

{
    x: {
        y: {
            z: VALOR;
        }
    }
}

Recordar que, como se mencionó en secciones anteriores, en la app cliente se requiere definir la clase del objeto y mantener siempre en sincronía sus propiedades y tipos con las keys y types de las variables de configuración que maneja el sistema.

4.2 Parseo de tipos

Los valores de las propiedades de configuración general siempre vienen en formato string desde la fuente, pero son procesados para convertirse al tipo correcto de modo que se tengan tipados para el mejor y más limpio acceso por parte de la app.
Cada propiedad de configuración indica el tipo del valor. Los tipos soportados son los siguientes:

• string (si se deja vacío se considera string): no se realiza conversión
• integer: se convierte a entero
• decimal-d: se convierte a número decimal considerando una cantidad determinada de dígitos decimales (parser.defaultDecimals por defecto o 'd' si se pasa, ejemplo 'decimal-2')
• boolean: se convierte a booleano, considerando true el string 'true' y false cualquier otra cosa
• date-p: se convierte a fecha considerando un patrón (parser.defaultDatePattern por defecto o 'p' si se pasa, ejemplo 'date-dd/MM/yyyy')
• @{customName}: al comenzar con @ representa que es un tipo customizado, que no es reconocido por la librería sino que será manejado por la app cliente. Se delegará su parseo al cliente de la librería mediante parser.parseCustomType.

Cada vez que se accede a una propiedad, ya sea mediante el objeto síncrono o mediante el pedido individual por key o ID, se obtiene el valor en el tipo ya parseado.

4.3 Ejemplo

Suponiendo que tenemos el siguiente conjunto de variables de configuración general (key, value, type):

• 'logic.discounts.percentage' | '1803' | 'decimal-2'
• 'cart.maxAllowedAmount' | '1000' | 'integer'
• 'cart.allowProductsWithourPrice' | 'false' | 'boolean'

Se transformarán en el siguiente objeto de configuración síncrono:

{
    logic: {
        discounts: {
            percentage: 18.03
        }
    },
    cart: {
        maxAllowedAmount: 1000,
        allowProductsWithourPrice: false
    }
}