@lunora/replica 0.0.0 → 1.0.0-alpha.3

package/dist/packem_shared/local-mirror.d-Cd8tAg-W.d.ts

@@ -0,0 +1,439 @@
+import { S as SqliteAdapter } from "./types.d-BuAWjEY5.js";
+/**
+* Row-level change kind within a TableDiff.
+*
+* Each change represents one row that was inserted, updated, or deleted on
+* the server since the last sync tick.
+* @experimental
+*/
+type RowChange = {
+  data: Record<string, unknown>;
+  type: "insert";
+} | {
+  data: Record<string, unknown>;
+  id: string;
+  type: "update";
+} | {
+  id: string;
+  type: "delete";
+};
+/**
+* A scoped, ordered set of row changes for a single table.
+*
+* `TableDiff` is the unit of replication between the server and the local
+* SQLite mirror. The server pushes diffs over the poke protocol; the
+* client applies them via `applyDiff`.
+* @experimental
+*/
+interface TableDiff {
+  /** Ordered row changes — insert/update/delete, earliest first. */
+  readonly changes: ReadonlyArray<RowChange>;
+  /** Logical table name (matches the schema table name). */
+  readonly table: string;
+  /** Monotonic server timestamp (ms since epoch) when this diff was emitted. */
+  readonly timestamp: number;
+}
+/**
+* Create a {@link TableDiff} with a snapshot of the current time.
+* @experimental
+*/
+declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number) => TableDiff;
+/**
+* Return `true` when the diff contains no row changes.
+* @experimental
+*/
+declare const isDiffEmpty: (diff: TableDiff) => boolean;
+/**
+* Return the number of rows touched by the diff (inserts + updates + deletes).
+* @experimental
+*/
+declare const diffSize: (diff: TableDiff) => number;
+/**
+* Partition a {@link TableDiff} into three categories for batch processing.
+* @experimental
+*/
+declare const classifyChanges: (diff: TableDiff) => {
+  deletes: RowChange[];
+  inserts: RowChange[];
+  updates: RowChange[];
+};
+/**
+* Merge several diffs for the same table into one (ordering preserved).
+*
+* Returns `null` when the input list is empty.
+* @experimental
+*/
+declare const mergeDiffs: (diffs: ReadonlyArray<TableDiff>) => TableDiff | null;
+/**
+* Sequence-number types for the event log.
+*
+* Three namespaces match the vocabulary established by event-sourcing:
+*
+* | Namespace | Shape              | Producer                  | Consumer                     |
+* |-----------|--------------------|---------------------------|------------------------------|
+* | `Global`  | `number`           | `EventLog` / `EventLogDO` | Materializers, subscribers   |
+* | `Input`   | No seq (optimistic) | `defineEvents` factories  | `EventLog.append` / DO client|
+* | `Client`  | `{generation,seq}`  | _(future: rebase engine)_ | _(future: rebase-aware code)_|
+* @module
+*/
+/**
+* A server-authoritative (global) sequence number.
+*
+* Monotonically increasing, assigned by `EventLog` (in-memory) or
+* `EventLogDO` (Durable Object). All confirmed log entries carry a
+* `GlobalSeq`.
+* @experimental
+*/
+type GlobalSeq = number;
+/**
+* A client-originated composite sequence number designed to survive rebase.
+*
+* Carries the last-confirmed `global` seq, a monotonically increasing
+* `client` counter, and a `rebaseGeneration` that increments whenever the
+* client's local events are rebased onto a new upstream baseline.
+* @experimental
+*/
+interface ClientSeq {
+  /** Client-local monotonically increasing counter. */
+  readonly client: number;
+  /** The last-confirmed global sequence number. 0 for unconfirmed events. */
+  readonly global: number;
+  /** Incremented on every rebase. */
+  readonly rebaseGeneration: number;
+}
+/**
+* Discriminated union of all sequence-number types.
+* @experimental
+*/
+type Seq = GlobalSeq | ClientSeq;
+/**
+* Narrow `Seq` to `GlobalSeq`.
+* @experimental
+*/
+declare const isGlobalSeq: (seq: Seq) => seq is GlobalSeq;
+/**
+* Narrow `Seq` to `ClientSeq`.
+* @experimental
+*/
+declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
+/**
+* An event that has **not** yet been assigned a sequence number.
+*
+* Input events represent optimistic / command payloads before the server
+* confirms them. They carry `type`, `payload`, and `timestamp` but no
+* `seq` — the log assigns one on append.
+*
+* Create input events via `defineEvents` factories:
+*
+* ```ts
+* const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
+* // event: InputEvent&lt;"chat.messageSent", { channelId: string; text: string }>
+* ```
+* @experimental
+*/
+interface InputEvent<Type extends string = string, Payload = unknown> {
+  /** Arbitrary JSON-serialisable payload. */
+  readonly payload: Payload;
+  /** Millisecond timestamp (epoch) when the event was created. */
+  readonly timestamp: number;
+  /** Event type discriminator (e.g. `"chat.messageSent"`). */
+  readonly type: Type;
+}
+/**
+* Type guard: check whether `value` is an {@link InputEvent}.
+* @experimental
+*/
+declare const isInputEvent: (value: unknown) => value is InputEvent;
+/**
+* A single entry in the append-only {@link EventLog}.
+*
+* Entries are immutable once appended; the `seq` field is assigned
+* monotonically by the log and doubles as a watermark for catch-up
+* replication between tabs or service-worker instances.
+* @experimental
+*/
+interface EventLogEntry {
+  /**
+  * Globally-unique client identifier that originated this event.
+  * Set by clients that support offline / optimistic writes.
+  * `undefined` when the event was created server-side.
+  */
+  readonly clientId?: string;
+  /**
+  * The sequence number of the causal parent event.
+  *
+  * A {@link GlobalSeq} for events confirmed by the server (pointing
+  * to the previous confirmed event), or a {@link ClientSeq} for
+  * optimistic / offline events pointing to the local predecessor.
+  * `undefined` for the first event in a log.
+  */
+  readonly parentSeqNum?: Seq;
+  /** Arbitrary JSON-serialisable payload. */
+  readonly payload: unknown;
+  /** Monotonically increasing sequence number (0-based). A {@link GlobalSeq}. */
+  readonly seq: GlobalSeq;
+  /**
+  * Session identifier from the originating client.
+  * Paired with `clientId` to disambiguate concurrent sessions.
+  */
+  readonly sessionId?: string;
+  /**
+  * Optional table diffs that this event produced.
+  * When present, a consumer can re-play the event by applying the diffs
+  * to its local mirror without re-executing the originating mutation.
+  */
+  readonly tableDiffs?: ReadonlyArray<TableDiff>;
+  /** Millisecond timestamp (epoch) when the entry was appended. */
+  readonly timestamp: number;
+  /** Event type discriminator (e.g. "row-insert", "mutation-apply"). */
+  readonly type: string;
+}
+/**
+* Serialised snapshot of the log — used for persistence and transfer.
+* @experimental
+*/
+interface EventLogSnapshot {
+  readonly entries: ReadonlyArray<EventLogEntry>;
+  /** The sequence number of the last entry (head), or `null` for an empty log. */
+  readonly headSeq: GlobalSeq | null;
+  readonly nextSeq: number;
+}
+/**
+* Optional metadata that can accompany an appended event.
+* @experimental
+*/
+interface AppendOptions {
+  /** Globally-unique client identifier. */
+  readonly clientId?: string;
+  /**
+  * Causal parent sequence number.
+  * Automatically set to the previous entry's seq when omitted.
+  */
+  readonly parentSeqNum?: Seq;
+  /** Session identifier within the client. */
+  readonly sessionId?: string;
+}
+/**
+* An append-only, in-memory event log for local event sourcing.
+*
+* The log is the single source of truth for "what happened" and drives
+* catch-up replication: a new tab or service worker asks for entries
+* since its known `seq` watermark and re-applies them.
+* @remarks This class is intentionally **not** a full SQLite-backed log.
+* Persistence is the caller's responsibility (write the snapshot
+* to IndexedDB / OPFS via {@link EventLog#snapshot}).
+* @experimental
+*/
+declare class EventLog {
+  #private;
+  /**
+  * Append a new entry to the log.
+  *
+  * Accepts either an {@link InputEvent} (e.g. from a `defineEvents` factory)
+  * or the traditional `(type, payload, tableDiffs?)` triple.
+  * @returns The newly created entry (already written to the log).
+  */
+  append(event: InputEvent, options?: AppendOptions): EventLogEntry;
+  append(type: string, payload: unknown, tableDiffs?: ReadonlyArray<TableDiff>, options?: AppendOptions): EventLogEntry;
+  /**
+  * Atomically append multiple events to the log.
+  *
+  * All events are assigned sequential global sequence numbers and
+  * automatically wired as a causal chain (each event's `parentSeqNum`
+  * points to the previous event in the batch, or to the log head for
+  * the first event).
+  * @param events An array of events to commit atomically.
+  * @returns The newly created entries in order.
+  */
+  commitAll(events: ReadonlyArray<InputEvent | {
+    payload: unknown;
+    type: string;
+  }>): EventLogEntry[];
+  /**
+  * Replace the log contents with a previously captured snapshot.
+  * This is the restore counterpart of {@link EventLog#snapshot}.
+  * Restores `headSeq` from the snapshot so auto-parenting continues
+  * after restore.
+  */
+  load(snapshot: EventLogSnapshot): void;
+  /**
+  * Return **all** entries whose `seq >= sinceSeq`.
+  * Useful for catch-up: "give me everything since my last watermark".
+  */
+  getSince(sinceSeq: number): ReadonlyArray<EventLogEntry>;
+  /**
+  * Paginated read starting at `fromSeq`.
+  * @returns `{ entries, hasMore }` where `hasMore` is `true` when more
+  * entries exist beyond the requested page.
+  */
+  getFrom(fromSeq: number, limit?: number): {
+    entries: ReadonlyArray<EventLogEntry>;
+    hasMore: boolean;
+  };
+  /**
+  * Return all entries as a snapshot suitable for serialisation.
+  */
+  snapshot(): EventLogSnapshot;
+  /** Number of entries currently in the log. */
+  get size(): number;
+  /** The next sequence number that will be assigned. */
+  get nextSeq(): number;
+  /** Return `true` when there are no entries. */
+  get isEmpty(): boolean;
+  /**
+  * The sequence number of the last (most recent) entry, or `null`
+  * when the log is empty. Used internally for auto-parenting and
+  * exposed for consumers that need the causal head.
+  */
+  get headSeq(): GlobalSeq | null;
+  /** Remove all entries (primarily for testing). */
+  clear(): void;
+  /**
+  * Return an async generator that yields every entry starting from
+  * `fromSeq` (default `0` = all entries).
+  *
+  * Because `EventLog` is purely in-memory, the generator yields all
+  * matching entries synchronously on first iteration and then completes.
+  * For a streaming / push-based variant see {@link EventSource.events}.
+  */
+  events(fromSeq?: number): AsyncGenerator<EventLogEntry>;
+}
+/**
+* `MirrorTableDef` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
+interface MirrorTableDef {
+  /** Primary key column name (defaults to `"id"`). */
+  readonly primaryKey?: string;
+}
+/**
+* Options for constructing a {@link LocalMirror}.
+* @experimental
+*/
+interface LocalMirrorOptions {
+  /** Platform-specific SQLite adapter. */
+  readonly db: SqliteAdapter;
+  /**
+  * Table schemas the mirror should manage.
+  *
+  * On first use the mirror creates any missing tables automatically
+  * based on the columns observed in the first diff/row applied.
+  * If you want a fixed schema, pass it here with explicit column
+  * definitions in `columns`.
+  */
+  readonly tables?: Record<string, MirrorTableDef>;
+}
+/**
+* Local SQLite mirror that maintains a client-side replica of server
+* tables by applying {@link TableDiff} deltas.
+*
+* Usage:
+* ```ts
+* import { createSqlJsAdapter } from "@lunora/replica/adapters/sqljs";
+* import initSqlJs from "sql.js";
+*
+* const SQL = await initSqlJs();
+* const db = createSqlJsAdapter(new SQL.Database());
+*
+* const mirror = new LocalMirror({ db });
+*
+* // Apply a server diff:
+* mirror.applyDiff(someDiff);
+*
+* // Query locally:
+* const rows = mirror.query&lt;{ id: string; name: string }>(
+*   "SELECT id, name FROM users WHERE name LIKE ?",
+*   ["alice%"],
+* );
+* ```
+*/
+type ChangeSubscriber = () => void;
+/**
+* `LocalMirror` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
+declare class LocalMirror {
+  #private;
+  /**
+  * Convenience factory that creates a {@link LocalMirror} backed by a
+  * {@link createSqlJsAdapter sql.js adapter} without needing to import
+  * and wire sql.js manually.
+  *
+  * The caller provides an initialised sql.js database — this method wraps
+  * it in an adapter and constructs the mirror.
+  * @example
+  * ```ts
+  * import initSqlJs from "sql.js";
+  *
+  * const SQL = await initSqlJs();
+  * const mirror = LocalMirror.create(new SQL.Database(), {
+  *   tables: { todos: { primaryKey: "id" } },
+  * });
+  * ```
+  */
+  static create(sqlJsDatabase: {
+    close: () => void;
+    exec: (sql: string) => {
+      columns: string[];
+      values: unknown[][];
+    }[];
+    run: (sql: string, params?: unknown[]) => void;
+  }, options?: {
+    tables?: Record<string, MirrorTableDef>;
+  }): LocalMirror;
+  constructor(options: LocalMirrorOptions);
+  /**
+  * Subscribe to data-change notifications. Fires after every {@link applyDiff}.
+  * Returns an unsubscribe function.
+  */
+  onChange(callback: ChangeSubscriber): () => void;
+  /**
+  * The in-memory event log tracking every diff applied to this mirror.
+  * Use {@link EventLog.getSince} for catch-up replication across tabs
+  * or service-worker instances.
+  */
+  get eventLog(): EventLog;
+  /**
+  * The raw SQLite adapter. Advanced consumers (e.g. the React hook)
+  * can use it for ad-hoc queries or bulk operations.
+  */
+  get db(): SqliteAdapter;
+  /**
+  * Apply a server-side diff to the local SQLite mirror.
+  *
+  * The diff is applied in a transaction and recorded in the event log
+  * so other tabs or the SW can catch up.
+  */
+  applyDiff(diff: TableDiff): void;
+  /**
+  * Run an arbitrary SQL query against the local mirror and return
+  * typed results.
+  * @example
+  * ```ts
+  * const users = mirror.query<{ id: string; name: string }>(
+  *   "SELECT id, name FROM users WHERE active = ?",
+  *   [true],
+  * );
+  * ```
+  */
+  query<T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>): T[];
+  /**
+  * Delete every row from all known tables (preserves the event log
+  * and schema). Useful when re-syncing from scratch.
+  */
+  clearData(): void;
+  /**
+  * Dispose the mirror and close the database connection.
+  */
+  close(): void;
+  /**
+  * Register a table schema so the mirror can create the table on
+  * first use.
+  */
+  registerTable(name: string, definition: MirrorTableDef): void;
+  /**
+  * Return the list of mirrored table names.
+  */
+  get mirroredTables(): ReadonlyArray<string>;
+}
+export { AppendOptions as A, ClientSeq as C, EventLogEntry as E, GlobalSeq as G, InputEvent as I, LocalMirror as L, MirrorTableDef as M, RowChange as R, Seq as S, TableDiff as T, EventLog as a, EventLogSnapshot as b, LocalMirrorOptions as c, classifyChanges as d, createTableDiff as e, diffSize as f, isDiffEmpty as g, isGlobalSeq as h, isClientSeq as i, isInputEvent as j, mergeDiffs as m };

