@lunora/db 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/packem_shared/define-collections.d-Po97lX6i.d.ts

@@ -0,0 +1,85 @@
+import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
+import { Transaction, Collection } from '@tanstack/db';
+import { OfflineExecutor } from '@tanstack/offline-transactions';
+import { R as Row } from "./collection-options.d-CbS3J_Fm.js";
+/** 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>;
+export { CollectionDef as C, InsertBinding as I, LunoraDb as L, defineCollections as d };

package/dist/packem_shared/define-mutators.d-C3DO284A.d.ts

@@ -0,0 +1,80 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-CbS3J_Fm.js";
+/** The local store a client mutator's optimistic body writes against. */
+interface ClientMutatorContext {
+  /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
+  collections: Record<string, Collection<Row, string>>;
+}
+/** A client-side custom mutator: an optimistic body plus the path of its authoritative server impl. */
+interface ClientMutatorDef<TArgs> {
+  /** Brand so codegen / `bindMutators` can recognize a mutator definition. */
+  __lunoraClientMutator: true;
+  /** The optimistic update applied to the local collections before the server confirms. */
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  /** The Lunora function path of the server-authoritative mutator (`defineMutator` on the server). */
+  serverRef: string;
+}
+/**
+* Declare a client-side custom mutator. `apply` runs optimistically against the
+* local TanStack collections; `serverRef` names the authoritative server mutator
+* the write is pushed to over the watermark protocol. The server impl is the
+* linearization point — this body is a prediction the server can override.
+*/
+declare const defineMutator: <TArgs = Record<string, unknown>>(definition: {
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  serverRef: string;
+}) => ClientMutatorDef<TArgs>;
+type AnyMutatorMap = Record<string, ClientMutatorDef<any>>;
+/** Args type of a mutator definition. */
+type ArgsOf<M> = M extends ClientMutatorDef<infer A> ? A : never;
+/** Inputs `bindMutators` needs to run a mutator: the local store + how the overlay drops. */
+interface BindMutatorsContext {
+  /**
+  * Resolves the optimistic-overlay drop against confirmed server watermarks.
+  * When supplied, a mutation's overlay is held until the sync stream echoes
+  * `lastMutationId >= clientSeq` (via {@link CheckpointRegistry.resolve}) — no
+  * flicker. When omitted, the overlay drops as soon as the server accepts the
+  * write (the by-value sync diff then converges the synced row in place).
+  */
+  checkpoints?: CheckpointRegistry;
+  /** The wired collections the optimistic bodies write against. */
+  collections: Record<string, Collection<Row, string>>;
+  /** Optional shard key the mutator's server push is routed to. */
+  shardKey?: string;
+}
+/** Calling a bound mutator runs the optimistic body + pushes the server write; returns the TanStack transaction. */
+type BoundMutators<M extends AnyMutatorMap> = { [K in keyof M]: (args: ArgsOf<M[K]>) => Transaction };
+/**
+* Bind a set of client mutators to a client + local store. Each returned handle,
+* when called, opens a TanStack optimistic transaction: the mutator's `apply`
+* body writes the predicted rows into the collections, and the transaction's
+* `mutationFn` pushes the authoritative write through
+* {@link LunoraClient.callMutator} under a monotonic per-client `clientSeq`.
+*
+* Rebase-on-poke is free — TanStack DB re-derives every pending optimistic overlay
+* over the latest synced base on each sync tick. The overlay is dropped when the
+* server confirms the write (and, if `checkpoints` is supplied, once it echoes the
+* matching watermark so the synced row has landed).
+*
+* The `clientSeq` generator is seeded from the server's echoed watermark
+* ({@link LunoraClient.confirmedMutationWatermark}) on every issue, so a reload —
+* which resets this in-memory counter while the server keeps a durable per-client
+* watermark — never reissues a sequence the DO has already applied. As a backstop
+* for the very first push of a fresh session (before any ack has taught the client
+* the watermark), a push the DO swallows as a replay (`applied === false`) is
+* reissued above the now-known watermark instead of being mistaken for a confirmed
+* write — closing the silent-drop window without risking a double-apply (a fresh
+* session's first stale push provably cannot be an honest replay).
+*
+* Pushes are **serialized per binding** (a FIFO chain): the DO rejects any push
+* with `clientSeq > watermark + 1` as `OUT_OF_ORDER` and drops the write, so two
+* mutators fired concurrently must not race the network into a gap. Each push
+* waits for the previous one's ack and assigns its `clientSeq` *inside* the
+* critical section — from the live watermark — so the sequence is always exactly
+* `watermark + 1`. Because a failed mutation never advances the server watermark,
+* a permanently-rejected predecessor can't wedge the chain: the next push simply
+* reclaims the same `watermark + 1` instead of leaving a hole the DO waits on.
+*/
+declare const bindMutators: <M extends AnyMutatorMap>(client: LunoraClient, context: BindMutatorsContext, mutators: M) => BoundMutators<M>;
+export { BindMutatorsContext as B, ClientMutatorContext as C, BoundMutators as a, ClientMutatorDef as b, bindMutators as c, defineMutator as d };

