@choksheak/ts-utils 0.1.5 → 0.1.6

package/nonEmpty.js

@@ -0,0 +1,58 @@
+"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/nonEmpty.ts
+var nonEmpty_exports = {};
+__export(nonEmpty_exports, {
+  nonEmpty: () => nonEmpty
+});
+module.exports = __toCommonJS(nonEmpty_exports);
+
+// src/isEmpty.ts
+function isEmpty(t) {
+  if (!t) {
+    return true;
+  }
+  if (typeof t !== "object") {
+    return false;
+  }
+  if ("length" in t) {
+    return t.length === 0;
+  }
+  if ("size" in t) {
+    return t.size === 0;
+  }
+  for (const k in t) {
+    return false;
+  }
+  return true;
+}
+
+// src/nonEmpty.ts
+function nonEmpty(t, varName = "value") {
+  if (isEmpty(t)) {
+    throw new Error(`Empty ${varName}: ${t}`);
+  }
+  return t;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  nonEmpty
+});
+//# sourceMappingURL=nonEmpty.js.map

package/nonEmpty.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/nonEmpty.ts","../src/isEmpty.ts"],"sourcesContent":["import { isEmpty } from \"./isEmpty\";\n\n/**\n * Type asserts that `t` is truthy.\n * Throws an error if `t` is null or undefined.\n */\nexport function nonEmpty<T>(\n  t: T | null | undefined | \"\" | 0 | -0 | 0n | false | typeof NaN,\n  varName = \"value\",\n): T {\n  if (isEmpty(t)) {\n    throw new Error(`Empty ${varName}: ${t}`);\n  }\n  return t as T;\n}\n","/**\n * Returns true if `t` is empty.\n */\nexport function isEmpty(t: unknown): boolean {\n  // Anything falsy is considered empty.\n  if (!t) {\n    return true;\n  }\n\n  // Arrays are also of type `object`.\n  if (typeof t !== \"object\") {\n    return false;\n  }\n\n  // `length` includes arrays as well.\n  if (\"length\" in t) {\n    return t.length === 0;\n  }\n\n  // `size` is for Set, Map, Blob etc.\n  if (\"size\" in t) {\n    return t.size === 0;\n  }\n\n  // Super fast check for object emptiness.\n  // https://stackoverflow.com/questions/679915/how-do-i-test-for-an-empty-javascript-object\n  for (const k in t) {\n    return false;\n  }\n\n  return true;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACGO,SAAS,QAAQ,GAAqB;AAE3C,MAAI,CAAC,GAAG;AACN,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,MAAM,UAAU;AACzB,WAAO;AAAA,EACT;AAGA,MAAI,YAAY,GAAG;AACjB,WAAO,EAAE,WAAW;AAAA,EACtB;AAGA,MAAI,UAAU,GAAG;AACf,WAAO,EAAE,SAAS;AAAA,EACpB;AAIA,aAAW,KAAK,GAAG;AACjB,WAAO;AAAA,EACT;AAEA,SAAO;AACT;;;ADzBO,SAAS,SACd,GACA,UAAU,SACP;AACH,MAAI,QAAQ,CAAC,GAAG;AACd,UAAM,IAAI,MAAM,SAAS,OAAO,KAAK,CAAC,EAAE;AAAA,EAC1C;AACA,SAAO;AACT;","names":[]}

package/nonNil.js

@@ -23,9 +23,9 @@ __export(nonNil_exports, {
   nonNil: () => nonNil
 });
 module.exports = __toCommonJS(nonNil_exports);
