@lunora/db 0.0.0 → 1.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,142 @@
+import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
+import { Transaction, Collection } from '@tanstack/db';
+import { OnlineDetector, OfflineExecutor } from '@tanstack/offline-transactions';
+/** A row carrying the Lunora document id. */
+type Row = Record<string, unknown> & {
+  _id: string;
+};
+/** The subset of a TanStack DB sync write channel that {@link makeDiffEmit} drives. */
+interface SyncWriter<T extends object> {
+  begin: () => void;
+  commit: () => void;
+  write: (message: {
+    type: "insert" | "update";
+    value: T;
+  } | {
+    key: string;
+    type: "delete";
+  }) => void;
+}
+/** Index a row list into a keyed map. */
+declare const toMap: <T extends object>(rows: ReadonlyArray<T>, getKey: (row: T) => string) => Map<string, T>;
+/**
+* Build an `emit(next)` that diffs a desired keyed snapshot into a collection's
+* sync channel — only changed rows are written, so a reconnect snapshot or a
+* scope change never churns the synced view out from under a pending optimistic
+* row. The last-synced base is tracked in `synced`.
+*
+* Change detection compares rows by `JSON.stringify`, which is key-order
+* sensitive — safe here because `synced` only ever holds server snapshots, whose
+* column order is stable across reconnects (same query projection). A sync source
+* with unstable key ordering would need a structural compare instead.
+*/
+declare const makeDiffEmit: <T extends object>(synced: Map<string, T>, writer: SyncWriter<T>) => (next: Map<string, T>) => void;
+/**
+* Run a Lunora mutation under the outbox's retry policy.
+*
+* The retryable/permanent split keys on whether the failure carries a server
+* application error `code` (set by `@lunora/client`'s rpc when the server returns
+* a `{ error: { code, … } }` envelope — validation, conflict, etc.). A coded
+* error is a definite verdict: surface it as a `NonRetriableError` so the executor
+* stops and TanStack DB rolls the optimistic insert back. Everything without a
+* code is transient — a `fetch` network failure (`TypeError`) or an HTTP/infra
+* blip the rpc surfaces as a code-less `Error` (a 5xx gateway page, a non-JSON
+* body) — so it's rethrown as-is and the durable outbox replays it. Keying on
+* `error instanceof TypeError` alone would wrongly drop the latter.
+*/
+declare const runOutboxMutation: (mutate: () => Promise<unknown>) => Promise<void>;
+/**
+* An "always attempt" online detector. We deliberately don't trust
+* `navigator.onLine`: some environments (and Playwright's `setOffline` under
+* Firefox) leave it stuck, which would freeze the outbox. Instead the executor
+* always tries the send and {@link runOutboxMutation}'s transient-error retry
+* handles real offline; the periodic tick nudges the executor to drain the outbox
+* so a queued write replays promptly once connectivity returns.
+*
+* `isOnline` is therefore intentionally always `true` — it gates the executor's
+* attempts, not a UI signal. A consumer that wants to show real connectivity
+* should read `navigator.onLine` itself, separately from this detector.
+*/
+declare const createOptimisticOnlineDetector: () => OnlineDetector;
+/** Element type of an array (the row type a `list` query returns). */
+type Element<T> = T extends ReadonlyArray<infer E> ? E : never;
+/** `true` for the `any` type, `false` otherwise. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+* The row type a `list` query syncs. For `TList = any` (the heterogeneous-map
+* constraint) it resolves to the permissive {@link Row}, not `never` — otherwise
+* the constraint would force every `optimistic` to return `never`. For a concrete
+* `FunctionReference` it's the element type of the query's array return.
+*/
+type RowOfList<TList> = IsAny<TList> extends true ? Row : TList extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> & Row : never;
+/** Maps a write through the durable outbox: optimistic insert + a retried mutation. */
+interface InsertBinding<TRow extends Row, TInput> {
+  /** The Lunora mutation that persists the row. */
+  mutation: FunctionReference;
+  /** Build the optimistic row to insert from the action input + the generated client id. */
+  optimistic: (input: TInput, id: string) => TRow;
+  /** Build the mutation args from the persisted optimistic row (forward `_id` as the `clientId`). */
+  toArgs: (row: TRow) => Record<string, unknown>;
+}
+/** Declarative binding of a Lunora table to a live collection (+ optional write action). */
+interface CollectionDef<TList extends FunctionReference, TInput = never> {
+  /** Row key extractor — defaults to `row._id`. */
+  getKey?: (row: RowOfList<TList>) => string;
+  /** Optional write binding — present iff this collection is written through the outbox. */
+  insert?: InsertBinding<RowOfList<TList>, TInput>;
+  /** The Lunora query that lists the rows (the sync source). */
+  list: TList;
+  /**
+  * Notified when the underlying `list` subscription errors (e.g. the server
+  * rejects it). Without this the error would be swallowed and the collection
+  * could hang in `loading`; the binding always moves the collection out of
+  * `loading` on error, and forwards the error here if supplied.
+  */
+  onError?: (error: SubscriptionError) => void;
+  /** A field that scopes the list (e.g. a shard key); makes the collection re-pointable via `scope`. */
+  scopeBy?: string;
+}
+type AnyDef = CollectionDef<any, any>;
+/**
+* The public row type a collection exposes — the element type of its `list`
+* query's return, with no `& Row`: a `Collection&lt;T>` is invariant in `T`, so the
+* exposed type must be exactly the document type, not a subtype.
+*/
+type RowOf<C extends AnyDef> = C["list"] extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> : never;
+/** The action input type, inferred structurally from the def's optimistic insert. */
+type InputOf<C> = C extends {
+  insert: {
+    optimistic: (input: infer I, id: string) => unknown;
+  };
+} ? I : never;
+/** The wired data layer `defineCollections` returns. */
+interface LunoraDb<D extends Record<string, AnyDef>> {
+  /** Optimistic, durable, retried write actions — present for `insert` collections. */
+  actions: { [K in keyof D]: D[K] extends {
+    insert: object;
+  } ? (input: InputOf<D[K]>) => {
+    id: string;
+    transaction: Transaction;
+  } : never };
+  /** The live, synced collections — feed these to `useLiveQuery`. */
+  collections: { [K in keyof D]: Collection<RowOf<D[K]>, string> };
+  /** The shared offline executor (the outbox). */
+  executor: OfflineExecutor;
+  /** Re-point a `scopeBy` collection's subscription (omit `args` to detach) — present for scoped collections. */
+  scope: { [K in keyof D]: D[K] extends {
+    scopeBy: string;
+  } ? (args?: Record<string, unknown>) => void : never };
+}
+/**
+* Wire a set of Lunora tables into a TanStack DB data layer in one declaration:
+* each entry becomes a live, auto-indexed collection synced from its `list` query,
+* and `insert` entries get an optimistic write action backed by the
+* offline-transactions outbox (durable, retried, client-id-keyed). Scoped
+* (`scopeBy`) collections are re-pointable for sharded queries.
+*
+* This is the hand-written form; `@lunora/codegen` can emit a fully-typed call to
+* it from `schema.ts`, so an app writes nothing.
+*/
+declare const defineCollections: <D extends Record<string, AnyDef>>(client: LunoraClient, defs: D) => LunoraDb<D>;
+declare const VERSION = "0.0.0";
+export { type CollectionDef, type InsertBinding, type LunoraDb, type Row, type SyncWriter, VERSION, createOptimisticOnlineDetector, defineCollections, makeDiffEmit, runOutboxMutation, toMap };

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
+import { Transaction, Collection } from '@tanstack/db';
+import { OnlineDetector, OfflineExecutor } from '@tanstack/offline-transactions';
+/** A row carrying the Lunora document id. */
+type Row = Record<string, unknown> & {
+  _id: string;
+};
+/** The subset of a TanStack DB sync write channel that {@link makeDiffEmit} drives. */
+interface SyncWriter<T extends object> {
+  begin: () => void;
+  commit: () => void;
+  write: (message: {
+    type: "insert" | "update";
+    value: T;
+  } | {
+    key: string;
+    type: "delete";
+  }) => void;
+}
+/** Index a row list into a keyed map. */
+declare const toMap: <T extends object>(rows: ReadonlyArray<T>, getKey: (row: T) => string) => Map<string, T>;
+/**
+* Build an `emit(next)` that diffs a desired keyed snapshot into a collection's
+* sync channel — only changed rows are written, so a reconnect snapshot or a
+* scope change never churns the synced view out from under a pending optimistic
+* row. The last-synced base is tracked in `synced`.
+*
+* Change detection compares rows by `JSON.stringify`, which is key-order
+* sensitive — safe here because `synced` only ever holds server snapshots, whose
+* column order is stable across reconnects (same query projection). A sync source
+* with unstable key ordering would need a structural compare instead.
+*/
+declare const makeDiffEmit: <T extends object>(synced: Map<string, T>, writer: SyncWriter<T>) => (next: Map<string, T>) => void;
+/**
+* Run a Lunora mutation under the outbox's retry policy.
+*
+* The retryable/permanent split keys on whether the failure carries a server
+* application error `code` (set by `@lunora/client`'s rpc when the server returns
+* a `{ error: { code, … } }` envelope — validation, conflict, etc.). A coded
+* error is a definite verdict: surface it as a `NonRetriableError` so the executor
+* stops and TanStack DB rolls the optimistic insert back. Everything without a
+* code is transient — a `fetch` network failure (`TypeError`) or an HTTP/infra
+* blip the rpc surfaces as a code-less `Error` (a 5xx gateway page, a non-JSON
+* body) — so it's rethrown as-is and the durable outbox replays it. Keying on
+* `error instanceof TypeError` alone would wrongly drop the latter.
+*/
+declare const runOutboxMutation: (mutate: () => Promise<unknown>) => Promise<void>;
+/**
+* An "always attempt" online detector. We deliberately don't trust
+* `navigator.onLine`: some environments (and Playwright's `setOffline` under
+* Firefox) leave it stuck, which would freeze the outbox. Instead the executor
+* always tries the send and {@link runOutboxMutation}'s transient-error retry
+* handles real offline; the periodic tick nudges the executor to drain the outbox
+* so a queued write replays promptly once connectivity returns.
+*
+* `isOnline` is therefore intentionally always `true` — it gates the executor's
+* attempts, not a UI signal. A consumer that wants to show real connectivity
+* should read `navigator.onLine` itself, separately from this detector.
+*/
+declare const createOptimisticOnlineDetector: () => OnlineDetector;
+/** Element type of an array (the row type a `list` query returns). */
+type Element<T> = T extends ReadonlyArray<infer E> ? E : never;
+/** `true` for the `any` type, `false` otherwise. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+* The row type a `list` query syncs. For `TList = any` (the heterogeneous-map
+* constraint) it resolves to the permissive {@link Row}, not `never` — otherwise
+* the constraint would force every `optimistic` to return `never`. For a concrete
+* `FunctionReference` it's the element type of the query's array return.
+*/
+type RowOfList<TList> = IsAny<TList> extends true ? Row : TList extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> & Row : never;
+/** Maps a write through the durable outbox: optimistic insert + a retried mutation. */
+interface InsertBinding<TRow extends Row, TInput> {
+  /** The Lunora mutation that persists the row. */
+  mutation: FunctionReference;
+  /** Build the optimistic row to insert from the action input + the generated client id. */
+  optimistic: (input: TInput, id: string) => TRow;
+  /** Build the mutation args from the persisted optimistic row (forward `_id` as the `clientId`). */
+  toArgs: (row: TRow) => Record<string, unknown>;
+}
+/** Declarative binding of a Lunora table to a live collection (+ optional write action). */
+interface CollectionDef<TList extends FunctionReference, TInput = never> {
+  /** Row key extractor — defaults to `row._id`. */
+  getKey?: (row: RowOfList<TList>) => string;
+  /** Optional write binding — present iff this collection is written through the outbox. */
+  insert?: InsertBinding<RowOfList<TList>, TInput>;
+  /** The Lunora query that lists the rows (the sync source). */
+  list: TList;
+  /**
+  * Notified when the underlying `list` subscription errors (e.g. the server
+  * rejects it). Without this the error would be swallowed and the collection
+  * could hang in `loading`; the binding always moves the collection out of
+  * `loading` on error, and forwards the error here if supplied.
+  */
+  onError?: (error: SubscriptionError) => void;
+  /** A field that scopes the list (e.g. a shard key); makes the collection re-pointable via `scope`. */
+  scopeBy?: string;
+}
+type AnyDef = CollectionDef<any, any>;
+/**
+* The public row type a collection exposes — the element type of its `list`
+* query's return, with no `& Row`: a `Collection&lt;T>` is invariant in `T`, so the
+* exposed type must be exactly the document type, not a subtype.
+*/
+type RowOf<C extends AnyDef> = C["list"] extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> : never;
+/** The action input type, inferred structurally from the def's optimistic insert. */
+type InputOf<C> = C extends {
+  insert: {
+    optimistic: (input: infer I, id: string) => unknown;
+  };
+} ? I : never;
+/** The wired data layer `defineCollections` returns. */
+interface LunoraDb<D extends Record<string, AnyDef>> {
+  /** Optimistic, durable, retried write actions — present for `insert` collections. */
+  actions: { [K in keyof D]: D[K] extends {
+    insert: object;
+  } ? (input: InputOf<D[K]>) => {
+    id: string;
+    transaction: Transaction;
+  } : never };
+  /** The live, synced collections — feed these to `useLiveQuery`. */
+  collections: { [K in keyof D]: Collection<RowOf<D[K]>, string> };
+  /** The shared offline executor (the outbox). */
+  executor: OfflineExecutor;
+  /** Re-point a `scopeBy` collection's subscription (omit `args` to detach) — present for scoped collections. */
+  scope: { [K in keyof D]: D[K] extends {
+    scopeBy: string;
+  } ? (args?: Record<string, unknown>) => void : never };
+}
+/**
+* Wire a set of Lunora tables into a TanStack DB data layer in one declaration:
+* each entry becomes a live, auto-indexed collection synced from its `list` query,
+* and `insert` entries get an optimistic write action backed by the
+* offline-transactions outbox (durable, retried, client-id-keyed). Scoped
+* (`scopeBy`) collections are re-pointable for sharded queries.
+*
+* This is the hand-written form; `@lunora/codegen` can emit a fully-typed call to
+* it from `schema.ts`, so an app writes nothing.
+*/
+declare const defineCollections: <D extends Record<string, AnyDef>>(client: LunoraClient, defs: D) => LunoraDb<D>;
+declare const VERSION = "0.0.0";
+export { type CollectionDef, type InsertBinding, type LunoraDb, type Row, type SyncWriter, VERSION, createOptimisticOnlineDetector, defineCollections, makeDiffEmit, runOutboxMutation, toMap };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+export { defineCollections } from './packem_shared/defineCollections-Cqtf9ffi.mjs';
+export { createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap } from './packem_shared/toMap-CRulWqZ7.mjs';
+
+const VERSION = "0.0.0";
+
+export { VERSION };

