offdex 1.0.6 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 offdex contributors
+
+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,59 +1,68 @@
-# Offdex
-
-ID-first object storage for the browser. Offdex wraps IndexedDB with a tiny, stable API so you can drop in `{ id: <uuid>, ...data }` objects and have them shared across tabs, workers, and sessions without thinking about schema versions.
-
-## Why use Offdex
-- Zero schema/versioning overhead: one object store keyed by `id`, no migrations to manage.
-- Works everywhere IndexedDB works: tabs, workers, and other browser runtimes share the same underlying database.
-- Offline by default: IndexedDB persists across reloads and disconnects.
-- Typed surface: ships with TypeScript definitions for easy adoption.
-
-## Install
-```bash
-npm install offdex
-```
-
-## Quick start
-```js
-import { storage } from "offdex";
-
+# Offdex
+
+Keyed object storage for the browser. Offdex wraps IndexedDB with a tiny, unbiased API so you can drop in `{ key: "<string>", ...data }` objects and have them shared across tabs, workers, and sessions without thinking about schema versions.
+
+## Why use Offdex
+
+- Zero schema/versioning overhead: one object store keyed by `key`, no migrations to manage.
+- Minimal wrapper: no hooks or proxies in the storage API, just data in and data out.
+- Works everywhere IndexedDB works: tabs, workers, and other browser runtimes share the same underlying database.
+- Offline by default: IndexedDB persists across reloads and disconnects.
+- Typed surface: ships with TypeScript definitions for easy adoption.
+
+## Install
+
+```bash
+npm install offdex
+```
+
+## Quick start
+
+```js
+import { storage } from "offdex";
+
 const profile = {
-  id: crypto.randomUUID(), // UUIDv4 string
+  key: "profile:ada",
   name: "Ada Lovelace",
-  role: "analyst"
+  role: "analyst",
 };
-
-await storage.put(profile);
-
-const again = await storage.get(profile.id);
-// -> { id: "…", name: "Ada Lovelace", role: "analyst" }
-
-await storage.delete(profile.id);
-```
-
-## API
-### `storage`
-- Ready-to-use singleton instance shared across every import in the same origin. Uses the `offdex` database and `objects` store under the hood.
-
-### `class ObjectStore`
-- `constructor()` — opens (or creates) the `offdex` database with the `objects` store. Use this only if you need a separate instance.
-- `put(object: { id: UUIDv4 } & Record<string, unknown>): Promise<void>` — upserts an object keyed by `id`.
-- `get(id: UUIDv4, onSet?, onDelete?): Promise<{ id: UUIDv4 } & Record<string, unknown> | undefined>` — fetches by `id`, returning `undefined` when missing. Optional callbacks run before a property change/delete; return `false` to block the change.
-- `delete(id: UUIDv4): Promise<void>` — removes an object by `id`.
-- `getAllMatches(queryOrFilter: StorageQuery | (object) => boolean, onSet?, onDelete?): Promise<object[]>` — returns objects that pass a query or predicate (with the same optional callbacks as `get`).
-- `deleteAllMatches(queryOrFilter: StorageQuery | (object) => boolean): Promise<void>` — deletes objects that pass a query or predicate.
-
-### Other exports
-- `StorageQuery` — helper for simple equality-based queries.
-- `ObservableValue` — observable wrapper around a single value.
-- `ObservableObject` — wraps an object in observable values keyed by its properties.
-
-### Types
-- `UUIDv4` — template literal type for UUID strings.
-- `StoredObject` — `{ id: UUIDv4 } & Record<string, unknown>`.
-- `OnSetHandler`, `OnDeleteHandler` — callback shapes used by `get`/`getAllMatches`.
-
-## Notes
-- Runs in any environment that exposes `indexedDB` (secure contexts in modern browsers).
-- Data is shared per origin; open multiple tabs or workers and you will see the same store.
-- There is no schema migration system; keep your stored objects backward compatible or manage migrations externally if you need them.
+
+await storage.put(profile);
+
+const again = await storage.get(profile.key);
+// -> { key: "profile:ada", name: "Ada Lovelace", role: "analyst" }
+
+await storage.delete(profile.key);
+```
+
+## API
+
+### `storage`
+
+- Ready-to-use singleton instance shared across every import in the same origin. Uses the `offdex` database and `objects` store under the hood.
+
+### `class ObjectStore`
+
+- `constructor()` — opens (or creates) the `offdex` database with the `objects` store. Use this only if you need a separate instance.
+- `put(object: { key: string } & Record<string, unknown>): Promise<void>` - upserts an object keyed by `key`.
+- `putAll(objects: { key: string } & Record<string, unknown>[]): Promise<void>` - upserts multiple objects in a single transaction.
+- `get(key: string): Promise<{ key: string } & Record<string, unknown> | undefined>` - fetches by `key`, returning `undefined` when missing.
+- `delete(key: string): Promise<void>` - removes an object by `key`.
+- `getAllMatches(queryOrFilter: StorageQuery | (object) => boolean): Promise<object[]>` - returns objects that pass a query or predicate.
+- `deleteAllMatches(queryOrFilter: StorageQuery | (object) => boolean): Promise<void>` — deletes objects that pass a query or predicate.
+
+### Other exports
+
+- `StorageQuery` — helper for simple equality-based queries.
+- `ObservableValue` — observable wrapper around a single value.
+- `ObservableObject` — wraps an object in observable values keyed by its properties.
+
+### Types
+
+- `StoredObject` - `{ key: string } & Record<string, unknown>`.
+
+## Notes
+
+- Runs in any environment that exposes `indexedDB` (secure contexts in modern browsers).
+- Data is shared per origin; open multiple tabs or workers and you will see the same store.
+- There is no schema migration system; keep your stored objects backward compatible or manage migrations externally if you need them.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "offdex",
-  "version": "1.0.6",
-  "description": "ID-driven object storage wrapper for IndexedDB with zero schema/versioning overhead. Shared across all browser threads, offline-persistent, large capacity, simple API.",
+  "version": "2.0.0",
+  "description": "Minimal, unbiased IndexedDB object-store wrapper keyed by a string. Shared across browser threads, offline-persistent, simple API.",
   "keywords": [
     "indexeddb",
     "offline",
@@ -10,16 +10,25 @@
     "web-storage",
     "object-store",
     "key-value",
-    "id",
+    "key",
     "persist",
     "threads",
     "workers",
-    "shared"
+    "shared",
+    "minimal"
   ],
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jortsupetterson/offdex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jortsupetterson/offdex/issues"
+  },
+  "homepage": "https://github.com/jortsupetterson/offdex#readme",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -29,6 +38,7 @@
   },
   "files": [
     "src",
+    "LICENSE",
     "README.md"
   ],
   "sideEffects": false