package/dist/packem_shared/subscribeToMirror-CiaM-nQ7.mjs

@@ -0,0 +1,45 @@
+const deriveTableName = (functionRef) => `fn_${functionRef.replaceAll(/[/:.]/g, "_")}`;
+const asRowArray = (data) => {
+  if (Array.isArray(data)) {
+    return data;
+  }
+  if (data !== null && typeof data === "object") {
+    return [data];
+  }
+  return [];
+};
+const subscribeToMirror = (client, mirror, functionRef, args, shardKey) => {
+  const tableName = deriveTableName(functionRef.__lunoraRef);
+  mirror.registerTable(tableName, {});
+  let knownIds = /* @__PURE__ */ new Set();
+  return client.subscribe(
+    functionRef,
+    args,
+    (data) => {
+      const rows = asRowArray(data);
+      const nextIds = /* @__PURE__ */ new Set();
+      const changes = [];
+      for (const row of rows) {
+        const record = row;
+        const rawId = record.id;
+        if (typeof rawId === "string" || typeof rawId === "number") {
+          nextIds.add(String(rawId));
+        }
+        changes.push({ type: "insert", data: record });
+      }
+      for (const id of knownIds) {
+        if (!nextIds.has(id)) {
+          changes.push({ type: "delete", id });
+        }
+      }
+      knownIds = nextIds;
+      if (changes.length === 0) {
+        return;
+      }
+      mirror.applyDiff({ table: tableName, changes, timestamp: Date.now() });
+    },
+    { shardKey }
+  );
+};
+
+export { subscribeToMirror };

