@lunora/replica 0.0.0 → 1.0.0-alpha.100

package/README.md

@@ -1,45 +1,255 @@
-# @lunora/replica
+<!-- START_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+<a href="https://www.anolilab.com/open-source" align="center">
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+  <img src="__assets__/package-og.svg" alt="replica" />
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+</a>
 
-## Purpose
+<h3 align="center">Local-first replica runtime + local SQLite mirror for Lunora</h3>
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@lunora/replica`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+<!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## What is OIDC Trusted Publishing?
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+<br />
 
-## Setup Instructions
+<div align="center">
 
-To properly configure OIDC trusted publishing for this package:
+[![typescript-image][typescript-badge]][typescript-url]
+[![FSL-1.1-Apache-2.0 licence][license-badge]][license]
+[![npm version][npm-version-badge]][npm-version]
+[![npm downloads][npm-downloads-badge]][npm-downloads]
+[![PRs Welcome][prs-welcome-badge]][prs-welcome]
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+</div>
 
-## DO NOT USE THIS PACKAGE
+---
+
+<div align="center">
+    <p>
+        <sup>
+            Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
+        </sup>
+    </p>
+</div>
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+---
 
-## More Information
+Local-first replica runtime and local SQLite mirror for [Lunora](https://lunora.sh).
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+**Events layer** — derive state from an append-only event log via reducers, persist
+events through a Durable Object, and subscribe to typed events.
 
----
+**Local mirror** — a client-side SQLite mirror that maintains a replica
+of server tables by applying typed row-level diffs. Choose the SQLite backend
+that fits your runtime:
 
-**Maintained for OIDC setup purposes only**
+| Backend                 | Entry point                               | Runtime                        |
+| ----------------------- | ----------------------------------------- | ------------------------------ |
+| sql.js (WASM)           | `@lunora/replica/adapters/sqljs`          | Browser, Node, Service Workers |
+| better-sqlite3 (native) | `@lunora/replica/adapters/better-sqlite3` | Node.js                        |
+| @sqlite.org/sqlite-wasm | `@lunora/replica/adapters/sqlite-wasm`    | Browser, Node (official WASM)  |
+| Custom                  | Write your own `SqliteAdapter`            | Any                            |
+
+## Install
+
+```bash
+pnpm add @lunora/replica
+# Choose one SQLite backend:
+pnpm add sql.js                       # browser + Node (WASM)
+pnpm add better-sqlite3              # Node.js only (native)
+pnpm add @sqlite.org/sqlite-wasm     # browser (official WASM)
+# @lunora/server is optional — needed only for the EventLogDO:
+pnpm add @lunora/server
+```
+
+## Exports
+
+| Entry point                               | Contents                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@lunora/replica`                         | `EventSource`, `EventEmitter`, `defineEvents`, `defineMaterializer`, `EventLogDO`, `EventLogDOClient`, `SubscriptionManager`, `InMemorySnapshotStore`, `eventsContext`, `LocalMirror`, `EventLog`, `EventsSync`, `subscribeToMirror`, `applyDiff`, `TableDiff` helpers, `createSqlJsAdapter`, `createBetterSqlite3Adapter`, `createSqliteWasmAdapter` |
+| `@lunora/replica/react`                   | `useLocalQuery` React hook                                                                                                                                                                                                                                                                                                                            |
+| `@lunora/replica/adapters/sqljs`          | `createSqlJsAdapter` (sql.js)                                                                                                                                                                                                                                                                                                                         |
+| `@lunora/replica/adapters/better-sqlite3` | `createBetterSqlite3Adapter` (better-sqlite3)                                                                                                                                                                                                                                                                                                         |
+| `@lunora/replica/adapters/sqlite-wasm`    | `createSqliteWasmAdapter` (@sqlite.org/sqlite-wasm)                                                                                                                                                                                                                                                                                                   |
+
+## EventSource
+
+The core runtime — a typed reducer that derives state from an append-only log:
+
+```ts
+import { EventSource } from "@lunora/replica";
+
+interface MyState {
+    count: number;
+    items: string[];
+}
+
+const source = new EventSource<MyState>({ count: 0, items: [] }, (state, entry) => {
+    switch (entry.type) {
+        case "item:added":
+            return { count: state.count + 1, items: [...state.items, entry.payload as string] };
+        default:
+            return state;
+    }
+});
+
+source.applyEvent("item:added", "hello");
+console.log(source.state.count); // 1
+```
+
+## LocalMirror
+
+An SQLite mirror that applies typed row-level diffs. Create it with your
+chosen backend:
+
+```ts
+import initSqlJs from "sql.js";
+import { createSqlJsAdapter, LocalMirror } from "@lunora/replica";
+
+const SQL = await initSqlJs();
+const adapter = createSqlJsAdapter(new SQL.Database());
+const mirror = new LocalMirror({ db: adapter });
+
+// A diff is `{ table, timestamp, changes }` (plus an optional stable `id`).
+// `createTableDiff("todos", changes)` fills the timestamp and id for you.
+mirror.applyDiff({
+    table: "todos",
+    timestamp: Date.now(),
+    changes: [{ type: "insert", data: { id: "1", title: "hello", done: false } }],
+});
+
+const todos = mirror.query<{ id: string; title: string }>("SELECT id, title FROM todos");
+```
+
+For `better-sqlite3`:
+
+```ts
+import Database from "better-sqlite3";
+import { createBetterSqlite3Adapter, LocalMirror } from "@lunora/replica";
+
+const adapter = createBetterSqlite3Adapter(new Database(":memory:"));
+const mirror = new LocalMirror({ db: adapter });
+```
+
+### EventsSync
+
+Periodically polls a server-side event log, replays events through a state
+machine, and pushes the resulting diffs to the mirror:
+
+```ts
+import { EventsSync } from "@lunora/replica";
+
+const sync = new EventsSync({
+    // `getSince` answers ONE bounded page; EventsSync keeps calling with the
+    // advanced watermark until the log is exhausted.
+    fetchEventsSince: async (seq) => (await eventLogClient.getSince(seq)).entries,
+    applyEvents: (events) => {
+        /* feed events into your state machine */
+    },
+    getTableDiffs: () => {
+        /* compare state before/after → TableDiff[] */
+    },
+    mirror,
+    pollInterval: 3000,
+});
+
+sync.start(); // begin polling
+// sync.sync(); // one-shot sync
+// sync.stop(); // halt polling
+```
+
+See the [EventsSync JSDoc](src/sync-events.ts) for full API details.
+
+### useLocalQuery (React)
+
+Live-updating hook that re-queries the mirror whenever a diff is applied. It
+returns a discriminated union — `{ data }` on success, `{ error }` when the
+query fails (malformed SQL, or the table doesn't exist yet because no matching
+diff has been applied). A failure is never collapsed to `undefined`, so check
+`error` explicitly rather than reading a missing `data` as "still loading".
+
+```tsx
+import { useLocalQuery } from "@lunora/replica/react";
+
+function TodoList() {
+    const { data: todos, error } = useLocalQuery<{ id: string; title: string; done: boolean }>(mirror, "SELECT id, title, done FROM todos WHERE done = ?", [
+        false,
+    ]);
+
+    if (error) {
+        return <p>Query failed: {error.message}</p>;
+    }
+
+    if (todos === undefined) {
+        return <p>Waiting for data…</p>;
+    }
+
+    return (
+        <ul>
+            {todos.map((t) => (
+                <li key={t.id}>{t.title}</li>
+            ))}
+        </ul>
+    );
+}
+```
+
+The hook uses `useSyncExternalStore` under the hood, so it integrates with
+React 18+ concurrent features and Suspense-based frameworks (Next.js, Remix).
+
+## EventLogDO
+
+A Durable Object that persists the event log to DO SQLite storage.
+
+Re-export the class from your worker entry so Wrangler can find it:
+
+```ts
+// src/worker.ts
+export { EventLogDO } from "@lunora/replica";
+```
+
+Then declare the binding in `wrangler.jsonc`. The DO uses `state.storage.sql`,
+so its migration **must** use `new_sqlite_classes` — `new_classes` gives the
+instance a key-value store with no `.sql`, and every request fails at the first
+statement:
+
+```jsonc
+{
+    "durable_objects": {
+        "bindings": [{ "name": "EVENT_LOG_DO", "class_name": "EventLogDO" }],
+    },
+    "migrations": [{ "tag": "v1", "new_sqlite_classes": ["EventLogDO"] }],
+}
+```
+
+`EventLogDOClient` wraps the DO's `fetch()` RPC surface. Its only option is
+`fetch` — a function that dispatches a request to the instance you want, which
+is where the namespace and instance id are chosen:
+
+```ts
+const client = new EventLogDOClient({
+    fetch: (request) => env.EVENT_LOG_DO.get(env.EVENT_LOG_DO.idFromName("my-app")).fetch(request),
+});
+
+// Append takes an ARRAY of events and returns them with their assigned `seq`s.
+const [entry] = await client.append([{ type: "order:placed", payload: { orderId: "123" } }]);
+
+// Read back by sequence number — the log is append-only and ordered, so
+// there is no filter-by-type query. Every read is ONE bounded page (500
+// entries by default, 1000 max): walk `cursor` while `truncated` is true.
+const { entries, truncated, cursor } = await client.getSince(entry.seq);
+const page = await client.getSince(0, 50);
+const size = await client.getSize();
+```
+
+## Custom adapters
+
+See the [custom adapter guide](docs/guides/custom-adapter.mdx) for writing
+`SqliteAdapter` implementations for `expo-sqlite`, `bun:sqlite`, or any other
+SQLite runtime.
+
+## License
+
+[FSL-1.1-Apache-2.0](./LICENSE.md)

