@lunora/replica 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/react.d.mts

@@ -1,67 +1,94 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-BUeOe5KC.mjs";
-import "./packem_shared/types.d-BuAWjEY5.mjs";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-Cip3QuMf.mjs";
+import "./packem_shared/types.d-CkMkSwLJ.mjs";
 /**
-* Options for the {@link useLocalQuery} hook.
-* @experimental
-*/
+ * Result of {@link useLocalQuery} — a discriminated union so callers get a
+ * typed error instead of a swallowed `undefined`.
+ * @experimental
+ */
+type LocalQueryResult<T> = {
+  readonly data: T[];
+  readonly error?: undefined;
+} | {
+  readonly data?: undefined;
+  readonly error: Error;
+};
+/**
+ * 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.
-  */
+   * 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 };
+ * React hook that subscribes to a local SQLite query and returns
+ * live-updating results whenever the mirror applies a diff.
+ *
+ * Uses `useSyncExternalStore` with `getSnapshot` reading {@link LocalMirror.version}
+ * — a plain number, unconditionally `Object.is`-stable across calls with no
+ * mutation in between. The actual query runs in a `useMemo` keyed on
+ * `[mirror, version, sql, stableParamsKey(params)]`, so it only re-executes
+ * when the mirror actually advances (or `sql`/`params` change) — not on
+ * every unrelated re-render.
+ *
+ * This intentionally does NOT cache query results inside {@link LocalMirror}
+ * itself: an LRU-capped cache in the mirror core evicts still-mounted hooks'
+ * entries once more than the cap's worth of distinct live queries are open
+ * on one mirror, which makes `getSnapshot` return a fresh (non-identical)
+ * object on the next read — `useSyncExternalStore` then force-re-renders,
+ * re-inserts, evicts another entry, and so on without bound. Keying the
+ * external-store snapshot on the version primitive instead of a cached
+ * query result has no such cap, so it can't loop.
+ *
+ * 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 `{ data }` with the result rows typed via the generic parameter
+ * `T`, or `{ error }` when the query fails (e.g. malformed SQL, or the
+ * target table doesn't exist yet because no matching diff has been applied
+ * — that specific case surfaces as a "no such table" `Error`). Never
+ * collapses a failure to `undefined` — check `error` explicitly rather than
+ * treating a missing `data` as "still loading".
+ * @example
+ * ```tsx
+ * import { useLocalQuery } from "@lunora/replica/react";
+ * import { mirror } from "./mirror";
+ *
+ * function UserList() {
+ *   const { data: users, error } = useLocalQuery<{ id: string; name: string }>(
+ *     mirror,
+ *     "SELECT id, name FROM fn_todos_list WHERE name LIKE ?",
+ *     ["%alice%"],
+ *   );
+ *
+ *   if (error) {
+ *     return <p>Query failed: {error.message}</p>;
+ *   }
+ *
+ *   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) => LocalQueryResult<T>;
+export { type LocalQueryResult, type UseLocalQueryOptions, useLocalQuery };

package/dist/react.d.ts

@@ -1,67 +1,94 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-Cd8tAg-W.js";
-import "./packem_shared/types.d-BuAWjEY5.js";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-ByrYTq4z.js";
+import "./packem_shared/types.d-CkMkSwLJ.js";
 /**
-* Options for the {@link useLocalQuery} hook.
-* @experimental
-*/
+ * Result of {@link useLocalQuery} — a discriminated union so callers get a
+ * typed error instead of a swallowed `undefined`.
+ * @experimental
+ */
+type LocalQueryResult<T> = {
+  readonly data: T[];
+  readonly error?: undefined;
+} | {
+  readonly data?: undefined;
+  readonly error: Error;
+};
+/**
+ * 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.
-  */
+   * 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 };
+ * React hook that subscribes to a local SQLite query and returns
+ * live-updating results whenever the mirror applies a diff.
+ *
+ * Uses `useSyncExternalStore` with `getSnapshot` reading {@link LocalMirror.version}
+ * — a plain number, unconditionally `Object.is`-stable across calls with no
+ * mutation in between. The actual query runs in a `useMemo` keyed on
+ * `[mirror, version, sql, stableParamsKey(params)]`, so it only re-executes
+ * when the mirror actually advances (or `sql`/`params` change) — not on
+ * every unrelated re-render.
+ *
+ * This intentionally does NOT cache query results inside {@link LocalMirror}
+ * itself: an LRU-capped cache in the mirror core evicts still-mounted hooks'
+ * entries once more than the cap's worth of distinct live queries are open
+ * on one mirror, which makes `getSnapshot` return a fresh (non-identical)
+ * object on the next read — `useSyncExternalStore` then force-re-renders,
+ * re-inserts, evicts another entry, and so on without bound. Keying the
+ * external-store snapshot on the version primitive instead of a cached
+ * query result has no such cap, so it can't loop.
+ *
+ * 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 `{ data }` with the result rows typed via the generic parameter
+ * `T`, or `{ error }` when the query fails (e.g. malformed SQL, or the
+ * target table doesn't exist yet because no matching diff has been applied
+ * — that specific case surfaces as a "no such table" `Error`). Never
+ * collapses a failure to `undefined` — check `error` explicitly rather than
+ * treating a missing `data` as "still loading".
+ * @example
+ * ```tsx
+ * import { useLocalQuery } from "@lunora/replica/react";
+ * import { mirror } from "./mirror";
+ *
+ * function UserList() {
+ *   const { data: users, error } = useLocalQuery<{ id: string; name: string }>(
+ *     mirror,
+ *     "SELECT id, name FROM fn_todos_list WHERE name LIKE ?",
+ *     ["%alice%"],
+ *   );
+ *
+ *   if (error) {
+ *     return <p>Query failed: {error.message}</p>;
+ *   }
+ *
+ *   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) => LocalQueryResult<T>;
+export { type LocalQueryResult, type UseLocalQueryOptions, useLocalQuery };

