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

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { Collection } from '@tanstack/db';
 import { R as Row } from "./packem_shared/collection-options.d-B_2IXvdU.mjs";
 export { b as CHECKPOINT_FALLBACK_MS, type d as CheckpointFallbackEvent, type C as CheckpointRegistry, type e as CheckpointRegistryOptions, type f as CheckpointRegistryStats, type g as CheckpointWatermark, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type h as OutboxExecutor, type i as OutboxMutationMetadata, type S as SyncWriter, c as createCheckpointRegistry, j as createExecutorOutboxSink, k as createOptimisticOnlineDetector, m as getShardCheckpoints, l as lunoraCollectionOptions, n as makeDiffEmit, r as releaseShardCheckpoints, o as runOutboxMutation, s as shardCheckpointStats, t as toMap } from "./packem_shared/collection-options.d-B_2IXvdU.mjs";
 export { type C as CollectionDef, type D as DefineCollectionsOptions, type I as InsertBinding, type L as LunoraDb, type W as WriteRejectedEvent, d as defineCollections } from "./packem_shared/define-collections.d-C6J1Y4Q_.mjs";
-export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, D as DIRECT_TRANSACTION_METADATA_KEY, type M as MutatorReference, c as bindMutators, d as defineMutator } from "./packem_shared/define-mutators.d--WcIPEJa.mjs";
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, D as DIRECT_TRANSACTION_METADATA_KEY, type g as MutatorReference, type M as MutatorRejectedEvent, e as bindMutators, f as defineMutator, i as initMutators } from "./packem_shared/define-mutators.d-BXQN7fju.mjs";
 import '@lunora/client';
 import '@tanstack/offline-transactions';
 /** One row to insert. `_id` may be pre-minted client-side so the optimistic row keys match the persisted one. */

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Collection } from '@tanstack/db';
 import { R as Row } from "./packem_shared/collection-options.d-B_2IXvdU.js";
 export { b as CHECKPOINT_FALLBACK_MS, type d as CheckpointFallbackEvent, type C as CheckpointRegistry, type e as CheckpointRegistryOptions, type f as CheckpointRegistryStats, type g as CheckpointWatermark, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type h as OutboxExecutor, type i as OutboxMutationMetadata, type S as SyncWriter, c as createCheckpointRegistry, j as createExecutorOutboxSink, k as createOptimisticOnlineDetector, m as getShardCheckpoints, l as lunoraCollectionOptions, n as makeDiffEmit, r as releaseShardCheckpoints, o as runOutboxMutation, s as shardCheckpointStats, t as toMap } from "./packem_shared/collection-options.d-B_2IXvdU.js";
 export { type C as CollectionDef, type D as DefineCollectionsOptions, type I as InsertBinding, type L as LunoraDb, type W as WriteRejectedEvent, d as defineCollections } from "./packem_shared/define-collections.d-DAFPHFxr.js";
-export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, D as DIRECT_TRANSACTION_METADATA_KEY, type M as MutatorReference, c as bindMutators, d as defineMutator } from "./packem_shared/define-mutators.d-C_E1q1_B.js";
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, D as DIRECT_TRANSACTION_METADATA_KEY, type g as MutatorReference, type M as MutatorRejectedEvent, e as bindMutators, f as defineMutator, i as initMutators } from "./packem_shared/define-mutators.d-DLP_vYu9.js";
 import '@lunora/client';
 import '@tanstack/offline-transactions';
 /** One row to insert. `_id` may be pre-minted client-side so the optimistic row keys match the persisted one. */

package/dist/index.mjs

