jg-storage 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 1.0.0
+
+The first release of `jg-storage`, which replaces `browser-keyval-stores` 1.1.1. Records written by `browser-keyval-stores` read back unchanged.
+
+### Added
+
+- `createLocalStore`, `createSessionStore`, `createMemoryStore`, and `createIndexedDbStore`, which replace the store classes.
+- The `fallback: 'memory'` and `parse` options.
+- `ERRORS`, the codes of every error the package throws, with the new `STORE_UNAVAILABLE` code.
+
+### Changed
+
+- Web storage stores accept any value JSON can represent, primitives included.
+- A store whose mechanism is unavailable keeps records in memory only with `fallback: 'memory'`. Without it, `set` and `del` throw `STORE_UNAVAILABLE`.
+- Web storage is read from `globalThis` on a store's first call, never from `window`.
+- `IRecordID` is renamed to `IRecordId`, and the store interfaces to `ISyncStore` and `IAsyncStore`.
+- Errors are `Exception`s from `jg-exception`.
+
+### Removed
+
+- The `LocalStorageStore`, `SessionStorageStore`, and `IndexedDBStore` classes.
+- The `INVALID_JSON_DATA` code.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesus Graterol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# jg-storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed key-value stores over localStorage, sessionStorage, IndexedDB, and memory, for browsers and workers.
+
+## Install
+
+```bash
+npm install jg-storage
+```
+
+## Usage
+
+Keep settings in localStorage, with a root record and records by ID:
+
+```ts
+import { createLocalStore } from 'jg-storage';
+
+const settings = createLocalStore<{ theme: 'light' | 'dark' }>('settings');
+settings.set(undefined, { theme: 'dark' }); // stored under the key 'settings'
+settings.get(); // { theme: 'dark' }
+settings.set('draft', { theme: 'light' }); // stored under the key 'settings_draft'
+settings.del('draft');
+```
+
+Keep records in IndexedDB, from a page or a service worker:
+
+```ts
+import { createIndexedDbStore } from 'jg-storage';
+
+const devices = createIndexedDbStore<{ token: string }>('devices');
+await devices.set('phone', { token: 'abc' });
+await devices.get('phone'); // { token: 'abc' }
+```
+
+Validate what you read, and fall back to memory where storage is blocked:
+
+```ts
+import { createSessionStore, ERRORS } from 'jg-storage';
+import { hasErrorCode } from 'jg-exception';
+import { z } from 'zod';
+
+const Step = z.number().int().min(1);
+const wizard = createSessionStore('wizard-step', {
+  fallback: 'memory', // without it, set and del throw STORE_UNAVAILABLE
+  parse: (value) => Step.parse(value), // runs on every stored value get reads
+});
+wizard.set(undefined, 2);
+wizard.get(); // 2
+
+try {
+  createSessionStore('other').set(undefined, 1);
+} catch (error) {
+  if (hasErrorCode(error, ERRORS.STORE_UNAVAILABLE)) {
+    // sessionStorage is unavailable in this context
+  }
+}
+```
+
+Every store probes its mechanism on its first call, never when it's created, so creating stores at module scope is safe during server-side rendering.
+
+## Coming from `browser-keyval-stores`
+
+| `browser-keyval-stores`                            | `jg-storage`                                                                    |
+| -------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `new LocalStorageStore<T>(id)`                     | `createLocalStore<T>(id, options?)`                                             |
+| `new SessionStorageStore<T>(id)`                   | `createSessionStore<T>(id, options?)`                                           |
+| `new IndexedDBStore<T>(id)`                        | `createIndexedDbStore<T>(id, options?)`                                         |
+| the internal temp-memory store                     | `createMemoryStore<T>(id, options?)`                                            |
+| `ILocalStorageStore<T>`, `ISessionStorageStore<T>` | `ISyncStore<T>`                                                                 |
+| `IIndexedDBStore<T>`                               | `IAsyncStore<T>`                                                                |
+| `IRecordID`                                        | `IRecordId`                                                                     |
+| the silent memory fallback                         | `{ fallback: 'memory' }`; without it, `set` and `del` throw `STORE_UNAVAILABLE` |
+| the codes, not exported                            | `ERRORS`                                                                        |
+
+`IStoreMechanism` and the `get`, `set`, and `del` methods keep their names and argument order.
+
+- Stored data is compatible: the keys, the compatibility probe's record, idb-keyval's default `keyval-store` database, JSON values in web storage, and structured-clone values in IndexedDB are all the same, so records written by `browser-keyval-stores` read back unchanged.
+- `set` on a web storage store accepts any value JSON can represent, primitives included. It used to accept only objects and arrays and throw `INVALID_JSON_DATA`, which is gone. A value JSON can't represent, such as `undefined` or a `bigint`, throws `FAILED_TO_STRINGIFY_JSON`.
+- When a mechanism is unavailable, a store without `fallback: 'memory'` returns `undefined` from `get` and throws `STORE_UNAVAILABLE` from `set` and `del`, instead of silently keeping records in memory.
+- The new `parse` option runs on every stored value `get` reads, and its errors propagate.
+- Nothing reads `window`: web storage is read from `globalThis` on the first call, and IndexedDB keeps using `globalThis.indexedDB`, so the IndexedDB store also works in workers.
+- Errors are `Exception`s from `jg-exception`.
+
+## Documentation
+
+The full API reference is at https://jg-packages.jesusgraterol.dev/packages/jg-storage/.
+
+## License
+
+[MIT](https://github.com/jesusgraterol/jg-packages/blob/main/packages/jg-storage/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { IAsyncStore, IRecordId, IStoreMechanism, IStoreOptions, ISyncStore, } from './shared/index.js';
+export { ERRORS } from './shared/index.js';
+export { createMemoryStore } from './memory-store/index.js';
+export { createLocalStore, createSessionStore } from './web-storage-store/index.js';
+export { createIndexedDbStore } from './indexed-db-store/index.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// error codes
+export { ERRORS } from './shared/index.js';
+// memory stores
+export { createMemoryStore } from './memory-store/index.js';
+// web storage stores
+export { createLocalStore, createSessionStore } from './web-storage-store/index.js';
+// IndexedDB stores
+export { createIndexedDbStore } from './indexed-db-store/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,cAAc;AACd,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,gBAAgB;AAChB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,qBAAqB;AACrB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEpF,mBAAmB;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC","sourcesContent":["// types\nexport type {\n  IAsyncStore,\n  IRecordId,\n  IStoreMechanism,\n  IStoreOptions,\n  ISyncStore,\n} from './shared/index.js';\n\n// error codes\nexport { ERRORS } from './shared/index.js';\n\n// memory stores\nexport { createMemoryStore } from './memory-store/index.js';\n\n// web storage stores\nexport { createLocalStore, createSessionStore } from './web-storage-store/index.js';\n\n// IndexedDB stores\nexport { createIndexedDbStore } from './indexed-db-store/index.js';\n"]}

package/dist/indexed-db-store/index.d.ts

@@ -0,0 +1 @@
+export { createIndexedDbStore } from './indexed-db-store.js';

package/dist/indexed-db-store/index.js

@@ -0,0 +1,3 @@
+// IndexedDB stores
+export { createIndexedDbStore } from './indexed-db-store.js';
+//# sourceMappingURL=index.js.map

package/dist/indexed-db-store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/indexed-db-store/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["// IndexedDB stores\nexport { createIndexedDbStore } from './indexed-db-store.js';\n"]}

