live-cache 0.2.2 → 0.2.4

package/README.md

@@ -14,6 +14,12 @@ A lightweight, type-safe client-side database library for JavaScript written in
 - ♻️ Pluggable invalidation strategies (timeouts, focus, websockets)
 - 🎨 Beautiful examples included
 
+## Examples
+
+See the `examples/` folder for ready-to-run demos:
+- `examples/react`: PokéAPI explorer built with controllers + `useController`
+- `examples/vanilla-js`: Simple browser demo using the UMD build
+
 ## Installation
 
 ```bash
@@ -132,17 +138,29 @@ Use `Controller<T, Name>` for **server-backed** resources: it wraps a `Collectio
 
 `commit()` is the important part: it **publishes** the latest snapshot to subscribers and **persists** the snapshot using the configured `StorageManager`.
 
+The `fetch(where?)` method can fetch all data or query-specific data based on the `where` parameter:
+
 ```ts
 import { Controller } from "live-cache";
 
 type User = { id: number; name: string };
 
 class UsersController extends Controller<User, "users"> {
-  async fetchAll(): Promise<[User[], number]> {
-    const res = await fetch("/api/users");
-    if (!res.ok) throw new Error("Failed to fetch users");
-    const data = (await res.json()) as User[];
-    return [data, data.length];
+  async fetch(where?: string | Partial<User>): Promise<[User[], number]> {
+    // Fetch all users if no where clause
+    if (!where) {
+      const res = await fetch("/api/users");
+      if (!res.ok) throw new Error("Failed to fetch users");
+      const data = (await res.json()) as User[];
+      return [data, data.length];
+    }
+
+    // Fetch specific user by id or name
+    const id = typeof where === "string" ? where : where.id;
+    const res = await fetch(`/api/users/${id}`);
+    if (!res.ok) throw new Error("Failed to fetch user");
+    const data = (await res.json()) as User;
+    return [[data], 1];
   }
 
   /**
@@ -151,7 +169,7 @@ class UsersController extends Controller<User, "users"> {
    */
   invalidate() {
     this.abort();
-    void this.refetch();
+    void this.update();
   }
 
   async renameUser(id: number, name: string) {
@@ -163,6 +181,68 @@ class UsersController extends Controller<User, "users"> {
 }
 ```
 
+### Real-world example: PokéAPI integration
+
+Here's a complete example from the `examples/react` demo showing how to build controllers for a public API:
+
+```ts
+import { Controller } from "live-cache";
+
+const API_BASE = "https://pokeapi.co/api/v2";
+
+// Controller for fetching the list of Pokémon
+class PokemonListController extends Controller<{ name: string; url: string }, "pokemonList"> {
+  constructor(name, options) {
+    super(name, options);
+    this.limit = 24;
+  }
+
+  async fetch() {
+    this.abort();
+    const response = await fetch(`${API_BASE}/pokemon?limit=${this.limit}`, {
+      signal: this.abortController?.signal,
+    });
+    if (!response.ok) throw new Error(`GET /pokemon failed (${response.status})`);
+    const data = await response.json();
+    return [data.results ?? [], data.count ?? 0];
+  }
+
+  invalidate() {
+    this.abort();
+    void this.update();
+  }
+}
+
+// Controller for fetching individual Pokémon details
+class PokemonDetailsController extends Controller<any, "pokemonDetails"> {
+  resolveQuery(where) {
+    if (!where) return null;
+    if (typeof where === "string") return where;
+    if (where.name) return String(where.name);
+    if (where.id !== undefined) return String(where.id);
+    return null;
+  }
+
+  async fetch(where) {
+    const query = this.resolveQuery(where);
+    if (!query) return [[], 0];
+
+    this.abort();
+    const response = await fetch(`${API_BASE}/pokemon/${query}`, {
+      signal: this.abortController?.signal,
+    });
+    if (!response.ok) throw new Error(`GET /pokemon/${query} failed (${response.status})`);
+    const data = await response.json();
+    return [[data], 1];
+  }
+
+  invalidate() {
+    this.abort();
+    void this.update(this.lastQuery);
+  }
+}
+```
+
 ### Persistence (`StorageManager`)
 
 Controllers persist snapshots through a `StorageManager` (array-of-models, not a JSON string).
