A whole project through the CLI

const naira = new Intl.NumberFormat("en-NG", { style: "currency", currency: "NGN" });
const formatKobo = (kobo) => naira.format(kobo / 100);

const dailyRateKobo = 50_000_000;
console.log(formatKobo(dailyRateKobo));
console.log(formatKobo(3 * dailyRateKobo));
console.log(Number.isSafeInteger(dailyRateKobo * 365));

₦500,000.00
₦1,500,000.00
true

const lagosDate = (instant) => instant.toLocaleDateString("en-CA", { timeZone: "Africa/Lagos" });

const lateEvening = new Date("2026-09-24T23:30:00Z");
console.log("UTC date:  ", lateEvening.toISOString().slice(0, 10));
console.log("Lagos date:", lagosDate(lateEvening));
console.log("24 Dec is not in the past:", "2026-12-24" >= lagosDate(lateEvening));

UTC date:   2026-09-24
Lagos date: 2026-09-25
24 Dec is not in the past: true

/**
 * booking-date validator.
 */

const PATTERN = /^\d{4}-\d{2}-\d{2}$/;

/** Whether `input` is a real calendar date written as YYYY-MM-DD. */
export function validateBookingDate(input: unknown): boolean {
  if (typeof input !== "string" || !PATTERN.test(input)) return false;
  const date = new Date(`${input}T00:00:00Z`);
  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === input;
}

import { validateBookingDate } from "./src/modules/scheduling/validators/booking-date.validator.js";

const stub = (_input: unknown): boolean => true;

for (const input of ["2026-12-24", "2026-02-30", "2028-02-29", "24/12/2026", "2026-12-24T10:00", 20261224]) {
  console.log(String(input).padEnd(17), "stub:", stub(input), " real:", validateBookingDate(input));
}

2026-12-24        stub: true  real: true
2026-02-30        stub: true  real: false
2028-02-29        stub: true  real: true
24/12/2026        stub: true  real: false
2026-12-24T10:00  stub: true  real: false
20261224          stub: true  real: false

import { schema, type Infer } from "@zudojs/schema";

/** A hall as the API returns it. Money is in kobo (₦1 = 100 kobo). */
export const HallSchema = schema.object({
  id: schema.string().uuid(),
  name: schema.string(),
  capacity: schema.number().int(),
  dailyRateKobo: schema.number().int(),
  createdAt: schema.string(),
  updatedAt: schema.string(),
});

/** Body of `POST /api/v1/halls`. Unknown fields are dropped. */
export const CreateHallSchema = schema.object({
  name: schema.string().trim().min(1).max(100),
  capacity: schema.number().int().min(1).max(5000),
  dailyRateKobo: schema.number().int().min(100).max(1_000_000_000),
});

/** Body of `PATCH /api/v1/halls/:id`. Every field is optional. */
export const UpdateHallSchema = CreateHallSchema.partial();

/** Path parameters of the `/api/v1/halls/:id` routes. */
export const HallParamsSchema = schema.object({
  id: schema.string().uuid(),
});

export type Hall = Infer<typeof HallSchema>;
export type CreateHallInput = Infer<typeof CreateHallSchema>;
export type UpdateHallInput = Infer<typeof UpdateHallSchema>;

import { schema, type Infer } from "@zudojs/schema";

import { validateBookingDate } from "../validators/booking-date.validator.js";

/** A booking as the API returns it. */
export const BookingSchema = schema.object({
  id: schema.string().uuid(),
  hallId: schema.string().uuid(),
  date: schema.string(),
  customerEmail: schema.string(),
  guests: schema.number().int(),
  amountKobo: schema.number().int(),
  createdAt: schema.string(),
  updatedAt: schema.string(),
});

/** Body of `POST /api/v1/bookings`. Unknown fields are dropped. */
export const CreateBookingSchema = schema.object({
  hallId: schema.string().uuid(),
  date: schema.string().regex(/^\d{4}-\d{2}-\d{2}$/).refine(validateBookingDate, "Expected a real date written as YYYY-MM-DD"),
  customerEmail: schema.string().trim().toLowerCase().email(),
  guests: schema.number().int().min(1),
});

