@lunora/db 1.0.0-alpha.3 → 1.0.0-alpha.31

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

@@ -0,0 +1,166 @@
+import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
+import { Transaction, Collection } from '@tanstack/db';
+import { OfflineExecutor, StorageDiagnostic } from '@tanstack/offline-transactions';
+import { R as Row } from "./collection-options.d-B_2IXvdU.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;
+  /**
+   * When this collection starts syncing — `"lazy"` (default) on the first
+   * `useLiveQuery` subscriber, or `"eager"` at creation, for small "instant"
+   * reference data you want warm at boot. Pairs with `scopeBy` for partial
+   * (per-scope) loading — together they give the full lazy/partial/eager
+   * (Linear `lazy`/`partial`/`instant`) load taxonomy declaratively. No effect
+   * on a `scopeBy` collection (nothing to sync until scoped).
+   */
+  load?: "eager" | "lazy";
+  /**
+   * 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;
+  /**
+   * Routes the `list` subscription (and the confirmed-mutation watermark its
+   * frames advance the checkpoint gate from) to a specific shard's DO — so a
+   * sharded collection's overlay gate compares against that shard's mutator
+   * sequence line, not the default ("") watermark bucket.
+   */
+  shardKey?: 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;
+/** A queued write that was permanently dropped, passed to {@link DefineCollectionsOptions.onWriteRejected}. */
+interface WriteRejectedEvent {
+  /**
+   * The machine-readable reason — the server's error `code` (e.g. `CONFLICT`,
+   * `FORBIDDEN`), or `UNKNOWN_MUTATION_FN` when the write referenced a collection
+   * that no longer exists (removed in a deploy). Mirrors the client's
+   * `MutationSettledEvent.code` so a consumer can branch on the verdict.
+   */
+  code?: string;
+  /** The collection/table name the write targeted. */
+  collection: string;
+  /** The error that dropped the write (message carried by the underlying `NonRetriableError`). */
+  error: Error;
+  /**
+   * The optimistic row being rolled back (the rollback follows the callback).
+   * Absent only if the dropped transaction carried no recoverable row (e.g. some
+   * `UNKNOWN_MUTATION_FN` cases).
+   */
+  row?: Row;
+}
+/** Options for {@link defineCollections}. */
+interface DefineCollectionsOptions {
+  /**
+   * Invoked when a leadership change occurs across tabs (only the leader tab
+   * drains the durable outbox). Informational — useful for diagnostics; the
+   * library handles the election itself.
+   */
+  onLeadershipChange?: (isLeader: boolean) => void;
+  /**
+   * Invoked when the durable outbox's storage layer fails — IndexedDB
+   * unavailable (private mode), blocked, or quota exceeded. The standalone
+   * client surfaces this via `offlineQueue.onPersistenceError`; this is the
+   * collection-layer counterpart. A storage failure means a write is NOT durable
+   * and won't survive a reload, so surface it (e.g. "your change may not be
+   * saved if you close this tab").
+   */
+  onStorageFailure?: (diagnostic: StorageDiagnostic) => void;
+  /**
+   * Invoked as a queued write is permanently dropped: a coded application error
+   * from the server (validation, RLS denial, conflict, surfaced as a
+   * `NonRetriableError`), OR a write whose target collection no longer exists —
+   * removed/renamed in a deploy (`code: "UNKNOWN_MUTATION_FN"`). This is the
+   * aggregate, fire-and-forget-safe channel: unlike awaiting the per-action
+   * `transaction` returned by `actions[name](...)`, it fires even when the caller
+   * never retained that handle, so a UI can surface "couldn't save" instead of a
+   * silently vanishing row. Transient failures (offline, 5xx) are retried by the
+   * outbox, not reported here.
+   *
+   * Timing: the callback runs at the point of rejection; the executor's
+   * optimistic-row rollback follows immediately after. The event's `row` is the
+   * (about-to-be-removed) optimistic row, so don't depend on the collection
+   * already reflecting the removal from inside the handler — use `row`/`error`
+   * directly (e.g. for a toast).
+   */
+  onWriteRejected?: (event: WriteRejectedEvent) => void;
+}
+/** 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;
+  /**
+   * Number of writes still pending in the durable outbox — the depth for a
+   * "N changes waiting to sync" indicator. A convenience over reaching through
+   * `executor.getPendingCount()`. **Pull-only** (the underlying TanStack
+   * executor exposes no change subscription): read it after a `db.actions.*`
+   * call and on connection-status changes, or poll. The standalone
+   * `LunoraClient` exposes the reactive `onPendingChange` for its built-in queue.
+   */
+  pendingCount: () => number;
+  /** 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, options?: DefineCollectionsOptions) => LunoraDb<D>;
+export { CollectionDef as C, DefineCollectionsOptions as D, InsertBinding as I, LunoraDb as L, WriteRejectedEvent as W, defineCollections as d };

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

@@ -0,0 +1,148 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-B_2IXvdU.mjs";
+/**
+ * TanStack DB's "direct transaction" marker.
+ *
+ * A completed transaction's optimistic rows are discarded as **stale** unless
+ * either a synced transaction for the same key is already queued, or the
+ * transaction carried this flag (`CollectionStateManager.recomputeOptimisticState`
+ * → `pendingOptimisticDirectUpserts`). Marked rows instead survive until a sync
+ * operation for that key actually lands, which is precisely the semantics a Lunora
+ * custom mutator needs: the server is the linearization point, so the prediction
+ * must stay visible until the authoritative row arrives. Without it, a text edit
+ * visibly reverts to the last synced value the moment the push is acked.
+ *
+ * The literal is pinned here because `@tanstack/db` does not re-export the constant
+ * from its package root (it lives in the unexported
+ * `collection/transaction-metadata` module). `__tests__/define-mutators.test.ts`
+ * reads that module off disk and fails if the upstream value ever changes.
+ */
+declare const DIRECT_TRANSACTION_METADATA_KEY = "__tanstack_db_direct";
+/** 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 generated mutator reference (`api.mutators.sendMessage`), accepted by
+ * {@link defineMutator} in place of a hand-written path string.
+ *
+ * Declared structurally rather than imported from `@lunora/client` so this module
+ * keeps its narrow dependency surface; the shape matches `FunctionReference`, and
+ * the phantom marker carries the server mutator's arg type so the client body's
+ * args are **inferred** instead of restated.
+ */
+interface MutatorReference<TArgs = unknown> {
+  readonly __lunoraPhantom?: {
+    args: TArgs;
+    kind: unknown;
+    returns: unknown;
+  };
+  readonly __lunoraRef: string;
+}
+/** Args type carried by a {@link MutatorReference}. */
+type ArgsOfReference<R> = R extends MutatorReference<infer A> ? A : never;
+/** 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.
+ *
+ * **Pass a generated reference, not a string.** `serverRef: api.mutators.sendMessage`
+ * both binds the path at compile time — a rename, a typo, or a moved file becomes a
+ * type error instead of a mutation that silently fails at runtime — and **infers
+ * `TArgs` from the server mutator's own validators**, so the arg type is declared
+ * once on the server rather than restated in every client body:
+ *
+ * ```ts
+ * // Typed + checked: args inferred from the server mutator.
+ * defineMutator({
+ *     apply: ({ collections }, args) => { … },   // args: { channelId: Id<"channels">; text: string }
+ *     serverRef: api.mutators.sendMessage,
+ * });
+ *
+ * // Escape hatch: a path string still works, but nothing checks it and you must
+ * // restate the args yourself.
+ * defineMutator<{ text: string }>({ apply, serverRef: "mutators:sendMessage" });
+ * ```
+ */
+declare const defineMutator: {
+  <TArgs = Record<string, unknown>>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: string;
+  }): ClientMutatorDef<TArgs>;
+  <R extends MutatorReference<never>>(definition: {
+    apply: (context: ClientMutatorContext, args: ArgsOfReference<R>) => void;
+    serverRef: R;
+  }): ClientMutatorDef<ArgsOfReference<R>>;
+};
+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: a
+   * mutation's overlay is held until the sync stream echoes
+   * `lastMutationId >= clientSeq` (via {@link CheckpointRegistry.resolve}), so the
+   * row never flashes out and back.
+   *
+   * Defaults to the shared per-shard registry for `client` + {@link shardKey}
+   * ({@link getShardCheckpoints}) — the same one
+   * {@link import("./collection-options").lunoraCollectionOptions} defaults to, so
+   * a shard's collections and its mutators gate on one watermark line without the
+   * caller wiring them together. Pass `false` to drop the overlay as soon as the
+   * server accepts the write (the by-value sync diff then converges the synced row
+   * in place).
+   */
+  checkpoints?: CheckpointRegistry | false;
+  /** 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, DIRECT_TRANSACTION_METADATA_KEY as D, MutatorReference as M, BoundMutators as a, ClientMutatorDef as b, bindMutators as c, defineMutator as d };

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

@@ -0,0 +1,148 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-B_2IXvdU.js";
+/**
+ * TanStack DB's "direct transaction" marker.
+ *
+ * A completed transaction's optimistic rows are discarded as **stale** unless
+ * either a synced transaction for the same key is already queued, or the
+ * transaction carried this flag (`CollectionStateManager.recomputeOptimisticState`
+ * → `pendingOptimisticDirectUpserts`). Marked rows instead survive until a sync
+ * operation for that key actually lands, which is precisely the semantics a Lunora
+ * custom mutator needs: the server is the linearization point, so the prediction
+ * must stay visible until the authoritative row arrives. Without it, a text edit
+ * visibly reverts to the last synced value the moment the push is acked.
+ *
+ * The literal is pinned here because `@tanstack/db` does not re-export the constant
+ * from its package root (it lives in the unexported
+ * `collection/transaction-metadata` module). `__tests__/define-mutators.test.ts`
+ * reads that module off disk and fails if the upstream value ever changes.
+ */
+declare const DIRECT_TRANSACTION_METADATA_KEY = "__tanstack_db_direct";
+/** 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 generated mutator reference (`api.mutators.sendMessage`), accepted by
+ * {@link defineMutator} in place of a hand-written path string.
+ *
+ * Declared structurally rather than imported from `@lunora/client` so this module
+ * keeps its narrow dependency surface; the shape matches `FunctionReference`, and
+ * the phantom marker carries the server mutator's arg type so the client body's
+ * args are **inferred** instead of restated.
+ */
+interface MutatorReference<TArgs = unknown> {
+  readonly __lunoraPhantom?: {
+    args: TArgs;
+    kind: unknown;
+    returns: unknown;
+  };
+  readonly __lunoraRef: string;
+}
+/** Args type carried by a {@link MutatorReference}. */
+type ArgsOfReference<R> = R extends MutatorReference<infer A> ? A : never;
+/** 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.
+ *
+ * **Pass a generated reference, not a string.** `serverRef: api.mutators.sendMessage`
+ * both binds the path at compile time — a rename, a typo, or a moved file becomes a
+ * type error instead of a mutation that silently fails at runtime — and **infers
+ * `TArgs` from the server mutator's own validators**, so the arg type is declared
+ * once on the server rather than restated in every client body:
+ *
+ * ```ts
+ * // Typed + checked: args inferred from the server mutator.
+ * defineMutator({
+ *     apply: ({ collections }, args) => { … },   // args: { channelId: Id<"channels">; text: string }
+ *     serverRef: api.mutators.sendMessage,
+ * });
+ *
+ * // Escape hatch: a path string still works, but nothing checks it and you must
+ * // restate the args yourself.
+ * defineMutator<{ text: string }>({ apply, serverRef: "mutators:sendMessage" });
+ * ```
+ */
+declare const defineMutator: {
+  <TArgs = Record<string, unknown>>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: string;
+  }): ClientMutatorDef<TArgs>;
+  <R extends MutatorReference<never>>(definition: {
+    apply: (context: ClientMutatorContext, args: ArgsOfReference<R>) => void;
+    serverRef: R;
+  }): ClientMutatorDef<ArgsOfReference<R>>;
+};
+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: a
+   * mutation's overlay is held until the sync stream echoes
+   * `lastMutationId >= clientSeq` (via {@link CheckpointRegistry.resolve}), so the
+   * row never flashes out and back.
+   *
+   * Defaults to the shared per-shard registry for `client` + {@link shardKey}
+   * ({@link getShardCheckpoints}) — the same one
+   * {@link import("./collection-options").lunoraCollectionOptions} defaults to, so
+   * a shard's collections and its mutators gate on one watermark line without the
+   * caller wiring them together. Pass `false` to drop the overlay as soon as the
+   * server accepts the write (the by-value sync diff then converges the synced row
+   * in place).
+   */
+  checkpoints?: CheckpointRegistry | false;
+  /** 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, DIRECT_TRANSACTION_METADATA_KEY as D, MutatorReference as M, BoundMutators as a, ClientMutatorDef as b, bindMutators as c, defineMutator as d };

package/dist/packem_shared/defineCollections-BCgkk3A6.mjs

@@ -0,0 +1 @@
+import{createCollection as I,safeRandomUUID as R}from"@tanstack/db";import{startOfflineExecutor as U,NonRetriableError as w}from"@tanstack/offline-transactions";import{lunoraCollectionOptions as _}from"./CHECKPOINT_FALLBACK_MS-vBJLOBjX.mjs";import{createOutboxCarrier as b,createOptimisticOnlineDetector as E,OUTBOX_MUTATION_FN_NAME as C,registerOutboxCarrier as M,runOutboxMutation as N}from"./OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const S=(a,K,e={})=>{const c={},p={},l={},y=Object.entries(K);for(const[t,o]of y){const n=o.insert,{config:d,scope:m}=_({client:a,getKey:o.getKey,id:t,list:o.list,...o.load===void 0?{}:{load:o.load},onError:o.onError,scopeBy:o.scopeBy,shardKey:o.shardKey});c[t]=I(d),o.scopeBy!==void 0&&(p[t]=m),n&&(l[t]=async({idempotencyKey:r,transaction:i})=>{for(const[f,x]of i.mutations.entries()){const O=x.modified,F=`${r}:${String(f)}`;try{await N(()=>a.mutation(n.mutation,n.toArgs(O),{mutationId:F}))}catch(u){if(u instanceof w&&e.onWriteRejected)try{e.onWriteRejected({code:u.code,collection:t,error:u,row:O})}catch{}throw u}}})}l[C]=async({transaction:t})=>{const o=t.metadata;if(o){if(o.identity!==a.currentIdentity())throw new w("outbox write dropped: identity changed since it was queued");await N(()=>a.mutation({__lunoraRef:o.functionPath},o.args,{mutationId:o.idempotencyKey,shardKey:o.shardKey}))}};const g=b(),s=U({collections:{...c,[C]:g},mutationFns:l,onlineDetector:E(),...e.onLeadershipChange?{onLeadershipChange:e.onLeadershipChange}:{},...e.onStorageFailure?{onStorageFailure:e.onStorageFailure}:{},onUnknownMutationFn:(t,o)=>{try{e.onWriteRejected?.({code:"UNKNOWN_MUTATION_FN",collection:t,error:new Error(`offline write dropped: mutation "${t}" no longer exists (removed or renamed in a deploy?)`),row:o.mutations[0]?.modified})}catch{}}});M(s,g);const h={};for(const[t,o]of y){const n=o.insert,d=c[t];if(!n||!d)continue;const m=s.createOfflineAction({mutationFnName:t,onMutate:({id:r,input:i})=>{d.insert(n.optimistic(i,r))}});h[t]=r=>{const i=R(),f=m({id:i,input:r});return{id:i,transaction:f}}}return{actions:h,collections:c,executor:s,pendingCount:()=>s.getPendingCount(),scope:p}};export{S as defineCollections};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/db",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.31",
   "description": "TanStack DB binding: typed, live-synced collections and a durable offline outbox over the Lunora client",
   "keywords": [
     "cloudflare",
@@ -40,13 +40,22 @@
       "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.3"
+    "@lunora/client": "1.0.0-alpha.31",
+    "@lunora/errors": "1.0.0-alpha.8"
   },
   "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 };