package/dist/adapters/better-sqlite3.d.mts

@@ -0,0 +1,29 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuLTPLaQ.mjs";
+/**
+ * Create a {@link SqliteAdapter} backed by [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
+ * (a synchronous SQLite3 binding for Node.js).
+ *
+ * The adapter takes a structural projection of better-sqlite3's `Database` so
+ * the package never imports from `better-sqlite3` directly — consumers install
+ * it themselves and pass in their database instance.
+ * @param database An already-initialised better-sqlite3 `Database` instance.
+ * @param database.close Tear down the database connection.
+ * @param database.exec Execute one or more SQL statements (no params, no results).
+ * @param database.prepare Prepare a SQL statement for repeated execution.
+ * @param database.transaction Wrap a function so its statements run in a transaction.
+ * @experimental
+ */
+declare const createBetterSqlite3Adapter: (database: {
+  close: () => void;
+  exec: (sql: string) => void;
+  prepare: (sql: string) => {
+    all: (params?: unknown[]) => unknown[];
+    get: (params?: unknown[]) => unknown;
+    run: (params?: unknown[]) => {
+      lastInsertRowid: number | bigint;
+    };
+    safeIntegers: (toggle?: boolean) => unknown;
+  };
+  transaction: (function_: () => void) => () => void;
+}) => SqliteAdapter;
+export { createBetterSqlite3Adapter };

