@thetally/toolbox 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,129 @@
+interface DebouncedFunction<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): void;
+    cancel: () => void;
+    flush: () => void;
+}
+declare function debounce<T extends (...args: any[]) => any>(fn: T, delay?: number, options?: {
+    immediate?: boolean;
+}): DebouncedFunction<T>;
+declare function throttle<F extends (this: any, ...args: any[]) => void>(fn: F, interval?: number): (this: ThisParameterType<F>, ...args: Parameters<F>) => void;
+declare function deepEqual(a: any, b: any): boolean;
+declare function once<F extends (this: any, ...args: any[]) => any>(fn: F): (this: ThisParameterType<F>, ...args: Parameters<F>) => ReturnType<F>;
+declare function pick<T, K extends readonly (keyof T)[]>(obj: T, keys: K): Pick<T, K[number]>;
+declare function omit<T extends Record<string, any>, K extends readonly (keyof T)[]>(obj: T, keys: K): Omit<T, K[number]>;
+declare function retry<T>(fn: () => Promise<T>, attempts: number, delayMs?: number): Promise<T>;
+declare const noop: () => void;
+declare function tryCatch<T>(fn: () => T): [error: unknown, value?: T];
+declare function tap<T>(fn: (v: T) => void): (v: T) => T;
+declare function range(end: number | {
+    start?: number;
+    end: number;
+    step?: number;
+}): Generator<number>;
+declare function cycle<T>(iterable: Iterable<T>): Generator<T>;
+declare function chunk<T>(arr: T[], size: number): T[][];
+declare function shuffle<T>(arr: T[]): T[];
+declare function sample<T>(arr: T[]): T | undefined;
+declare function rotate<T>(arr: T[], n: number): T[];
+
+declare function sleep(ms: number): Promise<void>;
+declare class AsyncQueue {
+    private queue;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+declare function deferred(): {
+    promise: Promise<unknown>;
+    resolve: (value: unknown) => void;
+    reject: (reason?: any) => void;
+};
+declare function timeoutPromise<T>(promise: Promise<T>, ms: number, error?: Error): Promise<unknown>;
+
+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>;
+
+declare function bigIntPower(one: bigint, two: bigint): bigint;
+declare function convertBase(value: string, sourceBase: number, outBase: number, chars?: string): string;
+declare namespace convertBase {
+    var defaultChars: string;
+    var MAX_BASE: number;
+}
+declare function clamp(number: number, min: number, max: number): number;
+declare function randInt(min: number, max: number, inclusive?: boolean): number;
+declare function chance(probability: number): boolean;
+declare function roundTo(n: number, decimals: number): number;
+declare function lerp(a: number, b: number, t: number): number;
+declare function inRange(n: number, min: number, max: number): boolean;
+
+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;
+}
+
+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;
+
+export { AsyncQueue, type DebouncedFunction, type DeepPartial, type DeepRequired, type Entries, 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 };

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+interface DebouncedFunction<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): void;
+    cancel: () => void;
+    flush: () => void;
+}
+declare function debounce<T extends (...args: any[]) => any>(fn: T, delay?: number, options?: {
+    immediate?: boolean;
+}): DebouncedFunction<T>;
+declare function throttle<F extends (this: any, ...args: any[]) => void>(fn: F, interval?: number): (this: ThisParameterType<F>, ...args: Parameters<F>) => void;
+declare function deepEqual(a: any, b: any): boolean;
+declare function once<F extends (this: any, ...args: any[]) => any>(fn: F): (this: ThisParameterType<F>, ...args: Parameters<F>) => ReturnType<F>;
+declare function pick<T, K extends readonly (keyof T)[]>(obj: T, keys: K): Pick<T, K[number]>;
+declare function omit<T extends Record<string, any>, K extends readonly (keyof T)[]>(obj: T, keys: K): Omit<T, K[number]>;
+declare function retry<T>(fn: () => Promise<T>, attempts: number, delayMs?: number): Promise<T>;
+declare const noop: () => void;
+declare function tryCatch<T>(fn: () => T): [error: unknown, value?: T];
+declare function tap<T>(fn: (v: T) => void): (v: T) => T;
+declare function range(end: number | {
+    start?: number;
+    end: number;
+    step?: number;
+}): Generator<number>;
+declare function cycle<T>(iterable: Iterable<T>): Generator<T>;
+declare function chunk<T>(arr: T[], size: number): T[][];
+declare function shuffle<T>(arr: T[]): T[];
+declare function sample<T>(arr: T[]): T | undefined;
+declare function rotate<T>(arr: T[], n: number): T[];
+
+declare function sleep(ms: number): Promise<void>;
+declare class AsyncQueue {
+    private queue;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+declare function deferred(): {
+    promise: Promise<unknown>;
+    resolve: (value: unknown) => void;
+    reject: (reason?: any) => void;
+};
+declare function timeoutPromise<T>(promise: Promise<T>, ms: number, error?: Error): Promise<unknown>;
+
+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>;
+
+declare function bigIntPower(one: bigint, two: bigint): bigint;
+declare function convertBase(value: string, sourceBase: number, outBase: number, chars?: string): string;
+declare namespace convertBase {
+    var defaultChars: string;
+    var MAX_BASE: number;
+}
+declare function clamp(number: number, min: number, max: number): number;
+declare function randInt(min: number, max: number, inclusive?: boolean): number;
+declare function chance(probability: number): boolean;
+declare function roundTo(n: number, decimals: number): number;
+declare function lerp(a: number, b: number, t: number): number;
+declare function inRange(n: number, min: number, max: number): boolean;
+
+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;
+}
+
+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;
+
+export { AsyncQueue, type DebouncedFunction, type DeepPartial, type DeepRequired, type Entries, 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 };