package/dist/packem_shared/define-mutators.d-DNVJIpW8.d.mts

@@ -0,0 +1,80 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-CbS3J_Fm.mjs";
+/** The local store a client mutator's optimistic body writes against. */
+interface ClientMutatorContext {
+  /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
+  collections: Record<string, Collection<Row, string>>;
+}
+/** A client-side custom mutator: an optimistic body plus the path of its authoritative server impl. */
+interface ClientMutatorDef<TArgs> {
+  /** Brand so codegen / `bindMutators` can recognize a mutator definition. */
+  __lunoraClientMutator: true;
+  /** The optimistic update applied to the local collections before the server confirms. */
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  /** The Lunora function path of the server-authoritative mutator (`defineMutator` on the server). */
+  serverRef: string;
+}
+/**
+* Declare a client-side custom mutator. `apply` runs optimistically against the
+* local TanStack collections; `serverRef` names the authoritative server mutator
+* the write is pushed to over the watermark protocol. The server impl is the
+* linearization point — this body is a prediction the server can override.
+*/
+declare const defineMutator: <TArgs = Record<string, unknown>>(definition: {
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  serverRef: string;
+}) => ClientMutatorDef<TArgs>;
+type AnyMutatorMap = Record<string, ClientMutatorDef<any>>;
+/** Args type of a mutator definition. */
+type ArgsOf<M> = M extends ClientMutatorDef<infer A> ? A : never;
+/** Inputs `bindMutators` needs to run a mutator: the local store + how the overlay drops. */
+interface BindMutatorsContext {
+  /**
+  * Resolves the optimistic-overlay drop against confirmed server watermarks.
+  * When supplied, a mutation's overlay is held until the sync stream echoes
+  * `lastMutationId >= clientSeq` (via {@link CheckpointRegistry.resolve}) — no
+  * flicker. When omitted, the overlay drops as soon as the server accepts the
+  * write (the by-value sync diff then converges the synced row in place).
+  */
+  checkpoints?: CheckpointRegistry;
+  /** The wired collections the optimistic bodies write against. */
+  collections: Record<string, Collection<Row, string>>;
+  /** Optional shard key the mutator's server push is routed to. */
+  shardKey?: string;
+}
+/** Calling a bound mutator runs the optimistic body + pushes the server write; returns the TanStack transaction. */
+type BoundMutators<M extends AnyMutatorMap> = { [K in keyof M]: (args: ArgsOf<M[K]>) => Transaction };
+/**
+* Bind a set of client mutators to a client + local store. Each returned handle,
+* when called, opens a TanStack optimistic transaction: the mutator's `apply`
+* body writes the predicted rows into the collections, and the transaction's
+* `mutationFn` pushes the authoritative write through
+* {@link LunoraClient.callMutator} under a monotonic per-client `clientSeq`.
+*
+* Rebase-on-poke is free — TanStack DB re-derives every pending optimistic overlay
+* over the latest synced base on each sync tick. The overlay is dropped when the
+* server confirms the write (and, if `checkpoints` is supplied, once it echoes the
+* matching watermark so the synced row has landed).
+*
+* The `clientSeq` generator is seeded from the server's echoed watermark
+* ({@link LunoraClient.confirmedMutationWatermark}) on every issue, so a reload —
+* which resets this in-memory counter while the server keeps a durable per-client
+* watermark — never reissues a sequence the DO has already applied. As a backstop
+* for the very first push of a fresh session (before any ack has taught the client
+* the watermark), a push the DO swallows as a replay (`applied === false`) is
+* reissued above the now-known watermark instead of being mistaken for a confirmed
+* write — closing the silent-drop window without risking a double-apply (a fresh
+* session's first stale push provably cannot be an honest replay).
+*
+* Pushes are **serialized per binding** (a FIFO chain): the DO rejects any push
+* with `clientSeq > watermark + 1` as `OUT_OF_ORDER` and drops the write, so two
+* mutators fired concurrently must not race the network into a gap. Each push
+* waits for the previous one's ack and assigns its `clientSeq` *inside* the
+* critical section — from the live watermark — so the sequence is always exactly
+* `watermark + 1`. Because a failed mutation never advances the server watermark,
+* a permanently-rejected predecessor can't wedge the chain: the next push simply
+* reclaims the same `watermark + 1` instead of leaving a hole the DO waits on.
+*/
+declare const bindMutators: <M extends AnyMutatorMap>(client: LunoraClient, context: BindMutatorsContext, mutators: M) => BoundMutators<M>;
+export { BindMutatorsContext as B, ClientMutatorContext as C, BoundMutators as a, ClientMutatorDef as b, bindMutators as c, defineMutator as d };

package/dist/packem_shared/defineCollections-oL1qzsWE.mjs

@@ -0,0 +1,74 @@
+import { createCollection } from '@tanstack/db';
+import { startOfflineExecutor, NonRetriableError } from '@tanstack/offline-transactions';
+import { lunoraCollectionOptions } from './createCheckpointRegistry-DztP2nI8.mjs';
+import { createOptimisticOnlineDetector, runOutboxMutation, OUTBOX_MUTATION_FN_NAME } from './OUTBOX_MUTATION_FN_NAME-DZrP1gna.mjs';
+
+const defineCollections = (client, defs) => {
+  const collections = {};
+  const scope = {};
+  const mutationFns = {};
+  const entries = Object.entries(defs);
+  for (const [name, definition] of entries) {
+    const insert = definition.insert;
+    const { config, scope: scopeFunction } = lunoraCollectionOptions({
+      client,
+      getKey: definition.getKey,
+      id: name,
+      // `AnyDef` erases `list` to `any` (`TList = any`); it's a `FunctionReference` here.
+      list: definition.list,
+      onError: definition.onError,
+      scopeBy: definition.scopeBy
+    });
+    collections[name] = createCollection(config);
+    if (definition.scopeBy !== void 0) {
+      scope[name] = scopeFunction;
+    }
+    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)));
+        }
+      };
+    }
+  }
+  mutationFns[OUTBOX_MUTATION_FN_NAME] = async ({ transaction }) => {
+    const meta = transaction.metadata;
+    if (!meta) {
+      return;
+    }
+    if (meta.identity !== client.currentIdentity()) {
+      throw new NonRetriableError("outbox write dropped: identity changed since it was queued");
+    }
+    await runOutboxMutation(
+      () => client.mutation({ __lunoraRef: meta.functionPath }, meta.args, { mutationId: meta.idempotencyKey, shardKey: meta.shardKey })
+    );
+  };
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/db",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.6",
   "description": "TanStack DB binding: typed, live-synced collections and a durable offline outbox over the Lunora client",
   "keywords": [
     "cloudflare",
@@ -40,13 +40,21 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs"
     },
+    "./collections": {
+      "types": "./dist/collections/index.d.ts",
+      "import": "./dist/collections/index.mjs"
+    },
+    "./mutators": {
+      "types": "./dist/mutators/index.d.ts",
+      "import": "./dist/mutators/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.4"
+    "@lunora/client": "1.0.0-alpha.6"
   },
   "peerDependencies": {
     "@tanstack/db": "^0.6.0",

package/dist/packem_shared/createOptimisticOnlineDetector-CRulWqZ7.mjs

@@ -1,65 +0,0 @@
-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/dist/packem_shared/defineCollections-BAmslSrF.mjs

@@ -1,109 +0,0 @@
-import { createCollection, BTreeIndex } from '@tanstack/db';
-import { startOfflineExecutor } from '@tanstack/offline-transactions';
-import { toMap, createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation } from './createOptimisticOnlineDetector-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 };