@indietabletop/appkit 3.4.0 → 3.6.0-0

package/lib/ModernIDB/VersionChangeManager.ts

@@ -0,0 +1,57 @@
+import { VersionChangeObjectStore } from "./ObjectStore.ts";
+import { VersionChangeTransaction } from "./Transaction.ts";
+import type { KeyPath, ModernIDBSchema } from "./types.ts";
+
+export class VersionChangeManager<
+  Schema extends ModernIDBSchema,
+  IndexNames extends {
+    [K in keyof Schema]?: string;
+  } = never,
+> {
+  readonly idbDatabase: IDBDatabase;
+  readonly event: IDBVersionChangeEvent;
+  readonly transaction: VersionChangeTransaction<Schema, IndexNames>;
+
+  constructor(props: {
+    idbDatabase: IDBDatabase;
+    event: IDBVersionChangeEvent;
+    idbTransaction: IDBTransaction;
+  }) {
+    this.idbDatabase = props.idbDatabase;
+    this.event = props.event;
+    this.transaction = new VersionChangeTransaction({
+      transaction: props.idbTransaction,
+    });
+  }
+
+  /**
+   * Creates a new object store with the given name and options and returns a new IDBObjectStore.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBDatabase/createObjectStore)
+   */
+  createObjectStore<StoreName extends string & keyof Schema>(
+    name: StoreName,
+    options?: {
+      autoIncrement?: boolean;
+      keyPath?:
+        | KeyPath<Schema[StoreName]>
+        | KeyPath<Schema[StoreName]>[]
+        | null;
+    },
+  ) {
+    const objectStore = this.idbDatabase.createObjectStore(name, options);
+    return new VersionChangeObjectStore<
+      Schema[StoreName],
+      IndexNames[StoreName] extends string ? IndexNames[StoreName] : never
+    >(objectStore);
+  }
+
+  /**
+   * Deletes the object store with the given name.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBDatabase/deleteObjectStore)
+   */
+  deleteObjectStore(name: string): void {
+    this.idbDatabase.deleteObjectStore(name);
+  }
+}

package/lib/ModernIDB/bindings/factory.tsx

@@ -0,0 +1,160 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { Failure, isAsyncOp, Pending, Success } from "../../async-op.ts";
+import { caughtValueToString } from "../../caught-value.ts";
+import { useAsyncOp } from "../../use-async-op.ts";
+import type { AnyModernIDB } from "../types.ts";
+import type {
+  DatabaseOpenRequestOp,
+  FlattenSuccessOps,
+  InaccessibleDatabaseError,
+  QueryOp,
+} from "./types.ts";
+import { toKnownError } from "./utils.tsx";
+
+export function createDatabaseBindings<T extends AnyModernIDB>(db: T) {
+  const DatabaseContext = createContext(db);
+
+  const DatabaseOpenRequest = createContext<DatabaseOpenRequestOp<T>>(
+    new Pending(),
+  );
+
+  const cache = new Map<string, unknown>();
+
+  /**
+   * Performs an IndexedDB query and watches for changes.
+   *
+   * Note that queries will only be executed once IndexedDB is open.
+   *
+   * If query output is an AsyncOp, it will be flattened. In other words, you
+   * will only get one 'layer' of async ops.
+   *
+   * Provide a cache key if you want to make sure that data is synchronously
+   * available during mounts/unmounts.
+   */
+  function useQuery<Output>(
+    /**
+     * `query` must have stable identity.
+     *
+     * Make sure you use `useCallback` or a module-scoped function.
+     */
+    query: (db: T) => Promise<Output>,
+
+    cacheKey?: string,
+  ): FlattenSuccessOps<QueryOp<Output>> {
+    const openRequest = useDatabaseOpenRequest();
+    const [queryOp, setOp] = useState<QueryOp<Output>>(new Pending());
+
+    useEffect(() => {
+      async function runQuery(): Promise<void> {
+        if (openRequest.isSuccess) {
+          try {
+            const data = await query(openRequest.value);
+            const success = new Success(data);
+            setOp(success);
+
+            if (cacheKey) {
+              cache.set(cacheKey, success);
+            }
+          } catch (error) {
+            const failure = new Failure({
+              type: "QUERY_ERROR" as const,
+              error: caughtValueToString(error),
+            });
+
+            setOp(failure);
+            if (cacheKey) {
+              cache.set(cacheKey, failure);
+            }
+          }
+        }
+      }
+
+      db.addEventListener("readwrite", runQuery);
+      window.addEventListener("focus", runQuery);
+      void runQuery();
+
+      return () => {
+        db.removeEventListener("readwrite", runQuery);
+        window.removeEventListener("focus", runQuery);
+      };
+    }, [cacheKey, openRequest, query]);
+
+    return openRequest.flatMap(() => {
+      const flattenOutput = (output: Output) => {
+        if (isAsyncOp(output)) {
+          return output as FlattenSuccessOps<QueryOp<Output>>;
+        }
+
+        return new Success(output) as FlattenSuccessOps<QueryOp<Output>>;
+      };
+
+      if (cacheKey) {
+        const lastResult = cache.get(cacheKey) as QueryOp<Output> | undefined;
+
+        if (lastResult && queryOp.isPending) {
+          return lastResult.flatMap(flattenOutput);
+        }
+      }
+
+      return queryOp.flatMap(flattenOutput);
+    });
+  }
+
+  function useDatabase() {
+    return useContext(DatabaseContext);
+  }
+
+  function useDatabaseOpenRequest() {
+    return useContext(DatabaseOpenRequest);
+  }
+
+  function DatabaseProvider(props: { children: ReactNode }) {
+    const { op, setSuccess, setFailure } = useAsyncOp<
+      T,
+      InaccessibleDatabaseError
+    >();
+
+    useEffect(() => {
+      db.open({
+        onBlocking() {
+          setFailure({ type: "CLOSED_FOR_UPGRADE" });
+          db.close();
+          console.info("Database closed due to version upgrade.");
+        },
+      }).then(
+        () => {
+          setSuccess(db);
+          console.info("Database open.");
+        },
+        (error: unknown) => {
+          setFailure(toKnownError(error));
+          console.warn(`Request to open database failed.`);
+        },
+      );
+
+      return () => {
+        db.close();
+        console.info("Database closed.");
+      };
+    }, [setFailure, setSuccess]);
+
+    return (
+      <DatabaseOpenRequest.Provider value={op}>
+        {props.children}
+      </DatabaseOpenRequest.Provider>
+    );
+  }
+
+  return {
+    useQuery,
+    useDatabase,
+    useDatabaseOpenRequest,
+    DatabaseProvider,
+  };
+}

package/lib/ModernIDB/bindings/index.ts

@@ -0,0 +1,2 @@
+export * from "./factory.tsx";
+export * from "./types.ts";

package/lib/ModernIDB/bindings/types.ts

@@ -0,0 +1,56 @@
+import type { AsyncOp, Success } from "../../async-op.ts";
+import type { AnyModernIDB } from "../types.ts";
+
+export type DatabaseQueryOpFailure = QueryError | InaccessibleDatabaseError;
+
+export type QueryOp<Output> = AsyncOp<Output, DatabaseQueryOpFailure>;
+
+export type FlattenSuccessOps<T> = T extends Success<
+  infer S extends AsyncOp<unknown, unknown>
+>
+  ? S
+  : T;
+
+export type QueryError = {
+  type: "QUERY_ERROR";
+  error: string;
+};
+
+/**
+ * The stored database version is higher than the version requested.
+ */
+export type VersionHigherState = {
+  type: "DB_VERSION_HIGHER_THAN_REQUESTED";
+  message: string;
+};
+
+/**
+ * Database could not be opened for an unrecognized reason.
+ */
+export type UnexpectedErrorState = {
+  type: "UNKNOWN_ERROR";
+  message: string;
+};
+
+/**
+ * This happens if the database needs an upgrade due to version change, but there are connections open to it from other tabs.
+ */
+export type UpgradeBlockedState = {
+  type: "UPGRADE_BLOCKED";
+};
+
+/**
+ * The DB has been closed to allow for version change.
+ */
+export type ClosedForUpgradeState = {
+  type: "CLOSED_FOR_UPGRADE";
+};
+
+export type InaccessibleDatabaseError =
+  | UpgradeBlockedState
+  | ClosedForUpgradeState
+  | VersionHigherState
+  | UnexpectedErrorState;
+
+export type DatabaseOpenRequestOp<T extends AnyModernIDB = AnyModernIDB> =
+  AsyncOp<T, InaccessibleDatabaseError>;

package/lib/ModernIDB/bindings/utils.tsx

@@ -0,0 +1,32 @@
+import type { InaccessibleDatabaseError } from "./types.ts";
+
+export function toKnownError(error: unknown): InaccessibleDatabaseError {
+  if (error instanceof Error) {
+    switch (error.name) {
+      case "OpenRequestBlockedError": {
+        return {
+          type: "UPGRADE_BLOCKED",
+        };
+      }
+
+      case "VersionError": {
+        return {
+          type: "DB_VERSION_HIGHER_THAN_REQUESTED",
+          message: error.message,
+        };
+      }
+
+      default: {
+        return {
+          type: "UNKNOWN_ERROR",
+          message: error.message,
+        };
+      }
+    }
+  }
+
+  return {
+    type: "UNKNOWN_ERROR",
+    message: "A non-error object was thrown.",
+  };
+}

package/lib/ModernIDB/index.ts

@@ -0,0 +1,10 @@
+export * from "./bindings/index.ts";
+export * from "./Cursor.ts";
+export * from "./ModernIDB.ts";
+export * from "./ModernIDBError.ts";
+export * from "./ObjectStore.ts";
+export * from "./ObjectStoreIndex.ts";
+export * from "./Transaction.ts";
+export * from "./types.ts";
+export * from "./utils.ts";
+export * from "./VersionChangeManager.ts";

package/lib/ModernIDB/types.ts

@@ -0,0 +1,77 @@
+import { ModernIDB } from "./ModernIDB.ts";
+import { VersionChangeManager } from "./VersionChangeManager.ts";
+
+/**
+ * IDB supports "readonly", "readwrite", and "versionchange" transaction modes,
+ * but "versionchange" can only be initiated automatically during DB upgrade.
+ */
+export type TransactionMode = "readonly" | "readwrite";
+
+export type ModernIDBState = "open" | "opening" | "closed";
+
+export type ModernIDBSchema = {
+  [key: string]: unknown;
+};
+
+export type VersionChangeHandler<
+  Schema extends ModernIDBSchema,
+  IndexNames extends {
+    [K in keyof Schema]?: string;
+  },
+> = (props: {
+  event: IDBVersionChangeEvent;
+  manager: VersionChangeManager<Schema, IndexNames>;
+  db: ModernIDB<Schema, IndexNames>;
+}) => void;
+
+export type BlockingHandler<
+  Schema extends ModernIDBSchema,
+  IndexNames extends {
+    [K in keyof Schema]?: string;
+  },
+> = (props: {
+  event: IDBVersionChangeEvent;
+  db: ModernIDB<Schema, IndexNames>;
+}) => void;
+
+export type OpenRequestHandlers<
+  Schema extends ModernIDBSchema,
+  IndexNames extends {
+    [K in keyof Schema]?: string;
+  },
+> = {
+  /**
+   * If error is thrown inside the `onInit` handler, the version change
+   * transaction will be aborted.
+   */
+  onInit?: VersionChangeHandler<Schema, IndexNames>;
+
+  /**
+   * If error is thrown inside the `onUpgrade` handler, the version change
+   * transaction will be aborted.
+   */
+  onUpgrade?: VersionChangeHandler<Schema, IndexNames>;
+
+  /**
+   * If a new connection opens which requests a higher version number than
+   * is the current version number, a `versionchange` event will be dispatched
+   * on the IDBDatabase instance. This handler can specify desired behaviour.
+   * For example, you might want to close currently connected connections
+   * to allow the version change to proceed.
+   */
+  onBlocking?: BlockingHandler<Schema, IndexNames>;
+};
+
+type ValidKeyValue = string | number | Date;
+
+export type KeyPath<T> = T extends { [key: string]: unknown }
+  ? {
+      [K in keyof T]: K extends string
+        ? T[K] extends ValidKeyValue
+          ? `${K}`
+          : `${K}.${KeyPath<T[K]>}`
+        : never;
+    }[keyof T]
+  : never;
+
+export type AnyModernIDB = ModernIDB<any, any>;

package/lib/ModernIDB/utils.ts

@@ -0,0 +1,51 @@
+export function transactionToPromise(
+  transaction: IDBTransaction,
+): Promise<Event> {
+  return new Promise<Event>((resolve, reject) => {
+    transaction.addEventListener("complete", resolve, { once: true });
+    transaction.addEventListener("error", reject, { once: true });
+    transaction.addEventListener("abort", reject, { once: true });
+  });
+}
+
+export function requestToPromise<T>(request: IDBRequest<T>) {
+  return new Promise<T>((resolve, reject) => {
+    const success = () => resolve(request.result);
+    const error = () => reject(request.error);
+    request.addEventListener("success", success, { once: true });
+    request.addEventListener("error", error, { once: true });
+  });
+}
+
+export function openRequestToPromise(request: IDBOpenDBRequest) {
+  return new Promise<IDBDatabase>((resolve, reject) => {
+    const success = () => resolve(request.result);
+    const error = () => reject(request.error);
+    const blocked = () =>
+      reject(
+        new Error(
+          "Operation blocked. An existing database connection is preventing this action.",
+        ),
+      );
+
+    request.addEventListener("success", success, { once: true });
+    request.addEventListener("error", error, { once: true });
+    request.addEventListener("blocked", blocked, { once: true });
+  });
+}
+
+export async function* requestToAsyncGenerator(
+  request: IDBRequest<IDBCursorWithValue | null>,
+) {
+  let cursor = await requestToPromise(request);
+
+  while (cursor) {
+    yield cursor;
+
+    if (request.readyState !== "pending") {
+      cursor.continue();
+    }
+
+    cursor = await requestToPromise(request);
+  }
+}

package/lib/ReleaseInfo/index.tsx

@@ -0,0 +1,29 @@
+export function ReleaseInfo(props: {
+  branch?: string;
+  shortcode?: string;
+  backgroundColor?: string;
+}) {
+  if (!props.branch || !props.shortcode) {
+    return <>Release [local]</>;
+  }
+
+  return (
+    <>
+      {`Release `}
+      <code
+        style={{
+          fontSize: "0.875em",
+          backgroundColor: props.backgroundColor,
+          paddingInline: "0.25rem",
+          paddingBlock: "0.125rem",
+          borderRadius: "0.25rem",
+          fontFamily: "monospace",
+        }}
+      >
+        {props.shortcode}
+      </code>
+
+      {props.branch === "main" ? "" : ` (${props.branch})`}
+    </>
+  );
+}

package/lib/RulesetResolver.ts

@@ -0,0 +1,214 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { Failure, Pending, Success } from "./async-op.ts";
+import { isNullish } from "./typeguards.ts";
+
+type RulesetLike = { version: string };
+
+type GetRemoteRuleset<R extends RulesetLike, F> = (
+  version: string,
+) => Promise<Success<R> | Failure<F>>;
+
+type RulesetResolverProps<R extends RulesetLike, F> = {
+  /**
+   * The initial ruleset that will be available to all users immediately at
+   * app start.
+   */
+  initialRuleset: R;
+
+  /**
+   * A function that should return a Result with an instance of
+   * a Ruleset for the given game.
+   */
+  getRemoteRuleset: GetRemoteRuleset<R, F>;
+};
+
+/**
+ * Encapsulates ruleset caching and retrieval logic.
+ *
+ * Usually you want to instantiate this class and immediately pass it to
+ * {@link createRulesetResolverBindings} so that you can use it from within
+ * React components with proper re-renders.
+ *
+ * @example
+ * ```ts
+ * import { createRulesetResolverBindings, RulesetResolver } from "@indietabletop/appkit";
+ *
+ * // Instantiate a resolver and export it for any potential use
+ * export const resolver = new RulesetResolver({
+ *   initialRuleset: new Ruleset({ ... }),
+ *   async getRemoteRuleset(version) {
+ *     // Get ruleset from a remote location somehow
+ *     return new Ruleset({ ... });
+ *   },
+ * });
+ *
+ * // Generate resolver-bound hooks for use within React components
+ * export const { useResolveRuleset, useLatestRuleset } =
+ *   createRulesetResolverBindings(resolver);
+ * ```
+ */
+export class RulesetResolver<R extends RulesetLike, F> {
+  getRemoteRuleset: GetRemoteRuleset<R, F>;
+  rulesets: Map<string, Success<R> | Failure<F>>;
+
+  constructor(props: RulesetResolverProps<R, F>) {
+    this.getRemoteRuleset = props.getRemoteRuleset;
+    this.rulesets = new Map([
+      [props.initialRuleset.version, new Success(props.initialRuleset)],
+    ]);
+  }
+
+  get latest() {
+    const sortedRulesets = Array.from(this.rulesets.values())
+      .filter((result) => result.isSuccess)
+      .map((result) => result.value)
+      .sort((left, right) => left.version.localeCompare(right.version));
+
+    if (sortedRulesets.length === 0) {
+      throw new Error(
+        `Could not resolve latest ruleset. Ruleset resolver doesn't include any succesfully resolved ruleset versions.`,
+      );
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return sortedRulesets.at(-1)!;
+  }
+
+  requests = new Map<string, Promise<Success<R> | Failure<F>>>();
+
+  /**
+   * Resolves a ruleset version if it is currently in memory.
+   *
+   * Otherwise, initiates ruleset resolution from a remote source  in the
+   * background and returns `null`. If you want to know when the freshly
+   * requested ruleset will be resolved, you must use the {@link subscribe}
+   * method (possibly using a hook returned from {@link createRulesetResolverBindings}).
+   */
+  resolve(version: string) {
+    const ruleset = this.rulesets.get(version);
+    if (ruleset) {
+      return ruleset;
+    }
+
+    void this.resolveFromRemote(version);
+    return null;
+  }
+
+  /**
+   * Resolves a ruleset from a remote source, deduplicating requests to
+   * identical rulesets.
+   */
+  async resolveFromRemote(version: string) {
+    const ongoingRequest = this.requests.get(version);
+    if (ongoingRequest) {
+      return await ongoingRequest;
+    }
+
+    const remoteRulesetPromise = this.getRemoteRuleset(version);
+    this.requests.set(version, remoteRulesetPromise);
+
+    const newRuleset = await remoteRulesetPromise;
+    this.rulesets.set(version, newRuleset);
+    this.notify();
+
+    // Clear requests cache to allow for potential retries
+    this.requests.delete(version);
+
+    return newRuleset;
+  }
+
+  listeners = new Set<() => void>();
+
+  subscribe(callback: () => void) {
+    this.listeners.add(callback);
+  }
+
+  unsubscribe(callback: () => void) {
+    this.listeners.delete(callback);
+  }
+
+  notify() {
+    for (const notifyListener of this.listeners) {
+      notifyListener();
+    }
+  }
+}
+
+/**
+ * Given a RulesetResolver, creates bound React hooks that trigger re-renders
+ * when new rulesets are resolved by the resolver.
+ *
+ * Usually you will create these hooks in their own module and export them
+ * for further use.
+ *
+ * @example
+ * ```ts
+ * export const resolver = new RulesetResolver({ ... });
+ *
+ * export const { useResolveRuleset, useLatestRuleset } =
+ *   createRulesetResolverHooks(resolver);
+ * ```
+ */
+export function createRulesetResolverBindings<
+  Ruleset extends RulesetLike,
+  Failure,
+>(resolver: RulesetResolver<Ruleset, Failure>) {
+  // Pending state with stable identity — necessary so that
+  // useSyncExternalStore doesn't enter an infinite loop.
+  const pending = new Pending();
+
+  /**
+   * Returns a ruleset result compatible with the provided version.
+   *
+   * If a ruleset is not currently in memory, it will be requested in the
+   * background and the component using this hook will be re-rendered once
+   * the request is completed.
+   *
+   * Note that requests are deduplicated, so it is safe to use this hook
+   * in loops/lists where multiple components might request identical
+   * ruleset verions.
+   */
+  function useResolveRuleset(version: string | null | undefined) {
+    const subscribe = useCallback((callback: () => void) => {
+      resolver.subscribe(callback);
+
+      return () => {
+        resolver.unsubscribe(callback);
+      };
+    }, []);
+
+    const getSnapshot = useCallback(() => {
+      if (!isNullish(version)) {
+        return resolver.resolve(version) ?? pending;
+      }
+
+      return pending;
+    }, [version]);
+
+    return useSyncExternalStore(subscribe, getSnapshot);
+  }
+
+  /**
+   * Returns the latest ruleset available in memory.
+   */
+  function useLatestRuleset() {
+    const subscribe = useCallback((callback: () => void) => {
+      resolver.subscribe(callback);
+
+      return () => {
+        resolver.unsubscribe(callback);
+      };
+    }, []);
+
+    const getSnapshot = useCallback(() => {
+      return resolver.latest;
+    }, []);
+
+    return useSyncExternalStore(subscribe, getSnapshot);
+  }
+
+  return {
+    useLatestRuleset,
+    useResolveRuleset,
+  };
+}