@isdk/util 0.3.1 → 0.3.3

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Dirent } from 'fs';
 import { ScalarTag, CollectionTag, TagId, Tags, ParseOptions, DocumentOptions, SchemaOptions, ToJSOptions, CreateNodeOptions, ToStringOptions } from 'yaml';
+import { EventEmitter } from 'events-ex';
 
 type StringifyFunc = (content: any) => string;
 interface LoadConfigFileOptions {
@@ -73,6 +74,33 @@ declare class ConfigFile {
      * ```
      */
     static saveSync(filename: string, config: any, options?: LoadConfigFileOptions): string;
+    /**
+     * Checks if a configuration file exists at the specified path.
+     *
+     * This method normalizes the filename by removing the extension (if present) and then delegates
+     * to the underlying LoadConfigFile utility to perform the existence check. The normalization
+     * ensures consistent handling of files regardless of whether they include extensions in the
+     * provided filename.
+     *
+     * @param filename - The path to the configuration file to check for existence.
+     *                  This can include or omit the file extension.
+     * @param options - Optional configuration options that may affect how the file existence
+     *                 is checked, including extension level handling.
+     *
+     * @returns `true` if the configuration file exists, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * // Check if a YAML config file exists
+     * const exists = ConfigFile.existsSync('config.yaml');
+     * console.log(exists); // true or false
+     *
+     * // Check with options
+     * const existsWithExt = ConfigFile.existsSync('config', { extLevel: 2 });
+     * console.log(existsWithExt); // true or false
+     * ```
+     */
+    static existsSync(filename: string, options?: LoadConfigFileOptions): boolean;
 }
 
 /**
@@ -437,4 +465,466 @@ declare function extNameLevel(extName: string): number;
  */
 declare function arrayHasAll<T = any>(array: T[], elements: T[]): boolean;
 
-export { ConfigFile, DefaultAllTextFiles, FilenameReservedRegex, type IncludeFiles, type LoadConfigFileOptions, type SanitizeFilenameOptions, type StringifyFunc, type TraverseFolderHandler, type TraverseFolderSyncHandler, WindowsReservedNameRegex, arrayHasAll, extNameLevel, filenameReservedRegex, getMultiLevelExtname, glob, isStringIn, isValidFilename, isValidFilepath, normalizeIncludeFiles, parseFrontMatter, parseYaml, reControlCharsRegex, registerYamlTag, removeLeadingEmptyLines, sanitizeFilename, sanitizeFilepath, stringifyYaml, toCamelCase, toCapitalCase, toPascalCase, traverseFolder, traverseFolderSync };
+declare class Deque<T = any> extends Array<T> {
+    private _capacity;
+    private _length;
+    private _front;
+    private _disableAutoResize?;
+    constructor(capacity?: number | T[], disableAutoResize?: boolean);
+    push(item: T): number;
+    unshift(item: T): number;
+    /**
+     * Removes and returns the element at the back of the deque.
+     *
+     * @param skipNull When `true`, skips trailing `null`/`undefined` values until a valid element is found or all elements are processed.
+     * @returns The removed element, or `undefined` if the deque is empty or all elements are skipped.
+     *
+     * @example
+     * // Normal pop without skipping
+     * const deque = new Deque([1, 2, 3]);
+     * deque.pop(); // 3
+     *
+     * @example
+     * // Skipping null values
+     * const nullDeque = new Deque([null, 4, null]);
+     * nullDeque.pop(true); // 4
+     * nullDeque.pop(true); // undefined (skipped remaining nulls)
+     *
+     * @example
+     * // Mixed elements with skip
+     * const mixedDeque = new Deque([5, null, 6, null]);
+     * mixedDeque.pop(true); // 6
+     * mixedDeque.pop(false); // null (explicitly not skipping)
+     */
+    pop(skipNull?: boolean): T | undefined;
+    /**
+     * Removes and returns the element at the front of the deque.
+     *
+     * @param skipNull When `true`, skips leading `null`/`undefined` values until a valid element is found or all elements are processed.
+     * @returns The removed element, or `undefined` if the deque is empty or all elements are skipped.
+     *
+     * @example
+     * // Normal shift without skipping
+     * const deque = new Deque([1, 2, 3]);
+     * deque.shift(); // 1
+     *
+     * @example
+     * // Skipping null values
+     * const nullDeque = new Deque([null, 4, null]);
+     * nullDeque.shift(true); // 4
+     * nullDeque.shift(true); // undefined (skipped remaining nulls)
+     *
+     * @example
+     * // Mixed elements with skip
+     * const mixedDeque = new Deque([null, 5, null, 6]);
+     * mixedDeque.shift(true); // 5
+     * mixedDeque.shift(false); // null (explicitly not skipping)
+     */
+    shift(skipNull?: boolean): T | undefined;
+    /**
+     * Gets the number of elements in the deque.
+     *
+     * @returns The current count of elements in the deque.
+     *
+     * @example
+     * const deque = new Deque([1, 2, 3]);
+     * console.log(deque.size); // 3
+     *
+     * @important
+     * Do NOT use the native `Array.length` property. The Deque implementation uses a circular buffer with capacity management, so the native `length` reflects the underlying array capacity, not the actual element count. Always use `size` to get the correct element count.
+     */
+    get size(): number;
+    get(index: number): T | undefined;
+    peekBack(): T | undefined;
+    peekFront(): T | undefined;
+    clear(): void;
+    isEmpty(): boolean;
+    /**
+     * Removes the element at the specified index.
+     * @param index Logical index position (0 represents the front, length-1 represents the back)
+     * @returns The removed element
+     */
+    removeAt(index: number): T | undefined;
+    private checkCapacity;
+    private resizeTo;
+}
+
+/**
+ * Represents a set of integers using a bit field.
+ * Each bit in the bit field represents an integer starting from 0,
+ * where the flag value 0 represents the 0th bit, 1 represents the 1st bit, and so on.
+ */
+declare class IntSet {
+    private bitField;
+    static has(bitField: number, flag: number): boolean;
+    static add(bitField: number, flag: number): number;
+    static delete(bitField: number, flag: number): number;
+    constructor(bitField?: number);
+    /**
+     * Adds an element to the set.
+     *
+     * @param flag - The flag value representing the bit position to set.
+     *              Note: the flag value 0 represents the 0th bit, and so on.
+     */
+    add(flag: number): this;
+    /**
+     * Removes an element from the set.
+     *
+     * @param flag - The flag value representing the bit position to set. 0 represents the 0th bit
+     */
+    delete(flag: number): this;
+    /**
+     * Determines whether an element is in the set.
+     *
+     * @param flag - The flag value representing the bit position to set. 0 represents the 0th bit
+     * @returns true if the element is in the set; otherwise, false.
+     */
+    has(flag: number): boolean;
+    /**
+     * Clears all elements from the set.
+     */
+    clear(): this;
+    valueOf(): number;
+    toString(): string;
+    toJSON(): number;
+}
+
+/**
+ * Suspends execution for a specified number of milliseconds
+ * @param ms - The number of milliseconds to pause execution
+ * @example
+ * ```ts
+ * await sleep(500); // Pause for half a second
+ * ```
+ * @remarks
+ * This implementation uses `setTimeout` under the hood and is more precise
+ * for longer durations than `setImmediate`-based approaches
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Yields execution control to the event loop, allowing pending I/O operations
+ * and scheduled tasks to run before continuing.
+ *
+ * @remarks
+ * This method creates a microtask checkpoint using `setImmediate`, which helps:
+ * - Interleave CPU-intensive work with I/O events
+ * - Prevent event loop blocking
+ * - Maintain application responsiveness
+ *
+ * Particularly useful for breaking up long synchronous operations in Node.js.
+ */
+declare function yieldExec(): Promise<void>;
+
+declare const DefaultAsyncSemaphoreCapacity = 32;
+type SemaphoreIsReadyFuncType = () => Promise<boolean> | boolean;
+interface BinarySemaphoreOptions {
+    initFn?: () => any;
+    pauseFn?: () => void;
+    resumeFn?: () => void;
+    capacity?: number;
+}
+interface BinarySemaphoreAcquireOptions {
+    signal?: AbortSignal;
+    [n: string]: any;
+}
+interface BinarySemaphoreReleaseOptions {
+    token?: any;
+    [n: string]: any;
+}
+interface BinarySemaphoreReleaserFunc extends BinarySemaphoreReleaseOptions {
+    (): void;
+}
+interface SemaphoreOptions extends BinarySemaphoreOptions {
+    maxConcurrency?: number;
+    isReadyFn?: SemaphoreIsReadyFuncType;
+}
+interface SemaphoreTaskItem extends BinarySemaphoreAcquireOptions {
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+    token?: any;
+}
+/**
+ * A binary semaphore implementation for managing concurrency in asynchronous operations.
+ * Unlike a general semaphore, a binary semaphore allows only one caller to acquire the semaphore at a time.
+ * It provides methods to acquire, release, and manage waiting tasks efficiently.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * const semaphore = new Semaphore(5); // Allows 5 concurrent operations.
+ *
+ * const semaphore = new Semaphore(
+ *   4, // Allow 4 concurrent async calls
+ *   {
+ *     capacity: 100 // Prealloc space for 100 tokens
+ *   }
+ * );
+ *
+ * async function fetchData(x) {
+ *   await semaphore.acquire()
+ *   try {
+ *     console.log(semaphore.pendingCount + ' calls to fetch are waiting')
+ *     // ... do some async stuff with x
+ *   } finally {
+ *     semaphore.release();
+ *   }
+ * }
+ *
+ * const data = await Promise.all(array.map(fetchData));
+ * ```
+ */
+declare class BinarySemaphore {
+    readonly waiting: Deque<SemaphoreTaskItem | undefined>;
+    protected free: any;
+    protected emitter: EventEmitter;
+    protected useDefaultTokens: boolean;
+    protected pauseFn?: () => void;
+    protected resumeFn?: () => void;
+    protected initTokenFn: (token?: any) => void;
+    protected paused: boolean;
+    protected _activeCount: number;
+    /**
+     * Creates a binary semaphore object for managing concurrency in asynchronous operations.
+     *
+     * @param options.initFn Function that is used to initialize the tokens used to manage the semaphore. The default is () => '1'.
+     * @param options.pauseFn An optional fuction that is called to opportunistically request pausing the the incoming stream of data,
+     *    instead of piling up waiting promises and possibly running out of memory. See examples/pausing.js.
+     * @param options.resumeFn An optional function that is called when there is room again to accept new waiters on the semaphore.
+     *    This function must be declared if a pauseFn is declared.
+     * @param options.capacity Sets the size of the preallocated waiting list inside the semaphore.
+     *    This is typically used by high performance where the developer can make a rough estimate of the number of concurrent users of a semaphore.
+     *
+     * ```ts
+     * const readline = require('readline');
+     *
+     * const rl = readline.createInterface({
+     * 	input: process.stdin,
+     * 	output: process.stdout,
+     * 	terminal: false
+     * });
+     *
+     * function pause() {
+     * 	console.log('Pausing the stream');
+     * 	rl.pause();
+     * }
+     *
+     * function resume() {
+     * 	console.log('Resuming the stream');
+     * 	rl.resume();
+     * }
+     *
+     * const s = new BinarySemaphore({ pauseFn: pause, resumeFn: resume });
+     *
+     * async function parse(line) {
+     * 	await s.acquire();
+     *
+     * 	console.log(line);
+     *
+     * 	s.release();
+     * }
+     *
+     * rl.on('line', line => {
+     * 	parse(line).catch(console.error);
+     * });
+     * ```
+     *
+     */
+    constructor(options?: BinarySemaphoreOptions);
+    initFree(options?: BinarySemaphoreOptions): void;
+    onReleased(options?: BinarySemaphoreReleaseOptions): void;
+    init(options: BinarySemaphoreOptions): void;
+    _newReleaser(options?: BinarySemaphoreReleaseOptions): BinarySemaphoreReleaserFunc;
+    _dispatchTask(task: SemaphoreTaskItem, options?: BinarySemaphoreReleaseOptions): void;
+    lock(options?: BinarySemaphoreAcquireOptions): any;
+    unlock(token?: any): void;
+    /**
+     * Attempt to acquire a token from the semaphore, if one is available immediately. Otherwise, return undefined.
+     *
+     * @return Returns a token if the semaphore is not full; otherwise, returns `undefined`.
+     */
+    tryAcquire(options?: BinarySemaphoreAcquireOptions): any | undefined;
+    /**
+     * Acquire a token from the semaphore, thus decrement the number of available execution slots. If initFn is not used then the return value of the function can be discarded.
+     * @param options.signal An optional AbortSignal to abort the acquisition process. If aborted, the promise will reject with an AbortError.
+     * @return A promise that resolves to a release function when a token is acquired. If the semaphore is full, the caller will be added to a waiting queue.
+     */
+    acquire(options?: BinarySemaphoreAcquireOptions): Promise<BinarySemaphoreReleaserFunc>;
+    /**
+     * Releases the semaphore, incrementing the number of free execution slots. If there are tasks in the waiting queue, the next task will be dispatched.
+     * @param options.token Optional token returned by `acquire()` when using a custom `initFn`. If provided, it will be used to unlock the semaphore.
+     */
+    release(options?: BinarySemaphoreReleaseOptions): void;
+    /**
+     * Drains the semaphore and returns all the initialized tokens in an array. Draining is an ideal way to ensure there are no pending async tasks, for example before a process will terminate.
+     */
+    drain(): Promise<any[]>;
+    abort(reason?: any): void;
+    /**
+     * Get the total count of all active operations.
+     *
+     * This method returns the number of operations that are either:
+     * - Waiting in the queue to acquire the semaphore (`pendingCount`).
+     * - Already acquired the semaphore but have not yet released it.
+     *
+     * @returns {number} The total count of active operations, including both waiting and ongoing tasks.
+     */
+    get activeCount(): number;
+    /**
+     * Get the number of callers waiting on the semaphore, i.e. the number of pending promises.
+     *
+     * @returns The number of waiters in the waiting list.
+     */
+    get pendingCount(): number;
+}
+/**
+ * A Semaphore implementation for managing concurrency in asynchronous operations.
+ * Semaphores allow a fixed number of resources to be accessed concurrently.
+ * This class extends BinarySemaphore and adds support for a maximum concurrency limit and an optional readiness check.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * const semaphore = new Semaphore(5); // Allows 5 concurrent operations.
+ *
+ * const semaphore = new Semaphore(
+ *   4, // Allow 4 concurrent async calls
+ *   {
+ *     capacity: 100, // Prealloc space for 100 tokens
+ *     isReadyFn: async () => {
+ *       // Check if the system is ready to handle more requests
+ *       return true;
+ *     },
+ *     pauseFn: () => {
+ *       console.log('Pausing the stream');
+ *     },
+ *     resumeFn: () => {
+ *       console.log('Resuming the stream');
+ *     }
+ *   }
+ * );
+ *
+ * async function fetchData(x) {
+ *   await semaphore.acquire()
+ *   try {
+ *     console.log(semaphore.pendingCount() + ' calls to fetch are waiting')
+ *     // ... do some async stuff with x
+ *   } finally {
+ *     semaphore.release();
+ *   }
+ * }
+ *
+ * const data = await Promise.all(array.map(fetchData));
+ * ```
+ */
+declare class Semaphore extends BinarySemaphore {
+    readonly maxConcurrency: number;
+    protected free: Deque<any>;
+    private isReady?;
+    /**
+     * Creates a semaphore object. The first argument is the maximum concurrently number and the second argument is optional.
+     *
+     * @param maxConcurrency The maximum number of callers allowed to acquire the semaphore concurrently.
+     * @param options.initFn Function that is used to initialize the tokens used to manage the semaphore. The default is () => '1'.
+     * @param options.pauseFn An optional function that is called to opportunistically request pausing the incoming stream of data,
+     *    instead of piling up waiting promises and possibly running out of memory. See examples/pausing.js.
+     * @param options.resumeFn An optional function that is called when there is room again to accept new waiters on the semaphore.
+     *    This function must be declared if a pauseFn is declared.
+     * @param options.capacity Sets the size of the preallocated waiting list inside the semaphore.
+     *    This is typically used by high performance where the developer can make a rough estimate of the number of concurrent users of a semaphore.
+     * @param options.isReadyFn An optional function that returns a boolean or a promise that resolves to a boolean indicating whether the semaphore is ready to accept new requests.
+     */
+    constructor(maxConcurrency: number | SemaphoreOptions, options?: SemaphoreOptions);
+    initFree(options: SemaphoreOptions): void;
+    tryAcquire(options?: BinarySemaphoreAcquireOptions): Promise<any | undefined> | any | undefined;
+    unlock(token?: any): void;
+    lock(options?: BinarySemaphoreAcquireOptions): any;
+    drain(): Promise<any[]>;
+}
+/**
+ * Creates a rate limiter function that blocks with a promise whenever the rate limit is hit and resolves the promise once the call rate is within the limit set by rps. The second argument is optional.
+ *
+ * @param rps
+ * @param options.timeUnit The `timeUnit` is an optional argument setting the width of the rate limiting window in milliseconds.
+ *    The default `timeUnit` is 1000 ms, therefore making the rps argument act as requests per second limit.
+ * @param options.uniformDistribution  The `uniformDistribution` argument enforces a discrete uniform distribution over time,
+ *    instead of the default that allows hitting the function rps time and then pausing for timeWindow milliseconds. Setting
+ *    the `uniformDistribution` option is mainly useful in a situation where the flow of rate limit function calls is continuous
+ *    and and occuring faster than timeUnit (e.g. reading a file) and not enabling it would cause the maximum number of calls to
+ *    resolve immediately (thus exhaust the limit immediately) and therefore the next bunch calls would need to wait for timeWindow
+ *    milliseconds. However if the flow is sparse then this option may make the code run slower with no advantages.
+ *
+ * Examples:
+ *
+ * ```ts
+ * async function f() {
+ *   const lim = RateLimit(5); // rps
+ *
+ *   for (let i = 0; i < n; i++) {
+ *     await lim();
+ *     // ... do something async
+ *   }
+ * }
+ * ```
+ *
+ *
+ */
+declare function RateLimit(rps: number, { timeUnit, uniformDistribution, }?: {
+    timeUnit?: number;
+    uniformDistribution?: boolean;
+}): () => Promise<void>;
+
+/**
+ * An asynchronous signal gate that blocks operations until a signal is emitted.
+ * This class allows multiple awaiters to wait for a signal and resolves all pending promises with the emitted value.
+ * The gate can be reset to reuse for subsequent signals.
+ *
+ * @example
+ *
+ * ```typescript
+ * // Default type is void, can call signal() without parameters
+ * const gate = new SignalGate();
+ * gate.signal(); // No parameters required
+ *
+ * // Example with explicit type
+ * const valueGate = new SignalGate<number>();
+ * valueGate.signal(42); // Must provide a number value
+ * ```
+ */
+declare class SignalGate<T = void> {
+    protected _isSignaled: boolean;
+    protected _signalValue: T | undefined;
+    protected waitQueue: Array<{
+        resolve: (value: T) => void;
+        reject: (error: any) => void;
+    }>;
+    get signaled(): boolean;
+    /**
+     * Emits the signal with an optional value, resolving all pending {@link wait} promises.
+     * Subsequent calls have no effect until {@link reset} is called.
+     *
+     * @param value The value to emit with the signal (only required if T is not void).
+     */
+    signal(value?: T): void;
+    /**
+     * Resets the gate to its initial state, allowing a new signal to be emitted.
+     */
+    reset(): void;
+    /**
+     * Aborts all pending waits, rejecting their promises with an error.
+     * This does **not** reset the signal state (the gate remains signaled or unsignaled).
+     *
+     * @param reason The reason for aborting the waits.
+     */
+    abort(reason?: any): void;
+    /**
+     * Returns a promise that resolves with the emitted signal value.
+     * If called after the signal has been emitted, resolves immediately with the stored value.
+     *
+     * @returns A promise resolving to the signal value (type T).
+     */
+    wait(): Promise<T>;
+}
+
+declare function findPort(port: string | number, portRetryCount?: number): Promise<number>;
+
+export { BinarySemaphore, type BinarySemaphoreAcquireOptions, type BinarySemaphoreOptions, type BinarySemaphoreReleaseOptions, type BinarySemaphoreReleaserFunc, ConfigFile, DefaultAllTextFiles, DefaultAsyncSemaphoreCapacity, Deque, FilenameReservedRegex, type IncludeFiles, IntSet, type LoadConfigFileOptions, RateLimit, type SanitizeFilenameOptions, Semaphore, type SemaphoreIsReadyFuncType, type SemaphoreOptions, type SemaphoreTaskItem, SignalGate, type StringifyFunc, type TraverseFolderHandler, type TraverseFolderSyncHandler, WindowsReservedNameRegex, arrayHasAll, extNameLevel, filenameReservedRegex, findPort, getMultiLevelExtname, glob, isStringIn, isValidFilename, isValidFilepath, normalizeIncludeFiles, parseFrontMatter, parseYaml, reControlCharsRegex, registerYamlTag, removeLeadingEmptyLines, sanitizeFilename, sanitizeFilepath, sleep, stringifyYaml, toCamelCase, toCapitalCase, toPascalCase, traverseFolder, traverseFolderSync, yieldExec };