@@ -1 +1 @@
-import{applyPlanToCollections as r,applyPlanToDb as i}from"./packem_shared/applyPlanToCollections-C29s6OoX.mjs";import{CHECKPOINT_FALLBACK_MS as a,createCheckpointRegistry as p,getShardCheckpoints as c,lunoraCollectionOptions as l,releaseShardCheckpoints as s,shardCheckpointStats as C}from"./packem_shared/CHECKPOINT_FALLBACK_MS-vBJLOBjX.mjs";import{defineCollections as T}from"./packem_shared/defineCollections-BCgkk3A6.mjs";import{DIRECT_TRANSACTION_METADATA_KEY as x,bindMutators as A,defineMutator as m}from"./packem_shared/DIRECT_TRANSACTION_METADATA_KEY-BxF71ve7.mjs";import{OUTBOX_MUTATION_FN_NAME as E,createExecutorOutboxSink as M,createOptimisticOnlineDetector as _,makeDiffEmit as h,runOutboxMutation as N,toMap as S}from"./packem_shared/OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const t="0.0.0";export{a as CHECKPOINT_FALLBACK_MS,x as DIRECT_TRANSACTION_METADATA_KEY,E as OUTBOX_MUTATION_FN_NAME,t as VERSION,r as applyPlanToCollections,i as applyPlanToDb,A as bindMutators,p as createCheckpointRegistry,M as createExecutorOutboxSink,_ as createOptimisticOnlineDetector,T as defineCollections,m as defineMutator,c as getShardCheckpoints,l as lunoraCollectionOptions,h as makeDiffEmit,s as releaseShardCheckpoints,N as runOutboxMutation,C as shardCheckpointStats,S as toMap};
+import{applyPlanToCollections as r,applyPlanToDb as i}from"./packem_shared/applyPlanToCollections-C29s6OoX.mjs";import{CHECKPOINT_FALLBACK_MS as a,createCheckpointRegistry as p,getShardCheckpoints as c,lunoraCollectionOptions as l,releaseShardCheckpoints as s,shardCheckpointStats as C}from"./packem_shared/CHECKPOINT_FALLBACK_MS-vBJLOBjX.mjs";import{defineCollections as T}from"./packem_shared/defineCollections-BCgkk3A6.mjs";import{DIRECT_TRANSACTION_METADATA_KEY as u,bindMutators as x,defineMutator as A,initMutators as M}from"./packem_shared/DIRECT_TRANSACTION_METADATA_KEY-DDE7m9p9.mjs";import{OUTBOX_MUTATION_FN_NAME as E,createExecutorOutboxSink as _,createOptimisticOnlineDetector as h,makeDiffEmit as N,runOutboxMutation as S,toMap as d}from"./packem_shared/OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const t="0.0.0";export{a as CHECKPOINT_FALLBACK_MS,u as DIRECT_TRANSACTION_METADATA_KEY,E as OUTBOX_MUTATION_FN_NAME,t as VERSION,r as applyPlanToCollections,i as applyPlanToDb,x as bindMutators,p as createCheckpointRegistry,_ as createExecutorOutboxSink,h as createOptimisticOnlineDetector,T as defineCollections,A as defineMutator,c as getShardCheckpoints,M as initMutators,l as lunoraCollectionOptions,N as makeDiffEmit,s as releaseShardCheckpoints,S as runOutboxMutation,C as shardCheckpointStats,d as toMap};

package/dist/mutators/index.d.mts

@@ -1,4 +1,4 @@
-export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, c as bindMutators, d as defineMutator } from "../packem_shared/define-mutators.d--WcIPEJa.mjs";
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, type M as MutatorRejectedEvent, e as bindMutators, f as defineMutator, i as initMutators } from "../packem_shared/define-mutators.d-BXQN7fju.mjs";
 import '@lunora/client';
 import '@tanstack/db';
 import "../packem_shared/collection-options.d-B_2IXvdU.mjs";

package/dist/mutators/index.d.ts

@@ -1,4 +1,4 @@
-export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, c as bindMutators, d as defineMutator } from "../packem_shared/define-mutators.d-C_E1q1_B.js";
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, type M as MutatorRejectedEvent, e as bindMutators, f as defineMutator, i as initMutators } from "../packem_shared/define-mutators.d-DLP_vYu9.js";
 import '@lunora/client';
 import '@tanstack/db';
 import "../packem_shared/collection-options.d-B_2IXvdU.js";

package/dist/mutators/index.mjs

@@ -1 +1 @@
-import{bindMutators as r,defineMutator as e}from"../packem_shared/DIRECT_TRANSACTION_METADATA_KEY-BxF71ve7.mjs";export{r as bindMutators,e as defineMutator};
+import{bindMutators as r,defineMutator as i,initMutators as a}from"../packem_shared/DIRECT_TRANSACTION_METADATA_KEY-DDE7m9p9.mjs";export{r as bindMutators,i as defineMutator,a as initMutators};

package/dist/packem_shared/DIRECT_TRANSACTION_METADATA_KEY-DDE7m9p9.mjs

@@ -0,0 +1 @@
+import{LunoraError as l}from"@lunora/errors";import{createTransaction as g}from"@tanstack/db";import{getShardCheckpoints as w,hasCheckpointsAttached as M}from"./CHECKPOINT_FALLBACK_MS-vBJLOBjX.mjs";import{runOutboxMutation as _}from"./OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const v="__tanstack_db_direct",T="defineMutator: `serverRef` must be a generated mutator reference (api.mutators.*) or a 'namespace:fn' string",k=e=>{const t=typeof e=="string"?e:e?.__lunoraRef;if(typeof t!="string"||t.length===0)throw new l("INTERNAL",T);return t},A=e=>({__lunoraClientMutator:!0,apply:e.apply,serverRef:k(e.serverRef)}),E=(e,t,p)=>{let i=0;const d=()=>(i=Math.max(i,e.confirmedMutationWatermark(t.shardKey))+1,i);let u=Promise.resolve();const h=(r,a)=>{const s=u.then(async()=>{for(let c=0;;c+=1){const o=d(),{applied:n}=await e.callMutator(r,a,{clientSeq:o,shardKey:t.shardKey});if(n)return o;if(c>=32)throw new l("INTERNAL",`lunora: custom mutator "${r}" could not claim a fresh client sequence after ${String(32)} attempts`)}});return u=s.then(()=>{},()=>{}),s},R=()=>{if(t.checkpoints===!1)return;if(t.checkpoints)return t.checkpoints;const r=w(e,t.shardKey);return M(r)?r:void 0},y=(r,a,s,c)=>{const{onWriteRejected:o}=t;o&&r.isPersisted.promise.catch(n=>{const m=n instanceof Error?n:new Error(String(n));try{o({args:c,code:m.code,error:m,mutator:a,serverRef:s})}catch{}})},f={};for(const[r,a]of Object.entries(p))f[r]=s=>{const c=g({autoCommit:!0,metadata:{[v]:!0,serverRef:a.serverRef},mutationFn:async()=>{let o=0;await _(async()=>{o=await h(a.serverRef,s)});const n=R();n&&(n.acknowledge({mutationId:o}),await n.awaitMutationId(o))}});return c.mutate(()=>{a.apply({collections:t.collections},s)}),y(c,r,a.serverRef,s),c};return f},K=()=>({bindMutators:E,defineMutator:A});export{v as DIRECT_TRANSACTION_METADATA_KEY,E as bindMutators,A as defineMutator,K as initMutators};

package/dist/packem_shared/{define-mutators.d-C_E1q1_B.d.ts → define-mutators.d-BXQN7fju.d.mts}

@@ -1,6 +1,6 @@
 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";
+import { C as CheckpointRegistry } from "./collection-options.d-B_2IXvdU.mjs";
 /**
  * TanStack DB's "direct transaction" marker.
  *
@@ -19,10 +19,23 @@ import { C as CheckpointRegistry, R as Row } from "./collection-options.d-B_2IXv
  * reads that module off disk and fails if the upstream value ever changes.
  */
 declare const DIRECT_TRANSACTION_METADATA_KEY = "__tanstack_db_direct";
+/**
+ * A map of wired collections, keyed by the name the optimistic bodies address them
+ * by.
+ *
+ * The row type is `any` on purpose. `Collection<T, string>` is **invariant** in
+ * `T` (its methods both consume and produce rows), so a concrete
+ * `Collection<Doc<"nodes"> & Row>` is NOT assignable to `Collection<Row>` — which
+ * is why the previous `Record<string, Collection<Row, string>>` forced an
+ * `as never` cast on every entry, and left `context.collections.<name>` too
+ * untyped to be worth using. Projects recover the concrete types by binding them
+ * once through {@link initMutators}.
+ */
+type CollectionMap = Record<string, Collection<any, string>>;
 /** The local store a client mutator's optimistic body writes against. */
-interface ClientMutatorContext {
+interface ClientMutatorContext<TCollections extends CollectionMap = CollectionMap> {
   /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
-  collections: Record<string, Collection<Row, string>>;
+  collections: TCollections;
 }
 /**
  * A generated mutator reference (`api.mutators.sendMessage`), accepted by
@@ -41,14 +54,12 @@ interface MutatorReference<TArgs = 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> {
+interface ClientMutatorDef<TArgs, TCollections extends CollectionMap = CollectionMap> {
   /** 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;
+  apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
   /** The Lunora function path of the server-authoritative mutator (`defineMutator` on the server). */
   serverRef: string;
 }
@@ -75,22 +86,47 @@ interface ClientMutatorDef<TArgs> {
  * // restate the args yourself.
  * defineMutator<{ text: string }>({ apply, serverRef: "mutators:sendMessage" });
  * ```
+ *
+ * `context.collections` is typed by whatever map it is bound to — which for this
+ * standalone form is the widest one. Bind the concrete collections once with
+ * {@link initMutators} to get `collections.&lt;name>` typed inside `apply`.
  */
 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>>;
+  <TArgs>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: MutatorReference<TArgs>;
+  }): 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 {
+/**
+ * A mutator map whose defs are bound to `TCollections`, arg types erased — the
+ * `TCollections`-pinned counterpart of {@link AnyMutatorMap}, and `any` for the
+ * same variance reason.
+ */
+type MutatorMapFor<TCollections extends CollectionMap> = Record<string, ClientMutatorDef<any, TCollections>>;
+type AnyMutatorMap = Record<string, ClientMutatorDef<any, any>>;
+/** Args type of a mutator definition, whatever collections map it was bound to. */
+type ArgsOf<M> = M extends ClientMutatorDef<infer A, infer _C> ? A : never;
+/** A mutator write that was permanently rejected, passed to {@link BindMutatorsContext.onWriteRejected}. */
+interface MutatorRejectedEvent {
+  /** The args the rejected call was made with. */
+  args: unknown;
+  /**
+   * The machine-readable reason when the server supplied one (e.g. `CONFLICT`,
+   * `FORBIDDEN`). Mirrors {@link import("./define-collections").WriteRejectedEvent.code}.
+   */
+  code?: string;
+  /** The error that rejected the write. */
+  error: Error;
+  /** The bound mutator's key in the map passed to `bindMutators`. */
+  mutator: string;
+  /** The `namespace:fn` path the push targeted. */
+  serverRef: string;
+}
+interface BindMutatorsContext<TCollections extends CollectionMap = CollectionMap> {
   /**
    * Resolves the optimistic-overlay drop against confirmed server watermarks: a
    * mutation's overlay is held until the sync stream echoes
@@ -107,7 +143,24 @@ interface BindMutatorsContext {
    */
   checkpoints?: CheckpointRegistry | false;
   /** The wired collections the optimistic bodies write against. */
-  collections: Record<string, Collection<Row, string>>;
+  collections: TCollections;
+  /**
+   * Called when a mutator's server push is permanently rejected — the aggregate
+   * failure channel for writes, symmetric with
+   * {@link import("./define-collections").DefineCollectionsOptions.onWriteRejected}
+   * on the outbox path.
+   *
+   * Supplying it also makes a **fire-and-forget** call safe: a bound handle
+   * returns a `Transaction` whose `isPersisted` promise rejects on failure, so a
+   * caller that neither awaits it nor attaches a `.catch` leaves an unhandled
+   * rejection. With this hook set, `bindMutators` consumes that rejection itself
+   * after reporting it — a caller that DOES await still sees the rejection, so
+   * per-call handling is unaffected.
+   *
+   * A throwing listener is swallowed: reporting a failure must not manufacture a
+   * second one.
+   */
+  onWriteRejected?: (event: MutatorRejectedEvent) => void;
   /** Optional shard key the mutator's server push is routed to. */
   shardKey?: string;
 }
@@ -144,5 +197,39 @@ type BoundMutators<M extends AnyMutatorMap> = { [K in keyof M]: (args: ArgsOf<M[
  * 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 };
+declare const bindMutators: <M extends AnyMutatorMap, TCollections extends CollectionMap = CollectionMap>(client: LunoraClient, context: BindMutatorsContext<TCollections>, mutators: M) => BoundMutators<M>;
+/** `defineMutator` + `bindMutators`, both bound to one project's collections map. */
+interface BoundMutatorApi<TCollections extends CollectionMap> {
+  /** {@link bindMutators}, with `collections` pinned to `TCollections`. */
+  bindMutators: <M extends MutatorMapFor<TCollections>>(client: LunoraClient, context: BindMutatorsContext<TCollections>, mutators: M) => BoundMutators<M>;
+  /** {@link defineMutator}, with `context.collections` typed as `TCollections`. */
+  defineMutator: {
+    <TArgs = Record<string, unknown>>(definition: {
+      apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
+      serverRef: string;
+    }): ClientMutatorDef<TArgs, TCollections>;
+    <TArgs>(definition: {
+      apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
+      serverRef: MutatorReference<TArgs>;
+    }): ClientMutatorDef<TArgs, TCollections>;
+  };
+}
+/**
+ * Bind the mutator surface to **this project's** collections map, once.
+ *
+ * `Collection` is invariant in its row type, so a shared
+ * `Record&lt;string, Collection&lt;Row, string>>` could neither accept a generated
+ * collection without an `as never` cast nor hand a usable type back to `apply` —
+ * which is why optimistic bodies tended to ignore `context.collections` and close
+ * over module-scope collection variables instead. Declaring the map once here
+ * fixes both ends: `bindMutators` takes the concrete collections cast-free, and
+ * `apply` reads `collections.&lt;name>` at its real row type.
+ *
+ * Runtime-identical to the standalone {@link defineMutator} / {@link bindMutators}
+ * (this returns those very functions); only the types narrow.
+ * @example
+ * const { bindMutators, defineMutator } = initMutators&lt;{ nodes: typeof wholeOutlineCollection }>();
+ * const setText = defineMutator({ apply: ({ collections }, args) => collections.nodes.update(args.id, setter), serverRef: api.mutators.setText });
+ */
+declare const initMutators: <TCollections extends CollectionMap>() => BoundMutatorApi<TCollections>;
+export { BindMutatorsContext as B, ClientMutatorContext as C, DIRECT_TRANSACTION_METADATA_KEY as D, MutatorRejectedEvent as M, BoundMutatorApi as a, BoundMutators as b, ClientMutatorDef as c, CollectionMap as d, bindMutators as e, defineMutator as f, MutatorReference as g, initMutators as i };

package/dist/packem_shared/{define-mutators.d--WcIPEJa.d.mts → define-mutators.d-DLP_vYu9.d.ts}

@@ -1,6 +1,6 @@
 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";
+import { C as CheckpointRegistry } from "./collection-options.d-B_2IXvdU.js";
 /**
  * TanStack DB's "direct transaction" marker.
  *
@@ -19,10 +19,23 @@ import { C as CheckpointRegistry, R as Row } from "./collection-options.d-B_2IXv
  * reads that module off disk and fails if the upstream value ever changes.
  */
 declare const DIRECT_TRANSACTION_METADATA_KEY = "__tanstack_db_direct";
+/**
+ * A map of wired collections, keyed by the name the optimistic bodies address them
+ * by.
+ *
+ * The row type is `any` on purpose. `Collection<T, string>` is **invariant** in
+ * `T` (its methods both consume and produce rows), so a concrete
+ * `Collection<Doc<"nodes"> & Row>` is NOT assignable to `Collection<Row>` — which
+ * is why the previous `Record<string, Collection<Row, string>>` forced an
+ * `as never` cast on every entry, and left `context.collections.<name>` too
+ * untyped to be worth using. Projects recover the concrete types by binding them
+ * once through {@link initMutators}.
+ */
+type CollectionMap = Record<string, Collection<any, string>>;
 /** The local store a client mutator's optimistic body writes against. */
-interface ClientMutatorContext {
+interface ClientMutatorContext<TCollections extends CollectionMap = CollectionMap> {
   /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
-  collections: Record<string, Collection<Row, string>>;
+  collections: TCollections;
 }
 /**
  * A generated mutator reference (`api.mutators.sendMessage`), accepted by
@@ -41,14 +54,12 @@ interface MutatorReference<TArgs = 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> {
+interface ClientMutatorDef<TArgs, TCollections extends CollectionMap = CollectionMap> {
   /** 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;
+  apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
   /** The Lunora function path of the server-authoritative mutator (`defineMutator` on the server). */
   serverRef: string;
 }
@@ -75,22 +86,47 @@ interface ClientMutatorDef<TArgs> {
  * // restate the args yourself.
  * defineMutator<{ text: string }>({ apply, serverRef: "mutators:sendMessage" });
  * ```
+ *
+ * `context.collections` is typed by whatever map it is bound to — which for this
+ * standalone form is the widest one. Bind the concrete collections once with
+ * {@link initMutators} to get `collections.&lt;name>` typed inside `apply`.
  */
 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>>;
+  <TArgs>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: MutatorReference<TArgs>;
+  }): 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 {
+/**
+ * A mutator map whose defs are bound to `TCollections`, arg types erased — the
+ * `TCollections`-pinned counterpart of {@link AnyMutatorMap}, and `any` for the
+ * same variance reason.
+ */
+type MutatorMapFor<TCollections extends CollectionMap> = Record<string, ClientMutatorDef<any, TCollections>>;
+type AnyMutatorMap = Record<string, ClientMutatorDef<any, any>>;
+/** Args type of a mutator definition, whatever collections map it was bound to. */
+type ArgsOf<M> = M extends ClientMutatorDef<infer A, infer _C> ? A : never;
+/** A mutator write that was permanently rejected, passed to {@link BindMutatorsContext.onWriteRejected}. */
+interface MutatorRejectedEvent {
+  /** The args the rejected call was made with. */
+  args: unknown;
+  /**
+   * The machine-readable reason when the server supplied one (e.g. `CONFLICT`,
+   * `FORBIDDEN`). Mirrors {@link import("./define-collections").WriteRejectedEvent.code}.
+   */
+  code?: string;
+  /** The error that rejected the write. */
+  error: Error;
+  /** The bound mutator's key in the map passed to `bindMutators`. */
+  mutator: string;
+  /** The `namespace:fn` path the push targeted. */
+  serverRef: string;
+}
+interface BindMutatorsContext<TCollections extends CollectionMap = CollectionMap> {
   /**
    * Resolves the optimistic-overlay drop against confirmed server watermarks: a
    * mutation's overlay is held until the sync stream echoes
@@ -107,7 +143,24 @@ interface BindMutatorsContext {
    */
   checkpoints?: CheckpointRegistry | false;
   /** The wired collections the optimistic bodies write against. */
-  collections: Record<string, Collection<Row, string>>;
+  collections: TCollections;
+  /**
+   * Called when a mutator's server push is permanently rejected — the aggregate
+   * failure channel for writes, symmetric with
+   * {@link import("./define-collections").DefineCollectionsOptions.onWriteRejected}
+   * on the outbox path.
+   *
+   * Supplying it also makes a **fire-and-forget** call safe: a bound handle
+   * returns a `Transaction` whose `isPersisted` promise rejects on failure, so a
+   * caller that neither awaits it nor attaches a `.catch` leaves an unhandled
+   * rejection. With this hook set, `bindMutators` consumes that rejection itself
+   * after reporting it — a caller that DOES await still sees the rejection, so
+   * per-call handling is unaffected.
+   *
+   * A throwing listener is swallowed: reporting a failure must not manufacture a
+   * second one.
+   */
+  onWriteRejected?: (event: MutatorRejectedEvent) => void;
   /** Optional shard key the mutator's server push is routed to. */
   shardKey?: string;
 }
@@ -144,5 +197,39 @@ type BoundMutators<M extends AnyMutatorMap> = { [K in keyof M]: (args: ArgsOf<M[
  * 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 };
+declare const bindMutators: <M extends AnyMutatorMap, TCollections extends CollectionMap = CollectionMap>(client: LunoraClient, context: BindMutatorsContext<TCollections>, mutators: M) => BoundMutators<M>;
+/** `defineMutator` + `bindMutators`, both bound to one project's collections map. */
+interface BoundMutatorApi<TCollections extends CollectionMap> {
+  /** {@link bindMutators}, with `collections` pinned to `TCollections`. */
+  bindMutators: <M extends MutatorMapFor<TCollections>>(client: LunoraClient, context: BindMutatorsContext<TCollections>, mutators: M) => BoundMutators<M>;
+  /** {@link defineMutator}, with `context.collections` typed as `TCollections`. */
+  defineMutator: {
+    <TArgs = Record<string, unknown>>(definition: {
+      apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
+      serverRef: string;
+    }): ClientMutatorDef<TArgs, TCollections>;
+    <TArgs>(definition: {
+      apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
+      serverRef: MutatorReference<TArgs>;
+    }): ClientMutatorDef<TArgs, TCollections>;
+  };
+}
+/**
+ * Bind the mutator surface to **this project's** collections map, once.
+ *
+ * `Collection` is invariant in its row type, so a shared
+ * `Record&lt;string, Collection&lt;Row, string>>` could neither accept a generated
+ * collection without an `as never` cast nor hand a usable type back to `apply` —
+ * which is why optimistic bodies tended to ignore `context.collections` and close
+ * over module-scope collection variables instead. Declaring the map once here
+ * fixes both ends: `bindMutators` takes the concrete collections cast-free, and
+ * `apply` reads `collections.&lt;name>` at its real row type.
+ *
+ * Runtime-identical to the standalone {@link defineMutator} / {@link bindMutators}
+ * (this returns those very functions); only the types narrow.
+ * @example
+ * const { bindMutators, defineMutator } = initMutators&lt;{ nodes: typeof wholeOutlineCollection }>();
+ * const setText = defineMutator({ apply: ({ collections }, args) => collections.nodes.update(args.id, setter), serverRef: api.mutators.setText });
+ */
+declare const initMutators: <TCollections extends CollectionMap>() => BoundMutatorApi<TCollections>;
+export { BindMutatorsContext as B, ClientMutatorContext as C, DIRECT_TRANSACTION_METADATA_KEY as D, MutatorRejectedEvent as M, BoundMutatorApi as a, BoundMutators as b, ClientMutatorDef as c, CollectionMap as d, bindMutators as e, defineMutator as f, MutatorReference as g, initMutators as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/db",
-  "version": "1.0.0-alpha.31",
+  "version": "1.0.0-alpha.32",
   "description": "TanStack DB binding: typed, live-synced collections and a durable offline outbox over the Lunora client",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/DIRECT_TRANSACTION_METADATA_KEY-BxF71ve7.mjs

@@ -1 +0,0 @@
-import{LunoraError as l}from"@lunora/errors";import{createTransaction as y}from"@tanstack/db";import{getShardCheckpoints as R,hasCheckpointsAttached as M}from"./CHECKPOINT_FALLBACK_MS-vBJLOBjX.mjs";import{runOutboxMutation as _}from"./OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const w="__tanstack_db_direct",A="defineMutator: `serverRef` must be a generated mutator reference (api.mutators.*) or a 'namespace:fn' string",g=e=>{const t=typeof e=="string"?e:e?.__lunoraRef;if(typeof t!="string"||t.length===0)throw new l("INTERNAL",A);return t},E=e=>({__lunoraClientMutator:!0,apply:e.apply,serverRef:g(e.serverRef)}),I=(e,t,m)=>{let c=0;const p=()=>(c=Math.max(c,e.confirmedMutationWatermark(t.shardKey))+1,c);let u=Promise.resolve();const d=(r,o)=>{const a=u.then(async()=>{for(let s=0;;s+=1){const n=p(),{applied:i}=await e.callMutator(r,o,{clientSeq:n,shardKey:t.shardKey});if(i)return n;if(s>=32)throw new l("INTERNAL",`lunora: custom mutator "${r}" could not claim a fresh client sequence after ${String(32)} attempts`)}});return u=a.then(()=>{},()=>{}),a},h=()=>{if(t.checkpoints===!1)return;if(t.checkpoints)return t.checkpoints;const r=R(e,t.shardKey);return M(r)?r:void 0},f={};for(const[r,o]of Object.entries(m))f[r]=a=>{const s=y({autoCommit:!0,metadata:{[w]:!0,serverRef:o.serverRef},mutationFn:async()=>{let n=0;await _(async()=>{n=await d(o.serverRef,a)});const i=h();i&&(i.acknowledge({mutationId:n}),await i.awaitMutationId(n))}});return s.mutate(()=>{o.apply({collections:t.collections},a)}),s};return f};export{w as DIRECT_TRANSACTION_METADATA_KEY,I as bindMutators,E as defineMutator};