@beignet/core 0.0.1

package/src/application/index.ts

@@ -0,0 +1,747 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Any Standard Schema validator type
+ */
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Infer the output type from a Standard Schema
+ */
+export type InferOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Infer the input type accepted by a Standard Schema
+ */
+export type InferInput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferInput<T>;
+
+type SchemaInput<T> = T extends StandardSchemaV1 ? InferInput<T> : never;
+type SchemaOutput<T> = T extends StandardSchemaV1 ? InferOutput<T> : never;
+
+export type UseCaseValidationPhase = "input" | "output";
+
+/**
+ * Error thrown when a use case input or output fails schema validation.
+ */
+export class UseCaseValidationError extends Error {
+  readonly name = "UseCaseValidationError";
+  readonly useCaseName: string;
+  readonly phase: UseCaseValidationPhase;
+  readonly issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(args: {
+    useCaseName: string;
+    phase: UseCaseValidationPhase;
+    issues: readonly StandardSchemaV1.Issue[];
+  }) {
+    super(
+      `Use case "${args.useCaseName}" ${args.phase} validation failed: ${formatIssues(args.issues)}`,
+    );
+    this.useCaseName = args.useCaseName;
+    this.phase = args.phase;
+    this.issues = args.issues;
+  }
+}
+
+/**
+ * Error thrown when a use case tries to emit an event it did not declare with
+ * `.emits(...)`.
+ */
+export class UseCaseEventDeclarationError extends Error {
+  readonly name = "UseCaseEventDeclarationError";
+  readonly useCaseName: string;
+  readonly eventName: string;
+  readonly declaredEventNames: readonly string[];
+
+  constructor(args: {
+    useCaseName: string;
+    eventName: string;
+    declaredEventNames: readonly string[];
+  }) {
+    const declared =
+      args.declaredEventNames.length > 0
+        ? args.declaredEventNames.map((name) => `"${name}"`).join(", ")
+        : "none";
+
+    super(
+      `Use case "${args.useCaseName}" cannot emit undeclared event "${args.eventName}". Declare it with .emits([...]). Declared events: ${declared}.`,
+    );
+    this.useCaseName = args.useCaseName;
+    this.eventName = args.eventName;
+    this.declaredEventNames = args.declaredEventNames;
+  }
+}
+
+function formatPath(path: StandardSchemaV1.Issue["path"]): string {
+  if (!path?.length) return "";
+  return path
+    .map((segment) =>
+      typeof segment === "object" && segment !== null && "key" in segment
+        ? String(segment.key)
+        : String(segment),
+    )
+    .join(".");
+}
+
+function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues
+    .map((issue) => {
+      const path = formatPath(issue.path);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+}
+
+/**
+ * Error thrown when a use-case event helper fails to validate an event payload
+ * before recording or publishing it.
+ */
+export class UseCaseEventValidationError extends Error {
+  readonly name = "UseCaseEventValidationError";
+  readonly useCaseName: string;
+  readonly eventName: string;
+  readonly issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(args: {
+    useCaseName: string;
+    eventName: string;
+    issues: readonly StandardSchemaV1.Issue[];
+  }) {
+    super(
+      `Use case "${args.useCaseName}" event "${args.eventName}" payload validation failed: ${formatIssues(args.issues)}`,
+    );
+    this.useCaseName = args.useCaseName;
+    this.eventName = args.eventName;
+    this.issues = args.issues;
+  }
+}
+
+async function parseSchema<TSchema extends StandardSchemaV1>(
+  schema: TSchema,
+  value: unknown,
+  useCaseName: string,
+  phase: UseCaseValidationPhase,
+): Promise<InferOutput<TSchema>> {
+  const result = await schema["~standard"].validate(value);
+  if (result.issues?.length) {
+    throw new UseCaseValidationError({
+      useCaseName,
+      phase,
+      issues: result.issues,
+    });
+  }
+  if ("value" in result) {
+    return result.value as InferOutput<TSchema>;
+  }
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+/**
+ * Represents a domain event definition (from @beignet/core/domain or compatible).
+ * This is a minimal interface to avoid hard dependency on @beignet/core/domain.
+ */
+export interface DomainEventLike {
+  name: string;
+  payload: StandardSchema;
+}
+
+/**
+ * Infer the output payload type from a use-case event definition.
+ */
+export type InferUseCaseEventPayload<E extends DomainEventLike> =
+  E["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+
+/**
+ * Minimal recorder shape accepted by use-case event helpers.
+ */
+export interface UseCaseEventRecorderTarget {
+  record<E extends DomainEventLike>(
+    event: E,
+    payload: InferUseCaseEventPayload<E>,
+  ): void;
+}
+
+/**
+ * Minimal event-bus shape accepted by use-case event helpers.
+ */
+export interface UseCaseEventBusTarget {
+  publish<E extends DomainEventLike>(
+    event: E,
+    payload: InferUseCaseEventPayload<E>,
+  ): Promise<void> | void;
+}
+
+/**
+ * Event helper scoped to the events declared by a use case.
+ */
+export interface UseCaseEventHelpers<Emits extends readonly DomainEventLike[]> {
+  /**
+   * The exact event definitions declared with `.emits(...)`.
+   */
+  readonly declared: Emits;
+
+  /**
+   * Return whether an event is declared by this use case.
+   */
+  isDeclared(event: DomainEventLike): boolean;
+
+  /**
+   * Throw if an event is not declared by this use case.
+   */
+  assertDeclared(event: DomainEventLike): void;
+
+  /**
+   * Validate and record a declared event into a transaction-scoped recorder.
+   */
+  record<E extends Emits[number]>(
+    recorder: UseCaseEventRecorderTarget,
+    event: E,
+    payload: InferUseCaseEventPayload<E>,
+  ): Promise<void>;
+
+  /**
+   * Validate and publish a declared event directly through an event bus.
+   */
+  publish<E extends Emits[number]>(
+    eventBus: UseCaseEventBusTarget,
+    event: E,
+    payload: InferUseCaseEventPayload<E>,
+  ): Promise<void>;
+}
+
+async function parseEventPayload<E extends DomainEventLike>(
+  event: E,
+  payload: unknown,
+  useCaseName: string,
+): Promise<InferUseCaseEventPayload<E>> {
+  const result = await event.payload["~standard"].validate(payload);
+
+  if (result.issues?.length) {
+    throw new UseCaseEventValidationError({
+      useCaseName,
+      eventName: event.name,
+      issues: result.issues,
+    });
+  }
+
+  if ("value" in result) {
+    return result.value as InferUseCaseEventPayload<E>;
+  }
+
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+function createUseCaseEventHelpers<Emits extends readonly DomainEventLike[]>(
+  useCaseName: string,
+  declared: Emits,
+): UseCaseEventHelpers<Emits> {
+  const declaredEventNames = declared.map((event) => event.name);
+  const declaredEventByName = new Map<string, DomainEventLike>();
+
+  for (const event of declared) {
+    if (declaredEventByName.has(event.name)) {
+      throw new Error(
+        `Use case "${useCaseName}" declares duplicate event "${event.name}". Event names must be unique within .emits([...]).`,
+      );
+    }
+
+    declaredEventByName.set(event.name, event);
+  }
+
+  function resolveDeclared(event: DomainEventLike): DomainEventLike {
+    const declaredEvent = declaredEventByName.get(event.name);
+    if (declaredEvent) return declaredEvent;
+
+    throw new UseCaseEventDeclarationError({
+      useCaseName,
+      eventName: event.name,
+      declaredEventNames,
+    });
+  }
+
+  function assertDeclared(event: DomainEventLike): void {
+    resolveDeclared(event);
+  }
+
+  return {
+    declared,
+    isDeclared(event) {
+      return declaredEventByName.has(event.name);
+    },
+    assertDeclared,
+    async record(recorder, event, payload) {
+      const declaredEvent = resolveDeclared(event) as typeof event;
+      const parsed = await parseEventPayload(
+        declaredEvent,
+        payload,
+        useCaseName,
+      );
+      recorder.record(declaredEvent, parsed);
+    },
+    async publish(eventBus, event, payload) {
+      const declaredEvent = resolveDeclared(event) as typeof event;
+      const parsed = await parseEventPayload(
+        declaredEvent,
+        payload,
+        useCaseName,
+      );
+      await eventBus.publish(declaredEvent, parsed);
+    },
+  };
+}
+
+/**
+ * Use case kind - distinguishes commands (write/side-effect) from queries (read-only)
+ */
+export type UseCaseKind = "command" | "query";
+
+/**
+ * Use case definition - the final form consumed by server adapters
+ */
+export interface UseCaseDef<
+  Ctx,
+  Name extends string,
+  Kind extends UseCaseKind,
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+  Emits extends readonly DomainEventLike[] = readonly [],
+> {
+  name: Name;
+  kind: Kind;
+  /** Input schema, suitable for reuse in HTTP contracts and forms. */
+  inputSchema: InputSchema;
+  /** Output schema, suitable for reuse in HTTP contracts and clients. */
+  outputSchema: OutputSchema;
+  emits: Emits;
+  run: (args: {
+    ctx: Ctx;
+    input: InferInput<InputSchema>;
+  }) => Promise<InferOutput<OutputSchema>>;
+}
+
+/**
+ * Event passed to the onRun hook for instrumentation
+ */
+export interface UseCaseRunEvent<Ctx> {
+  name: string;
+  kind: UseCaseKind;
+  phase: "start" | "end" | "error";
+  durationMs?: number;
+  error?: unknown;
+  ctx: Ctx;
+}
+
+/**
+ * Options for createUseCase
+ */
+export interface CreateUseCaseOptions<Ctx> {
+  /**
+   * Optional instrumentation hook called on use case start, end, and error.
+   */
+  onRun?: (event: UseCaseRunEvent<Ctx>) => void;
+
+  /**
+   * Enable or disable schema validation for use case boundaries.
+   *
+   * Defaults to validating both input and output. Pass `false` to opt out, or
+   * configure phases independently with `{ input: boolean, output: boolean }`.
+   */
+  validate?: boolean | { input?: boolean; output?: boolean };
+}
+
+type ValidationOptions = {
+  input: boolean;
+  output: boolean;
+};
+
+function normalizeValidationOptions(
+  validate: CreateUseCaseOptions<unknown>["validate"],
+): ValidationOptions {
+  if (validate === false) {
+    return { input: false, output: false };
+  }
+  if (typeof validate === "object" && validate !== null) {
+    return {
+      input: validate.input ?? true,
+      output: validate.output ?? true,
+    };
+  }
+  return { input: true, output: true };
+}
+
+/**
+ * Internal configuration for the use case builder
+ */
+interface UseCaseBuilderConfig<
+  Name extends string,
+  Kind extends UseCaseKind,
+  InputSchema extends StandardSchemaV1 | undefined,
+  OutputSchema extends StandardSchemaV1 | undefined,
+  Emits extends readonly DomainEventLike[],
+> {
+  name: Name;
+  kind: Kind;
+  input?: InputSchema;
+  output?: OutputSchema;
+  emits: Emits;
+}
+
+/**
+ * Fluent builder for creating use cases
+ */
+class UseCaseBuilder<
+  Ctx,
+  Name extends string,
+  Kind extends UseCaseKind,
+  InputSchema extends StandardSchemaV1 | undefined,
+  OutputSchema extends StandardSchemaV1 | undefined,
+  Emits extends readonly DomainEventLike[] = readonly [],
+> {
+  constructor(
+    private readonly config: UseCaseBuilderConfig<
+      Name,
+      Kind,
+      InputSchema,
+      OutputSchema,
+      Emits
+    >,
+    private readonly onRun?: (event: UseCaseRunEvent<Ctx>) => void,
+    private readonly validation: ValidationOptions = {
+      input: true,
+      output: true,
+    },
+  ) {}
+
+  /**
+   * Define the input schema for this use case
+   */
+  input<I extends StandardSchemaV1>(
+    schema: I,
+  ): UseCaseBuilder<Ctx, Name, Kind, I, OutputSchema, Emits> {
+    return new UseCaseBuilder<Ctx, Name, Kind, I, OutputSchema, Emits>(
+      {
+        ...this.config,
+        input: schema,
+      },
+      this.onRun,
+      this.validation,
+    );
+  }
+
+  /**
+   * Define the output schema for this use case
+   */
+  output<O extends StandardSchemaV1>(
+    schema: O,
+  ): UseCaseBuilder<Ctx, Name, Kind, InputSchema, O, Emits> {
+    return new UseCaseBuilder<Ctx, Name, Kind, InputSchema, O, Emits>(
+      {
+        ...this.config,
+        output: schema,
+      },
+      this.onRun,
+      this.validation,
+    );
+  }
+
+  /**
+   * Define the domain events that this use case may emit.
+   */
+  emits<E extends readonly DomainEventLike[]>(
+    events: E,
+  ): UseCaseBuilder<Ctx, Name, Kind, InputSchema, OutputSchema, E> {
+    return new UseCaseBuilder<Ctx, Name, Kind, InputSchema, OutputSchema, E>(
+      {
+        ...this.config,
+        emits: events,
+      },
+      this.onRun,
+      this.validation,
+    );
+  }
+
+  /**
+   * Define the run function and finalize the use case definition
+   */
+  run(
+    fn: InputSchema extends StandardSchemaV1
+      ? OutputSchema extends StandardSchemaV1
+        ? (args: {
+            ctx: Ctx;
+            input: SchemaOutput<InputSchema>;
+            events: UseCaseEventHelpers<Emits>;
+          }) => Promise<SchemaOutput<OutputSchema>> | SchemaOutput<OutputSchema>
+        : never
+      : never,
+  ): InputSchema extends StandardSchemaV1
+    ? OutputSchema extends StandardSchemaV1
+      ? UseCaseDef<Ctx, Name, Kind, InputSchema, OutputSchema, Emits>
+      : never
+    : never {
+    if (!this.config.input) {
+      throw new Error(`Use case "${this.config.name}" is missing input schema`);
+    }
+    if (!this.config.output) {
+      throw new Error(
+        `Use case "${this.config.name}" is missing output schema`,
+      );
+    }
+
+    const useCaseName = this.config.name;
+    const useCaseKind = this.config.kind;
+    const onRun = this.onRun;
+    const inputSchema = this.config.input as Extract<
+      InputSchema,
+      StandardSchemaV1
+    >;
+    const outputSchema = this.config.output as Extract<
+      OutputSchema,
+      StandardSchemaV1
+    >;
+    const validation = this.validation;
+    const eventHelpers = createUseCaseEventHelpers(
+      useCaseName,
+      this.config.emits,
+    );
+
+    const runFn = async (
+      args: InputSchema extends StandardSchemaV1
+        ? OutputSchema extends StandardSchemaV1
+          ? {
+              ctx: Ctx;
+              input: SchemaInput<InputSchema>;
+            }
+          : never
+        : never,
+    ) => {
+      const startedAt = Date.now();
+      onRun?.({
+        name: useCaseName,
+        kind: useCaseKind,
+        phase: "start",
+        ctx: args.ctx,
+      });
+
+      try {
+        const parsedInput = validation.input
+          ? await parseSchema(inputSchema, args.input, useCaseName, "input")
+          : (args.input as SchemaOutput<InputSchema>);
+
+        const rawResult = await fn({
+          ctx: args.ctx,
+          input: parsedInput,
+          events: eventHelpers,
+        });
+
+        const result = validation.output
+          ? await parseSchema(outputSchema, rawResult, useCaseName, "output")
+          : (rawResult as SchemaOutput<OutputSchema>);
+
+        onRun?.({
+          name: useCaseName,
+          kind: useCaseKind,
+          phase: "end",
+          durationMs: Date.now() - startedAt,
+          ctx: args.ctx,
+        });
+
+        return result;
+      } catch (err) {
+        onRun?.({
+          name: useCaseName,
+          kind: useCaseKind,
+          phase: "error",
+          durationMs: Date.now() - startedAt,
+          error: err,
+          ctx: args.ctx,
+        });
+        throw err;
+      }
+    };
+
+    // Type assertion required to satisfy the conditional return type.
+    // The runtime checks above ensure input/output schemas are set.
+    // The conditional types ensure type safety at compile time - run() returns
+    // UseCaseDef only when both InputSchema and OutputSchema are StandardSchemaV1.
+    return {
+      name: this.config.name,
+      kind: this.config.kind,
+      inputSchema: this.config.input,
+      outputSchema: this.config.output,
+      emits: this.config.emits,
+      run: runFn,
+    } as unknown as InputSchema extends StandardSchemaV1
+      ? OutputSchema extends StandardSchemaV1
+        ? UseCaseDef<Ctx, Name, Kind, InputSchema, OutputSchema, Emits>
+        : never
+      : never;
+  }
+}
+
+/**
+ * Root builder returned by createUseCase.
+ */
+export interface UseCaseBuilderRoot<Ctx> {
+  /**
+   * Create a command use case (write/side-effect path)
+   */
+  command<Name extends string>(
+    name: Name,
+  ): UseCaseBuilder<Ctx, Name, "command", undefined, undefined, readonly []>;
+
+  /**
+   * Create a query use case (read-only path)
+   */
+  query<Name extends string>(
+    name: Name,
+  ): UseCaseBuilder<Ctx, Name, "query", undefined, undefined, readonly []>;
+}
+
+export type UseCaseContext<TUseCase> = TUseCase extends {
+  run: (args: {
+    ctx: infer Ctx;
+    input: infer _Input;
+  }) => Promise<infer _Output>;
+}
+  ? Ctx
+  : never;
+
+export type UseCaseInput<TUseCase> = TUseCase extends {
+  run: (args: {
+    ctx: infer _Ctx;
+    input: infer Input;
+  }) => Promise<infer _Output>;
+}
+  ? Input
+  : never;
+
+export type UseCaseOutput<TUseCase> = TUseCase extends {
+  run: (args: {
+    ctx: infer _Ctx;
+    input: infer _Input;
+  }) => Promise<infer Output>;
+}
+  ? Output
+  : never;
+
+type MaybePromise<T> = T | Promise<T>;
+
+export interface UseCaseTester<Ctx> {
+  /**
+   * Create a fresh test context.
+   */
+  ctx(): Promise<Ctx>;
+
+  /**
+   * Run a use case with a typed input and either a fresh or explicit context.
+   */
+  run<Input, Output>(
+    useCase: {
+      run(args: { ctx: Ctx; input: Input }): Promise<Output>;
+    },
+    input: Input,
+    options?: { ctx?: Ctx },
+  ): Promise<Output>;
+}
+
+/**
+ * Create a small test harness for use cases.
+ *
+ * Pass a context factory when tests mutate ports or state. Pass a fixed context
+ * for simple, immutable tests.
+ */
+export function createUseCaseTester<Ctx>(
+  createContext: Ctx | (() => MaybePromise<Ctx>),
+): UseCaseTester<Ctx> {
+  const ctx = async () =>
+    typeof createContext === "function"
+      ? await (createContext as () => MaybePromise<Ctx>)()
+      : createContext;
+
+  return {
+    ctx,
+    async run<Input, Output>(
+      useCase: {
+        run(args: { ctx: Ctx; input: Input }): Promise<Output>;
+      },
+      input: Input,
+      options?: { ctx?: Ctx },
+    ): Promise<Output> {
+      return useCase.run({
+        ctx: options?.ctx ?? (await ctx()),
+        input,
+      });
+    },
+  };
+}
+
+/**
+ * Create a use case builder with a specific context type.
+ *
+ * @example
+ * ```ts
+ * import { createUseCase } from "@beignet/core/application";
+ * import type { AppCtx } from "./ctx";
+ *
+ * export const useCase = createUseCase<AppCtx>();
+ *
+ * export const createTodo = useCase
+ *   .command("todos.create")
+ *   .input(CreateTodoInput)
+ *   .output(CreateTodoOutput)
+ *   .run(async ({ ctx, input }) => {
+ *     const todo = await ctx.ports.db.todos.create(input);
+ *     return { id: todo.id, title: todo.title };
+ *   });
+ * ```
+ */
+
+/** Empty emits array used as default */
+const EMPTY_EMITS = [] as const;
+
+export function createUseCase<Ctx>(
+  options?: CreateUseCaseOptions<Ctx>,
+): UseCaseBuilderRoot<Ctx> {
+  const onRun = options?.onRun;
+  const validation = normalizeValidationOptions(options?.validate);
+  return {
+    command<Name extends string>(name: Name) {
+      return new UseCaseBuilder<
+        Ctx,
+        Name,
+        "command",
+        undefined,
+        undefined,
+        readonly []
+      >(
+        {
+          name,
+          kind: "command",
+          emits: EMPTY_EMITS,
+        },
+        onRun,
+        validation,
+      );
+    },
+    query<Name extends string>(name: Name) {
+      return new UseCaseBuilder<
+        Ctx,
+        Name,
+        "query",
+        undefined,
+        undefined,
+        readonly []
+      >(
+        {
+          name,
+          kind: "query",
+          emits: EMPTY_EMITS,
+        },
+        onRun,
+        validation,
+      );
+    },
+  };
+}