@ls-stack/utils 3.65.0 → 3.66.0

package/dist/awaitDebounce.cjs

@@ -1,106 +0,0 @@
-"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/awaitDebounce.ts
-var awaitDebounce_exports = {};
-__export(awaitDebounce_exports, {
-  awaitDebounce: () => awaitDebounce
-});
-module.exports = __toCommonJS(awaitDebounce_exports);
-
-// src/typeGuards.ts
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-// src/assertions.ts
-var isObject2 = isObject;
-
-// src/getCompositeKey.ts
-function getCompositeKey(input, maxSortingDepth = 3) {
-  if (typeof input === "string") return `"${input}`;
-  if (!input || typeof input !== "object") return `$${input}`;
-  return stringifyCompact(input, maxSortingDepth, 0, /* @__PURE__ */ new WeakSet());
-}
-function stringifyCompact(input, maxSortingDepth, depth, refs) {
-  const isJsObj = input && typeof input === "object";
-  if (isJsObj) {
-    if (refs.has(input)) {
-      throw new Error("Circular reference detected");
-    }
-    refs.add(input);
-  }
-  let result;
-  if (Array.isArray(input)) {
-    result = "[";
-    for (const v of input) {
-      if (result.length > 1) result += ",";
-      result += stringifyCompact(v, maxSortingDepth, depth + 1, refs);
-    }
-    result += "]";
-  } else if (isObject2(input)) {
-    let entries = Object.entries(input);
-    if (entries.length === 0) {
-      result = "{}";
-    } else {
-      if (depth < maxSortingDepth) {
-        entries = entries.sort(
-          ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
-        );
-      }
-      result = "{";
-      for (const [k, v] of entries) {
-        if (v === void 0) continue;
-        if (result.length > 1) result += ",";
-        result += `${k}:${stringifyCompact(v, maxSortingDepth, depth + 1, refs)}`;
-      }
-      result += "}";
-    }
-  } else {
-    result = JSON.stringify(input);
-  }
-  if (isJsObj) {
-    refs.delete(input);
-  }
-  return result;
-}
-
-// src/awaitDebounce.ts
-var resolvers = {};
-var debouncers = {};
-async function awaitDebounce({
-  callId: _callId,
-  debounce
-}) {
-  const callId = getCompositeKey(_callId);
-  if (debouncers[callId]) clearTimeout(debouncers[callId]);
-  debouncers[callId] = globalThis.setTimeout(() => {
-    const resolve = resolvers[callId];
-    resolvers[callId] = void 0;
-    resolve?.("continue");
-  }, debounce);
-  if (resolvers[callId]) resolvers[callId]("skip");
-  return new Promise((resolve) => {
-    resolvers[callId] = resolve;
-  });
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  awaitDebounce
-});

package/dist/awaitDebounce.d.ts

@@ -1,41 +0,0 @@
-import { __LEGIT_ANY__ } from './saferTyping.js';
-
-/**
- * Creates an awaitable debounce mechanism that allows you to debounce async
- * operations. When called multiple times with the same `callId`, only the last
- * call will resolve with 'continue', while all previous calls resolve with
- * 'skip'.
- *
- * This is useful for debouncing API calls, search operations, or any async work
- * where you want to ensure only the most recent request is processed.
- *
- * @example
- *   ```ts
- *   async function searchUsers(query: string) {
- *     const result = await awaitDebounce({ callId: 'search', debounce: 300 });
- *     if (result === 'skip') return; // This search was superseded
- *
- *     // Only the most recent search will reach here
- *     const users = await fetchUsers(query);
- *     updateUI(users);
- *   }
- *
- *   // Called rapidly - only the last call will execute
- *   searchUsers('a');
- *   searchUsers('ab');
- *   searchUsers('abc'); // Only this one will continue
- *   ```;
- *
- * @param options - Configuration object
- * @param options.callId - Unique identifier for the debounce group. Calls with
- *   the same ID are debounced together
- * @param options.debounce - Debounce delay in milliseconds
- * @returns Promise that resolves to 'continue' if this call should proceed, or
- *   'skip' if it was superseded
- */
-declare function awaitDebounce({ callId: _callId, debounce, }: {
-    callId: __LEGIT_ANY__;
-    debounce: number;
-}): Promise<'continue' | 'skip'>;
-
-export { awaitDebounce };

