effect-zero 0.7.0 → 0.9.0

package/src/client.ts

@@ -1,79 +1,182 @@
-import { Zero, type ZeroOptions, type Schema as ZeroSchema, type Transaction as ZeroTransaction } from "@rocicorp/zero";
-import * as Cause from "effect/Cause";
+import {
+  type MutatorResultDetails,
+  type MutatorResultErrorDetails,
+  type MutatorResultSuccessDetails,
+  type ReadonlyJSONValue,
+  Zero,
+  type ZeroOptions,
+} from "@rocicorp/zero";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Fn from "effect/Function";
 import type { NodeInspectSymbol } from "effect/Inspectable";
+import type * as LogLevel from "effect/LogLevel";
 import * as Match from "effect/Match";
+import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
 import * as Rec from "effect/Record";
-import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import type * as Tracer from "effect/Tracer";
 import type * as Unify from "effect/Unify";
-import type * as ClientTransaction from "./client-transaction.js";
-import { ContextSymbol, SchemaSymbol } from "./client-transaction.js";
-import { normalizeArgs } from "./internal/utils.js";
-import * as Mutators from "./mutators.js";
+import { type ContextSymbol, SchemaSymbol } from "./client-transaction.js";
+import * as Mutator from "./mutator.js";
 
 type _NodeInspectSymbol = NodeInspectSymbol;
 type _Unify = Unify.typeSymbol | Unify.unifySymbol | Unify.ignoreSymbol;
 
