@andrew_l/toolkit 0.3.5 → 0.3.7

package/dist/index.d.ts

@@ -466,6 +466,33 @@ 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 };
 }
 
+/**
+ * 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;
+
 interface BaseX {
     /**
      * Base alphabet
@@ -512,33 +539,6 @@ interface BaseX {
  */
 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
  *
@@ -670,6 +670,11 @@ type Base64ToBytesOptions = {
      * Whether to enforce strict Base64 decoding.
      */
     strict?: boolean;
+    /**
+     * Prefer to use native `Uint8Array.fromBase64` and `Uint8Array.fromBase64` when possible
+     * @default true
+     */
+    native?: boolean;
 };
 /**
  * Decodes a Base64 or Base64URL encoded string into a `Uint8Array`.
@@ -700,7 +705,7 @@ type Base64ToBytesOptions = {
  *
  * @group Binary
  */
-declare function base64ToBytes(data: string, { encoding, strict }?: Base64ToBytesOptions): Uint8Array;
+declare function base64ToBytes(data: string, { encoding, strict, native }?: Base64ToBytesOptions): Uint8Array;
 
 /**
  * Converts a `bigint` value into a byte array (`Uint8Array`) in big-endian order.
@@ -947,7 +952,7 @@ interface Logger {
   error: (...args: unknown[]) => void;
   debug: (...args: unknown[]) => void;
   log: (...args: unknown[]) => void;
-  extend: (...args: unknown[]) => void;
+  extend: (...args: unknown[]) => Logger;
 }
 
 declare namespace BitPack {
@@ -992,6 +997,31 @@ type Plan = {
     value?: unknown;
     child?: Plan;
 };
+/**
+ * Define compact packed structure
+ * @group Binary
+ *
+ * @example
+ * ```typescript
+ * const snowflake = bitPack({
+ *   totalBits: 64,
+ *   fields: [
+ *     { name: 'timestamp', bits: 42, take: 'low' },
+ *     { name: 'workerId', bits: 5, take: 'low' },
+ *     { name: 'processId', bits: 5, take: 'low' },
+ *     { name: 'increment', bits: 12, take: 'low' },
+ *   ],
+ *   optimize: true,
+ * });
+ *
+ * const userId = snowflake.bigint({
+ *   timestamp: 1781295314562,
+ *   workerId: 1,
+ *   processId: 0,
+ *   increment: 0
+ * }); // 7471294063048785920n
+ * ```
+ */
 declare function bitPack<const TFields extends BitPack.Field[], TFieldNames extends string = BitPack.ExtractFieldNames<TFields>>(options: BitPack.Options<TFields>): BitPack.API<TFieldNames>;
 
 declare namespace BitUnpack {
@@ -1024,6 +1054,27 @@ declare namespace BitUnpack {
         [P in T]: number;
     };
 }