package/dist/awaitDebounce.js

@@ -1,28 +0,0 @@
-import {
-  getCompositeKey
-} from "./chunk-6FIBVC2P.js";
-import "./chunk-C2SVCIWE.js";
-import "./chunk-JF2MDHOJ.js";
-
-// src/awaitDebounce.ts
-var resolvers = {};
-var debouncers = {};
-async function awaitDebounce({
-  callId: _callId,
-  debounce
-}) {
-  const callId = getCompositeKey(_callId);
-  if (debouncers[callId]) clearTimeout(debouncers[callId]);
-  debouncers[callId] = globalThis.setTimeout(() => {
-    const resolve = resolvers[callId];
-    resolvers[callId] = void 0;
-    resolve?.("continue");
-  }, debounce);
-  if (resolvers[callId]) resolvers[callId]("skip");
-  return new Promise((resolve) => {
-    resolvers[callId] = resolve;
-  });
-}
-export {
-  awaitDebounce
-};

package/dist/cache.cjs

@@ -1,367 +0,0 @@
-"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/cache.ts
-var cache_exports = {};
-__export(cache_exports, {
-  SkipCaching: () => SkipCaching,
-  WithExpiration: () => WithExpiration,
-  cachedGetter: () => cachedGetter,
-  createCache: () => createCache,
-  fastCache: () => fastCache
-});
-module.exports = __toCommonJS(cache_exports);
-
-// src/typeGuards.ts
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isFunction(value) {
-  return typeof value === "function";
-}
-function isPromise(value) {
-  return isObject(value) && "then" in value && isFunction(value.then);
-}
-
-// src/assertions.ts
-var isPromise2 = isPromise;
-
-// src/time.ts
-var MINUTE_AS_MS = 60 * 1e3;
-var HOUR_AS_MS = 60 * MINUTE_AS_MS;
-var DAY_AS_MS = 24 * HOUR_AS_MS;
-var WEEK_AS_MS = 7 * DAY_AS_MS;
-var MONTH_AS_MS = 30 * DAY_AS_MS;
-var YEAR_AS_MS = 365 * DAY_AS_MS;
-var HOUR_AS_SECS = 60 * 60;
-var DAY_AS_SECS = 24 * HOUR_AS_SECS;
-var WEEK_AS_SECS = 7 * DAY_AS_SECS;
-var MONTH_AS_SECS = 30 * DAY_AS_SECS;
-var YEAR_AS_SECS = 365 * DAY_AS_SECS;
-function durationObjToMs(durationObj) {
-  return (durationObj.hours ?? 0) * HOUR_AS_MS + (durationObj.minutes ?? 0) * MINUTE_AS_MS + (durationObj.seconds ?? 0) * 1e3 + (durationObj.ms ?? 0) + (durationObj.days ?? 0) * DAY_AS_MS;
-}
-
-// src/cache.ts
-function cachedGetter(getter) {
-  return {
-    get value() {
-      const value = getter();
-      Object.defineProperty(this, "value", { value });
-      return value;
-    }
-  };
-}
-var SkipCaching = class {
-  value;
-  constructor(value) {
-    this.value = value;
-  }
-};
-var WithExpiration = class {
-  value;
-  expiration;
-  /**
-   * @param value - The value to store in the cache.
-   * @param expiration - The expiration time of the value in seconds or a
-   *   duration object.
-   */
-  constructor(value, expiration) {
-    this.value = value;
-    this.expiration = durationObjToMs(expiration);
-  }
-};
-function createCache({
-  maxCacheSize = 1e3,
-  maxItemAge,
-  expirationThrottle = 1e4
-} = {}) {
-  const cache = /* @__PURE__ */ new Map();
-  let lastExpirationCheck = 0;
-  const defaultMaxItemAgeMs = maxItemAge && durationObjToMs(maxItemAge);
-  function cleanExpiredItems() {
-    const now = Date.now();
-    if (!defaultMaxItemAgeMs || now - lastExpirationCheck < expirationThrottle)
-      return;
-    lastExpirationCheck = now;
-    for (const [key, item] of cache.entries()) {
-      if (isExpired(item, now)) {
-        cache.delete(key);
-      }
-    }
-  }
-  function trimToSize() {
-    const currentSize = cache.size;
-    if (currentSize > maxCacheSize) {
-      const keysToRemove = currentSize - maxCacheSize;
-      const iterator = cache.keys();
-      for (let i = 0; i < keysToRemove; i++) {
-        const { value: key } = iterator.next();
-        if (key) {
-          cache.delete(key);
-        }
-      }
-    }
-  }
-  function isExpired(entry, now) {
-    const maxItemAgeMs = entry.expiration ?? defaultMaxItemAgeMs;
-    return !!maxItemAgeMs && now - entry.timestamp > maxItemAgeMs;
-  }
-  function unwrapValue(value, now) {
-    if (value instanceof WithExpiration) {
-      return {
-        value: value.value,
-        timestamp: now,
-        expiration: value.expiration ? typeof value.expiration === "number" ? value.expiration : now + durationObjToMs(value.expiration) : void 0
-      };
-    }
-    return { value, timestamp: now, expiration: void 0 };
-  }
-  const utils = {
-    skipCaching: (value) => new SkipCaching(value),
-    withExpiration: (value, expiration) => {
-      return new WithExpiration(value, expiration);
-    }
-  };
-  function refreshEntry(key, now) {
-    const entry = cache.get(key);
-    if (entry && !isExpired(entry, now)) {
-      cache.delete(key);
-      cache.set(key, entry);
-    }
-  }
-  return {
-    /**
-     * Gets a value from the cache or computes and stores it if not present.
-     * This is the primary method for synchronous caching operations.
-     *
-     * @param cacheKey - Unique key to identify the cached value
-     * @param val - Function that computes the value if not cached. Receives
-     *   utility functions for advanced features.
-     * @param options - Optional configuration for this specific get operation
-     * @returns The cached or newly computed value
-     * @throws Error if the cached value is a promise (use getOrInsertAsync
-     *   instead)
-     */
-    getOrInsert(cacheKey, val, options) {
-      const now = Date.now();
-      const entry = cache.get(cacheKey);
-      if (!entry || isExpired(entry, now)) {
-        const value = val(utils);
-        if (value instanceof SkipCaching) {
-          return value.value;
-        }
-        if (options?.skipCachingWhen?.(value)) {
-          return value;
-        }
-        const unwrappedValue = unwrapValue(value, now);
-        cache.set(cacheKey, unwrappedValue);
-        trimToSize();
-        cleanExpiredItems();
-        return unwrappedValue.value;
-      }
-      if (isPromise2(entry.value)) {
-        throw new Error(
-          "Cache value is a promise, use getOrInsertAsync instead"
-        );
-      }
-      refreshEntry(cacheKey, now);
-      return entry.value;
-    },
-    /**
-     * Gets a value from the cache or computes and stores it asynchronously.
-     * Provides promise deduplication - concurrent calls with the same key will
-     * share the same promise.
-     *
-     * @param cacheKey - Unique key to identify the cached value
-     * @param val - Async function that computes the value if not cached.
-     *   Receives utility functions for advanced features.
-     * @param options - Optional configuration for this specific get operation
-     * @returns Promise that resolves to the cached or newly computed value
-     */
-    async getOrInsertAsync(cacheKey, val, options) {
-      const entry = cache.get(cacheKey);
-      if (entry && isPromise2(entry.value)) {
-        return entry.value;
-      }
-      const now = Date.now();
-      if (entry && !isExpired(entry, now)) {
-        refreshEntry(cacheKey, now);
-        return entry.value;
-      }
-      const promise = val(utils).then((result) => {
-        if (result instanceof SkipCaching) {
-          const cacheValue = cache.get(cacheKey);
-          if (cacheValue?.value === promise) {
-            cache.delete(cacheKey);
-          }
-          return result.value;
-        }
-        if (options?.skipCachingWhen?.(result)) {
-          const cacheValue = cache.get(cacheKey);
-          if (cacheValue?.value === promise) {
-            cache.delete(cacheKey);
-          }
-          return result;
-        }
-        const unwrappedValue = unwrapValue(result, Date.now());
-        cache.set(cacheKey, unwrappedValue);
-        return unwrappedValue.value;
-      }).catch((error) => {
-        cache.delete(cacheKey);
-        throw error;
-      });
-      cache.set(cacheKey, {
-        value: promise,
-        timestamp: now,
-        expiration: void 0
-      });
-      trimToSize();
-      cleanExpiredItems();
-      return promise;
-    },
-    /** Removes all items from the cache. */
-    clear() {
-      cache.clear();
-    },
-    /**
-     * Gets a value from the cache without computing it if missing. Returns
-     * undefined if the key doesn't exist or has expired.
-     *
-     * @param cacheKey - Key to look up in the cache
-     * @returns The cached value or undefined if not found/expired
-     * @throws Error if the cached value is a promise (use getAsync instead)
-     */
-    get(cacheKey) {
-      const entry = cache.get(cacheKey);
-      const now = Date.now();
-      if (!entry || isExpired(entry, now)) {
-        return void 0;
-      }
-      if (isPromise2(entry.value)) {
-        throw new Error("Cache value is a promise, use getAsync instead");
-      }
-      refreshEntry(cacheKey, now);
-      return entry.value;
-    },
-    /**
-     * Manually sets a value in the cache.
-     *
-     * @param cacheKey - Key to store the value under
-     * @param value - Value to store, or WithExpiration wrapper for custom
-     *   expiration
-     */
-    set(cacheKey, value) {
-      cache.set(cacheKey, unwrapValue(value, Date.now()));
-      trimToSize();
-      cleanExpiredItems();
-    },
-    /**
-     * Gets a value from the cache without computing it if missing. Works with
-     * both sync and async cached values.
-     *
-     * @param cacheKey - Key to look up in the cache
-     * @returns Promise that resolves to the cached value or undefined if not
-     *   found/expired
-     */
-    async getAsync(cacheKey) {
-      const entry = cache.get(cacheKey);
-      const now = Date.now();
-      if (!entry || isExpired(entry, now)) {
-        return void 0;
-      }
-      refreshEntry(cacheKey, now);
-      return entry.value;
-    },
-    /**
-     * Manually sets an async value in the cache. The promise will be stored
-     * immediately and shared with concurrent requests.
-     *
-     * @param cacheKey - Key to store the value under
-     * @param value - Async function that returns the value to cache
-     * @returns Promise that resolves to the computed value
-     */
-    async setAsync(cacheKey, value) {
-      const promise = value(utils).then((result) => {
-        if (result instanceof SkipCaching) {
-          const cacheValue = cache.get(cacheKey);
-          if (cacheValue?.value === promise) {
-            cache.delete(cacheKey);
-          }
-          return result.value;
-        }
-        const unwrappedValue = unwrapValue(result, Date.now());
-        cache.set(cacheKey, unwrappedValue);
-        return unwrappedValue.value;
-      }).catch((error) => {
-        cache.delete(cacheKey);
-        throw error;
-      });
-      cache.set(cacheKey, {
-        value: promise,
-        timestamp: Date.now(),
-        expiration: void 0
-      });
-      trimToSize();
-      cleanExpiredItems();
-      return promise;
-    },
-    /**
-     * Manually triggers cleanup of expired items. Normally this happens
-     * automatically during cache operations.
-     */
-    cleanExpiredItems,
-    /** @internal */
-    " cache": { map: cache }
-  };
-}
-function fastCache({ maxCacheSize = 1e3 } = {}) {
-  const cache = /* @__PURE__ */ new Map();
-  function trimCache() {
-    const cacheSize = cache.size;
-    if (cacheSize > maxCacheSize) {
-      const keys = Array.from(cache.keys());
-      for (let i = 0; i < cacheSize - maxCacheSize; i++) {
-        cache.delete(keys[i]);
-      }
-    }
-  }
-  function getOrInsert(cacheKey, val) {
-    if (!cache.has(cacheKey)) {
-      const value = val();
-      cache.set(cacheKey, value);
-      trimCache();
-      return cache.get(cacheKey) ?? value;
-    }
-    return cache.get(cacheKey);
-  }
-  return {
-    getOrInsert,
-    /** Clears all cached values */
-    clear: () => cache.clear()
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  SkipCaching,
-  WithExpiration,
-  cachedGetter,
-  createCache,
-  fastCache
-});