@lunora/replica 1.0.0-alpha.8 → 1.0.0-alpha.81

package/dist/packem_shared/{local-mirror.d-CyGOpUES.d.ts → local-mirror.d-CvNV3_gk.d.ts}

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "./types.d-CkMkSwLJ.js";
+import { S as SqliteAdapter } from "./types.d-BuLTPLaQ.js";
 /**
  * Row-level change kind within a TableDiff.
  *
@@ -140,7 +140,7 @@ declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
  *
  * ```ts
  * const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
- * // event: InputEvent<"chat.messageSent", { channelId: string; text: string }>
+ * // event: InputEvent<"chat.messageSent", { channelId: string; text: string }>
  * ```
  * @experimental
  */
@@ -381,15 +381,18 @@ interface LocalMirrorOptions {
   /** Platform-specific SQLite adapter. */
   readonly db: SqliteAdapter;
   /**
-   * Cap the mirror's internal {@link EventLog} to this many entries
-   * (REPLICA-06). Every applied diff is recorded in the log — with no cap,
-   * a long-running client accumulates one entry per diff forever.
+   * Cap the mirror's internal {@link EventLog} to this many entries.
+   * Every applied diff is recorded in the log, so an uncapped log grows by
+   * one entry (holding every changed row) per diff for the life of the
+   * mirror — a leak by construction on a long-lived client.
    *
-   * `undefined` (the default) preserves unbounded retention. Set this when
-   * catch-up replication only ever needs a bounded recent window; older
-   * entries are silently evicted (oldest-first) once the cap is exceeded.
-   * See {@link EventLog#truncateBelow} for caller-driven truncation tied to
-   * a snapshot instead.
+   * Defaults to {@link DEFAULT_MAX_EVENT_LOG_ENTRIES}. On overflow the
+   * OLDEST entries are dropped; nothing in the mirror replays its own log,
+   * so a drop loses nothing the mirror needs. A consumer that does replay
+   * it (`eventLog.getSince(watermark)` from another tab / service worker)
+   * detects a gap when the first returned entry's `seq` is above its
+   * watermark, and should re-seed from the mirror's rows (`query`) instead
+   * of applying the partial window.
    */
   readonly maxEventLogEntries?: number;
   /**
@@ -420,7 +423,7 @@ interface LocalMirrorOptions {
  * mirror.applyDiff(someDiff);
  *
  * // Query locally:
- * const rows = mirror.query&lt;{ id: string; name: string }>(
+ * const rows = mirror.query<{ id: string; name: string }>(
  *   "SELECT id, name FROM users WHERE name LIKE ?",
  *   ["alice%"],
  * );
@@ -504,8 +507,17 @@ declare class LocalMirror {
    */
   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.
+   * Delete every row from every data table in the adapter's database
+   * (preserves the event log and schema). Useful when re-syncing from scratch.
+   *
+   * **The mirror owns its database.** The sweep is `sqlite_master` minus the
+   * reserved prefixes, NOT {@link LocalMirror.mirroredTables} — a table this
+   * mirror never registered is cleared too, and `#reconcileSchemaVersion`
+   * DROPs on the same list. It cannot be narrowed to the registered set: that
+   * runs from the constructor, before any `applyDiff` has re-registered the
+   * tables a previous session persisted, and those are exactly the
+   * stale-schema tables it exists to drop. So hand the adapter a database
+   * dedicated to the mirror, never one that also holds your own tables.
    *
    * Notifies `onChange` subscribers and bumps {@link LocalMirror.version}
    * (REPLICA-09) even though nothing is appended to the event log — a
@@ -519,9 +531,14 @@ declare class LocalMirror {
   close(): void;
   /**
    * Register a table schema so the mirror can create the table on
-   * first use.
+   * first use. Merges into any definition already registered for `name`
+   * (from the constructor's `tables` or an earlier call), so a helper that
+   * registers `{}` just to make the table known does not erase a
+   * user-supplied `primaryKey`.
    */
   registerTable(name: string, definition: MirrorTableDef): void;
+  /** The primary-key column of a mirrored table (`"id"` unless registered otherwise). */
+  primaryKeyOf(table: string): string;
   /**
    * Return the list of mirrored table names.
    */

package/dist/packem_shared/subscribeToMirror-Cv24WiWj.mjs

@@ -0,0 +1 @@
+import{s as w}from"./wire-key-CU8KEXPo.mjs";const h=e=>`fn_${e.replaceAll(/[/:.]/g,"_")}`,m=e=>Array.isArray(e)?e:e!==null&&typeof e=="object"?[e]:[],M=(e,c,a,y,b)=>{const i=h(a.__lunoraRef);c.registerTable(i,{});const u=c.primaryKeyOf(i);let p=new Map;return e.subscribe(a,y,d=>{const r=new Map,f=new Map,o=[];for(const t of m(d)){const n=t,s=n[u];if(typeof s!="string"&&typeof s!="number"&&typeof s!="bigint"){o.push({type:"insert",data:n});continue}const l=String(s),g=w(n);r.set(l,g),f.set(l,n)}for(const[t,n]of r)p.get(t)!==n&&o.push({data:f.get(t),type:"insert"});for(const t of p.keys())r.has(t)||o.push({type:"delete",id:t});o.length>0&&c.applyDiff({table:i,changes:o,timestamp:Date.now()}),p=r},{shardKey:b})};export{M as subscribeToMirror};

package/dist/packem_shared/{types.d-CkMkSwLJ.d.mts → types.d-BuLTPLaQ.d.mts}

@@ -11,8 +11,6 @@ interface SqliteAdapter {
   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.

package/dist/packem_shared/{types.d-CkMkSwLJ.d.ts → types.d-BuLTPLaQ.d.ts}

@@ -11,8 +11,6 @@ interface SqliteAdapter {
   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.

package/dist/packem_shared/wire-key-CU8KEXPo.mjs

@@ -0,0 +1 @@
+const d=/["\\\u0000-\u001F\uD800-\uDFFF]/,p=r=>d.test(r)?JSON.stringify(r):`"${r}"`,b=r=>{if(r===void 0)return"null";if(typeof r=="bigint")throw new TypeError("stableStringify: cannot use a bigint in a stable JSON cache key — pass it as a string, or use stableWireKey");if(typeof r=="number"){if(Number.isNaN(r))return"nan";if(r===1/0)return"inf";if(r===-1/0)return"-inf";if(Object.is(r,-0))return"-0"}if(typeof r=="string")return p(r);if(r===null||typeof r!="object")return JSON.stringify(r);if(Array.isArray(r)){let n="[";for(let i=0;i<r.length;i++)i>0&&(n+=","),n+=b(r[i]);return n+"]"}const e=Object.getPrototypeOf(r);if(e!==null&&e!==Object.prototype){const n=r.constructor?.name??"value";throw new TypeError(`stableStringify: cannot use a ${n} in a stable JSON cache key — only plain objects, arrays, and JSON primitives are supported (wire-typed values key via stableWireKey)`)}const y=r,s=Object.keys(y).sort();let f="{",t=!0;for(const n of s){const i=y[n];i!==void 0&&(t?t=!1:f+=",",f+=p(n),f+=":",f+=b(i))}return f+"}"},u=r=>{let e="";for(let s=0;s<r.length;s+=32768)e+=String.fromCharCode(...r.subarray(s,s+32768));return btoa(e)},o="$lunora.wire$";const g="__proto__",m=r=>{if(r===null||typeof r!="object")return!1;const e=Object.getPrototypeOf(r);return e===null||e===Object.prototype},c=(r,e=0)=>{if(e>64)throw new RangeError("wire-codec: value nesting exceeds the 64-level limit");if(r===void 0)return[o,"undefined"];if(r===null)return null;const y=typeof r;if(y==="bigint")return[o,"bigint",r.toString()];if(y==="number"){const t=r;return Number.isNaN(t)?[o,"nan"]:t===1/0?[o,"inf"]:t===-1/0?[o,"-inf"]:t}if(y!=="object")return r;if(r instanceof Date)return[o,"date",c(r.getTime(),e+1)];if(r instanceof Error){const t=r,n={};for(const a of Object.keys(t))t[a]!==void 0&&(n[a]=c(t[a],e+1));const i=[o,"error",t.name,t.message,n];return t.cause!==void 0&&i.push(c(t.cause,e+1)),i}if(r instanceof URL)return[o,"url",r.href];if(r instanceof Map)return[o,"map",[...r.entries()].map(([t,n])=>[c(t,e+1),c(n,e+1)])];if(r instanceof Set)return[o,"set",[...r].map(t=>c(t,e+1))];if(r instanceof ArrayBuffer)return[o,"bytes",u(new Uint8Array(r)),"ArrayBuffer"];if(ArrayBuffer.isView(r)){const t=r,n=t.constructor.name,i=new Uint8Array(t.buffer,t.byteOffset,t.byteLength);return n==="Uint8Array"?[o,"bytes",u(i)]:[o,"bytes",u(i),n]}if(Array.isArray(r)){const t=r.map(n=>c(n,e+1));return t.length>0&&t[0]===o?[o,"arr",t]:t}if(!m(r)){const t=r.constructor?.name??"value";throw new TypeError(`wire-codec: cannot encode a ${t} over the Lunora wire — only plain objects, arrays, and the supported built-ins (Date, Error, URL, Map, Set, ArrayBuffer/typed arrays, bigint) round-trip`)}const s=r,f={};for(const t of Object.keys(s)){const n=s[t];if(n===void 0)continue;const i=c(n,e+1);t===g?Object.defineProperty(f,t,{configurable:!0,enumerable:!0,value:i,writable:!0}):f[t]=i}return f},w=r=>b(c(r));export{w as s};

package/dist/react.d.mts

@@ -1,26 +1,36 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-DTavX_y0.mjs";
-import "./packem_shared/types.d-CkMkSwLJ.mjs";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-CHCqFAg9.mjs";
+import "./packem_shared/types.d-BuLTPLaQ.mjs";
 /**
- * Options for the {@link useLocalQuery} hook.
+ * Result of {@link useLocalQuery} — a discriminated union so callers get a
+ * typed error instead of a swallowed `undefined`.
  * @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;
-}
+type LocalQueryResult<T> = {
+  readonly data: T[];
+  readonly error?: undefined;
+} | {
+  readonly data?: undefined;
+  readonly error: Error;
+};
 /**
  * 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.
+ * 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
@@ -32,28 +42,28 @@ interface UseLocalQueryOptions {
  * 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.
+ * @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 users = useLocalQuery<{ id: string; name: string }>(
+ *   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>;
  *   }
@@ -63,5 +73,5 @@ interface UseLocalQueryOptions {
  * ```
  * @experimental
  */
-declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
-export { UseLocalQueryOptions, useLocalQuery };
+declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>) => LocalQueryResult<T>;
+export { type LocalQueryResult, useLocalQuery };

package/dist/react.d.ts

@@ -1,26 +1,36 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-CyGOpUES.js";
-import "./packem_shared/types.d-CkMkSwLJ.js";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-CvNV3_gk.js";
+import "./packem_shared/types.d-BuLTPLaQ.js";
 /**
- * Options for the {@link useLocalQuery} hook.
+ * Result of {@link useLocalQuery} — a discriminated union so callers get a
+ * typed error instead of a swallowed `undefined`.
  * @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;
-}
+type LocalQueryResult<T> = {
+  readonly data: T[];
+  readonly error?: undefined;
+} | {
+  readonly data?: undefined;
+  readonly error: Error;
+};
 /**
  * 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.
+ * 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
@@ -32,28 +42,28 @@ interface UseLocalQueryOptions {
  * 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.
+ * @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 users = useLocalQuery<{ id: string; name: string }>(
+ *   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>;
  *   }
@@ -63,5 +73,5 @@ interface UseLocalQueryOptions {
  * ```
  * @experimental
  */
-declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
-export { UseLocalQueryOptions, useLocalQuery };
+declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>) => LocalQueryResult<T>;
+export { type LocalQueryResult, 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.version;
-  const getServerSnapshot = () => mirror.version;
-  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-  try {
-    return mirror.query(sql, params);
-  } catch {
-    return void 0;
-  }
-};
-
-export { useLocalQuery };
+import{useSyncExternalStore as y,useMemo as i}from"react";const u=t=>JSON.stringify(t??[],(r,e)=>typeof e=="bigint"?`${e.toString()}n`:e),S=(t,r,e)=>{const s=n=>t.onChange(n),o=()=>t.version,c=y(s,o,o),a=u(e);return i(()=>{try{return{data:t.query(r,e)}}catch(n){return{error:n instanceof Error?n:new Error(String(n))}}},[t,c,r,a])};export{S as useLocalQuery};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/replica",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-alpha.81",
   "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 };