@lunora/replica 0.0.0 → 1.0.0-alpha.11

package/dist/react.d.ts

@@ -0,0 +1,67 @@
+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.
+ * @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 @@
+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,10 +1,91 @@
 {
   "name": "@lunora/replica",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @lunora/replica",
+  "version": "1.0.0-alpha.11",
+  "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"
+  }
+}