package/dist/indexed-db-store/indexed-db-store.d.ts

@@ -0,0 +1,22 @@
+import { type IAsyncStore, type IStoreOptions } from '../shared/index.js';
+/**
+ * Creates a store over IndexedDB, which works in pages and workers alike. Records live in
+ * idb-keyval's default database, `keyval-store`, under the same keys browser-keyval-stores used,
+ * so their records read back unchanged. Values are stored with the structured clone algorithm,
+ * so dates, maps, and binary data keep their types. IndexedDB is read and probed on the first
+ * call, never when the store is created.
+ * @param id The identifier every record key starts with.
+ * @param options fallback: 'memory' keeps records in memory when IndexedDB is unavailable, and
+ * parse runs on every stored value get reads.
+ * @returns The store.
+ * @example
+ * const devices = createIndexedDbStore<{ token: string }>('devices');
+ * await devices.set('phone', { token: 'abc' }); // stored under the key 'devices_phone'
+ * await devices.get('phone'); // { token: 'abc' }
+ * await devices.del('phone');
+ * @throws
+ * - STORE_UNAVAILABLE: set or del ran while IndexedDB is unavailable, without a fallback.
+ *
+ * Errors from IndexedDB itself, such as a value it can't clone, propagate.
+ */
+export declare const createIndexedDbStore: <T>(id: string, options?: IStoreOptions<T>) => IAsyncStore<T>;

package/dist/indexed-db-store/indexed-db-store.js

