@tally.paws/toolbox 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,368 @@
+interface DebouncedFunction<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): void;
+    cancel: () => void;
+    flush: () => void;
+}
+/**
+ * Debounces a function to prevent excessive calling.
+ * @param fn The function to debounce.
+ * @param delay The number of milliseconds to wait after the last call before calling the function again.
+ * @param options Immediate: If True, it will call the function immediately if more than the delay milliseconds since last call has passed. Any further calls within delay milliseconds will be debounced.
+ * @returns The Debounced function.
+ */
+declare function debounce<T extends (...args: any[]) => any>(fn: T, delay?: number, options?: {
+    immediate?: boolean;
+}): DebouncedFunction<T>;
+/**
+ * Throttles a function to only run once for every interval of time.
+ * @param fn The function to throttle.
+ * @param interval Minimum amount of milliseconds betweeen function calls.
+ * @returns The throttled function.
+ */
+declare function throttle<F extends (this: any, ...args: any[]) => void>(fn: F, interval?: number): (this: ThisParameterType<F>, ...args: Parameters<F>) => void;
+/**
+ * Compares values recursively.
+ * @param a First object or primitive.
+ * @param b Second object or primitive.
+ * @returns If both objects are equal or not.
+ */
+declare function deepEqual(a: any, b: any): boolean;
+/**
+ * Only allows a function to be called once. If called more than once, the stored result is returned.
+ * @param fn Function to limit.
+ * @returns The stored result of the function.
+ */
+declare function once<F extends (this: any, ...args: any[]) => any>(fn: F): (this: ThisParameterType<F>, ...args: Parameters<F>) => ReturnType<F>;
+/**
+ * Picks certain keys from an object.
+ * @param obj The object to pick keys from.
+ * @param keys The keys to pick from the object.
+ * @returns An object with only the specified keys.
+ */
+declare function pick<T, K extends readonly (keyof T)[]>(obj: T, keys: K): Pick<T, K[number]>;
+/**
+ * Excludes certain keys from an object.
+ * @param obj The object to exclude keys from.
+ * @param keys The keys to exclude.
+ * @returns An object with the specified keys excluded.
+ */
+declare function omit<T extends Record<string, any>, K extends readonly (keyof T)[]>(obj: T, keys: K): Omit<T, K[number]>;
+/**
+ * Retries an async function an amount of times with optional delay.
+ * @param fn The function to retry.
+ * @param attempts Number of attempts to run.
+ * @param delayMs Optional number of milliseconds to wait between tries.
+ * @returns Result of the function.
+ */
+declare function retry<T>(fn: () => Promise<T>, attempts: number, delayMs?: number): Promise<T>;
+/**
+ * no operation (like in assembly code)
+ */
+declare const noop: () => void;
+/**
+ * Executes a function and catches any errors and returns a tuple, similar to GoLang.
+ * @param fn The function to execute.
+ * @returns A tuple where:
+ *   - The first element is the error if one was thrown, otherwise `null`.
+ *   - The second element is the return value of `fn` if no error occurred.
+ * @example
+ * ```ts
+ * const [err, value] = tryCatch(() => JSON.parse('{"x":1}'));
+ * if (err) {
+ *   console.error("uh oh", err);
+ * } else {
+ *   console.log("value:", value);
+ * }
+ * ```
+ */
+declare function tryCatch<T>(fn: () => T): [error: unknown] | [error: null, value: T];
+/**
+ * A function to tap into a value.
+ * @param fn A function that takes a value.
+ * @returns The value passed into the function `fn`.
+ * @example
+ * ```ts
+ * const double = (x: number) => x * 2;
+ *
+ * const result = [1, 2, 3]
+ *   .map(tap(x => console.log("before doubling:", x)))
+ *   .map(double);
+ *
+ * console.log(result);
+ * ```
+ */
+declare function tap<T>(fn: (v: T) => void): (v: T) => T;
+/**
+ * A generator for creating number ranges.
+ * @param end An end value (exclusive) starting at 0 or an object with start, step and end values.
+ * start: The value to start at (inclusive).
+ * step: How far to increment in each iteration, can be negative, defaults to 1.
+ * end: The value to end at (exclusive).
+ * @example
+ * ```ts
+ * for (const i of range(5)) {
+ *   console.log(i) //0, 1, 2, 3, 4
+ * }
+ *
+ * for (const i of range({
+ *   start: 3,
+ *   end: 10,
+ *   step: 2
+ * })) {
+ *   console.log(i) //3, 5, 7, 9
+ * }
+ *
+ * for (const i of range({
+ *   start: 10,
+ *   end: 3,
+ *   step: -2
+ * })) {
+ *   console.log(i) //10, 8, 6, 4
+ * }
+ * ```
+ */
+declare function range(end: number | {
+    start?: number;
+    end: number;
+    step?: number;
+}): Generator<number>;
+/**
+ * Creates a generator that loops through an iterator indefinitely.
+ * @param iterable The iterator to loop over.
+ * @returns A looping generator using the iterator specified.
+ */
+declare function cycle<T>(iterable: Iterable<T>): Generator<T>;
+/**
+ * Breaks an array into chunks.
+ * @param arr The array to chunk.
+ * @param size Chunk size. (up to this value)
+ * @returns The chunked array.
+ */
+declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * Shuffles an array.
+ * @param arr Array to shuffle.
+ * @returns Shuffled array.
+ */
+declare function shuffle<T>(arr: T[]): T[];
+/**
+ * Picks a random element from an array.
+ * @param arr Array to select from.
+ * @returns A random element from the specified array.
+ */
+declare function sample<T>(arr: T[]): T | undefined;
+/**
+ * Safely shifts an array by an amount.
+ * @param arr The array to rotate.
+ * @param n How much to shift by, and which way to shift; Positive ->, Negative <-.
+ * @returns Shifted (Rotated) array.
+ */
+declare function rotate<T>(arr: T[], n: number): T[];
+
+/**
+ * Returns a promise that resolves in a certain amount of milliseconds.
+ * Note: this won't be 100% accurate.
+ * @param ms The number of milliseconds to wait.
+ * @returns The promise.
+ */
+declare function sleep(ms: number): Promise<void>;
+declare class AsyncQueue {
+    private queue;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Creates a deferred promise.
+ *
+ * Useful when the promise must be resolved or rejected from outside its executor.
+ *
+ * @returns An object containing:
+ *  - `promise`: Promise<unknown>
+ *  - `resolve`: (value: unknown) => void
+ *  - `reject`: (reason?: any) => void
+ *
+ * @example
+ * const { promise, resolve, reject } = deferred();
+ * // `resolve('ok')` or `reject(new Error('fail'))` can be called later.
+ */
+declare function deferred(): {
+    promise: Promise<unknown>;
+    resolve: (value: unknown) => void;
+    reject: (reason?: any) => void;
+};
+/**
+ * Limits a promise's waiting time with a timeout.
+ * @param promise The promise to time.
+ * @param ms How many milliseconds to wait before timing out.
+ * @param error The error to throw after the set delay.
+ * @returns The timed out promise.
+ */
+declare function timeoutPromise<T>(promise: Promise<T>, ms: number, error?: Error): Promise<unknown>;
+
+type ValueOf<T> = T[keyof T];
+type Entries<T> = {
+    [K in keyof T]: [K, T[K]];
+}[keyof T][];
+type Mutable<T> = {
+    -readonly [K in keyof T]: T[K];
+};
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+type DeepRequired<T> = {
+    [K in keyof T]-?: T[K] extends object ? DeepRequired<T[K]> : T[K];
+};
+type Nullable<T> = T | null | undefined;
+type NonNullable<T> = T extends null | undefined ? never : T;
+type TupleOf<T, N extends number, R extends T[] = []> = R["length"] extends N ? R : TupleOf<T, N, [T, ...R]>;
+type Merge<A, B> = Omit<A, keyof B> & B;
+type Flat<T> = {
+    [K in keyof T]: T[K];
+};
+
+type DurationBuilderLongBase = {
+    toMilliseconds(): number;
+    toSeconds(): number;
+    toMinutes(): number;
+    toHours(): number;
+    toDays(): number;
+};
+type DurationBuilderShortBase = {
+    toMs(): number;
+    toS(): number;
+    toM(): number;
+    toH(): number;
+    toD(): number;
+};
+type LongValues = {
+    milliseconds(v: number): DurationBuilderLong;
+    seconds(v: number): DurationBuilderLong;
+    minutes(v: number): DurationBuilderLong;
+    hours(v: number): DurationBuilderLong;
+    days(v: number): DurationBuilderLong;
+};
+type DurationBuilderLong = Flat<DurationBuilderLongBase & LongValues>;
+type ShortValues = {
+    ms(v: number): DurationBuilderShort;
+    s(v: number): DurationBuilderShort;
+    m(v: number): DurationBuilderShort;
+    h(v: number): DurationBuilderShort;
+    d(v: number): DurationBuilderShort;
+};
+type DurationBuilderShort = Flat<DurationBuilderShortBase & ShortValues>;
+declare const days: (v: number) => Flat<DurationBuilderLongBase & LongValues>;
+declare const hours: (v: number) => Flat<DurationBuilderLongBase & LongValues>;
+declare const minutes: (v: number) => Flat<DurationBuilderLongBase & LongValues>;
+declare const seconds: (v: number) => Flat<DurationBuilderLongBase & LongValues>;
+declare const milliseconds: (v: number) => Flat<DurationBuilderLongBase & LongValues>;
+declare const d: (v: number) => Flat<DurationBuilderShortBase & ShortValues>;
+declare const h: (v: number) => Flat<DurationBuilderShortBase & ShortValues>;
+declare const m: (v: number) => Flat<DurationBuilderShortBase & ShortValues>;
+declare const s: (v: number) => Flat<DurationBuilderShortBase & ShortValues>;
+declare const ms: (v: number) => Flat<DurationBuilderShortBase & ShortValues>;
+
+/**
+ * BigInt Exponent Operation.
+ * @param one The base.
+ * @param two The exponent.
+ * @returns The bigint result of `one` to the power of `two`.
+ */
+declare function bigIntPower(one: bigint, two: bigint): bigint;
+/**
+ * Converts numbers between bases. (e.g. hexadecimal to binary)
+ * @param value The value to convert.
+ * @param sourceBase The base of value.
+ * @param outBase The result's base.
+ * @param chars The characters to use, defaults to `convertBase.defaultChars`.
+ * @returns The resulting value in specified base using the specified characters.
+ */
+declare function convertBase(value: string, sourceBase: number, outBase: number, chars?: string): string;
+declare namespace convertBase {
+    var defaultChars: string;
+    var MAX_BASE: number;
+}
+/**
+ * Clamps a number between min and max.
+ * @param number The number to clamp.
+ * @param min The minimum number.
+ * @param max The maximum number.
+ * @returns The number clamped to the range specified.
+ */
+declare function clamp(number: number, min: number, max: number): number;
+/**
+ * Returns a random integer between min and max
+ * @param min The minimum number.
+ * @param max The maximum number. Exclusive by default, like Java's `Math.Random()`.
+ * @param inclusive Determines whether the `max` is included or excluded from the range.
+ * @returns A random number within the range specified.
+ */
+declare function randInt(min: number, max: number, inclusive?: boolean): number;
+/**
+ * Returns true approximately (probablity * 100)% of the time
+ * @param probability Number between 0 and 1.
+ * @returns A boolean averaging the probability specified.
+ */
+declare function chance(probability: number): boolean;
+/**
+ * Rounds a number to a certain number of decimals.
+ * @param n The number to round.
+ * @param decimals The number of places.
+ * @returns Number rounded to specified places.
+ * @example
+ * ```ts
+ * console.log(roundTo(Math.PI, 5));
+ * ```
+ * shows as `3.14159` in the console.
+ */
+declare function roundTo(n: number, decimals: number): number;
+/**
+ * Interpolates between a and b.
+ * @param a
+ * @param b
+ * @param t
+ * @returns
+ */
+declare function lerp(a: number, b: number, t: number): number;
+/**
+ * Determines if a value is in a range.
+ * @param n The number to check for in a range.
+ * @param min The minimum of the range.
+ * @param max The maximum of the range.
+ * @returns If the number is in the specified range.
+ */
+declare function inRange(n: number, min: number, max: number): boolean;
+
+/**
+ * A map with time-limited keys.
+ * Keys are deleted after a set amount of time.
+ */
+declare class TimedMap<K, V> {
+    private defaultTtlMs?;
+    private map;
+    private timers;
+    constructor(defaultTtlMs?: number | undefined);
+    set(key: K, value: V, ttlMs?: number | undefined): void;
+    has(key: K): boolean;
+    clear(): void;
+    get(key: K): V | undefined;
+    delete(key: K): boolean;
+    get size(): number;
+}
+/**
+ * A map with access based expiration.
+ * Keys are deleted after a set amount of time without access.
+ */
+declare class AccessMap<K, V> {
+    private defaultTtlMs?;
+    private map;
+    private timers;
+    constructor(defaultTtlMs?: number | undefined);
+    set(key: K, value: V, ttlMs?: number | undefined): void;
+    has(key: K): boolean;
+    clear(): void;
+    get(key: K): V | undefined;
+    delete(key: K): boolean;
+    get size(): number;
+    private resetTimer;
+}
+
+export { AccessMap, AsyncQueue, type DebouncedFunction, type DeepPartial, type DeepRequired, type Entries, type Flat, type Merge, type Mutable, type NonNullable, type Nullable, TimedMap, type TupleOf, type ValueOf, bigIntPower, chance, chunk, clamp, convertBase, cycle, d, days, debounce, deepEqual, deferred, h, hours, inRange, lerp, m, milliseconds, minutes, ms, noop, omit, once, pick, randInt, range, retry, rotate, roundTo, s, sample, seconds, shuffle, sleep, tap, throttle, timeoutPromise, tryCatch };