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

package/dist/packem_shared/define-collections.d-CK7jEXQJ.d.mts

@@ -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.mjs";
+/** 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<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-D51n_r1n.d.mts

@@ -0,0 +1,235 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry } 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";
+/**
+ * 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<TCollections extends CollectionMap = CollectionMap> {
+  /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
+  collections: TCollections;
+}
+/**
+ * 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;
+}
+/** A client-side custom mutator: an optimistic body plus the path of its authoritative server impl. */
+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<TCollections>, 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" });
+ * ```
+ *
+ * `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.<name>` typed inside `apply`.
+ */
+declare const defineMutator: {
+  <TArgs = Record<string, unknown>>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: string;
+  }): ClientMutatorDef<TArgs>;
+  <TArgs>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: MutatorReference<TArgs>;
+  }): ClientMutatorDef<TArgs>;
+};
+/**
+ * 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
+   * `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: 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;
+}
+/** 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, 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<string, Collection<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.<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<{ 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-DuAmdkYR.d.ts

@@ -0,0 +1,235 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry } 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";
+/**
+ * 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<TCollections extends CollectionMap = CollectionMap> {
+  /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
+  collections: TCollections;
+}
+/**
+ * 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;
+}
+/** A client-side custom mutator: an optimistic body plus the path of its authoritative server impl. */
+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<TCollections>, 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" });
+ * ```
+ *
+ * `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.<name>` typed inside `apply`.
+ */
+declare const defineMutator: {
+  <TArgs = Record<string, unknown>>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: string;
+  }): ClientMutatorDef<TArgs>;
+  <TArgs>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: MutatorReference<TArgs>;
+  }): ClientMutatorDef<TArgs>;
+};
+/**
+ * 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
+   * `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: 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;
+}
+/** 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, 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<string, Collection<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.<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<{ 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/defineCollections-4CPSF9OJ.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-6GmTGWsH.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};