@choksheak/react-utils 0.1.6 → 0.1.8

package/src/utils/storage.ts

@@ -0,0 +1,197 @@
+import { kvStore } from "@choksheak/ts-utils/kvStore";
+
+export type StorageAdapter<T> = {
+  save: (key: string, value: T) => Promise<void> | void;
+  load: (key: string) => Promise<T | undefined> | T | undefined;
+  delete: (key: string) => Promise<void> | void;
+  clear: () => Promise<void> | void;
+};
+
+export type StorageOptions<T> = {
+  // If specified, this will be used and all other fields will be ignored.
+  store?: StorageAdapter<T>;
+
+  // Storage key in local storage for this data.
+  localStorageKey?: string;
+
+  // Storage key in indexed db for this data.
+  indexedDbKey?: string;
+
+  // How long to wait before the value is considered expired.
+  storeExpiryMs?: number;
+};
+
+export function getStorageAdapter<T>(
+  options: StorageOptions<T> | undefined,
+  defaultStoreExpiryMs: number,
+): StorageAdapter<T> | null {
+  const { localStorageKey, indexedDbKey, storeExpiryMs, store } = options ?? {};
+
+  if (store) {
+    return store;
+  }
+
+  const expiryMs = storeExpiryMs || defaultStoreExpiryMs;
+
+  if (localStorageKey) {
+    return new LocalStorageAdapter<T>(localStorageKey, expiryMs);
+  }
+
+  if (indexedDbKey) {
+    return new IndexedDbAdapter<T>(indexedDbKey, expiryMs);
+  }
+
+  return null;
+}
+
+/************************************************************************/
+/* Storage adapters                                                     */
+/************************************************************************/
+
+type ValueWithExpiration<T> = { value: T; expiresAt: number };
+
+/** Save state to memory only - not persisted. */
+export class InMemoryStorageAdapter<T> implements StorageAdapter<T> {
+  private readonly cache = new Map<string, ValueWithExpiration<T>>();
+
+  public constructor(
+    public readonly keyPrefix: string,
+    public readonly expiryMs: number,
+  ) {}
+
+  public save(key: string, value: T): void {
+    const fullKey = this.keyPrefix + ":" + key;
+    this.cache.set(fullKey, {
+      value,
+      expiresAt: Date.now() + this.expiryMs,
+    });
+  }
+
+  public load(key: string): T | undefined {
+    const fullKey = this.keyPrefix + ":" + key;
+    const cached = this.cache.get(fullKey);
+
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.value;
+    }
+
+    return undefined;
+  }
+
+  public delete(key: string): void {
+    const fullKey = this.keyPrefix + ":" + key;
+    this.cache.delete(fullKey);
+  }
+
+  public clear(): void {
+    this.cache.clear();
+  }
+}
+
+/** Save state to local storage. */
+export class LocalStorageAdapter<T> implements StorageAdapter<T> {
+  public constructor(
+    public readonly keyPrefix: string,
+    public readonly expiryMs: number,
+  ) {}
+
+  public save(key: string, value: T): void {
+    if (typeof window === "undefined") return;
+
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.setItem(
+      fullKey,
+      JSON.stringify({
+        value,
+        expiresAt: this.expiryMs ? Date.now() + this.expiryMs : 0,
+      } satisfies ValueWithExpiration<T>),
+    );
+  }
+
+  public load(key: string): T | undefined {
+    if (typeof window === "undefined") return undefined;
+
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = window.localStorage.getItem(fullKey);
+    if (!raw) return undefined;
+
+    try {
+      const box = JSON.parse(raw) as ValueWithExpiration<T>;
+      if (!box || (box.expiresAt && Date.now() >= box.expiresAt)) {
+        window.localStorage.removeItem(fullKey);
+        return undefined;
+      }
+
+      return box.value;
+    } catch {
+      // Ignore error.
+      window.localStorage.removeItem(fullKey);
+      return undefined;
+    }
+  }
+
+  public delete(key: string): void {
+    if (typeof window === "undefined") return;
+
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.removeItem(fullKey);
+  }
+
+  public clear(): void {
+    if (typeof window === "undefined") return;
+
+    for (const key of Object.keys(window.localStorage)) {
+      if (key.startsWith(this.keyPrefix)) {
+        window.localStorage.removeItem(key);
+      }
+    }
+  }
+}
+
+/** Save state to indexed db. */
+export class IndexedDbAdapter<T> implements StorageAdapter<T> {
+  public constructor(
+    public readonly keyPrefix: string,
+    public readonly expiryMs: number,
+  ) {}
+
+  public async save(key: string, value: T): Promise<void> {
+    if (typeof window === "undefined") return;
+
+    const fullKey = this.keyPrefix + ":" + key;
+    await kvStore.set(fullKey, JSON.stringify(value), this.expiryMs);
+  }
+
+  public async load(key: string): Promise<T | undefined> {
+    if (typeof window === "undefined") return undefined;
+
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = await kvStore.get<string>(fullKey);
+    if (raw === undefined) return undefined;
+
+    try {
+      return JSON.parse(raw);
+    } catch {
+      // Ignore error.
+      await kvStore.delete(fullKey);
+      return undefined;
+    }
+  }
+
+  public async delete(key: string): Promise<void> {
+    if (typeof window === "undefined") return;
+
+    const fullKey = this.keyPrefix + ":" + key;
+    await kvStore.delete(fullKey);
+  }
+
+  public async clear(): Promise<void> {
+    if (typeof window === "undefined") return;
+
+    await kvStore.forEach(async (k) => {
+      if (k.startsWith(this.keyPrefix)) {
+        await kvStore.delete(k);
+      }
+    });
+  }
+}