/** Body of `PATCH /api/v1/bookings/:id`. Every field is optional. */
export const UpdateBookingSchema = schema.object({
  guests: schema.number().int().min(1).optional(),
});

/** Path parameters of the `/api/v1/bookings/:id` routes. */
export const BookingParamsSchema = schema.object({
  id: schema.string().uuid(),
});

export type Booking = Infer<typeof BookingSchema>;
export type CreateBookingInput = Infer<typeof CreateBookingSchema>;
export type UpdateBookingInput = Infer<typeof UpdateBookingSchema>;
/** What the repository stores: the input plus the price the service worked out. */
export type NewBooking = CreateBookingInput & { readonly amountKobo: number };

import { randomUUID } from "node:crypto";

import { ConflictError } from "@zudojs/errors";

import type { CreateHallInput, Hall, UpdateHallInput } from "../dtos/halls.dto.js";

/** Storage contract for hall records; the service depends on this only. */
export interface HallsRepository {
  findAll(): Promise<readonly Hall[]>;
  findById(id: string): Promise<Hall | undefined>;
  create(input: CreateHallInput): Promise<Hall>;
  update(id: string, input: UpdateHallInput): Promise<Hall | undefined>;
  delete(id: string): Promise<boolean>;
}

/** Most records the in-memory store keeps, so it cannot exhaust memory. */
const MAX_RECORDS = 10_000;

/**
 * Keeps hall records in process memory: for development and tests.
 * Data is lost on restart. Swap the implementation in container.ts.
 */
export class InMemoryHallsRepository implements HallsRepository {
  private readonly records = new Map<string, Hall>();

  public async findAll(): Promise<readonly Hall[]> {
    return [...this.records.values()];
  }

  public async findById(id: string): Promise<Hall | undefined> {
    return this.records.get(id);
  }

  public async create(input: CreateHallInput): Promise<Hall> {
    if (this.records.size >= MAX_RECORDS) {
      throw new ConflictError("The in-memory hall store is full.");
    }
    const now = new Date().toISOString();
    const record: Hall = {
      id: randomUUID(),
      name: input.name,
      capacity: input.capacity,
      dailyRateKobo: input.dailyRateKobo,
      createdAt: now,
      updatedAt: now,
    };
    this.records.set(record.id, record);
    return record;
  }

  public async update(
    id: string,
    input: UpdateHallInput,
  ): Promise<Hall | undefined> {
    const existing = this.records.get(id);
    if (existing === undefined) return undefined;
    const updated: Hall = {
      ...existing,
      name: input.name ?? existing.name,
      capacity: input.capacity ?? existing.capacity,
      dailyRateKobo: input.dailyRateKobo ?? existing.dailyRateKobo,
      updatedAt: new Date().toISOString(),
    };
    this.records.set(id, updated);
    return updated;
  }

  public async delete(id: string): Promise<boolean> {
    return this.records.delete(id);
  }
}

import { randomUUID } from "node:crypto";

import { ConflictError } from "@zudojs/errors";

import type { Booking, NewBooking, UpdateBookingInput } from "../dtos/bookings.dto.js";

/** Storage contract for booking records; the service depends on this only. */
export interface BookingsRepository {
  findAll(): Promise<readonly Booking[]>;
  findById(id: string): Promise<Booking | undefined>;
  findByHallAndDate(hallId: string, date: string): Promise<Booking | undefined>;
  /** Throws ConflictError when the hall is already booked on that date. */
  create(input: NewBooking): Promise<Booking>;
  update(id: string, input: UpdateBookingInput): Promise<Booking | undefined>;
  delete(id: string): Promise<boolean>;
}

/** Most records the in-memory store keeps, so it cannot exhaust memory. */
const MAX_RECORDS = 10_000;

/**
 * Keeps booking records in process memory: for development and tests.
 * Data is lost on restart. Swap the implementation in container.ts.
 */
export class InMemoryBookingsRepository implements BookingsRepository {
  private readonly records = new Map<string, Booking>();

  public async findAll(): Promise<readonly Booking[]> {
    return [...this.records.values()];
  }

  public async findById(id: string): Promise<Booking | undefined> {
    return this.records.get(id);
  }

  public async findByHallAndDate(hallId: string, date: string): Promise<Booking | undefined> {
    return this.taken(hallId, date);
  }