-export const make = Effect.fn(function* <TSchema extends ZeroSchema, TMutators extends Mutators.AnyMutators>(
-  transaction: ClientTransaction.Context<TSchema>,
-  mutators: TMutators,
-  options: Omit<ZeroOptions<TSchema, UnwrapMutators<TSchema, TMutators>>, "schema" | "mutators">,
+export type Options<TRegistry extends Mutator.AnyRegistry> = Omit<
+  ZeroOptions<Mutator.ZeroSchemaOf<TRegistry>>,
+  "schema" | "mutators" | "context"
+>;
+
+/**
+ * Makes a Zero client that runs the registry's mutators with the services in scope here.
+ * Run mutations with {@link mutate}.
+ */
+export const make = Effect.fn(function* <TRegistry extends Mutator.AnyRegistry>(
+  mutators: TRegistry,
+  options: Options<TRegistry>,
 ) {
-  const ctx =
+  const context =
     yield* Effect.context<
-      Exclude<Mutators.ExtractMutatorsRequirements<TMutators>, (typeof transaction)[typeof ContextSymbol]["Identifier"]>
+      Exclude<Mutator.Requirements<TRegistry>, Mutator.Transaction<TRegistry>[typeof ContextSymbol]["Identifier"]>
     >();
 
-  function unwrapMutator<E>(mutator: Mutators.AnyMutator<Mutators.ExtractMutatorsRequirements<TMutators>, E>) {
-    return (tx: ZeroTransaction<TSchema>, args: unknown, _ctx: unknown) =>
-      Schema.decodeUnknownEffect(mutator[Mutators.MutatorSchemaSymbol])(normalizeArgs(args)).pipe(
-        Effect.catchTag("SchemaError", (e) => Effect.fail(new ClientArgsParseError({ cause: Cause.fail(e) }))),
-        Effect.flatMap(mutator),
-        Effect.provideService(transaction[ContextSymbol], tx),
-        Effect.runPromiseWith(ctx),
-      );
-  }
-
-  const unwrappedMutators = Rec.map(mutators, (v) =>
-    Match.value(v).pipe(Match.when(Predicate.isFunction, unwrapMutator), Match.orElse(Rec.map(unwrapMutator))),
-  ) as ZeroOptions<TSchema, UnwrapMutators<TSchema, TMutators>>["mutators"];
-
   return yield* Effect.acquireRelease(
-    Effect.sync(() => {
-      return new Zero({
-        ...options,
-        schema: transaction[SchemaSymbol],
-        mutators: unwrappedMutators,
-      });
-    }),
+    Effect.sync(
+      () =>
+        new Zero<Mutator.ZeroSchemaOf<TRegistry>>({
+          // Zero's own logs (at its `logLevel`, "warn" by default) go through Effect's logger, unless `options` sets
+          // a `logSink`.
+          logSink: {
+            log: (level, logContext, ...args) =>
+              Match.value(level).pipe(
+                Match.withReturnType<LogLevel.Severity>(),
+                Match.when("debug", () => "Debug"),
+                Match.when("info", () => "Info"),
+                Match.when("warn", () => "Warn"),
+                Match.when("error", () => "Error"),
+                Match.exhaustive,
+                (severity) => Effect.logWithLevel(severity)(...args),
+                Effect.annotateLogs({ ...logContext, logger: "zero" }),
+                Effect.runForkWith(context),
+              ),
+          },
+          ...options,
+          schema: mutators[Mutator.RegistryTypeId].transaction[SchemaSymbol],
+          mutators,
+          // The mutators run with these services.
+          context,
+        }),
+    ),
     (zero) => Effect.promise(() => zero.close()),
   );
 });
 
-type UnwrapMutator<TSchema extends ZeroSchema, TMutators extends Mutators.AnyMutator> = Parameters<TMutators> extends []
-  ? (transaction: ZeroTransaction<TSchema>) => Promise<void>
-  : (
-      transaction: ZeroTransaction<TSchema>,
-      args: Schema.Codec.Encoded<TMutators[typeof Mutators.MutatorSchemaSymbol]>,
-    ) => Promise<void>;
+/** A mutation sent with {@link mutate}. Its client and server outcomes settle independently. */
+export interface Mutation {
+  /** Completes once the mutation is applied locally; fails if Zero or the client mutator rejected it. */
+  readonly client: Effect.Effect<void, MutationError>;
+  /** Completes once the server applied the mutation; fails if it was rejected anywhere. */
+  readonly server: Effect.Effect<void, MutationError>;
+}
+
+/**
+ * Sends a mutation with `zero.mutate(request)` and traces it. Awaiting `client` or `server` is optional; both
+ * outcomes are always recorded on the `zero.mutation` span, as the `zero.mutation.client` and
+ * `zero.mutation.server` child spans.
+ */
+export const mutate = Effect.fn(function* <Type>(
+  // biome-ignore lint/suspicious/noExplicitAny: any Zero instance made with `make`
+  zero: Zero<any, any, any>,
+  request: Mutator.MutateRequest<Type>,
+) {
+  const mutator = request.mutator.mutatorName;
+  const connection = zero.connection.state.current;
+  // The span outlives this call: it ends when this scope closes, once both outcomes are known.
+  const scope = yield* Scope.make();
+  const span = yield* Effect.makeSpanScoped("zero.mutation", {
+    attributes: {
+      "zero.mutator": mutator,
+      "zero.clientID": zero.clientID,
+      "zero.connection.state": connection.name,
+      ...Rec.getSomes({
+        "zero.connection.reason": Option.fromNullishOr("reason" in connection ? connection.reason : undefined).pipe(
+          Option.map((reason) => (Predicate.isString(reason) ? reason : reason.type)),
+        ),
+      }),
+    },
+  }).pipe(Scope.provide(scope));
+
+  const result = yield* Effect.sync(() => zero.mutate(request)).pipe(
+    Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))),
+  );
+
+  const client = yield* Effect.promise(() => result.client).pipe(
+    Effect.filterOrElse(isApplied, (details) => new MutationError({ mutator, origin: "client", ...details.error })),
+    Effect.asVoid,
+    traceOutcome({ origin: "client", parent: span, mutator }),
+    Effect.forkDetach,
+  );
+  const server = yield* Effect.promise(() => result.server).pipe(
+    Effect.filterOrElse(
+      isApplied,
+      Effect.fnUntraced(function* (details) {
+        // A write the client rejected is never pushed; Zero reports the client's error for the server too.
+        const origin = Exit.isFailure(yield* Fiber.await(client)) ? "client" : "server";
+        return yield* new MutationError({ mutator, origin, ...details.error });
+      }),
+    ),
+    Effect.asVoid,
+    traceOutcome({ origin: "server", parent: span, mutator }),
+    Effect.forkDetach,
+  );
+
+  yield* Effect.gen(function* () {
+    span.attribute("zero.clientGroupID", yield* Effect.promise(() => zero.clientGroupID));
+    const clientExit = yield* Fiber.await(client);
+    const serverExit = yield* Fiber.await(server);
+    yield* Scope.close(scope, Exit.isFailure(clientExit) ? clientExit : serverExit);
+  }).pipe(Effect.forkDetach);
+
+  // Joining a fiber never re-runs it, so either outcome can be awaited any number of times.
+  return { client: Fiber.join(client), server: Fiber.join(server) };
+});
+
+const isApplied = (details: MutatorResultDetails): details is MutatorResultSuccessDetails => details.type === "success";
 
