@vertz/core 0.1.0 → 0.2.1

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,43 @@ interface CorsConfig {
 	maxAge?: number;
 	exposedHeaders?: string[];
 }
+interface EntityDefinition {
+	readonly kind?: string;
+	readonly name: string;
+	readonly model: unknown;
+	readonly access: Record<string, unknown>;
+	readonly before: Record<string, unknown>;
+	readonly after: Record<string, unknown>;
+	readonly actions: Record<string, unknown>;
+	readonly relations: Record<string, unknown>;
+}
+/**
+* An entity route entry generated by @vertz/server's route generator.
+* Core doesn't know about entity internals — it just registers these as handlers.
+*/
+interface EntityRouteEntry {
+	method: string;
+	path: string;
+	handler: (ctx: Record<string, unknown>) => Promise<Response>;
+}
 interface AppConfig {
 	basePath?: string;
 	version?: string;
 	cors?: CorsConfig;
+	/** Entity definitions for auto-CRUD route generation */
+	entities?: EntityDefinition[];
+	/** API prefix for entity routes (default: '/api/') */
+	apiPrefix?: string;
+	/** Enable response schema validation in dev mode (logs warnings but doesn't break response) */
+	validateResponses?: boolean;
+	/** Internal: pre-built entity route handlers injected by @vertz/server */
+	_entityRoutes?: EntityRouteEntry[];
+	/** Internal: factory for creating DB adapters per entity (used by @vertz/server) */
+	_entityDbFactory?: (entityDef: EntityDefinition) => unknown;
 }
 interface ListenOptions {
 	hostname?: string;
+	logRoutes?: boolean;
 }
 interface ServerHandle {
 	readonly port: number;
@@ -180,25 +259,69 @@ 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>;
+	env?: Record<string, string | undefined>;
 }
+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;
 	readonly code: string;
 	readonly details?: unknown;
 	constructor(message: string, statusCode?: number, code?: string, details?: unknown);
-	toJSON(): Record<string, unknown>;
+	toJSON(): {
+		error: {
+			code: string;
+			message: string;
+			details?: unknown;
+		};
+	};
 }
 declare class BadRequestException extends VertzException {
 	constructor(message: string, details?: unknown);
@@ -224,7 +347,16 @@ declare class ValidationException extends VertzException {
 		path: string;
 		message: string;
 	}>);
-	toJSON(): Record<string, unknown>;
+	toJSON(): {
+		error: {
+			code: string;
+			message: string;
+			details?: ReadonlyArray<{
+				path: string;
+				message: string;
+			}>;
+		};
+	};
 }
 declare class InternalServerErrorException extends VertzException {
 	constructor(message: string, details?: unknown);
@@ -235,36 +367,22 @@ 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 };
+/**
+* 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, makeImmutable, deepFreeze, createServer, createModuleDef, createModule, createMiddleware, createImmutableProxy, createEnv, createApp2 as createApp, VertzException, ValidationException, UnauthorizedException, ServiceUnavailableException, ServiceFactory, ServiceDef, ServiceBootInstruction, ServerHandle, ServerAdapter, RouterDef, RouteInfo, ResolveInjectMap, RawRequest, NotFoundException, NamedServiceDef, NamedRouterDef, NamedModuleDef, NamedModule, NamedMiddlewareDef, ModuleDef, ModuleBootInstruction, Module, MiddlewareDef, ListenOptions, InternalServerErrorException, Infer2 as InferSchema, Infer, HttpStatusCode, HttpMethod, HandlerCtx, ForbiddenException, ExtractMethods, EnvConfig, EntityRouteEntry, Deps, DeepReadonly, Ctx, CorsConfig, ConflictException, BootSequence, BootInstruction, BadRequestException, AppConfig, AppBuilder, AccumulateProvides };