package/dist/packem_shared/types.d-BuAWjEY5.d.mts

@@ -0,0 +1,24 @@
+/**
+* Abstract SQLite driver interface used by the local mirror.
+*
+* Each runtime (browser via sql.js, React Native via expo-sqlite,
+* Node via better-sqlite3) provides its own adapter implementing this
+* interface so the rest of `@lunora/replica` stays platform-agnostic.
+* @experimental
+*/
+interface SqliteAdapter {
+  /** Close the database connection. */
+  close: () => void;
+  /** Execute a SQL statement (with optional bound params). */
+  exec: (sql: string, params?: ReadonlyArray<unknown>) => void;
+  /** Return the id of the last inserted row. */
+  lastInsertRowId: () => number;
+  /**
+  * Execute a SQL statement and return the result rows.
+  * Columns can be accessed by index or by name.
+  */
+  query: <T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>) => T[];
+  /** Run all statements in a transaction. */
+  transaction: (function_: () => void) => void;
+}
+export { SqliteAdapter as S };

package/dist/packem_shared/types.d-BuAWjEY5.d.ts

@@ -0,0 +1,24 @@
+/**
+* Abstract SQLite driver interface used by the local mirror.
+*
+* Each runtime (browser via sql.js, React Native via expo-sqlite,
+* Node via better-sqlite3) provides its own adapter implementing this
+* interface so the rest of `@lunora/replica` stays platform-agnostic.
+* @experimental
+*/
+interface SqliteAdapter {
+  /** Close the database connection. */
+  close: () => void;
+  /** Execute a SQL statement (with optional bound params). */
+  exec: (sql: string, params?: ReadonlyArray<unknown>) => void;
+  /** Return the id of the last inserted row. */
+  lastInsertRowId: () => number;
+  /**
+  * Execute a SQL statement and return the result rows.
+  * Columns can be accessed by index or by name.
+  */
+  query: <T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>) => T[];
+  /** Run all statements in a transaction. */
+  transaction: (function_: () => void) => void;
+}
+export { SqliteAdapter as S };

