@vertz/core 0.0.2 → 0.2.0

package/dist/index.d.ts

@@ -18,6 +18,23 @@ interface NamedMiddlewareDef<
 > extends MiddlewareDef<TRequires, TProvides> {
 	name: string;
 }
+/**
+* Identity type for middleware type accumulation.
+* Uses `{}` intentionally as it is the identity element for intersection types.
+*/
+type EmptyProvides = {};
+/**
+* Extracts TProvides from a NamedMiddlewareDef by inspecting the handler return type.
+* Uses the handler signature to extract the provides type without variance issues.
+*/
+type ExtractProvides<T> = T extends {
+	handler: (...args: never[]) => Promise<infer P> | infer P;
+} ? P extends Record<string, unknown> ? P : EmptyProvides : EmptyProvides;
+/**
+* Recursively accumulates the TProvides types from a tuple of middleware definitions
+* into an intersection type. Given [M1<P1>, M2<P2>, M3<P3>], produces P1 & P2 & P3.
+*/
+type AccumulateProvides<T extends readonly NamedMiddlewareDef<any, any>[]> = T extends readonly [infer First, ...infer Rest extends readonly NamedMiddlewareDef<any, any>[]] ? ExtractProvides<First> & AccumulateProvides<Rest> : EmptyProvides;
 declare function createMiddleware<
 	TRequires extends Record<string, unknown> = Record<string, unknown>,
 	TProvides extends Record<string, unknown> = Record<string, unknown>
@@ -34,16 +51,20 @@ interface ModuleDef<
 interface ServiceDef<
 	TDeps = unknown,
 	TState = unknown,
-	TMethods = unknown
+	TMethods = unknown,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TEnv extends Record<string, unknown> = Record<string, unknown>
 > {
 	inject?: Record<string, unknown>;
-	onInit?: (deps: TDeps) => Promise<TState> | TState;
-	methods: (deps: TDeps, state: TState) => TMethods;
+	options?: Schema2<TOptions>;
+	env?: Schema2<TEnv>;
+	onInit?: (deps: TDeps, opts: TOptions, env: TEnv) => Promise<TState> | TState;
+	methods: (deps: TDeps, state: TState, opts: TOptions, env: TEnv) => TMethods;
 	onDestroy?: (deps: TDeps, state: TState) => Promise<void> | void;
 }