package/dist/index.js

@@ -0,0 +1,461 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AsyncQueue: () => AsyncQueue,
+  TimedMap: () => TimedMap,
+  bigIntPower: () => bigIntPower,
+  chance: () => chance,
+  chunk: () => chunk,
+  clamp: () => clamp,
+  convertBase: () => convertBase,
+  cycle: () => cycle,
+  d: () => d,
+  days: () => days,
+  debounce: () => debounce,
+  deepEqual: () => deepEqual,
+  deferred: () => deferred,
+  h: () => h,
+  hours: () => hours,
+  inRange: () => inRange,
+  lerp: () => lerp,
+  m: () => m,
+  milliseconds: () => milliseconds,
+  minutes: () => minutes,
+  ms: () => ms,
+  noop: () => noop,
+  omit: () => omit,
+  once: () => once,
+  pick: () => pick,
+  randInt: () => randInt,
+  range: () => range,
+  retry: () => retry,
+  rotate: () => rotate,
+  roundTo: () => roundTo,
+  s: () => s,
+  sample: () => sample,
+  seconds: () => seconds,
+  shuffle: () => shuffle,
+  sleep: () => sleep,
+  tap: () => tap,
+  throttle: () => throttle,
+  timeoutPromise: () => timeoutPromise,
+  tryCatch: () => tryCatch
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/promises.ts
+function sleep(ms2) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms2);
+  });
+}
+var AsyncQueue = class {
+  queue = Promise.resolve();
+  run(fn) {
+    const res = this.queue.then(fn, fn);
+    this.queue = res.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return res;
+  }
+};
+function deferred() {
+  let resolve = null;
+  let reject = null;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+function timeoutPromise(promise, ms2, error = new Error("Timed out")) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(error), ms2))
+  ]);
+}
+
+// src/functions.ts
+function debounce(fn, delay = 300, options = {}) {
+  let timeout = null;
+  let lastArgs = null;
+  let lastThis;
+  let result;
+  const debounced = function(...args) {
+    lastArgs = args;
+    lastThis = this;
+    const callNow = options.immediate && !timeout;
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      timeout = null;
+      if (!options.immediate && lastArgs) {
+        result = fn.apply(lastThis, lastArgs);
+        lastArgs = null;
+      }
+    }, delay);
+    if (callNow) {
+      result = fn.apply(lastThis, lastArgs);
+      lastArgs = null;
+    }
+    return result;
+  };
+  debounced.cancel = () => {
+    if (timeout) clearTimeout(timeout);
+    timeout = null;
+    lastArgs = null;
+  };
+  debounced.flush = () => {
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = null;
+      if (lastArgs) {
+        fn.apply(lastThis, lastArgs);
+        lastArgs = null;
+      }
+    }
+  };
+  return debounced;
+}
+function throttle(fn, interval = 300) {
+  let last = 0;
+  let timeout = null;
+  return function(...args) {
+    const now = Date.now();
+    const remaining = interval - (now - last);
+    if (remaining <= 0) {
+      last = now;
+      fn.apply(this, args);
+    } else if (!timeout) {
+      timeout = setTimeout(() => {
+        last = Date.now();
+        timeout = null;
+        fn.apply(this, args);
+      }, remaining);
+    }
+  };
+}
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false;
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+  return keysA.every((k) => deepEqual(a[k], b[k]));
+}
+function once(fn) {
+  let called = false;
+  let result;
+  return function(...args) {
+    if (!called) {
+      called = true;
+      result = fn.apply(this, args);
+    }
+    return result;
+  };
+}
+function pick(obj, keys) {
+  return Object.fromEntries(keys.map((k) => [k, obj[k]]));
+}
+function omit(obj, keys) {
+  const set = new Set(keys);
+  return Object.fromEntries(
+    Object.entries(obj).filter(([k]) => !set.has(k))
+  );
+}
+async function retry(fn, attempts, delayMs = 0) {
+  let lastError;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      lastError = e;
+      if (delayMs) await sleep(delayMs);
+    }
+  }
+  throw lastError;
+}
+var noop = () => {
+};
+function tryCatch(fn) {
+  try {
+    return [null, fn()];
+  } catch (e) {
+    return [e];
+  }
+}
+function tap(fn) {
+  return (v) => {
+    fn(v);
+    return v;
+  };
+}
+function* range(end) {
+  let start = 0;
+  let step = 1;
+  let e = 0;
+  if (typeof end === "number") {
+    e = end;
+  } else {
+    start = end.start ?? 0;
+    step = end.step ?? 1;
+    e = end.end;
+  }
+  if (step === 0) throw new RangeError("step cannot be 0");
+  if (step > 0) {
+    for (let i = start; i < e; i += step) yield i;
+  } else {
+    for (let i = start; i > e; i += step) yield i;
+  }
+}
+function* cycle(iterable) {
+  const items = [...iterable];
+  if (!items.length) return;
+  while (true) {
+    for (const i of items) yield i;
+  }
+}
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+function shuffle(arr) {
+  const a = [...arr];
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}
+function sample(arr) {
+  if (!arr.length) return void 0;
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+function rotate(arr, n) {
+  const len = arr.length;
+  n = (n % len + len) % len;
+  return [...arr.slice(n), ...arr.slice(0, n)];
+}
+
+// src/duration.ts
+var msValues = {
+  ms: 1,
+  s: 1e3,
+  m: 1e3 * 60,
+  h: 1e3 * 60 * 60,
+  d: 1e3 * 60 * 60 * 24
+};
+function durationLong(initialMs = 0) {
+  let total = initialMs;
+  const add = (v, mult) => {
+    total += v * mult;
+    return builder;
+  };
+  const builder = {
+    toMilliseconds: () => total,
+    toSeconds: () => total / msValues.s,
+    toMinutes: () => total / msValues.m,
+    toHours: () => total / msValues.h,
+    toDays: () => total / msValues.d,
+    milliseconds: (v) => add(v, msValues.ms),
+    seconds: (v) => add(v, msValues.s),
+    minutes: (v) => add(v, msValues.m),
+    hours: (v) => add(v, msValues.h),
+    days: (v) => add(v, msValues.d)
+  };
+  return builder;
+}
+function durationShort(initialMs = 0) {
+  let total = initialMs;
+  const add = (v, mult) => {
+    total += v * mult;
+    return builder;
+  };
+  const builder = {
+    toMs: () => total,
+    toS: () => total / msValues.s,
+    toM: () => total / msValues.m,
+    toH: () => total / msValues.h,
+    toD: () => total / msValues.d,
+    ms: (v) => add(v, msValues.ms),
+    s: (v) => add(v, msValues.s),
+    m: (v) => add(v, msValues.m),
+    h: (v) => add(v, msValues.h),
+    d: (v) => add(v, msValues.d)
+  };
+  return builder;
+}
+function cS(unit) {
+  return (v) => durationShort()[unit](v);
+}
+function cL(unit) {
+  return (v) => durationLong()[unit](v);
+}
+var days = cL("days");
+var hours = cL("hours");
+var minutes = cL("minutes");
+var seconds = cL("seconds");
+var milliseconds = cL("milliseconds");
+var d = cS("d");
+var h = cS("h");
+var m = cS("m");
+var s = cS("s");
+var ms = cS("ms");
+
+// src/numbers.ts
+function bigIntPower(one, two) {
+  if (two === 0n) return 1n;
+  const powerTwo = bigIntPower(one, two / 2n);
+  if (two % 2n === 0n) return powerTwo * powerTwo;
+  return one * powerTwo * powerTwo;
+}
+function convertBase(value, sourceBase, outBase, chars = convertBase.defaultChars) {
+  const range2 = [...chars];
+  if (sourceBase < 2 || sourceBase > range2.length)
+    throw new RangeError(`sourceBase must be between 2 and ${range2.length}`);
+  if (outBase < 2 || outBase > range2.length)
+    throw new RangeError(`outBase must be between 2 and ${range2.length}`);
+  const outBaseBig = BigInt(outBase);
+  let decValue = [...value].toReversed().reduce((carry, digit, loopIndex) => {
+    const biggestBaseIndex = range2.indexOf(digit);
+    if (biggestBaseIndex === -1 || biggestBaseIndex > sourceBase - 1)
+      throw new ReferenceError(
+        `Invalid digit ${digit} for base ${sourceBase}.`
+      );
+    return carry + BigInt(biggestBaseIndex) * bigIntPower(BigInt(sourceBase), BigInt(loopIndex));
+  }, 0n);
+  let output = "";
+  while (decValue > 0) {
+    output = `${range2[Number(decValue % outBaseBig)] ?? ""}${output}`;
+    decValue = (decValue - decValue % outBaseBig) / outBaseBig;
+  }
+  return output || "0";
+}
+convertBase.defaultChars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-/=[];',.";
+convertBase.MAX_BASE = convertBase.defaultChars.length;
+function clamp(number, min, max) {
+  return Math.max(min, Math.min(max, number));
+}
+function randInt(min, max, inclusive = true) {
+  if (min > max) {
+    throw new RangeError("RandInt: min cannot be greater than max");
+  }
+  return Math.floor(Math.random() * (max - min + +inclusive)) + min;
+}
+function chance(probability) {
+  return Math.random() < probability;
+}
+function roundTo(n, decimals) {
+  const f = 10 ** decimals;
+  return Math.round(n * f) / f;
+}
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+function inRange(n, min, max) {
+  return n >= min && n <= max;
+}
+
+// src/timedMap.ts
+var TimedMap = class {
+  constructor(defaultTtlMs) {
+    this.defaultTtlMs = defaultTtlMs;
+  }
+  map = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  set(key, value, ttlMs = this.defaultTtlMs) {
+    this.map.set(key, value);
+    const timer = setTimeout(() => {
+      this.map.delete(key);
+      this.timers.delete(key);
+    }, ttlMs);
+    this.timers.set(key, timer);
+  }
+  has(key) {
+    return this.map.has(key);
+  }
+  clear() {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.map.clear();
+  }
+  get(key) {
+    return this.map.get(key);
+  }
+  delete(key) {
+    const timer = this.timers.get(key);
+    if (timer) clearTimeout(timer);
+    this.timers.delete(key);
+    return this.map.delete(key);
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AsyncQueue,
+  TimedMap,
+  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
+});
+//! days(12).h(5).s(4).toS();
+//! d(12).hours(5).seconds(4).toS();

package/dist/index.mjs

@@ -0,0 +1,396 @@
+// src/promises.ts
+function sleep(ms2) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms2);
+  });
+}
+var AsyncQueue = class {
+  queue = Promise.resolve();
+  run(fn) {
+    const res = this.queue.then(fn, fn);
+    this.queue = res.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return res;
+  }
+};
+function deferred() {
+  let resolve = null;
+  let reject = null;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+function timeoutPromise(promise, ms2, error = new Error("Timed out")) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(error), ms2))
+  ]);
+}
+
+// src/functions.ts
+function debounce(fn, delay = 300, options = {}) {
+  let timeout = null;
+  let lastArgs = null;
+  let lastThis;
+  let result;
+  const debounced = function(...args) {
+    lastArgs = args;
+    lastThis = this;
+    const callNow = options.immediate && !timeout;
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      timeout = null;
+      if (!options.immediate && lastArgs) {
+        result = fn.apply(lastThis, lastArgs);
+        lastArgs = null;
+      }
+    }, delay);
+    if (callNow) {
+      result = fn.apply(lastThis, lastArgs);
+      lastArgs = null;
+    }
+    return result;
+  };
+  debounced.cancel = () => {
+    if (timeout) clearTimeout(timeout);
+    timeout = null;
+    lastArgs = null;
+  };
+  debounced.flush = () => {
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = null;
+      if (lastArgs) {
+        fn.apply(lastThis, lastArgs);
+        lastArgs = null;
+      }
+    }
+  };
+  return debounced;
+}
+function throttle(fn, interval = 300) {
+  let last = 0;
+  let timeout = null;
+  return function(...args) {
+    const now = Date.now();
+    const remaining = interval - (now - last);
+    if (remaining <= 0) {
+      last = now;
+      fn.apply(this, args);
+    } else if (!timeout) {
+      timeout = setTimeout(() => {
+        last = Date.now();
+        timeout = null;
+        fn.apply(this, args);
+      }, remaining);
+    }
+  };
+}
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false;
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+  return keysA.every((k) => deepEqual(a[k], b[k]));
+}
+function once(fn) {
+  let called = false;
+  let result;
+  return function(...args) {
+    if (!called) {
+      called = true;
+      result = fn.apply(this, args);
+    }
+    return result;
+  };
+}
+function pick(obj, keys) {
+  return Object.fromEntries(keys.map((k) => [k, obj[k]]));
+}
+function omit(obj, keys) {
+  const set = new Set(keys);
+  return Object.fromEntries(
+    Object.entries(obj).filter(([k]) => !set.has(k))
+  );
+}
+async function retry(fn, attempts, delayMs = 0) {
+  let lastError;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      lastError = e;
+      if (delayMs) await sleep(delayMs);
+    }
+  }
+  throw lastError;
+}
+var noop = () => {
+};
+function tryCatch(fn) {
+  try {
+    return [null, fn()];
+  } catch (e) {
+    return [e];
+  }
+}
+function tap(fn) {
+  return (v) => {
+    fn(v);
+    return v;
+  };
+}
+function* range(end) {
+  let start = 0;
+  let step = 1;
+  let e = 0;
+  if (typeof end === "number") {
+    e = end;
+  } else {
+    start = end.start ?? 0;
+    step = end.step ?? 1;
+    e = end.end;
+  }
+  if (step === 0) throw new RangeError("step cannot be 0");
+  if (step > 0) {
+    for (let i = start; i < e; i += step) yield i;
+  } else {
+    for (let i = start; i > e; i += step) yield i;
+  }
+}
+function* cycle(iterable) {
+  const items = [...iterable];
+  if (!items.length) return;
+  while (true) {
+    for (const i of items) yield i;
+  }
+}
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+function shuffle(arr) {
+  const a = [...arr];
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}
+function sample(arr) {
+  if (!arr.length) return void 0;
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+function rotate(arr, n) {
+  const len = arr.length;
+  n = (n % len + len) % len;
+  return [...arr.slice(n), ...arr.slice(0, n)];
+}
+
+// src/duration.ts
+var msValues = {
+  ms: 1,
+  s: 1e3,
+  m: 1e3 * 60,
+  h: 1e3 * 60 * 60,
+  d: 1e3 * 60 * 60 * 24
+};
+function durationLong(initialMs = 0) {
+  let total = initialMs;
+  const add = (v, mult) => {
+    total += v * mult;
+    return builder;
+  };
+  const builder = {
+    toMilliseconds: () => total,
+    toSeconds: () => total / msValues.s,
+    toMinutes: () => total / msValues.m,
+    toHours: () => total / msValues.h,
+    toDays: () => total / msValues.d,
+    milliseconds: (v) => add(v, msValues.ms),
+    seconds: (v) => add(v, msValues.s),
+    minutes: (v) => add(v, msValues.m),
+    hours: (v) => add(v, msValues.h),
+    days: (v) => add(v, msValues.d)
+  };
+  return builder;
+}
+function durationShort(initialMs = 0) {
+  let total = initialMs;
+  const add = (v, mult) => {
+    total += v * mult;
+    return builder;
+  };
+  const builder = {
+    toMs: () => total,
+    toS: () => total / msValues.s,
+    toM: () => total / msValues.m,
+    toH: () => total / msValues.h,
+    toD: () => total / msValues.d,
+    ms: (v) => add(v, msValues.ms),
+    s: (v) => add(v, msValues.s),
+    m: (v) => add(v, msValues.m),
+    h: (v) => add(v, msValues.h),
+    d: (v) => add(v, msValues.d)
+  };
+  return builder;
+}
+function cS(unit) {
+  return (v) => durationShort()[unit](v);
+}
+function cL(unit) {
+  return (v) => durationLong()[unit](v);
+}
+var days = cL("days");
+var hours = cL("hours");
+var minutes = cL("minutes");
+var seconds = cL("seconds");
+var milliseconds = cL("milliseconds");
+var d = cS("d");
+var h = cS("h");
+var m = cS("m");
+var s = cS("s");
+var ms = cS("ms");
+
+// src/numbers.ts
+function bigIntPower(one, two) {
+  if (two === 0n) return 1n;
+  const powerTwo = bigIntPower(one, two / 2n);
+  if (two % 2n === 0n) return powerTwo * powerTwo;
+  return one * powerTwo * powerTwo;
+}
+function convertBase(value, sourceBase, outBase, chars = convertBase.defaultChars) {
+  const range2 = [...chars];
+  if (sourceBase < 2 || sourceBase > range2.length)
+    throw new RangeError(`sourceBase must be between 2 and ${range2.length}`);
+  if (outBase < 2 || outBase > range2.length)
+    throw new RangeError(`outBase must be between 2 and ${range2.length}`);
+  const outBaseBig = BigInt(outBase);
+  let decValue = [...value].toReversed().reduce((carry, digit, loopIndex) => {
+    const biggestBaseIndex = range2.indexOf(digit);
+    if (biggestBaseIndex === -1 || biggestBaseIndex > sourceBase - 1)
+      throw new ReferenceError(
+        `Invalid digit ${digit} for base ${sourceBase}.`
+      );
+    return carry + BigInt(biggestBaseIndex) * bigIntPower(BigInt(sourceBase), BigInt(loopIndex));
+  }, 0n);
+  let output = "";
+  while (decValue > 0) {
+    output = `${range2[Number(decValue % outBaseBig)] ?? ""}${output}`;
+    decValue = (decValue - decValue % outBaseBig) / outBaseBig;
+  }
+  return output || "0";
+}
+convertBase.defaultChars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-/=[];',.";
+convertBase.MAX_BASE = convertBase.defaultChars.length;
+function clamp(number, min, max) {
+  return Math.max(min, Math.min(max, number));
+}
+function randInt(min, max, inclusive = true) {
+  if (min > max) {
+    throw new RangeError("RandInt: min cannot be greater than max");
+  }
+  return Math.floor(Math.random() * (max - min + +inclusive)) + min;
+}
+function chance(probability) {
+  return Math.random() < probability;
+}
+function roundTo(n, decimals) {
+  const f = 10 ** decimals;
+  return Math.round(n * f) / f;
+}
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+function inRange(n, min, max) {
+  return n >= min && n <= max;
+}
+
+// src/timedMap.ts
+var TimedMap = class {
+  constructor(defaultTtlMs) {
+    this.defaultTtlMs = defaultTtlMs;
+  }
+  map = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  set(key, value, ttlMs = this.defaultTtlMs) {
+    this.map.set(key, value);
+    const timer = setTimeout(() => {
+      this.map.delete(key);
+      this.timers.delete(key);
+    }, ttlMs);
+    this.timers.set(key, timer);
+  }
+  has(key) {
+    return this.map.has(key);
+  }
+  clear() {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.map.clear();
+  }
+  get(key) {
+    return this.map.get(key);
+  }
+  delete(key) {
+    const timer = this.timers.get(key);
+    if (timer) clearTimeout(timer);
+    this.timers.delete(key);
+    return this.map.delete(key);
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+export {
+  AsyncQueue,
+  TimedMap,
+  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
+};
+//! days(12).h(5).s(4).toS();
+//! d(12).hours(5).seconds(4).toS();

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@thetally/toolbox",
+  "version": "1.0.0",
+  "description": "Core utils and helpers for nodejs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": ["utility", "debounce", "sleep"],
+  "author": "",
+  "license": "ISC"
+}