package/dist/react.d.mts

@@ -0,0 +1,67 @@
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-BUeOe5KC.mjs";
+import "./packem_shared/types.d-BuAWjEY5.mjs";
+/**
+* Options for the {@link useLocalQuery} hook.
+* @experimental
+*/
+interface UseLocalQueryOptions {
+  /**
+  * Optional shard key (reserved for future use; currently unused).
+  *
+  * Intended for multi-mirror setups where a single app maintains multiple
+  * SQLite databases sharded by a key (e.g. user id, tenant id). Currently
+  * has no effect — the hook always queries the mirror passed as the first
+  * argument.
+  */
+  shardKey?: string;
+}
+/**
+* React hook that subscribes to a local SQLite query and returns
+* live-updating results whenever the mirror applies a diff.
+*
+* Uses `useSyncExternalStore` to subscribe to the mirror's `onChange`
+* callback — every diff triggers a re-query against the local SQLite.
+*
+* The hook works with React 18+ concurrent features, Suspense, and
+* server-side rendering. During SSR the same value is returned as on
+* the client (the mirror's current state at render time).
+* @param mirror The {@link LocalMirror} instance to query. Must have been
+* constructed with an {@link import("./adapters/types").SqliteAdapter}.
+* @param sql Parameterised SQL query string. Use `?` placeholders for
+* bound parameters (the adapter forwards them to the underlying SQLite
+* engine without rewriting).
+* @param params Optional positional bound parameters matching `?`
+* placeholders in `sql`.
+* @param _options Optional configuration (currently unused; reserved for
+* future features like shard key routing).
+* @returns An array of result rows typed via the generic parameter `T`, or
+* `undefined` if the query fails (e.g. the target table doesn't exist yet
+* because no matching diff has been applied). Treat `undefined` as a
+* "loading" or "no data yet" signal in your component.
+*
+* **Error handling**: The hook catches SQL errors internally and returns
+* `undefined`. Use a try-catch around `mirror.query(...)` directly if you
+* need finer-grained error diagnostics.
+* @example
+* ```tsx
+* import { useLocalQuery } from "@lunora/replica/react";
+* import { mirror } from "./mirror";
+*
+* function UserList() {
+*   const users = useLocalQuery<{ id: string; name: string }>(
+*     mirror,
+*     "SELECT id, name FROM fn_todos_list WHERE name LIKE ?",
+*     ["%alice%"],
+*   );
+*
+*   if (users === undefined) {
+*     return <p>Waiting for data…</p>;
+*   }
+*
+*   return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+* }
+* ```
+* @experimental
+*/
+declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
+export { UseLocalQueryOptions, useLocalQuery };

