live-cache 0.2.1 → 0.2.3

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/core/Controller.d.ts

@@ -46,19 +46,20 @@ export interface ControllerOptions<TVariable, TName extends string> {
     storageManager?: StorageManager<TVariable[]>;
     pageSize?: number;
     invalidator?: Invalidator<TVariable>;
-    initialiseOnMount?: boolean;
 }
 export default class Controller<TVariable, TName extends string> {
     name: TName;
     collection: Collection<TVariable, TName>;
     protected subscribers: Set<(model: ModelType<TVariable>[]) => void>;
-    protected storageManager: StorageManager<TVariable[]>;
+    storageManager: StorageManager<TVariable[]>;
     loading: boolean;
     error: unknown;
     total: number;
-    pageSize: number;
+    page: number;
+    limit: number;
     abortController: AbortController | null;
     invalidator: Invalidator<TVariable>;
+    initialised: boolean;
     /**
      * Abort any in-flight work owned by this controller (typically network fetches).
      *
@@ -66,15 +67,18 @@ export default class Controller<TVariable, TName extends string> {
      * pass `this.abortController.signal` to the next request.
      */
     abort(): void;
-    protected updateTotal(total: number): void;
-    protected updatePageSize(pageSize: number): void;
+    updateTotal(total: number): void;
+    updatePage(page: number): void;
+    updateLimit(limit: number): void;
     /**
      * Fetch the complete dataset for this controller.
      *
      * Subclasses must implement this. Return `[rows, total]` where `total` is the
      * total number of rows available on the backend (useful for pagination).
      */
-    fetchAll(): Promise<[TVariable[], number]>;
+    fetch(where?: string | Partial<TVariable>): Promise<[TVariable[], number]>;
+    nextPage(where?: string | Partial<TVariable>): Promise<void>;
+    previousPage(where?: string | Partial<TVariable>): Promise<void>;
     /**
      * Initialise (hydrate) the controller's collection.
      *
@@ -85,7 +89,7 @@ export default class Controller<TVariable, TName extends string> {
      *
      * A successful initialise ends with `commit()` so subscribers receive the latest snapshot.
      */
-    initialise(): Promise<void>;
+    initialise(where?: string | Partial<TVariable>): Promise<void>;
     /**
      * Subscribe to controller updates.
      *
@@ -99,13 +103,13 @@ export default class Controller<TVariable, TName extends string> {
      * unsubscribe();
      * ```
      */
-    publish(onChange: (data: ModelType<TVariable>[]) => void): () => boolean;
+    subscribe(onChange: (models: ModelType<TVariable>[]) => void): () => boolean;
     /**
      * Persist the latest snapshot and notify all subscribers.
      *
      * This is intentionally private: consumers should use `commit()` which computes the snapshot.
      */
-    private subscribe;
+    private publish;
     /**
      * Publish + persist the current snapshot.
      *
@@ -119,7 +123,7 @@ export default class Controller<TVariable, TName extends string> {
      *
      * Subclasses typically use this inside `invalidate()`.
      */
-    protected refetch(): Promise<void>;
+    update(where?: string | Partial<TVariable>): Promise<void>;
     /**
      * Invalidate the cache for this controller.
      *
@@ -144,5 +148,5 @@ export default class Controller<TVariable, TName extends string> {
      * @param storageManager - where snapshots are persisted (defaults to no-op)
      * @param pageSize - optional pagination hint (userland)
      */
-    constructor(name: TName, { storageManager, pageSize, invalidator, initialiseOnMount, }: ControllerOptions<TVariable, TName>);
+    constructor(name: TName, { storageManager, pageSize, invalidator, }: ControllerOptions<TVariable, TName>);
 }

package/dist/core/ObjectStore.d.ts