@@ -213,6 +293,8 @@ Use `ContextProvider` to provide an `ObjectStore`, `useRegister()` to register c
 `controller.invalidator.registerInvalidation()` on mount and
 `controller.invalidator.unregisterInvalidation()` on unmount.
 
+### Basic example
+
 ```tsx
 import React from "react";
 import { ContextProvider, useRegister, useController } from "live-cache";
@@ -251,6 +333,40 @@ export default function Root() {
 }
 ```
 
+### Query-based fetching example
+
+You can pass a `where` clause to `useController()` to fetch specific data:
+
+```tsx
+import { useController } from "live-cache";
+import { useMemo } from "react";
+
+function PokemonDetails({ query }) {
+  // Convert query string to where clause
+  const where = useMemo(() => ({ name: query }), [query]);
+
+  const { data, loading, error } = useController(
+    "pokemonDetails",
+    where,
+    { initialise: !!where }
+  );
+
+  const pokemon = data[0];
+  if (loading) return <div>Loading Pokémon…</div>;
+  if (error) return <div>Error: {String(error)}</div>;
+  if (!pokemon) return null;
+
+  return (
+    <div>
+      <h2>{pokemon.name}</h2>
+      <img src={pokemon.sprites.front_default} alt={pokemon.name} />
+    </div>
+  );
+}
+```
+
+See `examples/react` for a complete PokéAPI explorer implementation with multiple components using controllers.
+
 ## Cache invalidation recipes
 
 These show **framework-agnostic** controller patterns and a **React** wiring example for each.

package/dist/index.cjs

@@ -1089,35 +1089,79 @@ class Transactions {
  */
 class IndexDbStorageManager extends StorageManager {
     constructor(options = {}) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         super((_a = options.prefix) !== null && _a !== void 0 ? _a : "live-cache:");
         this.dbPromise = null;
-        this.dbName = (_b = options.dbName) !== null && _b !== void 0 ? _b : "live-cache";
-        this.storeName = (_c = options.storeName) !== null && _c !== void 0 ? _c : "collections";
-        this.prefix = (_d = options.prefix) !== null && _d !== void 0 ? _d : "live-cache:";
+        this.dbPromises = new Map();
+        this.storeName = (_b = options.storeName) !== null && _b !== void 0 ? _b : "collections";
+        this.prefix = (_c = options.prefix) !== null && _c !== void 0 ? _c : "live-cache:";
+        this.useSameDatabase = (_d = options.useSameDatabase) !== null && _d !== void 0 ? _d : false;
+        this.dbName = (_e = options.dbName) !== null && _e !== void 0 ? _e : "live-cache";
     }
     key(name) {
         return `${this.prefix}${name}`;
     }
-    openDb() {
-        if (this.dbPromise)
+    getDbName(name) {
+        if (this.useSameDatabase) {
+            return this.dbName;
+        }
+        else {
+            // Create a separate database for each collection
+            const collectionName = name !== null && name !== void 0 ? name : this.storeName;
+            return `${this.dbName}-${collectionName}`;
+        }
+    }
+    openDb(name) {
+        if (this.useSameDatabase) {
+            if (this.dbPromise)
+                return this.dbPromise;
+            this.dbPromise = new Promise((resolve, reject) => {
+                if (typeof indexedDB === "undefined") {
+                    reject(new Error("indexedDB is not available in this environment"));
+                    return;
+                }
+                const dbName = this.getDbName();
+                const request = indexedDB.open(dbName, 1);
+                request.onupgradeneeded = () => {
+                    const db = request.result;
+                    if (!db.objectStoreNames.contains(this.storeName)) {
+                        db.createObjectStore(this.storeName);
+                    }
+                };
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => { var _a; return reject((_a = request.error) !== null && _a !== void 0 ? _a : new Error("Failed to open IndexedDB")); };
+            });
             return this.dbPromise;
-        this.dbPromise = new Promise((resolve, reject) => {
-            if (typeof indexedDB === "undefined") {
-                reject(new Error("indexedDB is not available in this environment"));
-                return;
+        }
+        else {
+            // Use separate database per collection
+            if (!name) {
+                throw new Error("Collection name is required when useSameDatabase is false");
             }
-            const request = indexedDB.open(this.dbName, 1);
-            request.onupgradeneeded = () => {
-                const db = request.result;
-                if (!db.objectStoreNames.contains(this.storeName)) {
-                    db.createObjectStore(this.storeName);
+            const existing = this.dbPromises.get(name);
+            if (existing)
+                return existing;
+            const promise = new Promise((resolve, reject) => {
+                if (typeof indexedDB === "undefined") {
+                    reject(new Error("indexedDB is not available in this environment"));
+                    return;
                 }
-            };
-            request.onsuccess = () => resolve(request.result);
-            request.onerror = () => { var _a; return reject((_a = request.error) !== null && _a !== void 0 ? _a : new Error("Failed to open IndexedDB")); };
-        });
-        return this.dbPromise;
+                const dbName = this.getDbName(name);
+                const request = indexedDB.open(dbName, 1);
+                request.onupgradeneeded = () => {
+                    const db = request.result;
+                    // When using separate databases, use a single object store named "documents"
+                    const storeName = "documents";
+                    if (!db.objectStoreNames.contains(storeName)) {
+                        db.createObjectStore(storeName);
+                    }
+                };
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => { var _a; return reject((_a = request.error) !== null && _a !== void 0 ? _a : new Error("Failed to open IndexedDB")); };
+            });
+            this.dbPromises.set(name, promise);
+            return promise;
+        }
     }
     idbGet(key) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1136,6 +1180,22 @@ class IndexDbStorageManager extends StorageManager {
             });
         });
     }