package/dist/packem_shared/defineCollections-Cqtf9ffi.mjs

@@ -0,0 +1,109 @@
+import { createCollection, BTreeIndex } from '@tanstack/db';
+import { startOfflineExecutor } from '@tanstack/offline-transactions';
+import { toMap, createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation } from './toMap-CRulWqZ7.mjs';
+
+const defineCollections = (client, defs) => {
+  const collections = {};
+  const scope = {};
+  const subscriptions = {};
+  const emitters = {};
+  const errorHandlers = {};
+  const mutationFns = {};
+  const entries = Object.entries(defs);
+  for (const [name, definition] of entries) {
+    const getKey = definition.getKey ?? ((row) => row._id);
+    const insert = definition.insert;
+    const synced = /* @__PURE__ */ new Map();
+    collections[name] = createCollection({
+      // Auto-build ordered (B-tree) indexes for whatever the app's live
+      // queries join / filter / sort on, so they stay fast as data grows.
+      autoIndex: "eager",
+      defaultIndexType: BTreeIndex,
+      getKey,
+      id: name,
+      sync: {
+        sync: (writer) => {
+          const emit = makeDiffEmit(synced, writer);
+          emitters[name] = emit;
+          const onError = (error) => {
+            writer.markReady();
+            definition.onError?.(error);
+          };
+          errorHandlers[name] = onError;
+          if (definition.scopeBy === void 0) {
+            subscriptions[name] = client.subscribe(
+              definition.list,
+              {},
+              (rows) => {
+                emit(toMap(rows, getKey));
+                writer.markReady();
+              },
+              { onError }
+            );
+          } else {
+            writer.markReady();
+          }
+          return () => {
+            emitters[name] = void 0;
+            errorHandlers[name] = void 0;
+            subscriptions[name]?.();
+            subscriptions[name] = void 0;
+          };
+        }
+      }
+    });
+    if (definition.scopeBy !== void 0) {
+      scope[name] = (args) => {
+        subscriptions[name]?.();
+        subscriptions[name] = void 0;
+        emitters[name]?.(/* @__PURE__ */ new Map());
+        if (args === void 0) {
+          return;
+        }
+        subscriptions[name] = client.subscribe(
+          definition.list,
+          args,
+          (rows) => {
+            emitters[name]?.(toMap(rows, getKey));
+          },
+          { onError: (error) => errorHandlers[name]?.(error) }
+        );
+      };
+    }
+    if (insert) {
+      mutationFns[name] = async ({ transaction }) => {
+        for (const mutation of transaction.mutations) {
+          const row = mutation.modified;
+          await runOutboxMutation(() => client.mutation(insert.mutation, insert.toArgs(row)));
+        }
+      };
+    }
+  }
+  const executor = startOfflineExecutor({
+    collections,
+    mutationFns,
+    onlineDetector: createOptimisticOnlineDetector()
+  });
+  const actions = {};
+  for (const [name, definition] of entries) {
+    const insert = definition.insert;
+    const collection = collections[name];
+    if (!insert || !collection) {
+      continue;
+    }
+    const action = executor.createOfflineAction({
+      mutationFnName: name,
+      onMutate: ({ id, input }) => {
+        collection.insert(insert.optimistic(input, id));
+      }
+    });
+    actions[name] = (input) => {
+      const id = crypto.randomUUID();
+      const transaction = action({ id, input });
+      return { id, transaction };
+    };
+  }
+  return { actions, collections, executor, scope };
+};
+
+export { defineCollections };

