@lunora/replica 0.0.0 → 1.0.0-alpha.100

package/dist/react.d.mts

@@ -0,0 +1,77 @@
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-DzREvGNM.mjs";
+import "./packem_shared/types.d-BuLTPLaQ.mjs";
+/**
+ * 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;
+};
+/**
+ * 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`.
+ * @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>) => LocalQueryResult<T>;
+export { type LocalQueryResult, useLocalQuery };

package/dist/react.d.ts

@@ -0,0 +1,77 @@
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-wbGXkXaE.js";
+import "./packem_shared/types.d-BuLTPLaQ.js";
+/**
+ * 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;
+};
+/**
+ * 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`.
+ * @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>) => LocalQueryResult<T>;
+export { type LocalQueryResult, useLocalQuery };

package/dist/react.mjs

@@ -0,0 +1 @@
+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,10 +1,91 @@
 {
   "name": "@lunora/replica",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @lunora/replica",
+  "version": "1.0.0-alpha.100",
+  "description": "Local-first replica runtime + local SQLite mirror for Lunora",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "cloudflare",
+    "durable-objects",
+    "event-sourcing",
+    "local-first",
+    "lunora",
+    "replica",
+    "sqlite",
+    "sync",
+    "workers"
+  ],
+  "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anolilab/lunora.git",
+    "directory": "packages/replica"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.mjs"
+    },
+    "./adapters/sqljs": {
+      "types": "./dist/adapters/sqljs.d.ts",
+      "import": "./dist/adapters/sqljs.mjs"
+    },
+    "./adapters/better-sqlite3": {
+      "types": "./dist/adapters/better-sqlite3.d.ts",
+      "import": "./dist/adapters/better-sqlite3.mjs"
+    },
+    "./adapters/sqlite-wasm": {
+      "types": "./dist/adapters/sqlite-wasm.d.ts",
+      "import": "./dist/adapters/sqlite-wasm.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@lunora/server": ">=1.0.0-alpha.24 <2.0.0-0",
+    "@sqlite.org/sqlite-wasm": "*",
+    "better-sqlite3": "*",
+    "react": "^18.0.0 || ^19.0.0",
+    "sql.js": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@lunora/server": {
+      "optional": true
+    },
+    "@sqlite.org/sqlite-wasm": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "sql.js": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
+}