-type UnwrapMutators<TSchema extends ZeroSchema, TMutators extends Mutators.AnyMutators> = {
-  [A in keyof TMutators]: TMutators[A] extends Mutators.AnyMutator
-    ? UnwrapMutator<TSchema, TMutators[A]>
-    : {
-        [B in keyof TMutators[A]]: TMutators[A][B] extends Mutators.AnyMutator
-          ? UnwrapMutator<TSchema, TMutators[A][B]>
-          : never;
-      };
-} & {};
+/** Runs a mutation's outcome in its `zero.mutation.client` or `zero.mutation.server` span. */
+const traceOutcome: {
+  (options: TraceOutcomeOptions): (self: Effect.Effect<void, MutationError>) => Effect.Effect<void, MutationError>;
+  (self: Effect.Effect<void, MutationError>, options: TraceOutcomeOptions): Effect.Effect<void, MutationError>;
+} = Fn.dual(2, (self: Effect.Effect<void, MutationError>, { origin, parent, mutator }: TraceOutcomeOptions) =>
+  self.pipe(
+    Effect.tapError((error) =>
+      Effect.annotateCurrentSpan({
+        "zero.mutation.error.type": error.type,
+        "zero.mutation.error.origin": error.origin,
+      }),
+    ),
+    Effect.withSpan(`zero.mutation.${origin}`, { parent, attributes: { "zero.mutator": mutator } }),
+  ),
+);
 
