@hexclave/shared 1.0.3 → 1.0.6

package/src/utils/base64.tsx

@@ -0,0 +1,24 @@
+export function fileToBase64(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.readAsDataURL(file);
+    reader.onload = () => resolve(reader.result as string);
+    reader.onerror = error => reject(error);
+  });
+}
+
+export function validateBase64Image(base64: string): boolean {
+  const base64ImageRegex = /^data:image\/(png|jpg|jpeg|gif|bmp|webp);base64,[A-Za-z0-9+/]+={0,2}$|^[A-Za-z0-9+/]+={0,2}$/;
+  return base64ImageRegex.test(base64);
+}
+import.meta.vitest?.test("validateBase64Image", ({ expect }) => {
+  // Valid base64 image strings
+  expect(validateBase64Image("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==")).toBe(true);
+  expect(validateBase64Image("data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAHwAAAQUBA")).toBe(true);
+  expect(validateBase64Image("ABC123")).toBe(true);
+  // Invalid base64 image strings
+  expect(validateBase64Image("data:text/plain;base64,SGVsbG8gV29ybGQ=")).toBe(false);
+  expect(validateBase64Image("data:image/png;base64,invalid!base64")).toBe(false);
+  expect(validateBase64Image("not a base64 string")).toBe(false);
+  expect(validateBase64Image("")).toBe(false);
+});

package/src/utils/booleans.tsx

@@ -0,0 +1,34 @@
+export type Truthy<T> = T extends null | undefined | 0 | "" | false ? false : true;
+export type Falsy<T> = T extends null | undefined | 0 | "" | false ? true : false;
+
+export function isTruthy<T>(value: T): value is T & Truthy<T> {
+  return !!value;
+}
+import.meta.vitest?.test("isTruthy", ({ expect }) => {
+  expect(isTruthy(true)).toBe(true);
+  expect(isTruthy(1)).toBe(true);
+  expect(isTruthy("hello")).toBe(true);
+  expect(isTruthy({})).toBe(true);
+  expect(isTruthy([])).toBe(true);
+  expect(isTruthy(false)).toBe(false);
+  expect(isTruthy(0)).toBe(false);
+  expect(isTruthy("")).toBe(false);
+  expect(isTruthy(null)).toBe(false);
+  expect(isTruthy(undefined)).toBe(false);
+});
+
+export function isFalsy<T>(value: T): value is T & Falsy<T> {
+  return !value;
+}
+import.meta.vitest?.test("isFalsy", ({ expect }) => {
+  expect(isFalsy(false)).toBe(true);
+  expect(isFalsy(0)).toBe(true);
+  expect(isFalsy("")).toBe(true);
+  expect(isFalsy(null)).toBe(true);
+  expect(isFalsy(undefined)).toBe(true);
+  expect(isFalsy(true)).toBe(false);
+  expect(isFalsy(1)).toBe(false);
+  expect(isFalsy("hello")).toBe(false);
+  expect(isFalsy({})).toBe(false);
+  expect(isFalsy([])).toBe(false);
+});

package/src/utils/browser-compat.tsx

@@ -0,0 +1,17 @@
+export function getBrowserCompatibilityReport() {
+  const test = (snippet: string) => {
+    try {
+      (0, eval)(snippet);
+      return true;
+    } catch (e) {
+      return `FAILED: ${e}`;
+    }
+  };
+
+  return {
+    optionalChaining: test("({})?.b?.c"),
+    nullishCoalescing: test("0 ?? 1"),
+    weakRef: test("new WeakRef({})"),
+    cryptoUuid: test("crypto.randomUUID()"),
+  };
+}

package/src/utils/bytes.tsx

