@nu-art/ts-common 0.400.4 → 0.400.6

package/index.d.ts

@@ -42,6 +42,7 @@ export * from './utils/ui-tools.js';
 export * from './utils/json-tools.js';
 export * from './utils/promise-tools.js';
 export * from './utils/url-tools.js';
+export * from './utils/debounce.js';
 export * from './validator/validator-core.js';
 export * from './validator/validators.js';
 export * from './validator/type-validators.js';

package/index.js

@@ -59,6 +59,7 @@ export * from './utils/ui-tools.js';
 export * from './utils/json-tools.js';
 export * from './utils/promise-tools.js';
 export * from './utils/url-tools.js';
+export * from './utils/debounce.js';
 export * from './validator/validator-core.js';
 export * from './validator/validators.js';
 export * from './validator/type-validators.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-art/ts-common",
-  "version": "0.400.4",
+  "version": "0.400.6",
   "description": "js and ts infra",
   "type": "module",
   "keywords": [
@@ -36,9 +36,7 @@
     "node-forge": "^1.2.1",
     "uuid": "^9.0.0",
     "csv-parser": "^2.3.3",
-    "xlsx": "^0.18.5",
-    "jose": "^5.0.0",
-    "pbkdf2": "3.1.2"
+    "jose": "^5.0.0"
   },
   "devDependencies": {
     "@types/mocha": "^10.0.6",

package/testing/workspace-creator.d.ts

@@ -1,10 +1,12 @@
 import { Logger } from '../core/logger/Logger.js';
+import { StringMap } from '../utils/index.js';
 export declare class TestWorkspaceCreator extends Logger {
     private readonly pathToFixtures;
     private readonly pathToWorkspace;
     constructor(pathToFixtures: string, pathToWorkspace: string);
-    setupWorkspace(fixtures: string[], relativePath?: string, clean?: boolean): void;
-    clearWorkspace(relativePathInWorkspace?: string): void;
-    extractFixture(pathToFixture: string, relativePathInWorkspace?: string): void;
+    setupWorkspace(fixtures: string[], relativePath?: string, clean?: boolean): Promise<void>;
+    setupWorkspace(fixtures: string[], params: StringMap, relativePath?: string, clean?: boolean): Promise<void>;
+    clearWorkspace(relativePathInWorkspace?: string): Promise<void>;
+    extractFixture(pathToFixture: string, relativePathInWorkspace?: string, params?: StringMap): Promise<void>;
 }
 export declare function setupWorkspace(pathToWorkspaceFile: string, outputRootDir: string, clean?: boolean): void;

package/testing/workspace-creator.js

@@ -1,6 +1,7 @@
-import { mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { dirname, resolve } from 'path';
 import { Logger } from '../core/logger/Logger.js';
+import { FileSystemUtils } from '../utils/FileSystemUtils.js';
 const FILE_HEADER_REGEX = /^\/\/ file: (.+)$/gm;
 const INNER_FILE_HEADER_REGEX = /^(\/\/)*?\/\/\/\/ file:/gm;
 export class TestWorkspaceCreator extends Logger {
@@ -11,20 +12,38 @@ export class TestWorkspaceCreator extends Logger {
         this.pathToFixtures = pathToFixtures;
         this.pathToWorkspace = pathToWorkspace;
     }
-    setupWorkspace(fixtures, relativePath = '', clean = true) {
-        if (clean)
-            this.clearWorkspace(relativePath);
+    async setupWorkspace(fixtures, params, relativePath, clean) {
+        let _clean = clean;
+        let _relativePath;
+        let _params;
+        if (typeof relativePath === 'boolean') {
+            _clean = relativePath;
+        }
+        else if (typeof relativePath === 'string') {
+            _relativePath = relativePath;
+        }
+        if (typeof params === 'string') {
+            _relativePath = params;
+            _params = {};
+        }
+        else {
+            _params = params;
+        }
+        _relativePath = _relativePath ?? '';
+        _clean = _clean ?? true;
+        if (_clean)
+            await this.clearWorkspace(_relativePath);
         for (const fixture of fixtures) {
-            this.extractFixture(resolve(this.pathToFixtures, fixture), relativePath);
+            await this.extractFixture(resolve(this.pathToFixtures, fixture), _relativePath, _params);
         }
     }
-    clearWorkspace(relativePathInWorkspace = '') {
+    async clearWorkspace(relativePathInWorkspace = '') {
         const path = resolve(this.pathToWorkspace, relativePathInWorkspace);
         this.logWarning(`Deleting folder: ${path}`);
-        rmSync(path, { recursive: true, force: true });
+        await FileSystemUtils.folder.delete(path);
     }
-    extractFixture(pathToFixture, relativePathInWorkspace = '') {
-        const content = readFileSync(pathToFixture, 'utf8');
+    async extractFixture(pathToFixture, relativePathInWorkspace = '', params = {}) {
+        const content = await FileSystemUtils.file.template.read(pathToFixture, params);
         const matches = [...content.matchAll(FILE_HEADER_REGEX)];
         if (matches.length === 0) {
             this.logError('No matching file headers found. Aborting.');
@@ -43,8 +62,7 @@ export class TestWorkspaceCreator extends Logger {
                 .slice(startIndex + currentMatch[0].length, endIndex)
                 .trimStart();
             fileContent = fileContent.replace(INNER_FILE_HEADER_REGEX, '\$1// file:');
-            mkdirSync(dirname(targetPath), { recursive: true });
-            writeFileSync(targetPath, fileContent);
+            await FileSystemUtils.file.write(targetPath, fileContent);
             this.logVerbose(`Wrote: ${targetPath}`);
         }
     }

package/utils/debounce.d.ts

@@ -0,0 +1,32 @@
+import { Logger } from '../core/logger/Logger.js';
+export declare class Debounce<Args extends any[], Response> extends Logger {
+    private action;
+    private readonly waitMs;
+    private readonly maxWaitMs?;
+    private triggerIndex;
+    private waitTimer?;
+    private maxTimer?;
+    private latestArgs;
+    private actionInProgress;
+    private triggerPending;
+    constructor(action: (...args: Args) => Response, waitMs: number, maxWaitMs?: number);
+    private validate_WaitMs;
+    private validate_MaxWaitMs;
+    private clearTimers;
+    private executeAction;
+    /** Schedule the action to be performed (fire-and-forget). */
+    trigger(...args: Args): void;
+    /**
+     * Returns whether an action is currently scheduled
+     */
+    isScheduled(): boolean;
+    /**
+     * Run immediately if scheduled and return the action's value.
+     * - Returns Response when something was scheduled, else undefined.
+     * - If action throws sync here, it throws to the caller.
+     * - If action returns a rejected Promise, caller handles it.
+     */
+    flush(): Response | undefined;
+    /** Cancel any scheduled run. (Does not cancel in-flight.) */
+    clear(): void;
+}

package/utils/debounce.js

@@ -0,0 +1,115 @@
+import { BadImplementationException } from '../core/exceptions/exceptions.js';
+import { Logger } from '../core/logger/Logger.js';
+import { isPromise } from './promise-tools.js';
+import { exists } from './tools.js';
+export class Debounce extends Logger {
+    action;
+    waitMs;
+    maxWaitMs;
+    triggerIndex = 0;
+    waitTimer;
+    maxTimer;
+    latestArgs = [];
+    actionInProgress = false;
+    triggerPending = false;
+    constructor(action, waitMs, maxWaitMs) {
+        super('Debounce');
+        this.validate_WaitMs(waitMs);
+        this.validate_MaxWaitMs(waitMs, maxWaitMs);
+        this.action = action;
+        this.waitMs = waitMs;
+        this.maxWaitMs = maxWaitMs;
+    }
+    //######################### Validation #########################
+    validate_WaitMs(waitMs) {
+        if (waitMs < 0)
+            throw new BadImplementationException('waitMs value must be >= 0');
+    }
+    validate_MaxWaitMs(waitMs, maxWaitMs) {
+        if (!exists(maxWaitMs))
+            return;
+        if (maxWaitMs <= 0)
+            throw new BadImplementationException('maxWaitMs value must be > 0');
+        if (maxWaitMs < waitMs)
+            this.logWarning('maxWaitMs < waitMs; the \'max\' may never matter');
+    }
+    //######################### Internal Logic #########################
+    clearTimers() {
+        if (this.waitTimer) {
+            clearTimeout(this.waitTimer);
+            this.waitTimer = undefined;
+        }
+        if (this.maxTimer) {
+            clearTimeout(this.maxTimer);
+            this.maxTimer = undefined;
+        }
+    }
+    executeAction(triggerIndex, immediate) {
+        if (triggerIndex !== this.triggerIndex)
+            return;
+        this.triggerIndex++;
+        const args = this.latestArgs ?? [];
+        this.clearTimers();
+        const result = this.action(...args);
+        if (immediate)
+            return result;
+        //Set up chain triggering if the action is asynchronous.
+        if (isPromise(result)) {
+            this.actionInProgress = true;
+            Promise.resolve(result).finally(() => {
+                this.actionInProgress = false;
+                //Immediately execute the action again if debounce was triggered during the current run
+                if (this.triggerPending) {
+                    this.triggerPending = false;
+                    void this.executeAction(this.triggerIndex);
+                }
+            });
+        }
+    }
+    //######################### Public Logic #########################
+    /** Schedule the action to be performed (fire-and-forget). */
+    trigger(...args) {
+        this.latestArgs = args;
+        //If action is in progress, queue up immediate trigger
+        if (this.actionInProgress) {
+            this.triggerPending = true;
+            return;
+        }
+        // Normal debounce behavior while idle:
+        //Reset waitTimer
+        if (this.waitTimer)
+            clearTimeout(this.waitTimer);
+        const triggerIndex = this.triggerIndex;
+        this.waitTimer = setTimeout(() => {
+            void this.executeAction(triggerIndex);
+        }, this.waitMs);
+        //Set maxWaitTimer if configured and does not currently exist
+        if (exists(this.maxWaitMs) && !exists(this.maxTimer))
+            this.maxTimer = setTimeout(() => {
+                void this.executeAction(triggerIndex);
+            }, this.maxWaitMs);
+    }
+    /**
+     * Returns whether an action is currently scheduled
+     */
+    isScheduled() {
+        return exists(this.waitTimer ?? this.maxTimer);
+    }
+    /**
+     * Run immediately if scheduled and return the action's value.
+     * - Returns Response when something was scheduled, else undefined.
+     * - If action throws sync here, it throws to the caller.
+     * - If action returns a rejected Promise, caller handles it.
+     */
+    flush() {
+        if (!this.isScheduled())
+            return void this.logInfo('Not scheduled');
+        return this.executeAction(this.triggerIndex, true);
+    }
+    /** Cancel any scheduled run. (Does not cancel in-flight.) */
+    clear() {
+        this.clearTimers();
+        this.triggerIndex++;
+        this.triggerPending = false;
+    }
+}

package/utils/number-tools.d.ts

@@ -1,2 +1,3 @@
 export declare const roundNumber: (number: number, digits: number) => number;
 export declare const clamp: (min: number, num: number, max: number) => number;
+export declare const numberInRange: (number: number, range: [number, number]) => boolean;

package/utils/number-tools.js

@@ -20,3 +20,6 @@ export const roundNumber = (number, digits) => {
     return Math.round(number * multiple) / multiple;
 };
 export const clamp = (min, num, max) => Math.min(Math.max(num, min), max);
+export const numberInRange = (number, range) => {
+    return range[0] <= number && number <= range[1];
+};

package/utils/tools.d.ts

@@ -19,3 +19,4 @@ export type KeyBinder<K extends string, Type> = {
     Key: K;
     Type: Type;
 };
+export declare function createLockedAsyncFunction(fn: () => Promise<void>): () => void;

package/utils/tools.js

@@ -63,3 +63,14 @@ export function freeze(item) {
 export const logicalXOR = (a, b) => {
     return (a && !b) || (!a && b);
 };
+export function createLockedAsyncFunction(fn) {
+    let inProgress = false;
+    return () => {
+        if (inProgress)
+            return;
+        inProgress = true;
+        Promise.resolve(fn()).finally(() => {
+            inProgress = false;
+        });
+    };
+}