  public async create(input: NewBooking): Promise<Booking> {
    if (this.records.size >= MAX_RECORDS) {
      throw new ConflictError("The in-memory booking store is full.");
    }
    // Check and insert with no await in between, so two requests cannot both pass.
    if (this.taken(input.hallId, input.date) !== undefined) {
      throw new ConflictError(`The hall is already booked on ${input.date}.`);
    }
    const now = new Date().toISOString();
    const record: Booking = { id: randomUUID(), ...input, createdAt: now, updatedAt: now };
    this.records.set(record.id, record);
    return record;
  }

  public async update(id: string, input: UpdateBookingInput): Promise<Booking | undefined> {
    const existing = this.records.get(id);
    if (existing === undefined) return undefined;
    const updated: Booking = {
      ...existing,
      guests: input.guests ?? existing.guests,
      updatedAt: new Date().toISOString(),
    };
    this.records.set(id, updated);
    return updated;
  }

  public async delete(id: string): Promise<boolean> {
    return this.records.delete(id);
  }

  private taken(hallId: string, date: string): Booking | undefined {
    for (const record of this.records.values()) {
      if (record.hallId === hallId && record.date === date) return record;
    }
    return undefined;
  }
}

import { ConflictError } from "@zudojs/errors";

import type { Booking, NewBooking } from "./src/modules/scheduling/dtos/bookings.dto.js";
import { InMemoryBookingsRepository } from "./src/modules/scheduling/repositories/bookings.repository.js";

// The first draft: look up with await, then insert.
class AwaitThenInsertRepository {
  private readonly records: Booking[] = [];

  async findByHallAndDate(hallId: string, date: string): Promise<Booking | undefined> {
    return this.records.find((record) => record.hallId === hallId && record.date === date);
  }

  async create(input: NewBooking): Promise<Booking> {
    if ((await this.findByHallAndDate(input.hallId, input.date)) !== undefined) {
      throw new ConflictError(`The hall is already booked on ${input.date}.`);
    }
    const record: Booking = { id: crypto.randomUUID(), ...input, createdAt: "", updatedAt: "" };
    this.records.push(record);
    return record;
  }
}

const ada: NewBooking = {
  hallId: "0b6f3c1e-8d4a-4f7e-9a2b-5c6d7e8f9a0b",
  date: "2026-12-24",
  customerEmail: "ada@example.com",
  guests: 150,
  amountKobo: 50_000_000,
};
const tunde: NewBooking = { ...ada, customerEmail: "tunde@example.com", guests: 80 };

for (const repository of [new AwaitThenInsertRepository(), new InMemoryBookingsRepository()]) {
  const results = await Promise.allSettled([repository.create(ada), repository.create(tunde)]);
  console.log(repository.constructor.name.padEnd(27), results.map((result) => result.status).join(", "));
}

AwaitThenInsertRepository   fulfilled, fulfilled
InMemoryBookingsRepository  fulfilled, rejected

import { NotFoundError, ValidationError } from "@zudojs/errors";

import type { Hall } from "../dtos/halls.dto.js";
import type { BookingsRepository } from "../repositories/bookings.repository.js";
import type { HallsRepository } from "../repositories/halls.repository.js";

/** Today's date in Lagos as YYYY-MM-DD. */
export const lagosToday = (): string => new Date().toLocaleDateString("en-CA", { timeZone: "Africa/Lagos" });

/** Whether a hall is free on a date, and what it costs. */
export interface Quote {
  readonly hallId: string;
  readonly date: string;
  readonly available: boolean;
  readonly capacity: number;
  readonly amountKobo: number;
}

/** Answers "can this hall be booked on this date?" for the bookings module. */
export class AvailabilityService {
  public constructor(
    private readonly halls: HallsRepository,
    private readonly bookings: BookingsRepository,
    private readonly today: () => string = lagosToday,
  ) {}

  public async hall(hallId: string): Promise<Hall> {
    const hall = await this.halls.findById(hallId);
    if (hall === undefined) throw new NotFoundError(`Hall "${hallId}" was not found.`);
    return hall;
  }