package/dist/adapters/better-sqlite3.d.ts

@@ -0,0 +1,29 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuLTPLaQ.js";
+/**
+ * Create a {@link SqliteAdapter} backed by [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
+ * (a synchronous SQLite3 binding for Node.js).
+ *
+ * The adapter takes a structural projection of better-sqlite3's `Database` so
+ * the package never imports from `better-sqlite3` directly — consumers install
+ * it themselves and pass in their database instance.
+ * @param database An already-initialised better-sqlite3 `Database` instance.
+ * @param database.close Tear down the database connection.
+ * @param database.exec Execute one or more SQL statements (no params, no results).
+ * @param database.prepare Prepare a SQL statement for repeated execution.
+ * @param database.transaction Wrap a function so its statements run in a transaction.
+ * @experimental
+ */
+declare const createBetterSqlite3Adapter: (database: {
+  close: () => void;
+  exec: (sql: string) => void;
+  prepare: (sql: string) => {
+    all: (params?: unknown[]) => unknown[];
+    get: (params?: unknown[]) => unknown;
+    run: (params?: unknown[]) => {
+      lastInsertRowid: number | bigint;
+    };
+    safeIntegers: (toggle?: boolean) => unknown;
+  };
+  transaction: (function_: () => void) => () => void;
+}) => SqliteAdapter;
+export { createBetterSqlite3Adapter };

