superjs-core 0.3.3 → 0.3.5

package/dist/async/index.d.ts

@@ -1,5 +1,88 @@
 import { RetryOptions } from '../core/index.js';
 
+interface QueueOptions {
+    concurrency?: number;
+}
+/**
+ * Priority-based async task queue with concurrency control.
+ *
+ * @example
+ * const queue = new Queue({ concurrency: 2 })
+ * const result = await queue.add(() => fetch('/api/data'))
+ */
+declare class Queue<T = unknown> {
+    private _tasks;
+    private _running;
+    private _paused;
+    private _idleResolve;
+    private _maxConcurrency;
+    constructor(options?: QueueOptions);
+    get pending(): number;
+    get running(): number;
+    add<R>(task: () => Promise<R>, options?: {
+        priority?: number;
+    }): Promise<R>;
+    pause(): void;
+    resume(): void;
+    clear(): void;
+    onIdle(): Promise<void>;
+    private _process;
+}
+
+/**
+ * Semaphore for controlling concurrent access to a resource.
+ *
+ * @example
+ * const sem = new Semaphore(2)
+ * await sem.use(async () => {
+ *   // Only 2 callers at a time
+ *   await doSomething()
+ * })
+ */
+declare class Semaphore {
+    private _available;
+    private _waiting;
+    constructor(concurrency: number);
+    get available(): number;
+    acquire(): Promise<() => void>;
+    use<T>(fn: () => Promise<T>): Promise<T>;
+    private _release;
+}
+
+/**
+ * Options for memoizeAsync.
+ */
+interface MemoizeAsyncOptions {
+    /** Time-to-live in milliseconds (default: 60000) */
+    ttl?: number;
+    /** Return stale value while fetching fresh data (default: false) */
+    staleWhileRevalidate?: boolean;
+    /** Maximum number of cached entries (default: 100) */
+    maxSize?: number;
+    /** Custom cache key resolver. Defaults to JSON.stringify of args. */
+    resolver?: (...args: unknown[]) => string;
+}
+interface CacheEntry {
+    value: unknown;
+    timestamp: number;
+    promise?: Promise<unknown>;
+}
+/**
+ * Memoizes an async function with TTL, stale-while-revalidate, and bounded cache.
+ *
+ * @example
+ * const fetchData = memoizeAsync(async (id: string) => {
+ *   return await api.fetch(id)
+ * }, { ttl: 5000, staleWhileRevalidate: true })
+ *
+ * const data = await fetchData('123') // cached for 5s
+ * const data2 = await fetchData('123') // returns cached, refreshes in bg
+ */
+declare function memoizeAsync<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, options?: MemoizeAsyncOptions): T & {
+    cache: Map<string, CacheEntry>;
+    clear: () => void;
+};
+
 /**
  * Delays execution for the given number of milliseconds.
  */
@@ -41,4 +124,4 @@ interface Deferred<T> {
     reject: (reason: unknown) => void;
 }
 
-export { type Deferred, allSettledMap, deferred, parallelMap, pipeline, raceWithTimeout, retryAsync, sleep, timeout };
+export { type Deferred, type MemoizeAsyncOptions, Queue, type QueueOptions, Semaphore, allSettledMap, deferred, memoizeAsync, parallelMap, pipeline, raceWithTimeout, retryAsync, sleep, timeout };

package/dist/async/index.js