  public async quote(hallId: string, date: string): Promise<Quote> {
    const hall = await this.hall(hallId);
    if (date < this.today()) throw new ValidationError(`${date} is in the past.`);
    const booking = await this.bookings.findByHallAndDate(hallId, date);
    return { hallId, date, available: booking === undefined, capacity: hall.capacity, amountKobo: hall.dailyRateKobo };
  }
}

import { NotFoundError, ValidationError } from "@zudojs/errors";

import type { CreateBookingInput, Booking, UpdateBookingInput } from "../dtos/bookings.dto.js";
import type { BookingsRepository } from "../repositories/bookings.repository.js";
import type { AvailabilityService } from "./availability.service.js";

/** Booking use cases. Throws NotFoundError (404), ValidationError (400), ConflictError (409). */
export class BookingsService {
  public constructor(
    private readonly repository: BookingsRepository,
    private readonly availability: AvailabilityService,
  ) {}

  public list(): Promise<readonly Booking[]> {
    return this.repository.findAll();
  }

  public async get(id: string): Promise<Booking> {
    const record = await this.repository.findById(id);
    if (record === undefined) throw notFound(id);
    return record;
  }

  public async create(input: CreateBookingInput): Promise<Booking> {
    const quote = await this.availability.quote(input.hallId, input.date);
    checkGuests(input.guests, quote.capacity);
    return this.repository.create({ ...input, amountKobo: quote.amountKobo });
  }

  public async update(id: string, input: UpdateBookingInput): Promise<Booking> {
    const existing = await this.get(id);
    if (input.guests !== undefined) {
      checkGuests(input.guests, (await this.availability.hall(existing.hallId)).capacity);
    }
    const record = await this.repository.update(id, input);
    if (record === undefined) throw notFound(id);
    return record;
  }

  public async remove(id: string): Promise<void> {
    if (!(await this.repository.delete(id))) throw notFound(id);
  }
}

function checkGuests(guests: number, capacity: number): void {
  if (guests > capacity) throw new ValidationError(`The hall holds ${capacity} guests, not ${guests}.`);
}

function notFound(id: string): NotFoundError {
  return new NotFoundError(`Booking "${id}" was not found.`);
}

import { InMemoryBookingsRepository } from "./src/modules/scheduling/repositories/bookings.repository.js";
import { InMemoryHallsRepository } from "./src/modules/scheduling/repositories/halls.repository.js";
import { AvailabilityService } from "./src/modules/scheduling/services/availability.service.js";
import { BookingsService } from "./src/modules/scheduling/services/bookings.service.js";
import type { CreateBookingInput } from "./src/modules/scheduling/dtos/bookings.dto.js";

const halls = new InMemoryHallsRepository();
const bookings = new InMemoryBookingsRepository();
const availability = new AvailabilityService(halls, bookings, () => "2026-10-01");
const service = new BookingsService(bookings, availability);
const eko = await halls.create({ name: "Eko Hall", capacity: 200, dailyRateKobo: 50_000_000 });

async function attempt(label: string, input: CreateBookingInput): Promise<void> {
  try {
    const booking = await service.create(input);
    console.log(`${label.padEnd(9)} 201 booked for ${booking.amountKobo} kobo`);
  } catch (error) {
    const { statusCode, name, message } = error as Error & { statusCode: number };
    console.log(`${label.padEnd(9)} ${statusCode} ${name}: ${message}`);
  }
}

const ada = { hallId: eko.id, date: "2026-12-24", customerEmail: "ada@example.com", guests: 150 };
await attempt("ada", ada);
await attempt("tunde", { ...ada, customerEmail: "tunde@example.com", guests: 80 });
await attempt("too many", { ...ada, date: "2026-12-26", guests: 350 });
await attempt("past", { ...ada, date: "2026-09-30" });
await attempt("no hall", { ...ada, hallId: "7a1c7a0e-5d7e-4f5b-9c1d-2b3e4f5a6b7c" });

const quote = await availability.quote(eko.id, "2026-12-24");
console.log("24 Dec available:", quote.available, "| 25 Dec available:", (await availability.quote(eko.id, "2026-12-25")).available);

ada       201 booked for 50000000 kobo
tunde     409 ConflictError: The hall is already booked on 2026-12-24.
too many  400 ValidationError: The hall holds 200 guests, not 350.
past      400 ValidationError: 2026-09-30 is in the past.
no hall   404 NotFoundError: Hall "7a1c7a0e-5d7e-4f5b-9c1d-2b3e4f5a6b7c" was not found.
24 Dec available: false | 25 Dec available: true

