@choksheak/ts-utils 0.2.9 → 0.3.1

package/iterators.mjs

@@ -0,0 +1,9 @@
+// src/iterators.ts
+function* concatIterators(...iterators) {
+  for (const iterator of iterators) {
+    yield* iterator;
+  }
+}
+export {
+  concatIterators
+};

package/kvStore.cjs

@@ -0,0 +1,365 @@
+"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/kvStore.ts
+var kvStore_exports = {};
+__export(kvStore_exports, {
+  KvStore: () => KvStore,
+  KvStoreConfig: () => KvStoreConfig,
+  KvStoreItem: () => KvStoreItem,
+  configureKvStore: () => configureKvStore,
+  kvStore: () => kvStore,
+  kvStoreItem: () => kvStoreItem
+});
+module.exports = __toCommonJS(kvStore_exports);
+
+// src/timeConstants.ts
+var MS_PER_SECOND = 1e3;
+var MS_PER_MINUTE = 6e4;
+var MS_PER_HOUR = 36e5;
+var MS_PER_DAY = 864e5;
+
+// src/duration.ts
+function durationToMs(duration) {
+  const daysMs = (duration.days ?? 0) * MS_PER_DAY;
+  const hoursMs = (duration.hours ?? 0) * MS_PER_HOUR;
+  const minsMs = (duration.minutes ?? 0) * MS_PER_MINUTE;
+  const secsMs = (duration.seconds ?? 0) * MS_PER_SECOND;
+  const msMs = duration.milliseconds ?? 0;
+  return daysMs + hoursMs + minsMs + secsMs + msMs;
+}
+function durationOrMsToMs(duration) {
+  return typeof duration === "number" ? duration : durationToMs(duration);
+}
+
+// src/kvStore.ts
+var KvStoreConfig = {
+  /**
+   * Name of the DB in the indexed DB.
+   * Updating the DB name will cause all old entries to be gone.
+   */
+  dbName: "KVStore",
+  /**
+   * Version of the DB schema. Most likely you will never want to change this.
+   * Updating the version will cause all old entries to be gone.
+   */
+  dbVersion: 1,
+  /**
+   * Name of the store within the indexed DB. Each DB can have multiple stores.
+   * In practice, it doesn't matter what you name this to be.
+   */
+  storeName: "kvStore",
+  /** 30 days in ms. */
+  expiryMs: MS_PER_DAY * 30,
+  /** Do GC once per day. */
+  gcIntervalMs: MS_PER_DAY
+};
+function configureKvStore(config) {
+  Object.assign(KvStoreConfig, config);
+}
+function validateStoredObject(obj) {
+  if (!obj || typeof obj !== "object" || typeof obj.key !== "string" || obj.value === void 0 || typeof obj.storedMs !== "number" || typeof obj.expiryMs !== "number" || Date.now() >= obj.expiryMs) {
+    return void 0;
+  }
+  return obj;
+}
+function withOnError(request, reject) {
+  request.onerror = (event) => {
+    reject(event);
+  };
+  return request;
+}
+var KvStore = class {
+  constructor(dbName, options) {
+    this.dbName = dbName;
+    this.dbVersion = options?.dbVersion ?? KvStoreConfig.dbVersion;
+    this.storeName = options?.storeName ?? KvStoreConfig.storeName;
+    this.defaultExpiryMs = options?.defaultExpiryMs ? durationOrMsToMs(options.defaultExpiryMs) : KvStoreConfig.expiryMs;
+    this.gcIntervalMs = options?.gcIntervalMs ? durationOrMsToMs(options.gcIntervalMs) : KvStoreConfig.gcIntervalMs;
+    this.gcMsStorageKey = `__kvStore:lastGcMs:${dbName}:v${this.dbVersion}:${this.storeName}`;
+  }
+  /** We'll init the DB only on first use. */
+  db;
+  /** Local storage key name for the last GC completed timestamp. */
+  gcMsStorageKey;
+  dbVersion;
+  storeName;
+  defaultExpiryMs;
+  gcIntervalMs;
+  async getOrCreateDb() {
+    if (!this.db) {
+      this.db = await new Promise((resolve, reject) => {
+        const request = withOnError(
+          globalThis.indexedDB.open(this.dbName, this.dbVersion),
+          reject
+        );
+        request.onupgradeneeded = (event) => {
+          const db = event.target.result;
+          const objectStore = db.createObjectStore(this.storeName, {
+            keyPath: "key"
+          });
+          objectStore.createIndex("key", "key", {
+            unique: true
+          });
+        };
+        request.onsuccess = (event) => {
+          const db = event.target.result;
+          resolve(db);
+        };
+      });
+    }
+    return this.db;
+  }
+  async transact(mode, callback) {
+    const db = await this.getOrCreateDb();
+    return await new Promise((resolve, reject) => {
+      const transaction = withOnError(
+        db.transaction(this.storeName, mode),
+        reject
+      );
+      transaction.onabort = (event) => {
+        reject(event);
+      };
+      const objectStore = transaction.objectStore(this.storeName);
+      callback(objectStore, resolve, reject);
+    });
+  }
+  /** Set a value in the store. */
+  async set(key, value, expiryDeltaMs = this.defaultExpiryMs) {
+    const nowMs = Date.now();
+    const obj = {
+      key,
+      value,
+      storedMs: nowMs,
+      expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs)
+    };
+    return await this.transact(
+      "readwrite",
+      (objectStore, resolve, reject) => {
+        const request = withOnError(objectStore.put(obj), reject);
+        request.onsuccess = () => {
+          resolve(value);
+          this.gc();
+        };
+      }
+    );
+  }
+  /** Delete one or multiple keys. */
+  async delete(key) {
+    return await this.transact(
+      "readwrite",
+      (objectStore, resolve, reject) => {
+        objectStore.transaction.oncomplete = () => {
+          resolve();
+        };
+        if (typeof key === "string") {
+          withOnError(objectStore.delete(key), reject);
+        } else {
+          for (const k of key) {
+            withOnError(objectStore.delete(k), reject);
+          }
+        }
+      }
+    );
+  }
+  /** Mainly used to get the expiration timestamp of an object. */
+  async getStoredObject(key) {
+    const stored = await this.transact(
+      "readonly",
+      (objectStore, resolve, reject) => {
+        const request = withOnError(objectStore.get(key), reject);
+        request.onsuccess = () => {
+          resolve(request.result);
+        };
+      }
+    );
+    if (!stored) {
+      return void 0;
+    }
+    try {
+      const obj = validateStoredObject(stored);
+      if (!obj) {
+        await this.delete(key);
+        this.gc();
+        return void 0;
+      }
+      return obj;
+    } catch (e) {
+      console.error(`Invalid kv value: ${key}=${JSON.stringify(stored)}:`, e);
+      await this.delete(key);
+      this.gc();
+      return void 0;
+    }
+  }
+  /** Get a value by key, or undefined if it does not exist. */
+  async get(key) {
+    const obj = await this.getStoredObject(key);
+    return obj?.value;
+  }
+  /** Generic way to iterate through all entries. */
+  async forEach(callback) {
+    await this.transact("readonly", (objectStore, resolve, reject) => {
+      const request = withOnError(objectStore.openCursor(), reject);
+      request.onsuccess = async (event) => {
+        const cursor = event.target.result;
+        if (cursor) {
+          if (cursor.key) {
+            const obj = validateStoredObject(cursor.value);
+            if (obj !== void 0) {
+              await callback(
+                String(cursor.key),
+                obj.value,
+                obj.expiryMs,
+                obj.storedMs
+              );
+            }
+          }
+          cursor.continue();
+        } else {
+          resolve();
+        }
+      };
+    });
+  }
+  /**
+   * 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.
+   */
+  async size() {
+    let count = 0;
+    await this.forEach(() => {
+      count++;
+    });
+    return count;
+  }
+  /** Remove all items from the store. */
+  async clear() {
+    const keys = [];
+    await this.forEach((key) => {
+      keys.push(key);
+    });
+    await this.delete(keys);
+  }
+  /**
+   * 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).
+   */
+  async asMap() {
+    const map = /* @__PURE__ */ new Map();
+    await 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. */
+  async gc() {
+    const lastGcMs = this.lastGcMs;
+    if (!lastGcMs) {
+      this.lastGcMs = Date.now();
+      return;
+    }
+    if (Date.now() < lastGcMs + this.gcIntervalMs) {
+      return;
+    }
+    await this.gcNow();
+  }
+  /**
+   * Perform garbage collection immediately without checking whether we are
+   * due for the next GC or not.
+   */
+  async gcNow() {
+    console.log(`Starting kvStore GC on ${this.dbName} v${this.dbVersion}...`);
+    this.lastGcMs = Date.now();
+    const keysToDelete = [];
+    await this.forEach(
+      async (key, value, expiryMs) => {
+        if (value === void 0 || Date.now() >= expiryMs) {
+          keysToDelete.push(key);
+        }
+      }
+    );
+    if (keysToDelete.length) {
+      await this.delete(keysToDelete);
+    }
+    console.log(
+      `Finished kvStore GC on ${this.dbName} v${this.dbVersion} - deleted ${keysToDelete.length} keys`
+    );
+    this.lastGcMs = Date.now();
+  }
+  /** Returns `this` casted into a StorageAdapter<T>. */
+  asStorageAdapter() {
+    return this;
+  }
+};
+var kvStore = new KvStore(KvStoreConfig.dbName);
+var KvStoreItem = class {
+  constructor(key, defaultExpiryMs = KvStoreConfig.expiryMs, store = kvStore) {
+    this.key = key;
+    this.store = store;
+    this.defaultExpiryMs = defaultExpiryMs && durationOrMsToMs(defaultExpiryMs);
+  }
+  defaultExpiryMs;
+  /** Set a value in the store. */
+  async set(value, expiryDeltaMs = this.defaultExpiryMs) {
+    await this.store.set(this.key, value, expiryDeltaMs);
+  }
+  /**
+   * Example usage:
+   *
+   *   const { value, storedMs, expiryMs, storedMs } =
+   *     await myKvItem.getStoredObject();
+   */
+  async getStoredObject() {
+    return await this.store.getStoredObject(this.key);
+  }
+  /** Get a value by key, or undefined if it does not exist. */
+  async get() {
+    return await this.store.get(this.key);
+  }
+  /** Delete this key from the store. */
+  async delete() {
+    await this.store.delete(this.key);
+  }
+};
+function kvStoreItem(key, expiryMs, store = kvStore) {
+  expiryMs = expiryMs && durationOrMsToMs(expiryMs);
+  return new KvStoreItem(key, expiryMs, store);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KvStore,
+  KvStoreConfig,
+  KvStoreItem,
+  configureKvStore,
+  kvStore,
+  kvStoreItem
+});

