@andrew_l/toolkit 0.2.14 → 0.2.16

package/dist/index.d.ts

@@ -253,6 +253,7 @@ declare function shuffle<T>(arr: readonly T[]): T[];
  * @template T The type of elements in the array
  */
 type SortedArrayCompareFn<T> = (a: T, b: T) => number;
+declare const SYM_COMPARE_FN: unique symbol;
 /**
  * A self-sorting array that maintains elements in a sorted order based on a comparison function.
  * All mutating operations preserve the sorted order of elements.
@@ -280,7 +281,7 @@ type SortedArrayCompareFn<T> = (a: T, b: T) => number;
  * @group Array
  */
 declare class SortedArray<T> extends Array<T> {
-    #private;
+    private [SYM_COMPARE_FN];
     /**
      * Creates a new SortedArray instance.
      *
@@ -478,6 +479,201 @@ declare namespace assert {
   export { assert_array as array, assert_arrayNumbers as arrayNumbers, assert_arrayStrings as arrayStrings, assert_boolean as boolean, assert_date as date, assert_equal as equal, assert_fn as fn, assert_greaterThan as greaterThan, assert_lessThan as lessThan, assert_notEmpty as notEmpty, assert_notEmptyString as notEmptyString, assert_number as number, assert_object as object, assert_ok as ok, assert_string as string };
 }
 
+interface BaseX {
+    /**
+     * Base alphabet
+     */
+    alphabet: string;
+    /**
+     * Base padding chars
+     */
+    padding: string;
+    /**
+     * Encodes binary data into a BaseX string representation
+     *
+     * @param input - The binary data to encode
+     * @returns The encoded string
+     */
+    encode(input: Uint8Array): string;
+    /**
+     * Decodes a baseX string back into binary data
+     *
+     * @param input - The encoded string to decode
+     * @returns The decoded binary data
+     * @throws {Error} When the input contains invalid characters or format
+     */
+    decode(input: string): Uint8Array;
+}
+/**
+ * Create custom base alphabet encoding.
+ *
+ * @example
+ * ```typescript
+ * const base16 = basex('0123456789abcdef')
+ * const data = new Uint8Array([255, 255]);
+ * console.log(base16.encode(data));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const base16 = basex('0123456789abcdef')
+ * const encoded = "16FA";
+ * console.log(base16.decode(encoded));
+ * ```
+ *
+ * @group Binary
+ */
+declare function basex(alphabet: string): BaseX;
+
+/**
+ * Base62 encoder/decoder for binary data.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const data = new Uint8Array([255, 128, 64]);
+ * const encoded = base62.encode(data);
+ * console.log(encoded);
+ *
+ * const decoded = base62.decode(encoded);
+ * console.log(decoded); // Uint8Array [255, 128, 64]
+ * ```
+ *
+ * @example Text encoding
+ * ```typescript
+ * const text = "Hello World!";
+ * const bytes = new TextEncoder().encode(text);
+ * const encoded = base62.encode(bytes);
+ * const decoded = base62.decode(encoded);
+ * const result = new TextDecoder().decode(decoded);
+ * console.log(result); // "Hello World!"
+ * ```
+ *
+ * @group Binary
+ */
+declare const base62: BaseX;
+
+/**
+ * Base62-like encoder/decoder for binary data but **super fast**. Useful for human readable tokens generation
+ *
+ * **Warning!** Not RFC standard
+ *
+ * @example Basic usage
+ * ```typescript
+ * const data = new Uint8Array([255, 128, 64]);
+ * const encoded = base62.encode(data);
+ * console.log(encoded);
+ *
+ * const decoded = base62.decode(encoded);
+ * console.log(decoded); // Uint8Array [255, 128, 64]
+ * ```
+ *
+ * @example Text encoding
+ * ```typescript
+ * const text = "Hello World!";
+ * const bytes = new TextEncoder().encode(text);
+ * const encoded = base62.encode(bytes);
+ * const decoded = base62.decode(encoded);
+ * const result = new TextDecoder().decode(decoded);
+ * console.log(result); // "Hello World!"
+ * ```
+ *
+ * @group Binary
+ */
+declare const base62Fast: BaseX;
+
+declare class Base64Encoding implements BaseX {
+    alphabet: string;
+    padding: string;
+    private decodeMap;
+    constructor(alphabet: string, options?: {
+        padding?: string;
+    });
+    /**
+     * Encodes binary data into a base64 string representation
+     *
+     * @param input - The binary data to encode
+     * @returns The encoded string
+     *
+     * @example
+     * ```typescript
+     * const data = new Uint8Array([255, 255]);
+     * console.log(base64.encode(data));
+     * ```
+     */
+    encode(data: Uint8Array, options?: {
+        includePadding?: boolean;
+    }): string;
+    /**
+     * Decodes a base64 string back into binary data
+     *
+     * @param input - The encoded string to decode
+     * @returns The decoded binary data
+     * @throws {Error} When the input contains invalid characters or format
+     *
+     * @example
+     * ```typescript
+     * const encoded = "AA==";
+     * console.log(base64.decode(encoded)); // Uint8Array [255, 255]
+     * ```
+     */
+    decode(data: string, options?: {
+        strict?: boolean;
+    }): Uint8Array;
+}
+
+/**
+ * Base64 encoder/decoder for binary data
+ *
+ * @example Basic usage
+ * ```typescript
+ * const data = new Uint8Array([255, 128, 64]);
+ * const encoded = base64.encode(data);
+ * console.log(encoded);
+ *
+ * const decoded = base64.decode(encoded);
+ * console.log(decoded); // Uint8Array [255, 128, 64]
+ * ```
+ *
+ * @example Text encoding
+ * ```typescript
+ * const text = "Hello World!";
+ * const bytes = new TextEncoder().encode(text);
+ * const encoded = base64.encode(bytes);
+ * const decoded = base64.decode(encoded);
+ * const result = new TextDecoder().decode(decoded);
+ * console.log(result); // "Hello World!"
+ * ```
+ *
+ * @group Binary
+ */
+declare const base64: Base64Encoding;
+/**
+ * Base64 encoder/decoder for binary data
+ *
+ * @example Basic usage
+ * ```typescript
+ * const data = new Uint8Array([255, 128, 64]);
+ * const encoded = base64url.encode(data);
+ * console.log(encoded);
+ *
+ * const decoded = base64url.decode(encoded);
+ * console.log(decoded); // Uint8Array [255, 128, 64]
+ * ```
+ *
+ * @example Text encoding
+ * ```typescript
+ * const text = "Hello World!";
+ * const bytes = new TextEncoder().encode(text);
+ * const encoded = base64url.encode(bytes);
+ * const decoded = base64url.decode(encoded);
+ * const result = new TextDecoder().decode(decoded);
+ * console.log(result); // "Hello World!"
+ * ```
+ *
+ * @group Binary
+ */
+declare const base64url: Base64Encoding;
+
 type Base64ToBytesOptions = {
     /**
      * Encoding type
@@ -4660,7 +4856,216 @@ declare class SimpleEventEmitter<T extends SimpleEventMap<T> = SimpleDefaultEven
     on<K>(eventName: Key<K, T>, listener: Listener1<K, T>): this;
     once<K>(eventName: Key<K, T>, listener: Listener1<K, T>): this;
     off<K>(eventName: Key<K, T>, listener: Listener1<K, T>): this;
-    removeAllListeners(eventName?: Key<unknown, T>): this;
+    removeAllListeners<K>(eventName?: Key<K, T>): this;
+}
+
+/**
+ * Configuration options for creating a ResourcePool instance.
+ * @template T The type of resource being pooled
+ */
+interface ResourcePoolOptions<T = unknown> {
+    /** Maximum number of resources that can exist in the pool */
+    poolSize: number;
+    /**
+     * Whether to automatically create resources when needed, up to poolSize limit.
+     * If false, resources must be pre-created or acquired requests will queue.
+     * @default false
+     */
+    auto?: boolean;
+    /** Factory function to create new resources */
+    createResource: () => Awaitable<T>;
+    /** Optional cleanup function called when destroying resources */
+    destroyResource?: (resource: T) => Awaitable<void>;
+}
+type ResourcePoolEventMap = {
+    error: [error: Error];
+};
+/**
+ * A generic resource pool that manages the lifecycle of expensive resources.
+ *
+ * ResourcePool provides a way to:
+ * - Limit the number of concurrent resources (e.g., database connections, file handles)
+ * - Reuse resources to avoid creation/destruction overhead
+ * - Queue requests when all resources are in use
+ * - Automatically create resources on demand (when auto mode is enabled)
+ * - Gracefully handle resource cleanup and pool destruction
+ *
+ * @template T The type of resource being pooled
+ *
+ * @example
+ * ```typescript
+ * // Database connection pool
+ * const dbPool = new ResourcePool({
+ *   poolSize: 10,
+ *   auto: true,
+ *   createResource: () => createDatabaseConnection(),
+ *   destroyResource: (conn) => conn.close()
+ * });
+ *
+ * // Acquire and use a connection
+ * const conn = await dbPool.acquire();
+ * try {
+ *   const result = await conn.query('SELECT * FROM users');
+ *   return result;
+ * } finally {
+ *   dbPool.release(conn);
+ * }
+ * ```
+ *
+ * @group Promise
+ */
+declare class ResourcePool<T = unknown> extends SimpleEventEmitter<ResourcePoolEventMap> {
+    private readonly poolSize;
+    private readonly auto;
+    private readonly createResource;
+    private readonly destroyResource?;
+    private readonly state;
+    /**
+     * Creates a new ResourcePool instance.
+     *
+     * @param options Configuration options for the pool
+     *
+     * @example
+     * ```typescript
+     * const pool = new ResourcePool({
+     *   poolSize: 5,
+     *   auto: true,
+     *   createResource: async () => new DatabaseConnection(),
+     *   destroyResource: async (conn) => conn.close()
+     * });
+     * ```
+     */
+    constructor({ poolSize, auto, createResource, destroyResource, }: ResourcePoolOptions<T>);
+    /**
+     * Whether the pool is idle (no resources currently in use).
+     * Useful for determining if it's safe to destroy the pool.
+     */
+    get isIdle(): boolean;
+    /** Number of resources currently available for acquisition */
+    get availableCount(): number;
+    /** Number of resources currently in use */
+    get usedCount(): number;
+    /** Maximum number of resources this pool can manage */
+    get size(): number;
+    /**
+     * Acquires a resource from the pool.
+     *
+     * This method will:
+     * 1. Return an available resource immediately if one exists
+     * 2. Create a new resource if auto mode is enabled and under the pool limit
+     * 3. Queue the request and wait if no resources are available
+     *
+     * @returns Promise that resolves to an acquired resource
+     * @throws Error if the pool is destroyed while waiting (when rejectAcquires is true)
+     *
+     * @example
+     * ```typescript
+     * const resource = await pool.acquire();
+     * try {
+     *   // Use the resource
+     *   await resource.doSomething();
+     * } finally {
+     *   pool.release(resource); // Always release in finally block
+     * }
+     * ```
+     */
+    acquire(): Promise<T>;
+    /**
+     * Returns a resource to the pool, making it available for reuse.
+     *
+     * The resource will be made available to the next queued acquisition request,
+     * or returned to the available pool if no requests are pending.
+     *
+     * @param resource The resource to return to the pool
+     *
+     * @example
+     * ```typescript
+     * const resource = await pool.acquire();
+     * try {
+     *   // Use resource...
+     * } finally {
+     *   pool.release(resource); // Always release when done
+     * }
+     * ```
+     *
+     * @remarks
+     * - Safe to call multiple times with the same resource (idempotent)
+     * - Only resources that were acquired from this pool should be released
+     * - Triggers drain completion if this was the last resource in use
+     */
+    release(resource: T): void;
+    /**
+     * Manually add a resource to the pool.
+     *
+     * @param resource The resource to return to the pool
+     *
+     * @throws Error if resource already exists in the pool.
+     * @throws Error if size reached.
+     */
+    add(resource: T): void;
+    /**
+     * Waits for all currently acquired resources to be released.
+     *
+     * This is useful for graceful shutdown scenarios where you want to ensure
+     * all work is completed before destroying the pool.
+     *
+     * @returns Promise that resolves when all resources are returned to the pool
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * console.log('Waiting for all connections to be released...');
+     * await pool.drain();
+     * console.log('All connections released, safe to destroy pool');
+     * await pool.destroy();
+     * ```
+     *
+     * @remarks
+     * - Resolves immediately if no resources are currently in use
+     * - Multiple drain calls can be made concurrently; they will all resolve together
+     * - Does not prevent new acquisitions; use destroy() to prevent new usage
+     */
+    drain(): Promise<void>;
+    /**
+     * Destroys the pool and all its resources.
+     *
+     * This method will:
+     * 1. Wait for all resources to be released (drain)
+     * 2. Optionally reject any pending acquisition requests
+     * 3. Call destroyResource() on all available resources
+     * 4. Clean up internal state
+     *
+     * @param rejectAcquires Whether to reject pending acquire() requests with an error
+     *                       If false, pending requests will remain queued indefinitely
+     * @returns Promise that resolves when destruction is complete
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown - let pending requests complete
+     * await pool.destroy(false);
+     *
+     * // Immediate shutdown - reject pending requests
+     * await pool.destroy(true);
+     * ```
+     *
+     * @remarks
+     * - Safe to call multiple times; subsequent calls will wait for the first to complete
+     * - The pool cannot be used after destruction
+     * - Resources currently in use will not be force-destroyed; drain() is called first
+     * - If destroyResource was not provided, resources are simply discarded
+     */
+    destroy(rejectAcquires?: boolean): Promise<void>;
+    private tryGetAvailableResource;
+    private tryCreateAutoResource;
+    private enqueueAcquireRequest;
+    private moveResourceToAvailable;
+    private processNextAcquireRequest;
+    private checkForDrainCompletion;
+    private enqueueDestroyRequest;
+    private rejectPendingAcquires;
+    private destroyAllResources;
+    private resetState;
+    private resolveDestroyQueue;
 }
 
 /**
@@ -5233,4 +5638,4 @@ declare function wrapText(value: string, maxLength?: number): string;
  */
 declare function toError<T>(value: T, unknownMessage?: string): T extends Error ? T : Error;
 
-export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSON as EJSONInstance, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EJSONType, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, SortedArray, type SortedArrayCompareFn, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, avgCircular, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };
+export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, type BaseX, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSON as EJSONInstance, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EJSONType, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, ResourcePool, type ResourcePoolEventMap, type ResourcePoolOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, SortedArray, type SortedArrayCompareFn, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, avgCircular, base62, base62Fast, base64, base64ToBytes, base64url, basex, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };