@indietabletop/appkit 3.5.0 → 3.6.0-0

package/lib/ModernIDB/ModernIDB.ts

@@ -0,0 +1,337 @@
+/* eslint-disable @typescript-eslint/prefer-promise-reject-errors */
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+
+import { ModernIDBError } from "./ModernIDBError.ts";
+import { ObjectStore } from "./ObjectStore.ts";
+import type {
+  BlockingHandler,
+  ModernIDBSchema,
+  ModernIDBState,
+  OpenRequestHandlers,
+  TransactionMode,
+  VersionChangeHandler,
+} from "./types.ts";
+import { openRequestToPromise, transactionToPromise } from "./utils.ts";
+import { VersionChangeManager } from "./VersionChangeManager.ts";
+
+export class TransactionEvent<StoreName extends string> extends CustomEvent<{
+  storeNames: StoreName[];
+}> {
+  constructor(type: TransactionMode, storeNames: StoreName[]) {
+    super(type, { detail: { storeNames } });
+  }
+}
+
+type TransactionOptions = IDBTransactionOptions & {
+  /**
+   * Do not emit events when this transaction completes.
+   */
+  noEmit?: boolean;
+};
+
+type DatabaseProps = {
+  name: string;
+  version: number;
+};
+
+export class ModernIDB<
+  Schema extends ModernIDBSchema,
+  IndexNames extends { [K in keyof Schema]?: string },
+> {
+  readonly name: string;
+  readonly version: number;
+
+  protected state: ModernIDBState = "closed";
+  protected idbDatabase: IDBDatabase | null = null;
+
+  private eventTarget: EventTarget;
+  private onBlocking?: BlockingHandler<Schema, IndexNames>;
+  private onUpgrade?: VersionChangeHandler<Schema, IndexNames>;
+  private onInit?: VersionChangeHandler<Schema, IndexNames>;
+
+  constructor(props: DatabaseProps & OpenRequestHandlers<Schema, IndexNames>) {
+    this.eventTarget = new EventTarget();
+    this.name = props.name;
+    this.version = props.version;
+
+    this.onInit = props.onInit;
+    this.onUpgrade = props.onUpgrade;
+    this.onBlocking = props.onBlocking;
+  }
+
+  public addEventListener(
+    type: TransactionMode,
+    callback: (event: TransactionEvent<string & keyof Schema>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void {
+    this.eventTarget.addEventListener(
+      type,
+
+      // The EventTarget should only have events dispatched by ModernIDB,
+      // meaning that it should be safe to assume that the event will be
+      // a TransactionEvent.
+      callback as EventListener,
+      options,
+    );
+  }
+
+  public removeEventListener(
+    type: TransactionMode,
+    callback: (event: TransactionEvent<string & keyof Schema>) => void,
+    options?: boolean | EventListenerOptions,
+  ): void {
+    this.eventTarget.removeEventListener(
+      type,
+
+      // The EventTarget should only have events dispatched by ModernIDB,
+      // meaning that it should be safe to assume that the event will be
+      // a TransactionEvent.
+      callback as EventListener,
+      options,
+    );
+  }
+
+  /**
+   * Opens a connection to IndexedDB.
+   *
+   * ModernIDB instance must be in a `closed` state, otherwise an
+   * `InvalidConnectionStateError` will be thrown.
+   *
+   * If the database needs to upgrade (i.e. supplied version is higher than
+   * the current version), but there are existing connections that don't
+   * close on `versionchange` event (the onBlocking handler), an
+   * `OpenRequestBlockedError` will be thrown.
+   *
+   * Additional browser-specific exceptions can also be thrown. Make
+   * sure to inspect any error's `name` property to differentiate
+   * between the various types of errors that could occur.
+   */
+  async open(handlers?: OpenRequestHandlers<Schema, IndexNames>) {
+    if (this.state !== "closed") {
+      throw new ModernIDBError(
+        "InvalidConnectionStateError",
+
+        `Cannot open connection to database '${this.name}'. Instance must ` +
+          `be in a 'closed' state in order to be opened, but current ` +
+          `state is '${this.state}'.`,
+      );
+    }
+
+    this.state = "opening";
+
+    // Override handlers supplied in the constructor
+    Object.assign(this, handlers);
+
+    const handleInit = this.onInit;
+    const handleBlocking = this.onBlocking;
+    const handleUpgrade = this.onUpgrade;
+
+    return new Promise<Event>((resolve, reject) => {
+      try {
+        const request = indexedDB.open(this.name, this.version);
+
+        if (handleUpgrade || handleInit) {
+          request.addEventListener(
+            "upgradeneeded",
+            (event) => {
+              const idbDatabase = request.result;
+              const idbTransaction = request.transaction!;
+
+              const manager = new VersionChangeManager<Schema, IndexNames>({
+                idbDatabase,
+                idbTransaction,
+                event,
+              });
+
+              try {
+                if (event.oldVersion === 0) {
+                  handleInit?.({ event, manager, db: this });
+                } else {
+                  handleUpgrade?.({ event, manager, db: this });
+                }
+              } catch (error) {
+                console.error(error);
+                idbTransaction.abort();
+              }
+            },
+            { once: true },
+          );
+        }
+
+        request.addEventListener(
+          "blocked",
+          () => {
+            this.state = "closed";
+            reject(
+              new ModernIDBError(
+                "OpenRequestBlockedError",
+
+                `ModernIDB connection could not be opened because there ` +
+                  `is an open connection preventing a 'versionchange' ` +
+                  `transaction from being created.`,
+              ),
+            );
+          },
+          { once: true },
+        );
+
+        request.addEventListener(
+          "success",
+          (event) => {
+            if (this.state === "opening") {
+              const idb = request.result;
+              this.idbDatabase = idb;
+
+              if (handleBlocking) {
+                this.idbDatabase.addEventListener("versionchange", (event) => {
+                  handleBlocking({ event, db: this });
+                });
+              }
+
+              this.state = "open";
+              resolve(event);
+            }
+          },
+          { once: true },
+        );
+
+        request.addEventListener(
+          "error",
+          () => {
+            this.state = "closed";
+            reject(request.error);
+          },
+          { once: true },
+        );
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  close() {
+    this.state = "closed";
+
+    this.idbDatabase?.close();
+    this.idbDatabase = null;
+  }
+
+  isOpen(): this is this & { idbDatabase: IDBDatabase } {
+    return !!this.idbDatabase;
+  }
+
+  private assertOpen(
+    hint: string,
+  ): asserts this is this & { idbDatabase: IDBDatabase } {
+    if (!this.isOpen()) {
+      throw new ModernIDBError("InvalidConnectionStateError", hint);
+    }
+  }
+
+  transaction<StoreName extends string & keyof Schema>(
+    name: StoreName,
+    mode?: TransactionMode,
+    options?: TransactionOptions,
+  ): [
+    ObjectStore<
+      Schema[StoreName],
+      IndexNames[StoreName] extends string ? IndexNames[StoreName] : never
+    >,
+    Promise<Event>,
+  ];
+
+  transaction<StoreNamesArray extends readonly (string & keyof Schema)[] | []>(
+    names: StoreNamesArray,
+    mode?: TransactionMode,
+    options?: TransactionOptions,
+  ): [
+    {
+      -readonly [Index in keyof StoreNamesArray]: ObjectStore<
+        Schema[StoreNamesArray[Index]],
+        IndexNames[StoreNamesArray[Index]] extends string
+          ? IndexNames[StoreNamesArray[Index]]
+          : never
+      >;
+    },
+    Promise<Event>,
+  ];
+
+  transaction(
+    nameOrNames: string | string[],
+    mode?: TransactionMode,
+    options?: TransactionOptions,
+  ) {
+    const transactionMode = mode ?? "readonly";
+
+    this.assertOpen(
+      `The "transaction" method can only be called on an instance that is ` +
+        `in the "open" state, but current state is: "${this.state}".`,
+    );
+
+    const transaction = this.idbDatabase.transaction(
+      nameOrNames,
+      transactionMode,
+      options,
+    );
+    const complete = transactionToPromise(transaction);
+
+    if (!options?.noEmit) {
+      // Generally, it is best practice to always attach then/catch handlers to
+      // promises. However, in this case, these should be attached in user-code,
+      // as it doesn't make sense to try to handle errors from here.
+      //
+      // eslint-disable-next-line @typescript-eslint/no-floating-promises
+      complete.then((event) => {
+        this.eventTarget.dispatchEvent(
+          new TransactionEvent(
+            transactionMode,
+            Array.isArray(nameOrNames) ? nameOrNames : [nameOrNames],
+          ),
+        );
+        return event;
+      });
+    }
+
+    if (Array.isArray(nameOrNames)) {
+      const objectStores = nameOrNames.map(
+        (name) => new ObjectStore(transaction.objectStore(name)),
+      );
+      return [objectStores, complete];
+    }
+
+    return [new ObjectStore(transaction.objectStore(nameOrNames)), complete];
+  }
+
+  async deleteFromStore(
+    storeName: string & keyof Schema,
+    query: IDBValidKey | IDBKeyRange,
+    options?: IDBTransactionOptions,
+  ) {
+    const [store, done] = this.transaction(storeName, "readwrite", options);
+    await Promise.all([store.delete(query), done]);
+  }
+
+  async getFromStore<StoreName extends string & keyof Schema>(
+    storeName: StoreName,
+    query: IDBValidKey | IDBKeyRange,
+    options?: IDBTransactionOptions,
+  ) {
+    const [store, done] = this.transaction(storeName, "readonly", options);
+    const [data] = await Promise.all([store.get(query), done]);
+    return data;
+  }
+
+  async putToStore<StoreName extends string & keyof Schema>(
+    storeName: StoreName,
+    value: Schema[StoreName],
+    key?: IDBValidKey,
+  ) {
+    const [store, done] = this.transaction(storeName, "readwrite");
+    const [itemKey] = await Promise.all([store.put(value, key), done]);
+    return itemKey;
+  }
+}
+
+export function deleteDatabase(name: string) {
+  return openRequestToPromise(indexedDB.deleteDatabase(name));
+}

package/lib/ModernIDB/ModernIDBError.ts

@@ -0,0 +1,9 @@
+export class ModernIDBError extends Error {
+  constructor(
+    name: "OpenRequestBlockedError" | "InvalidConnectionStateError",
+    message: string,
+  ) {
+    super(message);
+    this.name = name;
+  }
+}

package/lib/ModernIDB/ObjectStore.ts

@@ -0,0 +1,195 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+
+import { Cursor, CursorWithValue } from "./Cursor.ts";
+import { ObjectStoreIndex } from "./ObjectStoreIndex.ts";
+import type { KeyPath } from "./types.ts";
+import { requestToAsyncGenerator, requestToPromise } from "./utils.ts";
+
+export class ObjectStore<Item, IndexName extends string> {
+  readonly idbObjectStore = IDBObjectStore["prototype"];
+
+  constructor(objectStore: IDBObjectStore) {
+    this.idbObjectStore = objectStore;
+  }
+
+  /**
+   * Adds or updates a record in store with the given value and key.
+   *
+   * If the store uses in-line keys and key is specified a "DataError" DOMException will be thrown.
+   *
+   * If put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a "ConstraintError" DOMException.
+   *
+   * If successful, request's result will be the record's key.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/add)
+   */
+  add(value: Item, key?: IDBValidKey): Promise<IDBValidKey> {
+    return requestToPromise(this.idbObjectStore.add(value, key));
+  }
+  /**
+   * Deletes all records in store.
+   *
+   * If successful, request's result will be undefined.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/clear)
+   */
+  clear(): Promise<undefined> {
+    return requestToPromise(this.idbObjectStore.clear());
+  }
+  /**
+   * Retrieves the number of records matching the given key or key range in query.
+   *
+   * If successful, request's result will be the count.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/count)
+   */
+  count(query?: IDBValidKey | IDBKeyRange): Promise<number> {
+    return requestToPromise(this.idbObjectStore.count(query));
+  }
+  /**
+   * Deletes records in store with the given key or in the given key range in query.
+   *
+   * If successful, request's result will be undefined.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/delete)
+   */
+  delete(query: IDBValidKey | IDBKeyRange): Promise<undefined> {
+    return requestToPromise(this.idbObjectStore.delete(query));
+  }
+  /**
+   * Retrieves the value of the first record matching the given key or key range in query.
+   *
+   * If successful, request's result will be the value, or undefined if there was no matching record.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/get)
+   */
+  get(query: IDBValidKey | IDBKeyRange): Promise<Item | undefined> {
+    return requestToPromise(this.idbObjectStore.get(query));
+  }
+  /**
+   * Retrieves the values of the records matching the given key or key range in query (up to count if given).
+   *
+   * If successful, request's result will be an Array of the values.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/getAll)
+   */
+  getAll(
+    query?: IDBValidKey | IDBKeyRange | null,
+    count?: number,
+  ): Promise<Item[]> {
+    return requestToPromise(this.idbObjectStore.getAll(query, count));
+  }
+  /**
+   * Retrieves the keys of records matching the given key or key range in query (up to count if given).
+   *
+   * If successful, request's result will be an Array of the keys.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/getAllKeys)
+   */
+  getAllKeys(
+    query?: IDBValidKey | IDBKeyRange | null,
+    count?: number,
+  ): Promise<IDBValidKey[]> {
+    return requestToPromise(this.idbObjectStore.getAllKeys(query, count));
+  }
+  /**
+   * Retrieves the key of the first record matching the given key or key range in query.
+   *
+   * If successful, request's result will be the key, or undefined if there was no matching record.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/getKey)
+   */
+  getKey(query: IDBValidKey | IDBKeyRange): Promise<IDBValidKey | undefined> {
+    return requestToPromise(this.idbObjectStore.getKey(query));
+  }
+
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/index) */
+  index(name: IndexName): ObjectStoreIndex<Item> {
+    const idbIndex = this.idbObjectStore.index(name);
+    return new ObjectStoreIndex(idbIndex);
+  }
+
+  /**
+   * Opens a cursor over the records matching query, ordered by direction. If query is null, all records in store are matched.
+   */
+  async *openCursor(
+    query?: IDBValidKey | IDBKeyRange | null,
+    direction?: IDBCursorDirection,
+  ): AsyncGenerator<CursorWithValue<Item>, void, undefined> {
+    const idbCursorGenerator = requestToAsyncGenerator(
+      this.idbObjectStore.openCursor(query, direction),
+    );
+
+    for await (const idbCursor of idbCursorGenerator) {
+      yield new CursorWithValue<Item>(idbCursor);
+    }
+  }
+
+  /**
+   * Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in store are matched.
+   */
+  async *openKeyCursor(
+    query?: IDBValidKey | IDBKeyRange | null,
+    direction?: IDBCursorDirection,
+  ): AsyncGenerator<Cursor, void, undefined> {
+    const idbCursorGenerator = requestToAsyncGenerator(
+      this.idbObjectStore.openCursor(query, direction),
+    );
+
+    for await (const idbCursor of idbCursorGenerator) {
+      yield new Cursor(idbCursor);
+    }
+  }
+
+  /**
+   * Adds or updates a record in store with the given value and key.
+   *
+   * If the store uses in-line keys and key is specified a "DataError" DOMException will be thrown.
+   *
+   * If put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a "ConstraintError" DOMException.
+   *
+   * If successful, request's result will be the record's key.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/put)
+   */
+  put(value: Item, key?: IDBValidKey): Promise<IDBValidKey> {
+    return requestToPromise(this.idbObjectStore.put(value, key));
+  }
+}
+
+export class VersionChangeObjectStore<
+  Item,
+  IndexName extends string,
+> extends ObjectStore<Item, IndexName> {
+  /**
+   * Creates a new index in store with the given name, keyPath and options and returns a new IDBIndex. If the keyPath and options define constraints that cannot be satisfied with the data already in store the upgrade transaction will abort with a "ConstraintError" DOMException.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/createIndex)
+   */
+  createIndex(
+    name: IndexName,
+    keyPath: KeyPath<Item> | KeyPath<Item>[],
+    options?: IDBIndexParameters,
+  ): ObjectStoreIndex<Item> {
+    const idbIndex = this.idbObjectStore.createIndex(name, keyPath, options);
+    return new ObjectStoreIndex(idbIndex);
+  }
+
+  /**
+   * Deletes the index in store with the given name.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/deleteIndex)
+   */
+  deleteIndex(name: IndexName): void {
+    this.idbObjectStore.deleteIndex(name);
+  }
+
+  renameIndex(currentName: string, newName: IndexName) {
+    const index = this.idbObjectStore.index(currentName);
+    this.idbObjectStore.createIndex(newName, index.keyPath, {
+      multiEntry: index.multiEntry,
+      unique: index.unique,
+    });
+    this.idbObjectStore.deleteIndex(currentName);
+  }
+}

package/lib/ModernIDB/ObjectStoreIndex.ts

@@ -0,0 +1,102 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+
+import { IndexCursor, IndexCursorWithValue } from "./Cursor.ts";
+import { requestToAsyncGenerator, requestToPromise } from "./utils.ts";
+
+export class ObjectStoreIndex<Item> {
+  readonly idbIndex = IDBIndex["prototype"];
+
+  constructor(idbIndex: IDBIndex) {
+    this.idbIndex = idbIndex;
+  }
+
+  /**
+   * Retrieves the number of records matching the given key or key range in query.
+   *
+   * If successful, request's result will be the count.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/count)
+   */
+  count(query?: IDBValidKey | IDBKeyRange): Promise<number> {
+    return requestToPromise(this.idbIndex.count(query));
+  }
+
+  /**
+   * Retrieves the value of the first record matching the given key or key range in query.
+   *
+   * If successful, request's result will be the value, or undefined if there was no matching record.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/get)
+   */
+  get(query: IDBValidKey | IDBKeyRange): Promise<Item | undefined> {
+    return requestToPromise(this.idbIndex.get(query));
+  }
+  /**
+   * Retrieves the values of the records matching the given key or key range in query (up to count if given).
+   *
+   * If successful, request's result will be an Array of the values.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/getAll)
+   */
+  getAll(
+    query?: IDBValidKey | IDBKeyRange | null,
+    count?: number,
+  ): Promise<Item[]> {
+    return requestToPromise(this.idbIndex.getAll(query, count));
+  }
+  /**
+   * Retrieves the keys of records matching the given key or key range in query (up to count if given).
+   *
+   * If successful, request's result will be an Array of the keys.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/getAllKeys)
+   */
+  getAllKeys(
+    query?: IDBValidKey | IDBKeyRange | null,
+    count?: number,
+  ): Promise<IDBValidKey[]> {
+    return requestToPromise(this.idbIndex.getAllKeys(query, count));
+  }
+  /**
+   * Retrieves the key of the first record matching the given key or key range in query.
+   *
+   * If successful, request's result will be the key, or undefined if there was no matching record.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/IDBObjectStore/getKey)
+   */
+  getKey(query: IDBValidKey | IDBKeyRange): Promise<IDBValidKey | undefined> {
+    return requestToPromise(this.idbIndex.getKey(query));
+  }
+
+  /**
+   * Opens a cursor over the records matching query, ordered by direction. If query is null, all records in store are matched.
+   */
+  async *openCursor(
+    query?: IDBValidKey | IDBKeyRange | null,
+    direction?: IDBCursorDirection,
+  ): AsyncGenerator<IndexCursorWithValue<Item>, void, undefined> {
+    const idbCursorGenerator = requestToAsyncGenerator(
+      this.idbIndex.openCursor(query, direction),
+    );
+
+    for await (const idbCursor of idbCursorGenerator) {
+      yield new IndexCursorWithValue<Item>(idbCursor);
+    }
+  }
+
+  /**
+   * Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in store are matched.
+   */
+  async *openKeyCursor(
+    query?: IDBValidKey | IDBKeyRange | null,
+    direction?: IDBCursorDirection,
+  ): AsyncGenerator<IndexCursor, void, undefined> {
+    const idbCursorGenerator = requestToAsyncGenerator(
+      this.idbIndex.openCursor(query, direction),
+    );
+
+    for await (const idbCursor of idbCursorGenerator) {
+      yield new IndexCursor(idbCursor);
+    }
+  }
+}

package/lib/ModernIDB/README.md

@@ -0,0 +1,9 @@
+# Modern IndexedDB
+
+## Todo
+
+Include properties for unusual objects in Kaypath type. Eg. Array.length, etc...
+
+## Implementation Notes
+
+In several places, it could feel like subclassing should have been used in certain cases: ObjectStore could extend IDBObjectStore, ModernIDB could extend EventTarget, etc... However, this could not be done without violating the [Liskov substitution principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle). ModernIDB methods usually return Promises, which are not compatible with IDBRequests. Similarly, the addEventListener/removeEventListener of ModernIDB always dispatch CustomEvents, whereas the base addEventListener/removeEventListener of EventTarget must be able to handle any Event.

package/lib/ModernIDB/Transaction.ts

@@ -0,0 +1,40 @@
+import { ObjectStore, VersionChangeObjectStore } from "./ObjectStore.ts";
+import type { ModernIDBSchema } from "./types.ts";
+
+export class Transaction<
+  Schema extends ModernIDBSchema,
+  IndexNames extends {
+    [K in keyof Schema]?: string;
+  },
+> {
+  idbTransaction: IDBTransaction;
+
+  constructor(props: { transaction: IDBTransaction }) {
+    this.idbTransaction = props.transaction;
+  }
+
+  objectStore<StoreName extends string & keyof Schema>(
+    name: StoreName,
+  ): ObjectStore<
+    Schema[StoreName],
+    IndexNames[StoreName] extends string ? IndexNames[StoreName] : never
+  > {
+    return new ObjectStore(this.idbTransaction.objectStore(name));
+  }
+}
+
+export class VersionChangeTransaction<
+  Schema extends ModernIDBSchema,
+  IndexNames extends {
+    [K in keyof Schema]?: string;
+  },
+> extends Transaction<Schema, IndexNames> {
+  override objectStore<StoreName extends string & keyof Schema>(
+    name: StoreName,
+  ): VersionChangeObjectStore<
+    Schema[StoreName],
+    IndexNames[StoreName] extends string ? IndexNames[StoreName] : never
+  > {
+    return new VersionChangeObjectStore(this.idbTransaction.objectStore(name));
+  }
+}