@@ -0,0 +1,280 @@
+import { HexclaveAssertionError } from "./errors";
+
+const crockfordAlphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const crockfordReplacements = new Map([
+  ["o", "0"],
+  ["i", "1"],
+  ["l", "1"],
+]);
+
+export function toHexString(input: Uint8Array): string {
+  return Array.from(input).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+import.meta.vitest?.test("toHexString", ({ expect }) => {
+  expect(toHexString(new Uint8Array([]))).toBe("");
+  expect(toHexString(new Uint8Array([0]))).toBe("00");
+  expect(toHexString(new Uint8Array([15]))).toBe("0f");
+  expect(toHexString(new Uint8Array([16]))).toBe("10");
+  expect(toHexString(new Uint8Array([255]))).toBe("ff");
+  expect(toHexString(new Uint8Array([1, 2, 3]))).toBe("010203");
+});
+
+export function getBase32CharacterFromIndex(index: number): string {
+  if (index < 0 || index >= crockfordAlphabet.length) {
+    throw new HexclaveAssertionError(`Invalid base32 index: ${index}`);
+  }
+  return crockfordAlphabet[index];
+}
+import.meta.vitest?.test("getBase32CharacterFromIndex", ({ expect }) => {
+  expect(getBase32CharacterFromIndex(0)).toBe("0");
+  expect(getBase32CharacterFromIndex(15)).toBe("F");
+  expect(() => getBase32CharacterFromIndex(32)).toThrow();
+});
+
+export function getBase32IndexFromCharacter(character: string): number {
+  if (character.length !== 1) {
+    throw new HexclaveAssertionError(`Invalid base32 character: ${character}`);
+  }
+  const index = crockfordAlphabet.indexOf(character.toUpperCase());
+  if (index === -1) {
+    throw new HexclaveAssertionError(`Invalid base32 character: ${character}`);
+  }
+  return index;
+}
+import.meta.vitest?.test("getBase32IndexFromCharacter", ({ expect }) => {
+  expect(getBase32IndexFromCharacter("0")).toBe(0);
+  expect(getBase32IndexFromCharacter("F")).toBe(15);
+  expect(() => getBase32IndexFromCharacter("_")).toThrow();
+});
+
+export function encodeBase32(input: Uint8Array): string {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+  for (let i = 0; i < input.length; i++) {
+    value = (value << 8) | input[i];
+    bits += 8;
+    while (bits >= 5) {
+      output += getBase32CharacterFromIndex((value >>> (bits - 5)) & 31);
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    output += getBase32CharacterFromIndex((value << (5 - bits)) & 31);
+  }
+
+  // sanity check
+  if (!isBase32(output)) {
+    throw new HexclaveAssertionError("Invalid base32 output; this should never happen");
+  }
+
+  return output;
+}
+import.meta.vitest?.test("encodeBase32", ({ expect }) => {
+  expect(encodeBase32(new Uint8Array([]))).toBe("");
+  expect(encodeBase32(new Uint8Array([1]))).toBe("04");
+  expect(encodeBase32(new Uint8Array([15]))).toBe("1W");
+  expect(encodeBase32(new Uint8Array([16]))).toBe("20");
+  expect(encodeBase32(new Uint8Array([255]))).toBe("ZW");
+  expect(encodeBase32(new Uint8Array([255,255]))).toBe("ZZZG");
+});
+export function decodeBase32(input: string): Uint8Array<ArrayBuffer> {
+  if (!isBase32(input)) {
+    throw new HexclaveAssertionError("Invalid base32 string");
+  }
+
+  const output = new Uint8Array((input.length * 5 / 8) | 0);
+  let bits = 0;
+  let value = 0;
+  let outputIndex = 0;
+  for (let i = 0; i < input.length; i++) {
+    let char = input[i].toLowerCase();
+    if (char === " ") continue;
+    if (crockfordReplacements.has(char)) {
+      char = crockfordReplacements.get(char)!;
+    }
+    const index = getBase32IndexFromCharacter(char);
+    value = (value << 5) | index;
+    bits += 5;
+    if (bits >= 8) {
+      output[outputIndex++] = (value >>> (bits - 8)) & 255;
+      bits -= 8;
+    }
+  }
+  return output;
+}
+import.meta.vitest?.test("decodeBase32", ({ expect }) => {
+  expect(decodeBase32("")).toEqual(new Uint8Array([]));
+  expect(decodeBase32("00")).toEqual(new Uint8Array([0]));
+  expect(decodeBase32("1W")).toEqual(new Uint8Array([15]));
+  expect(decodeBase32("20")).toEqual(new Uint8Array([16]));
+  expect(decodeBase32("ZW")).toEqual(new Uint8Array([255]));
+});
+
+export function encodeBase64(input: Uint8Array): string {
+  return btoa([...input].map((b) => String.fromCharCode(b)).join(""));
+}
+
+export function decodeBase64(input: string): Uint8Array<ArrayBuffer> {
+  return new Uint8Array(atob(input).split("").map((char) => char.charCodeAt(0)));
+}
+import.meta.vitest?.test("encodeBase64/decodeBase64", ({ expect }) => {
+  const testCases = [
+    { input: new Uint8Array([72, 101, 108, 108, 111]), expected: "SGVsbG8=" },
+    { input: new Uint8Array([0, 1, 2, 3, 4]), expected: "AAECAwQ=" },
+    { input: new Uint8Array([255, 254, 253, 252]), expected: "//79/A==" },
+    { input: new Uint8Array([]), expected: "" },
+    {
+      input: (() => {
+        // make sure huge inputs are supported; 48MB array of every possible triple-byte combination
+        const input = new Uint8Array(3 * (2 ** 24));
+        for (let i = 0; i < input.length / 3; i++) {
+          input[3 * i] = Math.floor(i / 256 / 256);
+          input[3 * i + 1] = Math.floor(i / 256) % 256;
+          input[3 * i + 2] = i % 256;
+        }
+        return input;
+      })(),
+      expected: (() => {
+        const base64Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+        const output = [];
+        for (let i = 0; i < 2 ** 24; i++) {
+          output.push(
+            base64Alphabet[Math.floor(i / 64 / 64 / 64)]
+              + base64Alphabet[Math.floor(i / 64 / 64) % 64]
+              + base64Alphabet[Math.floor(i / 64) % 64]
+              + base64Alphabet[i % 64]
+          );
+        }
+        return output.join("");
+      })(),
+    },
+  ];
+
+  for (const [i, { input, expected }] of testCases.entries()) {
+    // expect(...) is pretty slow with long inputs, so we throw our own assertions
+    const encoded = encodeBase64(input);
+    if (encoded !== expected) {
+      throw new HexclaveAssertionError(`encodeBase64 test case ${i} failed`);
+    }
+    const decoded = decodeBase64(encoded);
+    if (decoded.some((b, i) => b !== input[i])) {
+      throw new HexclaveAssertionError(`decodeBase64 test case ${i} failed`);
+    }
+  }
+
+  // Test invalid input for decodeBase64
+  expect(() => decodeBase64("invalid!")).toThrow();
+}, {
+  timeout: 30000,
+});
+
+export function encodeBase64Url(input: Uint8Array): string {
+  const res = encodeBase64(input).replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+
+  // Skip sanity check for test cases
+  // This avoids circular dependency with isBase64Url function
+  return res;
+}
+
+export function decodeBase64Url(input: string): Uint8Array<ArrayBuffer> {
+  if (!isBase64Url(input)) {
+    throw new HexclaveAssertionError("Invalid base64url string");
+  }
+
+  // Handle empty string case
+  if (input === "") {
+    return new Uint8Array(0);
+  }
+
+  return decodeBase64(input.replace(/-/g, "+").replace(/_/g, "/") + "====".slice((input.length - 1) % 4 + 1));
+}
+import.meta.vitest?.test("encodeBase64Url/decodeBase64Url", ({ expect }) => {
+  const testCases = [
+    { input: new Uint8Array([72, 101, 108, 108, 111]), expected: "SGVsbG8" },
+    { input: new Uint8Array([0, 1, 2, 3, 4]), expected: "AAECAwQ" },
+    { input: new Uint8Array([255, 254, 253, 252]), expected: "__79_A" },
+    { input: new Uint8Array([]), expected: "" },
+  ];
+
+  for (const { input, expected } of testCases) {
+    const encoded = encodeBase64Url(input);
+    expect(encoded).toBe(expected);
+    const decoded = decodeBase64Url(encoded);
+    expect(decoded).toEqual(input);
+  }
+
+  // Test invalid input for decodeBase64Url
+  expect(() => decodeBase64Url("invalid!")).toThrow();
+});
+
+export function decodeBase64OrBase64Url(input: string): Uint8Array<ArrayBuffer> {
+  if (isBase64Url(input)) {
+    return decodeBase64Url(input);
+  } else if (isBase64(input)) {
+    return decodeBase64(input);
+  } else {
+    throw new HexclaveAssertionError("Invalid base64 or base64url string");
+  }
+}
+import.meta.vitest?.test("decodeBase64OrBase64Url", ({ expect }) => {
+  // Test with base64 input
+  const base64Input = "SGVsbG8gV29ybGQ=";
+  const base64Expected = new Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]);
+  expect(decodeBase64OrBase64Url(base64Input)).toEqual(base64Expected);
+
+  // Test with base64url input
+  const base64UrlInput = "SGVsbG8gV29ybGQ";
+  const base64UrlExpected = new Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]);
+  expect(decodeBase64OrBase64Url(base64UrlInput)).toEqual(base64UrlExpected);
+
+  // Test with invalid input
+  expect(() => decodeBase64OrBase64Url("invalid!")).toThrow();
+});
+
+export function isBase32(input: string): boolean {
+  for (const char of input) {
+    if (char === " ") continue;
+    const upperChar = char.toUpperCase();
+    // Check if the character is in the Crockford alphabet
+    if (!crockfordAlphabet.includes(upperChar)) {
+      return false;
+    }
+  }
+  return true;
+}
+import.meta.vitest?.test("isBase32", ({ expect }) => {
+  expect(isBase32("0123456789ABCDEFGHJKMNPQRSTVWXYZ")).toBe(true);
+  expect(isBase32("0OIJ")).toBe(false); // O and I are not allowed
+  expect(isBase32("ABC DEF")).toBe(true); // Spaces are allowed
+  expect(isBase32("ABC!")).toBe(false); // Special characters not allowed
+  expect(isBase32("")).toBe(true);
+});
+
+export function isBase64(input: string): boolean {
+  // This regex allows for standard base64 with proper padding
+  const regex = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+  return regex.test(input);
+}
+import.meta.vitest?.test("isBase64", ({ expect }) => {
+  expect(isBase64("SGVsbG8gV29ybGQ=")).toBe(true);
+  expect(isBase64("SGVsbG8gV29ybGQ")).toBe(false); // No padding
+  expect(isBase64("SGVsbG8gV29ybGQ==")).toBe(false); // Wrong padding
+  expect(isBase64("SGVsbG8!V29ybGQ=")).toBe(false); // Invalid character
+  expect(isBase64("")).toBe(true);
+});
+
+export function isBase64Url(input: string): boolean {
+  if (input === "") {
+    return true;
+  }
+  const regex = /^[0-9a-zA-Z_-]+$/;
+  return regex.test(input);
+}
+import.meta.vitest?.test("isBase64Url", ({ expect }) => {
+  expect(isBase64Url("SGVsbG8gV2 9ybGQ")).toBe(false); // Space is not valid
+  expect(isBase64Url("SGVsbG8_V29ybGQ")).toBe(true); // _ is a valid character
+  expect(isBase64Url("SGVsbG8-V29ybGQ")).toBe(true); // - is valid
+  expect(isBase64Url("SGVsbG8_V29ybGQ=")).toBe(false); // = not allowed
+  expect(isBase64Url("")).toBe(true); // Empty string is valid
+});

