@lunora/replica 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/react.d.mts

@@ -1,65 +1,67 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-Bp19ueGy.mjs";
-import "./packem_shared/types.d-VfJ76cK4.mjs";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-DTavX_y0.mjs";
+import "./packem_shared/types.d-CkMkSwLJ.mjs";
 /**
-* Options for the {@link useLocalQuery} hook.
-*/
+ * 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>;
-* }
-* ```
-*/
+ * 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

@@ -1,65 +1,67 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-GhuZAKgm.js";
-import "./packem_shared/types.d-VfJ76cK4.js";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-CyGOpUES.js";
+import "./packem_shared/types.d-CkMkSwLJ.js";
 /**
-* Options for the {@link useLocalQuery} hook.
-*/
+ * 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>;
-* }
-* ```
-*/
+ * 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

@@ -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 t}from"react";const c=(r,e,n,s)=>{t(o=>r.onChange(o),()=>r.version,()=>r.version);try{return r.query(e,n)}catch{return}};export{c as useLocalQuery};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/replica",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.21",
   "description": "Local-first replica runtime + local SQLite mirror for Lunora",
   "keywords": [
     "cloudflare",
@@ -62,7 +62,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@lunora/server": "1.0.0-alpha.24",
+    "@lunora/server": ">=1.0.0-alpha.24 <2.0.0-0",
     "@sqlite.org/sqlite-wasm": "*",
     "better-sqlite3": "*",
     "react": "^18.0.0 || ^19.0.0",

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 };