-function nonNil(t, varName = "variable") {
+function nonNil(t, varName = "value") {
   if (t === null || t === void 0) {
-    throw new Error(`Missing ${varName}`);
+    throw new Error(`Missing ${varName}: ${t}`);
   }
   return t;
 }

package/nonNil.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/nonNil.ts"],"sourcesContent":["/**\n * Type asserts that `t` is neither null nor undefined.\n * Throws an error if `t` is null or undefined.\n */\nexport function nonNil<T>(t: T | null | undefined, varName = \"variable\"): T {\n  if (t === null || t === undefined) {\n    throw new Error(`Missing ${varName}`);\n  }\n  return t;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,SAAS,OAAU,GAAyB,UAAU,YAAe;AAC1E,MAAI,MAAM,QAAQ,MAAM,QAAW;AACjC,UAAM,IAAI,MAAM,WAAW,OAAO,EAAE;AAAA,EACtC;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/nonNil.ts"],"sourcesContent":["/**\n * Type asserts that `t` is neither null nor undefined.\n * Throws an error if `t` is null or undefined.\n */\nexport function nonNil<T>(t: T | null | undefined, varName = \"value\"): T {\n  if (t === null || t === undefined) {\n    throw new Error(`Missing ${varName}: ${t}`);\n  }\n  return t;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,SAAS,OAAU,GAAyB,UAAU,SAAY;AACvE,MAAI,MAAM,QAAQ,MAAM,QAAW;AACjC,UAAM,IAAI,MAAM,WAAW,OAAO,KAAK,CAAC,EAAE;AAAA,EAC5C;AACA,SAAO;AACT;","names":[]}

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@choksheak/ts-utils",
   "license": "The Unlicense",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Random Typescript utilities with support for full tree-shaking",
   "private": false,
   "scripts": {
     "lint": "eslint src/**",
-    "format": "prettier --write \"**/*.{js,ts}\"",
-    "test": "jest",
-    "test:watch": "jest --watch",
+    "format": "prettier --write \"**/*.{ts}\"",
+    "test": "npm run clean && jest",
+    "test:watch": "npm run clean && jest --watch",
     "clean": "rm -rf dist",
-    "ci": "npm run clean && npm run lint && npm run format && npm run test",
+    "ci": "npm run lint && npm run format && npm run test",
     "build": "tsup src/*",
     "gen-types": "tsc --emitDeclarationOnly --declaration",
     "pub": "scripts/publish.sh"
@@ -21,6 +21,7 @@
     "@types/jest": "^27.5.2",
     "@types/node": "^16.18.97",
     "eslint": "^9.14.0",
+    "fake-indexeddb": "^6.0.0",
     "globals": "^15.12.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",

package/src/dateTimeStr.ts

@@ -0,0 +1,83 @@
+export class DateTimeStr {
+  public static yyyyMmDd(dt = new Date(), separator = "-"): string {
+    const yr = dt.getFullYear();
+    const mth = dt.getMonth() + 1;
+    const day = dt.getDate();
+
+    return (
+      yr +
+      separator +
+      (mth < 10 ? "0" + mth : mth) +
+      separator +
+      (day < 10 ? "0" + day : day)
+    );
+  }
+
+  public static hhMmSs(dt = new Date(), separator = ":"): string {
+    const hr = dt.getHours();
+    const min = dt.getMinutes();
+    const sec = dt.getSeconds();
+
+    return (
+      (hr < 10 ? "0" + hr : hr) +
+      separator +
+      (min < 10 ? "0" + min : min) +
+      separator +
+      (sec < 10 ? "0" + sec : sec)
+    );
+  }
+
+  public static hhMmSsMs(
+    dt = new Date(),
+    timeSeparator = ":",
+    msSeparator = ".",
+  ): string {
+    const ms = dt.getMilliseconds();
+
+    return (
+      DateTimeStr.hhMmSs(dt, timeSeparator) +
+      msSeparator +
+      (ms < 10 ? "00" + ms : ms < 100 ? "0" + ms : ms)
+    );
+  }
+
+  public static tz(dt = new Date()): string {
+    if (dt.getTimezoneOffset() === 0) {
+      return "Z";
+    }
+
+    const tzHours = dt.getTimezoneOffset() / 60;
+    return tzHours >= 0 ? "+" + tzHours : String(tzHours);
+  }
+
+  /** Full local date/time string. */
+  public static local(
+    dt = new Date(),
+    dateSeparator = "-",
+    dtSeparator = " ",
+    timeSeparator = ":",
+    msSeparator = ".",
+  ): string {
+    return (
+      DateTimeStr.yyyyMmDd(dt, dateSeparator) +
+      dtSeparator +
+      DateTimeStr.hhMmSsMs(dt, timeSeparator, msSeparator) +
+      DateTimeStr.tz(dt)
+    );
+  }
+
+  /** Use the default ISO string function to keep things simple here. */
+  public static utc(dt = new Date()) {
+    return dt.toISOString();
+  }
+
+  /** Default full local date+time string with full & concise info. */
+  public static get now() {
+    return DateTimeStr.local();
+  }
+
+  /** Default full UTC date+time string with full & concise info. */
+  public static get utcNow() {
+    return DateTimeStr.utc();
+  }
+}

package/src/isEmpty.ts

@@ -0,0 +1,32 @@
+/**
+ * Returns true if `t` is empty.
+ */
+export function isEmpty(t: unknown): boolean {
+  // Anything falsy is considered empty.
+  if (!t) {
+    return true;
+  }
+
+  // Arrays are also of type `object`.
+  if (typeof t !== "object") {
+    return false;
+  }
+
+  // `length` includes arrays as well.
+  if ("length" in t) {
+    return t.length === 0;
+  }
+
+  // `size` is for Set, Map, Blob etc.
+  if ("size" in t) {
+    return t.size === 0;
+  }
+
+  // Super fast check for object emptiness.
+  // https://stackoverflow.com/questions/679915/how-do-i-test-for-an-empty-javascript-object
+  for (const k in t) {
+    return false;
+  }
+
+  return true;
+}

package/src/kvStore.ts

@@ -0,0 +1,382 @@
+/**
+ * Indexed DB key-value store with support for auto-expirations.
+ *
+ * Why use this?
+ * 1. No need to worry about running out of storage.
+ * 2. Extremely simple interface to use indexed DBs.
+ * 3. Auto-expirations frees you from worrying about data clean-up.
+ * 4. Any serializable data type can be stored (except undefined).
+ *
+ * How to use?
+ * Just use the `kvStore` global constant like the local storage.
+ */
+
+// Updating the DB name will cause all old entries to be gone.
+const DEFAULT_DB_NAME = "KVStore";
+
+// Updating the version will cause all old entries to be gone.
+const DEFAULT_DB_VERSION = 1;
+
+// Use a constant store name to keep things simple.
+const STORE_NAME = "kvStore";
+
+/** One day in milliseconds. */
+export const MILLIS_PER_DAY = 86_400_000;
+
+/** 30 days in ms. */
+export const DEFAULT_EXPIRY_DELTA_MS = MILLIS_PER_DAY * 30;
+
+/** Do GC once per day. */
+export const GC_INTERVAL_MS = MILLIS_PER_DAY;
+
+type StoredObject<T> = {
+  key: string;
+  value: T;
+  expireMs: number;
+};
+
+/**
+ * Parse a stored value string. Returns undefined if invalid or expired.
+ * Throws an error if the string cannot be parsed as JSON.
+ */
+function validateStoredObject<T>(
+  obj: StoredObject<T>,
+): StoredObject<T> | undefined {
+  if (
+    !obj ||
+    typeof obj !== "object" ||
+    !("key" in obj) ||
+    typeof obj.key !== "string" ||
+    !("value" in obj) ||
+    obj.value === undefined ||
+    !("expireMs" in obj) ||
+    typeof obj.expireMs !== "number" ||
+    Date.now() >= obj.expireMs
+  ) {
+    return undefined;
+  }
+
+  return obj;
+}
+
+/** Add an `onerror` handler to the request. */
+function withOnError<T extends IDBRequest | IDBTransaction>(
+  request: T,
+  reject: (reason?: unknown) => void,
+): T {
+  request.onerror = (event) => {
+    reject(event);
+  };
+
+  return request;
+}
+
+export class KVStoreField<T> {
+  public constructor(
+    public readonly store: KVStore,
+    public readonly key: string,
+  ) {}
+
+  public get(): Promise<T | undefined> {
+    return this.store.get(this.key);
+  }
+
+  public set(t: T): Promise<T> {
+    return this.store.set(this.key, t);
+  }
+
+  public delete(): Promise<void> {
+    return this.store.delete(this.key);
+  }
+}
+
+/**
+ * You can create multiple KVStores if you want, but most likely you will only
+ * need to use the default `kvStore` instance.
+ */
+export class KVStore {
+  // We'll init the DB only on first use.
+  private db: IDBDatabase | undefined;
+
+  // Local storage key name for the last GC completed timestamp.
+  public readonly gcMsStorageKey: string;
+
+  public constructor(
+    public readonly dbName: string,
+    public readonly dbVersion: number,
+    public readonly defaultExpiryDeltaMs: number,
+  ) {
+    this.gcMsStorageKey = `__kvStore:lastGcMs:${dbName}:v${dbVersion}:${STORE_NAME}`;
+  }
+
+  private async getOrCreateDb() {
+    if (!this.db) {
+      this.db = await new Promise<IDBDatabase>((resolve, reject) => {
+        const request = withOnError(
+          globalThis.indexedDB.open(this.dbName, this.dbVersion),
+          reject,
+        );
+
+        request.onupgradeneeded = (event) => {
+          const db = (event.target as unknown as { result: IDBDatabase })
+            .result;
+
+          // Create the store on DB init.
+          const objectStore = db.createObjectStore(STORE_NAME, {
+            keyPath: "key",
+          });
+
+          objectStore.createIndex("key", "key", {
+            unique: true,
+          });
+        };
+
+        request.onsuccess = (event) => {
+          const db = (event.target as unknown as { result: IDBDatabase })
+            .result;
+          resolve(db);
+        };
+      });
+    }
+
+    return this.db;
+  }
+
+  private async transact<T>(
+    mode: IDBTransactionMode,
+    callback: (
+      objectStore: IDBObjectStore,
+      resolve: (t: T) => void,
+      reject: (reason?: unknown) => void,
+    ) => void,
+  ): Promise<T> {
+    const db = await this.getOrCreateDb();
+
+    return await new Promise<T>((resolve, reject) => {
+      const transaction = withOnError(db.transaction(STORE_NAME, mode), reject);
+
+      transaction.onabort = (event) => {
+        reject(event);
+      };
+
+      const objectStore = transaction.objectStore(STORE_NAME);
+
+      callback(objectStore, resolve, reject);
+    });
+  }
+
+  public async set<T>(
+    key: string,
+    value: T,
+    expireDeltaMs: number = this.defaultExpiryDeltaMs,
+  ): Promise<T> {
+    const obj = {
+      key,
+      value,
+      expireMs: Date.now() + expireDeltaMs,
+    };
+
+    return await this.transact<T>(
+      "readwrite",
+      (objectStore, resolve, reject) => {
+        const request = withOnError(objectStore.put(obj), reject);
+
+        request.onsuccess = () => {
+          resolve(value);
+
+          this.gc(); // check GC on every write
+        };
+      },
+    );
+  }
+
+  /** Delete one or multiple keys. */
+  public async delete(key: string | string[]): Promise<void> {
+    return await this.transact<void>(
+      "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);
+          }
+        }
+      },
+    );
+  }
+
+  public async get<T>(key: string): Promise<T | undefined> {
+    const stored = await this.transact<StoredObject<T> | undefined>(
+      "readonly",
+      (objectStore, resolve, reject) => {
+        const request = withOnError(objectStore.get(key), reject);
+
+        request.onsuccess = () => {
+          resolve(request.result);
+        };
+      },
+    );
+
+    if (!stored) {
+      return undefined;
+    }
+
+    try {
+      const obj = validateStoredObject(stored);
+      if (!obj) {
+        await this.delete(key);
+
+        this.gc(); // check GC on every read of an expired key
+
+        return undefined;
+      }
+
+      return obj.value;
+    } catch (e) {
+      console.error(`Invalid kv value: ${key}=${JSON.stringify(stored)}:`, e);
+      await this.delete(key);
+
+      this.gc(); // check GC on every read of an invalid key
+
+      return undefined;
+    }
+  }
+
+  public async forEach(
+    callback: (
+      key: string,
+      value: unknown,
+      expireMs: number,
+    ) => void | Promise<void>,
+  ): Promise<void> {
+    await this.transact<void>("readonly", (objectStore, resolve, reject) => {
+      const request = withOnError(objectStore.openCursor(), reject);
+
+      request.onsuccess = async (event) => {
+        const cursor = (
+          event.target as unknown as { result: IDBCursorWithValue }
+        ).result;
+
+        if (cursor) {
+          if (cursor.key) {
+            const obj = validateStoredObject(cursor.value);
+            if (obj) {
+              await callback(String(cursor.key), obj.value, obj.expireMs);
+            } else {
+              await callback(String(cursor.key), undefined, 0);
+            }
+          }
+          cursor.continue();
+        } else {
+          resolve();
+        }
+      };
+    });
+  }
+
+  /** Cannot be a getter because this needs to be async. */
+  public async size() {
+    let count = 0;
+    await this.forEach(() => {
+      count++;
+    });
+    return count;
+  }
+
+  public async clear() {
+    const keys: string[] = [];
+    await this.forEach((key) => {
+      keys.push(key);
+    });
+
+    await this.delete(keys);
+  }
+
+  /** Mainly for debugging dumps. */
+  public async asMap(): Promise<Map<string, unknown>> {
+    const map = new Map<string, unknown>();
+    await this.forEach((key, value, expireMs) => {
+      map.set(key, { value, expireMs });
+    });
+    return map;
+  }
+
+  public get lastGcMs(): number {
+    const lastGcMsStr = globalThis.localStorage.getItem(this.gcMsStorageKey);
+    if (!lastGcMsStr) return 0;
+
+    const ms = Number(lastGcMsStr);
+    return isNaN(ms) ? 0 : ms;
+  }
+
+  public set lastGcMs(ms: number) {
+    globalThis.localStorage.setItem(this.gcMsStorageKey, String(ms));
+  }
+
+  /** Perform garbage-collection if due. */
+  public async gc() {
+    const lastGcMs = this.lastGcMs;
+
+    // Set initial timestamp - no need GC now.
+    if (!lastGcMs) {
+      this.lastGcMs = Date.now();
+      return;
+    }
+
+    if (Date.now() < lastGcMs + GC_INTERVAL_MS) {
+      return; // not due for next GC yet
+    }
+
+    // GC is due now, so run it.
+    await this.gcNow();
+  }
+
+  /** Perform garbage-collection immediately without checking. */
+  public async gcNow() {
+    console.log(`Starting kvStore GC on ${this.dbName} v${this.dbVersion}...`);
+
+    // Prevent concurrent GC runs.
+    this.lastGcMs = Date.now();
+
+    const keysToDelete: string[] = [];
+    await this.forEach(
+      async (key: string, value: unknown, expireMs: number) => {
+        if (value === undefined || Date.now() >= expireMs) {
+          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`,
+    );
+
+    // Mark the end time as last GC time.
+    this.lastGcMs = Date.now();
+  }
+
+  /** Get an independent store item with a locked key and value type. */
+  public field<T>(key: string) {
+    return new KVStoreField<T>(this, key);
+  }
+}
+
+/**
+ * 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.
+ */
+export const kvStore = new KVStore(
+  DEFAULT_DB_NAME,
+  DEFAULT_DB_VERSION,
+  DEFAULT_EXPIRY_DELTA_MS,
+);

package/src/localStorageCache.ts

@@ -13,7 +13,10 @@ export class LocalStorageCache {
 
   public static getValue<T>(key: string, logError = true): T | undefined {
     const jsonStr = globalThis.localStorage.getItem(key);
-    if (!jsonStr) return undefined;
+
+    if (!jsonStr || typeof jsonStr !== "string") {
+      return undefined;
+    }
 
     try {
       const obj: { value: T; expireMs: number } | undefined =
@@ -22,17 +25,14 @@ export class LocalStorageCache {
         !obj ||
         typeof obj !== "object" ||
         !("value" in obj) ||
-        !("expireMs" in obj)
+        !("expireMs" in obj) ||
+        typeof obj.expireMs !== "number" ||
+        Date.now() >= obj.expireMs
       ) {
         globalThis.localStorage.removeItem(key);
         return undefined;
       }
 
-      if (Date.now() >= obj.expireMs) {
-        globalThis.localStorage.removeItem(key);
-        return undefined;
-      }
-
       return obj.value;
     } catch (e) {
       if (logError) {
@@ -43,3 +43,27 @@ export class LocalStorageCache {
     }
   }
 }
+
+/** Same as above, but saves some config for reuse. */
+export class LocalStorageCacheItem<T> {
+  public constructor(
+    public readonly key: string,
+    public readonly expireDeltaMs: number,
+    public readonly logError = true,
+    defaultValue?: T,
+  ) {
+    if (defaultValue !== undefined) {
+      if (this.get() === undefined) {
+        this.set(defaultValue);
+      }
+    }
+  }
+
+  public set(value: T) {
+    LocalStorageCache.setValue(this.key, value, this.expireDeltaMs);
+  }
+
+  public get(): T | undefined {
+    return LocalStorageCache.getValue(this.key, this.logError);
+  }
+}

package/src/nonEmpty.ts

@@ -0,0 +1,15 @@
+import { isEmpty } from "./isEmpty";
+
+/**
+ * Type asserts that `t` is truthy.
+ * Throws an error if `t` is null or undefined.
+ */
+export function nonEmpty<T>(
+  t: T | null | undefined | "" | 0 | -0 | 0n | false | typeof NaN,
+  varName = "value",
+): T {
+  if (isEmpty(t)) {
+    throw new Error(`Empty ${varName}: ${t}`);
+  }
+  return t as T;
+}

package/src/nonNil.ts

@@ -2,9 +2,9 @@
  * Type asserts that `t` is neither null nor undefined.
  * Throws an error if `t` is null or undefined.
  */
-export function nonNil<T>(t: T | null | undefined, varName = "variable"): T {
+export function nonNil<T>(t: T | null | undefined, varName = "value"): T {
   if (t === null || t === undefined) {
-    throw new Error(`Missing ${varName}`);
+    throw new Error(`Missing ${varName}: ${t}`);
   }
   return t;
 }