@choksheak/ts-utils 0.3.3 → 0.3.5

package/localStore.cjs

@@ -20,10 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/localStore.ts
 var localStore_exports = {};
 __export(localStore_exports, {
-  LocalStore: () => LocalStore,
   LocalStoreConfig: () => LocalStoreConfig,
-  LocalStoreItem: () => LocalStoreItem,
   configureLocalStore: () => configureLocalStore,
+  createLocalStore: () => createLocalStore,
   localStore: () => localStore,
   localStoreItem: () => localStoreItem
 });
@@ -66,202 +65,204 @@ function validateStoredObject(obj) {
   }
   return obj;
 }
-var LocalStore = class {
-  constructor(storeName, options) {
-    this.storeName = storeName;
-    this.keyPrefix = storeName + ":";
-    this.defaultExpiryMs = options?.defaultExpiryMs ? durationOrMsToMs(options.defaultExpiryMs) : LocalStoreConfig.expiryMs;
-    this.gcIntervalMs = options?.gcIntervalMs ? durationOrMsToMs(options.gcIntervalMs) : LocalStoreConfig.gcIntervalMs;
-    this.gcMsStorageKey = `__localStore:lastGcMs:${storeName}`;
-  }
-  /**
-   * The prefix string for the local storage key which identifies items
-   * belonging to this namespace.
-   */
-  keyPrefix;
-  /** Local storage key name for the last GC completed timestamp. */
-  gcMsStorageKey;
-  defaultExpiryMs;
-  gcIntervalMs;
-  /** Set a value in the store. */
-  set(key, value, expiryDeltaMs = this.defaultExpiryMs) {
-    const nowMs = Date.now();
-    const obj = {
-      value,
-      storedMs: nowMs,
-      expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs)
-    };
-    localStorage.setItem(this.keyPrefix + key, JSON.stringify(obj));
-    this.gc();
-    return value;
-  }
-  /** Delete one or multiple keys. */
-  delete(key) {
-    if (typeof key === "string") {
-      localStorage.removeItem(this.keyPrefix + key);
-    } else {
-      for (const k of key) {
-        localStorage.removeItem(this.keyPrefix + k);
+function createLocalStore(storeName, options) {
+  const keyPrefix = storeName + ":";
+  const defaultExpiryMs = options?.defaultExpiryMs ? durationOrMsToMs(options.defaultExpiryMs) : LocalStoreConfig.expiryMs;
+  const gcIntervalMs = options?.gcIntervalMs ? durationOrMsToMs(options.gcIntervalMs) : LocalStoreConfig.gcIntervalMs;
+  const gcMsStorageKey = `__localStore:lastGcMs:${storeName}`;
+  const obj = {
+    /** Input name for the store. */
+    storeName,
+    /**
+     * The prefix string for the local storage key which identifies items
+     * belonging to this namespace.
+     */
+    keyPrefix,
+    /** Default expiry to use if not specified in set(). */
+    defaultExpiryMs,
+    /** Time interval for when GC's occur. */
+    gcIntervalMs,
+    /** Local storage key name for the last GC completed timestamp. */
+    gcMsStorageKey,
+    /** Set a value in the store. */
+    set(key, value, expiryDeltaMs) {
+      const nowMs = Date.now();
+      const stored = {
+        value,
+        storedMs: nowMs,
+        expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs ?? defaultExpiryMs)
+      };
+      localStorage.setItem(keyPrefix + key, JSON.stringify(stored));
+      obj.gc();
+      return value;
+    },
+    /** Delete one or multiple keys. */
+    delete(key) {
+      if (typeof key === "string") {
+        localStorage.removeItem(keyPrefix + key);
+      } else {
+        for (const k of key) {
+          localStorage.removeItem(keyPrefix + k);
+        }
       }
-    }
-  }
-  /** Mainly used to get the expiration timestamp of an object. */
-  getStoredObject(key) {
-    const k = this.keyPrefix + key;
-    const stored = localStorage.getItem(k);
-    if (!stored) {
-      return void 0;
-    }
-    try {
-      const parsed = JSON.parse(stored);
-      const obj = validateStoredObject(parsed);
-      if (!obj) {
-        this.delete(k);
-        this.gc();
+    },
+    /** Mainly used to get the expiration timestamp of an object. */
+    getStoredObject(key) {
+      const k = keyPrefix + key;
+      const stored = localStorage.getItem(k);
+      if (!stored) {
         return void 0;
       }
-      return obj;
-    } catch (e) {
-      console.error(`Invalid local value: ${k}=${stored}:`, e);
-      this.delete(k);
-      this.gc();
-      return void 0;
-    }
-  }
-  /** Get a value by key, or undefined if it does not exist. */
-  get(key) {
-    const obj = this.getStoredObject(key);
-    return obj?.value;
-  }
-  /** Generic way to iterate through all entries. */
-  forEach(callback) {
-    for (const k of Object.keys(localStorage)) {
-      if (!k.startsWith(this.keyPrefix)) continue;
-      const key = k.slice(this.keyPrefix.length);
-      const obj = this.getStoredObject(key);
-      if (!obj) continue;
-      callback(key, obj.value, obj.expiryMs, obj.storedMs);
-    }
-  }
-  /**
-   * Returns the number of items in the store. Note that getting the size
-   * requires iterating through the entire store because the items could expire
-   * at any time, and hence the size is a dynamic number.
-   */
-  size() {
-    let count = 0;
-    this.forEach(() => {
-      count++;
-    });
-    return count;
-  }
-  /** Remove all items from the store. */
-  clear() {
-    for (const key of Object.keys(localStorage)) {
-      if (key.startsWith(this.keyPrefix)) {
-        localStorage.removeItem(key);
+      try {
+        const parsed = JSON.parse(stored);
+        const valid = validateStoredObject(parsed);
+        if (!valid) {
+          obj.delete(k);
+          obj.gc();
+          return void 0;
+        }
+        return valid;
+      } catch (e) {
+        console.error(`Invalid local value: ${k}=${stored}:`, e);
+        obj.delete(k);
+        obj.gc();
+        return void 0;
       }
-    }
-  }
-  /**
-   * Returns all items as map of key to value, mainly used for debugging dumps.
-   * The type T is applied to all values, even though they might not be of type
-   * T (in the case when you store different data types in the same store).
-   */
-  asMap() {
-    const map = /* @__PURE__ */ new Map();
-    this.forEach((key, value, expiryMs, storedMs) => {
-      map.set(key, { value, expiryMs, storedMs });
-    });
-    return map;
-  }
-  /** Returns the ms timestamp for the last GC (garbage collection). */
-  get lastGcMs() {
-    const lastGcMsStr = globalThis.localStorage.getItem(this.gcMsStorageKey);
-    if (!lastGcMsStr) return 0;
-    const ms = Number(lastGcMsStr);
-    return isNaN(ms) ? 0 : ms;
-  }
-  /** Set the ms timestamp for the last GC (garbage collection). */
-  set lastGcMs(ms) {
-    globalThis.localStorage.setItem(this.gcMsStorageKey, String(ms));
-  }
-  /** Perform garbage-collection if due, else do nothing. */
-  gc() {
-    const lastGcMs = this.lastGcMs;
-    if (!lastGcMs) {
-      this.lastGcMs = Date.now();
-      return;
-    }
-    if (Date.now() < lastGcMs + this.gcIntervalMs) {
-      return;
-    }
-    this.gcNow();
-  }
-  /**
-   * Perform garbage collection immediately without checking whether we are
-   * due for the next GC or not.
-   */
-  gcNow() {
-    console.log(`Starting localStore GC on ${this.storeName}`);
-    this.lastGcMs = Date.now();
-    let count = 0;
-    this.forEach((key, value, expiryMs) => {
-      if (Date.now() >= expiryMs) {
-        this.delete(key);
+    },
+    /** Get a value by key, or undefined if it does not exist. */
+    get(key) {
+      const stored = obj.getStoredObject(key);
+      return stored?.value;
+    },
+    /** Generic way to iterate through all entries. */
+    forEach(callback) {
+      for (const k of Object.keys(localStorage)) {
+        if (!k.startsWith(keyPrefix)) continue;
+        const key = k.slice(keyPrefix.length);
+        const stored = obj.getStoredObject(key);
+        if (!stored) continue;
+        callback(key, stored.value, stored.expiryMs, stored.storedMs);
+      }
+    },
+    /**
+     * Returns the number of items in the store. Note that getting the size
+     * requires iterating through the entire store because the items could expire
+     * at any time, and hence the size is a dynamic number.
+     */
+    size() {
+      let count = 0;
+      obj.forEach(() => {
         count++;
+      });
+      return count;
+    },
+    /** Remove all items from the store. */
+    clear() {
+      for (const key of Object.keys(localStorage)) {
+        if (key.startsWith(keyPrefix)) {
+          localStorage.removeItem(key);
+        }
       }
-    });
-    console.log(
-      `Finished localStore GC on ${this.storeName} - deleted ${count} keys`
-    );
-    this.lastGcMs = Date.now();
-  }
-  /** Returns `this` casted into a StorageAdapter<T>. */
-  asStorageAdapter() {
-    return this;
-  }
-};
-var localStore = new LocalStore(LocalStoreConfig.storeName);
-var LocalStoreItem = class {
-  constructor(key, defaultExpiryMs = LocalStoreConfig.expiryMs, store = localStore) {
-    this.key = key;
-    this.store = store;
-    this.defaultExpiryMs = defaultExpiryMs && durationOrMsToMs(defaultExpiryMs);
-  }
-  defaultExpiryMs;
-  /** Set a value in the store. */
-  set(value, expiryDeltaMs = this.defaultExpiryMs) {
-    this.store.set(this.key, value, expiryDeltaMs);
-  }
-  /**
-   * Example usage:
-   *
-   *   const { value, storedMs, expiryMs, storedMs } =
-   *     await myLocalItem.getStoredObject();
-   */
-  getStoredObject() {
-    return this.store.getStoredObject(this.key);
-  }
-  /** Get a value by key, or undefined if it does not exist. */
-  get() {
-    return this.store.get(this.key);
-  }
-  /** Delete this key from the store. */
-  delete() {
-    this.store.delete(this.key);
-  }
-};
+    },
+    /**
+     * Returns all items as map of key to value, mainly used for debugging dumps.
+     * The type T is applied to all values, even though they might not be of type
+     * T (in the case when you store different data types in the same store).
+     */
+    asMap() {
+      const map = /* @__PURE__ */ new Map();
+      obj.forEach(
+        (key, value, expiryMs, storedMs) => {
+          map.set(key, { value, expiryMs, storedMs });
+        }
+      );
+      return map;
+    },
+    /** Returns the ms timestamp for the last GC (garbage collection). */
+    getLastGcMs() {
+      const lastGcMsStr = localStorage.getItem(gcMsStorageKey);
+      if (!lastGcMsStr) return 0;
+      const ms = Number(lastGcMsStr);
+      return isNaN(ms) ? 0 : ms;
+    },
+    /** Set the ms timestamp for the last GC (garbage collection). */
+    setLastGcMs(ms) {
+      localStorage.setItem(gcMsStorageKey, String(ms));
+    },
+    /** Perform garbage-collection if due, else do nothing. */
+    gc() {
+      const lastGcMs = obj.getLastGcMs();
+      if (!lastGcMs) {
+        obj.setLastGcMs(Date.now());
+        return;
+      }
+      if (Date.now() < lastGcMs + gcIntervalMs) {
+        return;
+      }
+      obj.gcNow();
+    },
+    /**
+     * Perform garbage collection immediately without checking whether we are
+     * due for the next GC or not.
+     */
+    gcNow() {
+      console.log(`Starting localStore GC on ${storeName}`);
+      obj.setLastGcMs(Date.now());
+      let count = 0;
+      obj.forEach((key, value, expiryMs) => {
+        if (Date.now() >= expiryMs) {
+          obj.delete(key);
+          count++;
+        }
+      });
+      console.log(
+        `Finished localStore GC on ${storeName} - deleted ${count} keys`
+      );
+      obj.setLastGcMs(Date.now());
+    },
+    /** Returns `this` casted into a StorageAdapter<T>. */
+    asStorageAdapter() {
+      return obj;
+    }
+  };
+  return obj;
+}
+var localStore = createLocalStore(LocalStoreConfig.storeName);
 function localStoreItem(key, expiryMs, store = localStore) {
-  expiryMs = expiryMs && durationOrMsToMs(expiryMs);
-  return new LocalStoreItem(key, expiryMs, store);
+  const defaultExpiryMs = expiryMs && durationOrMsToMs(expiryMs);
+  const obj = {
+    key,
+    defaultExpiryMs,
+    store,
+    /** Set a value in the store. */
+    set(value, expiryDeltaMs) {
+      store.set(key, value, expiryDeltaMs ?? defaultExpiryMs);
+    },
+    /**
+     * Example usage:
+     *
+     *   const { value, storedMs, expiryMs, storedMs } =
+     *     await myLocalItem.getStoredObject();
+     */
+    getStoredObject() {
+      return store.getStoredObject(key);
+    },
+    /** Get a value by key, or undefined if it does not exist. */
+    get() {
+      return store.get(key);
+    },
+    /** Delete this key from the store. */
+    delete() {
+      store.delete(key);
+    }
+  };
+  return obj;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  LocalStore,
   LocalStoreConfig,
-  LocalStoreItem,
   configureLocalStore,
+  createLocalStore,
   localStore,
   localStoreItem
 });

package/localStore.d.mts

@@ -1,5 +1,5 @@
 import { Duration } from './duration.mjs';
-import { FullStorageAdapter, StoredObject, StorageAdapter } from './storageAdapter.mjs';
+import { StoredObject, StorageAdapter } from './storageAdapter.mjs';
 
 /**
  * Local storage key-value store with support for auto-expirations.
@@ -33,72 +33,174 @@ declare function configureLocalStore(config: Partial<LocalStoreConfig>): void;
  * You can create multiple LocalStores if you want, but most likely you will only
  * need to use the default `localStore` instance.
  */
-declare class LocalStore implements FullStorageAdapter<any> {
+declare function createLocalStore(storeName: string, options?: {
+    defaultExpiryMs?: number | Duration;
+    gcIntervalMs?: number | Duration;
+}): {
+    /** Input name for the store. */
     readonly storeName: string;
     /**
      * The prefix string for the local storage key which identifies items
      * belonging to this namespace.
      */
     readonly keyPrefix: string;
-    /** Local storage key name for the last GC completed timestamp. */
-    readonly gcMsStorageKey: string;
+    /** Default expiry to use if not specified in set(). */
     readonly defaultExpiryMs: number;
+    /** Time interval for when GC's occur. */
     readonly gcIntervalMs: number;
-    constructor(storeName: string, options?: {
-        defaultExpiryMs?: number | Duration;
-        gcIntervalMs?: number | Duration;
-    });
+    /** Local storage key name for the last GC completed timestamp. */
+    readonly gcMsStorageKey: string;
     /** Set a value in the store. */
-    set<T>(key: string, value: T, expiryDeltaMs?: number | Duration): T;
+    readonly set: <T>(key: string, value: T, expiryDeltaMs?: number | Duration) => T;
     /** Delete one or multiple keys. */
-    delete(key: string | string[]): void;
+    readonly delete: (key: string | string[]) => void;
     /** Mainly used to get the expiration timestamp of an object. */
-    getStoredObject<T>(key: string): StoredObject<T> | undefined;
+    readonly getStoredObject: <T>(key: string) => StoredObject<T> | undefined;
     /** Get a value by key, or undefined if it does not exist. */
-    get<T>(key: string): T | undefined;
+    readonly get: <T>(key: string) => T | undefined;
     /** Generic way to iterate through all entries. */
-    forEach<T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void): void;
+    readonly forEach: <T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void) => void;
     /**
      * Returns the number of items in the store. Note that getting the size
      * requires iterating through the entire store because the items could expire
      * at any time, and hence the size is a dynamic number.
      */
-    size(): number;
+    readonly size: () => number;
     /** Remove all items from the store. */
-    clear(): void;
+    readonly clear: () => void;
     /**
      * Returns all items as map of key to value, mainly used for debugging dumps.
      * The type T is applied to all values, even though they might not be of type
      * T (in the case when you store different data types in the same store).
      */
-    asMap<T>(): Map<string, StoredObject<T>>;
+    readonly asMap: <T>() => Map<string, StoredObject<T>>;
     /** Returns the ms timestamp for the last GC (garbage collection). */
-    get lastGcMs(): number;
+    readonly getLastGcMs: () => number;
     /** Set the ms timestamp for the last GC (garbage collection). */
-    set lastGcMs(ms: number);
+    readonly setLastGcMs: (ms: number) => void;
     /** Perform garbage-collection if due, else do nothing. */
-    gc(): void;
+    readonly gc: () => void;
     /**
      * Perform garbage collection immediately without checking whether we are
      * due for the next GC or not.
      */
-    gcNow(): void;
+    readonly gcNow: () => void;
     /** Returns `this` casted into a StorageAdapter<T>. */
-    asStorageAdapter<T>(): StorageAdapter<T>;
-}
+    readonly asStorageAdapter: <T>() => StorageAdapter<T>;
+};
+type LocalStore = ReturnType<typeof createLocalStore>;
 /**
  * Default local store ready for immediate use. You can create new instances if
  * you want, but most likely you will only need one store instance.
  */