-export class ClientArgsParseError extends Data.TaggedError("ClientArgsParseError")<{
-  readonly cause: Cause.Cause<unknown>;
-}> {
-  override get message() {
-    const error = Cause.squash(this.cause);
-    return Predicate.isError(error) ? error.message : "Internal error";
-  }
+interface TraceOutcomeOptions {
+  readonly origin: "client" | "server";
+  readonly parent: Tracer.Span;
+  readonly mutator: string;
 }
+
+/**
+ * Zero rejected a mutation, with Zero's own error details: `type` is `"zero"` when Zero itself refused it
+ * (e.g. offline), and `"app"` when a mutator failed. `origin` is where it failed.
+ */
+export class MutationError extends Data.TaggedError("MutationError")<{
+  readonly mutator: string;
+  readonly origin: "client" | "server";
+  readonly type: MutatorResultErrorDetails["error"]["type"];
+  readonly message: string;
+  readonly details?: ReadonlyJSONValue | undefined;
+}> {}

package/src/internal/utils.ts

@@ -2,11 +2,3 @@
  * Prefix a string with the package name.
  */
 export const prefixId = <S extends string>(name: S) => `effect-zero/${name}` as const;
-
-/**
- * Zero unconditionally serializes arg-less mutator calls as `null` on the wire
- * (https://github.com/rocicorp/mono/blob/3082c9fa061891067b4bd7dc9fe74f798270d8d7/packages/zero-client/src/client/custom.ts).
- * v3 `Schema.Void` happened to accept any input; v4 `Schema.Void` is strict
- * `=== undefined`, so we renormalize before decoding.
- */
-export const normalizeArgs = (args: unknown): unknown => (args === null ? undefined : args);

package/src/mutator.ts

@@ -0,0 +1,232 @@
+import type {
+  AnyMutatorRegistry,
+  MutateRequest as ZeroMutateRequest,
+  Schema as ZeroSchema,
+  Transaction as ZeroTransaction,
+} from "@rocicorp/zero";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import type { NodeInspectSymbol } from "effect/Inspectable";
+import * as Predicate from "effect/Predicate";
+import * as Rec from "effect/Record";
+import * as Schema from "effect/Schema";
+import type * as Unify from "effect/Unify";
+import type * as ClientTransaction from "./client-transaction.js";
+import { ContextSymbol } from "./client-transaction.js";
+import { prefixId } from "./internal/utils.js";
+
+type _NodeInspectSymbol = NodeInspectSymbol;
+type _Unify = Unify.typeSymbol | Unify.unifySymbol | Unify.ignoreSymbol;
+
+export const RegistryTypeId = Symbol.for(prefixId("MutatorRegistry"));
+
+/**
+ * A mutator that isn't part of a registry yet, made with {@link make}. Like `defineMutator`, it gets its name
+ * from its path in the {@link registry}.
+ */
+export interface Definition<Type, Encoded, E, R> {
+  readonly payload: Schema.Codec<Type, Encoded, R>;
+  readonly mutator: (args: Type) => Effect.Effect<unknown, E, R>;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: upper bound to allow everything
+export type AnyDefinition = Definition<any, any, any, any>;
+
+export type Definitions = { readonly [key: string]: AnyDefinition | Definitions };
+
+/**
+ * A registered mutator. Calling it encodes `args` and returns a request for `ZfxClient.mutate(zero, request)`, or
+ * for Zero's own `zero.mutate(request)`. It is also a Zero `Mutator`, so the registry can be passed to Zero.
+ */
+export interface Mutator<Type, Encoded, E, R> extends Definition<Type, Encoded, E, R> {
+  (args: Type): MutateRequest<Type>;
+  readonly mutatorName: string;
+  /** Runs the mutator for Zero, which calls it with the transaction and the `context` from `ZfxClient.make`. */
+  readonly fn: (options: {
+    readonly args: unknown;
+    readonly ctx: unknown;
+    readonly tx: ZeroTransaction<ZeroSchema>;
+  }) => Promise<void>;
+  readonly "~": "Mutator";
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: upper bound to allow everything
+export type AnyMutator = Mutator<any, any, any, any>;
+
+/** A request to run a mutator, for `ZfxClient.mutate` or Zero's own `zero.mutate`. */
+// biome-ignore lint/suspicious/noExplicitAny: compatible with any Zero instance's `zero.mutate`
+export type MutateRequest<Type> = ZeroMutateRequest<any, any, any, any> & {
+  // biome-ignore lint/suspicious/noExplicitAny: the encoded args, errors and services don't matter to the caller
+  readonly mutator: Mutator<Type, any, any, any>;
+};
+
+type Tree<D> = {
+  readonly [K in keyof D]: D[K] extends Definition<infer Type, infer Encoded, infer E, infer R>
+    ? Mutator<Type, Encoded, E, R>
+    : Tree<D[K]>;
+};
+
+/** A tree of registered mutators, made with {@link registry}. Pass it to `ZfxClient.make` and the server. */
+export type Registry<D extends Definitions, TTransaction extends AnyClientTransaction> = Tree<D> & {
+  readonly "~": AnyMutatorRegistry["~"];
+  readonly [RegistryTypeId]: { readonly transaction: TTransaction };
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: upper bound to allow everything
+export type AnyRegistry = Registry<any, AnyClientTransaction>;
+
+// biome-ignore lint/suspicious/noExplicitAny: any client transaction
+type AnyClientTransaction = ClientTransaction.Context<any>;
+
+type Keys<T> = Exclude<Extract<keyof T, string>, "~">;
+
+/** The services a registry's mutators require. */
+// biome-ignore lint/suspicious/noExplicitAny: matches any mutator
+export type Requirements<T> = T extends Mutator<any, any, any, infer R>
+  ? R
+  : { [K in Keys<T>]: Requirements<T[K]> }[Keys<T>];
+
+/** The client transaction a registry's mutators run in. */
+export type Transaction<T extends AnyRegistry> = T[typeof RegistryTypeId]["transaction"];
+
+/** The Zero schema a registry's mutators run against. */
+export type ZeroSchemaOf<T extends AnyRegistry> = Transaction<T> extends ClientTransaction.Context<infer S> ? S : never;
+
+/**
+ * Defines a mutator. Its `payload` codec decodes the args on both the client and the server; it must encode without
+ * services, since calling a registered mutator encodes its args synchronously.
+ */
+export const make = <Type, Encoded, RD = never, A = unknown, E = never, R = never>(options: {
+  readonly payload: Schema.Codec<Type, Encoded, RD, never>;
+  readonly mutator: (args: NoInfer<Type>) => Effect.Effect<A, E, R>;
+}): Definition<Type, Encoded, E, R | RD> => options;
+
+/**
+ * Registers mutators under their path, like Zero's `defineMutators`: `{ todo: { create } }` registers
+ * `"todo.create"`. The result is also a Zero mutator registry, so it can be passed to `new Zero({ mutators })`.
+ */
+export const registry = <TTransaction extends AnyClientTransaction, const D extends Definitions>(
+  transaction: TTransaction,
+  definitions: D,
+): Registry<D, TTransaction> => {
+  const register = (definitions: Definitions, path: ReadonlyArray<string>): Record<string, unknown> =>
+    Rec.map(definitions, (value, key) =>
+      isDefinition(value) ? makeMutator(transaction, [...path, key].join("."), value) : register(value, [...path, key]),
+    );
+
+  // The registry's shape is only known from `D`.
+  return Object.assign(register(definitions, []), {
+    "~": "MutatorRegistry",
+    [RegistryTypeId]: { transaction },
+  }) as unknown as Registry<D, TTransaction>;
+};
+
+const isDefinition = (u: unknown): u is AnyDefinition =>
+  Predicate.hasProperty(u, "payload") && Schema.isSchema(u.payload);
+
+const makeMutator = <Type, Encoded, E, R>(
+  transaction: AnyClientTransaction,
+  name: string,
+  definition: Definition<Type, Encoded, E, R>,
+): Mutator<Type, Encoded, E, R> => {
+  const run = (args: unknown, tx: ZeroTransaction<ZeroSchema>) =>
+    Schema.decodeUnknownEffect(definition.payload)(args).pipe(
+      Effect.catchTag("SchemaError", (error) => new ClientArgsParseError({ cause: Cause.fail(error) })),
+      Effect.flatMap(definition.mutator),
+      Effect.withSpan("zero.mutator", {
+        attributes: {
+          "zero.mutator": name,
+          "zero.clientID": tx.clientID,
+          "zero.mutationID": tx.mutationID,
+          "zero.mutation.reason": tx.reason,
+        },
+      }),
+      Effect.provideService(transaction[ContextSymbol], tx),
+      Effect.asVoid,
+    );
+
+  const mutator: Mutator<Type, Encoded, E, R> = Object.assign(
+    (args: Type) =>
+      // A Zero `MutateRequest`, whose brand only exists at the type level.
+      ({ mutator, args: Schema.encodeSync(definition.payload)(args), "~": "MutateRequest" }) as MutateRequest<Type>,
+    {
+      ...definition,
+      mutatorName: name,
+      "~": "Mutator" as const,
+      fn: ({
+        args,
+        ctx,
+        tx,
+      }: {
+        readonly args: unknown;
+        readonly ctx: unknown;
+        readonly tx: ZeroTransaction<ZeroSchema>;
+      }) =>
+        Context.isContext(ctx)
+          ? // `ZfxClient.make` passes the services it captured, which cover every mutator's requirements.
+            run(args, tx).pipe(Effect.runPromiseWith(ctx as Context.Context<R>))
+          : Promise.reject(new MutatorContextNotFound({ mutator: name })),
+    },
+  );
+  return mutator;
+};
+
+type Overrides<T> = {
+  readonly [K in Keys<T>]?: T[K] extends Mutator<infer Type, infer _Encoded, infer _E, infer _R>
+    ? // biome-ignore lint/suspicious/noExplicitAny: any server implementation
+      (args: Type) => Effect.Effect<unknown, any, any>
+    : Overrides<T[K]>;
+};
+
+/** The server's view of a registry, made with {@link server}. */
+export interface ServerMutators<TRegistry extends AnyRegistry, O> {
+  readonly registry: TRegistry;
+  readonly overrides: O;
+}
+
+export type AnyServerMutators = ServerMutators<AnyRegistry, unknown>;
+
+/**
+ * The registry's mutators as the server runs them, for `ZfxServer.handleMutate`. `overrides` replaces some mutators'
+ * bodies, like Zero's `defineMutators(base, overrides)`; every other mutator runs its shared body in a server
+ * transaction, so pass `{}` if nothing differs. An override runs outside the transaction, so it can do work before
+ * and after `serverTransaction.execute`, e.g. `registry.todo.create.mutator(args).pipe(serverTransaction.execute)`.
+ */
+export const server = <TRegistry extends AnyRegistry, const O extends Overrides<TRegistry>>(
+  registry: TRegistry,
+  overrides: O,
+): ServerMutators<TRegistry, O> => ({ registry, overrides });
+
+type ServerTreeRequirements<T, O, ClientTransactionId> = {
+  [K in Keys<T>]: T[K] extends AnyMutator
+    ? K extends keyof O
+      ? O[K] extends (args: never) => Effect.Effect<infer _A, infer _E, infer R>
+        ? R
+        : never
+      : Exclude<Requirements<T[K]>, ClientTransactionId>
+    : ServerTreeRequirements<T[K], K extends keyof O ? O[K] : unknown, ClientTransactionId>;
+}[Keys<T>];
+
+/**
+ * The services the server needs to run these mutators. Mutators that aren't overridden run in a server transaction,
+ * which provides their client transaction.
+ */
+export type ServerRequirements<T extends AnyServerMutators> = T extends ServerMutators<infer TRegistry, infer O>
+  ? ServerTreeRequirements<TRegistry, O, Transaction<TRegistry>[typeof ContextSymbol]["Identifier"]>
+  : never;
+
+export class ClientArgsParseError extends Data.TaggedError("ClientArgsParseError")<{
+  readonly cause: Cause.Cause<unknown>;
+}> {
+  override get message() {
+    const error = Cause.squash(this.cause);
+    return Predicate.isError(error) && !Schema.isSchemaError(error) ? error.message : "Internal error";
+  }
+}
+
+/** A mutator ran on a Zero instance that wasn't made with `ZfxClient.make`. */
+export class MutatorContextNotFound extends Data.TaggedError("MutatorContextNotFound")<{
+  readonly mutator: string;
+}> {}

package/src/result.ts

@@ -5,14 +5,14 @@ import * as Fn from "effect/Function";
 import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
 import * as Struct from "effect/Struct";
-import { AsyncResult } from "effect/unstable/reactivity";
 import type { QueryResult } from "./internal/query-result.js";
 
 /*
 ### Introduction
 
-When using `effect/unstable/reactivity` (atoms) with effect-zero, you will often have atoms which contain a type in the form of
+When using `effect/reactivity` (atoms) with effect-zero, you will often have atoms which contain a type in the form of
 
 `AsyncResult<QueryResult<A>, E>`
 

package/src/server.ts

@@ -10,10 +10,8 @@ import * as Data from "effect/Data";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
-import * as Fn from "effect/Function";
 import type { NodeInspectSymbol } from "effect/Inspectable";
 import * as Layer from "effect/Layer";
-import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
 import * as Rec from "effect/Record";
@@ -22,8 +20,7 @@ import * as Str from "effect/String";
 import type * as Unify from "effect/Unify";
 import { TransactCallbackNotInvokedError, TransactInternalError } from "./internal/server.js";
 import * as ServerSynchronizationContext from "./internal/server-synchronization-context.js";
-import { normalizeArgs } from "./internal/utils.js";
-import * as Mutators from "./mutators.js";
+import type * as Mutator from "./mutator.js";
 import { type MakeQueryResult, QueryNameSymbol, RunQuerySymbol } from "./query.js";
 import type * as ServerTransaction from "./server-transaction.js";
 import { DatabaseSymbol, ServerTransactionCallbackSymbol } from "./server-transaction.js";
@@ -44,10 +41,14 @@ type _Unify = Unify.typeSymbol | Unify.unifySymbol | Unify.ignoreSymbol;
 type MutateUserId = Extract<Awaited<ReturnType<typeof handleMutateRequest>>, { kind: "MutateResponse" }>["userID"];
 type QueryUserId = Extract<Awaited<ReturnType<typeof handleQueryRequest>>, { kind: "QueryResponse" }>["userID"];
 
+/**
+ * Handles Zero's push endpoint, running each mutation's server implementation: its override from
+ * `ZfxMutator.server`, or else its shared body in a server transaction.
+ */
 export const handleMutate = Effect.fn(function* <
   TSchema extends ZeroSchema,
   TTransaction,
-  TMutators extends Mutators.AnyMutators,
+  TMutators extends Mutator.AnyServerMutators,
 >({
   transaction,
   mutators,
@@ -64,7 +65,7 @@ export const handleMutate = Effect.fn(function* <
   const ctx =
     yield* Effect.context<
       Exclude<
-        Mutators.ExtractMutatorsRequirements<TMutators>,
+        Mutator.ServerRequirements<TMutators>,
         | (typeof transaction)[typeof ServerTransactionCallbackSymbol]["Identifier"]
         | ServerSynchronizationContext.ServerSynchronizationContext
       >
@@ -91,28 +92,31 @@ export const handleMutate = Effect.fn(function* <
                       Effect.onExit((exit) => Deferred.done(exitDeferred, exit)),
                       Effect.catchCause((cause) => Effect.die(makeApplicationError(cause))),
                       Effect.asVoid,
-                      Effect.provide(innerCtx),
-                      (effect) => Effect.runPromise(effect, { signal }),
+                      (effect) => Effect.runPromiseWith(innerCtx)(effect, { signal }),
                     ),
                   ),
                 catch: (error) => new TransactInternalError({ cause: Cause.fail(error) }),
               }).pipe(Effect.flatMap((value) => Deferred.succeed(response, value)));
 
               return yield* Deferred.poll(exitDeferred).pipe(
-                Effect.flatMap(Effect.fromOption),
-                Effect.catchTag("NoSuchElementError", () => Effect.fail(new TransactCallbackNotInvokedError())),
+                Effect.flatMap(Effect.fromOption(() => new TransactCallbackNotInvokedError())),
                 Effect.flatten,
               );
             }, ServerSynchronizationContext.guard);
 
-            const exit: Exit.Exit<unknown, unknown> = yield* runMutation<
-              Mutators.ExtractMutatorsRequirements<TMutators>
-            >(mutators, mutation).pipe(
+            const exit: Exit.Exit<unknown, unknown> = yield* runMutation(mutators, transaction, mutation).pipe(
               ServerSynchronizationContext.finalize,
               Effect.provide([
                 Layer.succeed(transaction[ServerTransactionCallbackSymbol], { transact }),
                 ServerSynchronizationContext.layer,
               ]),
+              Effect.withSpan("zero.mutation.handle", {
+                attributes: {
+                  "zero.mutator": mutation.name,
+                  "zero.clientID": mutation.clientID,
+                  "zero.mutationID": mutation.id,
+                },
+              }),
               Effect.exit,
             );
 
@@ -142,29 +146,41 @@ export const handleMutate = Effect.fn(function* <
   });
 });
 
-const runMutation = Effect.fn(function* <R>(mutators: Mutators.AnyMutators<R>, mutation: Mutation) {
-  // Support both "namespace|name" and "namespace.name" formats, and single-segment names.
-  const [namespace, name] = mutation.name.includes("|") ? Str.split(mutation.name, "|") : Str.split(mutation.name, ".");
-
-  const mutator = yield* Fn.pipe(
-    mutators,
-    Rec.get<string>(namespace),
-    Option.flatMap((mutator) =>
-      Match.value([mutator, name]).pipe(
-        Match.when([Predicate.isObject, Predicate.isString], ([mutator, name]) => Rec.get<string>(name)(mutator)),
-        Match.when([Predicate.isFunction, Predicate.isUndefined], ([mutator]) => Option.some(mutator)),
-        Match.orElse(() => Option.none()),
-      ),
+/**
+ * Runs a mutation: its override if it has one, or else its shared body in a server transaction. Like upstream, names
+ * are split on "." or "|" (the separator of Zero's legacy custom mutators), at any depth. Their services aren't tracked
+ * from here on: `handleMutate` already requires every implementation's.
+ */
+const runMutation = Effect.fn(function* <TSchema extends ZeroSchema, TTransaction>(
+  mutators: Mutator.AnyServerMutators,
+  transaction: ServerTransaction.Context<TSchema, TTransaction>,
+  mutation: Mutation,
+) {
+  const { registry, overrides } = Rec.map(mutators, (root) =>
+    Arr.reduce(Str.split(mutation.name, /[.|]/), Option.some(root), (tree, key) =>
+      // Only an object has keys to walk into; the checks below make sure the walk ended at a mutator.
+      tree.pipe(Option.filter(Predicate.isObject), Option.flatMap(Rec.get(key))),
     ),
-    Effect.fromOption,
-    Effect.catchTag("NoSuchElementError", () => Effect.fail(new MutatorNotFoundError({ name: mutation.name }))),
+  );
+  const mutator = yield* registry.pipe(
+    Option.filter(
+      (u): u is Mutator.Mutator<unknown, unknown, unknown, never> =>
+        Predicate.isFunction(u) && Predicate.hasProperty(u, "mutatorName"),
+    ),
+    Effect.fromOption(() => new MutatorNotFoundError({ name: mutation.name })),
   );
 
-  const args = yield* Schema.decodeUnknownEffect(mutator[Mutators.MutatorSchemaSymbol])(
-    normalizeArgs(mutation.args[0]),
-  ).pipe(Effect.catchTag("SchemaError", (e) => Effect.fail(new ServerArgsParseError({ cause: Cause.fail(e) }))));
+  const args = yield* Schema.decodeUnknownEffect(mutator.payload)(mutation.args[0]).pipe(
+    Effect.catchTag("SchemaError", (e) => Effect.fail(new ServerArgsParseError({ cause: Cause.fail(e) }))),
+  );
 
-  return yield* mutator(args);
+  return yield* overrides.pipe(
+    Option.filter((u): u is (args: unknown) => Effect.Effect<unknown, unknown> => Predicate.isFunction(u)),
+    Option.match({
+      onNone: () => transaction.execute(mutator.mutator(args)),
+      onSome: (run) => run(args),
+    }),
+  );
 });
 
 export const makeApplicationError = (cause: Cause.Cause<unknown>) => {
@@ -204,8 +220,7 @@ export const handleQuery = Effect.fn(function* <E, R1, R2>({
       handleQueryRequest({
         handler: (name, args) =>
           Arr.findFirst(queries, (q) => q[QueryNameSymbol] === name).pipe(
-            Effect.fromOption,
-            Effect.catchTag("NoSuchElementError", () => Effect.fail(new QueryNotFound({ name }))),
+            Effect.fromOption(() => new QueryNotFound({ name })),
             Effect.flatMap((query) => query[RunQuerySymbol]({ _tag: "Encoded", args })),
             Effect.runSyncWith(ctx),
           ),

package/dist/client.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=client.test.d.ts.map

package/dist/client.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../src/client.test.ts"],"names":[],"mappings":""}