@hkdigital/lib-core 0.4.30 → 0.4.32

package/dist/util/expect/arrays.d.ts

@@ -18,6 +18,7 @@ export function expect_stringArray(value: any): void;
 export function expect_objectArray(value: any): void;
 /**
  * Throws an exception if the value is not an Array or the array is empty
+ * @param {any} value - Value to check
  */
 export function expect_notEmptyArray(value: any): void;
 /**

package/dist/util/expect/arrays.js

@@ -35,6 +35,7 @@ export { expect_objectArray as objectArray };
 
 /**
  * Throws an exception if the value is not an Array or the array is empty
+ * @param {any} value - Value to check
  */
 export function expect_notEmptyArray(value) {
 	v.parse(v.pipe(v.instance(Array), v.nonEmpty()), value);

package/dist/util/expect/primitives.d.ts

@@ -2,24 +2,32 @@
  * Throws a validation error if value is not a string
  *
  * @param {any} value
+ *
+ * @asserts value is string
  */
 export function expect_string(value: any): void;
 /**
  * Throws a validation error if value is not a boolean
  *
  * @param {any} value
+ *
+ * @asserts value is boolean
  */
 export function expect_boolean(value: any): void;
 /**
  * Throws a validation error if value is not a number
  *
  * @param {any} value
+ *
+ * @asserts value is number
  */
 export function expect_number(value: any): void;
 /**
  * Throws a validation error if value is not a Symbol
  *
  * @param {any} value
+ *
+ * @asserts value is Symbol
  */
 export function expect_symbol(value: any): void;
 /**
@@ -32,30 +40,40 @@ export function expect_defined(value: any): void;
  * Throws a validation error if value is not a function
  *
  * @param {any} value
+ *
+ * @asserts value is function
  */
 export function expect_function(value: any): void;
 /**
  * Throws a validation error if value is not a Promise
  *
  * @param {any} value
+ *
+ * @asserts value is Promise
  */
 export function expect_promise(value: any): void;
 /**
  * Throws a validation error if value is not a Map
  *
  * @param {any} value
+ *
+ * @asserts value is Map
  */
 export function expect_map(value: any): void;
 /**
  * Throws a validation error if value is not a Set
  *
  * @param {any} value
+ *
+ * @asserts value is Set
  */
 export function expect_set(value: any): void;
 /**
  * Throws a validation error if value is not an Error instance
  *
  * @param {any} value
+ *
+ * @asserts value is Error
  */
 export function expect_error(value: any): void;
 export { expect_string as string, expect_boolean as boolean, expect_number as number, expect_symbol as symbol, expect_defined as defined, expect_function as function, _function as function, expect_function as class, _class as class, expect_promise as promise, expect_map as map, expect_set as set, expect_error as error };

package/dist/util/expect/primitives.js

@@ -4,6 +4,8 @@ import * as v from 'valibot';
  * Throws a validation error if value is not a string
  *
  * @param {any} value
+ *
+ * @asserts value is string
  */
 export function expect_string(value) {
 	v.parse(v.string(), value);
@@ -15,6 +17,8 @@ export { expect_string as string };
  * Throws a validation error if value is not a boolean
  *
  * @param {any} value
+ *
+ * @asserts value is boolean
  */
 export function expect_boolean(value) {
 	v.parse(v.boolean(), value);
@@ -26,6 +30,8 @@ export { expect_boolean as boolean };
  * Throws a validation error if value is not a number
  *
  * @param {any} value
+ *
+ * @asserts value is number
  */
 export function expect_number(value) {
 	v.parse(v.number(), value);
@@ -37,6 +43,8 @@ export { expect_number as number };
  * Throws a validation error if value is not a Symbol
  *
  * @param {any} value
+ *
+ * @asserts value is Symbol
  */
 export function expect_symbol(value) {
 	v.parse(v.symbol(), value);
@@ -68,6 +76,8 @@ export { expect_defined as defined };
  * Throws a validation error if value is not a function
  *
  * @param {any} value
+ *
+ * @asserts value is function
  */
 export function expect_function(value) {
 	v.parse(v.function(), value);
@@ -80,6 +90,8 @@ export { expect_function as class };
  * Throws a validation error if value is not a Promise
  *
  * @param {any} value
+ *
+ * @asserts value is Promise
  */
 export function expect_promise(value) {
 	v.parse(v.instance(Promise), value);
@@ -91,6 +103,8 @@ export { expect_promise as promise };
  * Throws a validation error if value is not a Map
  *
  * @param {any} value
+ *
+ * @asserts value is Map
  */
 export function expect_map(value) {
 	v.parse(v.instance(Map), value);
@@ -102,6 +116,8 @@ export { expect_map as map };
  * Throws a validation error if value is not a Set
  *
  * @param {any} value
+ *
+ * @asserts value is Set
  */
 export function expect_set(value) {
 	v.parse(v.instance(Set), value);
@@ -113,6 +129,8 @@ export { expect_set as set };
  * Throws a validation error if value is not an Error instance
  *
  * @param {any} value
+ *
+ * @asserts value is Error
  */
 export function expect_error(value) {
 	v.parse(v.instance(Error), value);

package/dist/util/function/index.d.ts

@@ -18,4 +18,17 @@ export function once(callback: Function): Function;
  */
 export function debounce(fn: Function, intervalMs?: number): Function;
 export function noop(): void;
-export function defer(fn: any): void;
+/**
+ * Defer the execution of a function
+ *  - Uses the best 'setImmediate' implementation supported by the current
+ *    runtime environment
+ *
+ * @param {function} fn - Function to execute
+ *
+ * --
+ *
+ * @note setImmediate is preferred over nextTick
+ *
+ * @see https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/
+ */
+export const defer: typeof setImmediate | ((fn: any) => void);

package/dist/util/geometry/index.d.ts

@@ -3,8 +3,8 @@
  *
  * @param {number} xPct - X-coordinate as percentage
  * @param {number} yPct - Y-coordinate as percentage
- * @param {Array} polygon - Array of [x, y] points
+ * @param {Array<number[]>} polygon - Array of [x, y] points
  *
  * @returns {boolean} True if the point lies within the polygon
  */
-export function isPointInPolygon(xPct: number, yPct: number, polygon: any[]): boolean;
+export function isPointInPolygon(xPct: number, yPct: number, polygon: Array<number[]>): boolean;

package/dist/util/geometry/index.js

@@ -3,7 +3,7 @@
  *
  * @param {number} xPct - X-coordinate as percentage
  * @param {number} yPct - Y-coordinate as percentage
- * @param {Array} polygon - Array of [x, y] points
+ * @param {Array<number[]>} polygon - Array of [x, y] points
  *
  * @returns {boolean} True if the point lies within the polygon
  */

package/dist/util/iterate/index.d.ts

@@ -48,11 +48,11 @@ export function map(iterable: Iterable<any>, transformFn: Function): Generator;
  * @return {Iterable<[string[], any]>} iterable that yields [path, value] pairs
  */
 export function iterateObjectEntries(obj: object, options?: {
-    walkArrays?: boolean;
-    expandPathKeys?: boolean;
-    outputIntermediateNodes?: boolean;
-    ignoreEmptyObjectLeaves?: boolean;
-    depthFirst?: boolean;
+    walkArrays?: boolean | undefined;
+    expandPathKeys?: boolean | undefined;
+    outputIntermediateNodes?: boolean | undefined;
+    ignoreEmptyObjectLeaves?: boolean | undefined;
+    depthFirst?: boolean | undefined;
 }): Iterable<[string[], any]>;
 /**
  * Get an Iterator object that can be used to iterate over all paths in
@@ -92,6 +92,6 @@ export function iterateObjectValues(obj: object, options?: IterableTreeOptions):
 export function sortObjects({ it, getValueFn, reversed }: {
     it: Iterable<any>;
     getValueFn: Function;
-    reversed?: boolean;
-}): Promise<any[]>;
+    reversed?: boolean | undefined;
+}): Promise<array>;
 export type IterableTreeOptions = import("../../generic/typedef.js").IterableTreeOptions;

package/dist/util/object/index.d.ts

@@ -54,7 +54,7 @@ export function exportPublic(obj: object, keepKeys?: string[]): object;
  *
  * @returns {object|array} new object or array with only primitive values
  */
-export function exportNotNested(objectOrArray: object | any[]): object | any[];
+export function exportNotNested(objectOrArray: object | array): object | array;
 /**
  * Keep only the specified keys in the object
  * - deletes all other key-value pairs in the object
@@ -166,12 +166,12 @@ export function objectGetWithThrow(obj: object, path: string | any[], parseFn?:
  *   List of changes between the object before and object after
  */
 export function objectDiff(objBefore: object, objAfter: object, options: {
-    ignoreAdd?: boolean;
-    ignoreUpdate?: boolean;
-    ignoreDelete?: boolean;
-    ignorePrivate?: boolean;
-    deleteValue?: boolean;
-}, _recursion: any): any[];
+    ignoreAdd?: boolean | undefined;
+    ignoreUpdate?: boolean | undefined;
+    ignoreDelete?: boolean | undefined;
+    ignorePrivate?: boolean | undefined;
+    deleteValue?: boolean | undefined;
+} | undefined, _recursion: any): array;
 /**
  * Applies a list of differences to the input object
  * - A list of changes can be generated by e.g. objectDiff
@@ -188,10 +188,10 @@ export function objectDiff(objBefore: object, objAfter: object, options: {
  *   Ignore properties that start with an underscore e.g. _id or _updatedAt
  */
 export function patchObject(obj: object, changes: object[], options?: {
-    ignoreAdd?: boolean;
-    ignoreUpdate?: boolean;
-    ignoreDelete?: boolean;
-    ignorePrivate?: boolean;
+    ignoreAdd?: boolean | undefined;
+    ignoreUpdate?: boolean | undefined;
+    ignoreDelete?: boolean | undefined;
+    ignorePrivate?: boolean | undefined;
 }): void;
 /**
  * Extend the target object with methods and properties from the source
@@ -242,7 +242,7 @@ export function getPrototypeNames(obj: object): string[];
  *   nested object with the values that were found or defaultValues
  */
 export function getTree(obj: object, tree: object, options?: {
-    shallowLeaves?: boolean;
+    shallowLeaves?: boolean | undefined;
 }): object;
 /**
  * Deep clone an object or any kind of other variable
@@ -284,7 +284,7 @@ export function setReadOnlyProperty(obj: object, propertyName: string, value: an
  * @returns {object} updated object
  */
 export function updateObject(obj?: object, updateData?: object | Iterable<any>, options?: {
-    replaceArrays?: boolean;
+    replaceArrays?: boolean | undefined;
 }): object;
 /**
  * Copy own properties from an object to another object if they do not

package/dist/util/singleton/index.d.ts

@@ -12,8 +12,8 @@
  */
 export function getInstance({ needle, class: Class, args }: {
     class: any;
-    args?: any[];
-    needle?: string;
+    args?: any[] | undefined;
+    needle?: string | undefined;
 }): any;
 /**
  * Creates a proxy that instantiates the singleton class upon it's first usage
@@ -28,7 +28,7 @@ export function getInstance({ needle, class: Class, args }: {
  */
 export function lazySingleton<T>({ class: Class, args }: {
     class: new () => T;
-    args?: any[];
+    args?: any[] | undefined;
 }): T & {
     init: () => null;
 };

package/dist/util/svelte/loading/loading-tracker.svelte.d.ts

@@ -11,7 +11,7 @@
  *
  * @returns {Object} Loading tracker instance
  */
-export function createTracker(): any;
+export function createTracker(): Object;
 /**
  * Simple utility for tracking combined loading progress across multiple components
  */

package/dist/util/sveltekit/env/all.d.ts

@@ -13,7 +13,7 @@
  * @param {boolean} [options.autoGroup=true]
  *   Enable automatic prefix grouping
  *
- * @returns {Object} Grouped and parsed combined environment variables
+ * @returns {Record<string, any>} Grouped and parsed combined environment variables
  *
  * @example
  * // Environment variables:
@@ -31,24 +31,13 @@
  * // }
  */
 export function getAllEnv(options?: {
-    camelCase?: boolean;
-    parseValues?: boolean;
-    autoGroup?: boolean;
-}): any;
-/**
- * Get combined environment variables by prefix
- *
- * @param {string} prefix - Environment variable prefix (e.g., 'DATABASE')
- * @param {Object} [options={}] - Parsing options
- *
- * @returns {Object} Parsed configuration object
- */
-export function getAllEnvByPrefix(prefix: string, options?: any): any;
+    camelCase?: boolean | undefined;
+    parseValues?: boolean | undefined;
+    autoGroup?: boolean | undefined;
+}): Record<string, any>;
 /**
  * Get raw combined environment variables (no parsing)
  *
- * @returns {Object<string, string>} Raw combined environment variables
+ * @returns {Record<string, string|undefined>} Raw combined environment variables
  */
-export function getRawAllEnv(): {
-    [x: string]: string;
-};
+export function getRawAllEnv(): Record<string, string | undefined>;

package/dist/util/sveltekit/env/all.js

@@ -14,7 +14,7 @@
 
 import { getPublicEnv, getRawPublicEnv } from './public.js';
 import { getPrivateEnv, getRawPrivateEnv } from './private.js';
-import { autoGroupEnvByPrefix, parseEnv } from './parsers.js';
+import { autoGroupEnvByPrefix } from './parsers.js';
 
 /**
  * Get all environment variables (public + private) with automatic grouping
@@ -31,7 +31,7 @@ import { autoGroupEnvByPrefix, parseEnv } from './parsers.js';
  * @param {boolean} [options.autoGroup=true]
  *   Enable automatic prefix grouping
  *
- * @returns {Object} Grouped and parsed combined environment variables
+ * @returns {Record<string, any>} Grouped and parsed combined environment variables
  *
  * @example
  * // Environment variables:
@@ -65,28 +65,10 @@ export function getAllEnv(options = {}) {
   return { ...publicVars, ...privateVars };
 }
 
-/**
- * Get combined environment variables by prefix
- *
- * @param {string} prefix - Environment variable prefix (e.g., 'DATABASE')
- * @param {Object} [options={}] - Parsing options
- *
- * @returns {Object} Parsed configuration object
- */
-export function getAllEnvByPrefix(prefix, options = {}) {
-  const prefixWithUnderscore = prefix.endsWith('_') ? prefix : `${prefix}_`;
-  
-  return getAllEnv({
-    ...options,
-    prefix: prefixWithUnderscore,
-    removePrefix: true
-  });
-}
-
 /**
  * Get raw combined environment variables (no parsing)
  *
- * @returns {Object<string, string>} Raw combined environment variables
+ * @returns {Record<string, string|undefined>} Raw combined environment variables
  */
 export function getRawAllEnv() {
   const publicVars = getRawPublicEnv();
@@ -94,4 +76,4 @@ export function getRawAllEnv() {
   
   // Private variables take precedence over public ones
   return { ...publicVars, ...privateVars };
-}
+}

package/dist/util/sveltekit/env/parsers.d.ts

@@ -17,7 +17,7 @@
 /**
  * Parse environment object with type conversion and key transformation
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {Object} [options={}] - Parsing options
  * @param {boolean} [options.camelCase=true]
  *   Convert env var names to camelCase object keys
@@ -27,28 +27,24 @@
  * @param {boolean} [options.removePrefix=true]
  *   Remove prefix from resulting keys
  *
- * @returns {Object} Parsed environment object
+ * @returns {Record<string, any>} Parsed environment object
  */
-export function parseEnv(env: {
-    [x: string]: string;
-}, options?: {
-    camelCase?: boolean;
-    parseValues?: boolean;
-    prefix?: string;
-    removePrefix?: boolean;
-}): any;
+export function parseEnv(env: Record<string, string | undefined>, options?: {
+    camelCase?: boolean | undefined;
+    parseValues?: boolean | undefined;
+    prefix?: string | undefined;
+    removePrefix?: boolean | undefined;
+}): Record<string, any>;
 /**
  * Parse environment variables by prefix
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {string} prefix - Environment variable prefix (e.g., 'DATABASE')
  * @param {Object} [options={}] - Parsing options
  *
- * @returns {Object} Parsed configuration object
+ * @returns {Record<string, any>} Parsed configuration object
  */
-export function parseEnvByPrefix(env: {
-    [x: string]: string;
-}, prefix: string, options?: any): any;
+export function parseEnvByPrefix(env: Record<string, string | undefined>, prefix: string, options?: Object): Record<string, any>;
 /**
  * Convert SCREAMING_SNAKE_CASE to camelCase
  *
@@ -72,14 +68,14 @@ export function parseValue(value: string): any;
  * them into configuration objects. All variables with underscores are
  * grouped by their prefix (the part before the first underscore).
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {Object} [options={}] - Parsing options
  * @param {boolean} [options.camelCase=true]
  *   Convert env var names to camelCase object keys
  * @param {boolean} [options.parseValues=true]
  *   Parse string values to numbers/booleans when possible
  *
- * @returns {Object<string, Object>} Grouped environment variables
+ * @returns {Record<string, Record<string, any> | any>} Grouped environment variables
  *
  * @example
  * // Input env vars:
@@ -95,41 +91,31 @@ export function parseValue(value: string): any;
  * //   single: 'value'  // No underscore, stays top-level
  * // }
  */
-export function autoGroupEnvByPrefix(env: {
-    [x: string]: string;
-}, options?: {
-    camelCase?: boolean;
-    parseValues?: boolean;
-}): {
-    [x: string]: any;
-};
+export function autoGroupEnvByPrefix(env: Record<string, string | undefined>, options?: {
+    camelCase?: boolean | undefined;
+    parseValues?: boolean | undefined;
+}): Record<string, Record<string, any> | any>;
 /**
  * Group environment variables by specific prefixes
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {string[]} prefixes - Array of prefixes to group by
  * @param {Object} [options={}] - Parsing options
  *
- * @returns {Object<string, Object>} Grouped environment variables
+ * @returns {Record<string, Record<string, any>>} Grouped environment variables
  *
  * @example
  * const grouped = groupEnvByPrefixes(env, ['DATABASE', 'REDIS', 'JWT']);
  * // Returns: { database: {...}, redis: {...}, jwt: {...} }
  */
-export function groupEnvByPrefixes(env: {
-    [x: string]: string;
-}, prefixes: string[], options?: any): {
-    [x: string]: any;
-};
+export function groupEnvByPrefixes(env: Record<string, string | undefined>, prefixes: string[], options?: Object): Record<string, Record<string, any>>;
 /**
  * Filter environment variables by pattern
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {RegExp|string} pattern - Pattern to match against keys
  * @param {Object} [options={}] - Parsing options
  *
- * @returns {Object} Filtered and parsed environment variables
+ * @returns {Record<string, any>} Filtered and parsed environment variables
  */
-export function filterEnvByPattern(env: {
-    [x: string]: string;
-}, pattern: RegExp | string, options?: any): any;
+export function filterEnvByPattern(env: Record<string, string | undefined>, pattern: RegExp | string, options?: Object): Record<string, any>;

package/dist/util/sveltekit/env/parsers.js

@@ -18,7 +18,7 @@
 /**
  * Parse environment object with type conversion and key transformation
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {Object} [options={}] - Parsing options
  * @param {boolean} [options.camelCase=true]
  *   Convert env var names to camelCase object keys
@@ -28,7 +28,7 @@
  * @param {boolean} [options.removePrefix=true]
  *   Remove prefix from resulting keys
  *
- * @returns {Object} Parsed environment object
+ * @returns {Record<string, any>} Parsed environment object
  */
 export function parseEnv(env, options = {}) {
   const {
@@ -41,8 +41,8 @@ export function parseEnv(env, options = {}) {
   const result = {};
 
   for (const [key, value] of Object.entries(env || {})) {
-    // Skip if prefix specified and key doesn't match
-    if (prefix && !key.startsWith(prefix)) {
+    // Skip if value is undefined or if prefix specified and key doesn't match
+    if (value === undefined || (prefix && !key.startsWith(prefix))) {
       continue;
     }
 
@@ -73,11 +73,11 @@ export function parseEnv(env, options = {}) {
 /**
  * Parse environment variables by prefix
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {string} prefix - Environment variable prefix (e.g., 'DATABASE')
  * @param {Object} [options={}] - Parsing options
  *
- * @returns {Object} Parsed configuration object
+ * @returns {Record<string, any>} Parsed configuration object
  */
 export function parseEnvByPrefix(env, prefix, options = {}) {
   const prefixWithUnderscore = prefix.endsWith('_') ? prefix : `${prefix}_`;
@@ -135,14 +135,14 @@ export function parseValue(value) {
  * them into configuration objects. All variables with underscores are 
  * grouped by their prefix (the part before the first underscore).
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {Object} [options={}] - Parsing options
  * @param {boolean} [options.camelCase=true]
  *   Convert env var names to camelCase object keys
  * @param {boolean} [options.parseValues=true]
  *   Parse string values to numbers/booleans when possible
  *
- * @returns {Object<string, Object>} Grouped environment variables
+ * @returns {Record<string, Record<string, any> | any>} Grouped environment variables
  *
  * @example
  * // Input env vars:
@@ -197,7 +197,7 @@ export function autoGroupEnvByPrefix(env, options = {}) {
 
   // Add remaining variables (no underscore) as top-level properties
   for (const [key, value] of Object.entries(env)) {
-    if (!usedKeys.has(key)) {
+    if (!usedKeys.has(key) && value !== undefined) {
       const finalKey = camelCase ? toCamelCase(key) : key.toLowerCase();
       result[finalKey] = parseValues ? parseValue(value) : value;
     }
@@ -209,11 +209,11 @@ export function autoGroupEnvByPrefix(env, options = {}) {
 /**
  * Group environment variables by specific prefixes
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {string[]} prefixes - Array of prefixes to group by
  * @param {Object} [options={}] - Parsing options
  *
- * @returns {Object<string, Object>} Grouped environment variables
+ * @returns {Record<string, Record<string, any>>} Grouped environment variables
  *
  * @example
  * const grouped = groupEnvByPrefixes(env, ['DATABASE', 'REDIS', 'JWT']);
@@ -236,19 +236,19 @@ export function groupEnvByPrefixes(env, prefixes, options = {}) {
 /**
  * Filter environment variables by pattern
  *
- * @param {Object<string, string>} env - Raw environment variables
+ * @param {Record<string, string | undefined>} env - Raw environment variables
  * @param {RegExp|string} pattern - Pattern to match against keys
  * @param {Object} [options={}] - Parsing options
  *
- * @returns {Object} Filtered and parsed environment variables
+ * @returns {Record<string, any>} Filtered and parsed environment variables
  */
 export function filterEnvByPattern(env, pattern, options = {}) {
   const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
-  /** @type {Object<string, string>} */
+  /** @type {Record<string, string>} */
   const filtered = {};
   
   for (const [key, value] of Object.entries(env || {})) {
-    if (regex.test(key)) {
+    if (regex.test(key) && value !== undefined) {
       filtered[key] = value;
     }
   }