export function createDependencies(options: DependencyOptions = {}) {
  const health: HealthCheck =
    options.health ?? (async () => ({ ready: true, checks: {} }));

  // Shared by two services, so built once, outside the markers.
  const hallsRepository = new InMemoryHallsRepository();
  const bookingsRepository = new InMemoryBookingsRepository();
  const availability = new AvailabilityService(hallsRepository, bookingsRepository);

  return {
    health,
    availability,
    hallsController: new HallsController(new HallsService(hallsRepository)),
    bookingsController: new BookingsController(new BookingsService(bookingsRepository, availability)),
    // zudojs:container:start
    // zudojs:container:end
  };
}

import {
  badRequest,
  createResponseContext,
  type HttpMiddleware,
  type HttpResponseContext,
  type HttpRouterContext,
} from "@zudojs/http";
import type { SchemaIssue } from "@zudojs/schema";
import { generateSecurityHeaders } from "@zudojs/security";

/** A JSON response with `status`. */
export function json(status: number, data: unknown): HttpResponseContext {
  return createResponseContext({ status }).json(data);
}

/** A response with no body (for example 204). */
export function empty(status: number): HttpResponseContext {
  return createResponseContext({ status });
}

/** 400 listing where the input failed validation, without echoing it back. */
export function validationFailed(issues: readonly SchemaIssue[]): HttpResponseContext {
  return json(400, {
    error: "Validation failed",
    issues: issues.map((issue) => ({
      path: issue.path.map(String).join("."),
      message: issue.message,
    })),
  });
}

/**
 * The request body parsed as JSON; `undefined` when there is none.
 * Malformed JSON is answered with 400.
 */
export function readJsonBody(ctx: HttpRouterContext): unknown {
  const body: unknown = ctx.request.body;
  if (body === undefined || body === null) return undefined;
  const text =
    body instanceof Uint8Array
      ? new TextDecoder().decode(body)
      : typeof body === "string"
        ? body
        : undefined;
  if (text === undefined) return body;
  if (text.trim() === "") return undefined;
  try {
    return JSON.parse(text) as unknown;
  } catch {
    throw badRequest("The request body is not valid JSON.");
  }
}

/**
 * The response for an error that carries an exposed 4xx status
 * (NotFoundError, badRequest(), ...). Anything else is left to the server,
 * which answers a generic 500 and never leaks the message.
 */
export function errorResponse(error: unknown): HttpResponseContext | undefined {
  if (typeof error !== "object" || error === null) return undefined;
  const candidate = error as {
    readonly statusCode?: unknown;
    readonly expose?: unknown;
    readonly message?: unknown;
    readonly code?: unknown;
  };
  const status = candidate.statusCode;
  if (typeof status !== "number" || status < 400 || status > 499) return undefined;
  if (candidate.expose !== true || typeof candidate.message !== "string") return undefined;
  return json(status, {
    error: candidate.message,
    ...(typeof candidate.code === "string" ? { code: candidate.code } : {}),
  });
}

/**
 * Adds the @zudojs/security default headers (CSP, HSTS, nosniff,
 * X-Frame-Options DENY, ...) to every response that does not set its own:
 * the /docs page, for instance, sends a CSP that allows its assets.
 */
export function securityHeaders(): HttpMiddleware {
  const defaults = Object.entries(generateSecurityHeaders());
  return async (_context, next) => {
    const response = (await next()).clone();
    const present = new Set(Object.keys(response.headers).map((name) => name.toLowerCase()));
    for (const [name, value] of defaults) {
      if (!present.has(name.toLowerCase())) response.setHeader(name, value);
    }
    return response;
  };
}

import type { HttpRouter } from "@zudojs/http";
import { schema } from "@zudojs/schema";

import { json, validationFailed } from "../../../utils/http.js";
import { HallParamsSchema } from "../dtos/halls.dto.js";
import type { AvailabilityService } from "../services/availability.service.js";
import { validateBookingDate } from "../validators/booking-date.validator.js";

