@lunora/db 0.0.0 → 1.0.0-alpha.10

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

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

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

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

package/dist/packem_shared/defineCollections-BWB7CJzY.mjs

@@ -0,0 +1,105 @@
+import { createCollection } from '@tanstack/db';
+import { startOfflineExecutor, NonRetriableError } from '@tanstack/offline-transactions';
+import { lunoraCollectionOptions } from './createCheckpointRegistry-SvwBczzv.mjs';
+import { createOptimisticOnlineDetector, runOutboxMutation, OUTBOX_MUTATION_FN_NAME } from './OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs';
+
+const defineCollections = (client, defs, options = {}) => {
+  const collections = {};
+  const scope = {};
+  const mutationFns = {};
+  const entries = Object.entries(defs);
+  for (const [name, definition] of entries) {
+    const insert = definition.insert;
+    const { config, scope: scopeFunction } = lunoraCollectionOptions({
+      client,
+      getKey: definition.getKey,
+      id: name,
+      // `AnyDef` erases `list` to `any` (`TList = any`); it's a `FunctionReference` here.
+      list: definition.list,
+      ...definition.load === void 0 ? {} : { load: definition.load },
+      onError: definition.onError,
+      scopeBy: definition.scopeBy
+    });
+    collections[name] = createCollection(config);
+    if (definition.scopeBy !== void 0) {
+      scope[name] = scopeFunction;
+    }
+    if (insert) {
+      mutationFns[name] = async ({ transaction }) => {
+        for (const mutation of transaction.mutations) {
+          const row = mutation.modified;
+          try {
+            await runOutboxMutation(() => client.mutation(insert.mutation, insert.toArgs(row)));
+          } catch (error) {
+            if (error instanceof NonRetriableError && options.onWriteRejected) {
+              try {
+                options.onWriteRejected({ code: error.code, collection: name, error, row });
+              } catch {
+              }
+            }
+            throw error;
+          }
+        }
+      };
+    }
+  }
+  mutationFns[OUTBOX_MUTATION_FN_NAME] = async ({ transaction }) => {
+    const meta = transaction.metadata;
+    if (!meta) {
+      return;
+    }
+    if (meta.identity !== client.currentIdentity()) {
+      throw new NonRetriableError("outbox write dropped: identity changed since it was queued");
+    }
+    await runOutboxMutation(
+      () => client.mutation({ __lunoraRef: meta.functionPath }, meta.args, { mutationId: meta.idempotencyKey, shardKey: meta.shardKey })
+    );
+  };
+  const executor = startOfflineExecutor({
+    collections,
+    mutationFns,
+    onlineDetector: createOptimisticOnlineDetector(),
+    ...options.onLeadershipChange ? { onLeadershipChange: options.onLeadershipChange } : {},
+    ...options.onStorageFailure ? { onStorageFailure: options.onStorageFailure } : {},
+    // A persisted write whose target collection was removed/renamed in a deploy
+    // hits an unregistered mutationFn. The executor drops it as a
+    // NonRetriableError *before* our per-collection `mutationFns` catch runs, so
+    // this hook is the only place to surface it on `onWriteRejected`.
+    onUnknownMutationFn: (name, tx) => {
+      try {
+        options.onWriteRejected?.({
+          code: "UNKNOWN_MUTATION_FN",
+          collection: name,
+          error: new Error(`offline write dropped: mutation "${name}" no longer exists (removed or renamed in a deploy?)`),
+          // Best-effort recovered row: the persisted `modified` shape isn't a
+          // validated `Row`, and a batched transaction surfaces only its first
+          // mutation's row. Enough to describe the dropped write to the user.
+          row: tx.mutations[0]?.modified
+        });
+      } catch {
+      }
+    }
+  });
+  const actions = {};
+  for (const [name, definition] of entries) {
+    const insert = definition.insert;
+    const collection = collections[name];
+    if (!insert || !collection) {
+      continue;
+    }
+    const action = executor.createOfflineAction({
+      mutationFnName: name,
+      onMutate: ({ id, input }) => {
+        collection.insert(insert.optimistic(input, id));
+      }
+    });
+    actions[name] = (input) => {
+      const id = crypto.randomUUID();
+      const transaction = action({ id, input });
+      return { id, transaction };
+    };
+  }
+  return { actions, collections, executor, pendingCount: () => executor.getPendingCount(), scope };
+};
+
+export { defineCollections };

package/package.json

@@ -1,31 +1,66 @@
 {
   "name": "@lunora/db",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.10",
   "description": "TanStack DB binding: typed, live-synced collections and a durable offline outbox over the Lunora client",
-  "license": "FSL-1.1-Apache-2.0",
+  "keywords": [
+    "cloudflare",
+    "durable-objects",
+    "live-query",
+    "lunora",
+    "offline-first",
+    "optimistic-updates",
+    "tanstack-db",
+    "workers"
+  ],
   "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/anolilab/lunora.git",
     "directory": "packages/db"
   },
-  "bugs": {
-    "url": "https://github.com/anolilab/lunora/issues"
-  },
-  "keywords": [
-    "lunora",
-    "cloudflare",
-    "workers",
-    "durable-objects",
-    "tanstack-db",
-    "offline-first",
-    "optimistic-updates",
-    "live-query"
+  "files": [
+    "./dist",
+    "__assets__",
+    "README.md",
+    "LICENSE.md"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./collections": {
+      "types": "./dist/collections/index.d.ts",
+      "import": "./dist/collections/index.mjs"
+    },
+    "./mutators": {
+      "types": "./dist/mutators/index.d.ts",
+      "import": "./dist/mutators/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "@lunora/client": "1.0.0-alpha.10"
+  },
+  "peerDependencies": {
+    "@tanstack/db": "^0.6.0",
+    "@tanstack/offline-transactions": "^1.0.0"
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
 }