package/dist/adapters/better-sqlite3.mjs

@@ -0,0 +1 @@
+import{n as c}from"../packem_shared/int64-CCVxepl4.mjs";const p=t=>({exec(r,e){e&&e.length>0?t.prepare(r).run([...e]):t.exec(r)},query(r,e){const n=t.prepare(r);n.safeIntegers(!0);const o=e&&e.length>0?n.all([...e]):n.all();return c(o)},transaction(r){t.transaction(r)()},close(){t.close()}});export{p as createBetterSqlite3Adapter};

package/dist/adapters/sqlite-wasm.d.mts

@@ -0,0 +1,30 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuLTPLaQ.mjs";
+/**
+ * Create a {@link SqliteAdapter} backed by the [official SQLite Wasm](https://www.npmjs.com/package/@sqlite.org/sqlite-wasm)
+ * (a WebAssembly build of SQLite that runs in browsers and Node.js).
+ *
+ * The adapter takes a structural projection of the OO API (`sqlite3.oo1.DB`) so
+ * the package never imports from `@sqlite.org/sqlite-wasm` directly — consumers
+ * install it themselves and pass in their database instance.
+ *
+ * IMPORTANT (REPLICA-01): the real `oo1.DB.exec()` does NOT return sql.js's
+ * `{ columns, values }[]` result shape — with `rowMode: "object"` and
+ * `returnValue: "resultRows"` it returns the rows directly, as
+ * `Record<string, unknown>[]`. This adapter is written against that real shape.
+ * @param database An already-initialised `sqlite3.oo1.DB` instance.
+ * @param database.close Tear down the database connection.
+ * @param database.exec Execute SQL with optional bind params. With
+ * `{ returnValue: "resultRows", rowMode: "object" }` it returns the matched
+ * rows directly (`Record<string, unknown>[]`); otherwise (DDL/DML/BEGIN/
+ * COMMIT/ROLLBACK) its return value is unused here.
+ * @experimental
+ */
+declare const createSqliteWasmAdapter: (database: {
+  close: () => void;
+  exec: (sql: string, options?: {
+    bind?: unknown[];
+    returnValue?: "resultRows";
+    rowMode?: "object";
+  }) => Record<string, unknown>[] | undefined;
+}) => SqliteAdapter;
+export { createSqliteWasmAdapter };

package/dist/adapters/sqlite-wasm.d.ts

@@ -0,0 +1,30 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuLTPLaQ.js";
+/**
+ * Create a {@link SqliteAdapter} backed by the [official SQLite Wasm](https://www.npmjs.com/package/@sqlite.org/sqlite-wasm)
+ * (a WebAssembly build of SQLite that runs in browsers and Node.js).
+ *
+ * The adapter takes a structural projection of the OO API (`sqlite3.oo1.DB`) so
+ * the package never imports from `@sqlite.org/sqlite-wasm` directly — consumers
+ * install it themselves and pass in their database instance.
+ *
+ * IMPORTANT (REPLICA-01): the real `oo1.DB.exec()` does NOT return sql.js's
+ * `{ columns, values }[]` result shape — with `rowMode: "object"` and
+ * `returnValue: "resultRows"` it returns the rows directly, as
+ * `Record<string, unknown>[]`. This adapter is written against that real shape.
+ * @param database An already-initialised `sqlite3.oo1.DB` instance.
+ * @param database.close Tear down the database connection.
+ * @param database.exec Execute SQL with optional bind params. With
+ * `{ returnValue: "resultRows", rowMode: "object" }` it returns the matched
+ * rows directly (`Record<string, unknown>[]`); otherwise (DDL/DML/BEGIN/
+ * COMMIT/ROLLBACK) its return value is unused here.
+ * @experimental
+ */
+declare const createSqliteWasmAdapter: (database: {
+  close: () => void;
+  exec: (sql: string, options?: {
+    bind?: unknown[];
+    returnValue?: "resultRows";
+    rowMode?: "object";
+  }) => Record<string, unknown>[] | undefined;
+}) => SqliteAdapter;
+export { createSqliteWasmAdapter };

