@choksheak/ts-utils 0.2.9 → 0.3.1

package/kvStore.mjs

@@ -0,0 +1,333 @@
+// 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);
+}
+export {
+  KvStore,
+  KvStoreConfig,
+  KvStoreItem,
+  configureKvStore,
+  kvStore,
+  kvStoreItem
+};

package/localStore.cjs

@@ -0,0 +1,267 @@
+"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/localStore.ts
+var localStore_exports = {};
+__export(localStore_exports, {
+  LocalStore: () => LocalStore,
+  LocalStoreConfig: () => LocalStoreConfig,
+  LocalStoreItem: () => LocalStoreItem,
+  configureLocalStore: () => configureLocalStore,
+  localStore: () => localStore,
+  localStoreItem: () => localStoreItem
+});
+module.exports = __toCommonJS(localStore_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/localStore.ts
+var LocalStoreConfig = {
+  /** All items with the same store name will share the same storage space. */
+  storeName: "ts-utils",
+  /** 30 days in ms. */
+  expiryMs: MS_PER_DAY * 30,
+  /** Do GC once per day. */
+  gcIntervalMs: MS_PER_DAY
+};
+function configureLocalStore(config) {
+  Object.assign(LocalStoreConfig, config);
+}
+function validateStoredObject(obj) {
+  if (!obj || typeof obj !== "object" || obj.value === void 0 || typeof obj.storedMs !== "number" || typeof obj.expiryMs !== "number" || Date.now() >= obj.expiryMs) {
+    return void 0;
+  }
+  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);
+      }
+    }
+  }
+  /** 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();
+        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);
+      }
+    }
+  }
+  /**
+   * 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);
+        count++;
+      }
+    });
+    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);
+  }
+};
+function localStoreItem(key, expiryMs, store = localStore) {
+  expiryMs = expiryMs && durationOrMsToMs(expiryMs);
+  return new LocalStoreItem(key, expiryMs, store);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LocalStore,
+  LocalStoreConfig,
+  LocalStoreItem,
+  configureLocalStore,
+  localStore,
+  localStoreItem
+});