package/dist/react.d.ts

@@ -0,0 +1,67 @@
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-Cd8tAg-W.js";
+import "./packem_shared/types.d-BuAWjEY5.js";
+/**
+* Options for the {@link useLocalQuery} hook.
+* @experimental
+*/
+interface UseLocalQueryOptions {
+  /**
+  * Optional shard key (reserved for future use; currently unused).
+  *
+  * Intended for multi-mirror setups where a single app maintains multiple
+  * SQLite databases sharded by a key (e.g. user id, tenant id). Currently
+  * has no effect — the hook always queries the mirror passed as the first
+  * argument.
+  */
+  shardKey?: string;
+}
+/**
+* React hook that subscribes to a local SQLite query and returns
+* live-updating results whenever the mirror applies a diff.
+*
+* Uses `useSyncExternalStore` to subscribe to the mirror's `onChange`
+* callback — every diff triggers a re-query against the local SQLite.
+*
+* The hook works with React 18+ concurrent features, Suspense, and
+* server-side rendering. During SSR the same value is returned as on
+* the client (the mirror's current state at render time).
+* @param mirror The {@link LocalMirror} instance to query. Must have been
+* constructed with an {@link import("./adapters/types").SqliteAdapter}.
+* @param sql Parameterised SQL query string. Use `?` placeholders for
+* bound parameters (the adapter forwards them to the underlying SQLite
+* engine without rewriting).
+* @param params Optional positional bound parameters matching `?`
+* placeholders in `sql`.
+* @param _options Optional configuration (currently unused; reserved for
+* future features like shard key routing).
+* @returns An array of result rows typed via the generic parameter `T`, or
+* `undefined` if the query fails (e.g. the target table doesn't exist yet
+* because no matching diff has been applied). Treat `undefined` as a
+* "loading" or "no data yet" signal in your component.
+*
+* **Error handling**: The hook catches SQL errors internally and returns
+* `undefined`. Use a try-catch around `mirror.query(...)` directly if you
+* need finer-grained error diagnostics.
+* @example
+* ```tsx
+* import { useLocalQuery } from "@lunora/replica/react";
+* import { mirror } from "./mirror";
+*
+* function UserList() {
+*   const users = useLocalQuery<{ id: string; name: string }>(
+*     mirror,
+*     "SELECT id, name FROM fn_todos_list WHERE name LIKE ?",
+*     ["%alice%"],
+*   );
+*
+*   if (users === undefined) {
+*     return <p>Waiting for data…</p>;
+*   }
+*
+*   return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+* }
+* ```
+* @experimental
+*/
+declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
+export { UseLocalQueryOptions, useLocalQuery };

package/dist/react.mjs

@@ -0,0 +1,15 @@
+import { useSyncExternalStore } from 'react';
+
+const useLocalQuery = (mirror, sql, params, _options) => {
+  const subscribe = (onStoreChange) => mirror.onChange(onStoreChange);
+  const getSnapshot = () => mirror.eventLog.size;
+  const getServerSnapshot = () => mirror.eventLog.size;
+  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  try {
+    return mirror.query(sql, params);
+  } catch {
+    return void 0;
+  }
+};
+
+export { useLocalQuery };