package/dist/react.mjs

@@ -1,15 +1 @@
-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 };
+import{useSyncExternalStore as c,useMemo as u}from"react";const y=r=>JSON.stringify(r??[],(o,t)=>typeof t=="bigint"?`${t.toString()}n`:t),f=(r,o,t,g)=>{const s=n=>r.onChange(n),e=()=>r.version,a=c(s,e,e),i=y(t);return u(()=>{try{return{data:r.query(o,t)}}catch(n){return{error:n instanceof Error?n:new Error(String(n))}}},[r,a,o,i])};export{f as useLocalQuery};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/replica",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.41",
   "description": "Local-first replica runtime + local SQLite mirror for Lunora",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/EventEmitter-CMZfct03.mjs

@@ -1,92 +0,0 @@
-class EventEmitter {
-  #listeners = /* @__PURE__ */ new Map();
-  #wildcardListeners = /* @__PURE__ */ new Set();
-  // ── Registration ──────────────────────────────────────────────────
-  /**
-   * Register a handler for a specific event type.
-   * @returns An unsubscribe function (equivalent to calling {@link off}).
-   */
-  on(event, handler) {
-    let set = this.#listeners.get(event);
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      this.#listeners.set(event, set);
-    }
-    set.add(handler);
-    return () => {
-      this.off(event, handler);
-    };
-  }
-  /**
-   * Remove a previously registered handler.
-   */
-  off(event, handler) {
-    this.#listeners.get(event)?.delete(handler);
-  }
-  /**
-   * Register a wildcard handler that fires for **every** event type.
-   * @returns An unsubscribe function.
-   */
-  onAny(handler) {
-    this.#wildcardListeners.add(handler);
-    return () => {
-      this.#wildcardListeners.delete(handler);
-    };
-  }
-  /**
-   * Remove a wildcard handler.
-   */
-  offAny(handler) {
-    this.#wildcardListeners.delete(handler);
-  }
-  // ── Emission ──────────────────────────────────────────────────────
-  /**
-   * Emit an event. All registered handlers (typed + wildcard) are invoked
-   * synchronously. Exceptions from handlers are caught and silently
-   * swallowed — they **must not** break the emitter loop.
-   * @returns `true` if at least one handler was called.
-   */
-  emit(event, payload) {
-    let called = false;
-    const typed = this.#listeners.get(event);
-    if (typed) {
-      for (const handler of typed) {
-        try {
-          handler(payload);
-          called = true;
-        } catch {
-        }
-      }
-    }
-    for (const handler of this.#wildcardListeners) {
-      try {
-        handler(event, payload);
-        called = true;
-      } catch {
-      }
-    }
-    return called;
-  }
-  // ── Introspection ─────────────────────────────────────────────────
-  /**
-   * Return `true` when at least one listener is registered for `event`.
-   */
-  hasListeners(event) {
-    return (this.#listeners.get(event)?.size ?? 0) > 0 || this.#wildcardListeners.size > 0;
-  }
-  /**
-   * Return the number of typed listeners for a specific event.
-   */
-  listenerCount(event) {
-    return this.#listeners.get(event)?.size ?? 0;
-  }
-  /**
-   * Remove all listeners.
-   */
-  clear() {
-    this.#listeners.clear();
-    this.#wildcardListeners.clear();
-  }
-}
-
-export { EventEmitter };

package/dist/packem_shared/EventLog-zMy7AYP4.mjs

