@xylabs/indexed-db 4.4.28

package/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,69 @@
+[![logo][]](https://xylabs.com)
+
+# @xylabs/indexed-db
+
+[![npm-badge][]][npm-link]
+[![npm-downloads-badge][]][npm-link]
+[![jsdelivr-badge][]][jsdelivr-link]
+[![npm-license-badge][]](LICENSE)
+[![socket-badge][]][socket-link]
+
+> XY Labs Indexed DB Helpers
+
+## Table of Contents
+
+-   [Description](#description)
+-   [Install](#install)
+-   [Maintainers](#maintainers)
+-   [License](#license)
+-   [Credits](#credits)
+
+## Description
+
+Various Indexed DB Helper Functions
+
+## Install
+
+Using npm:
+
+```sh
+npm i --save @xylabs/indexed-db
+```
+
+Using yarn:
+
+```sh
+yarn add @xylabs/indexed-db
+```
+
+## Documentation
+[Developer Reference](https://xylabs.github.io/sdk-js)
+
+## Maintainers
+
+-   [Arie Trouw](https://github.com/arietrouw) ([arietrouw.com](https://arietrouw.com))
+-   [Joel Carter](https://github.com/JoelBCarter)
+-   [Matt Jones](https://github.com/jonesmac)
+-   [Jordan Trouw](https://github.com/jordantrouw)
+
+## License
+
+See the [LICENSE](LICENSE) file for license details
+
+## Credits
+
+[Made with 🔥and ❄️ by XY Labs](https://xylabs.com)
+
+[logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg
+
+[npm-badge]: https://img.shields.io/npm/v/@xylabs/indexed-db.svg
+[npm-link]: https://www.npmjs.com/package/@xylabs/indexed-db
+
+[npm-downloads-badge]: https://img.shields.io/npm/dw/@xylabs/indexed-db
+[npm-license-badge]: https://img.shields.io/npm/l/@xylabs/indexed-db
+
+[jsdelivr-badge]: https://data.jsdelivr.com/v1/package/npm/@xylabs/indexed-db/badge
+[jsdelivr-link]: https://www.jsdelivr.com/package/npm/@xylabs/indexed-db
+
+[socket-badge]: https://socket.dev/api/badge/npm/package/@xylabs/indexed-db
+[socket-link]: https://socket.dev/npm/package/@xylabs/indexed-db

package/dist/neutral/IndexDescription.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The index direction (1 for ascending, -1 for descending)
+ */
+export type IndexDirection = -1 | 1;
+/**
+ * Description of index(es) to be created on a store
+ */
+export type IndexDescription = {
+    /**
+     * The key(s) to index
+     */
+    key: Record<string, IndexDirection>;
+    /**
+     * Is the indexed value an array
+     */
+    multiEntry?: boolean;
+    /**
+     * The name of the index
+     */
+    name?: string;
+    /**
+     * If true, the index must enforce uniqueness on the key
+     */
+    unique?: boolean;
+};
+export declare const IndexSeparator = "-";
+/**
+ * Given an index description, this will build the index
+ * name in standard form
+ * @param index The index description
+ * @returns The index name in standard form
+ */
+export declare const buildStandardIndexName: (index: IndexDescription) => string;
+//# sourceMappingURL=IndexDescription.d.ts.map

package/dist/neutral/IndexDescription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexDescription.d.ts","sourceRoot":"","sources":["../../src/IndexDescription.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;AAEnC;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IACnC;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,UAAW,gBAAgB,WAK7D,CAAA"}

package/dist/neutral/ObjectStore.d.ts

@@ -0,0 +1,5 @@
+import type { EmptyObject } from '@xylabs/object';
+export interface ObjectStore<T extends EmptyObject = EmptyObject> {
+    [s: string]: T;
+}
+//# sourceMappingURL=ObjectStore.d.ts.map

package/dist/neutral/ObjectStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStore.d.ts","sourceRoot":"","sources":["../../src/ObjectStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IAC9D,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAA;CACf"}

package/dist/neutral/createStore.d.ts

@@ -0,0 +1,7 @@
+import type { Logger } from '@xylabs/logger';
+import type { EmptyObject } from '@xylabs/object';
+import type { IDBPDatabase, StoreNames } from 'idb';
+import { type IndexDescription } from './IndexDescription.ts';
+import type { ObjectStore } from './ObjectStore.ts';
+export declare function createStore<T extends EmptyObject = EmptyObject>(db: IDBPDatabase<ObjectStore<T>>, storeName: StoreNames<ObjectStore<T>>, indexes: IndexDescription[], logger?: Logger): void;
+//# sourceMappingURL=createStore.d.ts.map

package/dist/neutral/createStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStore.d.ts","sourceRoot":"","sources":["../../src/createStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EACV,YAAY,EAAc,UAAU,EACrC,MAAM,KAAK,CAAA;AAEZ,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC7D,EAAE,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAChC,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EACrC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,MAAM,CAAC,EAAE,MAAM,QAoBhB"}

package/dist/neutral/getExistingIndexes.d.ts

@@ -0,0 +1,6 @@
+import type { EmptyObject } from '@xylabs/object';
+import type { IDBPDatabase, StoreNames } from 'idb';
+import { type IndexDescription } from './IndexDescription.ts';
+import type { ObjectStore } from './ObjectStore.ts';
+export declare function getExistingIndexes<T extends EmptyObject = EmptyObject>(db: IDBPDatabase<ObjectStore<T>>, storeName: StoreNames<ObjectStore<T>>): Promise<IndexDescription[]>;
+//# sourceMappingURL=getExistingIndexes.d.ts.map

package/dist/neutral/getExistingIndexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getExistingIndexes.d.ts","sourceRoot":"","sources":["../../src/getExistingIndexes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AAEnD,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC1E,EAAE,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAChC,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GACpC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqB7B"}

package/dist/neutral/index.d.ts

@@ -0,0 +1,8 @@
+export * from './createStore.ts';
+export * from './getExistingIndexes.ts';
+export * from './IndexDescription.ts';
+export * from './ObjectStore.ts';
+export * from './withDb.ts';
+export * from './withReadOnlyStore.ts';
+export * from './withReadWriteStore.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/neutral/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA"}

package/dist/neutral/index.mjs

@@ -0,0 +1,96 @@
+// src/IndexDescription.ts
+var IndexSeparator = "-";
+var buildStandardIndexName = (index) => {
+  const { key, unique } = index;
+  const prefix = unique ? "UX" : "IX";
+  const indexKeys = Object.keys(key);
+  return `${prefix}_${indexKeys.join(IndexSeparator)}`;
+};
+
+// src/createStore.ts
+function createStore(db, storeName, indexes, logger) {
+  logger?.log(`Creating store ${storeName}`);
+  const store = db.createObjectStore(storeName, {
+    // If it isn't explicitly set, create a value by auto incrementing.
+    autoIncrement: true
+  });
+  store.name = storeName;
+  for (const {
+    key,
+    multiEntry,
+    unique
+  } of indexes) {
+    const indexKeys = Object.keys(key);
+    const keys = indexKeys.length === 1 ? indexKeys[0] : indexKeys;
+    const indexName = buildStandardIndexName({ key, unique });
+    console.log("createIndex", indexName, keys, { multiEntry, unique });
+    store.createIndex(indexName, keys, { multiEntry, unique });
+  }
+}
+
+// src/withReadOnlyStore.ts
+async function withReadOnlyStore(db, storeName, callback) {
+  const transaction = db.transaction(storeName, "readonly");
+  const store = transaction.objectStore(storeName);
+  try {
+    return await callback(store);
+  } finally {
+    await transaction.done;
+  }
+}
+
+// src/getExistingIndexes.ts
+async function getExistingIndexes(db, storeName) {
+  return await withReadOnlyStore(db, storeName, (store) => {
+    return [...store.indexNames].map((indexName) => {
+      const index = store.index(indexName);
+      const key = {};
+      if (Array.isArray(index.keyPath)) {
+        for (const keyPath of index.keyPath) {
+          key[keyPath] = 1;
+        }
+      } else {
+        key[index.keyPath] = 1;
+      }
+      const desc = {
+        name: indexName,
+        key,
+        unique: index.unique,
+        multiEntry: index.multiEntry
+      };
+      return desc;
+    });
+  });
+}
+
+// src/withDb.ts
+import { openDB } from "idb";
+async function withDb(dbName, callback) {
+  const db = await openDB(dbName);
+  try {
+    return await callback(db);
+  } finally {
+    db.close();
+  }
+}
+
+// src/withReadWriteStore.ts
+async function withReadWriteStore(db, storeName, callback) {
+  const transaction = db.transaction(storeName, "readwrite");
+  const store = transaction.objectStore(storeName);
+  try {
+    return await callback(store);
+  } finally {
+    await transaction.done;
+  }
+}
+export {
+  IndexSeparator,
+  buildStandardIndexName,
+  createStore,
+  getExistingIndexes,
+  withDb,
+  withReadOnlyStore,
+  withReadWriteStore
+};
+//# sourceMappingURL=index.mjs.map

package/dist/neutral/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/IndexDescription.ts","../../src/createStore.ts","../../src/withReadOnlyStore.ts","../../src/getExistingIndexes.ts","../../src/withDb.ts","../../src/withReadWriteStore.ts"],"sourcesContent":["/**\n * The index direction (1 for ascending, -1 for descending)\n */\nexport type IndexDirection = -1 | 1\n\n/**\n * Description of index(es) to be created on a store\n */\nexport type IndexDescription = {\n  /**\n   * The key(s) to index\n   */\n  key: Record<string, IndexDirection>\n  /**\n   * Is the indexed value an array\n   */\n  multiEntry?: boolean\n  /**\n   * The name of the index\n   */\n  name?: string\n  /**\n   * If true, the index must enforce uniqueness on the key\n   */\n  unique?: boolean\n}\n\nexport const IndexSeparator = '-'\n\n/**\n * Given an index description, this will build the index\n * name in standard form\n * @param index The index description\n * @returns The index name in standard form\n */\nexport const buildStandardIndexName = (index: IndexDescription) => {\n  const { key, unique } = index\n  const prefix = unique ? 'UX' : 'IX'\n  const indexKeys = Object.keys(key)\n  return `${prefix}_${indexKeys.join(IndexSeparator)}`\n}\n","import type { Logger } from '@xylabs/logger'\nimport type { EmptyObject } from '@xylabs/object'\nimport type {\n  IDBPDatabase, IndexNames, StoreNames,\n} from 'idb'\n\nimport {\n  buildStandardIndexName,\n  type IndexDescription,\n} from './IndexDescription.ts'\nimport type { ObjectStore } from './ObjectStore.ts'\n\nexport function createStore<T extends EmptyObject = EmptyObject>(\n  db: IDBPDatabase<ObjectStore<T>>,\n  storeName: StoreNames<ObjectStore<T>>,\n  indexes: IndexDescription[],\n  logger?: Logger,\n) {\n  logger?.log(`Creating store ${storeName}`)\n  // Create the store\n  const store = db.createObjectStore(storeName, {\n    // If it isn't explicitly set, create a value by auto incrementing.\n    autoIncrement: true,\n  })\n  // Name the store\n  store.name = storeName\n  // Create an index on the hash\n  for (const {\n    key, multiEntry, unique,\n  } of indexes) {\n    const indexKeys = Object.keys(key)\n    const keys = indexKeys.length === 1 ? indexKeys[0] : indexKeys\n    const indexName = buildStandardIndexName({ key, unique }) as IndexNames<ObjectStore<T>, StoreNames<ObjectStore<T>>>\n    console.log('createIndex', indexName, keys, { multiEntry, unique })\n    store.createIndex(indexName, keys, { multiEntry, unique })\n  }\n}\n","import type { EmptyObject } from '@xylabs/object'\nimport type {\n  IDBPDatabase, IDBPObjectStore, StoreNames,\n} from 'idb'\n\nimport type { ObjectStore } from './ObjectStore.ts'\n\nexport async function withReadOnlyStore<T extends EmptyObject = EmptyObject, R = T>(\n  db: IDBPDatabase<ObjectStore<T>>,\n  storeName: StoreNames<ObjectStore<T>>,\n  callback: (store: IDBPObjectStore<ObjectStore<T>, [StoreNames<ObjectStore<T>>], StoreNames<ObjectStore<T>>, string>) => Promise<R> | R,\n): Promise<R> {\n  const transaction = db.transaction(storeName, 'readonly')\n  const store = transaction.objectStore(storeName)\n  try {\n    return await callback(store)\n  } finally {\n    await transaction.done\n  }\n}\n","import type { EmptyObject } from '@xylabs/object'\nimport type { IDBPDatabase, StoreNames } from 'idb'\n\nimport {\n  type IndexDescription,\n  type IndexDirection,\n} from './IndexDescription.ts'\nimport type { ObjectStore } from './ObjectStore.ts'\nimport { withReadOnlyStore } from './withReadOnlyStore.ts'\n\nexport async function getExistingIndexes<T extends EmptyObject = EmptyObject>(\n  db: IDBPDatabase<ObjectStore<T>>,\n  storeName: StoreNames<ObjectStore<T>>,\n): Promise<IndexDescription[]> {\n  return await withReadOnlyStore(db, storeName, (store) => {\n    return [...store.indexNames].map((indexName) => {\n      const index = store.index(indexName)\n      const key: Record<string, IndexDirection> = {}\n      if (Array.isArray(index.keyPath)) {\n        for (const keyPath of index.keyPath) {\n          key[keyPath] = 1\n        }\n      } else {\n        key[index.keyPath] = 1\n      }\n      const desc: IndexDescription = {\n        name: indexName as string,\n        key,\n        unique: index.unique,\n        multiEntry: index.multiEntry,\n      }\n      return desc\n    })\n  })\n}\n","import type { EmptyObject } from '@xylabs/object'\nimport type { IDBPDatabase } from 'idb'\nimport { openDB } from 'idb'\n\nimport type { ObjectStore } from './ObjectStore.ts'\n\nexport async function withDb<T extends EmptyObject = EmptyObject>(dbName: string, callback: (db: IDBPDatabase<ObjectStore<T>>) => Promise<T> | T): Promise<T> {\n  const db = await openDB<ObjectStore<T>>(dbName)\n  try {\n    return await callback(db)\n  } finally {\n    db.close()\n  }\n}\n","import type { EmptyObject } from '@xylabs/object'\nimport type {\n  IDBPDatabase, IDBPObjectStore, StoreNames,\n} from 'idb'\n\nimport type { ObjectStore } from './ObjectStore.ts'\n\nexport async function withReadWriteStore<T extends EmptyObject = EmptyObject, R = T>(\n  db: IDBPDatabase<ObjectStore<T>>,\n  storeName: StoreNames<ObjectStore<T>>,\n  callback: (store: IDBPObjectStore<ObjectStore<T>, [StoreNames<ObjectStore<T>>], StoreNames<ObjectStore<T>>, string>) => Promise<R> | R,\n): Promise<R> {\n  const transaction = db.transaction(storeName, 'readwrite')\n  const store = transaction.objectStore(storeName)\n  try {\n    return await callback(store)\n  } finally {\n    await transaction.done\n  }\n}\n"],"mappings":";AA2BO,IAAM,iBAAiB;AAQvB,IAAM,yBAAyB,CAAC,UAA4B;AACjE,QAAM,EAAE,KAAK,OAAO,IAAI;AACxB,QAAM,SAAS,SAAS,OAAO;AAC/B,QAAM,YAAY,OAAO,KAAK,GAAG;AACjC,SAAO,GAAG,MAAM,IAAI,UAAU,KAAK,cAAc,CAAC;AACpD;;;AC5BO,SAAS,YACd,IACA,WACA,SACA,QACA;AACA,UAAQ,IAAI,kBAAkB,SAAS,EAAE;AAEzC,QAAM,QAAQ,GAAG,kBAAkB,WAAW;AAAA;AAAA,IAE5C,eAAe;AAAA,EACjB,CAAC;AAED,QAAM,OAAO;AAEb,aAAW;AAAA,IACT;AAAA,IAAK;AAAA,IAAY;AAAA,EACnB,KAAK,SAAS;AACZ,UAAM,YAAY,OAAO,KAAK,GAAG;AACjC,UAAM,OAAO,UAAU,WAAW,IAAI,UAAU,CAAC,IAAI;AACrD,UAAM,YAAY,uBAAuB,EAAE,KAAK,OAAO,CAAC;AACxD,YAAQ,IAAI,eAAe,WAAW,MAAM,EAAE,YAAY,OAAO,CAAC;AAClE,UAAM,YAAY,WAAW,MAAM,EAAE,YAAY,OAAO,CAAC;AAAA,EAC3D;AACF;;;AC7BA,eAAsB,kBACpB,IACA,WACA,UACY;AACZ,QAAM,cAAc,GAAG,YAAY,WAAW,UAAU;AACxD,QAAM,QAAQ,YAAY,YAAY,SAAS;AAC/C,MAAI;AACF,WAAO,MAAM,SAAS,KAAK;AAAA,EAC7B,UAAE;AACA,UAAM,YAAY;AAAA,EACpB;AACF;;;ACTA,eAAsB,mBACpB,IACA,WAC6B;AAC7B,SAAO,MAAM,kBAAkB,IAAI,WAAW,CAAC,UAAU;AACvD,WAAO,CAAC,GAAG,MAAM,UAAU,EAAE,IAAI,CAAC,cAAc;AAC9C,YAAM,QAAQ,MAAM,MAAM,SAAS;AACnC,YAAM,MAAsC,CAAC;AAC7C,UAAI,MAAM,QAAQ,MAAM,OAAO,GAAG;AAChC,mBAAW,WAAW,MAAM,SAAS;AACnC,cAAI,OAAO,IAAI;AAAA,QACjB;AAAA,MACF,OAAO;AACL,YAAI,MAAM,OAAO,IAAI;AAAA,MACvB;AACA,YAAM,OAAyB;AAAA,QAC7B,MAAM;AAAA,QACN;AAAA,QACA,QAAQ,MAAM;AAAA,QACd,YAAY,MAAM;AAAA,MACpB;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH,CAAC;AACH;;;AChCA,SAAS,cAAc;AAIvB,eAAsB,OAA4C,QAAgB,UAA4E;AAC5J,QAAM,KAAK,MAAM,OAAuB,MAAM;AAC9C,MAAI;AACF,WAAO,MAAM,SAAS,EAAE;AAAA,EAC1B,UAAE;AACA,OAAG,MAAM;AAAA,EACX;AACF;;;ACNA,eAAsB,mBACpB,IACA,WACA,UACY;AACZ,QAAM,cAAc,GAAG,YAAY,WAAW,WAAW;AACzD,QAAM,QAAQ,YAAY,YAAY,SAAS;AAC/C,MAAI;AACF,WAAO,MAAM,SAAS,KAAK;AAAA,EAC7B,UAAE;AACA,UAAM,YAAY;AAAA,EACpB;AACF;","names":[]}

package/dist/neutral/withDb.d.ts

@@ -0,0 +1,5 @@
+import type { EmptyObject } from '@xylabs/object';
+import type { IDBPDatabase } from 'idb';
+import type { ObjectStore } from './ObjectStore.ts';
+export declare function withDb<T extends EmptyObject = EmptyObject>(dbName: string, callback: (db: IDBPDatabase<ObjectStore<T>>) => Promise<T> | T): Promise<T>;
+//# sourceMappingURL=withDb.d.ts.map

package/dist/neutral/withDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withDb.d.ts","sourceRoot":"","sources":["../../src/withDb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,CAAA;AAGvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,wBAAsB,MAAM,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAO5J"}

package/dist/neutral/withReadOnlyStore.d.ts

@@ -0,0 +1,5 @@
+import type { EmptyObject } from '@xylabs/object';
+import type { IDBPDatabase, IDBPObjectStore, StoreNames } from 'idb';
+import type { ObjectStore } from './ObjectStore.ts';
+export declare function withReadOnlyStore<T extends EmptyObject = EmptyObject, R = T>(db: IDBPDatabase<ObjectStore<T>>, storeName: StoreNames<ObjectStore<T>>, callback: (store: IDBPObjectStore<ObjectStore<T>, [StoreNames<ObjectStore<T>>], StoreNames<ObjectStore<T>>, string>) => Promise<R> | R): Promise<R>;
+//# sourceMappingURL=withReadOnlyStore.d.ts.map

package/dist/neutral/withReadOnlyStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withReadOnlyStore.d.ts","sourceRoot":"","sources":["../../src/withReadOnlyStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EACV,YAAY,EAAE,eAAe,EAAE,UAAU,EAC1C,MAAM,KAAK,CAAA;AAEZ,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,GAAG,CAAC,EAChF,EAAE,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAChC,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EACrC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACrI,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/dist/neutral/withReadWriteStore.d.ts

@@ -0,0 +1,5 @@
+import type { EmptyObject } from '@xylabs/object';
+import type { IDBPDatabase, IDBPObjectStore, StoreNames } from 'idb';
+import type { ObjectStore } from './ObjectStore.ts';
+export declare function withReadWriteStore<T extends EmptyObject = EmptyObject, R = T>(db: IDBPDatabase<ObjectStore<T>>, storeName: StoreNames<ObjectStore<T>>, callback: (store: IDBPObjectStore<ObjectStore<T>, [StoreNames<ObjectStore<T>>], StoreNames<ObjectStore<T>>, string>) => Promise<R> | R): Promise<R>;
+//# sourceMappingURL=withReadWriteStore.d.ts.map

package/dist/neutral/withReadWriteStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withReadWriteStore.d.ts","sourceRoot":"","sources":["../../src/withReadWriteStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EACV,YAAY,EAAE,eAAe,EAAE,UAAU,EAC1C,MAAM,KAAK,CAAA;AAEZ,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,GAAG,CAAC,EACjF,EAAE,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAChC,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EACrC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACrI,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@xylabs/indexed-db",
+  "version": "4.4.28",
+  "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
+  "keywords": [
+    "hex",
+    "xylabs",
+    "utility",
+    "typescript",
+    "esm"
+  ],
+  "homepage": "https://xylabs.com",
+  "bugs": {
+    "url": "git+https://github.com/xylabs/sdk-js/issues",
+    "email": "support@xylabs.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xylabs/sdk-js.git"
+  },
+  "license": "LGPL-3.0-only",
+  "author": {
+    "name": "XY Labs Development Team",
+    "email": "support@xylabs.com",
+    "url": "https://xylabs.com"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/neutral/index.d.ts",
+      "default": "./dist/neutral/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "module": "./dist/neutral/index.mjs",
+  "types": "./dist/neutral/index.d.ts",
+  "workspaces": [
+    "packages/**/*"
+  ],
+  "dependencies": {
+    "@xylabs/logger": "^4.4.28",
+    "@xylabs/object": "^4.4.28",
+    "idb": "^8.0.1"
+  },
+  "devDependencies": {
+    "@xylabs/ts-scripts-yarn3": "^4.2.6",
+    "@xylabs/tsconfig": "^4.2.6",
+    "@xylabs/vitest-extended": "^4.4.28",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/IndexDescription.ts

@@ -0,0 +1,41 @@
+/**
+ * The index direction (1 for ascending, -1 for descending)
+ */
+export type IndexDirection = -1 | 1
+
+/**
+ * Description of index(es) to be created on a store
+ */
+export type IndexDescription = {
+  /**
+   * The key(s) to index
+   */
+  key: Record<string, IndexDirection>
+  /**
+   * Is the indexed value an array
+   */
+  multiEntry?: boolean
+  /**
+   * The name of the index
+   */
+  name?: string
+  /**
+   * If true, the index must enforce uniqueness on the key
+   */
+  unique?: boolean
+}
+
+export const IndexSeparator = '-'
+
+/**
+ * Given an index description, this will build the index
+ * name in standard form
+ * @param index The index description
+ * @returns The index name in standard form
+ */
+export const buildStandardIndexName = (index: IndexDescription) => {
+  const { key, unique } = index
+  const prefix = unique ? 'UX' : 'IX'
+  const indexKeys = Object.keys(key)
+  return `${prefix}_${indexKeys.join(IndexSeparator)}`
+}

package/src/ObjectStore.ts

@@ -0,0 +1,5 @@
+import type { EmptyObject } from '@xylabs/object'
+
+export interface ObjectStore<T extends EmptyObject = EmptyObject> {
+  [s: string]: T
+}

package/src/createStore.ts

@@ -0,0 +1,37 @@
+import type { Logger } from '@xylabs/logger'
+import type { EmptyObject } from '@xylabs/object'
+import type {
+  IDBPDatabase, IndexNames, StoreNames,
+} from 'idb'
+
+import {
+  buildStandardIndexName,
+  type IndexDescription,
+} from './IndexDescription.ts'
+import type { ObjectStore } from './ObjectStore.ts'
+
+export function createStore<T extends EmptyObject = EmptyObject>(
+  db: IDBPDatabase<ObjectStore<T>>,
+  storeName: StoreNames<ObjectStore<T>>,
+  indexes: IndexDescription[],
+  logger?: Logger,
+) {
+  logger?.log(`Creating store ${storeName}`)
+  // Create the store
+  const store = db.createObjectStore(storeName, {
+    // If it isn't explicitly set, create a value by auto incrementing.
+    autoIncrement: true,
+  })
+  // Name the store
+  store.name = storeName
+  // Create an index on the hash
+  for (const {
+    key, multiEntry, unique,
+  } of indexes) {
+    const indexKeys = Object.keys(key)
+    const keys = indexKeys.length === 1 ? indexKeys[0] : indexKeys
+    const indexName = buildStandardIndexName({ key, unique }) as IndexNames<ObjectStore<T>, StoreNames<ObjectStore<T>>>
+    console.log('createIndex', indexName, keys, { multiEntry, unique })
+    store.createIndex(indexName, keys, { multiEntry, unique })
+  }
+}

package/src/getExistingIndexes.ts

@@ -0,0 +1,35 @@
+import type { EmptyObject } from '@xylabs/object'
+import type { IDBPDatabase, StoreNames } from 'idb'
+
+import {
+  type IndexDescription,
+  type IndexDirection,
+} from './IndexDescription.ts'
+import type { ObjectStore } from './ObjectStore.ts'
+import { withReadOnlyStore } from './withReadOnlyStore.ts'
+
+export async function getExistingIndexes<T extends EmptyObject = EmptyObject>(
+  db: IDBPDatabase<ObjectStore<T>>,
+  storeName: StoreNames<ObjectStore<T>>,
+): Promise<IndexDescription[]> {
+  return await withReadOnlyStore(db, storeName, (store) => {
+    return [...store.indexNames].map((indexName) => {
+      const index = store.index(indexName)
+      const key: Record<string, IndexDirection> = {}
+      if (Array.isArray(index.keyPath)) {
+        for (const keyPath of index.keyPath) {
+          key[keyPath] = 1
+        }
+      } else {
+        key[index.keyPath] = 1
+      }
+      const desc: IndexDescription = {
+        name: indexName as string,
+        key,
+        unique: index.unique,
+        multiEntry: index.multiEntry,
+      }
+      return desc
+    })
+  })
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './createStore.ts'
+export * from './getExistingIndexes.ts'
+export * from './IndexDescription.ts'
+export * from './ObjectStore.ts'
+export * from './withDb.ts'
+export * from './withReadOnlyStore.ts'
+export * from './withReadWriteStore.ts'

package/src/withDb.ts

@@ -0,0 +1,14 @@
+import type { EmptyObject } from '@xylabs/object'
+import type { IDBPDatabase } from 'idb'
+import { openDB } from 'idb'
+
+import type { ObjectStore } from './ObjectStore.ts'
+
+export async function withDb<T extends EmptyObject = EmptyObject>(dbName: string, callback: (db: IDBPDatabase<ObjectStore<T>>) => Promise<T> | T): Promise<T> {
+  const db = await openDB<ObjectStore<T>>(dbName)
+  try {
+    return await callback(db)
+  } finally {
+    db.close()
+  }
+}

package/src/withReadOnlyStore.ts

@@ -0,0 +1,20 @@
+import type { EmptyObject } from '@xylabs/object'
+import type {
+  IDBPDatabase, IDBPObjectStore, StoreNames,
+} from 'idb'
+
+import type { ObjectStore } from './ObjectStore.ts'
+
+export async function withReadOnlyStore<T extends EmptyObject = EmptyObject, R = T>(
+  db: IDBPDatabase<ObjectStore<T>>,
+  storeName: StoreNames<ObjectStore<T>>,
+  callback: (store: IDBPObjectStore<ObjectStore<T>, [StoreNames<ObjectStore<T>>], StoreNames<ObjectStore<T>>, string>) => Promise<R> | R,
+): Promise<R> {
+  const transaction = db.transaction(storeName, 'readonly')
+  const store = transaction.objectStore(storeName)
+  try {
+    return await callback(store)
+  } finally {
+    await transaction.done
+  }
+}

package/src/withReadWriteStore.ts

@@ -0,0 +1,20 @@
+import type { EmptyObject } from '@xylabs/object'
+import type {
+  IDBPDatabase, IDBPObjectStore, StoreNames,
+} from 'idb'
+
+import type { ObjectStore } from './ObjectStore.ts'
+
+export async function withReadWriteStore<T extends EmptyObject = EmptyObject, R = T>(
+  db: IDBPDatabase<ObjectStore<T>>,
+  storeName: StoreNames<ObjectStore<T>>,
+  callback: (store: IDBPObjectStore<ObjectStore<T>, [StoreNames<ObjectStore<T>>], StoreNames<ObjectStore<T>>, string>) => Promise<R> | R,
+): Promise<R> {
+  const transaction = db.transaction(storeName, 'readwrite')
+  const store = transaction.objectStore(storeName)
+  try {
+    return await callback(store)
+  } finally {
+    await transaction.done
+  }
+}

package/xy.config.ts

@@ -0,0 +1,10 @@
+import type { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
+const config: XyTsupConfig = {
+  compile: {
+    browser: {},
+    neutral: { src: true },
+    node: {},
+  },
+}
+
+export default config