-declare const localStore: LocalStore;
-/**
- * Class to represent one key in the store with a default expiration.
- */
-declare class LocalStoreItem<T> {
-    readonly key: string;
-    readonly store: LocalStore;
+declare const localStore: {
+    /** Input name for the store. */
+    readonly storeName: string;
+    /**
+     * The prefix string for the local storage key which identifies items
+     * belonging to this namespace.
+     */
+    readonly keyPrefix: string;
+    /** Default expiry to use if not specified in set(). */
     readonly defaultExpiryMs: number;
-    constructor(key: string, defaultExpiryMs?: number | Duration, store?: LocalStore);
+    /** Time interval for when GC's occur. */
+    readonly gcIntervalMs: number;
+    /** Local storage key name for the last GC completed timestamp. */
+    readonly gcMsStorageKey: string;
+    /** Set a value in the store. */
+    readonly set: <T>(key: string, value: T, expiryDeltaMs?: number | Duration) => T;
+    /** Delete one or multiple keys. */
+    readonly delete: (key: string | string[]) => void;
+    /** Mainly used to get the expiration timestamp of an object. */
+    readonly getStoredObject: <T>(key: string) => StoredObject<T> | undefined;
+    /** Get a value by key, or undefined if it does not exist. */
+    readonly get: <T>(key: string) => T | undefined;
+    /** Generic way to iterate through all entries. */
+    readonly forEach: <T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void) => void;
+    /**
+     * Returns the number of items in the store. Note that getting the size
+     * requires iterating through the entire store because the items could expire
+     * at any time, and hence the size is a dynamic number.
+     */
+    readonly size: () => number;
+    /** Remove all items from the store. */
+    readonly clear: () => void;
+    /**
+     * Returns all items as map of key to value, mainly used for debugging dumps.
+     * The type T is applied to all values, even though they might not be of type
+     * T (in the case when you store different data types in the same store).
+     */
+    readonly asMap: <T>() => Map<string, StoredObject<T>>;
+    /** Returns the ms timestamp for the last GC (garbage collection). */
+    readonly getLastGcMs: () => number;
+    /** Set the ms timestamp for the last GC (garbage collection). */
+    readonly setLastGcMs: (ms: number) => void;
+    /** Perform garbage-collection if due, else do nothing. */
+    readonly gc: () => void;
+    /**
+     * Perform garbage collection immediately without checking whether we are
+     * due for the next GC or not.
+     */
+    readonly gcNow: () => void;
+    /** Returns `this` casted into a StorageAdapter<T>. */
+    readonly asStorageAdapter: <T>() => StorageAdapter<T>;
+};
+/** Create a local store item with a key and a default expiration. */
+declare function localStoreItem<T>(key: string, expiryMs?: number | Duration, store?: LocalStore): {
+    key: string;
+    defaultExpiryMs: number | undefined;
+    store: {
+        /** Input name for the store. */
+        readonly storeName: string;
+        /**
+         * The prefix string for the local storage key which identifies items
+         * belonging to this namespace.
+         */
+        readonly keyPrefix: string;
+        /** Default expiry to use if not specified in set(). */
+        readonly defaultExpiryMs: number;
+        /** Time interval for when GC's occur. */
+        readonly gcIntervalMs: number;
+        /** Local storage key name for the last GC completed timestamp. */
+        readonly gcMsStorageKey: string;
+        /** Set a value in the store. */
+        readonly set: <T_1>(key: string, value: T_1, expiryDeltaMs?: number | Duration) => T_1;
+        /** Delete one or multiple keys. */
+        readonly delete: (key: string | string[]) => void;
+        /** Mainly used to get the expiration timestamp of an object. */
+        readonly getStoredObject: <T_1>(key: string) => StoredObject<T_1> | undefined;
+        /** Get a value by key, or undefined if it does not exist. */
+        readonly get: <T_1>(key: string) => T_1 | undefined;
+        /** Generic way to iterate through all entries. */
+        readonly forEach: <T_1>(callback: (key: string, value: T_1, expiryMs: number, storedMs: number) => void) => void;
+        /**
+         * Returns the number of items in the store. Note that getting the size
+         * requires iterating through the entire store because the items could expire
+         * at any time, and hence the size is a dynamic number.
+         */
+        readonly size: () => number;
+        /** Remove all items from the store. */
+        readonly clear: () => void;
+        /**
+         * Returns all items as map of key to value, mainly used for debugging dumps.
+         * The type T is applied to all values, even though they might not be of type
+         * T (in the case when you store different data types in the same store).
+         */
+        readonly asMap: <T_1>() => Map<string, StoredObject<T_1>>;
+        /** Returns the ms timestamp for the last GC (garbage collection). */
+        readonly getLastGcMs: () => number;
+        /** Set the ms timestamp for the last GC (garbage collection). */
+        readonly setLastGcMs: (ms: number) => void;
+        /** Perform garbage-collection if due, else do nothing. */
+        readonly gc: () => void;
+        /**
+         * Perform garbage collection immediately without checking whether we are
+         * due for the next GC or not.
+         */
+        readonly gcNow: () => void;
+        /** Returns `this` casted into a StorageAdapter<T>. */
+        readonly asStorageAdapter: <T_1>() => StorageAdapter<T_1>;
+    };
     /** Set a value in the store. */
     set(value: T, expiryDeltaMs?: number | undefined): void;
     /**
@@ -112,8 +214,7 @@ declare class LocalStoreItem<T> {
     get(): T | undefined;
     /** Delete this key from the store. */
     delete(): void;
-}
-/** Create a local store item with a key and a default expiration. */
-declare function localStoreItem<T>(key: string, expiryMs?: number | Duration, store?: LocalStore): LocalStoreItem<T>;
+};
+type LocalStoreItem<T> = ReturnType<typeof localStoreItem<T>>;
 
-export { LocalStore, LocalStoreConfig, LocalStoreItem, configureLocalStore, localStore, localStoreItem };
+export { type LocalStore, LocalStoreConfig, type LocalStoreItem, configureLocalStore, createLocalStore, localStore, localStoreItem };