package/src/utils/stringify.test.ts

@@ -0,0 +1,38 @@
+import { stringifyDeterministicForKeys } from "./stringify";
+
+describe("stringifyDeterministicForKeys", () => {
+  test("happy", () => {
+    const expected = `{"a":1,"b":2,"c":{"e":1,"f":2}}`;
+
+    const actual1 = stringifyDeterministicForKeys({
+      a: 1,
+      b: 2,
+      c: { e: 1, f: 2 },
+    });
+    expect(actual1).toBe(expected);
+
+    const actual2 = stringifyDeterministicForKeys({
+      c: { f: 2, e: 1 },
+      b: 2,
+      a: 1,
+    });
+    expect(actual2).toBe(expected);
+  });
+
+  test("circular", () => {
+    const circular = { b: {}, a: 1 };
+    circular.b = circular;
+
+    const actual = stringifyDeterministicForKeys(circular);
+
+    expect(actual).toBe(`{"a":1,"b":"[Circular]"}`);
+  });
+
+  test("function", () => {
+    const fn = { b: {}, a: () => {} };
+
+    expect(() => stringifyDeterministicForKeys(fn)).toThrow(
+      `Functions should not be passed into query parameters`,
+    );
+  });
+});

package/src/utils/stringify.ts

@@ -0,0 +1,49 @@
+/**
+ * JSON stringify a value of any type, and returns an unsafe string. The string
+ * is "unsafe" because you might not be able to restore the original object
+ * using the serialized JSON. This is specifically used for query key generation
+ * and is not suitable for more general uses.
+ *
+ * Note: The given value should not contain any functions because functions
+ * cannot be serialized and deserialized properly.
+ */
+export function stringifyDeterministicForKeys(params: unknown): string {
+  const cache = new Set();
+
+  return JSON.stringify(params, (_, value) => {
+    if (typeof value === "function") {
+      throw new Error(`Functions should not be passed into query parameters`);
+    }
+
+    if (!value || typeof value !== "object") {
+      return value;
+    }
+
+    if (cache.has(value)) {
+      // Circular reference detected! Return a placeholder string.
+      return "[Circular]";
+    }
+
+    cache.add(value);
+
+    // Don't crash on circular references, but don't mark the top level object
+    // as circular because we want to return as much string as possible.
+    if (value !== params) {
+      try {
+        JSON.stringify(value);
+      } catch {
+        return "[Unserializable]";
+      }
+    }
+
+    return Object.keys(value)
+      .sort()
+      .reduce(
+        (result: Record<string, unknown>, key: string) => {
+          result[key] = value[key];
+          return result;
+        },
+        {} as Record<string, unknown>,
+      );
+  });
+}