package/src/ObjectStore/index.js

@@ -12,7 +12,7 @@ export class ObjectStore {
       request.addEventListener("upgradeneeded", () => {
         const db = request.result;
         if (!db.objectStoreNames.contains(ObjectStore.#store)) {
-          db.createObjectStore(ObjectStore.#store, { keyPath: "id" });
+          db.createObjectStore(ObjectStore.#store, { keyPath: "key" });
         }
       });
 
@@ -48,19 +48,16 @@ export class ObjectStore {
   }
 
   /**
-   * @param {import("../types").UUIDv4} id
-   * @param {(propertyName: string, oldValue: any, newValue: any) => void | boolean} [onSetEvent]
-   * @param {(propertyName: string, deletedValue: any) => void | boolean} [onDeleteEvent]
+   * @param {string} key
    * @returns {Promise<import("../types").StoredObject | undefined>}
    */
-  async get(id, onSetEvent, onDeleteEvent) {
+  async get(key) {
     const db = await this.instance;
-    const objectStoreInstance = this;
 
     return new Promise((resolve, reject) => {
       const transaction = db.transaction(ObjectStore.#store, "readonly");
       const store = transaction.objectStore(ObjectStore.#store);
-      const request = store.get(id);
+      const request = store.get(key);
 
       transaction.oncomplete = () => {
         if (!request.result) {
@@ -68,32 +65,7 @@ export class ObjectStore {
           return;
         }
 
-        const target = request.result;
-
-        const handler = {
-          set(targetObject, propertyName, newValue) {
-            const oldValue = targetObject[propertyName];
-            if (onSetEvent) {
-              const shouldUpdate = onSetEvent(propertyName, oldValue, newValue);
-              if (shouldUpdate === false) return true;
-            }
-            targetObject[propertyName] = newValue;
-            void objectStoreInstance.put(targetObject);
-            return true;
-          },
-          deleteProperty(targetObject, propertyName) {
-            const deletedValue = targetObject[propertyName];
-            if (onDeleteEvent) {
-              const shouldDelete = onDeleteEvent(propertyName, deletedValue);
-              if (shouldDelete === false) return true;
-            }
-            delete targetObject[propertyName];
-            void objectStoreInstance.put(targetObject);
-            return true;
-          },
-        };
-
-        resolve(new Proxy(target, handler));
+        resolve(request.result);
       };
 
       transaction.onerror = () =>
@@ -102,28 +74,46 @@ export class ObjectStore {
   }
 
   /**
-   * @param {import("../types").UUIDv4} id
+   * @param {string} key
    * @returns {Promise<void>}
    */
-  async delete(id) {
+  async delete(key) {
     const db = await this.instance;
     return new Promise((resolve, reject) => {
       const transaction = db.transaction(ObjectStore.#store, "readwrite");
       const store = transaction.objectStore(ObjectStore.#store);
-      store.delete(id);
+      store.delete(key);
       transaction.oncomplete = () => resolve();
       transaction.onerror = () =>
         reject(new Error(`{offdex} ObjectStore: ${transaction.error}`));
     });
   }
 
+  /**
+   * @param {import("../types").StoredObject[]} objects
+   * @returns {Promise<void>}
+   */
+  async putAll(objects) {
+    const db = await this.instance;
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(ObjectStore.#store, "readwrite");
+      const store = transaction.objectStore(ObjectStore.#store);
+
+      for (const object of objects) {
+        store.put(object);
+      }
+
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () =>
+        reject(new Error(`{offdex} ObjectStore.putAll: ${transaction.error}`));
+    });
+  }
+
   /**
    * @param {import("../StorageQuery/index.js").StorageQuery | ((object: import("../types").StoredObject) => boolean)} queryOrPredicate
-   * @param {(propertyName: string, oldValue: any, newValue: any) => void | boolean} [onSetEvent]
-   * @param {(propertyName: string, deletedValue: any) => void | boolean} [onDeleteEvent]
    * @returns {Promise<import("../types").StoredObject[]>}
    */
-  async getAllMatches(queryOrPredicate, onSetEvent, onDeleteEvent) {
+  async getAllMatches(queryOrPredicate) {
     const db = await this.instance;
     const objectStoreInstance = this;
 
@@ -146,34 +136,7 @@ export class ObjectStore {
         const value = cursor.value;
 
         if (predicate(value)) {
-          const handler = {
-            set(targetObject, propertyName, newValue) {
-              const oldValue = targetObject[propertyName];
-              if (onSetEvent) {
-                const shouldUpdate = onSetEvent(
-                  propertyName,
-                  oldValue,
-                  newValue
-                );
-                if (shouldUpdate === false) return true;
-              }
-              targetObject[propertyName] = newValue;
-              void objectStoreInstance.put(targetObject);
-              return true;
-            },
-            deleteProperty(targetObject, propertyName) {
-              const deletedValue = targetObject[propertyName];
-              if (onDeleteEvent) {
-                const shouldDelete = onDeleteEvent(propertyName, deletedValue);
-                if (shouldDelete === false) return true;
-              }
-              delete targetObject[propertyName];
-              void objectStoreInstance.put(targetObject);
-              return true;
-            },
-          };
-
-          results.push(new Proxy(value, handler));
+          results.push(value);
         }
 
         cursor.continue();

package/src/index.d.ts

@@ -1,54 +1,36 @@
-export type UUIDv4 = `${string}-${string}-${string}-${string}-${string}`;
-
-export type StoredObject = { id: UUIDv4 } & Record<string, unknown>;
-
-export type OnSetHandler = (
-  propertyName: string,
-  oldValue: unknown,
-  newValue: unknown
-) => void | boolean;
-
-export type OnDeleteHandler = (
-  propertyName: string,
-  deletedValue: unknown
-) => void | boolean;
-
-export class StorageQuery {
-  constructor(args?: Record<string, unknown>);
-  args: Record<string, unknown>;
-  matches(object: StoredObject): boolean;
-}
-
-export class ObservableValue<T = unknown> {
-  constructor(value: T, fallback?: T);
-  get(): T;
-  set(newValue: T): void;
-  reset(): void;
-  observe(event: "set" | "reset", callback: (value: T) => void): () => void;
-}
-
-export class ObservableObject<T extends StoredObject = StoredObject> {
-  constructor(object: T);
-  [key: string]: ObservableValue<unknown>;
-}
-
+export type StoredObject = { key: string } & Record<string, unknown>;
+
+export class StorageQuery {
+  constructor(args?: Record<string, unknown>);
+  args: Record<string, unknown>;
+  matches(object: StoredObject): boolean;
+}
+
+export class ObservableValue<T = unknown> {
+  constructor(value: T, fallback?: T);
+  get(): T;
+  set(newValue: T): void;
+  reset(): void;
+  observe(event: "set" | "reset", callback: (value: T) => void): () => void;
+}
+
+export class ObservableObject<T extends StoredObject = StoredObject> {
+  constructor(object: T);
+  [key: string]: ObservableValue<unknown>;
+}
+
 export class ObjectStore {
   constructor();
   put(object: StoredObject): Promise<void>;
-  get(
-    id: UUIDv4,
-    onSetEvent?: OnSetHandler,
-    onDeleteEvent?: OnDeleteHandler
-  ): Promise<StoredObject | undefined>;
-  delete(id: UUIDv4): Promise<void>;
+  get(key: string): Promise<StoredObject | undefined>;
+  delete(key: string): Promise<void>;
+  putAll(objects: StoredObject[]): Promise<void>;
   getAllMatches(
-    queryOrFilter: StorageQuery | ((object: StoredObject) => boolean),
-    onSetEvent?: OnSetHandler,
-    onDeleteEvent?: OnDeleteHandler
+    queryOrFilter: StorageQuery | ((object: StoredObject) => boolean)
   ): Promise<StoredObject[]>;
   deleteAllMatches(
     queryOrFilter: StorageQuery | ((object: StoredObject) => boolean)
-  ): Promise<void>;
-}
-
-export const storage: ObjectStore;
+  ): Promise<void>;
+}
+
+export const storage: ObjectStore;

package/src/types.d.ts

@@ -1,3 +1 @@
-export type UUIDv4 = `${string}-${string}-${string}-${string}-${string}`;
-
-export type StoredObject = { id: UUIDv4 } & Record<string, unknown>;
+export type StoredObject = { key: string } & Record<string, unknown>;