-interface RouterDef {
+interface RouterDef<TInject extends Record<string, unknown> = Record<string, unknown>> {
 	prefix: string;
-	inject?: Record<string, unknown>;
+	inject?: TInject;
 }
 interface Module<TDef extends ModuleDef = ModuleDef> {
 	definition: TDef;
@@ -63,7 +84,7 @@ interface RawRequest {
 interface HandlerCtx {
 	params: Record<string, unknown>;
 	body: unknown;
-	query: Record<string, unknown>;
+	query: Record<string, string>;
 	headers: Record<string, unknown>;
 	raw: RawRequest;
 	options: Record<string, unknown>;
@@ -72,88 +93,116 @@ interface HandlerCtx {
 }
 type Deps<T extends Record<string, unknown>> = DeepReadonly<T>;
 type Ctx<T extends Record<string, unknown>> = DeepReadonly<T>;
-type InferOutput<T> = T extends {
+interface NamedServiceDef<
+	TDeps = unknown,
+	TState = unknown,
+	TMethods = unknown,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TEnv extends Record<string, unknown> = Record<string, unknown>
+> extends ServiceDef<TDeps, TState, TMethods, TOptions, TEnv> {
+	moduleName: string;
+}
+type InferOutput<
+	T,
+	TDefault = unknown
+> = T extends {
 	_output: infer O;
 } ? O : T extends {
 	parse(v: unknown): infer P;
-} ? P : unknown;
+} ? P : TDefault;
 type TypedHandlerCtx<
 	TParams = unknown,
 	TQuery = unknown,
 	THeaders = unknown,
-	TBody = unknown
+	TBody = unknown,
+	TMiddleware extends Record<string, unknown> = Record<string, unknown>
 > = Omit<HandlerCtx, "params" | "query" | "headers" | "body"> & {
 	params: TParams;
 	query: TQuery;
 	headers: THeaders;
 	body: TBody;
-};
+} & TMiddleware;
 interface RouteConfig<
 	TParams = unknown,
 	TQuery = unknown,
 	THeaders = unknown,
-	TBody = unknown
+	TBody = unknown,
+	TMiddleware extends Record<string, unknown> = Record<string, unknown>
 > {
 	params?: TParams;
 	body?: TBody;
 	query?: TQuery;
 	response?: unknown;
+	/** Error schemas for errors-as-values pattern. Keys are HTTP status codes. */
+	errors?: Record<number, unknown>;
 	headers?: THeaders;
 	middlewares?: unknown[];
-	handler: (ctx: TypedHandlerCtx<InferOutput<TParams>, InferOutput<TQuery>, InferOutput<THeaders>, InferOutput<TBody>>) => unknown;
+	handler: (ctx: TypedHandlerCtx<InferOutput<TParams>, InferOutput<TQuery, Record<string, string>>, InferOutput<THeaders>, InferOutput<TBody>, TMiddleware>) => unknown;
 }
 interface Route {
 	method: string;
 	path: string;
-	config: RouteConfig<unknown, unknown, unknown, unknown>;
-}
-type HttpMethodFn = <
+	config: RouteConfig<unknown, unknown, unknown, unknown, Record<string, unknown>>;
+}
+/**
+* Extracts the TMethods type from a NamedServiceDef or ServiceDef.
+* Returns `unknown` for non-service types.
+*/
+type ExtractMethods<T> = T extends NamedServiceDef<any, any, infer M> ? M : T extends ServiceDef<any, any, infer M> ? M : unknown;
+/**
+* Resolves an inject map by extracting TMethods from each NamedServiceDef value.
+* Given `{ userService: NamedServiceDef<..., ..., UserMethods> }`,
+* produces `{ userService: UserMethods }`.
+*/
+type ResolveInjectMap<T extends Record<string, unknown>> = { [K in keyof T] : ExtractMethods<T[K]> };
+type HttpMethodFn<
+	TMiddleware extends Record<string, unknown> = Record<string, unknown>,
+	TInject extends Record<string, unknown> = Record<string, unknown>
+> = <
 	TParams,
 	TQuery,
 	THeaders,
 	TBody
->(path: `/${string}`, config: RouteConfig<TParams, TQuery, THeaders, TBody>) => NamedRouterDef;
-interface NamedRouterDef extends RouterDef {
+>(path: `/${string}`, config: RouteConfig<TParams, TQuery, THeaders, TBody, TMiddleware & ResolveInjectMap<TInject>>) => NamedRouterDef<TMiddleware, TInject>;
+interface NamedRouterDef<
+	TMiddleware extends Record<string, unknown> = Record<string, unknown>,
+	TInject extends Record<string, unknown> = Record<string, unknown>
+> extends RouterDef<TInject> {
 	moduleName: string;
 	routes: Route[];
-	get: HttpMethodFn;
-	post: HttpMethodFn;
-	put: HttpMethodFn;
-	patch: HttpMethodFn;
-	delete: HttpMethodFn;
-	head: HttpMethodFn;
-}
-interface NamedServiceDef<
-	TDeps = unknown,
-	TState = unknown,
-	TMethods = unknown
-> extends ServiceDef<TDeps, TState, TMethods> {
-	moduleName: string;
+	get: HttpMethodFn<TMiddleware, TInject>;
+	post: HttpMethodFn<TMiddleware, TInject>;
+	put: HttpMethodFn<TMiddleware, TInject>;
+	patch: HttpMethodFn<TMiddleware, TInject>;
+	delete: HttpMethodFn<TMiddleware, TInject>;
+	head: HttpMethodFn<TMiddleware, TInject>;
 }
 interface NamedModuleDef<
 	TImports extends Record<string, unknown> = Record<string, unknown>,
-	TOptions extends Record<string, unknown> = Record<string, unknown>
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TMiddleware extends Record<string, unknown> = Record<string, unknown>
 > extends ModuleDef<TImports, TOptions> {
 	service: <
 		TDeps,
 		TState,
 		TMethods
 	>(config: ServiceDef<TDeps, TState, TMethods>) => NamedServiceDef<TDeps, TState, TMethods>;
-	router: (config: RouterDef) => NamedRouterDef;
+	router: <TInject extends Record<string, unknown> = Record<string, unknown>>(config: RouterDef<TInject>) => NamedRouterDef<TMiddleware, TInject>;
 }
 declare function createModuleDef<
 	TImports extends Record<string, unknown> = Record<string, unknown>,
-	TOptions extends Record<string, unknown> = Record<string, unknown>
->(config: ModuleDef<TImports, TOptions>): NamedModuleDef<TImports, TOptions>;
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TMiddleware extends Record<string, unknown> = Record<string, unknown>
+>(config: ModuleDef<TImports, TOptions>): NamedModuleDef<TImports, TOptions, TMiddleware>;
 interface NamedModule {
 	definition: NamedModuleDef;
 	services: NamedServiceDef[];
-	routers: NamedRouterDef[];
+	routers: NamedRouterDef<any, any>[];
 	exports: NamedServiceDef[];
 }
 declare function createModule(definition: NamedModuleDef, config: {
 	services: NamedServiceDef[];
-	routers: NamedRouterDef[];
+	routers: NamedRouterDef<any, any>[];
 	exports: NamedServiceDef[];
 }): NamedModule;
 interface CorsConfig {
@@ -164,13 +213,29 @@ interface CorsConfig {
 	maxAge?: number;
 	exposedHeaders?: string[];
 }
+interface DomainDefinition {
+	readonly name: string;
+	readonly type: string;
+	readonly table: unknown;
+	readonly exposedRelations: Record<string, unknown>;
+	readonly access: Record<string, unknown>;
+	readonly handlers: Record<string, unknown>;
+	readonly actions: Record<string, unknown>;
+}
 interface AppConfig {
 	basePath?: string;
 	version?: string;
 	cors?: CorsConfig;
+	/** Domain definitions for auto-CRUD route generation */
+	domains?: DomainDefinition[];
+	/** API prefix for domain routes (default: '/api/') */
+	apiPrefix?: string;
+	/** Enable response schema validation in dev mode (logs warnings but doesn't break response) */
+	validateResponses?: boolean;
 }
 interface ListenOptions {
 	hostname?: string;
+	logRoutes?: boolean;
 }
 interface ServerHandle {
 	readonly port: number;
@@ -180,18 +245,55 @@ interface ServerHandle {
 interface ServerAdapter {
 	listen(port: number, handler: (request: Request) => Promise<Response>, options?: ListenOptions): Promise<ServerHandle>;
 }
-interface AppBuilder {
-	register(module: NamedModule, options?: Record<string, unknown>): AppBuilder;
-	middlewares(list: NamedMiddlewareDef[]): AppBuilder;
+interface RouteInfo {
+	method: string;
+	path: string;
+}
+interface AppBuilder<TMiddlewareCtx extends Record<string, unknown> = Record<string, unknown>> {
+	register(module: NamedModule, options?: Record<string, unknown>): AppBuilder<TMiddlewareCtx>;
+	middlewares<const M extends readonly NamedMiddlewareDef<any, any>[]>(list: M): AppBuilder<AccumulateProvides<M>>;
 	readonly handler: (request: Request) => Promise<Response>;
 	listen(port?: number, options?: ListenOptions): Promise<ServerHandle>;
+	/** Exposes registered routes for testing/inspection */
+	readonly router: {
+		routes: RouteInfo[];
+	};
 }
 declare function createApp(config: AppConfig): AppBuilder;
+type ServiceFactory<
+	TDeps = unknown,
+	TState = unknown,
+	TMethods = unknown,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TEnv extends Record<string, unknown> = Record<string, unknown>
+> = ServiceDef<TDeps, TState, TMethods, TOptions, TEnv>;
+interface ServiceBootInstruction {
+	type: "service";
+	id: string;
+	deps: string[];
+	factory: ServiceFactory;
+	options?: Record<string, unknown>;
+	env?: Record<string, unknown>;
+}
+interface ModuleBootInstruction {
+	type: "module";
+	id: string;
+	services: string[];
+	options?: Record<string, unknown>;
+}
+type BootInstruction = ServiceBootInstruction | ModuleBootInstruction;
+interface BootSequence {
+	instructions: BootInstruction[];
+	shutdownOrder: string[];
+}
 import { Schema as Schema3 } from "@vertz/schema";
 interface EnvConfig<T = unknown> {
 	load?: string[];
 	schema: Schema3<T>;
 }
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+type HttpStatusCode = 200 | 201 | 204 | 301 | 302 | 304 | 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 | 500 | 502 | 503 | 504;
+import { Infer, Infer as Infer2 } from "@vertz/schema";
 declare function createEnv<T>(config: EnvConfig<T>): T;
 declare class VertzException extends Error {
 	readonly statusCode: number;
@@ -235,36 +337,137 @@ declare class ServiceUnavailableException extends VertzException {
 declare function createImmutableProxy<T extends object>(obj: T, contextName: string, rootName?: string, proxyCache?: WeakMap<object, unknown>): T;
 declare function deepFreeze<T>(obj: T, visited?: WeakSet<object>): T;
 declare function makeImmutable<T extends object>(obj: T, contextName: string): DeepReadonly<T>;
-type ServiceFactory<
-	TDeps = unknown,
-	TState = unknown,
-	TMethods = unknown
-> = ServiceDef<TDeps, TState, TMethods>;
-interface ServiceBootInstruction {
-	type: "service";
-	id: string;
-	deps: string[];
-	factory: ServiceFactory;
-}
-interface ModuleBootInstruction {
-	type: "module";
-	id: string;
-	services: string[];
-	options?: Record<string, unknown>;
-}
-type BootInstruction = ServiceBootInstruction | ModuleBootInstruction;
-interface BootSequence {
-	instructions: BootInstruction[];
-	shutdownOrder: string[];
-}
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
-type HttpStatusCode = 200 | 201 | 204 | 301 | 302 | 304 | 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 | 500 | 502 | 503 | 504;
-import { Infer, Infer as Infer2 } from "@vertz/schema";
 declare const vertz: {
 	readonly env: typeof createEnv;
 	readonly middleware: typeof createMiddleware;
 	readonly moduleDef: typeof createModuleDef;
 	readonly module: typeof createModule;
 	readonly app: typeof createApp;
+	/** @since 0.2.0 — preferred alias for `app` */
+	readonly server: typeof createApp;
 };
-export { vertz, makeImmutable, deepFreeze, createModuleDef, createModule, createMiddleware, createImmutableProxy, createEnv, createApp, VertzException, ValidationException, UnauthorizedException, ServiceUnavailableException, ServiceFactory, ServiceDef, ServiceBootInstruction, ServerHandle, ServerAdapter, RouterDef, RawRequest, NotFoundException, NamedServiceDef, NamedRouterDef, NamedModuleDef, NamedModule, NamedMiddlewareDef, ModuleDef, ModuleBootInstruction, Module, MiddlewareDef, ListenOptions, InternalServerErrorException, Infer2 as InferSchema, Infer, HttpStatusCode, HttpMethod, HandlerCtx, ForbiddenException, EnvConfig, Deps, DeepReadonly, Ctx, CorsConfig, ConflictException, BootSequence, BootInstruction, BadRequestException, AppConfig, AppBuilder };
+/**
+* Symbol used to brand Result objects to prevent accidental matches with user data.
+* Using a Symbol makes it impossible for user objects to accidentally match isResult().
+*/
+declare const RESULT_BRAND: unique symbol;
+/**
+* Result type for explicit error handling in route handlers.
+*
+* This provides an alternative to exception-based error handling,
+* making error cases visible in type signatures.
+*
+* @example
+* ```typescript
+* router.get('/:id', {
+*   handler: async (ctx) => {
+*     const user = await ctx.userService.find(ctx.params.id);
+*     if (!user) {
+*       return err(404, { message: 'User not found' });
+*     }
+*     return ok({ id: user.id, name: user.name });
+*   }
+* });
+* ```
+*/
+/**
+* Represents a successful result containing data.
+*/
+interface Ok<T> {
+	readonly ok: true;
+	readonly data: T;
+	readonly [RESULT_BRAND]: true;
+}
+/**
+* Represents an error result containing status code and error body.
+*/
+interface Err<E> {
+	readonly ok: false;
+	readonly status: number;
+	readonly body: E;
+	readonly [RESULT_BRAND]: true;
+}
+/**
+* A discriminated union type representing either a success (Ok) or failure (Err).
+*
+* @typeParam T - The type of the success data
+* @typeParam E - The type of the error body
+*
+* @example
+* ```typescript
+* type UserResult = Result<{ id: number; name: string }, { message: string }>;
+* ```
+*/
+type Result<
+	T,
+	E = unknown
+> = Ok<T> | Err<E>;
+/**
+* Creates a successful Result containing the given data.
+*
+* @param data - The success data
+* @returns An Ok result with the data
+*
+* @example
+* ```typescript
+* return ok({ id: 1, name: 'John' });
+* ```
+*/
+declare function ok<T>(data: T): Ok<T>;
+/**
+* Creates an error Result with the given status code and body.
+*
+* @param status - HTTP status code for the error
+* @param body - Error body/response
+* @returns An Err result with status and body
+*
+* @example
+* ```typescript
+* return err(404, { message: 'Not found' });
+* ```
+*/
+declare function err<E>(status: number, body: E): Err<E>;
+/**
+* Type guard to check if a Result is Ok.
+*
+* @param result - The result to check
+* @returns True if the result is Ok
+*
+* @example
+* ```typescript
+* if (isOk(result)) {
+*   console.log(result.data);
+* }
+* ```
+*/
+declare function isOk<
+	T,
+	E
+>(result: Result<T, E>): result is Ok<T>;
+/**
+* Type guard to check if a Result is Err.
+*
+* @param result - The result to check
+* @returns True if the result is Err
+*
+* @example
+* ```typescript
+* if (isErr(result)) {
+*   console.log(result.status, result.body);
+* }
+* ```
+*/
+declare function isErr<
+	T,
+	E
+>(result: Result<T, E>): result is Err<E>;
+/**
+* Creates an HTTP server. Preferred entry point for building Vertz services.
+* @since 0.2.0
+*/
+declare const createServer: (config: AppConfig) => AppBuilder;
+/**
+* @deprecated Use `createServer` instead. `createApp` will be removed in v0.3.0.
+*/
+declare const createApp2: (config: AppConfig) => AppBuilder;
+export { vertz, ok, makeImmutable, isOk, isErr, err, deepFreeze, createServer, createModuleDef, createModule, createMiddleware, createImmutableProxy, createEnv, createApp2 as createApp, VertzException, ValidationException, UnauthorizedException, ServiceUnavailableException, ServiceFactory, ServiceDef, ServiceBootInstruction, ServerHandle, ServerAdapter, RouterDef, RouteInfo, Result, ResolveInjectMap, RawRequest, Ok, NotFoundException, NamedServiceDef, NamedRouterDef, NamedModuleDef, NamedModule, NamedMiddlewareDef, ModuleDef, ModuleBootInstruction, Module, MiddlewareDef, ListenOptions, InternalServerErrorException, Infer2 as InferSchema, Infer, HttpStatusCode, HttpMethod, HandlerCtx, ForbiddenException, ExtractMethods, Err, EnvConfig, Deps, DeepReadonly, Ctx, CorsConfig, ConflictException, BootSequence, BootInstruction, BadRequestException, AppConfig, AppBuilder, AccumulateProvides };