const AvailabilityQuerySchema = schema.object({
  date: schema.string().regex(/^\d{4}-\d{2}-\d{2}$/).refine(validateBookingDate, "Expected a real date written as YYYY-MM-DD"),
});

/** GET /api/v1/halls/:id/availability?date=YYYY-MM-DD, written by hand. */
export function registerAvailabilityRoutes(router: HttpRouter, availability: AvailabilityService): void {
  router.get(
    "/api/v1/halls/:id/availability",
    async (ctx) => {
      const params = HallParamsSchema.safeParse(ctx.params);
      if (!params.success) return validationFailed(params.issues);
      const query = AvailabilityQuerySchema.safeParse(ctx.query);
      if (!query.success) return validationFailed(query.issues);
      return json(200, await availability.quote(params.data.id, query.data.date));
    },
    {
      openapi: {
        summary: "Check whether a hall is free on a date",
        tags: ["halls"],
        params: HallParamsSchema,
        query: AvailabilityQuerySchema,
        responses: { "200": { description: "Availability and price" }, "400": { description: "Bad id or date" }, "404": { description: "No such hall" } },
      },
    },
  );
}

import type { HttpRouter } from "@zudojs/http";

import type { AppDependencies } from "../../../container.js";
import { registerAvailabilityRoutes } from "./availability.routes.js";
// zudojs:route-imports:start
import { registerHallsRoutes } from "./halls.routes.js";
import { registerBookingsRoutes } from "./bookings.routes.js";
// zudojs:route-imports:end

/** Registers this module's routes; called from the app's routes/index.ts. */
export function registerSchedulingModuleRoutes(router: HttpRouter, deps: AppDependencies): void {
  registerAvailabilityRoutes(router, deps.availability);
  // zudojs:routes:start
  registerHallsRoutes(router, deps.hallsController);
  registerBookingsRoutes(router, deps.bookingsController);
  // zudojs:routes:end
}

{
  "extends": "./tsconfig.json",
  "compilerOptions": { "rootDir": ".", "noEmit": true },
  "include": ["src/**/*", "tests/**/*"],
  "exclude": ["node_modules", "dist"]
}

import { createRouter, mountOpenAPI } from "@zudojs/http";
import { createHttpTestClient } from "@zudojs/testing";

import { InMemoryBookingsRepository } from "./src/modules/scheduling/repositories/bookings.repository.js";
import { InMemoryHallsRepository } from "./src/modules/scheduling/repositories/halls.repository.js";
import { registerAvailabilityRoutes } from "./src/modules/scheduling/routes/availability.routes.js";
import { AvailabilityService } from "./src/modules/scheduling/services/availability.service.js";

const halls = new InMemoryHallsRepository();
const availability = new AvailabilityService(halls, new InMemoryBookingsRepository(), () => "2026-10-01");
const eko = await halls.create({ name: "Eko Hall", capacity: 200, dailyRateKobo: 50_000_000 });

const router = createRouter();
registerAvailabilityRoutes(router, availability);
mountOpenAPI(router, { info: { title: "bookings-api", version: "0.1.0" } });
const client = createHttpTestClient(router);

type Operation = { parameters: Array<{ in: string; name: string; schema: unknown }> };
const doc = (await client.get("/openapi.json")).json<{ paths: Record<string, { get: Operation }> }>();
for (const parameter of doc.paths["/api/v1/halls/{id}/availability"]!.get.parameters) {
  console.log(parameter.in.padEnd(5), parameter.name.padEnd(4), JSON.stringify(parameter.schema));
}
console.log((await client.get(`/api/v1/halls/${eko.id}/availability?date=2026-12-24`)).text);
const bad = await client.get(`/api/v1/halls/${eko.id}/availability?date=24-12-2026`);
console.log(bad.status, bad.text);
await client.close();

path  id   {"type":"string","format":"uuid","maxLength":255}
query date {"type":"string","maxLength":255,"pattern":"^\\d{4}-\\d{2}-\\d{2}$"}
{"hallId":"3e2f2228-f73a-4c1d-8e79-6b575d16b24a","date":"2026-12-24","available":true,"capacity":200,"amountKobo":50000000}
400 {"error":"Validation failed","issues":[{"path":"date","message":"String does not match pattern"}]}

