sailfork / t3code-github / .repos/ alchemy-effect/ packages/ domain/ src/ ExternalSystem.ts

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 * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";
import { DefinitionError, ReservedOperation } from "./DefinitionError.ts";
import type { Fields } from "./Event.ts";
import * as Telemetry from "./Telemetry.ts";

type OpImpl = (args: unknown) => Effect.Effect<unknown, unknown, unknown>;

/**
 * Trace every call to an external system: one client span per call, named
 * after the system and operation, plus a call count by outcome.
 *
 * @internal
 */
export const observeOps = (
  system: string,
  impl: Readonly<Record<string, OpImpl>>,
): Record<string, OpImpl> =>
  Object.fromEntries(
    Object.entries(impl).map(([op, call]) => [
      op,
      (args: unknown) =>
        call(args).pipe(
          Effect.onExit((exit) =>
            Telemetry.record(Telemetry.externalCalls, {
              "domain.system": system,
              "domain.operation": op,
              "domain.outcome": Exit.isSuccess(exit) ? "ok" : "failed",
            }),
          ),
          Effect.withSpan(`Domain.external ${system}.${op}`, {
            kind: "client",
            attributes: { "domain.system": system, "domain.operation": op },
          }),
        ),
    ]),
  );

/**
 * Sees every call to an implemented external system. A story provides one, so
 * it can assert what each real call was sent and what it returned.
 *
 * @internal
 */
export interface CallRecorder {
  readonly record: (
    system: string,
    op: string,
    args: unknown,
    call: Effect.Effect<unknown, unknown, unknown>,
  ) => Effect.Effect<unknown, unknown, unknown>;
}

/** @internal */
export const CallRecorder = Context.Reference<CallRecorder | undefined>(
  "alchemy/Domain/ExternalSystem/CallRecorder",
  { defaultValue: () => undefined },
);

const recordOps = (
  system: string,
  impl: Readonly<Record<string, OpImpl>>,
): Record<string, OpImpl> =>
  Object.fromEntries(
    Object.entries(impl).map(([op, call]) => [
      op,
      Effect.fn(function* (args: unknown) {
        const recorder = yield* CallRecorder;
        return yield* recorder ? recorder.record(system, op, args, call(args)) : call(args);
      }),
    ]),
  );

/**
 * A call to an external system broke its declared schema: the model sent
 * arguments the operation's `args` reject, or the adapter answered with a
 * value or error the operation's `success` or `error` reject. It is a defect,
 * not a business error, because the declaration and the implementation
 * disagree.
 */
export class ExternalSystemSchemaError extends Data.TaggedError("ExternalSystemSchemaError")<{
  readonly system: string;
  readonly op: string;
  /** The side of the call the schema rejected. */
  readonly part: "args" | "success" | "error";
  readonly message: string;
}> {}

const describePart = {
  args: "was called with arguments its schema rejects",
  success: "returned a value its success schema rejects",
  error: "failed with an error its error schema rejects",
} as const;

/** A built check: the value its schema accepts, or an {@link ExternalSystemSchemaError} defect. */
type Check = (value: unknown) => Exit.Exit<unknown>;

/** One operation's built checks. `args` and `success` are absent when it declares none. */
interface OpChecks {
  readonly args: Check | undefined;
  readonly success: Check | undefined;
  readonly error: Check;
}

const makeCheck = (
  system: string,
  op: string,
  part: keyof typeof describePart,
  schema: Schema.Top,
): Check => {
  // Only the type side: it validates values and never re-runs a transformation.
  const decode = Schema.decodeUnknownExit(Schema.toType(schema) as Schema.Decoder<unknown>) as (
    value: unknown,
  ) => Exit.Exit<unknown, Schema.SchemaError>;
  return (value) => {
    const exit = decode(value);
    if (Exit.isSuccess(exit)) return Exit.succeed(exit.value);
    const found = Cause.findError(exit.cause);
    return Exit.die(
      found._tag === "Success"
        ? new ExternalSystemSchemaError({
            system,
            op,
            part,
            message: `${system}.${op} ${describePart[part]}\n${found.success.message}`,
          })
        : // A defect inside the schema passes through.
          Cause.squash(exit.cause),
    );
  };
};

/**
 * Build the checks for every operation of a system, once: its arguments, its
 * success value and its typed error.
 *
 * @internal
 */