@@ -1,3 +1,151 @@
+// src/async/queue.ts
+var Queue = class {
+  _tasks = [];
+  _running = 0;
+  _paused = false;
+  _idleResolve = null;
+  _maxConcurrency;
+  constructor(options) {
+    this._maxConcurrency = options?.concurrency ?? 1;
+    if (this._maxConcurrency < 1) this._maxConcurrency = 1;
+  }
+  get pending() {
+    return this._tasks.length;
+  }
+  get running() {
+    return this._running;
+  }
+  add(task, options) {
+    return new Promise((resolve, reject) => {
+      this._tasks.push({
+        priority: options?.priority ?? 0,
+        task,
+        resolve,
+        reject
+      });
+      this._tasks.sort((a, b) => b.priority - a.priority);
+      this._process();
+    });
+  }
+  pause() {
+    this._paused = true;
+  }
+  resume() {
+    this._paused = false;
+    this._process();
+  }
+  clear() {
+    const err = new Error("Queue cleared");
+    for (const t of this._tasks) t.reject(err);
+    this._tasks = [];
+  }
+  onIdle() {
+    if (this._running === 0 && this._tasks.length === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      this._idleResolve = resolve;
+    });
+  }
+  _process() {
+    if (this._paused) return;
+    while (this._running < this._maxConcurrency && this._tasks.length > 0) {
+      const item = this._tasks.shift();
+      this._running++;
+      item.task().then((result) => item.resolve(result)).catch((err) => item.reject(err)).finally(() => {
+        this._running--;
+        this._process();
+        if (this._running === 0 && this._tasks.length === 0 && this._idleResolve) {
+          this._idleResolve();
+          this._idleResolve = null;
+        }
+      });
+    }
+  }
+};
+
+// src/async/semaphore.ts
+var Semaphore = class {
+  _available;
+  _waiting = [];
+  constructor(concurrency) {
+    if (concurrency < 1) throw new RangeError("Semaphore concurrency must be >= 1");
+    this._available = concurrency;
+  }
+  get available() {
+    return this._available;
+  }
+  acquire() {
+    if (this._available > 0) {
+      this._available--;
+      return Promise.resolve(this._release.bind(this));
+    }
+    return new Promise((resolve) => {
+      this._waiting.push(() => {
+        this._available--;
+        resolve(this._release.bind(this));
+      });
+    });
+  }
+  async use(fn) {
+    const release = await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+  _release() {
+    this._available++;
+    if (this._waiting.length > 0) {
+      const next = this._waiting.shift();
+      if (next) next();
+    }
+  }
+};
+
+// src/async/memoize.ts
+function memoizeAsync(fn, options) {
+  const {
+    ttl = 6e4,
+    staleWhileRevalidate = false,
+    maxSize = 100,
+    resolver = (...args) => JSON.stringify(args)
+  } = options ?? {};
+  const cache = /* @__PURE__ */ new Map();
+  const memoized = (async (...args) => {
+    const key = resolver(...args);
+    const now = Date.now();
+    const entry = cache.get(key);
+    if (entry && now - entry.timestamp < ttl) {
+      return entry.value;
+    }
+    if (entry && staleWhileRevalidate && now - entry.timestamp >= ttl) {
+      if (entry.promise) {
+        return entry.value;
+      }
+      entry.promise = fn(...args).then((result2) => {
+        entry.value = result2;
+        entry.timestamp = now;
+        entry.promise = void 0;
+        return result2;
+      }).catch((err) => {
+        entry.promise = void 0;
+        throw err;
+      });
+      return entry.value;
+    }
+    const result = await fn(...args);
+    cache.set(key, { value: result, timestamp: now });
+    if (cache.size > maxSize) {
+      const firstKey = cache.keys().next().value;
+      if (firstKey !== void 0) cache.delete(firstKey);
+    }
+    return result;
+  });
+  memoized.cache = cache;
+  memoized.clear = () => cache.clear();
+  return memoized;
+}
+
 // src/async/index.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -76,8 +224,11 @@ function deferred() {
   return { promise, resolve, reject };
 }
 export {
+  Queue,
+  Semaphore,
   allSettledMap,
   deferred,
+  memoizeAsync,
   parallelMap,
   pipeline,
   raceWithTimeout,

package/dist/async/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/async/index.ts"],"sourcesContent":["import type { RetryOptions } from '../core/index.js'\r\n\r\n/**\r\n * Delays execution for the given number of milliseconds.\r\n */\r\nexport function sleep(ms: number): Promise<void> {\r\n  return new Promise(resolve => setTimeout(resolve, ms))\r\n}\r\n\r\n/**\r\n * Rejects a promise if it does not resolve within the specified timeout.\r\n */\r\nexport async function timeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T> {\r\n  let timer: ReturnType<typeof setTimeout> | undefined\r\n  const timeoutPromise = new Promise<never>((_, reject) => {\r\n    timer = setTimeout(() => reject(new Error(errorMessage ?? `Promise timed out after ${ms}ms`)), ms)\r\n  })\r\n  try {\r\n    return await Promise.race([promise, timeoutPromise])\r\n  } finally {\r\n    if (timer !== undefined) clearTimeout(timer)\r\n  }\r\n}\r\n\r\n/**\r\n * Races a promise against a timeout, returning 'timeout' if the timer wins.\r\n */\r\nexport async function raceWithTimeout<T>(promise: Promise<T>, ms: number): Promise<T | 'timeout'> {\r\n  let timer: ReturnType<typeof setTimeout> | undefined\r\n  const timeoutPromise = new Promise<'timeout'>(resolve => {\r\n    timer = setTimeout(() => resolve('timeout'), ms)\r\n  })\r\n  try {\r\n    return await Promise.race([promise, timeoutPromise])\r\n  } finally {\r\n    if (timer !== undefined) clearTimeout(timer)\r\n  }\r\n}\r\n\r\n/**\r\n * Maps over an array with an async function, using Promise.allSettled.\r\n * Returns an array of PromiseSettledResult.\r\n */\r\nexport async function allSettledMap<T, R>(\r\n  items: T[],\r\n  fn: (item: T) => Promise<R>,\r\n): Promise<PromiseSettledResult<R>[]> {\r\n  return await Promise.allSettled(items.map(fn))\r\n}\r\n\r\n/**\r\n * Maps over an array with an async function, limiting concurrency.\r\n *\r\n * @param concurrency - Maximum number of concurrent operations (default Infinity)\r\n */\r\nexport async function parallelMap<T, R>(\r\n  items: T[],\r\n  fn: (item: T) => Promise<R>,\r\n  concurrency = Number.POSITIVE_INFINITY,\r\n): Promise<R[]> {\r\n  if (concurrency === Number.POSITIVE_INFINITY) {\r\n    return await Promise.all(items.map(fn))\r\n  }\r\n\r\n  const results: R[] = []\r\n  const queue = [...items]\r\n\r\n  const worker = async (): Promise<void> => {\r\n    while (queue.length > 0) {\r\n      const item = queue.shift()!\r\n      results.push(await fn(item))\r\n    }\r\n  }\r\n\r\n  const workerCount = Math.min(concurrency, items.length)\r\n  const workers = Array.from({ length: workerCount }, () => worker())\r\n  await Promise.all(workers)\r\n  return results\r\n}\r\n\r\n/**\r\n * Retries an async function with exponential backoff.\r\n */\r\nexport async function retryAsync<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T> {\r\n  const { attempts = 3, baseDelay = 1000, maxDelay = 30000, shouldRetry = () => true } = options ?? {}\r\n  let lastError: unknown\r\n  for (let attempt = 0; attempt < attempts; attempt++) {\r\n    try {\r\n      return await fn()\r\n    } catch (error) {\r\n      lastError = error\r\n      if (!shouldRetry(error) || attempt >= attempts - 1) break\r\n      const delay = Math.min(baseDelay * 2 ** attempt + Math.random() * baseDelay, maxDelay)\r\n      await sleep(delay)\r\n    }\r\n  }\r\n  throw lastError\r\n}\r\n\r\n/**\r\n * Composes async functions, passing the result of each to the next.\r\n */\r\nexport async function pipeline<T>(initial: T, ...fns: Array<(arg: T) => Promise<T>>): Promise<T> {\r\n  let result = initial\r\n  for (const fn of fns) {\r\n    result = await fn(result)\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Creates a deferred promise with external resolve and reject methods.\r\n */\r\nexport function deferred<T>(): Deferred<T> {\r\n  let resolve!: (value: T) => void\r\n  let reject!: (reason: unknown) => void\r\n  const promise = new Promise<T>((res, rej) => {\r\n    resolve = res\r\n    reject = rej\r\n  })\r\n  return { promise, resolve, reject }\r\n}\r\n\r\nexport interface Deferred<T> {\r\n  promise: Promise<T>\r\n  resolve: (value: T) => void\r\n  reject: (reason: unknown) => void\r\n}\r\n"],"mappings":";AAKO,SAAS,MAAM,IAA2B;AAC/C,SAAO,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AACvD;AAKA,eAAsB,QAAW,SAAqB,IAAY,cAAmC;AACnG,MAAI;AACJ,QAAM,iBAAiB,IAAI,QAAe,CAAC,GAAG,WAAW;AACvD,YAAQ,WAAW,MAAM,OAAO,IAAI,MAAM,gBAAgB,2BAA2B,EAAE,IAAI,CAAC,GAAG,EAAE;AAAA,EACnG,CAAC;AACD,MAAI;AACF,WAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,cAAc,CAAC;AAAA,EACrD,UAAE;AACA,QAAI,UAAU,OAAW,cAAa,KAAK;AAAA,EAC7C;AACF;AAKA,eAAsB,gBAAmB,SAAqB,IAAoC;AAChG,MAAI;AACJ,QAAM,iBAAiB,IAAI,QAAmB,aAAW;AACvD,YAAQ,WAAW,MAAM,QAAQ,SAAS,GAAG,EAAE;AAAA,EACjD,CAAC;AACD,MAAI;AACF,WAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,cAAc,CAAC;AAAA,EACrD,UAAE;AACA,QAAI,UAAU,OAAW,cAAa,KAAK;AAAA,EAC7C;AACF;AAMA,eAAsB,cACpB,OACA,IACoC;AACpC,SAAO,MAAM,QAAQ,WAAW,MAAM,IAAI,EAAE,CAAC;AAC/C;AAOA,eAAsB,YACpB,OACA,IACA,cAAc,OAAO,mBACP;AACd,MAAI,gBAAgB,OAAO,mBAAmB;AAC5C,WAAO,MAAM,QAAQ,IAAI,MAAM,IAAI,EAAE,CAAC;AAAA,EACxC;AAEA,QAAM,UAAe,CAAC;AACtB,QAAM,QAAQ,CAAC,GAAG,KAAK;AAEvB,QAAM,SAAS,YAA2B;AACxC,WAAO,MAAM,SAAS,GAAG;AACvB,YAAM,OAAO,MAAM,MAAM;AACzB,cAAQ,KAAK,MAAM,GAAG,IAAI,CAAC;AAAA,IAC7B;AAAA,EACF;AAEA,QAAM,cAAc,KAAK,IAAI,aAAa,MAAM,MAAM;AACtD,QAAM,UAAU,MAAM,KAAK,EAAE,QAAQ,YAAY,GAAG,MAAM,OAAO,CAAC;AAClE,QAAM,QAAQ,IAAI,OAAO;AACzB,SAAO;AACT;AAKA,eAAsB,WAAc,IAAsB,SAAoC;AAC5F,QAAM,EAAE,WAAW,GAAG,YAAY,KAAM,WAAW,KAAO,cAAc,MAAM,KAAK,IAAI,WAAW,CAAC;AACnG,MAAI;AACJ,WAAS,UAAU,GAAG,UAAU,UAAU,WAAW;AACnD,QAAI;AACF,aAAO,MAAM,GAAG;AAAA,IAClB,SAAS,OAAO;AACd,kBAAY;AACZ,UAAI,CAAC,YAAY,KAAK,KAAK,WAAW,WAAW,EAAG;AACpD,YAAM,QAAQ,KAAK,IAAI,YAAY,KAAK,UAAU,KAAK,OAAO,IAAI,WAAW,QAAQ;AACrF,YAAM,MAAM,KAAK;AAAA,IACnB;AAAA,EACF;AACA,QAAM;AACR;AAKA,eAAsB,SAAY,YAAe,KAAgD;AAC/F,MAAI,SAAS;AACb,aAAW,MAAM,KAAK;AACpB,aAAS,MAAM,GAAG,MAAM;AAAA,EAC1B;AACA,SAAO;AACT;AAKO,SAAS,WAA2B;AACzC,MAAI;AACJ,MAAI;AACJ,QAAM,UAAU,IAAI,QAAW,CAAC,KAAK,QAAQ;AAC3C,cAAU;AACV,aAAS;AAAA,EACX,CAAC;AACD,SAAO,EAAE,SAAS,SAAS,OAAO;AACpC;","names":[]}
+{"version":3,"sources":["../../src/async/queue.ts","../../src/async/semaphore.ts","../../src/async/memoize.ts","../../src/async/index.ts"],"sourcesContent":["export interface QueueOptions {\n  concurrency?: number\n}\n\n/**\n * Priority-based async task queue with concurrency control.\n *\n * @example\n * const queue = new Queue({ concurrency: 2 })\n * const result = await queue.add(() => fetch('/api/data'))\n */\nexport class Queue<T = unknown> {\n  private _tasks: Array<{\n    priority: number\n    task: () => Promise<T>\n    resolve: (value: T) => void\n    reject: (reason: unknown) => void\n  }> = []\n  private _running = 0\n  private _paused = false\n  private _idleResolve: (() => void) | null = null\n  private _maxConcurrency: number\n\n  constructor(options?: QueueOptions) {\n    this._maxConcurrency = options?.concurrency ?? 1\n    if (this._maxConcurrency < 1) this._maxConcurrency = 1\n  }\n\n  get pending(): number {\n    return this._tasks.length\n  }\n\n  get running(): number {\n    return this._running\n  }\n\n  add<R>(task: () => Promise<R>, options?: { priority?: number }): Promise<R> {\n    return new Promise<R>((resolve, reject) => {\n      this._tasks.push({\n        priority: options?.priority ?? 0,\n        task: task as unknown as () => Promise<T>,\n        resolve: resolve as (value: T) => void,\n        reject,\n      })\n      this._tasks.sort((a, b) => b.priority - a.priority)\n      this._process()\n    })\n  }\n\n  pause(): void {\n    this._paused = true\n  }\n\n  resume(): void {\n    this._paused = false\n    this._process()\n  }\n\n  clear(): void {\n    const err = new Error('Queue cleared')\n    for (const t of this._tasks) t.reject(err)\n    this._tasks = []\n  }\n\n  onIdle(): Promise<void> {\n    if (this._running === 0 && this._tasks.length === 0) return Promise.resolve()\n    return new Promise<void>((resolve) => {\n      this._idleResolve = resolve\n    })\n  }\n\n  private _process(): void {\n    if (this._paused) return\n    while (this._running < this._maxConcurrency && this._tasks.length > 0) {\n      const item = this._tasks.shift()!\n      this._running++\n      item\n        .task()\n        .then((result) => item.resolve(result))\n        .catch((err) => item.reject(err))\n        .finally(() => {\n          this._running--\n          this._process()\n          if (this._running === 0 && this._tasks.length === 0 && this._idleResolve) {\n            this._idleResolve()\n            this._idleResolve = null\n          }\n        })\n    }\n  }\n}\n\nexport default Queue\n","/**\n * Semaphore for controlling concurrent access to a resource.\n *\n * @example\n * const sem = new Semaphore(2)\n * await sem.use(async () => {\n *   // Only 2 callers at a time\n *   await doSomething()\n * })\n */\nexport class Semaphore {\n  private _available: number\n  private _waiting: Array<() => void> = []\n\n  constructor(concurrency: number) {\n    if (concurrency < 1) throw new RangeError('Semaphore concurrency must be >= 1')\n    this._available = concurrency\n  }\n\n  get available(): number {\n    return this._available\n  }\n\n  acquire(): Promise<() => void> {\n    if (this._available > 0) {\n      this._available--\n      return Promise.resolve(this._release.bind(this))\n    }\n    return new Promise<() => void>((resolve) => {\n      this._waiting.push(() => {\n        this._available--\n        resolve(this._release.bind(this))\n      })\n    })\n  }\n\n  async use<T>(fn: () => Promise<T>): Promise<T> {\n    const release = await this.acquire()\n    try {\n      return await fn()\n    } finally {\n      release()\n    }\n  }\n\n  private _release(): void {\n    this._available++\n    if (this._waiting.length > 0) {\n      const next = this._waiting.shift()\n      if (next) next()\n    }\n  }\n}\n\nexport default Semaphore\n","/**\n * Options for memoizeAsync.\n */\nexport interface MemoizeAsyncOptions {\n  /** Time-to-live in milliseconds (default: 60000) */\n  ttl?: number\n  /** Return stale value while fetching fresh data (default: false) */\n  staleWhileRevalidate?: boolean\n  /** Maximum number of cached entries (default: 100) */\n  maxSize?: number\n  /** Custom cache key resolver. Defaults to JSON.stringify of args. */\n  resolver?: (...args: unknown[]) => string\n}\n\ninterface CacheEntry {\n  value: unknown\n  timestamp: number\n  promise?: Promise<unknown>\n}\n\n/**\n * Memoizes an async function with TTL, stale-while-revalidate, and bounded cache.\n *\n * @example\n * const fetchData = memoizeAsync(async (id: string) => {\n *   return await api.fetch(id)\n * }, { ttl: 5000, staleWhileRevalidate: true })\n *\n * const data = await fetchData('123') // cached for 5s\n * const data2 = await fetchData('123') // returns cached, refreshes in bg\n */\nexport function memoizeAsync<T extends (...args: unknown[]) => Promise<unknown>>(\n  fn: T,\n  options?: MemoizeAsyncOptions,\n): T & {\n  cache: Map<string, CacheEntry>\n  clear: () => void\n} {\n  const {\n    ttl = 60000,\n    staleWhileRevalidate = false,\n    maxSize = 100,\n    resolver = (...args: unknown[]) => JSON.stringify(args),\n  } = options ?? {}\n\n  const cache = new Map<string, CacheEntry>()\n\n  const memoized = (async (...args: unknown[]): Promise<unknown> => {\n    const key = resolver(...args)\n    const now = Date.now()\n    const entry = cache.get(key)\n\n    if (entry && now - entry.timestamp < ttl) {\n      return entry.value\n    }\n\n    if (entry && staleWhileRevalidate && now - entry.timestamp >= ttl) {\n      if (entry.promise) {\n        return entry.value\n      }\n      entry.promise = fn(...args)\n        .then((result) => {\n          entry.value = result\n          entry.timestamp = now\n          entry.promise = undefined\n          return result\n        })\n        .catch((err) => {\n          entry.promise = undefined\n          throw err\n        })\n      return entry.value\n    }\n\n    const result = await fn(...args)\n    cache.set(key, { value: result, timestamp: now })\n\n    if (cache.size > maxSize) {\n      const firstKey = cache.keys().next().value\n      if (firstKey !== undefined) cache.delete(firstKey)\n    }\n\n    return result\n  }) as T & {\n    cache: Map<string, CacheEntry>\n    clear: () => void\n  }\n\n  memoized.cache = cache\n  memoized.clear = () => cache.clear()\n\n  return memoized\n}\n\nexport default memoizeAsync\n","import type { RetryOptions } from '../core/index.js'\r\n\r\n/**\r\n * Delays execution for the given number of milliseconds.\r\n */\r\nexport function sleep(ms: number): Promise<void> {\r\n  return new Promise(resolve => setTimeout(resolve, ms))\r\n}\r\n\r\n/**\r\n * Rejects a promise if it does not resolve within the specified timeout.\r\n */\r\nexport async function timeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T> {\r\n  let timer: ReturnType<typeof setTimeout> | undefined\r\n  const timeoutPromise = new Promise<never>((_, reject) => {\r\n    timer = setTimeout(() => reject(new Error(errorMessage ?? `Promise timed out after ${ms}ms`)), ms)\r\n  })\r\n  try {\r\n    return await Promise.race([promise, timeoutPromise])\r\n  } finally {\r\n    if (timer !== undefined) clearTimeout(timer)\r\n  }\r\n}\r\n\r\n/**\r\n * Races a promise against a timeout, returning 'timeout' if the timer wins.\r\n */\r\nexport async function raceWithTimeout<T>(promise: Promise<T>, ms: number): Promise<T | 'timeout'> {\r\n  let timer: ReturnType<typeof setTimeout> | undefined\r\n  const timeoutPromise = new Promise<'timeout'>(resolve => {\r\n    timer = setTimeout(() => resolve('timeout'), ms)\r\n  })\r\n  try {\r\n    return await Promise.race([promise, timeoutPromise])\r\n  } finally {\r\n    if (timer !== undefined) clearTimeout(timer)\r\n  }\r\n}\r\n\r\n/**\r\n * Maps over an array with an async function, using Promise.allSettled.\r\n * Returns an array of PromiseSettledResult.\r\n */\r\nexport async function allSettledMap<T, R>(\r\n  items: T[],\r\n  fn: (item: T) => Promise<R>,\r\n): Promise<PromiseSettledResult<R>[]> {\r\n  return await Promise.allSettled(items.map(fn))\r\n}\r\n\r\n/**\r\n * Maps over an array with an async function, limiting concurrency.\r\n *\r\n * @param concurrency - Maximum number of concurrent operations (default Infinity)\r\n */\r\nexport async function parallelMap<T, R>(\r\n  items: T[],\r\n  fn: (item: T) => Promise<R>,\r\n  concurrency = Number.POSITIVE_INFINITY,\r\n): Promise<R[]> {\r\n  if (concurrency === Number.POSITIVE_INFINITY) {\r\n    return await Promise.all(items.map(fn))\r\n  }\r\n\r\n  const results: R[] = []\r\n  const queue = [...items]\r\n\r\n  const worker = async (): Promise<void> => {\r\n    while (queue.length > 0) {\r\n      const item = queue.shift()!\r\n      results.push(await fn(item))\r\n    }\r\n  }\r\n\r\n  const workerCount = Math.min(concurrency, items.length)\r\n  const workers = Array.from({ length: workerCount }, () => worker())\r\n  await Promise.all(workers)\r\n  return results\r\n}\r\n\r\n/**\r\n * Retries an async function with exponential backoff.\r\n */\r\nexport async function retryAsync<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T> {\r\n  const { attempts = 3, baseDelay = 1000, maxDelay = 30000, shouldRetry = () => true } = options ?? {}\r\n  let lastError: unknown\r\n  for (let attempt = 0; attempt < attempts; attempt++) {\r\n    try {\r\n      return await fn()\r\n    } catch (error) {\r\n      lastError = error\r\n      if (!shouldRetry(error) || attempt >= attempts - 1) break\r\n      const delay = Math.min(baseDelay * 2 ** attempt + Math.random() * baseDelay, maxDelay)\r\n      await sleep(delay)\r\n    }\r\n  }\r\n  throw lastError\r\n}\r\n\r\n/**\r\n * Composes async functions, passing the result of each to the next.\r\n */\r\nexport async function pipeline<T>(initial: T, ...fns: Array<(arg: T) => Promise<T>>): Promise<T> {\r\n  let result = initial\r\n  for (const fn of fns) {\r\n    result = await fn(result)\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Creates a deferred promise with external resolve and reject methods.\r\n */\r\nexport function deferred<T>(): Deferred<T> {\r\n  let resolve!: (value: T) => void\r\n  let reject!: (reason: unknown) => void\r\n  const promise = new Promise<T>((res, rej) => {\r\n    resolve = res\r\n    reject = rej\r\n  })\r\n  return { promise, resolve, reject }\r\n}\r\n\r\nexport interface Deferred<T> {\r\n  promise: Promise<T>\r\n  resolve: (value: T) => void\r\n  reject: (reason: unknown) => void\r\n}\r\n\r\n// ─── Queue, Semaphore, memoizeAsync ─────────────────────\r\nexport { Queue } from './queue.js'\r\nexport type { QueueOptions } from './queue.js'\r\nexport { Semaphore } from './semaphore.js'\r\nexport { memoizeAsync } from './memoize.js'\r\nexport type { MemoizeAsyncOptions } from './memoize.js'\r\n"],"mappings":"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","names":["result"]}

package/dist/collection/index.d.ts

@@ -71,5 +71,11 @@ declare function last<T>(items: T[]): T | undefined;
  */
 declare function isEmpty(value: unknown): boolean;
 type SortDirection = 'asc' | 'desc';
+declare function topoSort<T extends {
+    id: string;
+    dependencies?: string[];
+}>(items: T[]): T[];
+declare function slidingWindows<T>(items: T[], size: number, step?: number): T[][];
+declare function tumblingWindows<T>(items: T[], size: number): T[][];
 
-export { type SortDirection, chunk, first, flatten, groupBy, isEmpty, keyBy, last, omit, orderBy, pick, pluck, sample, sampleSize, shuffle, sortBy, uniq, uniqueBy };
+export { type SortDirection, chunk, first, flatten, groupBy, isEmpty, keyBy, last, omit, orderBy, pick, pluck, sample, sampleSize, shuffle, slidingWindows, sortBy, topoSort, tumblingWindows, uniq, uniqueBy };

package/dist/collection/index.js

@@ -118,6 +118,58 @@ function isEmpty(value) {
   if (value !== null && typeof value === "object") return Object.keys(value).length === 0;
   return false;
 }
+function topoSort(items) {
+  const adj = /* @__PURE__ */ new Map();
+  const inDegree = /* @__PURE__ */ new Map();
+  const itemMap = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    itemMap.set(item.id, item);
+    if (!adj.has(item.id)) adj.set(item.id, []);
+    if (!inDegree.has(item.id)) inDegree.set(item.id, 0);
+  }
+  for (const item of items) {
+    if (item.dependencies) {
+      for (const depId of item.dependencies) {
+        adj.get(depId)?.push(item.id);
+        inDegree.set(item.id, (inDegree.get(item.id) ?? 0) + 1);
+      }
+    }
+  }
+  const queue = [];
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id);
+  }
+  const sorted = [];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    sorted.push(id);
+    for (const neighbor of adj.get(id) ?? []) {
+      const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+      inDegree.set(neighbor, newDegree);
+      if (newDegree === 0) queue.push(neighbor);
+    }
+  }
+  if (sorted.length !== items.length) {
+    throw new Error("Circular dependency detected");
+  }
+  return sorted.map((id) => itemMap.get(id));
+}
+function slidingWindows(items, size, step = 1) {
+  if (size <= 0 || items.length === 0 || step <= 0) return [];
+  const result = [];
+  for (let i = 0; i + size <= items.length; i += step) {
+    result.push(items.slice(i, i + size));
+  }
+  return result;
+}
+function tumblingWindows(items, size) {
+  if (size <= 0 || items.length === 0) return [];
+  const result = [];
+  for (let i = 0; i < items.length; i += size) {
+    result.push(items.slice(i, i + size));
+  }
+  return result;
+}
 export {
   chunk,
   first,
@@ -133,7 +185,10 @@ export {
   sample,
   sampleSize,
   shuffle,
+  slidingWindows,
   sortBy,
+  topoSort,
+  tumblingWindows,
   uniq,
   uniqueBy
 };

package/dist/collection/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/collection/index.ts"],"sourcesContent":["/**\r\n * Groups an array of items by a key extracted from each item.\r\n *\r\n * @example groupBy([{ type: 'a' }, { type: 'b' }, { type: 'a' }], x => x.type)\r\n *          // => { a: [{ type: 'a' }, { type: 'a' }], b: [{ type: 'b' }] }\r\n */\r\nexport function groupBy<T, K extends string | number | symbol>(items: T[], keyFn: (item: T) => K): Record<K, T[]> {\r\n  const result = {} as Record<K, T[]>\r\n  for (const item of items) {\r\n    const key = keyFn(item)\r\n    if (!result[key]) result[key] = []\r\n    result[key]!.push(item)\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Creates an object keyed by the result of keyFn for each item.\r\n *\r\n * @example keyBy([{ id: 1, name: 'a' }, { id: 2, name: 'b' }], x => x.id)\r\n *          // => { 1: { id: 1, name: 'a' }, 2: { id: 2, name: 'b' } }\r\n */\r\nexport function keyBy<T, K extends string | number | symbol>(items: T[], keyFn: (item: T) => K): Record<K, T> {\r\n  const result = {} as Record<K, T>\r\n  for (const item of items) {\r\n    const key = keyFn(item)\r\n    result[key] = item\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns a copy of the object with the specified keys omitted.\r\n */\r\nexport function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K> {\r\n  const result = { ...obj } as T\r\n  for (const key of keys) {\r\n    delete result[key]\r\n  }\r\n  return result as Omit<T, K>\r\n}\r\n\r\n/**\r\n * Returns a copy of the object with only the specified keys.\r\n */\r\nexport function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {\r\n  const result = {} as Pick<T, K>\r\n  for (const key of keys) {\r\n    if (key in obj) {\r\n      result[key] = obj[key]\r\n    }\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Extracts a property value from each item in an array.\r\n */\r\nexport function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {\r\n  return items.map(item => item[key])\r\n}\r\n\r\n/**\r\n * Randomizes array order in-place using the Fisher-Yates algorithm.\r\n */\r\nexport function shuffle<T>(items: T[]): T[] {\r\n  const result = [...items]\r\n  for (let i = result.length - 1; i > 0; i--) {\r\n    const j = Math.floor(Math.random() * (i + 1))\r\n    const temp = result[i]!\r\n    result[i] = result[j]!\r\n    result[j] = temp\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns a random element from the array, or undefined if empty.\r\n */\r\nexport function sample<T>(items: T[]): T | undefined {\r\n  return items.length > 0 ? items[Math.floor(Math.random() * items.length)] : undefined\r\n}\r\n\r\n/**\r\n * Returns an array of `size` random elements (without duplicates).\r\n */\r\nexport function sampleSize<T>(items: T[], size: number): T[] {\r\n  if (size <= 0 || items.length === 0) return []\r\n  const pool = shuffle(items)\r\n  return pool.slice(0, Math.min(size, items.length))\r\n}\r\n\r\n/**\r\n * Splits an array into chunks of the specified size.\r\n */\r\nexport function chunk<T>(items: T[], size: number): T[][] {\r\n  if (size <= 0 || items.length === 0) return []\r\n  const result: T[][] = []\r\n  for (let i = 0; i < items.length; i += size) {\r\n    result.push(items.slice(i, i + size))\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns a sorted copy of the array using the provided criteria functions.\r\n * Earlier criteria take precedence.\r\n */\r\nfunction compareValues(a: unknown, b: unknown): number {\r\n  if (a === b) return 0\r\n  if (a == null) return -1\r\n  if (b == null) return 1\r\n  if (typeof a === 'string' && typeof b === 'string') return a < b ? -1 : 1\r\n  if (typeof a === 'number' && typeof b === 'number') return a < b ? -1 : 1\r\n  return String(a) < String(b) ? -1 : 1\r\n}\r\n\r\nexport function sortBy<T>(items: T[], ...criteria: Array<(item: T) => unknown>): T[] {\r\n  return [...items].sort((a, b) => {\r\n    for (const criterion of criteria) {\r\n      const cmp = compareValues(criterion(a), criterion(b))\r\n      if (cmp !== 0) return cmp\r\n    }\r\n    return 0\r\n  })\r\n}\r\n\r\n/**\r\n * Returns a sorted copy of the array by a single key and direction.\r\n */\r\nexport function orderBy<T>(items: T[], key: (item: T) => unknown, direction: SortDirection = 'asc'): T[] {\r\n  return [...items].sort((a, b) => {\r\n    const cmp = compareValues(key(a), key(b))\r\n    return direction === 'asc' ? cmp : -cmp\r\n  })\r\n}\r\n\r\n/**\r\n * Returns unique elements based on the result of keyFn.\r\n */\r\nexport function uniqueBy<T>(items: T[], keyFn: (item: T) => unknown): T[] {\r\n  const seen = new Set<unknown>()\r\n  return items.filter(item => {\r\n    const key = keyFn(item)\r\n    if (seen.has(key)) return false\r\n    seen.add(key)\r\n    return true\r\n  })\r\n}\r\n\r\n/**\r\n * Flattens an array of arrays one level.\r\n */\r\nexport function flatten<T>(items: T[][]): T[] {\r\n  const result: T[] = []\r\n  for (const sub of items) {\r\n    for (const item of sub) {\r\n      result.push(item)\r\n    }\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns an array with unique primitive values.\r\n */\r\nexport function uniq<T>(items: T[]): T[] {\r\n  return [...new Set(items)]\r\n}\r\n\r\n/**\r\n * Returns the first element, or undefined if empty.\r\n */\r\nexport function first<T>(items: T[]): T | undefined {\r\n  return items[0]\r\n}\r\n\r\n/**\r\n * Returns the last element, or undefined if empty.\r\n */\r\nexport function last<T>(items: T[]): T | undefined {\r\n  return items[items.length - 1]\r\n}\r\n\r\n/**\r\n * Checks if a value is empty.\r\n * Works for arrays, objects, strings, Map, and Set.\r\n */\r\nexport function isEmpty(value: unknown): boolean {\r\n  if (Array.isArray(value)) return value.length === 0\r\n  if (typeof value === 'string') return value.length === 0\r\n  if (value instanceof Map || value instanceof Set) return value.size === 0\r\n  if (value !== null && typeof value === 'object') return Object.keys(value as Record<string, unknown>).length === 0\r\n  return false\r\n}\r\n\r\nexport type SortDirection = 'asc' | 'desc'\r\n"],"mappings":";AAMO,SAAS,QAA+C,OAAY,OAAuC;AAChH,QAAM,SAAS,CAAC;AAChB,aAAW,QAAQ,OAAO;AACxB,UAAM,MAAM,MAAM,IAAI;AACtB,QAAI,CAAC,OAAO,GAAG,EAAG,QAAO,GAAG,IAAI,CAAC;AACjC,WAAO,GAAG,EAAG,KAAK,IAAI;AAAA,EACxB;AACA,SAAO;AACT;AAQO,SAAS,MAA6C,OAAY,OAAqC;AAC5G,QAAM,SAAS,CAAC;AAChB,aAAW,QAAQ,OAAO;AACxB,UAAM,MAAM,MAAM,IAAI;AACtB,WAAO,GAAG,IAAI;AAAA,EAChB;AACA,SAAO;AACT;AAKO,SAAS,KAA2D,KAAQ,MAAuB;AACxG,QAAM,SAAS,EAAE,GAAG,IAAI;AACxB,aAAW,OAAO,MAAM;AACtB,WAAO,OAAO,GAAG;AAAA,EACnB;AACA,SAAO;AACT;AAKO,SAAS,KAA2D,KAAQ,MAAuB;AACxG,QAAM,SAAS,CAAC;AAChB,aAAW,OAAO,MAAM;AACtB,QAAI,OAAO,KAAK;AACd,aAAO,GAAG,IAAI,IAAI,GAAG;AAAA,IACvB;AAAA,EACF;AACA,SAAO;AACT;AAKO,SAAS,MAA4B,OAAY,KAAgB;AACtE,SAAO,MAAM,IAAI,UAAQ,KAAK,GAAG,CAAC;AACpC;AAKO,SAAS,QAAW,OAAiB;AAC1C,QAAM,SAAS,CAAC,GAAG,KAAK;AACxB,WAAS,IAAI,OAAO,SAAS,GAAG,IAAI,GAAG,KAAK;AAC1C,UAAM,IAAI,KAAK,MAAM,KAAK,OAAO,KAAK,IAAI,EAAE;AAC5C,UAAM,OAAO,OAAO,CAAC;AACrB,WAAO,CAAC,IAAI,OAAO,CAAC;AACpB,WAAO,CAAC,IAAI;AAAA,EACd;AACA,SAAO;AACT;AAKO,SAAS,OAAU,OAA2B;AACnD,SAAO,MAAM,SAAS,IAAI,MAAM,KAAK,MAAM,KAAK,OAAO,IAAI,MAAM,MAAM,CAAC,IAAI;AAC9E;AAKO,SAAS,WAAc,OAAY,MAAmB;AAC3D,MAAI,QAAQ,KAAK,MAAM,WAAW,EAAG,QAAO,CAAC;AAC7C,QAAM,OAAO,QAAQ,KAAK;AAC1B,SAAO,KAAK,MAAM,GAAG,KAAK,IAAI,MAAM,MAAM,MAAM,CAAC;AACnD;AAKO,SAAS,MAAS,OAAY,MAAqB;AACxD,MAAI,QAAQ,KAAK,MAAM,WAAW,EAAG,QAAO,CAAC;AAC7C,QAAM,SAAgB,CAAC;AACvB,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,MAAM;AAC3C,WAAO,KAAK,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC;AAAA,EACtC;AACA,SAAO;AACT;AAMA,SAAS,cAAc,GAAY,GAAoB;AACrD,MAAI,MAAM,EAAG,QAAO;AACpB,MAAI,KAAK,KAAM,QAAO;AACtB,MAAI,KAAK,KAAM,QAAO;AACtB,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,SAAU,QAAO,IAAI,IAAI,KAAK;AACxE,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,SAAU,QAAO,IAAI,IAAI,KAAK;AACxE,SAAO,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK;AACtC;AAEO,SAAS,OAAU,UAAe,UAA4C;AACnF,SAAO,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM;AAC/B,eAAW,aAAa,UAAU;AAChC,YAAM,MAAM,cAAc,UAAU,CAAC,GAAG,UAAU,CAAC,CAAC;AACpD,UAAI,QAAQ,EAAG,QAAO;AAAA,IACxB;AACA,WAAO;AAAA,EACT,CAAC;AACH;AAKO,SAAS,QAAW,OAAY,KAA2B,YAA2B,OAAY;AACvG,SAAO,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM;AAC/B,UAAM,MAAM,cAAc,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;AACxC,WAAO,cAAc,QAAQ,MAAM,CAAC;AAAA,EACtC,CAAC;AACH;AAKO,SAAS,SAAY,OAAY,OAAkC;AACxE,QAAM,OAAO,oBAAI,IAAa;AAC9B,SAAO,MAAM,OAAO,UAAQ;AAC1B,UAAM,MAAM,MAAM,IAAI;AACtB,QAAI,KAAK,IAAI,GAAG,EAAG,QAAO;AAC1B,SAAK,IAAI,GAAG;AACZ,WAAO;AAAA,EACT,CAAC;AACH;AAKO,SAAS,QAAW,OAAmB;AAC5C,QAAM,SAAc,CAAC;AACrB,aAAW,OAAO,OAAO;AACvB,eAAW,QAAQ,KAAK;AACtB,aAAO,KAAK,IAAI;AAAA,IAClB;AAAA,EACF;AACA,SAAO;AACT;AAKO,SAAS,KAAQ,OAAiB;AACvC,SAAO,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC;AAC3B;AAKO,SAAS,MAAS,OAA2B;AAClD,SAAO,MAAM,CAAC;AAChB;AAKO,SAAS,KAAQ,OAA2B;AACjD,SAAO,MAAM,MAAM,SAAS,CAAC;AAC/B;AAMO,SAAS,QAAQ,OAAyB;AAC/C,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,WAAW;AAClD,MAAI,OAAO,UAAU,SAAU,QAAO,MAAM,WAAW;AACvD,MAAI,iBAAiB,OAAO,iBAAiB,IAAK,QAAO,MAAM,SAAS;AACxE,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO,OAAO,KAAK,KAAgC,EAAE,WAAW;AACjH,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/collection/index.ts"],"sourcesContent":["/**\r\n * Groups an array of items by a key extracted from each item.\r\n *\r\n * @example groupBy([{ type: 'a' }, { type: 'b' }, { type: 'a' }], x => x.type)\r\n *          // => { a: [{ type: 'a' }, { type: 'a' }], b: [{ type: 'b' }] }\r\n */\r\nexport function groupBy<T, K extends string | number | symbol>(items: T[], keyFn: (item: T) => K): Record<K, T[]> {\r\n  const result = {} as Record<K, T[]>\r\n  for (const item of items) {\r\n    const key = keyFn(item)\r\n    if (!result[key]) result[key] = []\r\n    result[key]!.push(item)\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Creates an object keyed by the result of keyFn for each item.\r\n *\r\n * @example keyBy([{ id: 1, name: 'a' }, { id: 2, name: 'b' }], x => x.id)\r\n *          // => { 1: { id: 1, name: 'a' }, 2: { id: 2, name: 'b' } }\r\n */\r\nexport function keyBy<T, K extends string | number | symbol>(items: T[], keyFn: (item: T) => K): Record<K, T> {\r\n  const result = {} as Record<K, T>\r\n  for (const item of items) {\r\n    const key = keyFn(item)\r\n    result[key] = item\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns a copy of the object with the specified keys omitted.\r\n */\r\nexport function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K> {\r\n  const result = { ...obj } as T\r\n  for (const key of keys) {\r\n    delete result[key]\r\n  }\r\n  return result as Omit<T, K>\r\n}\r\n\r\n/**\r\n * Returns a copy of the object with only the specified keys.\r\n */\r\nexport function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {\r\n  const result = {} as Pick<T, K>\r\n  for (const key of keys) {\r\n    if (key in obj) {\r\n      result[key] = obj[key]\r\n    }\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Extracts a property value from each item in an array.\r\n */\r\nexport function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {\r\n  return items.map(item => item[key])\r\n}\r\n\r\n/**\r\n * Randomizes array order in-place using the Fisher-Yates algorithm.\r\n */\r\nexport function shuffle<T>(items: T[]): T[] {\r\n  const result = [...items]\r\n  for (let i = result.length - 1; i > 0; i--) {\r\n    const j = Math.floor(Math.random() * (i + 1))\r\n    const temp = result[i]!\r\n    result[i] = result[j]!\r\n    result[j] = temp\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns a random element from the array, or undefined if empty.\r\n */\r\nexport function sample<T>(items: T[]): T | undefined {\r\n  return items.length > 0 ? items[Math.floor(Math.random() * items.length)] : undefined\r\n}\r\n\r\n/**\r\n * Returns an array of `size` random elements (without duplicates).\r\n */\r\nexport function sampleSize<T>(items: T[], size: number): T[] {\r\n  if (size <= 0 || items.length === 0) return []\r\n  const pool = shuffle(items)\r\n  return pool.slice(0, Math.min(size, items.length))\r\n}\r\n\r\n/**\r\n * Splits an array into chunks of the specified size.\r\n */\r\nexport function chunk<T>(items: T[], size: number): T[][] {\r\n  if (size <= 0 || items.length === 0) return []\r\n  const result: T[][] = []\r\n  for (let i = 0; i < items.length; i += size) {\r\n    result.push(items.slice(i, i + size))\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns a sorted copy of the array using the provided criteria functions.\r\n * Earlier criteria take precedence.\r\n */\r\nfunction compareValues(a: unknown, b: unknown): number {\r\n  if (a === b) return 0\r\n  if (a == null) return -1\r\n  if (b == null) return 1\r\n  if (typeof a === 'string' && typeof b === 'string') return a < b ? -1 : 1\r\n  if (typeof a === 'number' && typeof b === 'number') return a < b ? -1 : 1\r\n  return String(a) < String(b) ? -1 : 1\r\n}\r\n\r\nexport function sortBy<T>(items: T[], ...criteria: Array<(item: T) => unknown>): T[] {\r\n  return [...items].sort((a, b) => {\r\n    for (const criterion of criteria) {\r\n      const cmp = compareValues(criterion(a), criterion(b))\r\n      if (cmp !== 0) return cmp\r\n    }\r\n    return 0\r\n  })\r\n}\r\n\r\n/**\r\n * Returns a sorted copy of the array by a single key and direction.\r\n */\r\nexport function orderBy<T>(items: T[], key: (item: T) => unknown, direction: SortDirection = 'asc'): T[] {\r\n  return [...items].sort((a, b) => {\r\n    const cmp = compareValues(key(a), key(b))\r\n    return direction === 'asc' ? cmp : -cmp\r\n  })\r\n}\r\n\r\n/**\r\n * Returns unique elements based on the result of keyFn.\r\n */\r\nexport function uniqueBy<T>(items: T[], keyFn: (item: T) => unknown): T[] {\r\n  const seen = new Set<unknown>()\r\n  return items.filter(item => {\r\n    const key = keyFn(item)\r\n    if (seen.has(key)) return false\r\n    seen.add(key)\r\n    return true\r\n  })\r\n}\r\n\r\n/**\r\n * Flattens an array of arrays one level.\r\n */\r\nexport function flatten<T>(items: T[][]): T[] {\r\n  const result: T[] = []\r\n  for (const sub of items) {\r\n    for (const item of sub) {\r\n      result.push(item)\r\n    }\r\n  }\r\n  return result\r\n}\r\n\r\n/**\r\n * Returns an array with unique primitive values.\r\n */\r\nexport function uniq<T>(items: T[]): T[] {\r\n  return [...new Set(items)]\r\n}\r\n\r\n/**\r\n * Returns the first element, or undefined if empty.\r\n */\r\nexport function first<T>(items: T[]): T | undefined {\r\n  return items[0]\r\n}\r\n\r\n/**\r\n * Returns the last element, or undefined if empty.\r\n */\r\nexport function last<T>(items: T[]): T | undefined {\r\n  return items[items.length - 1]\r\n}\r\n\r\n/**\r\n * Checks if a value is empty.\r\n * Works for arrays, objects, strings, Map, and Set.\r\n */\r\nexport function isEmpty(value: unknown): boolean {\r\n  if (Array.isArray(value)) return value.length === 0\r\n  if (typeof value === 'string') return value.length === 0\r\n  if (value instanceof Map || value instanceof Set) return value.size === 0\r\n  if (value !== null && typeof value === 'object') return Object.keys(value as Record<string, unknown>).length === 0\r\n  return false\r\n}\r\n\r\nexport type SortDirection = 'asc' | 'desc'\r\n\r\nexport function topoSort<T extends { id: string; dependencies?: string[] }>(items: T[]): T[] {\r\n  const adj = new Map<string, string[]>()\r\n  const inDegree = new Map<string, number>()\r\n  const itemMap = new Map<string, T>()\r\n\r\n  for (const item of items) {\r\n    itemMap.set(item.id, item)\r\n    if (!adj.has(item.id)) adj.set(item.id, [])\r\n    if (!inDegree.has(item.id)) inDegree.set(item.id, 0)\r\n  }\r\n\r\n  for (const item of items) {\r\n    if (item.dependencies) {\r\n      for (const depId of item.dependencies) {\r\n        adj.get(depId)?.push(item.id)\r\n        inDegree.set(item.id, (inDegree.get(item.id) ?? 0) + 1)\r\n      }\r\n    }\r\n  }\r\n\r\n  const queue: string[] = []\r\n  for (const [id, degree] of inDegree) {\r\n    if (degree === 0) queue.push(id)\r\n  }\r\n\r\n  const sorted: string[] = []\r\n  while (queue.length > 0) {\r\n    const id = queue.shift()!\r\n    sorted.push(id)\r\n    for (const neighbor of adj.get(id) ?? []) {\r\n      const newDegree = (inDegree.get(neighbor) ?? 1) - 1\r\n      inDegree.set(neighbor, newDegree)\r\n      if (newDegree === 0) queue.push(neighbor)\r\n    }\r\n  }\r\n\r\n  if (sorted.length !== items.length) {\r\n    throw new Error('Circular dependency detected')\r\n  }\r\n\r\n  return sorted.map(id => itemMap.get(id)!)\r\n}\r\n\r\nexport function slidingWindows<T>(items: T[], size: number, step: number = 1): T[][] {\r\n  if (size <= 0 || items.length === 0 || step <= 0) return []\r\n  const result: T[][] = []\r\n  for (let i = 0; i + size <= items.length; i += step) {\r\n    result.push(items.slice(i, i + size))\r\n  }\r\n  return result\r\n}\r\n\r\nexport function tumblingWindows<T>(items: T[], size: number): T[][] {\r\n  if (size <= 0 || items.length === 0) return []\r\n  const result: T[][] = []\r\n  for (let i = 0; i < items.length; i += size) {\r\n    result.push(items.slice(i, i + size))\r\n  }\r\n  return result\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/date/index.d.ts

@@ -199,5 +199,75 @@ declare function addBusinessDays(date: Date, days: number): Date;
  * @throws {InvalidDateError} If the birth date is invalid.
  */
 declare function calculateAge(birthDate: Date): number;
+/**
+ * Returns a human-readable relative time string (e.g. "5 menit yang lalu").
+ *
+ * @param date - The past date.
+ * @param options - Options with locale ('id' by default, 'en' supported).
+ * @returns A relative time string.
+ */
+declare function timeAgo(date: Date, options?: {
+    locale?: string;
+}): string;
+/**
+ * Shows the time remaining until a future date.
+ *
+ * @param target - The target future date.
+ * @param options - Options with locale ('id' by default, 'en' supported).
+ * @returns A relative time string.
+ */
+declare function timeRemaining(target: Date, options?: {
+    locale?: string;
+}): string;
+/**
+ * Represents a duration split into calendar and time components.
+ */
+interface Duration {
+    years: number;
+    months: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+/**
+ * Formats a Duration object into a human-readable string.
+ *
+ * @example
+ * formatDuration({ hours: 2, minutes: 30, seconds: 15 }) // "2 jam 30 menit 15 detik"
+ * formatDuration({ hours: 2, minutes: 30 }, { locale: 'en' }) // "2 hours 30 minutes"
+ *
+ * @param duration - The duration to format.
+ * @param options - Options with locale ('id' by default, 'en' supported).
+ * @returns A formatted duration string.
+ */
+declare function formatDuration(duration: Duration, options?: {
+    locale?: string;
+}): string;
+/** UTC+7 — Western Indonesia Time (WIB). */
+declare const TIMEZONE_WIB = 7;
+/** UTC+8 — Central Indonesia Time (WITA). */
+declare const TIMEZONE_WITA = 8;
+/** UTC+9 — Eastern Indonesia Time (WIT). */
+declare const TIMEZONE_WIT = 9;
+/**
+ * Converts a date to a specific timezone offset by returning a new Date whose
+ * local-time getters (getHours, getMinutes etc.) reflect the target timezone.
+ *
+ * @param date - The source date.
+ * @param offsetHours - The timezone offset in hours (e.g. 7 for WIB).
+ * @returns A new Date adjusted to the target timezone.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function toTimezone(date: Date, offsetHours: number): Date;
+/**
+ * Formats a date in a specific timezone using `formatDate` tokens.
+ *
+ * @param date - The source date.
+ * @param format - The format string (see `formatDate` for supported tokens).
+ * @param offsetHours - The timezone offset in hours.
+ * @returns The formatted date string.
+ */
+declare function formatInTimezone(date: Date, format: string, offsetHours: number): string;
 
-export { type DateDiff, InvalidDateError, addBusinessDays, addDays, addMonths, addYears, calculateAge, dateDiff, endOfDay, endOfMonth, endOfYear, formatDate, isAfter, isBefore, isBetween, isBusinessDay, isLeapYear, isWeekend, parseDate, startOfDay, startOfMonth, startOfYear };
+export { type DateDiff, type Duration, InvalidDateError, TIMEZONE_WIB, TIMEZONE_WIT, TIMEZONE_WITA, addBusinessDays, addDays, addMonths, addYears, calculateAge, dateDiff, endOfDay, endOfMonth, endOfYear, formatDate, formatDuration, formatInTimezone, isAfter, isBefore, isBetween, isBusinessDay, isLeapYear, isWeekend, parseDate, startOfDay, startOfMonth, startOfYear, timeAgo, timeRemaining, toTimezone };

package/dist/date/index.js

@@ -253,8 +253,123 @@ function calculateAge(birthDate) {
   }
   return age;
 }
+var LOCALE_LABELS = {
+  id: {
+    years: { single: "tahun", plural: "tahun" },
+    months: { single: "bulan", plural: "bulan" },
+    weeks: { single: "minggu", plural: "minggu" },
+    days: { single: "hari", plural: "hari" },
+    hours: { single: "jam", plural: "jam" },
+    minutes: { single: "menit", plural: "menit" },
+    seconds: { single: "detik", plural: "detik" }
+  },
+  en: {
+    years: { single: "year", plural: "years" },
+    months: { single: "month", plural: "months" },
+    weeks: { single: "week", plural: "weeks" },
+    days: { single: "day", plural: "days" },
+    hours: { single: "hour", plural: "hours" },
+    minutes: { single: "minute", plural: "minutes" },
+    seconds: { single: "second", plural: "seconds" }
+  }
+};
+function getSuffix(diffMs, kind, locale) {
+  if (diffMs < 0) {
+    return locale === "en" ? "ago" : "yang lalu";
+  }
+  if (kind === "remaining") {
+    return locale === "en" ? "remaining" : "lagi";
+  }
+  return locale === "en" ? "ago" : "yang lalu";
+}
+function formatRelativeTime(absDiffMs, suffix, locale) {
+  const labels = LOCALE_LABELS[locale] ?? LOCALE_LABELS.id;
+  const seconds = Math.floor(absDiffMs / 1e3);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  const weeks = Math.floor(days / 7);
+  const months = Math.floor(days / 30.4375);
+  const years = Math.floor(days / 365.25);
+  let count;
+  let unit;
+  if (years >= 1) {
+    count = years;
+    unit = "years";
+  } else if (months >= 1) {
+    count = months;
+    unit = "months";
+  } else if (weeks >= 1) {
+    count = weeks;
+    unit = "weeks";
+  } else if (days >= 1) {
+    count = days;
+    unit = "days";
+  } else if (hours >= 1) {
+    count = hours;
+    unit = "hours";
+  } else if (minutes >= 1) {
+    count = minutes;
+    unit = "minutes";
+  } else {
+    count = Math.max(1, seconds);
+    unit = "seconds";
+  }
+  const label = count === 1 ? labels[unit].single : labels[unit].plural;
+  return `${count} ${label} ${suffix}`;
+}
+function timeAgo(date, options) {
+  const diff = Date.now() - date.getTime();
+  const locale = options?.locale ?? "id";
+  const suffix = getSuffix(diff, "ago", locale);
+  return formatRelativeTime(Math.abs(diff), suffix, locale);
+}
+function timeRemaining(target, options) {
+  const diff = target.getTime() - Date.now();
+  const locale = options?.locale ?? "id";
+  const suffix = getSuffix(diff, "remaining", locale);
+  return formatRelativeTime(Math.abs(diff), suffix, locale);
+}
+function formatDuration(duration, options) {
+  const locale = options?.locale ?? "id";
+  const labels = LOCALE_LABELS[locale] ?? LOCALE_LABELS.id;
+  const parts = [];
+  const entries = [
+    ["years", duration.years],
+    ["months", duration.months],
+    ["days", duration.days],
+    ["hours", duration.hours],
+    ["minutes", duration.minutes],
+    ["seconds", duration.seconds]
+  ];
+  for (const [key, value] of entries) {
+    if (value > 0) {
+      const label = value === 1 ? labels[key].single : labels[key].plural;
+      parts.push(`${value} ${label}`);
+    }
+  }
+  if (parts.length === 0) {
+    const label = labels.seconds.plural;
+    return `0 ${label}`;
+  }
+  return parts.join(" ");
+}
+var TIMEZONE_WIB = 7;
+var TIMEZONE_WITA = 8;
+var TIMEZONE_WIT = 9;
+function toTimezone(date, offsetHours) {
+  if (!isValidDate(date)) throw new InvalidDateError(date);
+  const utcMs = date.getTime() + date.getTimezoneOffset() * 6e4;
+  return new Date(utcMs + offsetHours * 36e5);
+}
+function formatInTimezone(date, format, offsetHours) {
+  return formatDate(toTimezone(date, offsetHours), format);
+}
 export {
   InvalidDateError,
+  TIMEZONE_WIB,
+  TIMEZONE_WIT,
+  TIMEZONE_WITA,
   addBusinessDays,
   addDays,
   addMonths,
@@ -265,6 +380,8 @@ export {
   endOfMonth,
   endOfYear,
   formatDate,
+  formatDuration,
+  formatInTimezone,
   isAfter,
   isBefore,
   isBetween,
@@ -274,6 +391,9 @@ export {
   parseDate,
   startOfDay,
   startOfMonth,
-  startOfYear
+  startOfYear,
+  timeAgo,
+  timeRemaining,
+  toTimezone
 };
 //# sourceMappingURL=index.js.map