@choksheak/ts-utils 0.1.9 → 0.2.1

package/src/kvStore.ts

@@ -11,6 +11,8 @@
  * 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";
 
@@ -32,7 +34,8 @@ export const GC_INTERVAL_MS = MILLIS_PER_DAY;
 type StoredObject<T> = {
   key: string;
   value: T;
-  expireMs: number;
+  storedMs: number;
+  expiryMs: number;
 };
 
 /**
@@ -48,10 +51,12 @@ function validateStoredObject<T>(
     !("key" in obj) ||
     typeof obj.key !== "string" ||
     !("value" in obj) ||
+    !("storedMs" in obj) ||
+    typeof obj.storedMs !== "number" ||
     obj.value === undefined ||
-    !("expireMs" in obj) ||
-    typeof obj.expireMs !== "number" ||
-    Date.now() >= obj.expireMs
+    !("expiryMs" in obj) ||
+    typeof obj.expiryMs !== "number" ||
+    Date.now() >= obj.expiryMs
   ) {
     return undefined;
   }
@@ -168,12 +173,14 @@ export class KVStore {
   public async set<T>(
     key: string,
     value: T,
-    expireDeltaMs: number = this.defaultExpiryDeltaMs,
+    expiryDeltaMs: number | Duration = this.defaultExpiryDeltaMs,
   ): Promise<T> {
-    const obj = {
+    const nowMs = Date.now();
+    const obj: StoredObject<T> = {
       key,
       value,
-      expireMs: Date.now() + expireDeltaMs,
+      storedMs: nowMs,
+      expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs),
     };
 
     return await this.transact<T>(
@@ -210,7 +217,9 @@ export class KVStore {
     );
   }
 
-  public async get<T>(key: string): Promise<T | undefined> {
+  public async getStoredObject<T>(
+    key: string,
+  ): Promise<StoredObject<T> | undefined> {
     const stored = await this.transact<StoredObject<T> | undefined>(
       "readonly",
       (objectStore, resolve, reject) => {
@@ -236,7 +245,7 @@ export class KVStore {
         return undefined;
       }
 
-      return obj.value;
+      return obj;
     } catch (e) {
       console.error(`Invalid kv value: ${key}=${JSON.stringify(stored)}:`, e);
       await this.delete(key);
@@ -247,11 +256,17 @@ export class KVStore {
     }
   }
 
+  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,
-      expireMs: number,
+      expiryMs: number,
     ) => void | Promise<void>,
   ): Promise<void> {
     await this.transact<void>("readonly", (objectStore, resolve, reject) => {
@@ -266,7 +281,7 @@ export class KVStore {
           if (cursor.key) {
             const obj = validateStoredObject(cursor.value);
             if (obj) {
-              await callback(String(cursor.key), obj.value, obj.expireMs);
+              await callback(String(cursor.key), obj.value, obj.expiryMs);
             } else {
               await callback(String(cursor.key), undefined, 0);
             }
@@ -300,8 +315,8 @@ export class KVStore {
   /** 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 });
+    await this.forEach((key, value, expiryMs) => {
+      map.set(key, { value, expiryMs });
     });
     return map;
   }
@@ -345,8 +360,8 @@ export class KVStore {
 
     const keysToDelete: string[] = [];
     await this.forEach(
-      async (key: string, value: unknown, expireMs: number) => {
-        if (value === undefined || Date.now() >= expireMs) {
+      async (key: string, value: unknown, expiryMs: number) => {
+        if (value === undefined || Date.now() >= expiryMs) {
           keysToDelete.push(key);
         }
       },
@@ -380,3 +395,50 @@ export const kvStore = new KVStore(
   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,4 +1,6 @@
-import { Duration, durationToMs } from "./duration";
+import { Duration, durationOrMsToMs } from "./duration";
+
+export type StoredItem<T> = { value: T; storedMs: number; expiryMs: number };
 
 /**
  * Simple local storage cache with support for auto-expiration.
@@ -12,7 +14,12 @@ import { Duration, durationToMs } from "./duration";
  * In order to provide proper type-checking, please always specify the T
  * type parameter. E.g. const item = storeItem<string>("name", 10_000);
  *
- * expires - Either a number in milliseconds, or a Duration object
+ * @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,
@@ -20,8 +27,7 @@ export function storeItem<T>(
   logError = true,
   defaultValue?: T,
 ) {
-  const expireDeltaMs =
-    typeof expires === "number" ? expires : durationToMs(expires);
+  const expireDeltaMs = durationOrMsToMs(expires);
 
   return new CacheItem<T>(key, expireDeltaMs, logError, defaultValue);
 }
@@ -34,51 +40,57 @@ class CacheItem<T> {
     public readonly key: string,
     public readonly expireDeltaMs: number,
     public readonly logError: boolean,
-    defaultValue: T | undefined,
-  ) {
-    if (defaultValue !== undefined) {
-      if (this.get() === undefined) {
-        this.set(defaultValue);
-      }
-    }
-  }
+    public readonly defaultValue: T | undefined,
+  ) {}
 
   /**
    * Set the value of this item with auto-expiration.
    */