export const compileChecks = (
  system: string,
  ops: Readonly<Record<string, OpSpec>>,
): Effect.Effect<Readonly<Record<string, OpChecks>>> =>
  Effect.sync(() =>
    Object.fromEntries(
      Object.entries(ops).map(([op, spec]) => [
        op,
        {
          args:
            spec.args === undefined
              ? undefined
              : makeCheck(system, op, "args", Schema.Struct(spec.args)),
          success:
            spec.success === undefined
              ? undefined
              : makeCheck(system, op, "success", successSchema(spec)),
          error: makeCheck(system, op, "error", errorSchema(spec)),
        } satisfies OpChecks,
      ]),
    ),
  );

/**
 * Check every call against its operation's built checks: the arguments before
 * the implementation runs, and its success value or typed error after. A value
 * a schema rejects becomes an {@link ExternalSystemSchemaError} defect. Defects
 * pass through.
 *
 * @internal
 */
export const validateOps = (
  checks: Readonly<Record<string, OpChecks>>,
  impl: Readonly<Record<string, OpImpl>>,
): Record<string, OpImpl> =>
  Object.fromEntries(
    Object.entries(impl).map(([op, call]): [string, OpImpl] => {
      const check = checks[op];
      if (check === undefined) return [op, call];
      const { args, success, error } = check;
      const checked: OpImpl = (input) =>
        Effect.matchEffect(args ? Effect.flatMap(args(input), call) : call(input), {
          onSuccess: success ?? Effect.succeed,
          onFailure: (failure) => Effect.flatMap(error(failure), Effect.fail),
        });
      return [op, checked];
    }),
  );

/**
 * Options for {@link ExternalSystemClass.toLayer}.
 */
export interface ToLayerOptions {
  /**
   * Check every call against the operation's schemas. Defaults to `true`.
   * Turn it off only when the check costs too much, for example on a large
   * payload an adapter already validates.
   */
  readonly validate?: boolean;
}

/**
 * One operation of an external system: its arguments, success value and business errors.
 * `error` is one schema, or a list of them when the vendor can refuse in several ways.
 */
export interface OpSpec {
  readonly args?: Fields;
  readonly success?: Fields | Schema.Top;
  readonly error?: Schema.Top | ReadonlyArray<Schema.Top>;
}

type ArgsOf<S extends OpSpec> = S["args"] extends Fields ? Schema.Struct<S["args"]>["Type"] : void;
type SuccessOf<S extends OpSpec> = S["success"] extends Schema.Top
  ? S["success"]["Type"]
  : S["success"] extends Fields
    ? Schema.Struct<S["success"]>["Type"]
    : void;
type ErrorOf<S extends OpSpec> =
  S["error"] extends ReadonlyArray<Schema.Top>
    ? S["error"][number]["Type"]
    : S["error"] extends Schema.Top
      ? S["error"]["Type"]
      : never;

/**
 * The service shape of an external system: one Effect-returning function per operation.
 */
export type Shape<Ops extends Record<string, OpSpec>> = {
  readonly [K in keyof Ops]: (
    args: ArgsOf<Ops[K]>,
  ) => Effect.Effect<SuccessOf<Ops[K]>, ErrorOf<Ops[K]>>;
};

/**
 * A reference to one external system operation, used by stories (`call`, `succeed`, `fail`).
 */
export interface Op<Args = unknown, Success = unknown, Error = unknown> {
  readonly kind: "ExternalSystemOp";
  readonly system: string;
  readonly op: string;
  readonly "~args"?: Args;
  readonly "~success"?: Success;
  readonly "~error"?: Error;
}

/**
 * Structural constraint satisfied by every external system class.
 */
export interface Any extends Context.Key<unknown, unknown> {
  readonly kind: "ExternalSystem";
  readonly systemName: string;
  readonly ops: Record<string, OpSpec>;
}

/** The requirement identifier of an external system class. */
export type Identifier<P extends Any> = P extends Context.Key<infer I, unknown> ? I : never;

/**
 * Type-level identity of an external system in an Effect's requirements.
 */
export interface ExternalSystemKey<Name extends string> {
  readonly "~alchemy/Domain/ExternalSystem": Name;
}

const RESERVED = [
  "name",
  "length",
  "prototype",
  "kind",
  "systemName",
  "ops",
  "toLayer",
  "key",
] as const;
type Reserved = (typeof RESERVED)[number];
const reserved = new Set<string>(RESERVED);