+    idbGetAll(name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const db = yield this.openDb(name);
+            const storeName = this.useSameDatabase ? this.storeName : "documents";
+            return yield new Promise((resolve, reject) => {
+                const tx = db.transaction(storeName, "readonly");
+                const store = tx.objectStore(storeName);
+                const req = store.getAll();
+                req.onsuccess = () => {
+                    const values = req.result;
+                    resolve(Array.isArray(values) ? values : []);
+                };
+                req.onerror = () => { var _a; return reject((_a = req.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB getAll failed")); };
+            });
+        });
+    }
     idbSet(key, value) {
         return __awaiter(this, void 0, void 0, function* () {
             const db = yield this.openDb();
@@ -1149,6 +1209,27 @@ class IndexDbStorageManager extends StorageManager {
             });
         });
     }
+    idbSetAll(name, models) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const db = yield this.openDb(name);
+            const storeName = this.useSameDatabase ? this.storeName : "documents";
+            yield new Promise((resolve, reject) => {
+                const tx = db.transaction(storeName, "readwrite");
+                const store = tx.objectStore(storeName);
+                // Clear existing documents first
+                store.clear();
+                // Store each document individually using _id as key
+                for (const model of models) {
+                    if (model && model._id) {
+                        store.put(model, model._id);
+                    }
+                }
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB setAll failed")); };
+                tx.onabort = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB setAll aborted")); };
+            });
+        });
+    }
     idbDelete(key) {
         return __awaiter(this, void 0, void 0, function* () {
             const db = yield this.openDb();
@@ -1162,50 +1243,105 @@ class IndexDbStorageManager extends StorageManager {
             });
         });
     }