@@ -0,0 +1,95 @@
+import { del, get, set } from 'idb-keyval';
+import { createMemoryStore } from '../memory-store/index.js';
+import { STORAGE_TEST_DATA, buildDataKey, buildUnavailableException, parseValue, } from '../shared/index.js';
+// IndexedDB, read from globalThis so the store also works in workers. Some environments lack it,
+// so it's optional here
+const indexedDbGlobals = globalThis;
+/**
+ * Probes whether IndexedDB accepts writes, by writing and deleting a record in idb-keyval's
+ * default database.
+ * @returns Whether IndexedDB is available.
+ */
+const probeIndexedDb = async () => {
+    try {
+        if (!indexedDbGlobals.indexedDB) {
+            return false;
+        }
+        await set(STORAGE_TEST_DATA.key, STORAGE_TEST_DATA.value);
+        await del(STORAGE_TEST_DATA.key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Creates a store over IndexedDB, which works in pages and workers alike. Records live in
+ * idb-keyval's default database, `keyval-store`, under the same keys browser-keyval-stores used,
+ * so their records read back unchanged. Values are stored with the structured clone algorithm,
+ * so dates, maps, and binary data keep their types. IndexedDB is read and probed on the first
+ * call, never when the store is created.
+ * @param id The identifier every record key starts with.
+ * @param options fallback: 'memory' keeps records in memory when IndexedDB is unavailable, and
+ * parse runs on every stored value get reads.
+ * @returns The store.
+ * @example
+ * const devices = createIndexedDbStore<{ token: string }>('devices');
+ * await devices.set('phone', { token: 'abc' }); // stored under the key 'devices_phone'
+ * await devices.get('phone'); // { token: 'abc' }
+ * await devices.del('phone');
+ * @throws
+ * - STORE_UNAVAILABLE: set or del ran while IndexedDB is unavailable, without a fallback.
+ *
+ * Errors from IndexedDB itself, such as a value it can't clone, propagate.
+ */
+export const createIndexedDbStore = (id, options = {}) => {
+    let compatibility;
+    let memory;
+    // the probe runs once, even when several calls start before it settles
+    const isCompatible = () => {
+        compatibility ??= probeIndexedDb();
+        return compatibility;
+    };
+    // the memory store an unavailable IndexedDB falls back to, when the options ask for one
+    const getMemory = () => {
+        if (options.fallback === 'memory') {
+            memory ??= createMemoryStore(id, options);
+        }
+        return memory;
+    };
+    return {
+        id,
+        mechanism: 'indexedDB',
+        isCompatible,
+        get: async (recordId) => {
+            if (!(await isCompatible())) {
+                return getMemory()?.get(recordId);
+            }
+            const value = await get(buildDataKey(id, recordId));
+            return value === undefined ? undefined : parseValue(value, options);
+        },
+        set: async (recordId, value) => {
+            if (await isCompatible()) {
+                await set(buildDataKey(id, recordId), value);
+                return;
+            }
+            const fallback = getMemory();
+            if (fallback === undefined) {
+                throw buildUnavailableException(id, 'indexedDB');
+            }
+            fallback.set(recordId, value);
+        },
+        del: async (recordId) => {
+            if (await isCompatible()) {
+                await del(buildDataKey(id, recordId));
+                return;
+            }
+            const fallback = getMemory();
+            if (fallback === undefined) {
+                throw buildUnavailableException(id, 'indexedDB');
+            }
+            fallback.del(recordId);
+        },
+    };
+};
+//# sourceMappingURL=indexed-db-store.js.map

package/dist/indexed-db-store/indexed-db-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexed-db-store.js","sourceRoot":"","sources":["../../src/indexed-db-store/indexed-db-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { del, get, set } from 'idb-keyval';\n\nimport { createMemoryStore } from '../memory-store/index.js';\nimport {\n  STORAGE_TEST_DATA,\n  buildDataKey,\n  buildUnavailableException,\n  parseValue,\n  type IAsyncStore,\n  type IRecordId,\n  type IStoreOptions,\n  type ISyncStore,\n} from '../shared/index.js';\n\n// IndexedDB, read from globalThis so the store also works in workers. Some environments lack it,\n// so it's optional here\nconst indexedDbGlobals: { indexedDB?: IDBFactory } = globalThis;\n\n/**\n * Probes whether IndexedDB accepts writes, by writing and deleting a record in idb-keyval's\n * default database.\n * @returns Whether IndexedDB is available.\n */\nconst probeIndexedDb = async (): Promise<boolean> => {\n  try {\n    if (!indexedDbGlobals.indexedDB) {\n      return false;\n    }\n    await set(STORAGE_TEST_DATA.key, STORAGE_TEST_DATA.value);\n    await del(STORAGE_TEST_DATA.key);\n    return true;\n  } catch {\n    return false;\n  }\n};\n\n/**\n * Creates a store over IndexedDB, which works in pages and workers alike. Records live in\n * idb-keyval's default database, `keyval-store`, under the same keys browser-keyval-stores used,\n * so their records read back unchanged. Values are stored with the structured clone algorithm,\n * so dates, maps, and binary data keep their types. IndexedDB is read and probed on the first\n * call, never when the store is created.\n * @param id The identifier every record key starts with.\n * @param options fallback: 'memory' keeps records in memory when IndexedDB is unavailable, and\n * parse runs on every stored value get reads.\n * @returns The store.\n * @example\n * const devices = createIndexedDbStore<{ token: string }>('devices');\n * await devices.set('phone', { token: 'abc' }); // stored under the key 'devices_phone'\n * await devices.get('phone'); // { token: 'abc' }\n * await devices.del('phone');\n * @throws\n * - STORE_UNAVAILABLE: set or del ran while IndexedDB is unavailable, without a fallback.\n *\n * Errors from IndexedDB itself, such as a value it can't clone, propagate.\n */\nexport const createIndexedDbStore = <T>(\n  id: string,\n  options: IStoreOptions<T> = {},\n): IAsyncStore<T> => {\n  let compatibility: Promise<boolean> | undefined;\n  let memory: ISyncStore<T> | undefined;\n\n  // the probe runs once, even when several calls start before it settles\n  const isCompatible = (): Promise<boolean> => {\n    compatibility ??= probeIndexedDb();\n    return compatibility;\n  };\n\n  // the memory store an unavailable IndexedDB falls back to, when the options ask for one\n  const getMemory = (): ISyncStore<T> | undefined => {\n    if (options.fallback === 'memory') {\n      memory ??= createMemoryStore(id, options);\n    }\n    return memory;\n  };\n\n  return {\n    id,\n    mechanism: 'indexedDB',\n    isCompatible,\n    get: async (recordId?: IRecordId) => {\n      if (!(await isCompatible())) {\n        return getMemory()?.get(recordId);\n      }\n      const value: unknown = await get(buildDataKey(id, recordId));\n      return value === undefined ? undefined : parseValue(value, options);\n    },\n    set: async (recordId: IRecordId, value: T) => {\n      if (await isCompatible()) {\n        await set(buildDataKey(id, recordId), value);\n        return;\n      }\n      const fallback = getMemory();\n      if (fallback === undefined) {\n        throw buildUnavailableException(id, 'indexedDB');\n      }\n      fallback.set(recordId, value);\n    },\n    del: async (recordId?: IRecordId) => {\n      if (await isCompatible()) {\n        await del(buildDataKey(id, recordId));\n        return;\n      }\n      const fallback = getMemory();\n      if (fallback === undefined) {\n        throw buildUnavailableException(id, 'indexedDB');\n      }\n      fallback.del(recordId);\n    },\n  };\n};\n"]}

package/dist/memory-store/index.d.ts

@@ -0,0 +1 @@
+export { createMemoryStore } from './memory-store.js';

package/dist/memory-store/index.js

@@ -0,0 +1,3 @@
+// memory stores
+export { createMemoryStore } from './memory-store.js';
+//# sourceMappingURL=index.js.map

package/dist/memory-store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-store/index.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC","sourcesContent":["// memory stores\nexport { createMemoryStore } from './memory-store.js';\n"]}

package/dist/memory-store/memory-store.d.ts

@@ -0,0 +1,16 @@
+import { type IStoreOptions, type ISyncStore } from '../shared/index.js';
+/**
+ * Creates a store that keeps its records in memory for as long as the store exists. Values are
+ * kept as they are, without serializing them, and the store is always available.
+ * @param id The identifier every record key starts with.
+ * @param options parse runs on every stored value get reads. fallback has no effect, because
+ * memory is always available.
+ * @returns The store.
+ * @example
+ * const drafts = createMemoryStore<{ text: string }>('drafts');
+ * drafts.set('post-1', { text: 'Hello' });
+ * drafts.get('post-1'); // { text: 'Hello' }
+ * drafts.del('post-1');
+ * drafts.get('post-1'); // undefined
+ */
+export declare const createMemoryStore: <T>(id: string, options?: IStoreOptions<T>) => ISyncStore<T>;

package/dist/memory-store/memory-store.js

@@ -0,0 +1,34 @@
+import { buildDataKey, parseValue, } from '../shared/index.js';
+/**
+ * Creates a store that keeps its records in memory for as long as the store exists. Values are
+ * kept as they are, without serializing them, and the store is always available.
+ * @param id The identifier every record key starts with.
+ * @param options parse runs on every stored value get reads. fallback has no effect, because
+ * memory is always available.
+ * @returns The store.
+ * @example
+ * const drafts = createMemoryStore<{ text: string }>('drafts');
+ * drafts.set('post-1', { text: 'Hello' });
+ * drafts.get('post-1'); // { text: 'Hello' }
+ * drafts.del('post-1');
+ * drafts.get('post-1'); // undefined
+ */
+export const createMemoryStore = (id, options = {}) => {
+    const records = new Map();
+    return {
+        id,
+        mechanism: 'tempMemory',
+        isCompatible: () => true,
+        get: (recordId) => {
+            const value = records.get(buildDataKey(id, recordId));
+            return value === undefined ? undefined : parseValue(value, options);
+        },
+        set: (recordId, value) => {
+            records.set(buildDataKey(id, recordId), value);
+        },
+        del: (recordId) => {
+            records.delete(buildDataKey(id, recordId));
+        },
+    };
+};
+//# sourceMappingURL=memory-store.js.map

package/dist/memory-store/memory-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.js","sourceRoot":"","sources":["../../src/memory-store/memory-store.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,UAAU,GAIX,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAI,EAAU,EAAE,UAA4B,EAAE,EAAiB,EAAE;IAChG,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;IACrC,OAAO;QACL,EAAE;QACF,SAAS,EAAE,YAAY;QACvB,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI;QACxB,GAAG,EAAE,CAAC,QAAoB,EAAE,EAAE;YAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;YACtD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACtE,CAAC;QACD,GAAG,EAAE,CAAC,QAAmB,EAAE,KAAQ,EAAE,EAAE;YACrC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;QACD,GAAG,EAAE,CAAC,QAAoB,EAAE,EAAE;YAC5B,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import {\n  buildDataKey,\n  parseValue,\n  type IRecordId,\n  type IStoreOptions,\n  type ISyncStore,\n} from '../shared/index.js';\n\n/**\n * Creates a store that keeps its records in memory for as long as the store exists. Values are\n * kept as they are, without serializing them, and the store is always available.\n * @param id The identifier every record key starts with.\n * @param options parse runs on every stored value get reads. fallback has no effect, because\n * memory is always available.\n * @returns The store.\n * @example\n * const drafts = createMemoryStore<{ text: string }>('drafts');\n * drafts.set('post-1', { text: 'Hello' });\n * drafts.get('post-1'); // { text: 'Hello' }\n * drafts.del('post-1');\n * drafts.get('post-1'); // undefined\n */\nexport const createMemoryStore = <T>(id: string, options: IStoreOptions<T> = {}): ISyncStore<T> => {\n  const records = new Map<string, T>();\n  return {\n    id,\n    mechanism: 'tempMemory',\n    isCompatible: () => true,\n    get: (recordId?: IRecordId) => {\n      const value = records.get(buildDataKey(id, recordId));\n      return value === undefined ? undefined : parseValue(value, options);\n    },\n    set: (recordId: IRecordId, value: T) => {\n      records.set(buildDataKey(id, recordId), value);\n    },\n    del: (recordId?: IRecordId) => {\n      records.delete(buildDataKey(id, recordId));\n    },\n  };\n};\n"]}

package/dist/shared/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const STORAGE_TEST_DATA: {
+    readonly key: "SOME_KEY_2d22df80-fc4b-498a-a4a7-734daa71c8dd";
+    readonly value: "Hello world!";
+};

package/dist/shared/constants.js

@@ -0,0 +1,7 @@
+// the record written and removed to probe whether a mechanism accepts writes. Its key and value
+// match browser-keyval-stores', so both packages probe the same record
+export const STORAGE_TEST_DATA = {
+    key: 'SOME_KEY_2d22df80-fc4b-498a-a4a7-734daa71c8dd',
+    value: 'Hello world!',
+};
+//# sourceMappingURL=constants.js.map

package/dist/shared/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,uEAAuE;AACvE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE,+CAA+C;IACpD,KAAK,EAAE,cAAc;CACb,CAAC","sourcesContent":["// the record written and removed to probe whether a mechanism accepts writes. Its key and value\n// match browser-keyval-stores', so both packages probe the same record\nexport const STORAGE_TEST_DATA = {\n  key: 'SOME_KEY_2d22df80-fc4b-498a-a4a7-734daa71c8dd',\n  value: 'Hello world!',\n} as const;\n"]}

package/dist/shared/errors.d.ts

@@ -0,0 +1,5 @@
+export declare const ERRORS: {
+    readonly FAILED_TO_STRINGIFY_JSON: "FAILED_TO_STRINGIFY_JSON";
+    readonly FAILED_TO_PARSE_JSON: "FAILED_TO_PARSE_JSON";
+    readonly STORE_UNAVAILABLE: "STORE_UNAVAILABLE";
+};

package/dist/shared/errors.js

@@ -0,0 +1,7 @@
+// the codes for every error thrown by the package
+export const ERRORS = {
+    FAILED_TO_STRINGIFY_JSON: 'FAILED_TO_STRINGIFY_JSON',
+    FAILED_TO_PARSE_JSON: 'FAILED_TO_PARSE_JSON',
+    STORE_UNAVAILABLE: 'STORE_UNAVAILABLE',
+};
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,wBAAwB,EAAE,0BAA0B;IACpD,oBAAoB,EAAE,sBAAsB;IAC5C,iBAAiB,EAAE,mBAAmB;CAC9B,CAAC","sourcesContent":["// the codes for every error thrown by the package\nexport const ERRORS = {\n  FAILED_TO_STRINGIFY_JSON: 'FAILED_TO_STRINGIFY_JSON',\n  FAILED_TO_PARSE_JSON: 'FAILED_TO_PARSE_JSON',\n  STORE_UNAVAILABLE: 'STORE_UNAVAILABLE',\n} as const;\n"]}

package/dist/shared/index.d.ts

@@ -0,0 +1,4 @@
+export { STORAGE_TEST_DATA } from './constants.js';
+export { ERRORS } from './errors.js';
+export type { IAsyncStore, IRecordId, IStoreMechanism, IStoreOptions, ISyncStore, } from './types.js';
+export { buildDataKey, buildUnavailableException, parseJSON, parseValue, stringifyJSON, } from './utilities.js';

package/dist/shared/index.js

@@ -0,0 +1,7 @@
+// constants
+export { STORAGE_TEST_DATA } from './constants.js';
+// errors
+export { ERRORS } from './errors.js';
+// utilities
+export { buildDataKey, buildUnavailableException, parseJSON, parseValue, stringifyJSON, } from './utilities.js';
+//# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,SAAS;AACT,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAWrC,YAAY;AACZ,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,gBAAgB,CAAC","sourcesContent":["// constants\nexport { STORAGE_TEST_DATA } from './constants.js';\n\n// errors\nexport { ERRORS } from './errors.js';\n\n// types\nexport type {\n  IAsyncStore,\n  IRecordId,\n  IStoreMechanism,\n  IStoreOptions,\n  ISyncStore,\n} from './types.js';\n\n// utilities\nexport {\n  buildDataKey,\n  buildUnavailableException,\n  parseJSON,\n  parseValue,\n  stringifyJSON,\n} from './utilities.js';\n"]}

package/dist/shared/types.d.ts

@@ -0,0 +1,22 @@
+export type IStoreMechanism = 'tempMemory' | 'localStorage' | 'sessionStorage' | 'indexedDB';
+export type IRecordId = undefined | string | number;
+export type IStoreOptions<T> = {
+    fallback?: 'memory';
+    parse?: (value: unknown) => T;
+};
+export type ISyncStore<T> = {
+    readonly id: string;
+    readonly mechanism: IStoreMechanism;
+    isCompatible(): boolean;
+    get(recordId?: IRecordId): T | undefined;
+    set(recordId: IRecordId, value: T): void;
+    del(recordId?: IRecordId): void;
+};
+export type IAsyncStore<T> = {
+    readonly id: string;
+    readonly mechanism: IStoreMechanism;
+    isCompatible(): Promise<boolean>;
+    get(recordId?: IRecordId): Promise<T | undefined>;
+    set(recordId: IRecordId, value: T): Promise<void>;
+    del(recordId?: IRecordId): Promise<void>;
+};

package/dist/shared/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"","sourcesContent":["// the mechanism a store keeps its records in\nexport type IStoreMechanism = 'tempMemory' | 'localStorage' | 'sessionStorage' | 'indexedDB';\n\n// identifies a record in a store. undefined addresses the store's root record, and a string or a\n// number addresses the record stored under `${storeId}_${recordId}`\nexport type IRecordId = undefined | string | number;\n\n// the options every store factory accepts\nexport type IStoreOptions<T> = {\n  // keeps records in a memory map owned by the store when its mechanism is unavailable. Without it,\n  // get returns undefined and set and del throw STORE_UNAVAILABLE\n  fallback?: 'memory';\n\n  // validates or converts every stored value get reads, such as a schema's parse. Its errors\n  // propagate\n  parse?: (value: unknown) => T;\n};\n\n// a store whose methods return their results directly: localStorage, sessionStorage, and memory\nexport type ISyncStore<T> = {\n  // the identifier every record key starts with\n  readonly id: string;\n\n  // the mechanism the store was created for. isCompatible tells whether it's available\n  readonly mechanism: IStoreMechanism;\n\n  // whether the mechanism accepts writes, probed on the first call and remembered\n  isCompatible(): boolean;\n\n  // reads a record, or the root record when recordId is undefined\n  get(recordId?: IRecordId): T | undefined;\n\n  // writes a record, or the root record when recordId is undefined\n  set(recordId: IRecordId, value: T): void;\n\n  // deletes a record, or the root record when recordId is undefined\n  del(recordId?: IRecordId): void;\n};\n\n// a store whose methods return promises: IndexedDB\nexport type IAsyncStore<T> = {\n  // the identifier every record key starts with\n  readonly id: string;\n\n  // the mechanism the store was created for. isCompatible tells whether it's available\n  readonly mechanism: IStoreMechanism;\n\n  // whether the mechanism accepts writes, probed on the first call and remembered\n  isCompatible(): Promise<boolean>;\n\n  // reads a record, or the root record when recordId is undefined\n  get(recordId?: IRecordId): Promise<T | undefined>;\n\n  // writes a record, or the root record when recordId is undefined\n  set(recordId: IRecordId, value: T): Promise<void>;\n\n  // deletes a record, or the root record when recordId is undefined\n  del(recordId?: IRecordId): Promise<void>;\n};\n"]}

package/dist/shared/utilities.d.ts

@@ -0,0 +1,39 @@
+import { Exception } from 'jg-exception';
+import type { IRecordId, IStoreMechanism, IStoreOptions } from './types.js';
+/**
+ * Builds the key a record is stored under, the same one browser-keyval-stores used.
+ * @param storeId The store's identifier.
+ * @param recordId The record's identifier, or undefined for the store's root record.
+ * @returns The key.
+ */
+export declare const buildDataKey: (storeId: string, recordId: IRecordId) => string;
+/**
+ * Runs the store's parse option on a stored value, or returns the value as it is without one.
+ * @param value The stored value.
+ * @param options The store's options.
+ * @returns The value.
+ */
+export declare const parseValue: <T>(value: unknown, options: IStoreOptions<T>) => T;
+/**
+ * Parses a value read from web storage.
+ * @param data The stored text.
+ * @returns The value.
+ * @throws
+ * - FAILED_TO_PARSE_JSON: Unable to parse the JSON data.
+ */
+export declare const parseJSON: (data: string) => unknown;
+/**
+ * Serializes a value to be written to web storage.
+ * @param value The value.
+ * @returns The JSON text.
+ * @throws
+ * - FAILED_TO_STRINGIFY_JSON: Unable to stringify the JSON data.
+ */
+export declare const stringifyJSON: (value: unknown) => string;
+/**
+ * Builds the error a store without a fallback throws when it writes to an unavailable mechanism.
+ * @param storeId The store's identifier.
+ * @param mechanism The mechanism that's unavailable.
+ * @returns The error.
+ */
+export declare const buildUnavailableException: (storeId: string, mechanism: IStoreMechanism) => Exception;

package/dist/shared/utilities.js

@@ -0,0 +1,60 @@
+import { Exception, extractMessage } from 'jg-exception';
+import { ERRORS } from './errors.js';
+/**
+ * Builds the key a record is stored under, the same one browser-keyval-stores used.
+ * @param storeId The store's identifier.
+ * @param recordId The record's identifier, or undefined for the store's root record.
+ * @returns The key.
+ */
+export const buildDataKey = (storeId, recordId) => recordId === undefined ? storeId : `${storeId}_${recordId}`;
+/**
+ * Runs the store's parse option on a stored value, or returns the value as it is without one.
+ * @param value The stored value.
+ * @param options The store's options.
+ * @returns The value.
+ */
+export const parseValue = (value, options) => options.parse === undefined ? value : options.parse(value);
+/**
+ * Parses a value read from web storage.
+ * @param data The stored text.
+ * @returns The value.
+ * @throws
+ * - FAILED_TO_PARSE_JSON: Unable to parse the JSON data.
+ */
+export const parseJSON = (data) => {
+    try {
+        return JSON.parse(data);
+    }
+    catch (error) {
+        throw new Exception(`Unable to parse the JSON data: ${extractMessage(error)}`, ERRORS.FAILED_TO_PARSE_JSON, undefined, { cause: error });
+    }
+};
+/**
+ * Serializes a value to be written to web storage.
+ * @param value The value.
+ * @returns The JSON text.
+ * @throws
+ * - FAILED_TO_STRINGIFY_JSON: Unable to stringify the JSON data.
+ */
+export const stringifyJSON = (value) => {
+    let data;
+    try {
+        data = JSON.stringify(value);
+    }
+    catch (error) {
+        throw new Exception(`Unable to stringify the JSON data: ${extractMessage(error)}`, ERRORS.FAILED_TO_STRINGIFY_JSON, undefined, { cause: error });
+    }
+    // JSON.stringify returns undefined for undefined, functions, and symbols
+    if (data === undefined) {
+        throw new Exception(`Unable to stringify the JSON data: JSON can't represent a value of type '${typeof value}'.`, ERRORS.FAILED_TO_STRINGIFY_JSON);
+    }
+    return data;
+};
+/**
+ * Builds the error a store without a fallback throws when it writes to an unavailable mechanism.
+ * @param storeId The store's identifier.
+ * @param mechanism The mechanism that's unavailable.
+ * @returns The error.
+ */
+export const buildUnavailableException = (storeId, mechanism) => new Exception(`The store '${storeId}' can't write because ${mechanism} is unavailable. Pass { fallback: 'memory' } to keep its records in memory instead.`, ERRORS.STORE_UNAVAILABLE);
+//# sourceMappingURL=utilities.js.map

package/dist/shared/utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../src/shared/utilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,QAAmB,EAAU,EAAE,CAC3E,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAI,KAAc,EAAE,OAAyB,EAAK,EAAE,CAC5E,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAE,KAAW,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAY,EAAW,EAAE;IACjD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,SAAS,CACjB,kCAAkC,cAAc,CAAC,KAAK,CAAC,EAAE,EACzD,MAAM,CAAC,oBAAoB,EAC3B,SAAS,EACT,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAAU,EAAE;IACtD,IAAI,IAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,SAAS,CACjB,sCAAsC,cAAc,CAAC,KAAK,CAAC,EAAE,EAC7D,MAAM,CAAC,wBAAwB,EAC/B,SAAS,EACT,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CACjB,4EAA4E,OAAO,KAAK,IAAI,EAC5F,MAAM,CAAC,wBAAwB,CAChC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,OAAe,EAAE,SAA0B,EAAa,EAAE,CAClG,IAAI,SAAS,CACX,cAAc,OAAO,yBAAyB,SAAS,qFAAqF,EAC5I,MAAM,CAAC,iBAAiB,CACzB,CAAC","sourcesContent":["import { Exception, extractMessage } from 'jg-exception';\n\nimport { ERRORS } from './errors.js';\nimport type { IRecordId, IStoreMechanism, IStoreOptions } from './types.js';\n\n/**\n * Builds the key a record is stored under, the same one browser-keyval-stores used.\n * @param storeId The store's identifier.\n * @param recordId The record's identifier, or undefined for the store's root record.\n * @returns The key.\n */\nexport const buildDataKey = (storeId: string, recordId: IRecordId): string =>\n  recordId === undefined ? storeId : `${storeId}_${recordId}`;\n\n/**\n * Runs the store's parse option on a stored value, or returns the value as it is without one.\n * @param value The stored value.\n * @param options The store's options.\n * @returns The value.\n */\nexport const parseValue = <T>(value: unknown, options: IStoreOptions<T>): T =>\n  options.parse === undefined ? (value as T) : options.parse(value);\n\n/**\n * Parses a value read from web storage.\n * @param data The stored text.\n * @returns The value.\n * @throws\n * - FAILED_TO_PARSE_JSON: Unable to parse the JSON data.\n */\nexport const parseJSON = (data: string): unknown => {\n  try {\n    return JSON.parse(data);\n  } catch (error) {\n    throw new Exception(\n      `Unable to parse the JSON data: ${extractMessage(error)}`,\n      ERRORS.FAILED_TO_PARSE_JSON,\n      undefined,\n      { cause: error },\n    );\n  }\n};\n\n/**\n * Serializes a value to be written to web storage.\n * @param value The value.\n * @returns The JSON text.\n * @throws\n * - FAILED_TO_STRINGIFY_JSON: Unable to stringify the JSON data.\n */\nexport const stringifyJSON = (value: unknown): string => {\n  let data: string | undefined;\n  try {\n    data = JSON.stringify(value);\n  } catch (error) {\n    throw new Exception(\n      `Unable to stringify the JSON data: ${extractMessage(error)}`,\n      ERRORS.FAILED_TO_STRINGIFY_JSON,\n      undefined,\n      { cause: error },\n    );\n  }\n\n  // JSON.stringify returns undefined for undefined, functions, and symbols\n  if (data === undefined) {\n    throw new Exception(\n      `Unable to stringify the JSON data: JSON can't represent a value of type '${typeof value}'.`,\n      ERRORS.FAILED_TO_STRINGIFY_JSON,\n    );\n  }\n  return data;\n};\n\n/**\n * Builds the error a store without a fallback throws when it writes to an unavailable mechanism.\n * @param storeId The store's identifier.\n * @param mechanism The mechanism that's unavailable.\n * @returns The error.\n */\nexport const buildUnavailableException = (storeId: string, mechanism: IStoreMechanism): Exception =>\n  new Exception(\n    `The store '${storeId}' can't write because ${mechanism} is unavailable. Pass { fallback: 'memory' } to keep its records in memory instead.`,\n    ERRORS.STORE_UNAVAILABLE,\n  );\n"]}

package/dist/web-storage-store/index.d.ts

@@ -0,0 +1 @@
+export { createLocalStore, createSessionStore } from './web-storage-store.js';

package/dist/web-storage-store/index.js

@@ -0,0 +1,3 @@
+// web storage stores
+export { createLocalStore, createSessionStore } from './web-storage-store.js';
+//# sourceMappingURL=index.js.map

package/dist/web-storage-store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/web-storage-store/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC","sourcesContent":["// web storage stores\nexport { createLocalStore, createSessionStore } from './web-storage-store.js';\n"]}

package/dist/web-storage-store/web-storage-store.d.ts

@@ -0,0 +1,43 @@
+import { type IStoreOptions, type ISyncStore } from '../shared/index.js';
+/**
+ * Creates a store over localStorage, whose records outlive the page. Values are stored as JSON,
+ * under the same keys browser-keyval-stores used, so their records read back unchanged.
+ * localStorage is read and probed on the first call, never when the store is created.
+ * @param id The identifier every record key starts with.
+ * @param options fallback: 'memory' keeps records in memory when localStorage is unavailable, and
+ * parse runs on every stored value get reads.
+ * @returns The store.
+ * @example
+ * const settings = createLocalStore<{ theme: 'light' | 'dark' }>('settings');
+ * settings.set(undefined, { theme: 'dark' }); // stored under the key 'settings'
+ * settings.get(); // { theme: 'dark' }
+ * settings.set('draft', { theme: 'light' }); // stored under the key 'settings_draft'
+ * @throws
+ * - FAILED_TO_STRINGIFY_JSON: set received a value JSON can't represent.
+ * - FAILED_TO_PARSE_JSON: get read a value that isn't JSON.
+ * - STORE_UNAVAILABLE: set or del ran while localStorage is unavailable, without a fallback.
+ *
+ * Errors from localStorage itself, such as a full quota, propagate.
+ */
+export declare const createLocalStore: <T>(id: string, options?: IStoreOptions<T>) => ISyncStore<T>;
+/**
+ * Creates a store over sessionStorage, whose records last as long as the browser tab. Values are
+ * stored as JSON, under the same keys browser-keyval-stores used, so their records read back
+ * unchanged. sessionStorage is read and probed on the first call, never when the store is created.
+ * @param id The identifier every record key starts with.
+ * @param options fallback: 'memory' keeps records in memory when sessionStorage is unavailable,
+ * and parse runs on every stored value get reads.
+ * @returns The store.
+ * @example
+ * const wizard = createSessionStore<number>('wizard-step', { fallback: 'memory' });
+ * wizard.set(undefined, 2);
+ * wizard.get(); // 2
+ * wizard.del();
+ * @throws
+ * - FAILED_TO_STRINGIFY_JSON: set received a value JSON can't represent.
+ * - FAILED_TO_PARSE_JSON: get read a value that isn't JSON.
+ * - STORE_UNAVAILABLE: set or del ran while sessionStorage is unavailable, without a fallback.
+ *
+ * Errors from sessionStorage itself, such as a full quota, propagate.
+ */
+export declare const createSessionStore: <T>(id: string, options?: IStoreOptions<T>) => ISyncStore<T>;

package/dist/web-storage-store/web-storage-store.js

@@ -0,0 +1,132 @@
+import { createMemoryStore } from '../memory-store/index.js';
+import { STORAGE_TEST_DATA, buildDataKey, buildUnavailableException, parseJSON, parseValue, stringifyJSON, } from '../shared/index.js';
+const webStorageGlobals = globalThis;
+/**
+ * Reads a web storage mechanism and probes whether it accepts writes. Reading it can throw, such
+ * as when a browser blocks storage for the page.
+ * @param mechanism The mechanism.
+ * @returns The storage, or undefined when it's missing or rejects writes.
+ */
+const probeWebStorage = (mechanism) => {
+    try {
+        const storage = webStorageGlobals[mechanism];
+        if (!storage) {
+            return undefined;
+        }
+        storage.setItem(STORAGE_TEST_DATA.key, STORAGE_TEST_DATA.value);
+        storage.removeItem(STORAGE_TEST_DATA.key);
+        return storage;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Creates a store over localStorage or sessionStorage. The mechanism is probed on the first call,
+ * never when the store is created.
+ * @param id The identifier every record key starts with.
+ * @param mechanism The mechanism.
+ * @param options The store's options.
+ * @returns The store.
+ */
+const createWebStorageStore = (id, mechanism, options) => {
+    let isProbed = false;
+    let storage;
+    let memory;
+    // the mechanism, probed on the first call. undefined when it's unavailable
+    const getStorage = () => {
+        if (!isProbed) {
+            storage = probeWebStorage(mechanism);
+            isProbed = true;
+        }
+        return storage;
+    };
+    // the memory store an unavailable mechanism falls back to, when the options ask for one
+    const getMemory = () => {
+        if (options.fallback === 'memory') {
+            memory ??= createMemoryStore(id, options);
+        }
+        return memory;
+    };
+    return {
+        id,
+        mechanism,
+        isCompatible: () => getStorage() !== undefined,
+        get: (recordId) => {
+            const webStorage = getStorage();
+            if (webStorage === undefined) {
+                return getMemory()?.get(recordId);
+            }
+            // a missing record reads as null. An empty string isn't JSON, so it reads as missing too
+            const data = webStorage.getItem(buildDataKey(id, recordId));
+            return data ? parseValue(parseJSON(data), options) : undefined;
+        },
+        set: (recordId, value) => {
+            const webStorage = getStorage();
+            if (webStorage !== undefined) {
+                webStorage.setItem(buildDataKey(id, recordId), stringifyJSON(value));
+                return;
+            }
+            const fallback = getMemory();
+            if (fallback === undefined) {
+                throw buildUnavailableException(id, mechanism);
+            }
+            fallback.set(recordId, value);
+        },
+        del: (recordId) => {
+            const webStorage = getStorage();
+            if (webStorage !== undefined) {
+                webStorage.removeItem(buildDataKey(id, recordId));
+                return;
+            }
+            const fallback = getMemory();
+            if (fallback === undefined) {
+                throw buildUnavailableException(id, mechanism);
+            }
+            fallback.del(recordId);
+        },
+    };
+};
+/**
+ * Creates a store over localStorage, whose records outlive the page. Values are stored as JSON,
+ * under the same keys browser-keyval-stores used, so their records read back unchanged.
+ * localStorage is read and probed on the first call, never when the store is created.
+ * @param id The identifier every record key starts with.
+ * @param options fallback: 'memory' keeps records in memory when localStorage is unavailable, and
+ * parse runs on every stored value get reads.
+ * @returns The store.
+ * @example
+ * const settings = createLocalStore<{ theme: 'light' | 'dark' }>('settings');
+ * settings.set(undefined, { theme: 'dark' }); // stored under the key 'settings'
+ * settings.get(); // { theme: 'dark' }
+ * settings.set('draft', { theme: 'light' }); // stored under the key 'settings_draft'
+ * @throws
+ * - FAILED_TO_STRINGIFY_JSON: set received a value JSON can't represent.
+ * - FAILED_TO_PARSE_JSON: get read a value that isn't JSON.
+ * - STORE_UNAVAILABLE: set or del ran while localStorage is unavailable, without a fallback.
+ *
+ * Errors from localStorage itself, such as a full quota, propagate.
+ */
+export const createLocalStore = (id, options = {}) => createWebStorageStore(id, 'localStorage', options);
+/**
+ * Creates a store over sessionStorage, whose records last as long as the browser tab. Values are
+ * stored as JSON, under the same keys browser-keyval-stores used, so their records read back
+ * unchanged. sessionStorage is read and probed on the first call, never when the store is created.
+ * @param id The identifier every record key starts with.
+ * @param options fallback: 'memory' keeps records in memory when sessionStorage is unavailable,
+ * and parse runs on every stored value get reads.
+ * @returns The store.
+ * @example
+ * const wizard = createSessionStore<number>('wizard-step', { fallback: 'memory' });
+ * wizard.set(undefined, 2);
+ * wizard.get(); // 2
+ * wizard.del();
+ * @throws
+ * - FAILED_TO_STRINGIFY_JSON: set received a value JSON can't represent.
+ * - FAILED_TO_PARSE_JSON: get read a value that isn't JSON.
+ * - STORE_UNAVAILABLE: set or del ran while sessionStorage is unavailable, without a fallback.
+ *
+ * Errors from sessionStorage itself, such as a full quota, propagate.
+ */
+export const createSessionStore = (id, options = {}) => createWebStorageStore(id, 'sessionStorage', options);
+//# sourceMappingURL=web-storage-store.js.map

package/dist/web-storage-store/web-storage-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-storage-store.js","sourceRoot":"","sources":["../../src/web-storage-store/web-storage-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createMemoryStore } from '../memory-store/index.js';\nimport {\n  STORAGE_TEST_DATA,\n  buildDataKey,\n  buildUnavailableException,\n  parseJSON,\n  parseValue,\n  stringifyJSON,\n  type IRecordId,\n  type IStoreOptions,\n  type ISyncStore,\n} from '../shared/index.js';\n\n// the web storage mechanisms, read from globalThis when a store first needs them. Workers have\n// neither, so they're optional here\ntype IWebStorageMechanism = 'localStorage' | 'sessionStorage';\nconst webStorageGlobals: Partial<Record<IWebStorageMechanism, Storage>> = globalThis;\n\n/**\n * Reads a web storage mechanism and probes whether it accepts writes. Reading it can throw, such\n * as when a browser blocks storage for the page.\n * @param mechanism The mechanism.\n * @returns The storage, or undefined when it's missing or rejects writes.\n */\nconst probeWebStorage = (mechanism: IWebStorageMechanism): Storage | undefined => {\n  try {\n    const storage = webStorageGlobals[mechanism];\n    if (!storage) {\n      return undefined;\n    }\n    storage.setItem(STORAGE_TEST_DATA.key, STORAGE_TEST_DATA.value);\n    storage.removeItem(STORAGE_TEST_DATA.key);\n    return storage;\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * Creates a store over localStorage or sessionStorage. The mechanism is probed on the first call,\n * never when the store is created.\n * @param id The identifier every record key starts with.\n * @param mechanism The mechanism.\n * @param options The store's options.\n * @returns The store.\n */\nconst createWebStorageStore = <T>(\n  id: string,\n  mechanism: IWebStorageMechanism,\n  options: IStoreOptions<T>,\n): ISyncStore<T> => {\n  let isProbed = false;\n  let storage: Storage | undefined;\n  let memory: ISyncStore<T> | undefined;\n\n  // the mechanism, probed on the first call. undefined when it's unavailable\n  const getStorage = (): Storage | undefined => {\n    if (!isProbed) {\n      storage = probeWebStorage(mechanism);\n      isProbed = true;\n    }\n    return storage;\n  };\n\n  // the memory store an unavailable mechanism falls back to, when the options ask for one\n  const getMemory = (): ISyncStore<T> | undefined => {\n    if (options.fallback === 'memory') {\n      memory ??= createMemoryStore(id, options);\n    }\n    return memory;\n  };\n\n  return {\n    id,\n    mechanism,\n    isCompatible: () => getStorage() !== undefined,\n    get: (recordId?: IRecordId) => {\n      const webStorage = getStorage();\n      if (webStorage === undefined) {\n        return getMemory()?.get(recordId);\n      }\n\n      // a missing record reads as null. An empty string isn't JSON, so it reads as missing too\n      const data = webStorage.getItem(buildDataKey(id, recordId));\n      return data ? parseValue(parseJSON(data), options) : undefined;\n    },\n    set: (recordId: IRecordId, value: T) => {\n      const webStorage = getStorage();\n      if (webStorage !== undefined) {\n        webStorage.setItem(buildDataKey(id, recordId), stringifyJSON(value));\n        return;\n      }\n      const fallback = getMemory();\n      if (fallback === undefined) {\n        throw buildUnavailableException(id, mechanism);\n      }\n      fallback.set(recordId, value);\n    },\n    del: (recordId?: IRecordId) => {\n      const webStorage = getStorage();\n      if (webStorage !== undefined) {\n        webStorage.removeItem(buildDataKey(id, recordId));\n        return;\n      }\n      const fallback = getMemory();\n      if (fallback === undefined) {\n        throw buildUnavailableException(id, mechanism);\n      }\n      fallback.del(recordId);\n    },\n  };\n};\n\n/**\n * Creates a store over localStorage, whose records outlive the page. Values are stored as JSON,\n * under the same keys browser-keyval-stores used, so their records read back unchanged.\n * localStorage is read and probed on the first call, never when the store is created.\n * @param id The identifier every record key starts with.\n * @param options fallback: 'memory' keeps records in memory when localStorage is unavailable, and\n * parse runs on every stored value get reads.\n * @returns The store.\n * @example\n * const settings = createLocalStore<{ theme: 'light' | 'dark' }>('settings');\n * settings.set(undefined, { theme: 'dark' }); // stored under the key 'settings'\n * settings.get(); // { theme: 'dark' }\n * settings.set('draft', { theme: 'light' }); // stored under the key 'settings_draft'\n * @throws\n * - FAILED_TO_STRINGIFY_JSON: set received a value JSON can't represent.\n * - FAILED_TO_PARSE_JSON: get read a value that isn't JSON.\n * - STORE_UNAVAILABLE: set or del ran while localStorage is unavailable, without a fallback.\n *\n * Errors from localStorage itself, such as a full quota, propagate.\n */\nexport const createLocalStore = <T>(id: string, options: IStoreOptions<T> = {}): ISyncStore<T> =>\n  createWebStorageStore(id, 'localStorage', options);\n\n/**\n * Creates a store over sessionStorage, whose records last as long as the browser tab. Values are\n * stored as JSON, under the same keys browser-keyval-stores used, so their records read back\n * unchanged. sessionStorage is read and probed on the first call, never when the store is created.\n * @param id The identifier every record key starts with.\n * @param options fallback: 'memory' keeps records in memory when sessionStorage is unavailable,\n * and parse runs on every stored value get reads.\n * @returns The store.\n * @example\n * const wizard = createSessionStore<number>('wizard-step', { fallback: 'memory' });\n * wizard.set(undefined, 2);\n * wizard.get(); // 2\n * wizard.del();\n * @throws\n * - FAILED_TO_STRINGIFY_JSON: set received a value JSON can't represent.\n * - FAILED_TO_PARSE_JSON: get read a value that isn't JSON.\n * - STORE_UNAVAILABLE: set or del ran while sessionStorage is unavailable, without a fallback.\n *\n * Errors from sessionStorage itself, such as a full quota, propagate.\n */\nexport const createSessionStore = <T>(id: string, options: IStoreOptions<T> = {}): ISyncStore<T> =>\n  createWebStorageStore(id, 'sessionStorage', options);\n"]}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "jg-storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Typed key-value stores over localStorage, sessionStorage, IndexedDB, and memory, for browsers and workers.",
+  "author": "Jesus Graterol",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jesusgraterol/jg-packages.git",
+    "directory": "packages/jg-storage"
+  },
+  "homepage": "https://jg-packages.jesusgraterol.dev/packages/jg-storage/",
+  "bugs": {
+    "url": "https://github.com/jesusgraterol/jg-packages/issues"
+  },
+  "keywords": [
+    "browser",
+    "storage",
+    "localstorage",
+    "sessionstorage",
+    "indexeddb",
+    "key-value"
+  ],
+  "dependencies": {
+    "idb-keyval": "^6.3.0",
+    "jg-exception": "^1.0.0"
+  },
+  "devDependencies": {
+    "@jg-packages/eslint-config": "0.0.0",
+    "@jg-packages/tsconfig": "0.0.0",
+    "@jg-packages/vitest-config": "0.0.0",
+    "@types/node": "24.19.2",
+    "browser-keyval-stores": "1.1.1",
+    "eslint": "10.12.0",
+    "fake-indexeddb": "6.2.5",
+    "typescript": "6.0.3",
+    "vitest": "5.0.5"
+  },
+  "scripts": {
+    "build": "node ../../internal/build-tools/src/clean-dist.ts && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "test": "pnpm test:unit && pnpm test:integration",
+    "test:integration": "vitest run --project integration",
+    "test:unit": "vitest run --project unit",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.browser.json"
+  }
 }