qznt 2.1.1 → 2.2.1

package/dist/index.cjs

@@ -63,6 +63,7 @@ __export(index_exports, {
   isSortedArray: () => isSortedArray,
   isString: () => isString,
   isToday: () => isToday,
+  keyedQueue: () => keyedQueue,
   lerp: () => lerp,
   memoize: () => memoize,
   merge: () => merge,
@@ -604,6 +605,24 @@ function unique(array, key) {
 }
 
 // src/async.ts
+function keyedQueue() {
+  const queues = /* @__PURE__ */ new Map();
+  return {
+    run(key, work) {
+      const previous = queues.get(key) ?? Promise.resolve();
+      const result = previous.then(work);
+      const release = () => {
+        if (queues.get(key) === tail) queues.delete(key);
+      };
+      const tail = result.then(release, release);
+      queues.set(key, tail);
+      return result;
+    },
+    get size() {
+      return queues.size;
+    }
+  };
+}
 async function retryPromise(fn, options = {}) {
   const { attempts = 3, delay = 500, timeout, signal } = options;
   if (signal?.aborted) throw new Error("Operation aborted");
@@ -719,9 +738,28 @@ function throttle(fn, limit) {
 function memoize(fn, options = {}) {
   const cache = /* @__PURE__ */ new Map();
   const { resolver, maxAge } = options;
+  let lastSweep = Date.now();
+  const getKey = (...args) => resolver ? resolver(...args) : JSON.stringify(args);
+  const sweep = (now) => {
+    if (!maxAge || now - lastSweep < maxAge) return;
+    lastSweep = now;
+    for (const [key, entry] of cache) {
+      if (now - entry.timestamp >= maxAge) cache.delete(key);
+    }
+  };
+  const cacheValue = (key, value, timestamp) => {
+    const entry = { value, timestamp };
+    cache.set(key, entry);
+    if (value !== null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function") {
+      void Promise.resolve(value).catch(() => {
+        if (cache.get(key) === entry) cache.delete(key);
+      });
+    }
+  };
   const memoized = function(...args) {
-    const key = resolver ? resolver(...args) : JSON.stringify(args);
+    const key = getKey(...args);
     const now = Date.now();
+    sweep(now);
     const entry = cache.get(key);
     if (entry) {
       if (!maxAge || now - entry.timestamp < maxAge) {
@@ -730,10 +768,17 @@ function memoize(fn, options = {}) {
       cache.delete(key);
     }
     const result = fn.apply(this, args);
-    cache.set(key, { value: result, timestamp: now });
+    cacheValue(key, result, now);
     return result;
   };
   memoized.clear = () => cache.clear();
+  memoized.delete = (...args) => cache.delete(getKey(...args));
+  memoized.set = (value, ...args) => {
+    const key = getKey(...args);
+    const now = Date.now();
+    sweep(now);
+    cacheValue(key, value, now);
+  };
   return memoized;
 }
 
@@ -784,7 +829,7 @@ function formatDuration(target, style = "hms", options = {}) {
   if (diff === 0) return style === "digital" ? "00:00" : "now";
   const s = Math.floor(diff / 1e3) % 60;
   const m = Math.floor(diff / 6e4) % 60;
-  const h = Math.floor(diff / 36e5) % 24;
+  const h = style === "hms" ? Math.floor(diff / 36e5) : Math.floor(diff / 36e5) % 24;
   const d = Math.floor(diff / 864e5);
   if (style === "digital") {
     const parts = [m, s].map((v) => String(v).padStart(2, "0"));
@@ -1080,6 +1125,7 @@ function toTitleCase(str, smart = true) {
   isSortedArray,
   isString,
   isToday,
+  keyedQueue,
   lerp,
   memoize,
   merge,

package/dist/index.d.cts

@@ -208,6 +208,20 @@ interface RetryOptions {
     /** An AbortSignal to cancel the entire operation. */
     signal?: AbortSignal;
 }
+/**
+ * Creates a queue that runs tasks in call order for each key, while different keys run concurrently.
+ * Task errors reach their callers without blocking later tasks. Drained keys are removed automatically.
+ * @example
+ * const queue = keyedQueue();
+ * const first = queue.run("user-1", () => saveInventory("user-1"));
+ * const second = queue.run("user-1", () => readInventory("user-1"));
+ * await Promise.all([first, second]); // The read runs after the save finishes
+ * console.log(queue.size); // 0 active keys
+ */
+declare function keyedQueue(): {
+    run<T>(key: string | number, work: () => T | Promise<T>): Promise<T>;
+    readonly size: number;
+};
 /**
  * Retries an async function until the maximum number of attempts is reached.
  *
@@ -275,17 +289,23 @@ declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, wait
  */
 declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
 
-interface MemoizedFunction<T extends (...args: any[]) => any> {
+interface MemoizedFunction<T extends (...args: never[]) => unknown> {
     (...args: Parameters<T>): ReturnType<T>;
     /** Clears the cache. */
     clear: () => void;
+    /** Removes the entry for these arguments, returning whether it existed. */
+    delete: (...args: Parameters<T>) => boolean;
+    /** Caches a value for these arguments, starting a fresh TTL. */
+    set: (value: ReturnType<T>, ...args: Parameters<T>) => void;
 }
 /**
  * Memoizes a function by caching its results based on the input arguments.
  * A resolver function can be provided to customize the key generation.
  * If no resolver is provided, the key will be generated by JSON stringify-ing the input arguments.
+ * Rejected promises are evicted. Expired entries are swept lazily on calls and writes,
+ * at most once per maxAge interval; no cleanup timers are created.
  * @param fn The function to memoize
- * @param resolver An optional resolver function to customize the key generation
+ * @param options Optional key resolver and cache lifetime in milliseconds
  * @example
  * // 1. Basic usage
  * const heavyCalc = memoize((n: number) => {
@@ -306,8 +326,14 @@ interface MemoizedFunction<T extends (...args: any[]) => any> {
  * @example
  * // 4. Manual cache clearing
  * heavyCalc.clear();
+ * @example
+ * // 5. Seed or invalidate one entry using the original arguments
+ * const getFlag = memoize(async (id: string) => readFlag(id));
+ * await writeFlag("drops", true);
+ * getFlag.set(Promise.resolve(true), "drops");
+ * getFlag.delete("drops");
  */
-declare function memoize<T extends (...args: any[]) => any>(fn: T, options?: {
+declare function memoize<T extends (...args: never[]) => unknown>(fn: T, options?: {
     /** Function to generate a cache key from the input arguments. */
     resolver?: (...args: Parameters<T>) => string;
     /** The time to wait in milliseconds before expiring a cache entry. */
@@ -368,9 +394,9 @@ declare function FormatNumberCompact(num: number, locale?: Intl.LocalesArgument)
  * Duration formatter.
  *
  * Available styles:
- * - Digital (00:00)
- * - HMS
- * - YMDHMS.
+ * - "digital": MM:SS, HH:MM:SS, or D:HH:MM:SS.
+ * - "hms": hours, minutes, and seconds, with total hours that can exceed 23.
+ * - "ymdhms": days, hours, minutes, and seconds, with hours capped at 23.
  * @param target The target time to calculate from
  * @param style The output style to use
  * @param options Formatting options
@@ -673,4 +699,4 @@ declare function pluralize(count: number, singular: string, plural?: string): st
  */
 declare function toTitleCase(str: string, smart?: boolean): string;
 
-export { type AlphaCasing, type AnyFunc, Cache, type DebouncedFunction, type DeepPartial, type FormatDurationOptions, FormatNumberCompact, Loop, type LoopEvents, type MemoizedFunction, type ParseTimeOptions, Pipe, type ReadDirOptions, type RetryOptions, type RndArrayOptions, type RndStrOptions, type SequentialMapContext, Storage, type TypedEmitter, chunk, chunkAdj, clampNumber, cluster, compactArray, createSampler, debounce, escapeRegex, forceArray, formatCurrency, formatDuration, formatETA, formatMemory, formatNumber, formatOrdinal, getAge, getFlag, getProp, hasFlag, hasProp, inverseLerp, isDefined, isEmpty, isInRange, isObject, isSortedArray, isString, isToday, lerp, memoize, merge, msToSecs, omit, parseTime, percent, pick, pluralize, prng, readDir, remap, retryPromise, rndChance, rndChoice, rndFloat, rndIndex, rndInt, rndString, searchSorted, secsToMs, seqMap, setProp, shuffle, sortBy, sum, throttle, toTitleCase, unique, wait, weightedRnd, wrap };
+export { type AlphaCasing, type AnyFunc, Cache, type DebouncedFunction, type DeepPartial, type FormatDurationOptions, FormatNumberCompact, Loop, type LoopEvents, type MemoizedFunction, type ParseTimeOptions, Pipe, type ReadDirOptions, type RetryOptions, type RndArrayOptions, type RndStrOptions, type SequentialMapContext, Storage, type TypedEmitter, chunk, chunkAdj, clampNumber, cluster, compactArray, createSampler, debounce, escapeRegex, forceArray, formatCurrency, formatDuration, formatETA, formatMemory, formatNumber, formatOrdinal, getAge, getFlag, getProp, hasFlag, hasProp, inverseLerp, isDefined, isEmpty, isInRange, isObject, isSortedArray, isString, isToday, keyedQueue, lerp, memoize, merge, msToSecs, omit, parseTime, percent, pick, pluralize, prng, readDir, remap, retryPromise, rndChance, rndChoice, rndFloat, rndIndex, rndInt, rndString, searchSorted, secsToMs, seqMap, setProp, shuffle, sortBy, sum, throttle, toTitleCase, unique, wait, weightedRnd, wrap };

package/dist/index.d.ts

@@ -208,6 +208,20 @@ interface RetryOptions {
     /** An AbortSignal to cancel the entire operation. */
     signal?: AbortSignal;
 }
+/**
+ * Creates a queue that runs tasks in call order for each key, while different keys run concurrently.
+ * Task errors reach their callers without blocking later tasks. Drained keys are removed automatically.
+ * @example
+ * const queue = keyedQueue();
+ * const first = queue.run("user-1", () => saveInventory("user-1"));
+ * const second = queue.run("user-1", () => readInventory("user-1"));
+ * await Promise.all([first, second]); // The read runs after the save finishes
+ * console.log(queue.size); // 0 active keys
+ */
+declare function keyedQueue(): {
+    run<T>(key: string | number, work: () => T | Promise<T>): Promise<T>;
+    readonly size: number;
+};
 /**
  * Retries an async function until the maximum number of attempts is reached.
  *
@@ -275,17 +289,23 @@ declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, wait
  */
 declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
 
-interface MemoizedFunction<T extends (...args: any[]) => any> {
+interface MemoizedFunction<T extends (...args: never[]) => unknown> {
     (...args: Parameters<T>): ReturnType<T>;
     /** Clears the cache. */
     clear: () => void;
+    /** Removes the entry for these arguments, returning whether it existed. */
+    delete: (...args: Parameters<T>) => boolean;
+    /** Caches a value for these arguments, starting a fresh TTL. */
+    set: (value: ReturnType<T>, ...args: Parameters<T>) => void;
 }
 /**
  * Memoizes a function by caching its results based on the input arguments.
  * A resolver function can be provided to customize the key generation.
  * If no resolver is provided, the key will be generated by JSON stringify-ing the input arguments.
+ * Rejected promises are evicted. Expired entries are swept lazily on calls and writes,
+ * at most once per maxAge interval; no cleanup timers are created.
  * @param fn The function to memoize
- * @param resolver An optional resolver function to customize the key generation
+ * @param options Optional key resolver and cache lifetime in milliseconds
  * @example
  * // 1. Basic usage
  * const heavyCalc = memoize((n: number) => {
@@ -306,8 +326,14 @@ interface MemoizedFunction<T extends (...args: any[]) => any> {
  * @example
  * // 4. Manual cache clearing
  * heavyCalc.clear();
+ * @example
+ * // 5. Seed or invalidate one entry using the original arguments
+ * const getFlag = memoize(async (id: string) => readFlag(id));
+ * await writeFlag("drops", true);
+ * getFlag.set(Promise.resolve(true), "drops");
+ * getFlag.delete("drops");
  */
-declare function memoize<T extends (...args: any[]) => any>(fn: T, options?: {
+declare function memoize<T extends (...args: never[]) => unknown>(fn: T, options?: {
     /** Function to generate a cache key from the input arguments. */
     resolver?: (...args: Parameters<T>) => string;
     /** The time to wait in milliseconds before expiring a cache entry. */
@@ -368,9 +394,9 @@ declare function FormatNumberCompact(num: number, locale?: Intl.LocalesArgument)
  * Duration formatter.
  *
  * Available styles:
- * - Digital (00:00)
- * - HMS
- * - YMDHMS.
+ * - "digital": MM:SS, HH:MM:SS, or D:HH:MM:SS.
+ * - "hms": hours, minutes, and seconds, with total hours that can exceed 23.
+ * - "ymdhms": days, hours, minutes, and seconds, with hours capped at 23.
  * @param target The target time to calculate from
  * @param style The output style to use
  * @param options Formatting options
@@ -673,4 +699,4 @@ declare function pluralize(count: number, singular: string, plural?: string): st
  */
 declare function toTitleCase(str: string, smart?: boolean): string;
 
-export { type AlphaCasing, type AnyFunc, Cache, type DebouncedFunction, type DeepPartial, type FormatDurationOptions, FormatNumberCompact, Loop, type LoopEvents, type MemoizedFunction, type ParseTimeOptions, Pipe, type ReadDirOptions, type RetryOptions, type RndArrayOptions, type RndStrOptions, type SequentialMapContext, Storage, type TypedEmitter, chunk, chunkAdj, clampNumber, cluster, compactArray, createSampler, debounce, escapeRegex, forceArray, formatCurrency, formatDuration, formatETA, formatMemory, formatNumber, formatOrdinal, getAge, getFlag, getProp, hasFlag, hasProp, inverseLerp, isDefined, isEmpty, isInRange, isObject, isSortedArray, isString, isToday, lerp, memoize, merge, msToSecs, omit, parseTime, percent, pick, pluralize, prng, readDir, remap, retryPromise, rndChance, rndChoice, rndFloat, rndIndex, rndInt, rndString, searchSorted, secsToMs, seqMap, setProp, shuffle, sortBy, sum, throttle, toTitleCase, unique, wait, weightedRnd, wrap };
+export { type AlphaCasing, type AnyFunc, Cache, type DebouncedFunction, type DeepPartial, type FormatDurationOptions, FormatNumberCompact, Loop, type LoopEvents, type MemoizedFunction, type ParseTimeOptions, Pipe, type ReadDirOptions, type RetryOptions, type RndArrayOptions, type RndStrOptions, type SequentialMapContext, Storage, type TypedEmitter, chunk, chunkAdj, clampNumber, cluster, compactArray, createSampler, debounce, escapeRegex, forceArray, formatCurrency, formatDuration, formatETA, formatMemory, formatNumber, formatOrdinal, getAge, getFlag, getProp, hasFlag, hasProp, inverseLerp, isDefined, isEmpty, isInRange, isObject, isSortedArray, isString, isToday, keyedQueue, lerp, memoize, merge, msToSecs, omit, parseTime, percent, pick, pluralize, prng, readDir, remap, retryPromise, rndChance, rndChoice, rndFloat, rndIndex, rndInt, rndString, searchSorted, secsToMs, seqMap, setProp, shuffle, sortBy, sum, throttle, toTitleCase, unique, wait, weightedRnd, wrap };

package/dist/index.js

@@ -504,6 +504,24 @@ function unique(array, key) {
 }
 
 // src/async.ts
+function keyedQueue() {
+  const queues = /* @__PURE__ */ new Map();
+  return {
+    run(key, work) {
+      const previous = queues.get(key) ?? Promise.resolve();
+      const result = previous.then(work);
+      const release = () => {
+        if (queues.get(key) === tail) queues.delete(key);
+      };
+      const tail = result.then(release, release);
+      queues.set(key, tail);
+      return result;
+    },
+    get size() {
+      return queues.size;
+    }
+  };
+}
 async function retryPromise(fn, options = {}) {
   const { attempts = 3, delay = 500, timeout, signal } = options;
   if (signal?.aborted) throw new Error("Operation aborted");
@@ -619,9 +637,28 @@ function throttle(fn, limit) {
 function memoize(fn, options = {}) {
   const cache = /* @__PURE__ */ new Map();
   const { resolver, maxAge } = options;
+  let lastSweep = Date.now();
+  const getKey = (...args) => resolver ? resolver(...args) : JSON.stringify(args);
+  const sweep = (now) => {
+    if (!maxAge || now - lastSweep < maxAge) return;
+    lastSweep = now;
+    for (const [key, entry] of cache) {
+      if (now - entry.timestamp >= maxAge) cache.delete(key);
+    }
+  };
+  const cacheValue = (key, value, timestamp) => {
+    const entry = { value, timestamp };
+    cache.set(key, entry);
+    if (value !== null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function") {
+      void Promise.resolve(value).catch(() => {
+        if (cache.get(key) === entry) cache.delete(key);
+      });
+    }
+  };
   const memoized = function(...args) {
-    const key = resolver ? resolver(...args) : JSON.stringify(args);
+    const key = getKey(...args);
     const now = Date.now();
+    sweep(now);
     const entry = cache.get(key);
     if (entry) {
       if (!maxAge || now - entry.timestamp < maxAge) {
@@ -630,10 +667,17 @@ function memoize(fn, options = {}) {
       cache.delete(key);
     }
     const result = fn.apply(this, args);
-    cache.set(key, { value: result, timestamp: now });
+    cacheValue(key, result, now);
     return result;
   };
   memoized.clear = () => cache.clear();
+  memoized.delete = (...args) => cache.delete(getKey(...args));
+  memoized.set = (value, ...args) => {
+    const key = getKey(...args);
+    const now = Date.now();
+    sweep(now);
+    cacheValue(key, value, now);
+  };
   return memoized;
 }
 
@@ -684,7 +728,7 @@ function formatDuration(target, style = "hms", options = {}) {
   if (diff === 0) return style === "digital" ? "00:00" : "now";
   const s = Math.floor(diff / 1e3) % 60;
   const m = Math.floor(diff / 6e4) % 60;
-  const h = Math.floor(diff / 36e5) % 24;
+  const h = style === "hms" ? Math.floor(diff / 36e5) : Math.floor(diff / 36e5) % 24;
   const d = Math.floor(diff / 864e5);
   if (style === "digital") {
     const parts = [m, s].map((v) => String(v).padStart(2, "0"));
@@ -979,6 +1023,7 @@ export {
   isSortedArray,
   isString,
   isToday,
+  keyedQueue,
   lerp,
   memoize,
   merge,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qznt",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "A lightweight typed utility toolkit for modern TypeScript environments.",
   "license": "MIT",
   "author": "xsqu1znt",
@@ -27,6 +27,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "test": "pnpm build && node --test tests/*.test.mjs",
     "check": "tsc --noEmit",
     "format": "prettier --write \"./**/*.{ts,json}\""
   }