@xylabs/indexed-db 7.0.8 → 8.0.0

package/README.md

@@ -1,866 +1,3 @@
-[![logo][]](https://xylabs.com)
-
 # @xylabs/indexed-db
 
-[![npm][npm-badge]][npm-link]
-[![license][license-badge]][license-link]
-
-> Base functionality used throughout XY Labs TypeScript/JavaScript libraries
-
-## Install
-
-Using npm:
-
-```sh
-npm install {{name}}
-```
-
-Using yarn:
-
-```sh
-yarn add {{name}}
-```
-
-Using pnpm:
-
-```sh
-pnpm add {{name}}
-```
-
-Using bun:
-
-```sh
-bun add {{name}}
-```
-
-
-## License
-
-See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
-
-## Reference
-
-### packages
-
-  ### indexed-db
-
-    ### .temp-typedoc
-
-      ### classes
-
-        ### <a id="IndexedDbKeyValueStore"></a>IndexedDbKeyValueStore
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-An IndexedDB key/value store.
-
-## Type Parameters
-
-### T
-
-`T` *extends* `DBSchema`
-
-### S
-
-`S` *extends* `StoreNames`\<`T`\>
-
-## Implements
-
-- `KeyValueStore`\<`StoreValue`\<`T`, `S`\>, `StoreKey`\<`T`, `S`\>\>
-
-## Constructors
-
-### Constructor
-
-```ts
-new IndexedDbKeyValueStore<T, S>(dbName, storeName): IndexedDbKeyValueStore<T, S>;
-```
-
-### Parameters
-
-#### dbName
-
-`string`
-
-#### storeName
-
-`S`
-
-### Returns
-
-`IndexedDbKeyValueStore`\<`T`, `S`\>
-
-## Properties
-
-### dbName
-
-```ts
-readonly dbName: string;
-```
-
-The name of the IndexedDB database.
-
-***
-
-### storeName
-
-```ts
-readonly storeName: S;
-```
-
-The name of the object store within the database.
-
-## Methods
-
-### clear()?
-
-```ts
-optional clear(): Promise<void>;
-```
-
-Removes all entries from the store.
-
-### Returns
-
-`Promise`\<`void`\>
-
-### Implementation of
-
-```ts
-KeyValueStore.clear
-```
-
-***
-
-### delete()
-
-```ts
-delete(key): Promise<void>;
-```
-
-Deletes the entry with the given key.
-
-### Parameters
-
-#### key
-
-`StoreKey`\<`T`, `S`\>
-
-The key of the entry to delete
-
-### Returns
-
-`Promise`\<`void`\>
-
-### Implementation of
-
-```ts
-KeyValueStore.delete
-```
-
-***
-
-### get()
-
-```ts
-get(key): Promise<StoreValue<T, S> | undefined>;
-```
-
-Retrieves the value associated with the given key.
-
-### Parameters
-
-#### key
-
-`StoreKey`\<`T`, `S`\>
-
-The key to look up
-
-### Returns
-
-`Promise`\<`StoreValue`\<`T`, `S`\> \| `undefined`\>
-
-The value, or undefined if not found
-
-### Implementation of
-
-```ts
-KeyValueStore.get
-```
-
-***
-
-### keys()?
-
-```ts
-optional keys(): Promise<StoreKey<T, S>[]>;
-```
-
-Returns all keys in the store.
-
-### Returns
-
-`Promise`\<`StoreKey`\<`T`, `S`\>[]\>
-
-### Implementation of
-
-```ts
-KeyValueStore.keys
-```
-
-***
-
-### set()
-
-```ts
-set(key, value): Promise<void>;
-```
-
-Sets a value for the given key, creating or updating the entry.
-
-### Parameters
-
-#### key
-
-`StoreKey`\<`T`, `S`\>
-
-The key to set
-
-#### value
-
-`StoreValue`\<`T`, `S`\>
-
-The value to store
-
-### Returns
-
-`Promise`\<`void`\>
-
-### Implementation of
-
-```ts
-KeyValueStore.set
-```
-
-***
-
-### withDb()
-
-```ts
-withDb<R>(callback): Promise<R>;
-```
-
-Opens the underlying IndexedDB database and passes it to the callback.
-
-### Type Parameters
-
-#### R
-
-`R` = `StoreValue`\<`T`, `S`\>
-
-### Parameters
-
-#### callback
-
-(`db`) => `R` \| `Promise`\<`R`\>
-
-Function to execute with the database
-
-### Returns
-
-`Promise`\<`R`\>
-
-The result of the callback
-
-      ### functions
-
-        ### <a id="buildStandardIndexName"></a>buildStandardIndexName
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function buildStandardIndexName(index): string;
-```
-
-Given an index description, this will build the index
-name in standard form
-
-## Parameters
-
-### index
-
-[`IndexDescription`](#../interfaces/IndexDescription)
-
-The index description
-
-## Returns
-
-`string`
-
-The index name in standard form
-
-        ### <a id="checkDbNeedsUpgrade"></a>checkDbNeedsUpgrade
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function checkDbNeedsUpgrade(
-   dbName, 
-   stores, 
-logger?): Promise<number>;
-```
-
-Checks whether any store in the database needs an upgrade and returns the appropriate version number.
-
-## Parameters
-
-### dbName
-
-`string`
-
-The name of the database to check
-
-### stores
-
-`Record`\<`string`, [`IndexDescription`][#../interfaces/IndexDescription]()\>
-
-Map of store names to their expected index descriptions
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-## Returns
-
-`Promise`\<`number`\>
-
-The version to open (current version + 1 if upgrade needed, otherwise current version)
-
-        ### <a id="createStoreDuringUpgrade"></a>createStoreDuringUpgrade
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function createStoreDuringUpgrade<DBTypes>(
-   db, 
-   storeName, 
-   indexes, 
-   logger?): void;
-```
-
-Creates an object store with the specified indexes during a version upgrade transaction.
-
-## Type Parameters
-
-### DBTypes
-
-`DBTypes` *extends* `unknown` = `unknown`
-
-## Parameters
-
-### db
-
-`IDBPDatabase`\<`DBTypes`\>
-
-The IndexedDB database instance (during upgrade)
-
-### storeName
-
-`StoreNames`\<`DBTypes`\>
-
-The name of the store to create
-
-### indexes
-
-[`IndexDescription`][#../interfaces/IndexDescription]()
-
-The index descriptions to create on the store
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-## Returns
-
-`void`
-
-        ### <a id="getExistingIndexes"></a>getExistingIndexes
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function getExistingIndexes<T>(
-   db, 
-   storeName, 
-logger?): Promise<IndexDescription[] | null>;
-```
-
-Retrieves the existing index descriptions for a store. Accepts either a database instance or a database name.
-
-## Type Parameters
-
-### T
-
-`T` *extends* `object` = `object`
-
-## Parameters
-
-### db
-
-  \| `string`
-  \| `IDBPDatabase`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The IndexedDB database instance or database name
-
-### storeName
-
-`StoreNames`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The name of the store to inspect
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-## Returns
-
-`Promise`\<[`IndexDescription`][#../interfaces/IndexDescription]() \| `null`\>
-
-An array of index descriptions, or null if the store does not exist
-
-        ### <a id="withDb"></a>withDb
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function withDb<DBTypes, R>(
-   dbName, 
-   callback, 
-   expectedIndexes?, 
-   logger?, 
-lock?): Promise<R>;
-```
-
-Opens an IndexedDB database, automatically upgrading if needed, and passes it to the callback.
-Uses a mutex to serialize access to the same database by default.
-
-## Type Parameters
-
-### DBTypes
-
-`DBTypes` *extends* `unknown` = `unknown`
-
-### R
-
-`R` = `object`
-
-## Parameters
-
-### dbName
-
-`string`
-
-The name of the database to open
-
-### callback
-
-(`db`) => `R` \| `Promise`\<`R`\>
-
-Function to execute with the opened database
-
-### expectedIndexes?
-
-`Record`\<`string`, [`IndexDescription`][#../interfaces/IndexDescription]()\>
-
-Optional map of store names to their expected indexes (triggers upgrade check)
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-### lock?
-
-`boolean` = `true`
-
-Whether to use a mutex to serialize access (defaults to true)
-
-## Returns
-
-`Promise`\<`R`\>
-
-The result of the callback
-
-        ### <a id="withDbByVersion"></a>withDbByVersion
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function withDbByVersion<DBTypes, R>(
-   dbName, 
-   callback, 
-   version?, 
-   expectedIndexes?, 
-   logger?, 
-lock?): Promise<R>;
-```
-
-Opens an IndexedDB database at a specific version, handling upgrade events, and passes it to the callback.
-The database is automatically closed after the callback completes.
-
-## Type Parameters
-
-### DBTypes
-
-`DBTypes` *extends* `unknown` = `unknown`
-
-### R
-
-`R` = `object`
-
-## Parameters
-
-### dbName
-
-`string`
-
-The name of the database to open
-
-### callback
-
-(`db`) => `R` \| `Promise`\<`R`\>
-
-Function to execute with the opened database
-
-### version?
-
-`number`
-
-Optional specific version to open (undefined for latest)
-
-### expectedIndexes?
-
-`Record`\<`string`, [`IndexDescription`][#../interfaces/IndexDescription]()\>
-
-Optional map of store names to indexes to create during upgrade
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-### lock?
-
-`boolean` = `true`
-
-Whether to use a mutex to serialize access (defaults to true)
-
-## Returns
-
-`Promise`\<`R`\>
-
-The result of the callback
-
-        ### <a id="withReadOnlyStore"></a>withReadOnlyStore
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function withReadOnlyStore<T, R>(
-   db, 
-   storeName, 
-   callback, 
-logger?): Promise<R>;
-```
-
-Opens a read-only transaction on the specified store and passes it to the callback.
-
-## Type Parameters
-
-### T
-
-`T` *extends* `object` = `object`
-
-### R
-
-`R` = `T`
-
-## Parameters
-
-### db
-
-`IDBPDatabase`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The IndexedDB database instance
-
-### storeName
-
-`StoreNames`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The name of the object store to open
-
-### callback
-
-(`store`) => `R` \| `Promise`\<`R`\>
-
-Function to execute with the read-only store
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-## Returns
-
-`Promise`\<`R`\>
-
-The result of the callback
-
-        ### <a id="withReadWriteStore"></a>withReadWriteStore
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function withReadWriteStore<T, R>(
-   db, 
-   storeName, 
-   callback, 
-logger?): Promise<R>;
-```
-
-Opens a read-write transaction on the specified store and passes it to the callback.
-
-## Type Parameters
-
-### T
-
-`T` *extends* `object` = `object`
-
-### R
-
-`R` = `T`
-
-## Parameters
-
-### db
-
-`IDBPDatabase`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The IndexedDB database instance
-
-### storeName
-
-`StoreNames`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The name of the object store to open
-
-### callback
-
-(`store`) => `R` \| `Promise`\<`R`\>
-
-Function to execute with the read-write store
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-## Returns
-
-`Promise`\<`R`\>
-
-The result of the callback
-
-        ### <a id="withStore"></a>withStore
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-function withStore<T, R, M>(
-   db, 
-   storeName, 
-   callback, 
-   mode, 
-logger?): Promise<R>;
-```
-
-Opens a transaction on the specified store with the given mode and passes the store to the callback.
-If the store does not exist, the callback receives null.
-
-## Type Parameters
-
-### T
-
-`T` *extends* `object` = `object`
-
-### R
-
-`R` = `T`
-
-### M
-
-`M` *extends* `"readonly"` \| `"readwrite"` = `"readonly"`
-
-## Parameters
-
-### db
-
-`IDBPDatabase`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The IndexedDB database instance
-
-### storeName
-
-`StoreNames`\<[`ObjectStore`](#../type-aliases/ObjectStore)\<`T`\>\>
-
-The name of the object store to open
-
-### callback
-
-(`store`) => `R` \| `Promise`\<`R`\>
-
-Function to execute with the store (or null if it doesn't exist)
-
-### mode
-
-`M`
-
-The transaction mode ('readonly' or 'readwrite')
-
-### logger?
-
-`Logger`
-
-Optional logger for diagnostics
-
-## Returns
-
-`Promise`\<`R`\>
-
-The result of the callback
-
-      ### interfaces
-
-        ### <a id="IndexDescription"></a>IndexDescription
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-Description of index(es) to be created on a store
-
-## Properties
-
-### key
-
-```ts
-key: Record<string, IndexDirection>;
-```
-
-The key(s) to index
-
-***
-
-### multiEntry?
-
-```ts
-optional multiEntry?: boolean;
-```
-
-Is the indexed value an array
-
-***
-
-### unique?
-
-```ts
-optional unique?: boolean;
-```
-
-If true, the index must enforce uniqueness on the key
-
-      ### type-aliases
-
-        ### <a id="IndexDirection"></a>IndexDirection
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-type IndexDirection = -1 | 1;
-```
-
-The index direction (1 for ascending, -1 for descending)
-
-        ### <a id="ObjectStore"></a>ObjectStore
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-type ObjectStore<T> = Record<string, T>;
-```
-
-Generic IndexedDB schema type that maps store names to their value types.
-
-## Type Parameters
-
-### T
-
-`T` *extends* `EmptyObject` = `EmptyObject`
-
-      ### variables
-
-        ### <a id="IndexSeparator"></a>IndexSeparator
-
-[**@xylabs/indexed-db**](#../README)
-
-***
-
-```ts
-const IndexSeparator: "-" = '-';
-```
-
-Separator used between key names when building standard index names.
-
-## Credits
-
-[Made with 🔥 and ❄️ by XY Labs](https://xylabs.com)
-
-[npm-badge]: https://img.shields.io/npm/v/@xylabs/indexed-db.svg
-[npm-link]: https://www.npmjs.com/package/@xylabs/indexed-db
-[license-badge]: https://img.shields.io/npm/l/@xylabs/indexed-db.svg
-[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE
-[logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg
+DEPRECATED — use `@ariestools/indexed-db` instead.