@@ -38,7 +38,7 @@ export default class ObjectStore {
     /**
      * Initialise a controller once per store, even if multiple callers request it.
      */
-    initialiseOnce<TVariable, TName extends string>(name: TName): Promise<void>;
+    initialiseOnce<TVariable, TName extends string>(name: TName, where?: string | Partial<TVariable>): Promise<void>;
 }
 /**
  * Returns a singleton store instance.

package/dist/index.cjs

@@ -529,14 +529,17 @@ class Controller {
     abort() {
         if (this.abortController) {
             this.abortController.abort();
+            this.abortController = null;
         }
-        this.abortController = new AbortController();
     }
     updateTotal(total) {
         this.total = total;
     }
-    updatePageSize(pageSize) {
-        this.pageSize = pageSize;
+    updatePage(page) {
+        this.page = page;
+    }
+    updateLimit(limit) {
+        this.limit = limit;
     }
     /**
      * Fetch the complete dataset for this controller.
@@ -544,11 +547,23 @@ class Controller {
      * Subclasses must implement this. Return `[rows, total]` where `total` is the
      * total number of rows available on the backend (useful for pagination).
      */
-    fetchAll() {
+    fetch(where) {
         return __awaiter(this, void 0, void 0, function* () {
             throw Error("Not Implemented");
         });
     }
+    nextPage(where) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.updatePage(this.page + 1);
+            yield this.update(where);
+        });
+    }
+    previousPage(where) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.updatePage(this.page - 1);
+            yield this.update(where);
+        });
+    }
     /**
      * Initialise (hydrate) the controller's collection.
      *
@@ -559,37 +574,41 @@ class Controller {
      *
      * A successful initialise ends with `commit()` so subscribers receive the latest snapshot.
      */
-    initialise() {
+    initialise(where) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            if (this.loading)
-                return;
+            this.abortController = new AbortController();
             // If the collection is not empty, return.
-            let data = this.collection.find().map((doc) => doc.toData());
+            let data = this.collection.find(where).map((doc) => doc.toData());
             if (data.length !== 0) {
-                return;
-            }
-            // If the collection is empty, check the storage manager.
-            data = (_a = (yield this.storageManager.get(this.name))) !== null && _a !== void 0 ? _a : [];
-            if (data.length !== 0) {
-                this.updateTotal(this.collection.find().length);
-                this.collection.insertMany(data);
+                this.updateTotal(data.length);
                 yield this.commit();
                 return;
             }
+            const fromStorage = yield this.storageManager.get(this.name);
+            if (fromStorage && fromStorage.length !== 0) {
+                const __collection = new Collection(this.name);
+                __collection.insertMany(fromStorage);
+                const __data = __collection.find(where).map(x => x.toData());
+                if (__data.length !== 0) {
+                    this.collection.insertMany(__data);
+                    this.updateTotal(__data.length);
+                    yield this.commit();
+                    return;
+                }
+            }
             // If the storage manager is empty, fetch the data from the server.
             try {
                 this.loading = true;
-                const [_data, total] = yield this.fetchAll();
+                const [_data, total] = yield this.fetch(where);
                 this.collection.insertMany(_data);
                 this.updateTotal(total);
-                yield this.commit();
             }
             catch (error) {
                 this.error = error;
             }
             finally {
                 this.loading = false;
+                yield this.commit();
             }
         });
     }