package/kvStore.d.mts

@@ -0,0 +1,139 @@
+import { Duration } from './duration.mjs';
+import { StoredObject, FullStorageAdapter, StorageAdapter } from './storageAdapter.mjs';
+
+/**
+ * Indexed DB key-value store with support for auto-expirations.
+ *
+ * Why use this?
+ * 1. Extremely simple interface to use indexed DBs.
+ * 2. Auto-expirations with GC frees you from worrying about data clean-up.
+ * 3. Any serializable data type can be stored (except undefined).
+ *
+ * How to use?
+ * Just use the `kvStore` global constant like the local storage, but with
+ * async interface functions as required by indexed DB.
+ *
+ * Why not use the indexed DB directly?
+ * It will require you to write a lot of code to reinvent the wheel.
+ */
+
+/** Global defaults can be updated directly. */
+declare const KvStoreConfig: {
+    /**
+     * Name of the DB in the indexed DB.
+     * Updating the DB name will cause all old entries to be gone.
+     */
+    dbName: string;
+    /**
+     * Version of the DB schema. Most likely you will never want to change this.
+     * Updating the version will cause all old entries to be gone.
+     */
+    dbVersion: number;
+    /**
+     * Name of the store within the indexed DB. Each DB can have multiple stores.
+     * In practice, it doesn't matter what you name this to be.
+     */
+    storeName: string;
+    /** 30 days in ms. */
+    expiryMs: number;
+    /** Do GC once per day. */
+    gcIntervalMs: number;
+};
+type KvStoreConfig = typeof KvStoreConfig;
+/** Convenience function to update global defaults. */
+declare function configureKvStore(config: Partial<KvStoreConfig>): void;
+/** Type to represent a full object with metadata stored in the store. */
+type KvStoredObject<T> = StoredObject<T> & {
+    key: string;
+};
+/**
+ * You can create multiple KvStores if you want, but most likely you will only
+ * need to use the default `kvStore` instance.
+ */
+declare class KvStore implements FullStorageAdapter<any> {
+    readonly dbName: string;
+    /** We'll init the DB only on first use. */
+    private db;
+    /** Local storage key name for the last GC completed timestamp. */
+    readonly gcMsStorageKey: string;
+    readonly dbVersion: number;
+    readonly storeName: string;
+    readonly defaultExpiryMs: number;
+    readonly gcIntervalMs: number;
+    constructor(dbName: string, options?: {
+        dbVersion?: number;
+        storeName?: string;
+        defaultExpiryMs?: number | Duration;
+        gcIntervalMs?: number | Duration;
+    });
+    private getOrCreateDb;
+    private transact;
+    /** Set a value in the store. */
+    set<T>(key: string, value: T, expiryDeltaMs?: number | Duration): Promise<T>;
+    /** Delete one or multiple keys. */
+    delete(key: string | string[]): Promise<void>;
+    /** Mainly used to get the expiration timestamp of an object. */
+    getStoredObject<T>(key: string): Promise<KvStoredObject<T> | undefined>;
+    /** Get a value by key, or undefined if it does not exist. */
+    get<T>(key: string): Promise<T | undefined>;
+    /** Generic way to iterate through all entries. */
+    forEach<T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void | Promise<void>): Promise<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(): Promise<number>;
+    /** Remove all items from the store. */
+    clear(): Promise<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>(): Promise<Map<string, StoredObject<T>>>;
+    /** Returns the ms timestamp for the last GC (garbage collection). */
+    get lastGcMs(): number;
+    /** Set the ms timestamp for the last GC (garbage collection). */
+    set lastGcMs(ms: number);
+    /** Perform garbage-collection if due, else do nothing. */
+    gc(): Promise<void>;
+    /**
+     * Perform garbage collection immediately without checking whether we are
+     * due for the next GC or not.
+     */
+    gcNow(): Promise<void>;
+    /** Returns `this` casted into a StorageAdapter<T>. */
+    asStorageAdapter<T>(): StorageAdapter<T>;
+}
+/**
+ * Default KV 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 kvStore: KvStore;
+/**
+ * Class to represent one key in the store with a default expiration.
+ */
+declare class KvStoreItem<T> {
+    readonly key: string;
+    readonly store: KvStore;
+    readonly defaultExpiryMs: number;
+    constructor(key: string, defaultExpiryMs?: number | Duration, store?: KvStore);
+    /** Set a value in the store. */
+    set(value: T, expiryDeltaMs?: number | undefined): Promise<void>;
+    /**
+     * Example usage:
+     *
+     *   const { value, storedMs, expiryMs, storedMs } =
+     *     await myKvItem.getStoredObject();
+     */
+    getStoredObject(): Promise<KvStoredObject<T> | undefined>;
+    /** Get a value by key, or undefined if it does not exist. */
+    get(): Promise<T | undefined>;
+    /** Delete this key from the store. */
+    delete(): Promise<void>;
+}
+/** Create a KV store item with a key and a default expiration. */
+declare function kvStoreItem<T>(key: string, expiryMs?: number | Duration, store?: KvStore): KvStoreItem<T>;
+
+export { KvStore, KvStoreConfig, KvStoreItem, type KvStoredObject, configureKvStore, kvStore, kvStoreItem };