@nu-art/ts-common 0.500.0 → 0.500.6

package/core/error-handling.d.ts

@@ -47,7 +47,7 @@ export interface OnApplicationNotification {
  * Use this to notify all modules that implement `OnApplicationNotification`
  * about application-level events.
  */
-export declare const dispatch_onApplicationNotification: Dispatcher<OnApplicationNotification, "__processApplicationNotification", [errorLevel: ServerErrorSeverity, module: Module<any, any, import("../index.js").Validator<any> | import("../index.js").TypeValidator<any>>, message: ErrorMessage], void>;
+export declare const dispatch_onApplicationNotification: Dispatcher<OnApplicationNotification, "__processApplicationNotification", [errorLevel: ServerErrorSeverity, module: Module<any>, message: ErrorMessage], void>;
 /**
  * Interface for modules that handle application exceptions.
  *
@@ -69,4 +69,4 @@ export interface OnApplicationException {
  * Use this to notify all modules that implement `OnApplicationException`
  * about exceptions that occur at the application level.
  */
-export declare const dispatch_onApplicationException: Dispatcher<OnApplicationException, "__processApplicationException", [e: CustomException, module: Module<any, any, import("../index.js").Validator<any> | import("../index.js").TypeValidator<any>>], void>;
+export declare const dispatch_onApplicationException: Dispatcher<OnApplicationException, "__processApplicationException", [e: CustomException, module: Module<any>], void>;

package/core/module-manager.d.ts

@@ -8,7 +8,7 @@ import { Logger } from './logger/index.js';
  *
  * @internal
  */
-export declare function moduleResolver(): Module<any, any, import("../index.js").Validator<any> | import("../index.js").TypeValidator<any>>[];
+export declare function moduleResolver(): Module<any>[];
 /**
  * Runtime function to access all registered modules.
  *
@@ -21,7 +21,7 @@ export declare const RuntimeModules: () => {
     map: <T, S>(processor: (item: T, index: number, array: T[]) => S) => S[];
     forEach: <T>(processor: (item: T, index: number, array: T[]) => void) => void;
     includes: <T>(module: T) => boolean;
-    all: Module<any, any, import("../index.js").Validator<any> | import("../index.js").TypeValidator<any>>[];
+    all: Module<any>[];
 };
 /**
  * Runtime function to get the application version.
@@ -79,7 +79,7 @@ export declare class ModuleManager extends Logger {
         map: <T, S>(processor: (item: T, index: number, array: T[]) => S) => S[];
         forEach: <T>(processor: (item: T, index: number, array: T[]) => void) => void;
         includes: <T>(module: T) => boolean;
-        all: Module<any, any, import("../index.js").Validator<any> | import("../index.js").TypeValidator<any>>[];
+        all: Module<any>[];
     };
     /** Singleton instance of ModuleManager */
     static instance: ModuleManager;

package/core/module-manager.js

@@ -205,8 +205,10 @@ export class ModuleManager extends Logger {
      * @throws {BadImplementationException} If any module is undefined (cyclic import issue)
      */
     init() {
-        if (this.config.logLevel)
+        if (this.config.logLevel) {
             this.setMinLevel(this.config.logLevel);
+            this.modules.forEach((module) => module.setMinLevel(this.config.logLevel));
+        }
         this.logInfo(`---------  initializing app  ---------`);
         const undefinedModule = this.modules.some(module => !exists(module));
         if (undefinedModule) {

package/core/module.d.ts

@@ -3,7 +3,11 @@
  */
 import { ModuleManager } from './module-manager.js';
 import { Logger, LogLevel } from './logger/index.js';
-import { ValidatorTypeResolver } from '../validator/validator-core.js';
+import { TypeValidator } from '../validator/validator-core.js';
+import { TS_Object } from '../utils/types.js';
+type _ModuleConfig<C extends TS_Object> = C & {
+    minLogLevel?: LogLevel;
+};
 /**
  * Base abstract class for all modules in the nu-art ecosystem.
  *
@@ -20,9 +24,8 @@ import { ValidatorTypeResolver } from '../validator/validator-core.js';
  * 3. `init()` - Override to perform initialization logic
  * 4. `validate()` - Override to validate module state after initialization
  *
- * @template Config - The configuration type for this module
- * @template ModuleConfig - Extended config type that includes optional `minLogLevel`
- * @template ConfigValidator - Validator type resolver for config validation
+ * @template Config - The user-facing configuration type for this module.
+ *   Internal fields (e.g. minLogLevel) are computed from Config and hidden from consumers.
  *
  * @example
  * ```typescript
@@ -39,21 +42,17 @@ import { ValidatorTypeResolver } from '../validator/validator-core.js';
  * export const MyModule = new MyModule_Class();
  * ```
  */
-export declare abstract class Module<Config = any, ModuleConfig extends Config & {
-    minLogLevel?: LogLevel;
-} = Config & {
-    minLogLevel?: LogLevel;
-}, ConfigValidator extends ValidatorTypeResolver<ModuleConfig> = ValidatorTypeResolver<ModuleConfig>> extends Logger {
+export declare abstract class Module<Config extends TS_Object = any> extends Logger {
     private readonly classStack;
     private name;
     /** Module configuration, merged from default config and ModuleManager-provided config */
-    readonly config: ModuleConfig;
+    protected config: _ModuleConfig<Config>;
     /** Reference to the ModuleManager instance, injected during initialization */
     protected readonly manager: ModuleManager;
     /** Flag indicating whether the module has been initialized (set by ModuleManager) */
     protected readonly initiated = false;
     /** Optional config validator, set via setConfigValidator() */
-    protected readonly configValidator?: ConfigValidator;
+    protected configValidator?: TypeValidator<_ModuleConfig<Config>>;
     /**
      * Creates a new Module instance.
      *
@@ -75,7 +74,7 @@ export declare abstract class Module<Config = any, ModuleConfig extends Config &
      *
      * @param validator - Validator instance that implements ValidatorTypeResolver
      */
-    setConfigValidator(validator: ConfigValidator): void;
+    setConfigValidator(validator: TypeValidator<Config>): void;
     /**
      * Sets default configuration values that will be merged with any config
      * provided by the ModuleManager.
@@ -85,7 +84,7 @@ export declare abstract class Module<Config = any, ModuleConfig extends Config &
      *
      * @param config - Partial config object to merge with existing config
      */
-    setDefaultConfig(config: Partial<ModuleConfig>): void;
+    setDefaultConfig(config: Partial<_ModuleConfig<Config>>): void;
     /**
      * Gets the module name (class name without `_Class` suffix).
      */
@@ -162,3 +161,4 @@ export declare abstract class Module<Config = any, ModuleConfig extends Config &
     protected validate(): void;
     protected destroy(): Promise<void>;
 }
+export {};

package/core/module.js

@@ -17,8 +17,9 @@
  */
 import { BadImplementationException } from './exceptions/exceptions.js';
 import { merge } from '../utils/merge-tools.js';
-import { Logger } from './logger/index.js';
+import { Logger, LogLevel } from './logger/index.js';
 import { lastElement } from '../utils/array-tools.js';
+import { tsValidateEnum } from '../validator/type-validators.js';
 /**
  * Base abstract class for all modules in the nu-art ecosystem.
  *
@@ -35,9 +36,8 @@ import { lastElement } from '../utils/array-tools.js';
  * 3. `init()` - Override to perform initialization logic
  * 4. `validate()` - Override to validate module state after initialization
  *
- * @template Config - The configuration type for this module
- * @template ModuleConfig - Extended config type that includes optional `minLogLevel`
- * @template ConfigValidator - Validator type resolver for config validation
+ * @template Config - The user-facing configuration type for this module.
+ *   Internal fields (e.g. minLogLevel) are computed from Config and hidden from consumers.
  *
  * @example
  * ```typescript
@@ -100,8 +100,7 @@ export class Module extends Logger {
      * @param validator - Validator instance that implements ValidatorTypeResolver
      */
     setConfigValidator(validator) {
-        // @ts-ignore
-        this.configValidator = validator;
+        this.configValidator = { ...validator, minLogLevel: tsValidateEnum(LogLevel, false) };
     }
     /**
      * Sets default configuration values that will be merged with any config
@@ -113,7 +112,6 @@ export class Module extends Logger {
      * @param config - Partial config object to merge with existing config
      */
     setDefaultConfig(config) {
-        // @ts-ignore
         this.config = merge(this.config, config);
     }
     /**
@@ -140,8 +138,7 @@ export class Module extends Logger {
      */
     // @ts-ignore
     setConfig(config) {
-        // @ts-ignore
-        this.config = this.config ? merge(this.config, config) : config;
+        this.config = (this.config ? merge(this.config, config) : config);
         this.config.minLogLevel && this.setMinLevel(this.config.minLogLevel);
     }
     /**
@@ -155,7 +152,7 @@ export class Module extends Logger {
     // @ts-ignore
     setManager(manager) {
         // @ts-ignore
-        this.manager = manager;
+        this['manager'] = manager;
     }
     /**
      * Executes an async function in a fire-and-forget manner, logging the execution.

package/index.d.ts

@@ -35,5 +35,5 @@ export * from './validator/validator-core.js';
 export * from './validator/validators.js';
 export * from './validator/type-validators.js';
 export * from './consts/consts.js';
-export * from './mem-cache/index.js';
+export * from './mem-cache/MemCache.js';
 export * from './modules/csv-serializer.js';

package/index.js

@@ -52,5 +52,5 @@ export * from './validator/validator-core.js';
 export * from './validator/validators.js';
 export * from './validator/type-validators.js';
 export * from './consts/consts.js';
-export * from './mem-cache/index.js';
+export * from './mem-cache/MemCache.js';
 export * from './modules/csv-serializer.js';

package/mem-cache/MemCache.js

@@ -84,9 +84,8 @@ export class MemCache {
     onEntriesUpdated(itemsUpdated) {
         const frozen = itemsUpdated.map(item => Object.freeze(item));
         const ids = new Set(itemsUpdated.map(this.getId));
-        const toCache = this.filter(i => !ids.has(this.getId(i)));
-        toCache.push(...frozen);
-        this.setCache(toCache);
+        const retained = this.filter(i => !ids.has(this.getId(i)));
+        this.setCache(retained.concat(frozen));
     }
     setCache(cacheArray) {
         this._map = Object.freeze({ ...arrayToMap(cacheArray, (item) => this.getId(item)) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-art/ts-common",
-  "version": "0.500.0",
+  "version": "0.500.6",
   "description": "Core TypeScript infrastructure library for building modular applications with lifecycle management, logging, validation, and utilities",
   "type": "module",
   "keywords": [
@@ -37,8 +37,8 @@
     "run-tests": "ts-mocha --timeout 50000 -p src/test/tsconfig.json src/test/run-all-tests.ts"
   },
   "dependencies": {
-    "@nu-art/testalot": "0.500.0",
-    "@nu-art/logger": "0.500.0",
+    "@nu-art/testalot": "0.500.6",
+    "@nu-art/logger": "0.500.6",
     "fast-csv": "^5.0.2",
     "export-to-csv": "0.2.1",
     "moment": "^2.29.4",
@@ -61,12 +61,12 @@
       "import": "./index.js"
     },
     "./utils": {
-      "types": "./utils/index.d.ts",
-      "import": "./utils/index.js"
+      "types": "./utils-public-exports.d.ts",
+      "import": "./utils-public-exports.js"
     },
     "./mem-storage": {
-      "types": "./mem-storage/index.d.ts",
-      "import": "./mem-storage/index.js"
+      "types": "./mem-storage/MemStorage.d.ts",
+      "import": "./mem-storage/MemStorage.js"
     },
     "./testing": {
       "types": "./testing.d.ts",

package/testing/workspace-creator.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from '../core/logger/index.js';
-import { StringMap } from '../utils/index.js';
+import { StringMap } from '../utils/types.js';
 /**
  * Creates test workspaces from fixture files.
  *

package/testing.d.ts

@@ -1,2 +1,2 @@
-export * from './testing/index.js';
+export * from '@nu-art/testalot';
 export * from './testing/workspace-creator.js';

package/testing.js

@@ -1,2 +1,2 @@
-export * from './testing/index.js';
+export * from '@nu-art/testalot';
 export * from './testing/workspace-creator.js';

package/utils/date-time-tools.d.ts

@@ -7,6 +7,20 @@ export declare const Day: number;
 export declare const Week: number;
 export declare const Year: number;
 export declare const Month: number;
+/**
+ * Parse and format durations using compact notation (s/m/h/d/w).
+ *
+ * - `parse("3h1m30s")` → `10890000` (ms)
+ * - `format(10890000)` → `"3h1m30s"`
+ */
+export declare const StringFormat_Duration: {
+    format(ms: number): string;
+    parse(duration: string): number;
+};
+/** @see StringFormat_Duration.format */
+export declare const formatDuration: (ms: number) => string;
+/** @see StringFormat_Duration.parse */
+export declare const parseDuration: (duration: string) => number;
 /** Predefined timestamp format strings */
 export declare const Format_HHmmss_DDMMYYYY = "HH:mm:ss_DD-MM-YYYY";
 export declare const Format_YYYYMMDD_HHmmss = "YYYY-MM-DD_HH:mm:ss";

package/utils/date-time-tools.js

@@ -18,6 +18,7 @@
 import utc from 'moment';
 import { exists } from './tools.js';
 import { TimeProxy } from './time-proxy.js';
+import { BadImplementationException } from '../core/exceptions/exceptions.js';
 /** Time constants in milliseconds */
 export const Second = 1000;
 export const Minute = Second * 60;
@@ -26,6 +27,58 @@ export const Day = Hour * 24;
 export const Week = Day * 7;
 export const Year = Day * 365;
 export const Month = Year / 12;
+const durationUnits = {
+    s: Second,
+    m: Minute,
+    h: Hour,
+    d: Day,
+    w: Week,
+};
+const durationPattern = /^(?:\d+[smhdw])+$/;
+const durationSegment = /(\d+)([smhdw])/g;
+const durationUnitOrder = [
+    { unit: 'd', ms: Day },
+    { unit: 'h', ms: Hour },
+    { unit: 'm', ms: Minute },
+    { unit: 's', ms: Second },
+];
+/**
+ * Parse and format durations using compact notation (s/m/h/d/w).
+ *
+ * - `parse("3h1m30s")` → `10890000` (ms)
+ * - `format(10890000)` → `"3h1m30s"`
+ */
+export const StringFormat_Duration = {
+    format(ms) {
+        if (ms <= 0)
+            return '0s';
+        let remaining = ms;
+        let result = '';
+        for (const { unit, ms: unitMs } of durationUnitOrder) {
+            const count = Math.floor(remaining / unitMs);
+            if (count > 0) {
+                result += `${count}${unit}`;
+                remaining -= count * unitMs;
+            }
+        }
+        return result || '0s';
+    },
+    parse(duration) {
+        if (!durationPattern.test(duration))
+            throw new BadImplementationException(`Invalid duration format: "${duration}" — expected segments like 5s, 1m, 3h1m30s`);
+        let total = 0;
+        let match;
+        durationSegment.lastIndex = 0;
+        while ((match = durationSegment.exec(duration)) !== null) {
+            total += parseInt(match[1]) * durationUnits[match[2]];
+        }
+        return total;
+    },
+};
+/** @see StringFormat_Duration.format */
+export const formatDuration = StringFormat_Duration.format;
+/** @see StringFormat_Duration.parse */
+export const parseDuration = StringFormat_Duration.parse;
 /** Predefined timestamp format strings */
 export const Format_HHmmss_DDMMYYYY = 'HH:mm:ss_DD-MM-YYYY';
 export const Format_YYYYMMDD_HHmmss = 'YYYY-MM-DD_HH:mm:ss';

package/utils/query-params.d.ts

@@ -12,7 +12,7 @@ export type RouteParams = {
  *
  * Converts an object of parameters into a URL-encoded query string.
  * - Functions are evaluated to get their return value
- * - undefined/null values result in `key=` (empty value)
+ * - undefined/null values are omitted entirely
  * - All values are URI-encoded
  *
  * @param params - Object with parameter keys and values

package/utils/query-params.js

@@ -3,17 +3,17 @@
  *
  * Converts an object of parameters into a URL-encoded query string.
  * - Functions are evaluated to get their return value
- * - undefined/null values result in `key=` (empty value)
+ * - undefined/null values are omitted entirely
  * - All values are URI-encoded
  *
  * @param params - Object with parameter keys and values
  * @returns URL-encoded query string (e.g., "key1=value1&key2=value2")
  */
 export function composeQueryParams(params = {}) {
-    return Object.keys(params).map((paramKey) => {
+    return Object.keys(params)
+        .filter(key => params[key] !== undefined && params[key] !== null)
+        .map((paramKey) => {
         let param = params[paramKey];
-        if (param === undefined || param === null)
-            return `${paramKey}=`;
         if (typeof param === 'function')
             param = param();
         return `${paramKey}=${encodeURIComponent(param)}`;

package/utils/string-tools.d.ts

@@ -161,3 +161,13 @@ export declare function normalizeString(string: string): string;
  * ```
  */
 export declare function convertUpperCamelCase(upperCamelCase: string, delimiter?: string): string;
+/**
+ * Parse and format numbers using volume shorthand notation (K/M/G/T).
+ *
+ * - `parse("76M")` → `76_000_000`
+ * - `format(76_000_000)` → `"76M"`
+ */
+export declare const StringFormat_Volume: {
+    parse(input: string): number;
+    format(value: number): string;
+};

package/utils/string-tools.js

@@ -267,3 +267,48 @@ export function normalizeString(string) {
 export function convertUpperCamelCase(upperCamelCase, delimiter = ' ') {
     return upperCamelCase.replace(/([a-z0-9])([A-Z])/g, `$1${delimiter}$2`);
 }
+const _volumeSuffixes = [
+    { suffix: 'T', value: 1e12 },
+    { suffix: 'G', value: 1e9 },
+    { suffix: 'M', value: 1e6 },
+    { suffix: 'K', value: 1e3 },
+];
+const _volumeSuffixMap = Object.fromEntries(_volumeSuffixes.map(s => [s.suffix, s.value]));
+const _volumePattern = /^(-?\d+\.?\d*)\s*([KMGT])?$/;
+/**
+ * Parse and format numbers using volume shorthand notation (K/M/G/T).
+ *
+ * - `parse("76M")` → `76_000_000`
+ * - `format(76_000_000)` → `"76M"`
+ */
+export const StringFormat_Volume = {
+    parse(input) {
+        const trimmed = input.trim();
+        if (!trimmed)
+            throw new Error('Empty volume input');
+        const match = trimmed.match(_volumePattern);
+        if (!match)
+            throw new Error(`Invalid volume format: "${input}" — expected pattern like 76M, 1.5G, 300K`);
+        const coefficient = Number(match[1]);
+        const suffix = match[2];
+        if (!suffix)
+            return coefficient;
+        const multiplier = _volumeSuffixMap[suffix];
+        if (multiplier === undefined)
+            throw new Error(`Unknown volume suffix: "${suffix}"`);
+        return coefficient * multiplier;
+    },
+    format(value) {
+        if (value === 0)
+            return '0';
+        for (const { suffix, value: threshold } of _volumeSuffixes) {
+            if (Math.abs(value) < threshold)
+                continue;
+            const coefficient = value / threshold;
+            const rounded = Math.round(coefficient * 100) / 100;
+            if (rounded * threshold === value)
+                return `${rounded}${suffix}`;
+        }
+        return String(value);
+    },
+};

package/validator/type-validators.d.ts

@@ -78,6 +78,8 @@ export declare const tsValidateAnyNumber: Validator<number>;
 export declare const tsValidateOptionalAnyNumber: Validator<number>;
 export declare const tsValidateEnum: (enumType: TypedMap<number | string>, mandatory?: boolean) => Validator<number | string>;
 export declare const tsValidateBoolean: (mandatory?: boolean) => Validator<boolean>;
+export declare const tsValidateOptionalBoolean: Validator<boolean>;
+export declare const tsValidateMandatoryBoolean: Validator<boolean>;
 export declare const tsValidateValue: <T>(values: T[] | ReadonlyArray<T>, mandatory?: boolean) => Validator<any>;
 export declare const tsValidateIsInRange: (ranges: [number, number][], mandatory?: boolean) => Validator<number>;
 export declare const tsValidateRange: (mandatory?: boolean) => Validator<[number, number] | undefined>;

package/validator/type-validators.js

@@ -183,6 +183,8 @@ export const tsValidateBoolean = (mandatory = true) => {
             return `Input is not a boolean! \nvalue: ${input}\ntype: ${typeof input}`;
         }];
 };
+export const tsValidateOptionalBoolean = tsValidateBoolean(false);
+export const tsValidateMandatoryBoolean = tsValidateBoolean();
 export const tsValidateValue = (values, mandatory = true) => {
     return [tsValidateExists(mandatory),
         (input) => {

package/mem-cache/index.d.ts

@@ -1 +0,0 @@
-export * from './MemCache.js';

package/mem-cache/index.js

@@ -1,6 +0,0 @@
-/*
- * ts-common - Core TypeScript infrastructure
- * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
- * Licensed under the Apache License, Version 2.0
- */
-export * from './MemCache.js';

package/mem-storage/index.d.ts

@@ -1 +0,0 @@
-export * from './MemStorage.js';

package/mem-storage/index.js

@@ -1 +0,0 @@
-export * from './MemStorage.js';

package/testing/index.d.ts

@@ -1 +0,0 @@
-export * from '@nu-art/testalot';

package/testing/index.js

@@ -1 +0,0 @@
-export * from '@nu-art/testalot';

package/utils/index.d.ts

@@ -1,27 +0,0 @@
-export * from './array-tools.js';
-export * from './conflict-tools.js';
-export * from './crypto-tools.js';
-export * from './date-time-tools.js';
-export * from './db-object-tools.js';
-export * from './exception-tools.js';
-export * from './filter-tools.js';
-export * from './hash-tools.js';
-export * from './index.js';
-export * from './json-tools.js';
-export * from './merge-tools.js';
-export * from './mimetype-tools.js';
-export * from './number-tools.js';
-export * from './object-tools.js';
-export * from './promise-tools.js';
-export * from './query-params.js';
-export * from './queue.js';
-export * from './queue-v2.js';
-export * from './random-tools.js';
-export * from './storage-capacity-tools.js';
-export * from './string-tools.js';
-export * from './time-proxy.js';
-export * from './tools.js';
-export * from './types.js';
-export * from './ui-tools.js';
-export * from './url-tools.js';
-export * from './version-tools.js';

package/utils/index.js

@@ -1,27 +0,0 @@
-export * from './array-tools.js';
-export * from './conflict-tools.js';
-export * from './crypto-tools.js';
-export * from './date-time-tools.js';
-export * from './db-object-tools.js';
-export * from './exception-tools.js';
-export * from './filter-tools.js';
-export * from './hash-tools.js';
-export * from './index.js';
-export * from './json-tools.js';
-export * from './merge-tools.js';
-export * from './mimetype-tools.js';
-export * from './number-tools.js';
-export * from './object-tools.js';
-export * from './promise-tools.js';
-export * from './query-params.js';
-export * from './queue.js';
-export * from './queue-v2.js';
-export * from './random-tools.js';
-export * from './storage-capacity-tools.js';
-export * from './string-tools.js';
-export * from './time-proxy.js';
-export * from './tools.js';
-export * from './types.js';
-export * from './ui-tools.js';
-export * from './url-tools.js';
-export * from './version-tools.js';