@@ -606,7 +625,7 @@ class Controller {
      * unsubscribe();
      * ```
      */
-    publish(onChange) {
+    subscribe(onChange) {
         this.subscribers.add(onChange);
         return () => this.subscribers.delete(onChange);
     }
@@ -615,12 +634,12 @@ class Controller {
      *
      * This is intentionally private: consumers should use `commit()` which computes the snapshot.
      */
-    subscribe(model) {
+    publish(models) {
         return __awaiter(this, void 0, void 0, function* () {
             // Persist the full cache snapshot for hydration.
             yield this.storageManager.set(this.name, this.collection.find().map((doc) => doc.toModel()));
             this.subscribers.forEach((sub) => {
-                sub(model);
+                sub(models);
             });
         });
     }
@@ -634,7 +653,7 @@ class Controller {
     commit() {
         return __awaiter(this, void 0, void 0, function* () {
             const models = this.collection.find().map((doc) => doc.toModel());
-            yield this.subscribe(models);
+            yield this.publish(models);
         });
     }
     /**
@@ -642,8 +661,13 @@ class Controller {
      *
      * Subclasses typically use this inside `invalidate()`.
      */
-    refetch() {
-        return this.initialise();
+    update(where) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const [response, total] = yield this.fetch(where);
+            this.collection.insertMany(response);
+            this.updateTotal(total);
+            yield this.commit();
+        });
     }
     /**
      * Invalidate the cache for this controller.
@@ -667,10 +691,11 @@ class Controller {
         void this.storageManager.delete(this.name);
         this.collection.clear();
         this.updateTotal(0);
-        this.updatePageSize(-1);
+        this.updatePage(0);
+        this.updateLimit(10);
         this.error = null;
         this.loading = false;
-        void this.subscribe([]);
+        void this.publish([]);
     }
     /**
      * Create a controller.
@@ -679,22 +704,22 @@ class Controller {
      * @param storageManager - where snapshots are persisted (defaults to no-op)
      * @param pageSize - optional pagination hint (userland)
      */
-    constructor(name, { storageManager = new DefaultStorageManager("live-cache:"), pageSize = -1, invalidator = new DefaultInvalidator(), initialiseOnMount = true, }) {
+    constructor(name, { storageManager = new DefaultStorageManager("live-cache:"), pageSize = 10, invalidator = new DefaultInvalidator(), }) {
         this.subscribers = new Set();
         this.loading = false;
         this.error = null;
         this.total = -1;
-        this.pageSize = -1;
+        this.page = 0;
+        this.limit = 10;
         this.abortController = null;
+        this.initialised = false;
         this.name = name;
         this.collection = new Collection(name);
         this.storageManager = storageManager;
-        this.pageSize = pageSize;
+        this.page = 0;
+        this.limit = pageSize;
         this.invalidator = invalidator;
         this.invalidator.bind(this.invalidate.bind(this));
-        if (initialiseOnMount) {
-            this.initialise();
-        }
     }
 }
 
@@ -947,12 +972,12 @@ class ObjectStore {
     /**
      * Initialise a controller once per store, even if multiple callers request it.
      */
-    initialiseOnce(name) {
+    initialiseOnce(name, where) {
         const controller = this.get(name);
         const existing = this.initialisePromises.get(controller);
         if (existing)
             return existing;
-        const promise = controller.initialise().finally(() => {
+        const promise = controller.initialise(where).finally(() => {
             if (this.initialisePromises.get(controller) === promise) {
                 this.initialisePromises.delete(controller);
             }
@@ -1302,7 +1327,7 @@ function useRegister(controller, store = getDefaultObjectStore()) {
  */
 function useController(name, where, options) {
     var _a, _b, _c, _d;
-    const initialise = (_a = options === null || options === void 0 ? void 0 : options.initialise) !== null && _a !== void 0 ? _a : true;
+    (_a = options === null || options === void 0 ? void 0 : options.initialise) !== null && _a !== void 0 ? _a : true;
     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;
@@ -1324,13 +1349,12 @@ function useController(name, where, options) {
         };
         // Prime state immediately.
         callback();
-        const cleanup = controller.publish(callback);
+        const cleanup = controller.subscribe(callback);
         if (withInvalidation) {
             controller.invalidator.registerInvalidation();
         }
-        if (initialise) {
-            void store.initialiseOnce(name);
-        }
+        void store.initialiseOnce(name, where);
+        // controller.initialise(where);
         return () => {
             if (abortOnUnmount) {
                 controller.abort();
@@ -1338,7 +1362,7 @@ function useController(name, where, options) {
             cleanup();
             controller.invalidator.unregisterInvalidation();
         };
-    }, [controller, where, initialise, abortOnUnmount, withInvalidation]);
+    }, [controller, where, abortOnUnmount, withInvalidation]);
     return { controller, data, loading, error };
 }
 
@@ -1361,7 +1385,7 @@ function useJoinController({ from, where, select }) {
             setData(join(from, where, select));
         };
         callback();
-        const cleanup = from.map((c) => c.publish(callback));
+        const cleanup = from.map((c) => c.subscribe(callback));
         return () => {
             cleanup.forEach((c) => c());
         };