import type { HttpMiddleware, HttpRouter } from "@zudojs/http";
import type { Logger } from "@zudojs/logger";

import { errorResponse } from "./http.js";

/**
 * The last middleware: runs the router and turns exposed 4xx errors into
 * responses. Anything else is logged, then rethrown so the server answers a
 * generic 500 that reveals nothing to the client.
 */
export function createDispatch(router: HttpRouter, logger: Logger): HttpMiddleware {
  return async (context) => {
    try {
      return (await router.dispatch(context.request, { signal: context.signal })).response;
    } catch (error) {
      const response = errorResponse(error);
      if (response !== undefined) return response;
      logger.error("Unhandled error while serving a request", {
        method: context.request.method,
        path: context.request.path,
        error: error instanceof Error ? error.message : String(error),
      });
      throw error;
    }
  };
}

import { NotFoundError } from "@zudojs/errors";
import { HttpMiddlewarePipeline, createRouter } from "@zudojs/http";
import { createLogger } from "@zudojs/logger";
import { createHttpTestClient } from "@zudojs/testing";

import { createDispatch } from "./src/utils/dispatch.js";

const router = createRouter();
router.get("/api/v1/bookings", async () => {
  throw new Error("connection refused: 10.0.0.5:5432");
});
router.get("/api/v1/halls/:id", async () => {
  throw new NotFoundError("No such hall.");
});

const dispatch = createDispatch(router, createLogger({ name: "bookings-api" }));
const client = createHttpTestClient(new HttpMiddlewarePipeline({ middlewares: [dispatch] }));
for (const path of ["/api/v1/halls/abc", "/api/v1/bookings"]) {
  const response = await client.get(path);
  console.log(response.status, response.text);
}
await client.close();

404 {"error":"No such hall.","code":"ERR_RESOURCE_NOT_FOUND"}
2026-09-25T00:02:54.438Z [ERROR] [bookings-api] Unhandled error while serving a request method=GET path=/api/v1/bookings error="connection refused: 10.0.0.5:5432"
500 {"error":"Internal Server Error"}

import { resolveEnvironment } from "@zudojs/constants";

// What loadConfig({ NODE_ENV: "production" }) stores:
const config = { nodeEnv: "production" };

console.log("generated app.ts:", resolveEnvironment());
console.log("fixed app.ts:    ", resolveEnvironment({ NODE_ENV: config.nodeEnv }));
console.log("short form:      ", resolveEnvironment({ NODE_ENV: "prod" }));
try {
  resolveEnvironment({ NODE_ENV: "prodution" }, { strict: true });
} catch (error) {
  console.log("typo, strict:    ", (error as Error).name);
}

generated app.ts: development
fixed app.ts:     production
short form:       production
typo, strict:     InvalidConstantError

import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { createRouter } from "@zudojs/http";
import { createHttpTestClient } from "@zudojs/testing";

import { BookingsController } from "../src/modules/scheduling/controllers/bookings.controller.js";
import { InMemoryBookingsRepository } from "../src/modules/scheduling/repositories/bookings.repository.js";
import { InMemoryHallsRepository } from "../src/modules/scheduling/repositories/halls.repository.js";
import { registerBookingsRoutes } from "../src/modules/scheduling/routes/bookings.routes.js";
import { AvailabilityService } from "../src/modules/scheduling/services/availability.service.js";
import { BookingsService } from "../src/modules/scheduling/services/bookings.service.js";

const halls = new InMemoryHallsRepository();
const bookings = new InMemoryBookingsRepository();
// A fixed "today", so the test gives the same answer on every day of the year.
const availability = new AvailabilityService(halls, bookings, () => "2026-10-01");
const router = createRouter();
registerBookingsRoutes(router, new BookingsController(new BookingsService(bookings, availability)));
const client = createHttpTestClient(router);
afterAll(() => client.close());

let hallId = "";
beforeAll(async () => {
  hallId = (await halls.create({ name: "Eko Hall", capacity: 200, dailyRateKobo: 50_000_000 })).id;
});

const booking = (overrides: Record<string, unknown> = {}) => ({
  hallId,
  date: "2026-12-24",
  customerEmail: " Ada@Example.com ",
  guests: 150,
  ...overrides,
});