package/dist/adapters/sqlite-wasm.mjs

@@ -0,0 +1 @@
+import{n}from"../packem_shared/int64-CCVxepl4.mjs";const x=r=>({exec(o,e){e&&e.length>0?r.exec(o,{bind:[...e]}):r.exec(o)},query(o,e){const c=r.exec(o,{bind:e&&e.length>0?[...e]:void 0,returnValue:"resultRows",rowMode:"object"});return n(c??[])},transaction(o){r.exec("BEGIN");try{o(),r.exec("COMMIT")}catch(e){throw r.exec("ROLLBACK"),e}},close(){r.close()}});export{x as createSqliteWasmAdapter};

package/dist/adapters/sqljs.d.mts

@@ -0,0 +1,22 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuLTPLaQ.mjs";
+/**
+ * Create a {@link SqliteAdapter} backed by [sql.js](https://sql.js.org)
+ * (a WebAssembly build of SQLite that runs in browsers, Node, and
+ * React Native).
+ * @param database An already-initialised sql.js database instance.
+ * @param database.run Execute a parameterised SQL statement (no results).
+ * @param database.exec Execute SQL and return result rows.
+ * @param database.close Tear down the database connection.
+ * @experimental
+ */
+declare const createSqlJsAdapter: (database: {
+  close: () => void;
+  exec: (sql: string, params?: unknown[], config?: {
+    useBigInt?: boolean;
+  }) => {
+    columns: string[];
+    values: unknown[][];
+  }[];
+  run: (sql: string, params?: unknown[]) => void;
+}) => SqliteAdapter;
+export { createSqlJsAdapter };

package/dist/adapters/sqljs.d.ts

@@ -0,0 +1,22 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuLTPLaQ.js";
+/**
+ * Create a {@link SqliteAdapter} backed by [sql.js](https://sql.js.org)
+ * (a WebAssembly build of SQLite that runs in browsers, Node, and
+ * React Native).
+ * @param database An already-initialised sql.js database instance.
+ * @param database.run Execute a parameterised SQL statement (no results).
+ * @param database.exec Execute SQL and return result rows.
+ * @param database.close Tear down the database connection.
+ * @experimental
+ */
+declare const createSqlJsAdapter: (database: {
+  close: () => void;
+  exec: (sql: string, params?: unknown[], config?: {
+    useBigInt?: boolean;
+  }) => {
+    columns: string[];
+    values: unknown[][];
+  }[];
+  run: (sql: string, params?: unknown[]) => void;
+}) => SqliteAdapter;
+export { createSqlJsAdapter };

package/dist/adapters/sqljs.mjs

@@ -0,0 +1 @@
+import{n as i}from"../packem_shared/int64-CCVxepl4.mjs";const w=o=>({exec(e,r){r&&r.length>0?o.run(e,[...r]):o.exec(e)},query(e,r){const n=o.exec(e,r&&r.length>0?[...r]:void 0,{useBigInt:!0})[0];if(!n)return[];const u=n.columns,t=[];for(const s of n.values){const c={};for(const[l,f]of u.entries())c[f]=s[l];t.push(c)}return i(t)},transaction(e){o.run("BEGIN");try{e(),o.run("COMMIT")}catch(r){throw o.run("ROLLBACK"),r}},close(){o.close()}});export{w as createSqlJsAdapter};