package/dist/packem_shared/toMap-CRulWqZ7.mjs

@@ -0,0 +1,65 @@
+import { NonRetriableError } from '@tanstack/offline-transactions';
+
+const OUTBOX_DRAIN_INTERVAL_MS = 1e3;
+const toMap = (rows, getKey) => {
+  const map = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    map.set(getKey(row), row);
+  }
+  return map;
+};
+const makeDiffEmit = (synced, writer) => (next) => {
+  writer.begin();
+  for (const [key, value] of next) {
+    const previous = synced.get(key);
+    if (previous === void 0) {
+      writer.write({ type: "insert", value });
+    } else if (JSON.stringify(previous) !== JSON.stringify(value)) {
+      writer.write({ type: "update", value });
+    }
+  }
+  for (const key of synced.keys()) {
+    if (!next.has(key)) {
+      writer.write({ key, type: "delete" });
+    }
+  }
+  writer.commit();
+  synced.clear();
+  for (const [key, value] of next) {
+    synced.set(key, value);
+  }
+};
+const runOutboxMutation = async (mutate) => {
+  try {
+    await mutate();
+  } catch (error) {
+    if (typeof error.code === "string") {
+      throw new NonRetriableError(error instanceof Error ? error.message : String(error));
+    }
+    throw error;
+  }
+};
+const createOptimisticOnlineDetector = () => {
+  const intervals = /* @__PURE__ */ new Set();
+  return {
+    dispose: () => {
+      for (const handle of intervals) {
+        clearInterval(handle);
+      }
+      intervals.clear();
+    },
+    isOnline: () => true,
+    notifyOnline: () => {
+    },
+    subscribe: (callback) => {
+      const handle = setInterval(callback, OUTBOX_DRAIN_INTERVAL_MS);
+      intervals.add(handle);
+      return () => {
+        clearInterval(handle);
+        intervals.delete(handle);
+      };
+    }
+  };
+};
+
+export { createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap };

package/package.json

@@ -1,31 +1,58 @@
 {
   "name": "@lunora/db",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.1",
   "description": "TanStack DB binding: typed, live-synced collections and a durable offline outbox over the Lunora client",
-  "license": "FSL-1.1-Apache-2.0",
+  "keywords": [
+    "cloudflare",
+    "durable-objects",
+    "live-query",
+    "lunora",
+    "offline-first",
+    "optimistic-updates",
+    "tanstack-db",
+    "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/db"
   },
-  "bugs": {
-    "url": "https://github.com/anolilab/lunora/issues"
-  },
-  "keywords": [
-    "lunora",
-    "cloudflare",
-    "workers",
-    "durable-objects",
-    "tanstack-db",
-    "offline-first",
-    "optimistic-updates",
-    "live-query"
+  "files": [
+    "dist",
+    "__assets__",
+    "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"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "@lunora/client": "1.0.0-alpha.1"
+  },
+  "peerDependencies": {
+    "@tanstack/db": "^0.6.0",
+    "@tanstack/offline-transactions": "^1.0.0"
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
 }