/**
 * An outside system your model calls, such as a payment provider or a fraud
 * scorer, declared as the operations the model uses. It's an Effect service:
 * policies `yield*` it, an adapter implements it with `toLayer`, and stories
 * answer its calls themselves, so the model depends on what it asks for and
 * never on a vendor.
 *
 * ### Declaring an external system and an adapter
 * **Example:** A fraud scorer
 * ```typescript
 * import * as Domain from "@alchemy.run/domain";
 * import * as Effect from "effect/Effect";
 * import * as Schema from "effect/Schema";
 *
 * export class FraudCheck extends Domain.ExternalSystem("FraudCheck", {
 *   score: { args: { accountId: Schema.String, amount: Schema.Int }, success: { risk: Schema.Number } },
 * }) {}
 *
 * export const SiftFraudCheck = FraudCheck.toLayer(
 *   Effect.succeed({
 *     score: ({ amount }) => Effect.succeed({ risk: amount >= 80_000 ? 0.95 : 0.05 }),
 *   }),
 * );
 * ```
 *
 * @primitive
 */
export const make = <const Name extends string, const Ops extends Record<string, OpSpec>>(
  name: Name,
  // An operation named after a static of the class would replace it.
  ops: Ops & { readonly [K in Extract<keyof Ops, Reserved>]: never },
): ExternalSystemClass<Name, Ops> => {
  const Tag = Context.Service<ExternalSystemKey<Name>, Shape<Ops>>()(
    `alchemy/Domain/ExternalSystem/${name}`,
  );
  const cls = class extends Tag {
    static readonly kind = "ExternalSystem" as const;
    static readonly systemName: Name = name;
    static readonly ops: Ops = ops;
    /** Implement the external system with an Effect that builds its service. */
    static toLayer<E, R>(
      build: Effect.Effect<Shape<Ops>, E, R>,
      options?: ToLayerOptions,
    ): Layer.Layer<ExternalSystemKey<Name>, E, R> {
      return Layer.effect(
        Tag,
        Effect.gen(function* () {
          const clash = Object.keys(ops).find((op) => reserved.has(op));
          if (clash !== undefined) {
            return yield* Effect.die(
              new DefinitionError({
                reason: new ReservedOperation({ system: name, operation: clash }),
              }),
            );
          }
          const checks = options?.validate === false ? undefined : yield* compileChecks(name, ops);
          const impl = (yield* build) as Record<string, OpImpl>;
          const checked = checks === undefined ? impl : validateOps(checks, impl);
          return observeOps(name, recordOps(name, checked)) as never;
        }),
      );
    }
  };
  for (const op of Object.keys(ops)) {
    // The signature rejects a reserved name; toLayer dies if one gets through.
    if (reserved.has(op)) continue;
    // oxlint-disable-next-line effecttsgo/floating-effect -- returns `cls`, which is Effect-able; nothing to run
    Object.defineProperty(cls, op, {
      value: { kind: "ExternalSystemOp", system: name, op } satisfies Op,
      enumerable: true,
    });
  }
  return cls as unknown as ExternalSystemClass<Name, Ops>;
};

/**
 * The class type returned by {@link make}.
 */
export type ExternalSystemClass<
  Name extends string,
  Ops extends Record<string, OpSpec>,
> = Context.ServiceClass<ExternalSystemKey<Name>, string, Shape<Ops>> & {
  readonly kind: "ExternalSystem";
  readonly systemName: Name;
  readonly ops: Ops;
  /**
   * Implement the external system with an Effect that builds its service.
   * Every call is checked against the operation's schemas unless
   * `validate: false`.
   */
  toLayer<E, R>(
    build: Effect.Effect<Shape<Ops>, E, R>,
    options?: ToLayerOptions,
  ): Layer.Layer<ExternalSystemKey<Name>, E, R>;
} & {
  readonly [K in keyof Ops]: Op<ArgsOf<Ops[K]>, SuccessOf<Ops[K]>, ErrorOf<Ops[K]>>;
};

/** @internal */
export const successSchema = (spec: OpSpec): Schema.Top =>
  spec.success === undefined
    ? Schema.Void
    : "ast" in (spec.success as object)
      ? (spec.success as Schema.Top)
      : Schema.Struct(spec.success as Fields);

/**
 * The schema of an operation's declared `error`: the schema itself, a
 * `Schema.Union` of a list, or `Schema.Never` when it declares none.
 *
 * @internal
 */
export const errorSchema = (spec: OpSpec): Schema.Top =>
  spec.error === undefined
    ? Schema.Never
    : Array.isArray(spec.error)
      ? Schema.Union(spec.error as ReadonlyArray<Schema.Top>)
      : (spec.error as Schema.Top);