package/utils/storage.d.mts

@@ -0,0 +1,46 @@
+type StorageAdapter<T> = {
+    save: (key: string, value: T) => Promise<void> | void;
+    load: (key: string) => Promise<T | undefined> | T | undefined;
+    delete: (key: string) => Promise<void> | void;
+    clear: () => Promise<void> | void;
+};
+type StorageOptions<T> = {
+    store?: StorageAdapter<T>;
+    localStorageKey?: string;
+    indexedDbKey?: string;
+    storeExpiryMs?: number;
+};
+declare function getStorageAdapter<T>(options: StorageOptions<T> | undefined, defaultStoreExpiryMs: number): StorageAdapter<T> | null;
+/** Save state to memory only - not persisted. */
+declare class InMemoryStorageAdapter<T> implements StorageAdapter<T> {
+    readonly keyPrefix: string;
+    readonly expiryMs: number;
+    private readonly cache;
+    constructor(keyPrefix: string, expiryMs: number);
+    save(key: string, value: T): void;
+    load(key: string): T | undefined;
+    delete(key: string): void;
+    clear(): void;
+}
+/** Save state to local storage. */
+declare class LocalStorageAdapter<T> implements StorageAdapter<T> {
+    readonly keyPrefix: string;
+    readonly expiryMs: number;
+    constructor(keyPrefix: string, expiryMs: number);
+    save(key: string, value: T): void;
+    load(key: string): T | undefined;
+    delete(key: string): void;
+    clear(): void;
+}
+/** Save state to indexed db. */
+declare class IndexedDbAdapter<T> implements StorageAdapter<T> {
+    readonly keyPrefix: string;
+    readonly expiryMs: number;
+    constructor(keyPrefix: string, expiryMs: number);
+    save(key: string, value: T): Promise<void>;
+    load(key: string): Promise<T | undefined>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export { InMemoryStorageAdapter, IndexedDbAdapter, LocalStorageAdapter, type StorageAdapter, type StorageOptions, getStorageAdapter };

package/utils/storage.d.ts

@@ -0,0 +1,44 @@
+export type StorageAdapter<T> = {
+    save: (key: string, value: T) => Promise<void> | void;
+    load: (key: string) => Promise<T | undefined> | T | undefined;
+    delete: (key: string) => Promise<void> | void;
+    clear: () => Promise<void> | void;
+};
+export type StorageOptions<T> = {
+    store?: StorageAdapter<T>;
+    localStorageKey?: string;
+    indexedDbKey?: string;
+    storeExpiryMs?: number;
+};
+export declare function getStorageAdapter<T>(options: StorageOptions<T> | undefined, defaultStoreExpiryMs: number): StorageAdapter<T> | null;
+/** Save state to memory only - not persisted. */
+export declare class InMemoryStorageAdapter<T> implements StorageAdapter<T> {
+    readonly keyPrefix: string;
+    readonly expiryMs: number;
+    private readonly cache;
+    constructor(keyPrefix: string, expiryMs: number);
+    save(key: string, value: T): void;
+    load(key: string): T | undefined;
+    delete(key: string): void;
+    clear(): void;
+}
+/** Save state to local storage. */
+export declare class LocalStorageAdapter<T> implements StorageAdapter<T> {
+    readonly keyPrefix: string;
+    readonly expiryMs: number;
+    constructor(keyPrefix: string, expiryMs: number);
+    save(key: string, value: T): void;
+    load(key: string): T | undefined;
+    delete(key: string): void;
+    clear(): void;
+}
+/** Save state to indexed db. */
+export declare class IndexedDbAdapter<T> implements StorageAdapter<T> {
+    readonly keyPrefix: string;
+    readonly expiryMs: number;
+    constructor(keyPrefix: string, expiryMs: number);
+    save(key: string, value: T): Promise<void>;
+    load(key: string): Promise<T | undefined>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/utils/storage.js

@@ -0,0 +1,162 @@
+"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/utils/storage.ts
+var storage_exports = {};
+__export(storage_exports, {
+  InMemoryStorageAdapter: () => InMemoryStorageAdapter,
+  IndexedDbAdapter: () => IndexedDbAdapter,
+  LocalStorageAdapter: () => LocalStorageAdapter,
+  getStorageAdapter: () => getStorageAdapter
+});
+module.exports = __toCommonJS(storage_exports);
+var import_kvStore = require("@choksheak/ts-utils/kvStore");
+function getStorageAdapter(options, defaultStoreExpiryMs) {
+  const { localStorageKey, indexedDbKey, storeExpiryMs, store } = options ?? {};
+  if (store) {
+    return store;
+  }
+  const expiryMs = storeExpiryMs || defaultStoreExpiryMs;
+  if (localStorageKey) {
+    return new LocalStorageAdapter(localStorageKey, expiryMs);
+  }
+  if (indexedDbKey) {
+    return new IndexedDbAdapter(indexedDbKey, expiryMs);
+  }
+  return null;
+}
+var InMemoryStorageAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  cache = /* @__PURE__ */ new Map();
+  save(key, value) {
+    const fullKey = this.keyPrefix + ":" + key;
+    this.cache.set(fullKey, {
+      value,
+      expiresAt: Date.now() + this.expiryMs
+    });
+  }
+  load(key) {
+    const fullKey = this.keyPrefix + ":" + key;
+    const cached = this.cache.get(fullKey);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.value;
+    }
+    return void 0;
+  }
+  delete(key) {
+    const fullKey = this.keyPrefix + ":" + key;
+    this.cache.delete(fullKey);
+  }
+  clear() {
+    this.cache.clear();
+  }
+};
+var LocalStorageAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  save(key, value) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.setItem(
+      fullKey,
+      JSON.stringify({
+        value,
+        expiresAt: this.expiryMs ? Date.now() + this.expiryMs : 0
+      })
+    );
+  }
+  load(key) {
+    if (typeof window === "undefined") return void 0;
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = window.localStorage.getItem(fullKey);
+    if (!raw) return void 0;
+    try {
+      const box = JSON.parse(raw);
+      if (!box || box.expiresAt && Date.now() >= box.expiresAt) {
+        window.localStorage.removeItem(fullKey);
+        return void 0;
+      }
+      return box.value;
+    } catch {
+      window.localStorage.removeItem(fullKey);
+      return void 0;
+    }
+  }
+  delete(key) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.removeItem(fullKey);
+  }
+  clear() {
+    if (typeof window === "undefined") return;
+    for (const key of Object.keys(window.localStorage)) {
+      if (key.startsWith(this.keyPrefix)) {
+        window.localStorage.removeItem(key);
+      }
+    }
+  }
+};
+var IndexedDbAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  async save(key, value) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    await import_kvStore.kvStore.set(fullKey, JSON.stringify(value), this.expiryMs);
+  }
+  async load(key) {
+    if (typeof window === "undefined") return void 0;
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = await import_kvStore.kvStore.get(fullKey);
+    if (raw === void 0) return void 0;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      await import_kvStore.kvStore.delete(fullKey);
+      return void 0;
+    }
+  }
+  async delete(key) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    await import_kvStore.kvStore.delete(fullKey);
+  }
+  async clear() {
+    if (typeof window === "undefined") return;
+    await import_kvStore.kvStore.forEach(async (k) => {
+      if (k.startsWith(this.keyPrefix)) {
+        await import_kvStore.kvStore.delete(k);
+      }
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InMemoryStorageAdapter,
+  IndexedDbAdapter,
+  LocalStorageAdapter,
+  getStorageAdapter
+});

package/utils/storage.mjs

@@ -0,0 +1,134 @@
+// src/utils/storage.ts
+import { kvStore } from "@choksheak/ts-utils/kvStore";
+function getStorageAdapter(options, defaultStoreExpiryMs) {
+  const { localStorageKey, indexedDbKey, storeExpiryMs, store } = options ?? {};
+  if (store) {
+    return store;
+  }
+  const expiryMs = storeExpiryMs || defaultStoreExpiryMs;
+  if (localStorageKey) {
+    return new LocalStorageAdapter(localStorageKey, expiryMs);
+  }
+  if (indexedDbKey) {
+    return new IndexedDbAdapter(indexedDbKey, expiryMs);
+  }
+  return null;
+}
+var InMemoryStorageAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  cache = /* @__PURE__ */ new Map();
+  save(key, value) {
+    const fullKey = this.keyPrefix + ":" + key;
+    this.cache.set(fullKey, {
+      value,
+      expiresAt: Date.now() + this.expiryMs
+    });
+  }
+  load(key) {
+    const fullKey = this.keyPrefix + ":" + key;
+    const cached = this.cache.get(fullKey);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.value;
+    }
+    return void 0;
+  }
+  delete(key) {
+    const fullKey = this.keyPrefix + ":" + key;
+    this.cache.delete(fullKey);
+  }
+  clear() {
+    this.cache.clear();
+  }
+};
+var LocalStorageAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  save(key, value) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.setItem(
+      fullKey,
+      JSON.stringify({
+        value,
+        expiresAt: this.expiryMs ? Date.now() + this.expiryMs : 0
+      })
+    );
+  }
+  load(key) {
+    if (typeof window === "undefined") return void 0;
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = window.localStorage.getItem(fullKey);
+    if (!raw) return void 0;
+    try {
+      const box = JSON.parse(raw);
+      if (!box || box.expiresAt && Date.now() >= box.expiresAt) {
+        window.localStorage.removeItem(fullKey);
+        return void 0;
+      }
+      return box.value;
+    } catch {
+      window.localStorage.removeItem(fullKey);
+      return void 0;
+    }
+  }
+  delete(key) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.removeItem(fullKey);
+  }
+  clear() {
+    if (typeof window === "undefined") return;
+    for (const key of Object.keys(window.localStorage)) {
+      if (key.startsWith(this.keyPrefix)) {
+        window.localStorage.removeItem(key);
+      }
+    }
+  }
+};
+var IndexedDbAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  async save(key, value) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    await kvStore.set(fullKey, JSON.stringify(value), this.expiryMs);
+  }
+  async load(key) {
+    if (typeof window === "undefined") return void 0;
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = await kvStore.get(fullKey);
+    if (raw === void 0) return void 0;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      await kvStore.delete(fullKey);
+      return void 0;
+    }
+  }
+  async delete(key) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    await kvStore.delete(fullKey);
+  }
+  async clear() {
+    if (typeof window === "undefined") return;
+    await kvStore.forEach(async (k) => {
+      if (k.startsWith(this.keyPrefix)) {
+        await kvStore.delete(k);
+      }
+    });
+  }
+};
+export {
+  InMemoryStorageAdapter,
+  IndexedDbAdapter,
+  LocalStorageAdapter,
+  getStorageAdapter
+};

package/utils/stringify.d.mts

@@ -0,0 +1,12 @@
+/**
+ * JSON stringify a value of any type, and returns an unsafe string. The string
+ * is "unsafe" because you might not be able to restore the original object
+ * using the serialized JSON. This is specifically used for query key generation
+ * and is not suitable for more general uses.
+ *
+ * Note: The given value should not contain any functions because functions
+ * cannot be serialized and deserialized properly.
+ */
+declare function stringifyDeterministicForKeys(params: unknown): string;
+
+export { stringifyDeterministicForKeys };

package/utils/stringify.d.ts

@@ -0,0 +1,10 @@
+/**
+ * JSON stringify a value of any type, and returns an unsafe string. The string
+ * is "unsafe" because you might not be able to restore the original object
+ * using the serialized JSON. This is specifically used for query key generation
+ * and is not suitable for more general uses.
+ *
+ * Note: The given value should not contain any functions because functions
+ * cannot be serialized and deserialized properly.
+ */
+export declare function stringifyDeterministicForKeys(params: unknown): string;