@beignet/core 0.0.1 → 0.0.2

package/src/server/server.ts

@@ -42,22 +42,47 @@ import {
 } from "./providers";
 
 /**
- * Route definition
+ * Route registration for one contract.
+ *
+ * Route definitions connect a contract to the handler that implements it. Most
+ * apps keep these in `features/<feature>/routes.ts` and compose them with
+ * `defineRoutes(...)`.
  */
 export type RouteDef<Ctx, CLike extends ContractLike = ContractLike> = {
+  /**
+   * Contract builder or plain contract config for this route.
+   */
   contract: CLike;
+  /**
+   * Handler that implements the contract.
+   */
   handle: Handler<Ctx, ResolveContract<CLike>>;
 };
 
 const ROUTE_GROUP_KIND = "beignet.route-group";
 
+/**
+ * Named collection of related route registrations.
+ *
+ * Route groups are an organization helper only. `defineRoutes(...)` flattens
+ * them before server registration.
+ */
 export type RouteGroup<
   Ctx,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
   Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
 > = {
+  /**
+   * Internal marker used by `defineRoutes(...)`.
+   */
   kind: typeof ROUTE_GROUP_KIND;
+  /**
+   * Human-readable group name.
+   */
   name: string;
+  /**
+   * Route definitions in this group.
+   */
   routes: Routes;
 };
 
@@ -97,6 +122,9 @@ type ContractsFromRouteList<
     : never;
 };
 
+/**
+ * Options for creating a Beignet server instance.
+ */
 export type CreateServerOptions<
   Ctx,
   Ports extends AnyPorts,
@@ -109,21 +137,53 @@ export type CreateServerOptions<
     AnyPorts
   >[] = readonly [],
 > = {
+  /**
+   * App-owned ports available to context creation, hooks, and handlers.
+   */
   ports: Ports;
+  /**
+   * Providers installed during server startup.
+   *
+   * Provider ports are merged into `ports` before request handling and are
+   * stopped in reverse setup order when `server.stop()` runs.
+   */
   providers?: Providers;
 
-  // config sources
+  /**
+   * Runtime env used by providers. Defaults to `process.env`.
+   */
   providerEnv?: Record<string, string | undefined>;
+  /**
+   * Provider config overrides keyed by provider name.
+   */
   providerConfig?: Record<string, unknown>;
 
+  /**
+   * Create request context after a route is matched.
+   *
+   * The `ports` argument includes app ports plus ports provided during server
+   * startup.
+   */
   createContext: (args: {
     req: HttpRequestLike;
     ports: Ports & ProvidedPortsOfList<Providers>;
     contract?: HttpContractConfig;
   }) => Ctx | Promise<Ctx>;
+  /**
+   * Server hooks that wrap every registered route.
+   */
   hooks?: ServerHook<Ctx, Ports & ProvidedPortsOfList<Providers>>[];
+  /**
+   * Route list to register up front.
+   */
   routes?: Routes;
+  /**
+   * Global caught-error observer.
+   */
   onCaughtError?: ServerCaughtErrorHook<Ctx>;
+  /**
+   * Global mapper for unexpected errors not handled by app error catalogs.
+   */
   mapUnhandledError?: ServerUnhandledErrorMapper<Ctx>;
 };
 
@@ -133,13 +193,31 @@ interface RouteBuilder<Ctx, C extends HttpContractConfig> {
   ) => (req: HttpRequestLike) => Promise<HttpResponse>;
 }
 
+/**
+ * Runtime server object returned by `createServer(...)`.
+ */
 export interface ServerInstance<Ctx, Ports extends AnyPorts = AnyPorts> {
+  /**
+   * Catch-all request handler for platform adapters.
+   */
   api: (req: HttpRequestLike) => Promise<HttpResponse>;
+  /**
+   * Register and build a single route handler imperatively.
+   */
   route: <CLike extends ContractLike>(
     contractLike: CLike,
   ) => RouteBuilder<Ctx, ResolveContract<CLike>>;
+  /**
+   * Contract configs registered through the `routes` option.
+   */
   contracts: readonly HttpContractConfig[];
+  /**
+   * Stop installed providers in reverse setup order.
+   */
   stop: () => Promise<void>;
+  /**
+   * Final app ports after provider setup.
+   */
   ports: Ports;
 }
 
@@ -1234,6 +1312,18 @@ function buildHandler<
   };
 }
 
+/**
+ * Create a Beignet server instance.
+ *
+ * The server owns route registration, provider setup/startup, request
+ * validation, hook execution, response validation, and framework error mapping.
+ * Use adapter packages such as `@beignet/next` to expose `server.api` to a
+ * specific runtime.
+ *
+ * @param options - Ports, providers, routes, hooks, context factory, and error
+ * mapping hooks for the server.
+ * @returns A started server instance with final ports and a catch-all handler.
+ */
 export async function createServer<
   Ctx,
   Ports extends AnyPorts,
@@ -1447,13 +1537,17 @@ export async function createServer<
 }
 
 /**
- * Helper function to define routes with proper type inference.
- * Eliminates the need for type assertions when passing routes to createServer.
+ * Define and flatten route registrations with strong type inference.
+ *
+ * Pass route definitions and route groups here before `createServer(...)`.
+ * Group entries are flattened so downstream tooling receives one route list.
  *
  * @example
+ * ```ts
  * const routes = defineRoutes<AppContext>([
- *   { contract: myContract, handle: async ({ query }) => { ... } }
+ *   { contract: listPosts, handle: async ({ ctx }) => ctx.posts.list() },
  * ]);
+ * ```
  */
 export function defineRoutes<
   Ctx,
@@ -1473,8 +1567,10 @@ export function defineRoutes<
 }
 
 /**
- * Extract contract configs from a route list. Use this to drive OpenAPI from
- * the same route registration list that createServer receives.
+ * Extract contract configs from a route list.
+ *
+ * Use this to drive clients, OpenAPI, and docs from the same route list passed
+ * to `createServer(...)`.
  */
 export function contractsFromRoutes<
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
@@ -1486,18 +1582,20 @@ export function contractsFromRoutes<
 }
 
 /**
- * Helper function to group related route registrations.
+ * Define a named group of related route registrations.
  *
  * Route groups are flattened by defineRoutes, so createServer still receives
  * a regular route list while app code can keep feature route wiring colocated.
  *
  * @example
+ * ```ts
  * const todoRoutes = defineRouteGroup<AppContext>({
  *   name: "todos",
  *   routes: [
- *     { contract: listTodos, handle: async ({ ctx }) => { ... } }
+ *     { contract: listTodos, handle: async ({ ctx }) => ctx.todos.list() },
  *   ]
  * });
+ * ```
  */
 export function defineRouteGroup<
   Ctx,

package/src/testing/index.ts

@@ -0,0 +1,337 @@
+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;
+  }
+}
+
+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);
+    }
+  }
+}