offdex 1.0.3 → 1.0.6

package/README.md

@@ -15,9 +15,7 @@ npm install offdex
 
 ## Quick start
 ```js
-import { OfflineStorage } from "offdex";
-
-const storage = new OfflineStorage();
+import { storage } from "offdex";
 
 const profile = {
   id: crypto.randomUUID(), // UUIDv4 string
@@ -34,19 +32,28 @@ await storage.delete(profile.id);
 ```
 
 ## API
-### `class OfflineStorage`
-- `constructor()` — opens (or creates) the `offline` database with the `objects` store.
+### `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): Promise<{ id: UUIDv4 } & Record<string, unknown> | undefined>` — fetches by `id`, returning `undefined` when missing.
+- `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.
-
-## Quick manual test
-Open `in-browser-testing.html` in a browser (or serve it locally) to poke at the API from DevTools: the module attaches `OfflineStorage` to `globalThis`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offdex",
-  "version": "1.0.3",
+  "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.",
   "keywords": [
     "indexeddb",

package/src/ObjectStore/index.js

@@ -0,0 +1,221 @@
+export class ObjectStore {
+  static #idb = "offdex";
+  static #store = "objects";
+
+  /**
+   * @returns {Promise<IDBDatabase>}
+   */
+  static #open() {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(ObjectStore.#idb);
+
+      request.addEventListener("upgradeneeded", () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(ObjectStore.#store)) {
+          db.createObjectStore(ObjectStore.#store, { keyPath: "id" });
+        }
+      });
+
+      request.addEventListener("success", () => {
+        resolve(request.result);
+      });
+
+      request.addEventListener("error", () => {
+        reject(request.error);
+      });
+    });
+  }
+
+  constructor() {
+    this.instance = ObjectStore.#open();
+  }
+
+  /**
+   * @param {import("../types").StoredObject} object
+   * @returns {Promise<void>}
+   */
+  async put(object) {
+    const db = await this.instance;
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(ObjectStore.#store, "readwrite");
+      const store = transaction.objectStore(ObjectStore.#store);
+      store.put(object);
+
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () =>
+        reject(new Error(`{offdex} ObjectStore: ${transaction.error}`));
+    });
+  }
+
+  /**
+   * @param {import("../types").UUIDv4} id
+   * @param {(propertyName: string, oldValue: any, newValue: any) => void | boolean} [onSetEvent]
+   * @param {(propertyName: string, deletedValue: any) => void | boolean} [onDeleteEvent]
+   * @returns {Promise<import("../types").StoredObject | undefined>}
+   */
+  async get(id, onSetEvent, onDeleteEvent) {
+    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);
+
+      transaction.oncomplete = () => {
+        if (!request.result) {
+          resolve(undefined);
+          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));
+      };
+
+      transaction.onerror = () =>
+        reject(new Error(`{offdex} ObjectStore: ${transaction.error}`));
+    });
+  }
+
+  /**
+   * @param {import("../types").UUIDv4} id
+   * @returns {Promise<void>}
+   */
+  async delete(id) {
+    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);
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () =>
+        reject(new Error(`{offdex} ObjectStore: ${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) {
+    const db = await this.instance;
+    const objectStoreInstance = this;
+
+    const predicate =
+      typeof queryOrPredicate === "function"
+        ? queryOrPredicate
+        : (object) => queryOrPredicate.matches(object);
+
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(ObjectStore.#store, "readonly");
+      const store = transaction.objectStore(ObjectStore.#store);
+      const request = store.openCursor();
+
+      const results = [];
+
+      request.onsuccess = () => {
+        const cursor = request.result;
+        if (!cursor) return;
+
+        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));
+        }
+
+        cursor.continue();
+      };
+
+      transaction.oncomplete = () => resolve(results);
+      transaction.onerror = () =>
+        reject(new Error(`{offdex} ObjectStore: ${transaction.error}`));
+    });
+  }
+
+  /**
+   * @param {import("../StorageQuery/index.js").StorageQuery | ((object: import("../types").StoredObject) => boolean)} queryOrPredicate
+   * @returns {Promise<void>}
+   */
+  async deleteAllMatches(queryOrPredicate) {
+    const db = await this.instance;
+
+    const predicate =
+      typeof queryOrPredicate === "function"
+        ? queryOrPredicate
+        : (object) => queryOrPredicate.matches(object);
+
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(ObjectStore.#store, "readwrite");
+      const store = transaction.objectStore(ObjectStore.#store);
+      const request = store.openCursor();
+
+      request.onsuccess = () => {
+        const cursor = request.result;
+        if (!cursor) return;
+
+        if (predicate(cursor.value)) {
+          cursor.delete();
+        }
+
+        cursor.continue();
+      };
+
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () =>
+        reject(new Error(`{offdex} ObjectStore: ${transaction.error}`));
+    });
+  }
+}

package/src/ObservableObject/index.js

@@ -0,0 +1,12 @@
+import { ObservableValue } from "../ObservableValue/index.js";
+
+export class ObservableObject {
+  /**
+   * @param {import("../types").StoredObject} object
+   */
+  constructor(object) {
+    for (const key in object) {
+      this[key] = new ObservableValue(object[key]);
+    }
+  }
+}

package/src/ObservableValue/index.js