+    idbDeleteAll(name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const db = yield this.openDb(name);
+            const storeName = this.useSameDatabase ? this.storeName : "documents";
+            yield new Promise((resolve, reject) => {
+                const tx = db.transaction(storeName, "readwrite");
+                const store = tx.objectStore(storeName);
+                store.clear();
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB deleteAll failed")); };
+                tx.onabort = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB deleteAll aborted")); };
+            });
+        });
+    }
     get(name) {
         return __awaiter(this, void 0, void 0, function* () {
-            const k = this.key(name);
-            try {
-                const value = yield this.idbGet(k);
-                return (value !== null && value !== void 0 ? value : []);
+            if (this.useSameDatabase) {
+                const k = this.key(name);
+                try {
+                    const value = yield this.idbGet(k);
+                    return (value !== null && value !== void 0 ? value : []);
+                }
+                catch (_a) {
+                    return [];
+                }
             }
-            catch (_a) {
-                return [];
+            else {
+                // When using separate databases, get all documents from the collection's database
+                try {
+                    const values = yield this.idbGetAll(name);
+                    return values;
+                }
+                catch (_b) {
+                    return [];
+                }
             }
         });
     }
     set(name, models) {
         return __awaiter(this, void 0, void 0, function* () {
-            const k = this.key(name);
             const value = Array.isArray(models) ? models : [];
-            try {
-                yield this.idbSet(k, value);
+            if (this.useSameDatabase) {
+                const k = this.key(name);
+                try {
+                    yield this.idbSet(k, value);
+                }
+                catch (_a) {
+                    // ignore write errors
+                }
             }
-            catch (_a) {
-                // ignore write errors
+            else {
+                // When using separate databases, store each document individually by _id
+                try {
+                    yield this.idbSetAll(name, value);
+                }
+                catch (_b) {
+                    // ignore write errors
+                }
             }
         });
     }
     delete(name) {
         return __awaiter(this, void 0, void 0, function* () {
-            const k = this.key(name);
-            try {
-                yield this.idbDelete(k);
+            if (this.useSameDatabase) {
+                const k = this.key(name);
+                try {
+                    yield this.idbDelete(k);
+                }
+                catch (_a) {
+                    // ignore delete errors
+                }
             }
-            catch (_a) {
-                // ignore delete errors
+            else {
+                // When using separate databases, clear all documents from the collection's database
+                try {
+                    yield this.idbDeleteAll(name);
+                }
+                catch (_b) {
+                    // ignore delete errors
+                }
             }
         });
     }
     getParams() {
         return __awaiter(this, void 0, void 0, function* () {
-            const db = yield this.openDb();
-            return new Promise((resolve, reject) => {
-                const req = db.transaction(this.storeName, "readonly").objectStore(this.storeName).getAllKeys();
-                const keys = req.result.map(x => x.toString().replace(this.prefix, ""));
-                req.onsuccess = () => resolve(keys);
-                req.onerror = () => { var _a; return reject((_a = req.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB get params failed")); };
-            });
+            if (this.useSameDatabase) {
+                const db = yield this.openDb();
+                return new Promise((resolve, reject) => {
+                    const req = db.transaction(this.storeName, "readonly").objectStore(this.storeName).getAllKeys();
+                    const keys = req.result.map(x => x.toString().replace(this.prefix, ""));
+                    req.onsuccess = () => resolve(keys);
+                    req.onerror = () => { var _a; return reject((_a = req.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB get params failed")); };
+                });
+            }
+            else {
+                // When using separate databases, return the list of database names (collections)
+                // This is a simplified implementation - in practice, you might want to track collections differently
+                return Array.from(this.dbPromises.keys());
+            }
         });
     }
 }
@@ -1326,16 +1462,14 @@ function useRegister(controller, store = getDefaultObjectStore()) {
  * ```
  */
 function useController(name, where, options) {
-    var _a, _b, _c, _d;
-    (_a = options === null || options === void 0 ? void 0 : options.initialise) !== null && _a !== void 0 ? _a : true;
+    var _a, _b;
     const optionalStore = options === null || options === void 0 ? void 0 : options.store;
-    const abortOnUnmount = (_b = options === null || options === void 0 ? void 0 : options.abortOnUnmount) !== null && _b !== void 0 ? _b : true;
-    const withInvalidation = (_c = options === null || options === void 0 ? void 0 : options.withInvalidation) !== null && _c !== void 0 ? _c : true;
+    const withInvalidation = (_a = options === null || options === void 0 ? void 0 : options.withInvalidation) !== null && _a !== void 0 ? _a : true;
     const [data, setData] = React.useState([]);
     const [loading, setLoading] = React.useState(false);
     const [error, setError] = React.useState(null);
     const defaultStore = React.useContext(context);
-    const store = (_d = optionalStore !== null && optionalStore !== void 0 ? optionalStore : defaultStore) !== null && _d !== void 0 ? _d : null;
+    const store = (_b = optionalStore !== null && optionalStore !== void 0 ? optionalStore : defaultStore) !== null && _b !== void 0 ? _b : null;
     if (!store) {
         throw Error("Store is not defined");
     }
@@ -1354,15 +1488,12 @@ function useController(name, where, options) {
             controller.invalidator.registerInvalidation();
         }
         void store.initialiseOnce(name, where);
-        // controller.initialise(where);
         return () => {
-            if (abortOnUnmount) {
-                controller.abort();
-            }
+            controller.abort();
             cleanup();
             controller.invalidator.unregisterInvalidation();
         };
-    }, [controller, where, abortOnUnmount, withInvalidation]);
+    }, [where, withInvalidation]);
     return { controller, data, loading, error };
 }