effect-zero 0.0.0-alpha.0 → 0.1.0

package/src/server.ts

@@ -0,0 +1,377 @@
+import type { Database, TransactionProviderHooks, TransactionProviderInput } from "@rocicorp/zero/pg";
+import * as Cause from "effect/Cause";
+import * as Chunk from "effect/Chunk";
+import * as Context from "effect/Context";
+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 * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import type * as ParseResult from "effect/ParseResult";
+import * as Predicate from "effect/Predicate";
+import * as Rec from "effect/Record";
+import * as Runtime from "effect/Runtime";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as Str from "effect/String";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+import { type AnyMutators, type ExtractMutatorsRequirements, MutatorArgsSchemaSym } from "./mutators.js";
+import {
+  type ZeroAppError,
+  type ZeroError,
+  type ZeroMutation,
+  ZeroMutationResponse,
+  type ZeroMutationResult,
+  type ZeroPushBody,
+  type ZeroPushParams,
+  type ZeroPushResponse,
+} from "./types.js";
+import { prefixId } from "./utils.js";
+
+// Updated to: https://github.com/rocicorp/mono/blob/3082c9fa061891067b4bd7dc9fe74f798270d8d7/packages/zero-server/src/push-processor.ts
+
+export interface ZeroServerTransactionContext {
+  readonly _tag: unique symbol;
+}
+
+// NOTE(zero): Using the "Lifting the Generic" technique.
+// NOTE(zero): Could choose to not accept `Database<T>` as a param and instead create some `ZeroDatabase` service inside the
+// `make` function, which various other functions require. However, this means that the user will have to manually
+// specify the `T` type parameter which seemed a bit clunky.
+export const makeServer = <T, I = never>(options: { database: Database<T>; clientTransaction?: Context.Tag<I, T> }) => {
+  const ZeroServerTransactionContext = Context.Tag(prefixId("ZeroServerTransactionContext"))<
+    ZeroServerTransactionContext,
+    { transaction: T; transactionHooks: TransactionProviderHooks }
+  >();
+
+  // TODO: Maybe prefix this / suffix this with a tag passed in to `make`?
+  const execute = Effect.fn(function* <A, E, R>(effect: Effect.Effect<A, E, R>) {
+    const runtime =
+      // TODO: Is there a cleaner way to write this?
+      yield* Effect.runtime<Exclude<Exclude<R | ZeroTransactionInput, ZeroServerTransactionContext>, I>>();
+    const result = yield* Deferred.make<A, E | Effect.Effect.Error<typeof checkAndIncrementLastMutationID>>();
+
+    const transactionInput = yield* ZeroTransactionInput;
+    yield* Effect.tryPromise({
+      try: (signal) =>
+        options.database.transaction(async (transaction, transactionHooks) => {
+          const exit = await Effect.zipRight(checkAndIncrementLastMutationID, effect).pipe(
+            Effect.provideService(ZeroServerTransactionContext, { transaction, transactionHooks }),
+            options.clientTransaction
+              ? Effect.provideService(options.clientTransaction, transaction)
+              : // TODO: Is there a cleaner way to write this?
+                <A, E, R>(effect: Effect.Effect<A, E, R>) => effect as Effect.Effect<A, E, Exclude<R, I>>,
+            (effect) => Runtime.runPromiseExit(runtime, effect, { signal }),
+          );
+          Deferred.unsafeDone(result, exit);
+          return Exit.getOrElse(exit, () => {
+            // This error's purpose is to differentiate between "external" errors
+            // that originate from the user-defined mutator code and "internal" errors
+            // that originate from our own code and the Zero API.
+            // Both types are caught in the "catch" block below, but at this point we only need to handle
+            // the "internal" errors wrapping them in a `ZeroDatabaseError`, because "external" errors
+            // are already covered by passing the Exit result to the Deferred, which is why
+            // we have the ZeroTransactionUserError silenced below in the pipe.
+            throw new ZeroTransactionUserError();
+          });
+        }, transactionInput),
+      catch: (error) => {
+        if (ZeroTransactionUserError.is(error)) {
+          return error;
+        }
+        // This is for errors that occur when calling `database.transaction` despite the provided `effect` succeeding.
+        // This can be caused by e.g. the database connection timing out or other database-related issues.
+        return new ZeroDatabaseError({ cause: Cause.fail(error) });
+      },
+    }).pipe(Effect.catchTag("ZeroTransactionUserError", () => Effect.void));
+
+    return yield* result;
+  }, ZeroServerMutationContext.guard);
+
+  const use = <A>(fn: (transaction: T, options: { readonly signal: AbortSignal }) => PromiseLike<A>) =>
+    Effect.flatMap(ZeroServerTransactionContext, (ctx) =>
+      Effect.tryPromise({
+        try: (signal) => fn(ctx.transaction, { signal }),
+        catch: Fn.identity,
+      }),
+    );
+
+  const checkAndIncrementLastMutationID = Effect.gen(function* () {
+    const { transactionHooks } = yield* ZeroServerTransactionContext;
+    const { clientID, mutationID: receivedMutationID } = yield* ZeroTransactionInput;
+
+    const { lastMutationID } = yield* Effect.tryPromise({
+      try: () => transactionHooks.updateClientMutationID(),
+      catch: (error) => new UpdateClientMutationIDError({ cause: Cause.fail(error) }),
+    });
+
+    if (receivedMutationID < lastMutationID) {
+      return yield* new MutationAlreadyProcessedError({
+        clientID,
+        received: receivedMutationID,
+        actual: lastMutationID,
+      });
+    }
+    if (receivedMutationID > lastMutationID) {
+      return yield* new OutOfOrderMutationError({
+        clientID,
+        receivedMutationID,
+        lastMutationID,
+      });
+    }
+  });
+
+  const processPush = Effect.fn(function* <T extends AnyMutators>(
+    mutators: T,
+    params: ZeroPushParams,
+    request: ZeroPushBody,
+  ) {
+    if (request.pushVersion !== 1) {
+      return { error: "unsupportedPushVersion" as const };
+    }
+
+    const responses = yield* Stream.fromIterable(request.mutations).pipe(
+      Stream.mapEffect(
+        Effect.fn(function* (mutation) {
+          if (mutation.type !== "custom") {
+            return yield* new CustomMutationExpectedError({});
+          }
+          return yield* processMutation<ExtractMutatorsRequirements<T>>(mutators, mutation).pipe(
+            Effect.map((result) =>
+              ZeroMutationResponse.make({ id: { id: mutation.id, clientID: mutation.clientID }, result }),
+            ),
+            Effect.provideService(ZeroTransactionInput, {
+              clientID: mutation.clientID,
+              mutationID: mutation.id,
+              clientGroupID: request.clientGroupID,
+              upstreamSchema: params.schema,
+            }),
+          );
+        }),
+      ),
+      // We only stop processing if the mutation is out of order.
+      // If the mutation has already been processed or if it returns an application error,
+      // we continue processing the next mutation.
+      Stream.takeUntil(({ result }) => Predicate.hasProperty(result, "error") && result.error === "oooMutation"),
+      Stream.runCollect,
+      Effect.annotateLogs({ module: prefixId("ZeroServer"), method: "processPush" }),
+    );
+
+    return { mutations: Chunk.toArray(responses) } satisfies ZeroPushResponse;
+  });
+
+  const processMutation = Effect.fn(
+    function* <R>(mutators: AnyMutators<R>, mutation: ZeroMutation) {
+      // 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.isRecord, Predicate.isString], ([mutator, name]) => Rec.get<string>(name)(mutator)),
+            Match.when([Predicate.isFunction, Predicate.isUndefined], ([mutator]) => Option.some(mutator)),
+            Match.orElse(() => Option.none()),
+          ),
+        ),
+        Effect.catchTag("NoSuchElementException", () => new MutatorNotFoundError({ mutationName: mutation.name })),
+      );
+
+      const args = yield* Schema.decode(mutator[MutatorArgsSchemaSym])(mutation.args[0]).pipe(
+        Effect.catchTag("ParseError", (e) => new ZeroServerArgsParseError({ cause: Cause.fail(e) })),
+      );
+
+      return yield* mutator(args).pipe(
+        // Case #2 "One transaction then fail"
+        // If the transaction was executed successfully, swallow the error and just log it, otherwise re-throw it
+        Effect.catchAllCause(
+          Effect.fn(function* (e) {
+            const wasTransactionExecuted = yield* ZeroServerMutationContext.wasTransactionExecuted;
+            if (wasTransactionExecuted) {
+              return yield* Effect.logError("Error occurred after transaction execution completed", e);
+            }
+            return yield* Effect.failCause(e);
+          }),
+        ),
+        // Case #4 "Zero transactions then succeed"
+        // Check that the transaction was executed during the mutation
+        Effect.tap(
+          Effect.gen(function* () {
+            const wasTransactionExecuted = yield* ZeroServerMutationContext.wasTransactionExecuted;
+            if (!wasTransactionExecuted) {
+              return yield* new NoTransactionError();
+            }
+          }),
+        ),
+        Effect.as<ZeroMutationResult>({}),
+        Effect.catchIf(OutOfOrderMutationError.is, (e) =>
+          Effect.logError(e.message).pipe(Effect.as({ error: "oooMutation", details: e.message } satisfies ZeroError)),
+        ),
+        Effect.catchIf(MutationAlreadyProcessedError.is, (e) =>
+          Effect.logWarning(e.message).pipe(
+            Effect.as({ error: "alreadyProcessed", details: e.message } satisfies ZeroError),
+          ),
+        ),
+        // Case #5 "Zero transactions then fail" / #6 "Fail before transaction"
+        // Catches all errors that are produced before the transaction is executed
+        Effect.catchAllCause((cause) => new ZeroMutationUserError({ cause })),
+      );
+    },
+    Effect.catchAll((e) => processMutationError(e)),
+    Effect.provide(ZeroServerMutationContext.Default),
+  );
+
+  const processMutationError = Effect.fn(function* (e: unknown) {
+    const { clientID, mutationID } = yield* ZeroTransactionInput;
+
+    yield* Effect.logError(`Unexpected error processing mutation ${mutationID} for client ${clientID}`, Cause.fail(e));
+
+    const errorMessage = Match.value(e).pipe(
+      Match.when(ZeroMutationUserError.is, (e) => e.message),
+      Match.orElse(() => "Internal error"),
+    );
+
+    const appError = {
+      error: "app",
+      details: errorMessage,
+    } satisfies ZeroAppError;
+
+    yield* execute(
+      Effect.flatMap(ZeroServerTransactionContext, ({ transactionHooks }) => {
+        return Effect.tryPromise({
+          try: () => transactionHooks.writeMutationResult({ id: { id: mutationID, clientID }, result: appError }),
+          catch: (error) => new WriteMutationResultError({ cause: Cause.fail(error) }),
+        });
+      }),
+    ).pipe(Effect.catchAllCause(Effect.logError));
+
+    yield* Effect.logWarning(`Mutation ${mutationID} for client ${clientID} was retried after an error: ${e}`);
+
+    return appError;
+  });
+
+  return {
+    Transaction: Object.assign(ZeroServerTransactionContext, { execute, use }),
+    processPush,
+  };
+};
+
+class ZeroTransactionInput extends Context.Tag(prefixId("ZeroTransactionInput"))<
+  ZeroTransactionInput,
+  TransactionProviderInput
+>() {}
+
+class ZeroServerMutationContext extends Effect.Service<ZeroServerMutationContext>()(
+  prefixId("ZeroServerMutationContext"),
+  {
+    effect: Effect.gen(function* () {
+      return { wasTransactionExecuted: yield* SynchronizedRef.make(false) };
+    }),
+  },
+) {
+  static wasTransactionExecuted = Effect.flatMap(ZeroServerMutationContext, (ctx) => ctx.wasTransactionExecuted);
+
+  // Ensures that only one transaction is executed at a time and checks that another transaction wasn't already executed.
+  static guard = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    Effect.flatMap(this, ({ wasTransactionExecuted }) =>
+      SynchronizedRef.modifyEffect(
+        wasTransactionExecuted,
+        Effect.fn(function* (wasTransactionExecuted) {
+          if (wasTransactionExecuted) {
+            return yield* new MultipleTransactionsError();
+          }
+          const result = yield* effect;
+          return [result, true];
+        }),
+      ),
+    );
+}
+
+class ZeroDatabaseError extends Data.TaggedError("ZeroDatabaseError")<{
+  cause: Cause.Cause<unknown>;
+}> {}
+
+class UpdateClientMutationIDError extends Data.TaggedError("UpdateClientMutationIDError")<{
+  readonly cause: Cause.Cause<unknown>;
+}> {}
+
+class MutatorNotFoundError extends Data.TaggedError("MutatorNotFoundError")<{
+  mutationName: string;
+}> {
+  override message = `Mutator not found for mutation ${this.mutationName}`;
+}
+
+class WriteMutationResultError extends Data.TaggedError("WriteMutationResultError")<{
+  readonly cause: Cause.Cause<unknown>;
+}> {}
+class CustomMutationExpectedError extends Data.TaggedError("CustomMutationExpectedError")<object> {}
+
+export class MultipleTransactionsError extends Data.TaggedError("MultipleTransactionsError") {
+  override message = "Multiple transactions detected in a mutation, only one transaction is allowed.";
+}
+
+export class NoTransactionError extends Data.TaggedError("NoTransactionError") {
+  override message = "No transaction detected in a mutation, a transaction is required.";
+}
+
+const OutOfOrderMutationErrorTypeId = Symbol.for(prefixId("OutOfOrderMutationError"));
+export class OutOfOrderMutationError extends Data.TaggedError("OutOfOrderMutationError")<{
+  readonly clientID: string;
+  readonly receivedMutationID: number;
+  readonly lastMutationID: number | bigint;
+}> {
+  readonly [OutOfOrderMutationErrorTypeId] = OutOfOrderMutationErrorTypeId;
+  override get message() {
+    return `Client ${this.clientID} sent mutation ID ${this.receivedMutationID} but expected ${this.lastMutationID}`;
+  }
+  static is(e: unknown): e is OutOfOrderMutationError {
+    return Predicate.hasProperty(e, OutOfOrderMutationErrorTypeId);
+  }
+}
+
+const MutationAlreadyProcessedErrorTypeId = Symbol.for(prefixId("MutationAlreadyProcessedError"));
+export class MutationAlreadyProcessedError extends Data.TaggedError("MutationAlreadyProcessedError")<{
+  readonly clientID: string;
+  readonly received: number;
+  readonly actual: number | bigint;
+}> {
+  readonly [MutationAlreadyProcessedErrorTypeId] = MutationAlreadyProcessedErrorTypeId;
+  override get message() {
+    return `Ignoring mutation from ${this.clientID} with ID ${this.received} as it was already processed. Expected: ${this.actual}`;
+  }
+  static is(e: unknown): e is MutationAlreadyProcessedError {
+    return Predicate.hasProperty(e, MutationAlreadyProcessedErrorTypeId);
+  }
+}
+
+const ZeroTransactionUserErrorTypeId = Symbol.for(prefixId("ZeroTransactionUserError"));
+export class ZeroTransactionUserError extends Data.TaggedError("ZeroTransactionUserError") {
+  readonly [ZeroTransactionUserErrorTypeId] = ZeroTransactionUserErrorTypeId;
+  static is(e: unknown): e is ZeroTransactionUserError {
+    return Predicate.hasProperty(e, ZeroTransactionUserErrorTypeId);
+  }
+}
+
+const ZeroMutationUserErrorTypeId = Symbol.for(prefixId("ZeroMutationUserError"));
+export class ZeroMutationUserError extends Data.TaggedError("ZeroMutationUserError")<{
+  cause: Cause.Cause<unknown>;
+}> {
+  readonly [ZeroMutationUserErrorTypeId] = ZeroMutationUserErrorTypeId;
+  static is(e: unknown): e is ZeroMutationUserError {
+    return Predicate.hasProperty(e, ZeroMutationUserErrorTypeId);
+  }
+
+  override get message() {
+    const err = Cause.squash(this.cause);
+    return err instanceof Error ? err.message : "exception was not of type `Error`";
+  }
+}
+
+class ZeroServerArgsParseError extends Data.TaggedError("ZeroServerArgsParseError")<{
+  cause: Cause.Cause<ParseResult.ParseError>;
+}> {}

