@lunora/replica 1.0.0-alpha.12 → 1.0.0-alpha.121

package/README.md

@@ -112,9 +112,11 @@ 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",
-    schema: "1.0",
+    timestamp: Date.now(),
     changes: [{ type: "insert", data: { id: "1", title: "hello", done: false } }],
 });
 
@@ -140,7 +142,9 @@ machine, and pushes the resulting diffs to the mirror:
 import { EventsSync } from "@lunora/replica";
 
 const sync = new EventsSync({
-    fetchEventsSince: (seq) => eventLogClient.getSince(seq),
+    // `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 */
     },
@@ -160,15 +164,23 @@ 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.
+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 todos = useLocalQuery<{ id: string; title: string; done: boolean }>(mirror, "SELECT id, title, done FROM todos WHERE done = ?", [false]);
+    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>;
@@ -189,14 +201,47 @@ React 18+ concurrent features and Suspense-based frameworks (Next.js, Remix).
 
 ## EventLogDO
 
-A Durable Object that persists the event log to DO SQLite storage:
+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" } }]);
 
-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 });
+// 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

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

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.mjs";
+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).
@@ -22,6 +22,7 @@ declare const createBetterSqlite3Adapter: (database: {
     run: (params?: unknown[]) => {
       lastInsertRowid: number | bigint;
     };
+    safeIntegers: (toggle?: boolean) => unknown;
   };
   transaction: (function_: () => void) => () => void;
 }) => SqliteAdapter;

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

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.js";
+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).
@@ -22,6 +22,7 @@ declare const createBetterSqlite3Adapter: (database: {
     run: (params?: unknown[]) => {
       lastInsertRowid: number | bigint;
     };
+    safeIntegers: (toggle?: boolean) => unknown;
   };
   transaction: (function_: () => void) => () => void;
 }) => SqliteAdapter;

package/dist/adapters/better-sqlite3.mjs

@@ -1 +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};
+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

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.mjs";
+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).
@@ -10,18 +10,13 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.mjs";
  * 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.
+ * `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&lt;string, unknown>[]`); otherwise (DDL/DML/BEGIN/
+ * 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: {
@@ -31,6 +26,5 @@ declare const createSqliteWasmAdapter: (database: {
     returnValue?: "resultRows";
     rowMode?: "object";
   }) => Record<string, unknown>[] | undefined;
-  selectValue: (sql: string, bind?: unknown[]) => unknown;
 }) => SqliteAdapter;
 export { createSqliteWasmAdapter };

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

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.js";
+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).
@@ -10,18 +10,13 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.js";
  * 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.
+ * `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&lt;string, unknown>[]`); otherwise (DDL/DML/BEGIN/
+ * 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: {
@@ -31,6 +26,5 @@ declare const createSqliteWasmAdapter: (database: {
     returnValue?: "resultRows";
     rowMode?: "object";
   }) => Record<string, unknown>[] | undefined;
-  selectValue: (sql: string, bind?: unknown[]) => unknown;
 }) => SqliteAdapter;
 export { createSqliteWasmAdapter };

package/dist/adapters/sqlite-wasm.mjs

@@ -1 +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};
+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

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.mjs";
+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
@@ -11,7 +11,9 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.mjs";
  */
 declare const createSqlJsAdapter: (database: {
   close: () => void;
-  exec: (sql: string, params?: unknown[]) => {
+  exec: (sql: string, params?: unknown[], config?: {
+    useBigInt?: boolean;
+  }) => {
     columns: string[];
     values: unknown[][];
   }[];

package/dist/adapters/sqljs.d.ts

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.js";
+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
@@ -11,7 +11,9 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.js";
  */
 declare const createSqlJsAdapter: (database: {
   close: () => void;
-  exec: (sql: string, params?: unknown[]) => {
+  exec: (sql: string, params?: unknown[], config?: {
+    useBigInt?: boolean;
+  }) => {
     columns: string[];
     values: unknown[][];
   }[];

package/dist/adapters/sqljs.mjs

@@ -1 +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};
+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};