qznt 2.0.1 → 2.2.0

package/README.md

@@ -55,6 +55,7 @@ import { Cache, Storage } from "qznt";
 // Cache with a 1-minute global TTL
 const userCache = new Cache<UserData>(60000);
 userCache.set("user_1", data);
+userCache.delete("user_1");
 
 // Persistent storage (Browser or NodeJS based)
 const settings = new Storage("app_settings");

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,
@@ -128,6 +129,14 @@ var Cache = class {
     }
     return data.value;
   }
+  /**
+   * Removes a single entry from the cache.
+   * @param key The key to remove
+   * @returns Whether an entry existed and was removed
+   */
+  delete(key) {
+    return this.cache.delete(key);
+  }
   cleanup() {
     if (this.cache.size === 0) return;
     const now = Date.now();
@@ -596,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");
@@ -711,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) {
@@ -722,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;
 }
 
@@ -1072,6 +1125,7 @@ function toTitleCase(str, smart = true) {
   isSortedArray,
   isString,
   isToday,
+  keyedQueue,
   lerp,
   memoize,
   merge,

package/dist/index.d.cts

@@ -9,6 +9,12 @@ declare class Cache<T> {
     constructor(cleanupMs?: number);
     set(key: string | number, value: T, ttlMs?: number): void;
     get(key: string | number): T | null;
+    /**
+     * Removes a single entry from the cache.
+     * @param key The key to remove
+     * @returns Whether an entry existed and was removed
+     */
+    delete(key: string | number): boolean;
     private cleanup;
     clear(): void;
 }
@@ -202,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.
  *
@@ -269,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) => {
@@ -300,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. */
@@ -667,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

@@ -9,6 +9,12 @@ declare class Cache<T> {
     constructor(cleanupMs?: number);
     set(key: string | number, value: T, ttlMs?: number): void;
     get(key: string | number): T | null;
+    /**
+     * Removes a single entry from the cache.
+     * @param key The key to remove
+     * @returns Whether an entry existed and was removed
+     */
+    delete(key: string | number): boolean;
     private cleanup;
     clear(): void;
 }
@@ -202,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.
  *
@@ -269,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) => {
@@ -300,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. */
@@ -667,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

@@ -28,6 +28,14 @@ var Cache = class {
     }
     return data.value;
   }
+  /**
+   * Removes a single entry from the cache.
+   * @param key The key to remove
+   * @returns Whether an entry existed and was removed
+   */
+  delete(key) {
+    return this.cache.delete(key);
+  }
   cleanup() {
     if (this.cache.size === 0) return;
     const now = Date.now();
@@ -496,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");
@@ -611,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) {
@@ -622,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;
 }
 
@@ -971,6 +1023,7 @@ export {
   isSortedArray,
   isString,
   isToday,
+  keyedQueue,
   lerp,
   memoize,
   merge,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qznt",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "A lightweight typed utility toolkit for modern TypeScript environments.",
   "license": "MIT",
   "author": "xsqu1znt",