@jvsoft/utils 0.0.13-alpha.3 → 0.0.13-alpha.5

package/functions/mat-form-controls/autocomplete.d.ts

@@ -1,21 +1,51 @@
 import { AbstractControl } from '@angular/forms';
-export declare function mostrarValorEnBusqueda(campos: any, idxSel: any): string;
-export declare function changeSelectData(objThis: any, dataFiltro: {
+/**
+ * Devuelve un valor de visualización para un elemento buscado.
+ * Compatible con listas simples, objetos y campos múltiples.
+ */
+export declare function mostrarValorEnBusqueda(campos: any, idxSel: any): any;
+/**
+ * Vincula un FormControl a datos locales para autocompletado.
+ */
+export declare function changeSelectData(objThis: any, { formControl, data, campoBuscar, variableResultado }: {
     formControl: AbstractControl;
     data: any[];
     campoBuscar: string | string[];
     variableResultado: string;
 }): void;
-export declare function changeSelect(control: any, formControl: AbstractControl, tipo: any, campoBuscar: any, campoFiltro?: null): void;
-export declare function changeSelectDataApi(objThis: any, dataFiltro: {
+/**
+ * Vincula un FormControl a datos locales obtenidos de dataServidor o dataServidorSuscripcion.
+ */
+export declare function changeSelect(control: any, formControl: AbstractControl, tipo: string, campoBuscar: string | string[], campoFiltro?: string | null): void;
+/**
+ * Configuración para changeSelectReformateado.
+ */
+interface ChangeSelectConfig {
+    objThis: any;
     tipoReq: string;
+    formControl: AbstractControl;
+    queryService: any;
     campoId?: string;
     minLength?: number;
     dataExtra?: any;
-    dataExtraVariable?: any;
+    dataExtraVariable?: {
+        campo: string;
+        ctrlValue: AbstractControl;
+    }[];
     anonimo?: boolean;
-    queryService: any;
-    formControl: AbstractControl;
     variableResultado?: string;
-}): void;
+}
+/**
+ * Función genérica para vincular un FormControl con datos desde API o Promise.
+ * Preparada para migrar a signals en el futuro.
+ */
+export declare function changeSelectReformateado(config: ChangeSelectConfig): void;
+/**
+ * Alias para compatibilidad.
+ */
+export declare function changeSelectDataApi(objThis: any, dataFiltro: any): void;
+/**
+ * Alias para compatibilidad.
+ */
 export declare function changeSelectApi(control: any, queryService: any, formControl: AbstractControl, tipo: any, dataExtra?: {}, dataExtraVariable?: any[] | null, minLength?: number, anonimo?: boolean): void;
+export {};

package/functions/objects-arrays.d.ts

@@ -1,8 +1,23 @@
+/**
+ * Realiza una fusión profunda entre dos objetos, sin modificar el original.
+ * Si el valor en target no es un objeto, lo reemplaza directamente.
+ *
+ * @param source - Objeto fuente que se clonará y fusionará.
+ * @param target - Objeto destino cuyos valores se fusionarán.
+ * @returns Un nuevo objeto con la fusión profunda.
+ */
 export declare function deepMerge(source: any, target: any): any;
+/**
+ * Realiza una clonación profunda de un objeto, manejando funciones, fechas y arrays.
+ *
+ * @param obj - Objeto a clonar.
+ * @returns Una copia profunda del objeto.
+ */
 export declare function deepClone(obj: any): any;
 /**
  * Busca un elemento en un array o jerarquía de objetos según un campo y valor especificado.
  *
+ * @param datosFn - Objeto con los parámetros de búsqueda: items, campo, valor y opcionalmente campoHijo.
  * @returns El elemento encontrado o undefined si no existe.
  */
 export declare function buscarPorCampo<T>(datosFn: {
@@ -11,20 +26,90 @@ export declare function buscarPorCampo<T>(datosFn: {
     valor: any;
     campoHijo?: string;
 }): T | undefined;
+/**
+ * Suma los valores de las propiedades especificadas de un objeto.
+ *
+ * @param item - Objeto con las propiedades a sumar.
+ * @param campos - Array de nombres de las propiedades a sumar.
+ * @returns La suma de los valores de las propiedades.
+ */
 export declare function sumarPropiedades(item: Record<string, any>, campos: string[]): number;
+/**
+ * Verifica si el valor proporcionado es un número válido.
+ *
+ * @param value - Valor a verificar.
+ * @returns true si es un número, false en caso contrario.
+ */
 export declare function esNumero(value: any): boolean;
+/**
+ * Suma los valores de las propiedades especificadas en un array de objetos.
+ *
+ * @param arrayObjetos - Array de objetos a procesar.
+ * @param campos - Array de nombres de las propiedades a sumar.
+ * @returns Objeto con la suma de cada propiedad.
+ */
 export declare function sumarObjetos(arrayObjetos: any[], campos: string[]): Record<string, number>;
+/**
+ * Obtiene los valores únicos de un array.
+ *
+ * @param array - Array de valores.
+ * @returns Array con los valores únicos.
+ */
 export declare function getUniqueValues(array: any[]): any[];
+/**
+ * Obtiene los objetos únicos de un array según una propiedad específica.
+ *
+ * @param objetos - Array de objetos.
+ * @param campo - Nombre de la propiedad para determinar unicidad.
+ * @returns Array de objetos únicos por la propiedad.
+ */
 export declare function getUniqueValuesByProperty<T>(objetos: T[], campo: string): T[];
+/**
+ * Ordena un array de valores numéricos o alfabéticos.
+ *
+ * @param array - Array a ordenar.
+ * @param numeros - Si es true, ordena como números.
+ * @param sentido - 'ASC' para ascendente, 'DESC' para descendente.
+ * @returns Array ordenado.
+ */
 export declare function ordenarArray(array: any[], numeros?: boolean, sentido?: 'ASC' | 'DESC'): any[];
+/**
+ * Ordena un array de objetos por una propiedad específica.
+ *
+ * @param objData - Array de objetos a ordenar.
+ * @param propiedad - Propiedad por la que se ordena.
+ * @param numeros - (Obsoleto) Si es true, ordena como números.
+ * @returns Array ordenado.
+ */
 export declare function ordenarPorPropiedad(objData: any, propiedad: string, /**@deprecated*/ numeros?: boolean): {
     [x: string]: {};
 }[];
+/**
+ * Ordena un array de objetos por varias propiedades y direcciones.
+ *
+ * @param arr - Array de objetos a ordenar.
+ * @param options - Opciones con propiedades y direcciones de orden.
+ * @returns Array ordenado.
+ */
 export declare function ordenarPorPropiedades<T>(arr: T[], options: {
     propiedades: (keyof T)[];
     direcciones?: ('asc' | 'desc' | '')[];
 }): T[];
+/**
+ * Agrupa los elementos de un array según una clave o función de clave.
+ *
+ * @param array - Array de objetos a agrupar.
+ * @param key - Propiedad o función para agrupar.
+ * @returns Objeto con los grupos por clave.
+ */
 export declare function groupBy<T extends Record<string, any>, K extends keyof T>(array: T[], key: K | ((obj: T) => string)): Record<string, T[]>;
+/**
+ * Agrupa y anida los elementos de un array según una lista de propiedades.
+ *
+ * @param arr - Array de objetos a agrupar.
+ * @param properties - Propiedades para agrupar de forma anidada.
+ * @returns Objeto anidado por los grupos de propiedades.
+ */
 export declare function nestGroupsBy(arr: any, properties: any): any;
 /**
  * Retorna el valor máximo del campo especificado (incluso anidado) en un arreglo de objetos.
@@ -43,5 +128,20 @@ export declare function obtenerUltimoOrden(data: any[], campo: string, increment
  * @returns Nuevo array con las columnas eliminadas.
  */
 export declare function eliminarColumnaPorIndex<T extends unknown[][]>(data: T, columnIndex: number | number[]): T;
+/**
+ * Elimina elementos duplicados de un array de objetos según claves específicas.
+ *
+ * @param array - Array de objetos.
+ * @param claves - Claves para determinar unicidad. Si no se especifica, compara todo el objeto.
+ * @returns Array sin duplicados.
+ */
 export declare function eliminarDuplicados<T extends object>(array: T[], claves?: (keyof T)[]): T[];
+/**
+ * Elimina elementos de un array origen que estén presentes en otro array, según claves específicas.
+ *
+ * @param origen - Array original.
+ * @param elementosAEliminar - Elementos a eliminar del array origen.
+ * @param claves - Claves para comparar los objetos. Si no se especifica, compara todo el objeto.
+ * @returns Array filtrado sin los elementos eliminados.
+ */
 export declare function eliminarElementos<T extends object>(origen: T[], elementosAEliminar: T[], claves?: (keyof T)[]): T[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jvsoft/utils",
-  "version": "0.0.13-alpha.3",
+  "version": "0.0.13-alpha.5",
   "description": "JVSOFT Angular Utils",
   "publishConfig": {
     "tag": "alpha",

package/src/functions/mat-form-controls/autocomplete.d.ts

@@ -1,21 +1,51 @@
 import { AbstractControl } from '@angular/forms';
-export declare function mostrarValorEnBusqueda(campos: any, idxSel: any): string;
-export declare function changeSelectData(objThis: any, dataFiltro: {
+/**
+ * Devuelve un valor de visualización para un elemento buscado.
+ * Compatible con listas simples, objetos y campos múltiples.
+ */
+export declare function mostrarValorEnBusqueda(campos: any, idxSel: any): any;
+/**
+ * Vincula un FormControl a datos locales para autocompletado.
+ */
+export declare function changeSelectData(objThis: any, { formControl, data, campoBuscar, variableResultado }: {
     formControl: AbstractControl;
     data: any[];
     campoBuscar: string | string[];
     variableResultado: string;
 }): void;
-export declare function changeSelect(control: any, formControl: AbstractControl, tipo: any, campoBuscar: any, campoFiltro?: null): void;
-export declare function changeSelectDataApi(objThis: any, dataFiltro: {
+/**
+ * Vincula un FormControl a datos locales obtenidos de dataServidor o dataServidorSuscripcion.
+ */
+export declare function changeSelect(control: any, formControl: AbstractControl, tipo: string, campoBuscar: string | string[], campoFiltro?: string | null): void;
+/**
+ * Configuración para changeSelectReformateado.
+ */
+interface ChangeSelectConfig {
+    objThis: any;
     tipoReq: string;
+    formControl: AbstractControl;
+    queryService: any;
     campoId?: string;
     minLength?: number;
     dataExtra?: any;
-    dataExtraVariable?: any;
+    dataExtraVariable?: {
+        campo: string;
+        ctrlValue: AbstractControl;
+    }[];
     anonimo?: boolean;
-    queryService: any;
-    formControl: AbstractControl;
     variableResultado?: string;
-}): void;
+}
+/**
+ * Función genérica para vincular un FormControl con datos desde API o Promise.
+ * Preparada para migrar a signals en el futuro.
+ */
+export declare function changeSelectReformateado(config: ChangeSelectConfig): void;
+/**
+ * Alias para compatibilidad.
+ */
+export declare function changeSelectDataApi(objThis: any, dataFiltro: any): void;
+/**
+ * Alias para compatibilidad.
+ */
 export declare function changeSelectApi(control: any, queryService: any, formControl: AbstractControl, tipo: any, dataExtra?: {}, dataExtraVariable?: any[] | null, minLength?: number, anonimo?: boolean): void;
+export {};

package/src/functions/objects-arrays.d.ts

@@ -1,8 +1,23 @@
+/**
+ * Realiza una fusión profunda entre dos objetos, sin modificar el original.
+ * Si el valor en target no es un objeto, lo reemplaza directamente.
+ *
+ * @param source - Objeto fuente que se clonará y fusionará.
+ * @param target - Objeto destino cuyos valores se fusionarán.
+ * @returns Un nuevo objeto con la fusión profunda.
+ */
 export declare function deepMerge(source: any, target: any): any;
+/**
+ * Realiza una clonación profunda de un objeto, manejando funciones, fechas y arrays.
+ *
+ * @param obj - Objeto a clonar.
+ * @returns Una copia profunda del objeto.
+ */
 export declare function deepClone(obj: any): any;
 /**
  * Busca un elemento en un array o jerarquía de objetos según un campo y valor especificado.
  *
+ * @param datosFn - Objeto con los parámetros de búsqueda: items, campo, valor y opcionalmente campoHijo.
  * @returns El elemento encontrado o undefined si no existe.
  */
 export declare function buscarPorCampo<T>(datosFn: {
@@ -11,20 +26,90 @@ export declare function buscarPorCampo<T>(datosFn: {
     valor: any;
     campoHijo?: string;
 }): T | undefined;
+/**
+ * Suma los valores de las propiedades especificadas de un objeto.
+ *
+ * @param item - Objeto con las propiedades a sumar.
+ * @param campos - Array de nombres de las propiedades a sumar.
+ * @returns La suma de los valores de las propiedades.
+ */
 export declare function sumarPropiedades(item: Record<string, any>, campos: string[]): number;
+/**
+ * Verifica si el valor proporcionado es un número válido.
+ *
+ * @param value - Valor a verificar.
+ * @returns true si es un número, false en caso contrario.
+ */
 export declare function esNumero(value: any): boolean;
+/**
+ * Suma los valores de las propiedades especificadas en un array de objetos.
+ *
+ * @param arrayObjetos - Array de objetos a procesar.
+ * @param campos - Array de nombres de las propiedades a sumar.
+ * @returns Objeto con la suma de cada propiedad.
+ */
 export declare function sumarObjetos(arrayObjetos: any[], campos: string[]): Record<string, number>;
+/**
+ * Obtiene los valores únicos de un array.
+ *
+ * @param array - Array de valores.
+ * @returns Array con los valores únicos.
+ */
 export declare function getUniqueValues(array: any[]): any[];
+/**
+ * Obtiene los objetos únicos de un array según una propiedad específica.
+ *
+ * @param objetos - Array de objetos.
+ * @param campo - Nombre de la propiedad para determinar unicidad.
+ * @returns Array de objetos únicos por la propiedad.
+ */
 export declare function getUniqueValuesByProperty<T>(objetos: T[], campo: string): T[];
+/**
+ * Ordena un array de valores numéricos o alfabéticos.
+ *
+ * @param array - Array a ordenar.
+ * @param numeros - Si es true, ordena como números.
+ * @param sentido - 'ASC' para ascendente, 'DESC' para descendente.
+ * @returns Array ordenado.
+ */
 export declare function ordenarArray(array: any[], numeros?: boolean, sentido?: 'ASC' | 'DESC'): any[];
+/**
+ * Ordena un array de objetos por una propiedad específica.
+ *
+ * @param objData - Array de objetos a ordenar.
+ * @param propiedad - Propiedad por la que se ordena.
+ * @param numeros - (Obsoleto) Si es true, ordena como números.
+ * @returns Array ordenado.
+ */
 export declare function ordenarPorPropiedad(objData: any, propiedad: string, /**@deprecated*/ numeros?: boolean): {
     [x: string]: {};
 }[];
+/**
+ * Ordena un array de objetos por varias propiedades y direcciones.
+ *
+ * @param arr - Array de objetos a ordenar.
+ * @param options - Opciones con propiedades y direcciones de orden.
+ * @returns Array ordenado.
+ */
 export declare function ordenarPorPropiedades<T>(arr: T[], options: {
     propiedades: (keyof T)[];
     direcciones?: ('asc' | 'desc' | '')[];
 }): T[];
+/**
+ * Agrupa los elementos de un array según una clave o función de clave.
+ *
+ * @param array - Array de objetos a agrupar.
+ * @param key - Propiedad o función para agrupar.
+ * @returns Objeto con los grupos por clave.
+ */
 export declare function groupBy<T extends Record<string, any>, K extends keyof T>(array: T[], key: K | ((obj: T) => string)): Record<string, T[]>;
+/**
+ * Agrupa y anida los elementos de un array según una lista de propiedades.
+ *
+ * @param arr - Array de objetos a agrupar.
+ * @param properties - Propiedades para agrupar de forma anidada.
+ * @returns Objeto anidado por los grupos de propiedades.
+ */
 export declare function nestGroupsBy(arr: any, properties: any): any;
 /**
  * Retorna el valor máximo del campo especificado (incluso anidado) en un arreglo de objetos.
@@ -43,5 +128,20 @@ export declare function obtenerUltimoOrden(data: any[], campo: string, increment
  * @returns Nuevo array con las columnas eliminadas.
  */
 export declare function eliminarColumnaPorIndex<T extends unknown[][]>(data: T, columnIndex: number | number[]): T;
+/**
+ * Elimina elementos duplicados de un array de objetos según claves específicas.
+ *
+ * @param array - Array de objetos.
+ * @param claves - Claves para determinar unicidad. Si no se especifica, compara todo el objeto.
+ * @returns Array sin duplicados.
+ */
 export declare function eliminarDuplicados<T extends object>(array: T[], claves?: (keyof T)[]): T[];
+/**
+ * Elimina elementos de un array origen que estén presentes en otro array, según claves específicas.
+ *
+ * @param origen - Array original.
+ * @param elementosAEliminar - Elementos a eliminar del array origen.
+ * @param claves - Claves para comparar los objetos. Si no se especifica, compara todo el objeto.
+ * @returns Array filtrado sin los elementos eliminados.
+ */
 export declare function eliminarElementos<T extends object>(origen: T[], elementosAEliminar: T[], claves?: (keyof T)[]): T[];