package/src/snapshot.ts

@@ -0,0 +1,91 @@
+// TODO(zero): clean this up
+
+// Code borrowed from:
+// https://github.com/rocicorp/mono/blob/30f209f2946b4cf2cd2dee459849351498f11308/packages/zero-react/src/use-query.tsx
+// https://github.com/rocicorp/mono/blob/30f209f2946b4cf2cd2dee459849351498f11308/packages/shared/src/deep-clone.ts#L4
+
+import type { JSONValue, ReadonlyJSONValue } from "@rocicorp/zero";
+import type { HumanReadable, QueryResult } from "@rocicorp/zero/react";
+
+const emptyArray: unknown[] = [];
+
+const resultTypeUnknown = { type: "unknown" } as const;
+const resultTypeComplete = { type: "complete" } as const;
+
+const emptySnapshotSingularUnknown = [undefined, resultTypeUnknown] as const;
+const emptySnapshotSingularComplete = [undefined, resultTypeComplete] as const;
+const emptySnapshotPluralUnknown = [emptyArray, resultTypeUnknown] as const;
+const emptySnapshotPluralComplete = [emptyArray, resultTypeComplete] as const;
+
+export function getDefaultSnapshot<TReturn>(singular: boolean): QueryResult<TReturn> {
+  return (singular ? emptySnapshotSingularUnknown : emptySnapshotPluralUnknown) as QueryResult<TReturn>;
+}
+
+/**
+ * Returns a new snapshot or one of the empty predefined ones. Returning the
+ * predefined ones is important to prevent unnecessary re-renders in React.
+ */
+export function getSnapshot<TReturn>(
+  singular: boolean,
+  data: HumanReadable<TReturn>,
+  resultType: string,
+): QueryResult<TReturn> {
+  if (singular && data === undefined) {
+    return (resultType === "complete"
+      ? emptySnapshotSingularComplete
+      : emptySnapshotSingularUnknown) as unknown as QueryResult<TReturn>;
+  }
+
+  if (!singular && (data as unknown[]).length === 0) {
+    return (
+      resultType === "complete" ? emptySnapshotPluralComplete : emptySnapshotPluralUnknown
+    ) as QueryResult<TReturn>;
+  }
+
+  return [data, resultType === "complete" ? resultTypeComplete : resultTypeUnknown];
+}
+
+export function deepClone(value: ReadonlyJSONValue): JSONValue {
+  const seen: Array<ReadonlyJSONValue> = [];
+  return internalDeepClone(value, seen);
+}
+
+function internalDeepClone(value: ReadonlyJSONValue, seen: Array<ReadonlyJSONValue>): JSONValue {
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+    case "string":
+    case "undefined":
+      return value;
+    case "object": {
+      if (value === null) {
+        return null;
+      }
+      if (seen.includes(value)) {
+        throw new Error("Cyclic object");
+      }
+      seen.push(value);
+      if (Array.isArray(value)) {
+        const rv = value.map((v) => internalDeepClone(v, seen));
+        seen.pop();
+        return rv;
+      }
+
+      const obj: JSONValue = {};
+
+      for (const k in value) {
+        if (Object.hasOwn(value, k)) {
+          const v = (value as Record<string, ReadonlyJSONValue>)[k];
+          if (v !== undefined) {
+            obj[k] = internalDeepClone(v, seen);
+          }
+        }
+      }
+      seen.pop();
+      return obj;
+    }
+
+    default:
+      throw new Error(`Invalid type: ${typeof value}`);
+  }
+}

package/src/types.ts

@@ -0,0 +1,201 @@
+import * as Schema from "effect/Schema";
+
+// The code below was converted to Effect Schema from:
+// https://github.com/rocicorp/mono/blob/30f209f2946b4cf2cd2dee459849351498f11308/packages/zero-protocol/src/push.ts
+
+/** TODO: Defined as unknown for now */
+const JsonSchema = Schema.Unknown;
+
+const ZeroPrimaryKey = Schema.Array(Schema.String);
+
+const ZeroPrimaryKeyValue = Schema.Union(Schema.String, Schema.Number, Schema.Boolean);
+
+const ZeroPrimaryKeyValueRecord = Schema.Record({ key: Schema.String, value: ZeroPrimaryKeyValue });
+
+const ZeroValue = Schema.Union(JsonSchema, Schema.Undefined);
+const ZeroRow = Schema.Record({ key: Schema.String, value: ZeroValue });
+
+const CRUD_MUTATION_NAME = "_zero_crud";
+
+/**
+ * Inserts if entity with id does not already exist.
+ */
+const ZeroInsertOp = Schema.Struct({
+  op: Schema.Literal("insert"),
+  tableName: Schema.String,
+  primaryKey: ZeroPrimaryKey,
+  value: ZeroRow,
+});
+
+/**
+ * Upsert semantics. Inserts if entity with id does not already exist,
+ * otherwise updates existing entity with id.
+ */
+const ZeroUpsertOp = Schema.Struct({
+  op: Schema.Literal("upsert"),
+  tableName: Schema.String,
+  primaryKey: ZeroPrimaryKey,
+  value: ZeroRow,
+});
+
+/**
+ * Updates if entity with id exists, otherwise does nothing.
+ */
+const ZeroUpdateOp = Schema.Struct({
+  op: Schema.Literal("update"),
+  tableName: Schema.String,
+  primaryKey: ZeroPrimaryKey,
+  // Partial value with at least the primary key fields
+  value: ZeroRow,
+});
+
+/**
+ * Deletes entity with id if it exists, otherwise does nothing.
+ */
+const ZeroDeleteOp = Schema.Struct({
+  op: Schema.Literal("delete"),
+  tableName: Schema.String,
+  primaryKey: ZeroPrimaryKey,
+  // Partial value representing the primary key
+  value: ZeroPrimaryKeyValueRecord,
+});
+
+const ZeroCrudOp = Schema.Union(ZeroInsertOp, ZeroUpsertOp, ZeroUpdateOp, ZeroDeleteOp);
+
+const ZeroCrudArg = Schema.Struct({
+  ops: Schema.Array(ZeroCrudOp),
+});
+
+const ZeroCrudArgs = Schema.Tuple(ZeroCrudArg);
+
+const ZeroCrudMutation = Schema.Struct({
+  type: Schema.Literal("crud"),
+  id: Schema.Number,
+  clientID: Schema.String,
+  name: Schema.Literal(CRUD_MUTATION_NAME),
+  args: ZeroCrudArgs,
+  timestamp: Schema.Number,
+});
+
+const ZeroCustomMutation = Schema.Struct({
+  type: Schema.Literal("custom"),
+  id: Schema.Number,
+  clientID: Schema.String,
+  name: Schema.String,
+  args: Schema.Array(JsonSchema),
+  timestamp: Schema.Number,
+});
+
+export const ZeroMutation = Schema.Union(ZeroCrudMutation, ZeroCustomMutation);
+export type ZeroMutation = typeof ZeroMutation.Type;
+
+export const ZeroPushBody = Schema.Struct({
+  clientGroupID: Schema.String,
+  mutations: Schema.Array(ZeroMutation),
+  pushVersion: Schema.Number,
+  // For legacy (CRUD) mutations, the schema is tied to the client group /
+  // sync connection. For custom mutations, schema versioning is delegated
+  // to the custom protocol / api-server.
+  schemaVersion: Schema.optional(Schema.Number),
+  timestamp: Schema.Number,
+  requestID: Schema.String,
+});
+export type ZeroPushBody = typeof ZeroPushBody.Type;
+
+// biome-ignore lint/correctness/noUnusedVariables: borrowed code
+const ZeroPushMessage = Schema.Tuple(Schema.Literal("push"), ZeroPushBody);
+
+const ZeroMutationId = Schema.Struct({
+  id: Schema.Number,
+  clientID: Schema.String,
+});
+
+export const ZeroAppError = Schema.Struct({
+  error: Schema.Literal("app"),
+  // The user can return any additional data here
+  details: Schema.optional(JsonSchema),
+});
+
+export type ZeroAppError = typeof ZeroAppError.Type;
+
+export const ZeroError = Schema.Struct({
+  error: Schema.Union(Schema.Literal("oooMutation"), Schema.Literal("alreadyProcessed")),
+  details: Schema.optional(JsonSchema),
+});
+
+export type ZeroError = typeof ZeroError.Type;
+
+const ZeroMutationOk = Schema.Struct({
+  // The user can return any additional data here
+  data: Schema.optional(JsonSchema),
+});
+
+const ZeroMutationError = Schema.Union(ZeroAppError, ZeroError);
+
+// We flip the original order here as otherwise values of type ZeroMutationError would get parsed as ZeroMutationOk with empty `data`
+export const ZeroMutationResult = Schema.Union(ZeroMutationError, ZeroMutationOk);
+export type ZeroMutationResult = typeof ZeroMutationResult.Type;
+
+export const ZeroMutationResponse = Schema.Struct({
+  id: ZeroMutationId,
+  result: ZeroMutationResult,
+});
+export type ZeroMutationResponse = typeof ZeroMutationResponse.Type;
+
+const ZeroPushOk = Schema.Struct({
+  mutations: Schema.Array(ZeroMutationResponse),
+});
+
+const ZeroUnsupportedPushVersion = Schema.Struct({
+  error: Schema.Literal("unsupportedPushVersion"),
+  // optional for backwards compatibility
+  // This field is included so the client knows which mutations
+  // were not processed by the server.
+  mutationIDs: Schema.optional(Schema.Array(ZeroMutationId)),
+});
+
+const ZeroUnsupportedSchemaVersion = Schema.Struct({
+  error: Schema.Literal("unsupportedSchemaVersion"),
+  // optional for backwards compatibility
+  // This field is included so the client knows which mutations
+  // were not processed by the server.
+  mutationIDs: Schema.optional(Schema.Array(ZeroMutationId)),
+});
+
+const ZeroHttpError = Schema.Struct({
+  error: Schema.Literal("http"),
+  status: Schema.Number,
+  details: Schema.String,
+  mutationIDs: Schema.optional(Schema.Array(ZeroMutationId)),
+});
+
+const ZeroPusherError = Schema.Struct({
+  error: Schema.Literal("zeroPusher"),
+  details: Schema.String,
+  mutationIDs: Schema.optional(Schema.Array(ZeroMutationId)),
+});
+
+const ZeroPushError = Schema.Union(
+  ZeroUnsupportedPushVersion,
+  ZeroUnsupportedSchemaVersion,
+  ZeroHttpError,
+  ZeroPusherError,
+);
+
+export const ZeroPushResponse = Schema.Union(ZeroPushOk, ZeroPushError);
+export type ZeroPushResponse = typeof ZeroPushResponse.Type;
+
+// biome-ignore lint/correctness/noUnusedVariables: borrowed code
+const ZeroPushResponseMessage = Schema.Tuple(Schema.Literal("pushResponse"), ZeroPushResponse);
+
+// biome-ignore lint/correctness/noUnusedVariables: borrowed code
+const ZeroAckMutationResponsesMessage = Schema.Tuple(Schema.Literal("ackMutationResponses"), ZeroMutationId);
+
+/**
+ * The schema for the querystring parameters of the custom push endpoint.
+ */
+export const ZeroPushParams = Schema.Struct({
+  schema: Schema.String,
+  appID: Schema.String,
+});
+export type ZeroPushParams = typeof ZeroPushParams.Type;

package/src/utils.ts

@@ -0,0 +1,4 @@
+/**
+ * Prefix a string with the package name.
+ */
+export const prefixId = <S extends string>(name: S) => `effect-zero/${name}` as const;