@choksheak/ts-utils 0.2.8 → 0.3.0

package/src/kvStore.ts

@@ -1,444 +0,0 @@
-/**
- * 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.
- */
-
-import { Duration, durationOrMsToMs } from "./duration";
-
-// 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;
-  storedMs: number;
-  expiryMs: 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) ||
-    !("storedMs" in obj) ||
-    typeof obj.storedMs !== "number" ||
-    obj.value === undefined ||
-    !("expiryMs" in obj) ||
-    typeof obj.expiryMs !== "number" ||
-    Date.now() >= obj.expiryMs
-  ) {
-    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,
-    expiryDeltaMs: number | Duration = this.defaultExpiryDeltaMs,
-  ): Promise<T> {
-    const nowMs = Date.now();
-    const obj: StoredObject<T> = {
-      key,
-      value,
-      storedMs: nowMs,
-      expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs),
-    };
-
-    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 getStoredObject<T>(
-    key: string,
-  ): Promise<StoredObject<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;
-    } 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 get<T>(key: string): Promise<T | undefined> {
-    const obj = await this.getStoredObject<T>(key);
-
-    return obj?.value;
-  }
-
-  public async forEach(
-    callback: (
-      key: string,
-      value: unknown,
-      expiryMs: 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.expiryMs);
-            } 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, expiryMs) => {
-      map.set(key, { value, expiryMs });
-    });
-    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, expiryMs: number) => {
-        if (value === undefined || 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`,
-    );
-
-    // 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,
-);
-
-/**
- * Class to represent one key in the store with a default expiration.
- */
-class KvStoreItem<T> {
-  public constructor(
-    public readonly key: string,
-    public readonly defaultExpiryDeltaMs: number,
-    public readonly store = kvStore,
-  ) {}
-
-  /**
-   * Example usage:
-   *
-   *   const { value, storedMs, expiryMs } = await myKvItem.getStoredObject();
-   */
-  public async getStoredObject(): Promise<StoredObject<T> | undefined> {
-    return await this.store.getStoredObject(this.key);
-  }
-
-  public async get(): Promise<T | undefined> {
-    return await this.store.get(this.key);
-  }
-
-  public async set(
-    value: T,
-    expiryDeltaMs: number = this.defaultExpiryDeltaMs,
-  ): Promise<void> {
-    await this.store.set(this.key, value, expiryDeltaMs);
-  }
-
-  public async delete(): Promise<void> {
-    await this.store.delete(this.key);
-  }
-}
-
-/**
- * Create a KV store item with a key and a default expiration.
- */
-export function kvStoreItem<T>(
-  key: string,
-  defaultExpiration: number | Duration,
-): KvStoreItem<T> {
-  const defaultExpiryDeltaMs = durationOrMsToMs(defaultExpiration);
-
-  return new KvStoreItem<T>(key, defaultExpiryDeltaMs);
-}

package/src/localStorageCache.ts

@@ -1,121 +0,0 @@
-import { Duration, durationOrMsToMs } from "./duration";
-
-export type StoredItem<T> = { value: T; storedMs: number; expiryMs: number };
-
-/**
- * Simple local storage cache with support for auto-expiration.
- * Note that this works in the browser context only because nodejs does not
- * have local storage.
- *
- * Create a cache item accessor object with auto-expiration. The value will
- * always be stored as a string by applying JSON.stringify(), and will be
- * returned in the same object type by applying JSON.parse().
- *
- * In order to provide proper type-checking, please always specify the T
- * type parameter. E.g. const item = storeItem<string>("name", 10_000);
- *
- * @param key The store key in local storage.
- * @param expires Either a number in milliseconds, or a Duration object
- * @param logError Log an error if we found an invalid object in the store.
- *   The invalid object is usually a string that cannot be parsed as JSON.
- * @param defaultValue Specify a default value to use for the object. Defaults
- *   to undefined.
- */
-export function storeItem<T>(
-  key: string,
-  expires: number | Duration,
-  logError = true,
-  defaultValue?: T,
-) {
-  const expireDeltaMs = durationOrMsToMs(expires);
-
-  return new CacheItem<T>(key, expireDeltaMs, logError, defaultValue);
-}
-
-class CacheItem<T> {
-  /**
-   * Create a cache item accessor object with auto-expiration.
-   */
-  public constructor(
-    public readonly key: string,
-    public readonly expireDeltaMs: number,
-    public readonly logError: boolean,
-    public readonly defaultValue: T | undefined,
-  ) {}
-
-  /**
-   * Set the value of this item with auto-expiration.
-   */
-  public set(
-    value: T,
-    expiryDelta: number | Duration = this.expireDeltaMs,
-  ): void {
-    const nowMs = Date.now();
-    const toStore: StoredItem<T> = {
-      value,
-      storedMs: nowMs,
-      expiryMs: nowMs + durationOrMsToMs(expiryDelta),
-    };
-    const valueStr = JSON.stringify(toStore);
-
-    globalThis.localStorage.setItem(this.key, valueStr);
-  }
-
-  /**
-   * Example usage:
-   *
-   *   const { value, storedMs, expiryMs } = await myItem.getStoredItem();
-   */
-  public getStoredItem(): StoredItem<T> | undefined {
-    const jsonStr = globalThis.localStorage.getItem(this.key);
-
-    if (!jsonStr) {
-      return undefined;
-    }
-
-    try {
-      const obj: StoredItem<T> | undefined = JSON.parse(jsonStr);
-
-      if (
-        !obj ||
-        typeof obj !== "object" ||
-        !("value" in obj) ||
-        !("storedMs" in obj) ||
-        typeof obj.storedMs !== "number" ||
-        !("expiryMs" in obj) ||
-        typeof obj.expiryMs !== "number" ||
-        Date.now() >= obj.expiryMs
-      ) {
-        this.remove();
-        return undefined;
-      }
-
-      return obj;
-    } catch (e) {
-      if (this.logError) {
-        console.error(
-          `Found invalid storage value: ${this.key}=${jsonStr}:`,
-          e,
-        );
-      }
-      this.remove();
-      return undefined;
-    }
-  }
-
-  /**
-   * Get the value of this item, or undefined if value is not set or expired.
-   */
-  public get(): T | undefined {
-    const stored = this.getStoredItem();
-
-    return stored !== undefined ? stored.value : this.defaultValue;
-  }
-
-  /**
-   * Remove the value of this item.
-   */
-  public remove(): void {
-    globalThis.localStorage.removeItem(this.key);
-  }
-}

package/src/logging.ts

@@ -1,26 +0,0 @@
-export function stringify(u: unknown): string {
-  if (typeof u === "string") {
-    return u;
-  }
-
-  // If the object has a custom toString(), then use it.
-  if (
-    u !== null &&
-    typeof u === "object" &&
-    u.toString !== Object.prototype.toString
-  ) {
-    return u.toString();
-  }
-
-  return JSON.stringify(u);
-}
-
-export function capLength(u: unknown, maxLength = 400): string {
-  const s = stringify(u);
-
-  if (s.length <= maxLength) {
-    return s;
-  }
-
-  return s.slice(0, maxLength) + ` ... (${s.length - maxLength} more)`;
-}

package/src/nonEmpty.ts

@@ -1,18 +0,0 @@
-import { isEmpty } from "./isEmpty";
-
-/**
- * Type asserts that `t` is truthy.
- * Throws an error if `t` is null or undefined.
- *
- * @param varName The variable name to include in the error to throw when t is
- *   empty. Defaults to 'value'.
- */
-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/safeBtoa.ts

@@ -1,15 +0,0 @@
-/**
- * Base 64 encode the given input string, but safely.
- */
-export function safeBtoa(input: string): string {
-  // Convert the string to a UTF-8 encoded binary-safe string
-  const utf8Bytes = new TextEncoder().encode(input);
-
-  // Convert the binary data to a string for btoa
-  const binaryString = Array.from(utf8Bytes)
-    .map((byte) => String.fromCodePoint(byte))
-    .join("");
-
-  // Use btoa to encode the binary-safe string
-  return btoa(binaryString);
-}

package/src/safeParseFloat.ts

@@ -1,10 +0,0 @@
-/**
- * Returns 0 or the given defaultValue if the string is not a valid number.
- */
-export function safeParseFloat<T>(
-  s: string,
-  defaultValue: T | number = 0,
-): T | number {
-  const i = Number(s);
-  return isNaN(i) ? defaultValue : i;
-}

package/src/safeParseInt.ts

@@ -1,10 +0,0 @@
-/**
- * Returns 0 or the given defaultValue if the string is not a valid number.
- */
-export function safeParseInt<T>(
-  s: string,
-  defaultValue: T | number = 0,
-): T | number {
-  const i = Number(s);
-  return isNaN(i) ? defaultValue : Math.floor(i);
-}

package/src/sha256.ts

@@ -1,13 +0,0 @@
-/**
- * SHA-256 hash an input string into an ArrayBuffer.
- */
-export async function sha256(input: string): Promise<ArrayBuffer> {
-  // Encode the input string as a Uint8Array
-  const encoder = new TextEncoder();
-  const uint8Array = encoder.encode(input);
-
-  // Compute the SHA-256 hash using the SubtleCrypto API
-  const arrayBuffer = await crypto.subtle.digest("SHA-256", uint8Array);
-
-  return arrayBuffer;
-}

package/src/sum.ts

@@ -1,17 +0,0 @@
-/**
- * Add all the numbers together in the given array. Treats null, undefined and
- * NaN as zero.
- */
-export function sum(numbers: (number | null | undefined)[]): number {
-  return numbers.reduce(
-    (accumulated: number, current: number | null | undefined) => {
-      const value =
-        typeof current === "number" && !isNaN(current) && isFinite(current)
-          ? current
-          : 0;
-
-      return accumulated + value;
-    },
-    0,
-  );
-}

package/src/timeConstants.ts

@@ -1,22 +0,0 @@
-/**
- * Note that month and year do not have fixed durations, and hence are excluded
- * from this file.
- */
-
-export const MS_PER_SECOND = 1000;
-export const MS_PER_MINUTE = 60_000;
-export const MS_PER_HOUR = 3_600_000;
-export const MS_PER_DAY = 86_400_000;
-export const MS_PER_WEEK = 604_800_000;
-
-export const SECONDS_PER_MINUTE = 60;
-export const SECONDS_PER_HOUR = 3_600;
-export const SECONDS_PER_DAY = 86_400;
-export const SECONDS_PER_WEEK = 604_800;
-
-export const MINUTES_PER_HOUR = 60;
-export const MINUTES_PER_DAY = 1440;
-export const MINUTES_PER_WEEK = 10_080;
-
-export const HOURS_PER_DAY = 24;
-export const HOURS_PER_WEEK = 168;