describe("/api/v1/bookings", () => {
  it("books a free hall at the hall's price", async () => {
    await client
      .post("/api/v1/bookings")
      .send(booking())
      .expect(201)
      .expectJson({ customerEmail: "ada@example.com", amountKobo: 50_000_000 });
  });

  it("refuses a second booking of the same hall and date", async () => {
    await client.post("/api/v1/bookings").send(booking()).expect(409);
  });

  it("lets only one of two simultaneous bookings win", async () => {
    const service = new BookingsService(bookings, availability);
    const input = { hallId, date: "2026-12-31", customerEmail: "ada@example.com", guests: 10 };
    const both = await Promise.allSettled([service.create(input), service.create(input)]);
    expect(both.map((result) => result.status).sort()).toEqual(["fulfilled", "rejected"]);
  });

  it("refuses bad input with 400 and an unknown hall with 404", async () => {
    await client.post("/api/v1/bookings").send(booking({ guests: 201, date: "2027-01-02" })).expect(400);
    await client.post("/api/v1/bookings").send(booking({ date: "2026-02-30" })).expect(400);
    await client.post("/api/v1/bookings").send(booking({ date: "2026-09-30" })).expect(400);
    await client.post("/api/v1/bookings").send(booking({ hallId: crypto.randomUUID() })).expect(404);
  });
});

import { afterAll, describe, it } from "vitest";
import { createRouter } from "@zudojs/http";
import { createHttpTestClient } from "@zudojs/testing";

import { createDependencies } from "../src/container.js";
import { registerRoutes } from "../src/routes/index.js";

// The router exactly as server.ts builds it: this catches lost wiring.
const router = createRouter();
registerRoutes(router, createDependencies());
const client = createHttpTestClient(router);
afterAll(() => client.close());

describe("wiring", () => {
  it("serves every route the app should have", async () => {
    await client.get("/health").expect(200);
    await client.get("/api/v1/bookings").expect(200);
    await client.get("/api/v1/enquiries").expect(200);
    const hall = await client
      .post("/api/v1/halls")
      .send({ name: "Smoke Hall", capacity: 10, dailyRateKobo: 1_000_000 })
      .expect(201);
    const { id } = hall.json<{ id: string }>();
    await client.get(`/api/v1/halls/${id}/availability?date=2099-01-01`).expect(200);
  });
});

import { afterAll, describe, expect, it } from "vitest";
import { HttpMiddlewarePipeline, createRouter } from "@zudojs/http";
import { createHttpTestClient, createSpyLogger } from "@zudojs/testing";
import { NotFoundError } from "@zudojs/errors";

import { createDispatch } from "../src/utils/dispatch.js";

const logger = createSpyLogger("bookings-api");
const router = createRouter();
router.get("/broken", async () => {
  throw new Error("connection refused: 10.0.0.5:5432");
});
router.get("/missing", async () => {
  throw new NotFoundError("No such booking.");
});
const client = createHttpTestClient(new HttpMiddlewarePipeline({ middlewares: [createDispatch(router, logger)] }));
afterAll(() => client.close());

describe("dispatch", () => {
  it("answers 500 without details, and logs the real error", async () => {
    const response = await client.get("/broken").expect(500);
    expect(response.text).not.toContain("10.0.0.5");
    expect(logger.findByMethod("error")).toHaveLength(1);
    expect(logger.calls[0]?.metadata).toMatchObject({ path: "/broken", error: "connection refused: 10.0.0.5:5432" });
  });

  it("does not log expected 4xx answers", async () => {
    logger.clear();
    await client.get("/missing").expect(404);
    expect(logger.calls).toHaveLength(0);
  });
});

# syntax=docker/dockerfile:1
FROM node:24-alpine AS build
WORKDIR /app
# The lockfile is optional (copied with a wildcard): with it the install is
# frozen and the image reproducible; with no lockfile yet (nothing has been
# installed) dependencies resolve from package.json. Commit the lockfile.
COPY package.json package-lock.json* ./
RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
RUN npm prune --omit=dev --ignore-scripts

FROM node:24-alpine AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build --chown=node:node /app/package.json ./
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=15s CMD ["node", "-e", "fetch('http://127.0.0.1:3000/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
CMD ["node", "dist/server.js"]