@@ -0,0 +1,58 @@
+export class ObservableValue {
+  /**
+   * @param {any} value
+   * @param {any} [fallback]
+   */
+  constructor(value, fallback = null) {
+    this.value = value;
+    this.fallback = fallback;
+    /** @type {Set<{ event: "set" | "reset"; callback: (value: any) => void }>} */
+    this.observers = new Set();
+  }
+  get() {
+    return this.value;
+  }
+  /**
+   * @param {any} newValue
+   * @returns {void}
+   */
+  set(newValue) {
+    if (newValue === this.value) return;
+    this.value = newValue;
+    const changeObservers = [...this.observers].filter(
+      (observer) => observer.event === "set"
+    );
+    for (const observer of changeObservers) {
+      observer.callback(newValue);
+    }
+  }
+  reset() {
+    this.value = this.fallback;
+    const resetObservers = [...this.observers].filter(
+      (observer) => observer.event === "reset"
+    );
+    for (const observer of resetObservers) {
+      observer.callback(this.fallback);
+    }
+  }
+  /**
+   * @param {"set" | "reset"} event
+   * @param {Function} callback
+   * @returns {() => void}
+   */
+  observe(event, callback) {
+    if (event !== "set" && event !== "reset")
+      throw new Error(
+        "{offdex} ObservableValue: Supported `event` parameters are [set, reset]"
+      );
+    if (typeof callback !== "function")
+      throw new Error(
+        "{offdex} ObservableValue: Paramater `callback` must be of type function"
+      );
+    const observer = { event, callback };
+    this.observers.add(observer);
+    return () => {
+      this.observers.delete(observer);
+    };
+  }
+}

package/src/StorageQuery/index.js

@@ -0,0 +1,12 @@
+export class StorageQuery {
+  constructor(args = {}) {
+    this.args = args;
+  }
+
+  matches(object) {
+    for (const key in this.args) {
+      if (object[key] !== this.args[key]) return false;
+    }
+    return true;
+  }
+}

package/src/index.d.ts

@@ -2,18 +2,53 @@ export type UUIDv4 = `${string}-${string}-${string}-${string}-${string}`;
 
 export type StoredObject = { id: UUIDv4 } & Record<string, unknown>;
 
-export class OfflineStorage {
+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 class ObjectStore {
   constructor();
-  /**
-   * Persist or overwrite an object by id.
-   */
   put(object: StoredObject): Promise<void>;
-  /**
-   * Fetch an object by id. Returns undefined when missing.
-   */
-  get(id: UUIDv4): Promise<StoredObject | undefined>;
-  /**
-   * Remove an object by id.
-   */
+  get(
+    id: UUIDv4,
+    onSetEvent?: OnSetHandler,
+    onDeleteEvent?: OnDeleteHandler
+  ): Promise<StoredObject | undefined>;
   delete(id: UUIDv4): Promise<void>;
+  getAllMatches(
+    queryOrFilter: StorageQuery | ((object: StoredObject) => boolean),
+    onSetEvent?: OnSetHandler,
+    onDeleteEvent?: OnDeleteHandler
+  ): Promise<StoredObject[]>;
+  deleteAllMatches(
+    queryOrFilter: StorageQuery | ((object: StoredObject) => boolean)
+  ): Promise<void>;
 }
+
+export const storage: ObjectStore;

package/src/index.js

@@ -1,81 +1,7 @@
-export class OfflineStorage {
-  static #idb = "offline";
-  static #store = "objects";
-
-  /**
-   * @returns {Promise<IDBDatabase>}
-   */
-  static #open() {
-    return new Promise((resolve, reject) => {
-      const request = indexedDB.open(OfflineStorage.#idb);
-
-      request.addEventListener("upgradeneeded", () => {
-        const db = request.result;
-        if (!db.objectStoreNames.contains(OfflineStorage.#store)) {
-          db.createObjectStore(OfflineStorage.#store, { keyPath: "id" });
-        }
-      });
-
-      request.addEventListener("success", () => {
-        resolve(request.result);
-      });
-
-      request.addEventListener("error", () => {
-        reject(request.error);
-      });
-    });
-  }
-
-  constructor() {
-    this.storage = OfflineStorage.#open();
-  }
+import { ObjectStore } from "./ObjectStore/index.js";
+import { StorageQuery } from "./StorageQuery/index.js";
+import { ObservableValue } from "./ObservableValue/index.js";
+import { ObservableObject } from "./ObservableObject/index.js";
 
-  /**
-   * @param {import("./types").StoredObject} object
-   * @returns {Promise<void>}
-   */
-  async put(object) {
-    const db = await this.storage;
-    return new Promise((resolve, reject) => {
-      const tx = db.transaction(OfflineStorage.#store, "readwrite");
-      const store = tx.objectStore(OfflineStorage.#store);
-      store.put(object);
-
-      tx.oncomplete = () => resolve();
-      tx.onerror = () => reject(new Error(`[OfflineStorage] ${tx.error}`));
-    });
-  }
-
-  /**
-   * @param {import("./types").UUIDv4} id
-   * @returns {Promise<import("./types").StoredObject | undefined>}
-   */
-  async get(id) {
-    const db = await this.storage;
-    return new Promise((resolve, reject) => {
-      const tx = db.transaction(OfflineStorage.#store, "readonly");
-      const store = tx.objectStore(OfflineStorage.#store);
-      const request = store.get(id);
-
-      tx.oncomplete = () => {
-        resolve(request.result ? request.result : undefined);
-      };
-      tx.onerror = () => reject(new Error(`[OfflineStorage] ${tx.error}`));
-    });
-  }
-  /**
-   *
-   * @param {import("./types").UUIDv4} id
-   * @returns {Promise<void>}
-   */
-  async delete(id) {
-    const db = await this.storage;
-    return new Promise((resolve, reject) => {
-      const tx = db.transaction(OfflineStorage.#store, "readwrite");
-      const store = tx.objectStore(OfflineStorage.#store);
-      store.delete(id);
-      tx.oncomplete = () => resolve();
-      tx.onerror = () => reject(new Error(`[OfflineStorage] ${tx.error}`));
-    });
-  }
-}
+export { ObjectStore, StorageQuery, ObservableValue, ObservableObject };
+export const storage = new ObjectStore();