@beignet/core 0.0.1 → 0.0.3

package/src/testing/index.ts

@@ -0,0 +1,348 @@
+import { type ClockPort, createSystemClock } from "../ports/clock";
+import {
+  createUuidIdGenerator,
+  type IdGeneratorPort,
+} from "../ports/id-generator";
+
+/**
+ * Value that may be returned synchronously or asynchronously.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Arguments passed to a factory default builder.
+ */
+export interface FactoryBuildArgs<Name extends string = string> {
+  /**
+   * Factory name.
+   */
+  readonly name: Name;
+  /**
+   * Current sequence value.
+   */
+  readonly sequence: number;
+  /**
+   * ID generator available to the factory.
+   */
+  readonly ids: IdGeneratorPort;
+  /**
+   * Clock available to the factory.
+   */
+  readonly clock: ClockPort;
+}
+
+/**
+ * Arguments passed to a factory persistence function.
+ */
+export type FactoryPersistArgs<Name extends string = string> =
+  FactoryBuildArgs<Name>;
+
+/**
+ * Overrides accepted by factory build and create methods.
+ */
+export type FactoryOverrides<
+  Value extends object,
+  Name extends string = string,
+> =
+  | Partial<Value>
+  | ((value: Value, args: FactoryBuildArgs<Name>) => Partial<Value>);
+
+/**
+ * Options for declaring a test data factory.
+ */
+export interface DefineFactoryOptions<
+  Name extends string,
+  Value extends object,
+  Ctx = unknown,
+  Created = Value,
+> {
+  /**
+   * Build the default value for the current sequence.
+   */
+  defaults(args: FactoryBuildArgs<Name>): Value;
+  /**
+   * Persist a built value and return the created record.
+   */
+  persist?(
+    ctx: Ctx,
+    value: Value,
+    args: FactoryPersistArgs<Name>,
+  ): MaybePromise<Created>;
+  /**
+   * ID generator to expose to the factory.
+   */
+  ids?: IdGeneratorPort;
+  /**
+   * Clock to expose to the factory.
+   */
+  clock?: ClockPort;
+  /**
+   * Initial sequence number. Defaults to `1`.
+   */
+  start?: number;
+}
+
+/**
+ * Declared test data factory.
+ */
+export interface FactoryDef<
+  Name extends string = string,
+  Value extends object = object,
+  Ctx = unknown,
+  Created = Value,
+> {
+  /**
+   * Discriminator for factory definitions.
+   */
+  readonly kind: "factory";
+  /**
+   * Factory name.
+   */
+  readonly name: Name;
+  /**
+   * Build an in-memory value.
+   */
+  build(overrides?: FactoryOverrides<Value, Name>): Value;
+  /**
+   * Build multiple in-memory values.
+   */
+  buildList(count: number, overrides?: FactoryOverrides<Value, Name>): Value[];
+  /**
+   * Build and persist a value.
+   */
+  create(ctx: Ctx, overrides?: FactoryOverrides<Value, Name>): Promise<Created>;
+  /**
+   * Build and persist multiple values.
+   */
+  createList(
+    ctx: Ctx,
+    count: number,
+    overrides?: FactoryOverrides<Value, Name>,
+  ): Promise<Created[]>;
+  /**
+   * Reset the factory sequence.
+   */
+  resetSequence(next?: number): void;
+}
+
+/**
+ * Options for declaring a seed.
+ */
+export interface DefineSeedOptions<Ctx> {
+  /**
+   * Optional human-readable seed description.
+   */
+  description?: string;
+  /**
+   * Execute the seed.
+   */
+  run(ctx: Ctx): MaybePromise<void>;
+}
+
+/**
+ * Declared seed that can be run with `runSeeds(...)`.
+ */
+export interface SeedDef<Ctx = unknown, Name extends string = string> {
+  /**
+   * Discriminator for seed definitions.
+   */
+  readonly kind: "seed";
+  /**
+   * Seed name.
+   */
+  readonly name: Name;
+  /**
+   * Optional human-readable seed description.
+   */
+  readonly description?: string;
+  /**
+   * Execute the seed.
+   */
+  run(ctx: Ctx): MaybePromise<void>;
+}
+
+/**
+ * Options for running a list of seeds.
+ */
+export interface RunSeedsOptions<Ctx> {
+  /**
+   * Context passed to every seed.
+   */
+  ctx: Ctx;
+  /**
+   * Seeds to run in order.
+   */
+  seeds: readonly SeedDef<Ctx>[];
+}
+
+/**
+ * Error thrown when a seed fails.
+ */
+export class SeedRunError extends Error {
+  /**
+   * Seed that failed.
+   */
+  readonly seed: SeedDef;
+  /**
+   * Original thrown value.
+   */
+  readonly cause: unknown;
+
+  constructor(seed: SeedDef, cause: unknown) {
+    super(`Seed "${seed.name}" failed: ${errorMessage(cause)}`);
+    this.name = "SeedRunError";
+    this.seed = seed;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Reset one or more factory sequences to their configured starting values.
+ */
+export function resetFactories(
+  ...factories: readonly Pick<FactoryDef, "resetSequence">[]
+): void {
+  for (const factory of factories) {
+    factory.resetSequence();
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function factoryArgs<Name extends string>(args: {
+  name: Name;
+  sequence: number;
+  ids: IdGeneratorPort;
+  clock: ClockPort;
+}): FactoryBuildArgs<Name> {
+  return args;
+}
+
+function applyOverrides<Value extends object, Name extends string>(
+  value: Value,
+  args: FactoryBuildArgs<Name>,
+  overrides: FactoryOverrides<Value, Name> | undefined,
+): Value {
+  if (!overrides) return value;
+
+  const resolved =
+    typeof overrides === "function" ? overrides(value, args) : overrides;
+
+  return {
+    ...value,
+    ...resolved,
+  };
+}
+
+function assertCount(kind: "buildList" | "createList", count: number): void {
+  if (!Number.isInteger(count) || count < 0) {
+    throw new Error(`Factory ${kind} count must be a non-negative integer.`);
+  }
+}
+
+/**
+ * Define a typed test data factory with deterministic sequence support.
+ */
+export function defineFactory<
+  const Name extends string,
+  Value extends object,
+  Ctx = unknown,
+  Created = Value,
+>(
+  name: Name,
+  options: DefineFactoryOptions<Name, Value, Ctx, Created>,
+): FactoryDef<Name, Value, Ctx, Created> {
+  const start = options.start ?? 1;
+  const ids = options.ids ?? createUuidIdGenerator();
+  const clock = options.clock ?? createSystemClock();
+  let nextSequence = start;
+
+  function build(overrides?: FactoryOverrides<Value, Name>): Value {
+    const args = factoryArgs({
+      name,
+      sequence: nextSequence++,
+      ids,
+      clock,
+    });
+    const value = options.defaults(args);
+
+    return applyOverrides(value, args, overrides);
+  }
+
+  async function create(
+    ctx: Ctx,
+    overrides?: FactoryOverrides<Value, Name>,
+  ): Promise<Created> {
+    if (!options.persist) {
+      throw new Error(
+        `Factory "${name}" cannot create persisted records without a persist function.`,
+      );
+    }
+
+    const value = build(overrides);
+    const args = factoryArgs({
+      name,
+      sequence: nextSequence - 1,
+      ids,
+      clock,
+    });
+
+    return options.persist(ctx, value, args);
+  }
+
+  return {
+    kind: "factory",
+    name,
+    build,
+    buildList(count, overrides) {
+      assertCount("buildList", count);
+      return Array.from({ length: count }, () => build(overrides));
+    },
+    create,
+    async createList(ctx, count, overrides) {
+      assertCount("createList", count);
+      const created: Created[] = [];
+
+      for (let index = 0; index < count; index += 1) {
+        created.push(await create(ctx, overrides));
+      }
+
+      return created;
+    },
+    resetSequence(next = start) {
+      nextSequence = next;
+    },
+  };
+}
+
+/**
+ * Define a named seed.
+ */
+export function defineSeed<const Name extends string, Ctx = unknown>(
+  name: Name,
+  options: DefineSeedOptions<Ctx>,
+): SeedDef<Ctx, Name> {
+  return {
+    kind: "seed",
+    name,
+    description: options.description,
+    run: options.run,
+  };
+}
+
+/**
+ * Run seeds in order and wrap failures with the seed name.
+ */
+export async function runSeeds<Ctx>(
+  options: RunSeedsOptions<Ctx>,
+): Promise<void> {
+  for (const seed of options.seeds) {
+    try {
+      await seed.run(options.ctx);
+    } catch (error) {
+      throw new SeedRunError(seed, error);
+    }
+  }
+}