-  public set(value: T): void {
-    const expireMs = Date.now() + this.expireDeltaMs;
-    const valueStr = JSON.stringify({ value, expireMs });
+  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);
   }
 
   /**
-   * Get the value of this item, or undefined if value is not set or expired.
+   * Example usage:
+   *
+   *   const { value, storedMs, expiryMs } = await myItem.getStoredItem();
    */
-  public get(): T | undefined {
+  public getStoredItem(): StoredItem<T> | undefined {
     const jsonStr = globalThis.localStorage.getItem(this.key);
 
-    if (!jsonStr || typeof jsonStr !== "string") {
+    if (!jsonStr) {
       return undefined;
     }
 
     try {
-      const obj: { value: T; expireMs: number } | undefined =
-        JSON.parse(jsonStr);
+      const obj: StoredItem<T> | undefined = JSON.parse(jsonStr);
+
       if (
         !obj ||
         typeof obj !== "object" ||
         !("value" in obj) ||
-        !("expireMs" in obj) ||
-        typeof obj.expireMs !== "number" ||
-        Date.now() >= obj.expireMs
+        !("storedMs" in obj) ||
+        typeof obj.storedMs !== "number" ||
+        !("expiryMs" in obj) ||
+        typeof obj.expiryMs !== "number" ||
+        Date.now() >= obj.expiryMs
       ) {
-        globalThis.localStorage.removeItem(this.key);
+        this.remove();
         return undefined;
       }
 
-      return obj.value;
+      return obj;
     } catch (e) {
       if (this.logError) {
         console.error(
@@ -86,11 +98,20 @@ class CacheItem<T> {
           e,
         );
       }
-      globalThis.localStorage.removeItem(this.key);
+      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.
    */

package/src/nonEmpty.ts

@@ -3,6 +3,9 @@ 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,

package/src/nonNil.ts

@@ -1,6 +1,9 @@
 /**
  * Type asserts that `t` is neither null nor undefined.
  * Throws an error if `t` is null or undefined.
+ *
+ * @param varName The variable name to include in the error to throw when t is
+ *   nil. Defaults to 'value'.
  */
 export function nonNil<T>(t: T | null | undefined, varName = "value"): T {
   if (t === null || t === undefined) {

package/src/safeParseInt.ts

@@ -1,5 +1,8 @@
 /**
  * Returns 0 if the string is not a valid number.
+ *
+ * @param logError Log a console error if the given string is not a valid
+ *   number. Defaults to false (don't log anything).
  */
 export function safeParseInt(s: string, logError = false): number {
   const i = Number(s);

package/src/sleep.ts

@@ -1,3 +1,7 @@
+/**
+ * Sleep for a given number of milliseconds. Note that this method is async,
+ * so please remember to call it with await, like `await sleep(1000);`.
+ */
 export function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }