@lunora/db 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/collection-options.d-lJBOVJgq.d.ts

@@ -0,0 +1,216 @@
+import { OutboxSink, LunoraClient, FunctionReference, SubscriptionError } from '@lunora/client';
+import { CollectionConfig } from '@tanstack/db';
+import { OnlineDetector } from '@tanstack/offline-transactions';
+/**
+* Reserved `mutationFns` key the unified outbox routes raw `client.mutation`
+* offline writes through. `defineCollections` registers a handler under this
+* name that reads `transaction.metadata` (functionPath + args) and replays the
+* write, so a db app's direct mutations ride the same durable executor as its
+* collection inserts instead of the standalone {@link OutboxSink} fallback.
+*/
+declare const OUTBOX_MUTATION_FN_NAME = "__lunora_outbox__";
+/** The metadata an outbox-routed transaction carries so its replay can call `client.mutation`. */
+interface OutboxMutationMetadata extends Record<string, unknown> {
+  args: Record<string, unknown>;
+  clientId: string;
+  functionPath: string;
+  /** Stable `${clientId}:${mutationId}` replay key; passed back as the mutation id so a committed-but-unacked replay is server-idempotent. */
+  idempotencyKey: string;
+  /** Issuing identity fingerprint; the replay handler drops the write when it no longer matches. */
+  identity: string | null;
+  mutationId: number;
+  shardKey?: string;
+}
+/** A committable outbox transaction handle (the `OfflineTransaction` the executor mints). */
+interface OutboxTransaction {
+  mutate: (callback: () => void) => unknown;
+}
+/**
+* The slice of the TanStack `OfflineExecutor` the {@link createExecutorOutboxSink}
+* drives. Declared structurally so `@lunora/db`'s outbox glue doesn't widen its
+* coupling to the executor's full surface (and stays unit-testable with a fake).
+*/
+interface OutboxExecutor {
+  createOfflineTransaction: (options: {
+    autoCommit?: boolean;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+    mutationFnName: string;
+  }) => OutboxTransaction;
+  getPendingCount: () => number;
+}
+/** Tuning for {@link createExecutorOutboxSink}. */
+interface ExecutorOutboxSinkOptions {
+  /** Max persisted-but-unconfirmed writes before `enqueue` rejects with `OFFLINE_QUEUE_OVERFLOW` (default 1000, matching `OfflineQueue`). */
+  maxItems?: number;
+  /** `mutationFns` key the replay handler is registered under (default {@link OUTBOX_MUTATION_FN_NAME}). */
+  mutationFnName?: string;
+}
+/**
+* The blessed {@link OutboxSink} over the TanStack `OfflineExecutor` — the single
+* durable write path for a `@lunora/db` app. It persists each offline write as an
+* executor transaction carrying the `client.mutation` target in `metadata`, then
+* ports the two semantics the executor lacks vs the built-in `OfflineQueue`.
+*
+* First: a `maxItems` cap that **rejects** a new write at capacity with an
+* `OFFLINE_QUEUE_OVERFLOW`-coded error — the {@link OutboxSink} contract, matching
+* `OfflineQueue`. Rejecting (rather than evicting the oldest) preserves the
+* at-least-once promise: an already-persisted write is never silently dropped, and
+* the caller surfaces back-pressure to the issuing mutation (which rolls its
+* optimistic write back).
+* Second: the identity guard lives in the replay handler (`defineCollections`), which drops a write whose captured `identity` no longer matches — see {@link OutboxMutationMetadata}.
+*/
+declare const createExecutorOutboxSink: (executor: OutboxExecutor, options?: ExecutorOutboxSinkOptions) => OutboxSink;
+/** A row carrying the Lunora document id. */
+type Row = Record<string, unknown> & {
+  _id: string;
+};
+/** The subset of a TanStack DB sync write channel that {@link makeDiffEmit} drives. */
+interface SyncWriter<T extends object> {
+  begin: () => void;
+  commit: () => void;
+  write: (message: {
+    type: "insert" | "update";
+    value: T;
+  } | {
+    key: string;
+    type: "delete";
+  }) => void;
+}
+/** Index a row list into a keyed map. */
+declare const toMap: <T extends object>(rows: ReadonlyArray<T>, getKey: (row: T) => string) => Map<string, T>;
+/**
+* Build an `emit(next)` that diffs a desired keyed snapshot into a collection's
+* sync channel — only changed rows are written, so a reconnect snapshot or a
+* scope change never churns the synced view out from under a pending optimistic
+* row. The last-synced base is tracked in `syncedJson`.
+*
+* Change detection compares rows by `JSON.stringify`, which is key-order
+* sensitive — safe here because server snapshots have stable column order
+* across reconnects (same query projection). A sync source with unstable key
+* ordering would need a structural compare instead.
+*
+* `syncedJson` holds the JSON-serialized form of each last-synced row, keyed
+* by row id. It is the **sole** synced-state map — no parallel row-object map
+* is kept. Each incoming value is serialized exactly once per tick (for both
+* comparison and cache update), so the previous value is never re-serialized.
+*
+* Lifecycle: `syncedJson` must be owned by the caller at the same scope as any
+* other per-collection state (e.g. outside the `sync.sync` callback), so the
+* cache persists correctly across sync restarts. A new `makeDiffEmit` closure
+* created on restart receives the same map reference and starts from the
+* committed synced state — no spurious diffs on reconnect.
+*/
+declare const makeDiffEmit: <T extends object>(syncedJson: Map<string, string>, writer: SyncWriter<T>) => (next: Map<string, T>) => void;
+/**
+* Run a Lunora mutation under the outbox's retry policy.
+*
+* The retryable/permanent split keys on whether the failure carries a server
+* application error `code` (set by `@lunora/client`'s rpc when the server returns
+* a `{ error: { code, … } }` envelope — validation, conflict, etc.). A coded
+* error is a definite verdict: surface it as a `NonRetriableError` so the executor
+* stops and TanStack DB rolls the optimistic insert back. Everything without a
+* code is transient — a `fetch` network failure (`TypeError`) or an HTTP/infra
+* blip the rpc surfaces as a code-less `Error` (a 5xx gateway page, a non-JSON
+* body) — so it's rethrown as-is and the durable outbox replays it. Keying on
+* `error instanceof TypeError` alone would wrongly drop the latter.
+*/
+declare const runOutboxMutation: (mutate: () => Promise<unknown>) => Promise<void>;
+/**
+* An "always attempt" online detector. We deliberately don't trust
+* `navigator.onLine`: some environments (and Playwright's `setOffline` under
+* Firefox) leave it stuck, which would freeze the outbox. Instead the executor
+* always tries the send and {@link runOutboxMutation}'s transient-error retry
+* handles real offline; the periodic tick nudges the executor to drain the outbox
+* so a queued write replays promptly once connectivity returns.
+*
+* `isOnline` is therefore intentionally always `true` — it gates the executor's
+* attempts, not a UI signal. A consumer that wants to show real connectivity
+* should read `navigator.onLine` itself, separately from this detector.
+*/
+declare const createOptimisticOnlineDetector: () => OnlineDetector;
+/**
+* Resolves the TanStack optimistic-overlay drop against the server's confirmed
+* watermarks. A mutator's optimistic transaction returns `awaitMutationId(id)`
+* (or `awaitCheckpoint(cursor)`); TanStack keeps the overlay until that promise
+* settles, so the row de-duplicates exactly as the synced server value lands — no
+* flash of the optimistic row disappearing then reappearing.
+*
+* `resolve` is called by whoever owns the watermark stream — a `data`/`delta`
+* frame's `lastMutationId`, or a shape poke's `checkpoint` — to advance the gates.
+*/
+interface CheckpointRegistry {
+  /** Resolve once the server has acknowledged the op-log `cursor`. */
+  awaitCheckpoint: (cursor: number) => Promise<void>;
+  /** Resolve once the server has echoed a `lastMutationId >= id` for this client. */
+  awaitMutationId: (id: number) => Promise<void>;
+  /** Advance the gates from a frame's watermark; later callers past the mark settle immediately. */
+  resolve: (watermark: {
+    checkpoint?: number;
+    mutationId?: number;
+  }) => void;
+}
+/** A standalone checkpoint/mutation-id registry (also embedded in {@link lunoraCollectionOptions}). */
+declare const createCheckpointRegistry: () => CheckpointRegistry;
+/**
+* A replication-shape sync source (the local-first partial-replication path).
+* Mutually exclusive with {@link LunoraCollectionConfig.list}: the collection
+* live-syncs the named shape's rowset via the client's poke protocol
+* (`subscribeShape`) instead of a full-table `list` query subscription.
+*/
+interface ShapeSource {
+  /** Validated shape parameters (the partition selector — e.g. `{ channelId }`). */
+  args?: Record<string, unknown>;
+  /** The `defineShape` export name registered in `LUNORA_SHAPES`. */
+  name: string;
+  /** Routes the subscription to a specific shard's DO when the table is sharded. */
+  shardKey?: string;
+}
+/** Declarative inputs for {@link lunoraCollectionOptions}. */
+interface LunoraCollectionConfig<TRow extends Row> {
+  /** The Lunora client to subscribe through. */
+  client: LunoraClient;
+  /** Row key extractor — defaults to `row._id`. */
+  getKey?: (row: TRow) => string;
+  /** Collection id (TanStack identity) — defaults to the `list` function path (or `shape:` + the shape name). */
+  id?: string;
+  /** The Lunora query that lists the rows (the full-table sync source). Mutually exclusive with {@link LunoraCollectionConfig.shape}. */
+  list?: FunctionReference;
+  /**
+  * When the collection starts syncing. `"lazy"` (default) starts on the first
+  * `useLiveQuery` subscriber; `"eager"` starts at creation (TanStack's
+  * `startSync`) — for small "instant" reference data you want warm at boot.
+  * No effect on a `scopeBy` collection, which has nothing to sync until scoped.
+  * (Even eager, TanStack pauses sync while there are no subscribers, per its
+  * `gcTime` lifecycle — "warm while referenced", not pinned forever.)
+  */
+  load?: "eager" | "lazy";
+  /** Notified when the underlying subscription errors; the collection always leaves `loading` regardless. */
+  onError?: (error: SubscriptionError) => void;
+  /** When set, the collection stays empty until {@link LunoraCollectionOptions.scope} points it at args (sharded). */
+  scopeBy?: string;
+  /** A replication shape as the sync source (partial replication). Mutually exclusive with {@link LunoraCollectionConfig.list}. */
+  shape?: ShapeSource;
+}
+/** The result of {@link lunoraCollectionOptions}: a TanStack collection config plus its sync controls. */
+interface LunoraCollectionOptions<TRow extends Row> {
+  /** Resolves optimistic-overlay drops against the server's confirmed watermarks. */
+  checkpoints: CheckpointRegistry;
+  /** Pass to TanStack's `createCollection`. */
+  config: CollectionConfig<TRow, string>;
+  /** Re-point a `scopeBy` collection's subscription (omit `args` to detach). No-op for unscoped collections. */
+  scope: (args?: Record<string, unknown>) => void;
+}
+/**
+* Build a TanStack DB collection config (+ sync controls) that live-syncs a
+* Lunora `list` query through the client. This is the reusable core lifted out of
+* {@link import("./define-collections").defineCollections}: the same `makeDiffEmit`
+* diff-into-channel, `autoIndex:"eager"` + B-tree indexes, scoped-resubscribe, and
+* fail-safe `markReady`-on-error behavior, exposed as a standalone
+* collection-options creator so apps (and codegen) can compose it directly.
+*
+* The returned `checkpoints` registry lets a mutator runtime resolve optimistic
+* overlays against confirmed server watermarks (see {@link CheckpointRegistry}).
+*/
+declare const lunoraCollectionOptions: <TRow extends Row>(options: LunoraCollectionConfig<TRow>) => LunoraCollectionOptions<TRow>;
+export { CheckpointRegistry as C, ExecutorOutboxSinkOptions as E, LunoraCollectionConfig as L, OUTBOX_MUTATION_FN_NAME as O, Row as R, SyncWriter as S, LunoraCollectionOptions as a, OutboxExecutor as b, createCheckpointRegistry as c, OutboxMutationMetadata as d, createExecutorOutboxSink as e, createOptimisticOnlineDetector as f, lunoraCollectionOptions as l, makeDiffEmit as m, runOutboxMutation as r, toMap as t };

package/dist/packem_shared/createCheckpointRegistry-SvwBczzv.mjs

@@ -0,0 +1,127 @@
+import { BTreeIndex } from '@tanstack/db';
+import { toMap, makeDiffEmit } from './OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs';
+
+const createGate = () => {
+  let highest = Number.NEGATIVE_INFINITY;
+  const waiters = [];
+  return {
+    advance: (value) => {
+      if (value <= highest) {
+        return;
+      }
+      highest = value;
+      for (let index = waiters.length - 1; index >= 0; index -= 1) {
+        const waiter = waiters[index];
+        if (waiter && waiter.threshold <= highest) {
+          waiter.resolve();
+          waiters.splice(index, 1);
+        }
+      }
+    },
+    await: (threshold) => {
+      if (threshold <= highest) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => {
+        waiters.push({ resolve, threshold });
+      });
+    }
+  };
+};
+const createCheckpointRegistry = () => {
+  const checkpointGate = createGate();
+  const mutationGate = createGate();
+  return {
+    awaitCheckpoint: (cursor) => checkpointGate.await(cursor),
+    awaitMutationId: (id) => mutationGate.await(id),
+    resolve: ({ checkpoint, mutationId }) => {
+      if (checkpoint !== void 0) {
+        checkpointGate.advance(checkpoint);
+      }
+      if (mutationId !== void 0) {
+        mutationGate.advance(mutationId);
+      }
+    }
+  };
+};
+const lunoraCollectionOptions = (options) => {
+  if (options.list === void 0 === (options.shape === void 0)) {
+    throw new Error("lunoraCollectionOptions: pass exactly one of `list` or `shape`");
+  }
+  const getKey = options.getKey ?? ((row) => row._id);
+  const checkpoints = createCheckpointRegistry();
+  const syncedJson = /* @__PURE__ */ new Map();
+  let emit;
+  let unsubscribe;
+  let onErrorHandler;
+  const openSubscription = (args, onReady) => {
+    const onRows = (data) => {
+      emit?.(toMap(data, getKey));
+      onReady?.();
+      if (options.shape === void 0) {
+        checkpoints.resolve({ mutationId: options.client.confirmedMutationWatermark() });
+      }
+    };
+    const onError = (error) => onErrorHandler?.(error);
+    const onCheckpoint = (watermark) => {
+      checkpoints.resolve(watermark);
+    };
+    if (options.shape !== void 0) {
+      return options.client.subscribeShape({ args, name: options.shape.name }, onRows, {
+        onCheckpoint,
+        onError,
+        shardKey: options.shape.shardKey
+      });
+    }
+    return options.client.subscribe(options.list, args, onRows, { onCheckpoint, onError });
+  };
+  const config = {
+    // Auto-build ordered (B-tree) indexes for whatever the app's live queries
+    // join / filter / sort on, so they stay fast as the dataset grows.
+    autoIndex: "eager",
+    defaultIndexType: BTreeIndex,
+    getKey,
+    id: options.id ?? options.list?.__lunoraRef ?? `shape:${options.shape?.name ?? ""}`,
+    // `"eager"` syncs at creation; omitted otherwise so the wire stays
+    // byte-identical to the lazy default (sync on first subscriber).
+    ...options.load === "eager" ? { startSync: true } : {},
+    sync: {
+      sync: (writer) => {
+        emit = makeDiffEmit(syncedJson, writer);
+        const onError = (error) => {
+          writer.markReady();
+          options.onError?.(error);
+        };
+        onErrorHandler = onError;
+        if (options.scopeBy === void 0) {
+          unsubscribe = openSubscription(options.shape?.args ?? {}, () => {
+            writer.markReady();
+          });
+        } else {
+          writer.markReady();
+        }
+        return () => {
+          emit = void 0;
+          onErrorHandler = void 0;
+          unsubscribe?.();
+          unsubscribe = void 0;
+        };
+      }
+    }
+  };
+  const scope = (args) => {
+    if (options.scopeBy === void 0) {
+      return;
+    }
+    unsubscribe?.();
+    unsubscribe = void 0;
+    emit?.(/* @__PURE__ */ new Map());
+    if (args === void 0) {
+      return;
+    }
+    unsubscribe = openSubscription(args, void 0);
+  };
+  return { checkpoints, config, scope };
+};
+
+export { createCheckpointRegistry, lunoraCollectionOptions };

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

@@ -0,0 +1,159 @@
+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-lJBOVJgq.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;
+}
+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-collections.d-Cc1p0x3t.d.mts

@@ -0,0 +1,159 @@
+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-lJBOVJgq.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;
+}
+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 };