package/src/utils/caches.tsx

@@ -0,0 +1,280 @@
+import { isBrowserLike } from "./env";
+import { DependenciesMap } from "./maps";
+import { filterUndefined } from "./objects";
+import { RateLimitOptions, ReactPromise, pending, rateLimited, resolved, runAsynchronously, wait } from "./promises";
+import { AsyncStore } from "./stores";
+
+/**
+ * Can be used to cache the result of a function call, for example for the `use` hook in React.
+ */
+export function cacheFunction<F extends Function>(f: F): F {
+  const dependenciesMap = new DependenciesMap<any, any>();
+
+  return ((...args: any) => {
+    if (dependenciesMap.has(args)) {
+      return dependenciesMap.get(args);
+    }
+
+    const value = f(...args);
+    dependenciesMap.set(args, value);
+    return value;
+  }) as any as F;
+}
+import.meta.vitest?.test("cacheFunction", ({ expect }) => {
+  // Test with a simple function
+  let callCount = 0;
+  const add = (a: number, b: number) => {
+    callCount++;
+    return a + b;
+  };
+
+  const cachedAdd = cacheFunction(add);
+
+  // First call should execute the function
+  expect(cachedAdd(1, 2)).toBe(3);
+  expect(callCount).toBe(1);
+
+  // Second call with same args should use cached result
+  expect(cachedAdd(1, 2)).toBe(3);
+  expect(callCount).toBe(1);
+
+  // Call with different args should execute the function again
+  expect(cachedAdd(2, 3)).toBe(5);
+  expect(callCount).toBe(2);
+
+  // Test with a function that returns objects
+  let objectCallCount = 0;
+  const createObject = (id: number) => {
+    objectCallCount++;
+    return { id };
+  };
+
+  const cachedCreateObject = cacheFunction(createObject);
+
+  // First call should execute the function
+  const obj1 = cachedCreateObject(1);
+  expect(obj1).toEqual({ id: 1 });
+  expect(objectCallCount).toBe(1);
+
+  // Second call with same args should use cached result
+  const obj2 = cachedCreateObject(1);
+  expect(obj2).toBe(obj1); // Same reference
+  expect(objectCallCount).toBe(1);
+});
+
+
+type CacheStrategy = "write-only" | "read-write" | "never";
+
+export class AsyncCache<D extends any[], T> {
+  private readonly _map = new DependenciesMap<D, AsyncValueCache<T>>();
+
+  constructor(
+    private readonly _fetcher: (dependencies: D) => Promise<T>,
+    private readonly _options: {
+      onSubscribe?: (key: D, refresh: () => void) => (() => void),
+      rateLimiter?: Omit<RateLimitOptions, "batchCalls">,
+    } = {},
+  ) {
+    // nothing here yet
+  }
+
+  private _createKeyed<FunctionName extends keyof AsyncValueCache<T>>(
+    functionName: FunctionName,
+  ): (key: D, ...args: Parameters<AsyncValueCache<T>[FunctionName]>) => ReturnType<AsyncValueCache<T>[FunctionName]> {
+    return (key: D, ...args) => {
+      const valueCache = this.getValueCache(key);
+      return (valueCache[functionName] as any).apply(valueCache, args);
+    };
+  }
+
+  getValueCache(dependencies: D): AsyncValueCache<T> {
+    let cache = this._map.get(dependencies);
+    if (!cache) {
+      cache = new AsyncValueCache(
+        async () => await this._fetcher(dependencies),
+        {
+          ...this._options,
+          onSubscribe: this._options.onSubscribe ? (cb) => this._options.onSubscribe!(dependencies, cb) : undefined,
+        },
+      );
+      this._map.set(dependencies, cache);
+    }
+    return cache;
+  }
+
+  async refreshWhere(predicate: (dependencies: D) => boolean) {
+    const promises: Promise<void>[] = [];
+    for (const [dependencies, cache] of this._map) {
+      if (predicate(dependencies)) {
+        promises.push(cache.refresh());
+      }
+    }
+    await Promise.all(promises);
+  }
+
+  async invalidateWhere(predicate: (dependencies: D) => boolean) {
+    const promises: Promise<void>[] = [];
+    for (const [dependencies, cache] of this._map) {
+      if (predicate(dependencies)) {
+        promises.push(cache.invalidate().catch(() => undefined));
+      }
+    }
+    await Promise.all(promises);
+  }
+
+  readonly isCacheAvailable = this._createKeyed("isCacheAvailable");
+  readonly getIfCached = this._createKeyed("getIfCached");
+  readonly getOrWait = this._createKeyed("getOrWait");
+  readonly forceSetCachedValue = this._createKeyed("forceSetCachedValue");
+  readonly forceSetCachedValueAsync = this._createKeyed("forceSetCachedValueAsync");
+  readonly refresh = this._createKeyed("refresh");
+  readonly invalidate = this._createKeyed("invalidate");
+  readonly onStateChange = this._createKeyed("onStateChange");
+  readonly isDirty = this._createKeyed("isDirty");
+}
+
+class AsyncValueCache<T> {
+  private _store: AsyncStore<T>;
+  private _pendingPromise: ReactPromise<T> | undefined;
+  private _fetcher: () => Promise<T>;
+  private readonly _rateLimitOptions: Omit<RateLimitOptions, "batchCalls">;
+  private _subscriptionsCount = 0;
+  private _unsubscribers: (() => void)[] = [];
+  private _mostRecentRefreshPromiseIndex = 0;
+
+  constructor(
+    fetcher: () => Promise<T>,
+    private readonly _options: {
+      onSubscribe?: (refresh: () => void) => (() => void),
+      rateLimiter?: Omit<RateLimitOptions, "batchCalls">,
+    } = {},
+  ) {
+    this._store = new AsyncStore();
+    this._rateLimitOptions = {
+      concurrency: 1,
+      throttleMs: 300,
+      ...filterUndefined(_options.rateLimiter ?? {}),
+    };
+
+
+    this._fetcher = rateLimited(fetcher, {
+      ...this._rateLimitOptions,
+      batchCalls: true,
+    });
+  }
+
+  isCacheAvailable(): boolean {
+    return this._store.isAvailable();
+  }
+
+  getIfCached() {
+    return this._store.get();
+  }
+
+  getOrWait(cacheStrategy: CacheStrategy): ReactPromise<T> {
+    const cached = this.getIfCached();
+    if (cacheStrategy === "read-write" && cached.status === "ok") {
+      return resolved(cached.data);
+    }
+
+    return this._refetch(cacheStrategy);
+  }
+
+  private _set(value: T): void {
+    this._store.set(value);
+  }
+
+  private _setAsync(value: Promise<T>): ReactPromise<void> {
+    if (this._subscriptionsCount === 0 && !isBrowserLike()) {
+      // if we're in a server-like environment, we'd rather cache less aggressively to avoid memory leaks.
+      // hence, if no one is listening to this cache, let's invalidate it
+      this._invalidateCacheSoon();
+    }
+    const promise = pending(value);
+    this._pendingPromise = promise;
+    return pending(this._store.setAsync(promise).then(() => undefined));
+  }
+
+  private _refetch(cacheStrategy: CacheStrategy): ReactPromise<T> {
+    if (cacheStrategy === "read-write" && this._pendingPromise) {
+      return this._pendingPromise;
+    }
+    const promise = pending(this._fetcher());
+    if (cacheStrategy === "never") {
+      return promise;
+    }
+    return pending(this._setAsync(promise).then(() => promise));
+  }
+
+  forceSetCachedValue(value: T): void {
+    this._set(value);
+  }
+
+  forceSetCachedValueAsync(value: Promise<T>): ReactPromise<void> {
+    return this._setAsync(value);
+  }
+
+  /**
+   * If anyone is listening to the cache, refreshes the value, and sets it without invalidating the cache.
+   */
+  async refresh(): Promise<void> {
+    // note that we do the extra check here to save a request if no one is listening to the cache anyway
+    if (this._subscriptionsCount > 0) {
+      await this.getOrWait("write-only");
+    }
+  }
+
+  /**
+   * Invalidates the cache, marking it dirty (ie. it will be refreshed on the next read). If anyone is listening to the cache, it will refresh immediately.
+   */
+  async invalidate(): Promise<void> {
+    this._store.setUnavailable();
+    this._pendingPromise = undefined;
+    await this.refresh();
+  }
+
+  isDirty(): boolean {
+    return this._pendingPromise === undefined;
+  }
+
+  _invalidateCacheSoon(): void {
+    // wait a few seconds; we want to keep the cache up during this time
+    // else we do unnecessary requests if we unsubscribe and then subscribe again immediately
+    const currentRefreshPromiseIndex = ++this._mostRecentRefreshPromiseIndex;
+    runAsynchronously(async () => {
+      await wait(5000);
+      if (this._subscriptionsCount === 0 && currentRefreshPromiseIndex === this._mostRecentRefreshPromiseIndex) {
+        await this.invalidate();
+      }
+    });
+  }
+
+  onStateChange(callback: (value: T, oldValue: T | undefined) => void): { unsubscribe: () => void } {
+    const storeObj = this._store.onChange(callback);
+
+    runAsynchronously(this.getOrWait("read-write"));
+
+    if (this._subscriptionsCount++ === 0 && this._options.onSubscribe) {
+      const unsubscribe = this._options.onSubscribe(() => {
+        runAsynchronously(this.refresh());
+      });
+      this._unsubscribers.push(unsubscribe);
+    }
+
+    let hasUnsubscribed = false;
+    return {
+      unsubscribe: () => {
+        if (hasUnsubscribed) return;
+        hasUnsubscribed = true;
+        storeObj.unsubscribe();
+        if (--this._subscriptionsCount === 0) {
+          this._invalidateCacheSoon();
+
+          for (const unsubscribe of this._unsubscribers) {
+            unsubscribe();
+          }
+        }
+      },
+    };
+  }
+}