Registry

The Registry class is NOT part of the public Corpus API. It is the global container that holds every runtime dependency Corpus uses — the router, adapter, middleware router, entity store, parsers, XCors, and the global prefix. The registry is plug & play, so you can swap any of its fields with your own implementation as long as you satisfy the corresponding interface.

The registry instance can be accessed through $registry. Note that $registry itself cannot be reassigned — only its fields can be swapped.

Each Route, StaticRoute, WebSocketRoute, Controller, and Middleware object registers itself into the global registry at construction time. This means any field you intend to replace must be swapped before those objects are constructed, otherwise registrations will land on the old instance. Making all replacements at the top of your app would be a safe bet.

All interfaces can be imported by name, they are not namespaced to C or X.

Plug & Play

import { $registry } from "@ozanarslan/corpus";
// Just assign it directly.
$registry["what_you_need_to_replace"] = new MyReplacement();

Swappable Fields

Each of the following fields can be reassigned on $registry with a custom implementation that satisfies the listed interface. All interfaces and supporting types are exported by name from the package.

adapter

Implements RouterAdapterInterface. When the adapter is set, the default router is reset using the new adapter. See the Router docs for details.

middlewares

Implements MiddlewareRouterInterface. Responsible for storing middleware handlers keyed by route id and returning the inbound/outbound pipelines for a given match.

cors

Either null or an instance of XCorsInterface. Controls CORS handling and preflight responses.

urlParamsParser

Implements ObjectParserInterface<Record<string, string>>. Parses URL params from a matched route.

searchParamsParser

Implements ObjectParserInterface<URLSearchParams>. Parses query string search params.

formDataParser

Implements ObjectParserInterface<FormData>. Parses FormData request bodies.

bodyParser

Implements BodyParserInterface. Parses request bodies. The default implementation delegates to the form data and search params parsers, so if you replace those you usually do not need to replace this one.

schemaParser

Implements SchemaParserInterface. Parses and validates data against route schemas.

Non-Swappable Fields

docs

Readonly. Holds the documentation map used by the CLI tool.

entities

Readonly. Holds registered entities, used by the CLI tool.

router

Technically assignable but default instance depends on the adapter. Implements RouterInterface. See the Router docs.

prefix

Technically assignable, but the recommended way to set the global prefix is through Server.setGlobalPrefix.

const server = new C.Server();
server.setGlobalPrefix("/api");

Interfaces

All importable by name.

interface RouterAdapterInterface {
	readonly __brand: string;
	find(req: Req): RouterReturn | null;
	add(data: RouterData): void;
	list: Func<[], Array<RouterData>> | undefined;
}

interface RouterInterface {
	add(route: BaseRouteInterface<any, any, any, any>): void;
	find(req: Req): RouterReturn | null;
	list(): Array<RouterData>;
}

interface MiddlewareRouterInterface {
	add(middleware: MiddlewareInterface): void;
	find(routeId: string): MiddlewareStoreReturn;
}

interface XCorsInterface extends MiddlewareInterface {
	/** Preflight handler for OPTIONS requests. */
	getPreflightHandler(): RequestHandler;
}

interface ObjectParserInterface<T> {
	parse(input: T): UnknownObject;
}

type SchemaValidator<T = unknown> = StandardSchemaV1.Props<unknown, T>["validate"];

interface SchemaParserInterface {
	parse<T = UnknownObject>(label: string, data: unknown, validate?: SchemaValidator<T>): Promise<T>;
	parseSync<T = UnknownObject>(label: string, data: unknown, validate?: SchemaValidator<T>): T;
}