live-cache 0.1.0 → 0.2.0

package/README.md

@@ -10,6 +10,8 @@ A lightweight, type-safe client-side database library for JavaScript written in
 - ⚡ Fast indexed queries using hash-based lookups
 - 💾 Built-in serialization/deserialization for persistence
 - 🔍 MongoDB-like query interface
+- 🧰 Optimistic transactions with rollback support
+- ♻️ Pluggable invalidation strategies (timeouts, focus, websockets)
 - 🎨 Beautiful examples included
 
 ## Installation
@@ -147,10 +149,9 @@ class UsersController extends Controller<User, "users"> {
    * Example invalidation hook (you decide what invalidation means).
    * Common behavior is: abort in-flight fetch, clear/patch local cache, refetch, then commit.
    */
-  invalidate(): () => void {
+  invalidate() {
     this.abort();
     void this.refetch();
-    return () => {};
   }
 
   async renameUser(id: number, name: string) {
@@ -169,16 +170,48 @@ Controllers persist snapshots through a `StorageManager` (array-of-models, not a
 ```ts
 import { Controller, LocalStorageStorageManager } from "live-cache";
 
-const users = new UsersController(
-  "users",
-  true,
-  new LocalStorageStorageManager("my-app:")
-);
+const users = new UsersController("users", {
+  storageManager: new LocalStorageStorageManager("my-app:"),
+});
+// Other options: pageSize, invalidator, initialiseOnMount
+```
+
+### Transactions (optimistic updates)
+
+Transactions store collection snapshots so you can rollback failed mutations.
+
+```ts
+import { Controller, Transactions, LocalStorageStorageManager } from "live-cache";
+
+// Do this once at app startup.
+Transactions.createInstance(new LocalStorageStorageManager("my-app:tx:"));
+
+class UsersController extends Controller<User, "users"> {
+  async updateUser(id: number, patch: Partial<User>) {
+    const transaction = await Transactions.add(this.collection);
+    try {
+      this.collection.findOneAndUpdate({ id }, patch);
+      await this.commit();
+
+      // ...perform server request...
+
+      await Transactions.finish(this.name);
+    } catch (error) {
+      const previous = await Transactions.rollback(transaction, this.name);
+      this.collection.hydrate(previous.serialize());
+      await this.commit();
+      throw error;
+    }
+  }
+}
 ```
 
 ## React integration
 
 Use `ContextProvider` to provide an `ObjectStore`, `useRegister()` to register controllers, and `useController()` to subscribe to a controller.
+`useController()` automatically wires invalidators by calling
+`controller.invalidator.registerInvalidation()` on mount and
+`controller.invalidator.unregisterInvalidation()` on unmount.
 
 ```tsx
 import React from "react";
@@ -222,22 +255,32 @@ export default function Root() {
 
 These show **framework-agnostic** controller patterns and a **React** wiring example for each.
 
+### TODO: More invalidation strategies
+- [ ] Manual trigger
+- [ ] SWR on demand
+- [ ] Polling with backoff
+- [ ] ETag / If-Modified-Since
+- [ ] Server-Sent Events (SSE)
+- [ ] LRU-based invalidation
+- [ ] Background sync
+
 ### 1) Timeout-based cache invalidation (TTL)
 
 #### Framework-agnostic
 
 ```ts
-import { Controller } from "live-cache";
+import { Controller, TimeoutInvalidator } from "live-cache";
 
 type Post = { id: number; title: string };
 
 class PostsController extends Controller<Post, "posts"> {
   private ttlMs: number;
   private lastFetchedAt = 0;
-  private cleanupInvalidation: (() => void) | null = null;
 
   constructor(name: "posts", ttlMs = 30_000) {
-    super(name);
+    super(name, {
+      invalidator: new TimeoutInvalidator<Post>(ttlMs, { immediate: true }),
+    });
     this.ttlMs = ttlMs;
   }
 
@@ -249,31 +292,20 @@ class PostsController extends Controller<Post, "posts"> {
   }
 
   /**
-   * TTL invalidation lives here:
-   * - first call wires up the interval
-   * - subsequent calls perform the TTL check and revalidate if expired
+   * TTL invalidation logic lives here (TimeoutInvalidator triggers this).
    */
-  invalidate(): () => void {
-    if (!this.cleanupInvalidation) {
-      const id = window.setInterval(() => void this.invalidate(), this.ttlMs);
-      this.cleanupInvalidation = () => {
-        window.clearInterval(id);
-        this.cleanupInvalidation = null;
-      };
-    }
-
+  invalidate() {
     const now = Date.now();
     const fresh = this.lastFetchedAt && now - this.lastFetchedAt < this.ttlMs;
-    if (fresh) return this.cleanupInvalidation!;
+    if (fresh) return;
 
     this.abort();
     void this.refetch();
-    return this.cleanupInvalidation!;
   }
 }
 
 const posts = new PostsController("posts", 10_000);
-posts.invalidate(); // starts the interval + performs initial TTL check
+posts.invalidator.registerInvalidation(); // starts interval + initial check
 ```
 
 #### React
@@ -294,14 +326,33 @@ function PostsPage() {
 #### Framework-agnostic
 
 ```ts
-import { Controller } from "live-cache";
+import { Controller, Invalidator } from "live-cache";
 
 type Todo = { id: number; title: string };
 
+class SwrInvalidator<T> extends Invalidator<T> {
+  private revalidate = () => this.invalidator();
+
+  registerInvalidation() {
+    window.addEventListener("focus", this.revalidate);
+    window.addEventListener("online", this.revalidate);
+  }
+
+  unregisterInvalidation() {
+    window.removeEventListener("focus", this.revalidate);
+    window.removeEventListener("online", this.revalidate);
+  }
+}
+
 class TodosController extends Controller<Todo, "todos"> {
   private revalidateAfterMs = 30_000;
   private lastFetchedAt = 0;
-  private cleanupInvalidation: (() => void) | null = null;
+
+  constructor(name: "todos") {
+    super(name, {
+      invalidator: new SwrInvalidator<Todo>(),
+    });
+  }
 
   async fetchAll(): Promise<[Todo[], number]> {
     const res = await fetch("/api/todos");
@@ -321,29 +372,14 @@ class TodosController extends Controller<Todo, "todos"> {
     if (stale) void this.refetch();
   }
 
-  invalidate(): () => void {
-    // SWR-style invalidation wiring lives here:
-    // - first call wires up triggers (focus/online)
-    // - every call can also trigger a revalidation
-    if (!this.cleanupInvalidation) {
-      const revalidate = () => {
-        this.abort();
-        void this.refetch();
-      };
-      window.addEventListener("focus", revalidate);
-      window.addEventListener("online", revalidate);
-      this.cleanupInvalidation = () => {
-        window.removeEventListener("focus", revalidate);
-        window.removeEventListener("online", revalidate);
-        this.cleanupInvalidation = null;
-      };
-    }
-
+  invalidate() {
     this.abort();
     void this.refetch();
-    return this.cleanupInvalidation!;
   }
 }
+
+const todos = new TodosController("todos");
+todos.invalidator.registerInvalidation();
 ```
 
 #### React
@@ -372,6 +408,8 @@ function TodosPage() {
 #### Framework-agnostic
 
 ```ts
+import { Controller, Invalidator } from "live-cache";
+
 type InvalidationMsg =
   | { type: "invalidate"; controller: "users" }
   | { type: "patch-user"; id: number; name: string };
@@ -380,9 +418,6 @@ class UsersController extends Controller<
   { id: number; name: string },
   "users"
 > {
-  private ws: WebSocket | null = null;
-  private cleanupInvalidation: (() => void) | null = null;
-
   async fetchAll() {
     const res = await fetch("/api/users");
     const data = (await res.json()) as { id: number; name: string }[];
@@ -390,38 +425,46 @@ class UsersController extends Controller<
   }
 
   /**
-   * Websocket subscription lives here:
-   * - first call attaches the socket + listeners
-   * - incoming messages either trigger a refetch or apply a patch + commit
+   * Websocket message handling lives here (wiring lives in an Invalidator).
    */
-  invalidate(): () => void {
-    if (this.cleanupInvalidation) return this.cleanupInvalidation;
+  invalidate(msg?: InvalidationMsg) {
+    if (!msg) return;
+    if (msg.type === "invalidate" && msg.controller === "users") {
+      this.abort();
+      void this.refetch();
+      return;
+    }
 
+    if (msg.type === "patch-user") {
+      this.collection.findOneAndUpdate({ id: msg.id }, { name: msg.name });
+      void this.commit();
+    }
+  }
+}
+
+class WebsocketInvalidator extends Invalidator<InvalidationMsg> {
+  private ws: WebSocket | null = null;
+
+  registerInvalidation() {
     const ws = new WebSocket("wss://example.com/ws");
     this.ws = ws;
-    this.cleanupInvalidation = () => {
-      this.ws?.close();
-      this.ws = null;
-      this.cleanupInvalidation = null;
-    };
 
     ws.addEventListener("message", (evt) => {
       const msg = JSON.parse(String(evt.data)) as InvalidationMsg;
-
-      if (msg.type === "invalidate" && msg.controller === "users") {
-        this.abort();
-        void this.refetch();
-        return;
-      }
-
-      if (msg.type === "patch-user") {
-        this.collection.findOneAndUpdate({ id: msg.id }, { name: msg.name });
-        void this.commit();
-      }
+      this.invalidator(msg);
     });
-    return this.cleanupInvalidation;
+  }
+
+  unregisterInvalidation() {
+    this.ws?.close();
+    this.ws = null;
   }
 }
+
+const usersController = new UsersController("users", {
+  invalidator: new WebsocketInvalidator(),
+});
+usersController.invalidator.registerInvalidation();
 ```
 
 #### React
@@ -473,7 +516,8 @@ const rows = useJoinController({
 
 For full details, see the TSDoc on the exported APIs.
 
-- **Core**: `Collection`, `Document`, `Controller`, `ObjectStore`, `StorageManager`, `DefaultStorageManager`, `join`
+- **Core**: `Collection`, `Document`, `Controller`, `ObjectStore`, `StorageManager`, `DefaultStorageManager`, `join`, `Transactions`
+- **Invalidation**: `Invalidator`, `DefaultInvalidator`, `TimeoutInvalidator`
 - **Storage managers**: `LocalStorageStorageManager`, `IndexDbStorageManager`
 - **React**: `ContextProvider`, `useRegister`, `useController`, `useJoinController`
 

package/dist/core/Controller.d.ts

@@ -1,6 +1,7 @@
 import Collection from "./Collection";
 import { ModelType } from "./Document";
-import { DefaultStorageManager, StorageManager } from "./StorageManager";
+import { Invalidator } from "./Invalidator";
+import { StorageManager } from "./StorageManager";
 /**
  * Controller is the recommended integration layer for server-backed resources.
  *
@@ -41,16 +42,23 @@ import { DefaultStorageManager, StorageManager } from "./StorageManager";
  * }
  * ```
  */
+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>;
+    protected storageManager: StorageManager<TVariable[]>;
     loading: boolean;
     error: unknown;
     total: number;
     pageSize: number;
     abortController: AbortController | null;
+    invalidator: Invalidator<TVariable>;
     /**
      * Abort any in-flight work owned by this controller (typically network fetches).
      *
@@ -123,7 +131,7 @@ export default class Controller<TVariable, TName extends string> {
      * This method should return a cleanup function that unregisters any timers/listeners/sockets
      * created as part of invalidation wiring.
      */
-    invalidate(...data: TVariable[]): () => void;
+    invalidate(...data: TVariable[]): void;
     /**
      * Clear in-memory cache and delete persisted snapshot.
      * Publishes an empty snapshot to subscribers.
@@ -133,9 +141,8 @@ export default class Controller<TVariable, TName extends string> {
      * Create a controller.
      *
      * @param name - stable controller/collection name
-     * @param initialise - whether to run `initialise()` immediately
      * @param storageManager - where snapshots are persisted (defaults to no-op)
      * @param pageSize - optional pagination hint (userland)
      */
-    constructor(name: TName, initialise?: boolean, storageManager?: DefaultStorageManager<TVariable>, pageSize?: number);
+    constructor(name: TName, { storageManager, pageSize, invalidator, initialiseOnMount, }: ControllerOptions<TVariable, TName>);
 }

package/dist/core/Invalidator.d.ts

@@ -0,0 +1,11 @@
+export declare class Invalidator<TVariable> {
+    protected invalidator: (...data: TVariable[]) => void;
+    bind(invalidator: typeof this.invalidator): void;
+    registerInvalidation(): void;
+    unregisterInvalidation(): void;
+}
+export declare class DefaultInvalidator<TVariable> extends Invalidator<TVariable> {
+    bind(invalidator: (...data: TVariable[]) => void): void;
+    registerInvalidation(): void;
+    unregisterInvalidation(): () => void;
+}

package/dist/core/ObjectStore.d.ts

@@ -14,6 +14,7 @@ import Controller from "./Controller";
  */
 export default class ObjectStore {
     store: Map<string, Controller<any, any>>;
+    private initialisePromises;
     /**
      * Register a controller instance in this store.
      */
@@ -34,6 +35,10 @@ export default class ObjectStore {
      * This is equivalent to calling `controller.initialise()` for each controller.
      */
     initialise(): void;
+    /**
+     * Initialise a controller once per store, even if multiple callers request it.
+     */
+    initialiseOnce<TVariable, TName extends string>(name: TName): Promise<void>;
 }
 /**
  * Returns a singleton store instance.

package/dist/core/StorageManager.d.ts

@@ -1,4 +1,3 @@
-import { ModelType } from "./Document";
 /**
  * Storage adapter used by `Controller` to persist and hydrate snapshots.
  *
@@ -6,30 +5,35 @@ import { ModelType } from "./Document";
  * Implementations should be resilient: reads should return `[]` on failure.
  */
 export declare abstract class StorageManager<TVariable> {
+    prefix: string;
+    constructor(prefix: string);
     /**
      * Get a previously persisted snapshot for a controller name.
      *
      * @returns Array of models (each model includes `_id`)
      */
-    abstract get<T>(name: string): Promise<ModelType<T>[]>;
+    abstract get(name: string): Promise<TVariable | null>;
     /**
      * Persist a snapshot for a controller name.
      *
      * Controllers call this from `commit()`.
      */
-    abstract set<T>(name: string, models: ModelType<T>[]): Promise<void>;
+    abstract set(name: string, models: TVariable): Promise<void>;
     /**
      * Delete the persisted snapshot for a controller name.
      */
     abstract delete(name: string): Promise<void>;
+    abstract getParams(): Promise<string[]>;
 }
 /**
  * No-op storage manager.
  *
  * Useful in environments where you don’t want persistence (tests, ephemeral caches, etc).
  */
-export declare class DefaultStorageManager<TVariable> implements StorageManager<TVariable> {
-    get<T>(_name: string): Promise<ModelType<T>[]>;
-    set<T>(_name: string, _models: ModelType<T>[]): Promise<void>;
+export declare class DefaultStorageManager<TVariable> extends StorageManager<TVariable> {
+    constructor(prefix: string);
+    get(name: string): Promise<TVariable | null>;
+    set(name: string, models: TVariable): Promise<void>;
     delete(_name: string): Promise<void>;
+    getParams(): Promise<string[]>;
 }

package/dist/core/Transactions.d.ts

@@ -0,0 +1,20 @@
+import Collection from "./Collection";
+import { StorageManager } from "./StorageManager";
+declare class TransactionsInstance<TVariable, TName extends string> {
+    private storageManager;
+    constructor(storageManager: StorageManager<string>);
+    add<TVariable, TName extends string>(collection: Collection<TVariable, TName>): Promise<string>;
+    rollback(transaction_name: string, name: TName): Promise<Collection<TVariable, TName>>;
+    finish(name: TName): Promise<void>;
+    get<TVariable, TName extends string>(transaction_name: string, name: TName): Promise<Collection<TVariable, TName>>;
+}
+export default class Transactions {
+    static instance: TransactionsInstance<any, any>;
+    static createInstance(storageManager: StorageManager<string>): void;
+    static getInstance(): TransactionsInstance<any, any>;
+    static add<TVariable, TName extends string>(collection: Collection<TVariable, TName>): Promise<string>;
+    static rollback<TVariable, TName extends string>(transaction_name: string, name: TName): Promise<Collection<TVariable, TName>>;
+    static finish(name: string): Promise<void>;
+    static get<TVariable, TName extends string>(transaction_name: string, name: TName): Promise<Collection<TVariable, TName>>;
+}
+export {};