offdex 1.0.2

package/README.md

@@ -0,0 +1,52 @@
+# 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 { OfflineStorage } from "offdex";
+
+const storage = new OfflineStorage();
+
+const profile = {
+  id: crypto.randomUUID(), // UUIDv4 string
+  name: "Ada Lovelace",
+  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
+### `class OfflineStorage`
+- `constructor()` — opens (or creates) the `offline` database with the `objects` store.
+- `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.
+- `delete(id: UUIDv4): Promise<void>` — removes an object by `id`.
+
+### Types
+- `UUIDv4` — template literal type for UUID strings.
+
+## 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

@@ -0,0 +1,35 @@
+{
+  "name": "offdex",
+  "version": "1.0.2",
+  "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",
+    "offline",
+    "storage",
+    "browser-storage",
+    "web-storage",
+    "object-store",
+    "key-value",
+    "id",
+    "persist",
+    "threads",
+    "workers",
+    "shared"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false
+}

package/src/index.d.ts

@@ -0,0 +1,19 @@
+export type UUIDv4 = `${string}-${string}-${string}-${string}-${string}`;
+
+export type StoredObject = { id: UUIDv4 } & Record<string, unknown>;
+
+export class OfflineStorage {
+  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.
+   */
+  delete(id: UUIDv4): Promise<void>;
+}

package/src/index.js

@@ -0,0 +1,81 @@
+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();
+  }
+
+  /**
+   * @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}`));
+    });
+  }
+}

package/src/types.d.ts

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