+/**
+ * Define compact unpacked structure
+ * @group Binary
+ *
+ * @example
+ * ```typescript
+ * const snowflake = bitUnpack({
+ *   totalBits: 64,
+ *   fields: [
+ *     { name: 'timestamp', bits: 42, take: 'low' },
+ *     { name: 'workerId', bits: 5, take: 'low' },
+ *     { name: 'processId', bits: 5, take: 'low' },
+ *     { name: 'increment', bits: 12, take: 'low' },
+ *   ],
+ * });
+ *
+ * console.log(
+ *   snowflake.bigint(7471294063048785920n)
+ * ); // { timestamp: 1781295314562, workerId: 1, processId: 0, increment: 0 }
+ * ```
+ */
 declare function bitUnpack<const TFields extends BitUnpack.Field[], TFieldNames extends string = BitUnpack.ExtractFieldNames<TFields>>(options: BitUnpack.Options<TFields>): BitUnpack.API<TFieldNames>;
 
 type BytesToBase64Options = {
@@ -1035,6 +1086,11 @@ type BytesToBase64Options = {
      * Whether or not to include padding (`=`) in the encoded result. Defaults to `true` for Base64, `false` for Base64URL.
      */
     padding?: boolean;
+    /**
+     * Prefer to use native `Uint8Array.toBase64` and `Uint8Array.toBase64` when possible
+     * @default true
+     */
+    native?: boolean;
 };
 /**
  * Encodes a byte array (`Uint8Array`) into a Base64 or Base64URL encoded string.
@@ -1074,7 +1130,7 @@ type BytesToBase64Options = {
  *
  * @group Binary
  */
-declare function bytesToBase64(data: Uint8Array, { encoding, padding }?: BytesToBase64Options): string;
+declare function bytesToBase64(data: Uint8Array, { encoding, padding, native }?: BytesToBase64Options): string;
 
 /**
  * Compares two `Uint8Array` instances to check if their contents are identical.
@@ -1151,6 +1207,32 @@ declare function compareBytes(a: Uint8Array, b: Uint8Array): boolean;
  */
 declare function concatenateBytes(a: Uint8Array, b: Uint8Array): Uint8Array;
 
+/**
+ * Decode a run-length encoded buffer.
+ *
+ * Decodes `[value, count]` pairs back into runs of `value`.
+ * All other bytes pass through unchanged.
+ *
+ * @param buf - RLE-encoded buffer to decode
+ * @param value - Byte value that was compressed (default: 0)
+ * @returns Decoded buffer
+ * @group Binary
+ */
+declare function rleDecode(buf: Uint8Array, value?: number): Uint8Array;
+
+/**
+ * Run-length encode a buffer, compressing runs of a specific byte value.
+ *
+ * Runs of `value` are encoded as [value, count] pairs (count ≤ 255).
+ * All other bytes pass through unchanged.
+ *
+ * @param buf - Input buffer to encode
+ * @param value - Byte value to compress runs of (default: 0)
+ * @returns RLE-encoded buffer
+ * @group Binary
+ */
+declare function rleEncode(buf: Uint8Array, value?: number): Uint8Array;
+
 /**
  * Converts a `Uint16Array` into a `Uint8Array`.
  *
@@ -2904,10 +2986,9 @@ declare class AppError extends Error {
 }
 
 /**
- * Same as `AssertionError` but for browser env.
  * @group Errors
  */
-declare class BrowserAssertionError extends Error {
+declare class AssertionError extends Error {
     /**
      * Set to the `actual` argument for methods such as {@link assert.strictEqual()}.
      */
@@ -3462,7 +3543,12 @@ type LogLevel = Exclude<keyof Logger, 'extend'>;
  * Set global log level.
  * @group Utility Functions
  */
-declare const loggerSetLevel: (level: LogLevel) => void;
+declare const setLoggerLevel: (level: LogLevel) => void;
+/**
+ * Set global log level.
+ * @group Utility Functions
+ */
+declare const getLoggerLevel: () => LogLevel;
 /**
  * Create pretty simple `console.log` wrapper interface.
  *
@@ -5174,6 +5260,78 @@ declare class ResourcePool<T = unknown> extends SimpleEventEmitter<ResourcePoolE
     private resolveDestroyQueue;
 }
 
+declare const SCHEDULER_JOB_FLAGS: {
+    readonly QUEUED: number;
+    readonly ALLOW_RECURSE: number;
+    readonly DISPOSED: number;
+};
+/**
+ * Creates a microtask scheduler that batches jobs and flushes them in
+ * priority order on the next tick.
+ *
+ * Jobs are functions queued via {@link Scheduler.queueJob}. Each job may carry
+ * an optional numeric `id` used to order the queue — lower `id` runs first,
+ * and jobs without an `id` run last. Re-queueing the same job within an
+ * active flush cycle is a no-op unless `SCHEDULER_JOB_FLAGS.ALLOW_RECURSE`
+ * is set on the job. Use {@link Scheduler.queueJobWait} when you need to
+ * await a job's result through a {@link CancellablePromise}, and the
+ * `onJob` / `onJobStart` / `onJobComplete` hooks to observe lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const scheduler = createScheduler();
+ *
+ * const log = (msg: string) => () => console.log(msg);
+ *
+ * const first = log('first');
+ * first.id = 1;
+ * const second = log('second');
+ * second.id = 2;
+ *
+ * scheduler.queueJob(second);
+ * scheduler.queueJob(first);
+ *
+ * scheduler.nextTick().then(() => console.log('flushed'));
+ * // → first
+ * // → second
+ * // → flushed
+ * ```
+ *
+ * @group Promise
+ */
+declare function createScheduler(): Scheduler;
+declare namespace Scheduler {
+    type Job<T = any> = (() => T) & JobOptions;
+    type JobOptions = {
+        id?: number;
+        /**
+         * flags can technically be undefined, but it can still be used in bitwise
+         * operations just like 0.
+         */
+        flags?: number;
+        jobName?: string;
+    };
+}
+declare class Scheduler {
+    protected queue: Scheduler.Job[];
+    protected flushIndex: number;
+    protected resolvedPromise: Promise<any>;
+    protected currentFlushPromise: Promise<void> | null;
+    protected onJobCbs: ((job: Scheduler.JobOptions) => void)[];
+    protected onJobStartCbs: ((job: Scheduler.JobOptions) => void)[];
+    protected onJobCompleteCbs: ((job: Scheduler.JobOptions) => void)[];
+    constructor();
+    onJob(fn: (job: Scheduler.JobOptions) => void): void;
+    onJobStart(fn: (job: Scheduler.JobOptions) => void): void;
+    onJobComplete(fn: (job: Scheduler.JobOptions) => void): void;
+    nextTick(fn?: () => void): Promise<void>;
+    queueJob<T>(job: Scheduler.Job<T>, opts?: Scheduler.JobOptions): void;
+    queueJobWait<T>(job: Scheduler.Job<T>, opts?: Scheduler.JobOptions): CancellablePromise<Awaited<T>>;
+    protected findInsertionIndex(id: number): number;
+    protected flushJobs(): Promise<void>;
+    protected queueFlush(): void;
+}
+
 /**
  * Throws an error if the provided promise or callback is not resolved within the specified timeout period.
  *
@@ -5823,4 +5981,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, type BaseX, BitPack, BitUnpack, 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, 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 SecureCustomizerOptions, 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 WithCode, 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, bitPack, bitUnpack, 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, createFunction, 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, intersectionBy, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNode, 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, textDecoder, textEncoder, 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, withResolve, wrapText };
+export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AssertionError, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, type BaseX, BitPack, BitUnpack, 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, Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type LogLevel, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, ResourcePool, type ResourcePoolEventMap, type ResourcePoolOptions, type RetryOnErrorConfig, SCHEDULER_JOB_FLAGS, Scheduler, type SecureCustomizerOptions, 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 WithCode, 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, bitPack, bitUnpack, 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, createFunction, createRandomizer, createScheduler, 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, getLoggerLevel, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, intersectionBy, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNode, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, rleDecode, rleEncode, round2digits, secondsToHm, set, setLoggerLevel, shuffle, snakeCase, sprintf, startCase, strAssign, sum, textDecoder, textEncoder, 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, withResolve, wrapText };