@@ -1,162 +0,0 @@
-class EventLog {
-  #entries = [];
-  #nextSeq = 0;
-  // eslint-disable-next-line unicorn/no-null -- public contract uses `null` for an empty log head
-  #headSeq = null;
-  append(typeOrEvent, payload, tableDiffs, options) {
-    const type = typeof typeOrEvent === "string" ? typeOrEvent : typeOrEvent.type;
-    const pl = typeof typeOrEvent === "string" ? payload : typeOrEvent.payload;
-    let diffs;
-    let resolvedOptions;
-    if (typeof typeOrEvent === "string") {
-      diffs = tableDiffs;
-      resolvedOptions = options;
-    } else {
-      diffs = void 0;
-      resolvedOptions = payload;
-    }
-    const parentSeqNumber = resolvedOptions?.parentSeqNum ?? this.#headSeq ?? void 0;
-    const seq = this.#nextSeq;
-    this.#nextSeq += 1;
-    const entry = {
-      seq,
-      type,
-      payload: pl,
-      timestamp: Date.now(),
-      tableDiffs: diffs,
-      clientId: resolvedOptions?.clientId,
-      sessionId: resolvedOptions?.sessionId,
-      parentSeqNum: parentSeqNumber
-    };
-    this.#entries.push(entry);
-    this.#headSeq = entry.seq;
-    return entry;
-  }
-  /**
-   * 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) {
-    if (events.length === 0) {
-      return [];
-    }
-    const entries = [];
-    for (const event of events) {
-      const { type } = event;
-      const payload = "payload" in event ? event.payload : void 0;
-      const ts = "timestamp" in event ? event.timestamp : Date.now();
-      const parentSeqNumber = entries.at(-1)?.seq ?? this.#headSeq ?? void 0;
-      const seq = this.#nextSeq;
-      this.#nextSeq += 1;
-      const entry = {
-        seq,
-        type,
-        payload,
-        timestamp: ts,
-        parentSeqNum: parentSeqNumber
-      };
-      this.#entries.push(entry);
-      entries.push(entry);
-    }
-    this.#headSeq = entries.at(-1)?.seq ?? this.#headSeq;
-    return entries;
-  }
-  /**
-   * 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) {
-    this.#entries = [...snapshot.entries];
-    this.#nextSeq = snapshot.nextSeq;
-    this.#headSeq = snapshot.headSeq;
-  }
-  // ── Queries ───────────────────────────────────────────────────────
-  /**
-   * Return **all** entries whose `seq >= sinceSeq`.
-   * Useful for catch-up: "give me everything since my last watermark".
-   */
-  getSince(sinceSeq) {
-    if (sinceSeq <= 0) {
-      return [...this.#entries];
-    }
-    const first = this.#entries.findIndex((entry) => entry.seq >= sinceSeq);
-    return first === -1 ? [] : this.#entries.slice(first);
-  }
-  /**
-   * Paginated read starting at `fromSeq`.
-   * @returns `{ entries, hasMore }` where `hasMore` is `true` when more
-   * entries exist beyond the requested page.
-   */
-  getFrom(fromSeq, limit = 50) {
-    const first = this.#entries.findIndex((entry) => entry.seq >= fromSeq);
-    if (first === -1) {
-      return { entries: [], hasMore: false };
-    }
-    const slice = this.#entries.slice(first, first + limit);
-    return {
-      entries: slice,
-      hasMore: first + limit < this.#entries.length
-    };
-  }
-  /**
-   * Return all entries as a snapshot suitable for serialisation.
-   */
-  snapshot() {
-    return {
-      entries: [...this.#entries],
-      nextSeq: this.#nextSeq,
-      headSeq: this.#headSeq
-    };
-  }
-  /** Number of entries currently in the log. */
-  get size() {
-    return this.#entries.length;
-  }
-  /** The next sequence number that will be assigned. */
-  get nextSeq() {
-    return this.#nextSeq;
-  }
-  /** Return `true` when there are no entries. */
-  get isEmpty() {
-    return this.#entries.length === 0;
-  }
-  /**
-   * 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() {
-    return this.#headSeq;
-  }
-  /** Remove all entries (primarily for testing). */
-  clear() {
-    this.#entries = [];
-    this.#nextSeq = 0;
-    this.#headSeq = null;
-  }
-  /**
-   * 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}.
-   */
-  // eslint-disable-next-line @typescript-eslint/require-await -- kept async so callers can uniformly `for await` over any event stream
-  async *events(fromSeq = 0) {
-    const entries = this.getSince(fromSeq);
-    for (const entry of entries) {
-      yield entry;
-    }
-  }
-}
-
-export { EventLog };