@lunora/replica 0.0.0 → 1.0.0-alpha.11

package/README.md

@@ -1,45 +1,210 @@
-# @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
+---
 
-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
+<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>
 
-## More Information
+---
 
-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)
+Local-first replica runtime and local SQLite mirror for [Lunora](https://lunora.sh).
 
----
+**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:
+
+| 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 });
+
+mirror.applyDiff({
+    table: "todos",
+    schema: "1.0",
+    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({
+    fetchEventsSince: (seq) => eventLogClient.getSince(seq),
+    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.
+Returns `undefined` when the query fails (e.g. table doesn't exist yet),
+and the result rows otherwise.
+
+```tsx
+import { useLocalQuery } from "@lunora/replica/react";
+
+function TodoList() {
+    const todos = useLocalQuery<{ id: string; title: string; done: boolean }>(mirror, "SELECT id, title, done FROM todos WHERE done = ?", [false]);
+
+    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:
+
+```ts
+export { EventLogDO } from "@lunora/replica";
+
+const client = new EventLogDOClient({ namespace: "my-app" });
+await client.append({ type: "order:placed", payload: { orderId: "123" } });
+const events = await client.query({ type: "order:placed", limit: 10 });
+```
+
+## 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
 
-**Maintained for OIDC setup purposes only**
+[FSL-1.1-Apache-2.0](./LICENSE.md)

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

@@ -0,0 +1,28 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.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;
+    };
+  };
+  transaction: (function_: () => void) => () => void;
+}) => SqliteAdapter;
+export { createBetterSqlite3Adapter };

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

@@ -0,0 +1,28 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.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;
+    };
+  };
+  transaction: (function_: () => void) => () => void;
+}) => SqliteAdapter;
+export { createBetterSqlite3Adapter };

package/dist/adapters/better-sqlite3.mjs

@@ -0,0 +1 @@
+const a=r=>({exec(e,t){t&&t.length>0?r.prepare(e).run([...t]):r.exec(e)},query(e,t){const n=r.prepare(e);return t&&t.length>0?n.all([...t]):n.all()},transaction(e){r.transaction(e)()},lastInsertRowId(){const e=r.prepare("SELECT last_insert_rowid() AS id").get();return Number(e?.id??-1)},close(){r.close()}});export{a as createBetterSqlite3Adapter};

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

@@ -0,0 +1,36 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.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; `lastInsertRowId` uses the driver's `selectValue()` convenience
+ * method (a single-scalar query helper) rather than parsing a result-row
+ * array.
+ * @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.
+ * @param database.selectValue Run a query and return the first column of the
+ * first row as a single scalar — used for `SELECT last_insert_rowid()`.
+ * @experimental
+ */
+declare const createSqliteWasmAdapter: (database: {
+  close: () => void;
+  exec: (sql: string, options?: {
+    bind?: unknown[];
+    returnValue?: "resultRows";
+    rowMode?: "object";
+  }) => Record<string, unknown>[] | undefined;
+  selectValue: (sql: string, bind?: unknown[]) => unknown;
+}) => SqliteAdapter;
+export { createSqliteWasmAdapter };

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

@@ -0,0 +1,36 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.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; `lastInsertRowId` uses the driver's `selectValue()` convenience
+ * method (a single-scalar query helper) rather than parsing a result-row
+ * array.
+ * @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.
+ * @param database.selectValue Run a query and return the first column of the
+ * first row as a single scalar — used for `SELECT last_insert_rowid()`.
+ * @experimental
+ */
+declare const createSqliteWasmAdapter: (database: {
+  close: () => void;
+  exec: (sql: string, options?: {
+    bind?: unknown[];
+    returnValue?: "resultRows";
+    rowMode?: "object";
+  }) => Record<string, unknown>[] | undefined;
+  selectValue: (sql: string, bind?: unknown[]) => unknown;
+}) => SqliteAdapter;
+export { createSqliteWasmAdapter };

package/dist/adapters/sqlite-wasm.mjs

@@ -0,0 +1 @@
+const o=c=>({exec(e,t){t&&t.length>0?c.exec(e,{bind:[...t]}):c.exec(e)},query(e,t){return c.exec(e,{bind:t&&t.length>0?[...t]:void 0,returnValue:"resultRows",rowMode:"object"})??[]},transaction(e){c.exec("BEGIN");try{e(),c.exec("COMMIT")}catch(t){throw c.exec("ROLLBACK"),t}},lastInsertRowId(){const e=c.selectValue("SELECT last_insert_rowid()");return typeof e=="number"?e:typeof e=="bigint"?Number(e):-1},close(){c.close()}});export{o as createSqliteWasmAdapter};

package/dist/adapters/sqljs.d.mts

@@ -0,0 +1,20 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.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[]) => {
+    columns: string[];
+    values: unknown[][];
+  }[];
+  run: (sql: string, params?: unknown[]) => void;
+}) => SqliteAdapter;
+export { createSqlJsAdapter };

package/dist/adapters/sqljs.d.ts

@@ -0,0 +1,20 @@
+import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.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[]) => {
+    columns: string[];
+    values: unknown[][];
+  }[];
+  run: (sql: string, params?: unknown[]) => void;
+}) => SqliteAdapter;
+export { createSqlJsAdapter };

package/dist/adapters/sqljs.mjs

@@ -0,0 +1 @@
+const h=n=>({exec(e,t){t&&t.length>0?n.run(e,[...t]):n.exec(e)},query(e,t){const r=(t&&t.length>0?n.exec(e,[...t]):n.exec(e))[0];if(!r)return[];const o=r.columns,s=[];for(const u of r.values){const c={};for(const[l,a]of o.entries())c[a]=u[l];s.push(c)}return s},transaction(e){n.run("BEGIN");try{e(),n.run("COMMIT")}catch(t){throw n.run("ROLLBACK"),t}},lastInsertRowId(){const e=n.exec("SELECT last_insert_rowid() AS id"),t=e[0];if(e.length===0||!t||t.values.length===0)return-1;const r=t.values[0];return!r||r.length===0?-1:Number(r[0])},close(){n.close()}});export{h as createSqlJsAdapter};