adorn-api 1.0.0 → 1.0.2

package/dist/contracts/reply.js

@@ -0,0 +1,43 @@
+/**
+ * Type guard function to check if an object is an Adorn Reply.
+ *
+ * This function is used to safely check if an object conforms to
+ * the Reply type structure.
+ *
+ * @param x - Object to check
+ * @returns true if the object is a Reply, false otherwise
+ *
+ * @example
+ * ```typescript
+ * function handleResponse(response: unknown) {
+ *   if (isReply(response)) {
+ *     // TypeScript now knows response is a Reply
+ *     console.log('Status:', response.status);
+ *     console.log('Body:', response.body);
+ *   } else {
+ *     console.log('Not a reply object');
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In middleware or error handling
+ * if (isReply(error)) {
+ *   // It's a reply object, can be sent directly to client
+ *   res.status(error.status).json(error.body);
+ * } else {
+ *   // Handle non-reply errors
+ *   res.status(500).json({ error: 'Internal Server Error' });
+ * }
+ * ```
+ *
+ * @see Reply for the reply object type
+ */
+export function isReply(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const candidate = x;
+    return candidate.__adornReply === true && typeof candidate.status === 'number';
+}
+//# sourceMappingURL=reply.js.map

package/dist/contracts/reply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply.js","sourceRoot":"","sources":["../../src/contracts/reply.ts"],"names":[],"mappings":"AAoFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,SAAS,GAAG,CAA2B,CAAC;IAC9C,OAAO,SAAS,CAAC,YAAY,KAAK,IAAI,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC;AACjF,CAAC"}

package/dist/contracts/response-types.d.ts

@@ -0,0 +1,40 @@
+import type { Schema } from '../validation/native/schema.js';
+import type { ResponseSpec, ResponsesSpec } from './responses.js';
+export type StatusKey<R extends ResponsesSpec> = Extract<keyof R, `${number}`>;
+export type StatusNum<K extends string> = K extends `${infer N extends number}` ? N : never;
+export type AllowedStatus<R extends ResponsesSpec> = StatusNum<StatusKey<R>> | (R extends {
+    default: unknown;
+} ? number : never);
+export type ResAt<R extends ResponsesSpec, S extends number> = `${S}` extends keyof R ? R[`${S}`] : R extends {
+    default: infer D;
+} ? D : never;
+export type NormalizeRes<X> = X extends Schema<unknown> ? {
+    content: {
+        'application/json': {
+            schema: X;
+        };
+    };
+} : X extends ResponseSpec ? X : never;
+export type ContentOf<X> = NormalizeRes<X> extends {
+    content: infer C;
+} ? C : never;
+export type SchemaFromContent<C> = C extends Record<PropertyKey, unknown> ? ('application/json' extends keyof C ? C['application/json'] extends {
+    schema: infer S extends Schema<unknown>;
+} ? S : never : C[keyof C] extends {
+    schema: infer S extends Schema<unknown>;
+} ? S : never) : never;
+export type BodySchemaFor<R extends ResponsesSpec, S extends number> = SchemaFromContent<ContentOf<ResAt<R, S>>>;
+export type HeadersDefFor<R extends ResponsesSpec, S extends number> = NormalizeRes<ResAt<R, S>> extends {
+    headers?: infer H;
+} ? H : undefined;
+export type StatusesWithBody<R extends ResponsesSpec> = {
+    [K in StatusKey<R>]: BodySchemaFor<R, StatusNum<K>> extends never ? never : StatusNum<K>;
+}[StatusKey<R>];
+export type StatusesNoBody<R extends ResponsesSpec> = {
+    [K in StatusKey<R>]: BodySchemaFor<R, StatusNum<K>> extends never ? StatusNum<K> : never;
+}[StatusKey<R>];
+export type SuccessStatusKeys<R extends ResponsesSpec> = Extract<StatusKey<R>, `2${string}`>;
+export type SuccessStatusNumbers<R extends ResponsesSpec> = SuccessStatusKeys<R> extends `${infer N extends number}` ? N : never;
+export type SuccessStatusesWithBody<R extends ResponsesSpec> = Extract<StatusesWithBody<R>, SuccessStatusNumbers<R>>;
+export type SuccessStatusesNoBody<R extends ResponsesSpec> = Extract<StatusesNoBody<R>, SuccessStatusNumbers<R>>;
+//# sourceMappingURL=response-types.d.ts.map

package/dist/contracts/response-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-types.d.ts","sourceRoot":"","sources":["../../src/contracts/response-types.ts"],"names":[],"mappings":"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"}

package/dist/contracts/response-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=response-types.js.map

package/dist/contracts/response-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-types.js","sourceRoot":"","sources":["../../src/contracts/response-types.ts"],"names":[],"mappings":""}

package/dist/contracts/responses.d.ts

@@ -0,0 +1,98 @@
+import type { Schema } from '../validation/native/schema.js';
+/**
+ * Specification for response content including schema and example.
+ *
+ * @template T - The type that the schema validates
+ */
+export type ResponseContentSpec = {
+    /** Schema defining the structure and validation rules for the response content */
+    schema: Schema<unknown>;
+    /** Example value that matches the schema */
+    example?: unknown;
+};
+/**
+ * Specification for HTTP response headers.
+ *
+ * @template T - The type that the schema validates
+ */
+export type HeaderSpec = {
+    /** Schema defining the structure and validation rules for the header */
+    schema: Schema<unknown>;
+    /** Human-readable description of the header */
+    description?: string;
+    /** Whether the header is required */
+    required?: boolean;
+};
+/**
+ * Complete specification for an HTTP response.
+ *
+ * This type defines all aspects of an HTTP response including status codes,
+ * content types, headers, and schemas. It's used to document and validate
+ * API responses.
+ *
+ * @example
+ * ```typescript
+ * const successResponse: ResponseSpec = {
+ *   description: 'User created successfully',
+ *   headers: {
+ *     'X-Request-ID': {
+ *       schema: Schema.String(),
+ *       description: 'Unique request identifier',
+ *       required: true
+ *     }
+ *   },
+ *   content: {
+ *     'application/json': {
+ *       schema: userSchema,
+ *       example: { id: '123', name: 'John Doe', email: 'john@example.com' }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @see Schema for schema definition
+ */
+export type ResponseSpec = {
+    /** Human-readable description of the response */
+    description?: string;
+    /** Response headers specification */
+    headers?: Record<string, HeaderSpec>;
+    /** Response content by media type */
+    content?: Record<string, ResponseContentSpec>;
+    /** Legacy schema property (use content instead for proper media type handling) */
+    schema?: Schema<unknown>;
+};
+/**
+ * Collection of response specifications keyed by HTTP status code.
+ *
+ * This type represents all possible responses for a given endpoint,
+ * with status codes as keys and ResponseSpec objects as values.
+ *
+ * @example
+ * ```typescript
+ * const userResponses: ResponsesSpec = {
+ *   '200': {
+ *     description: 'User found',
+ *     content: {
+ *       'application/json': {
+ *         schema: userSchema,
+ *         example: { id: '123', name: 'John Doe' }
+ *       }
+ *     }
+ *   },
+ *   '404': {
+ *     description: 'User not found',
+ *     content: {
+ *       'application/json': {
+ *         schema: errorSchema,
+ *         example: { error: 'User not found', code: 'USER_NOT_FOUND' }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @see ResponseSpec for individual response specification
+ */
+export type ResponsesSpec = Record<string, ResponseSpec | Schema<unknown>>;
+//# sourceMappingURL=responses.d.ts.map

package/dist/contracts/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/contracts/responses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC9C,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC"}

package/dist/contracts/responses.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=responses.js.map

package/dist/contracts/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../src/contracts/responses.ts"],"names":[],"mappings":""}

package/dist/contracts/route-options.d.ts

@@ -0,0 +1,155 @@
+import type { ResponsesSpec } from './responses.js';
+import type { Schema } from '../validation/native/schema.js';
+import type { ExtractPathParams } from '../core/typing/path-params.js';
+import type { SecurityRequirementObject } from './openapi-v3.js';
+/**
+ * Type hints for path parameter coercion.
+ *
+ * These hints are used to automatically convert path parameters
+ * to specific types during request processing.
+ */
+export type ScalarHint = 'string' | 'int' | 'number' | 'boolean' | 'uuid';
+/**
+ * Validation configuration for route parameters.
+ *
+ * Specifies schemas for validating different parts of the request.
+ *
+ * @example
+ * ```typescript
+ * const routeValidation: RouteValidate = {
+ *   params: Schema.Object({
+ *     id: Schema.String().format('uuid')
+ *   }),
+ *   query: Schema.Object({
+ *     limit: Schema.Number().min(1).max(100),
+ *     offset: Schema.Number().min(0)
+ *   }),
+ *   body: Schema.Object({
+ *     title: Schema.String().minLength(3),
+ *     content: Schema.String().minLength(10)
+ *   })
+ * };
+ * ```
+ *
+ * @see Schema for schema definition
+ */
+export type RouteValidate = {
+    /** Schema for validating path parameters */
+    params?: Schema<unknown>;
+    /** Schema for validating query parameters */
+    query?: Schema<unknown>;
+    /** Schema for validating request body */
+    body?: Schema<unknown>;
+};
+/**
+ * Parameter binding configuration for routes.
+ *
+ * Specifies how path parameters should be coerced to specific types.
+ *
+ * @template Path - The route path as a string literal
+ *
+ * @example
+ * ```typescript
+ * // For route '/users/:id/:status'
+ * const routeBindings: RouteBindings<'/users/:id/:status'> = {
+ *   path: {
+ *     id: 'uuid',      // Coerce to UUID format
+ *     status: 'string' // Keep as string
+ *   }
+ * };
+ * ```
+ *
+ * @see ScalarHint for available type hints
+ */
+export type RouteBindings<Path extends string> = {
+    /** Type hints for path parameters */
+    path?: Partial<Record<ExtractPathParams<Path>, ScalarHint>>;
+};
+/**
+ * Complete route configuration options.
+ *
+ * This type defines all available options for configuring a route,
+ * including OpenAPI documentation, validation, parameter binding,
+ * and response specifications.
+ *
+ * @template Path - The route path as a string literal
+ *
+ * @example
+ * ```typescript
+ * const userRouteOptions: RouteOptions<'/users/:id'> = {
+ *   summary: 'Get user by ID',
+ *   description: 'Retrieves a user by their unique identifier',
+ *   tags: ['Users'],
+ *   operationId: 'getUserById',
+ *   deprecated: false,
+ *   security: [{ bearerAuth: [] }],
+ *
+ *   validate: {
+ *     params: Schema.Object({
+ *       id: Schema.String().format('uuid')
+ *     })
+ *   },
+ *
+ *   bindings: {
+ *     path: { id: 'uuid' }
+ *   },
+ *
+ *   responses: {
+ *     '200': {
+ *       description: 'User found',
+ *       content: {
+ *         'application/json': {
+ *           schema: userSchema,
+ *           example: { id: '123', name: 'John Doe' }
+ *         }
+ *       }
+ *     },
+ *     '404': {
+ *       description: 'User not found'
+ *     }
+ *   },
+ *
+ *   successStatus: 200
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal route options
+ * const simpleRouteOptions: RouteOptions = {
+ *   summary: 'Health check',
+ *   responses: {
+ *     '200': { description: 'Service is healthy' }
+ *   }
+ * };
+ * ```
+ *
+ * @see ResponsesSpec for response specification format
+ * @see RouteValidate for validation configuration
+ * @see RouteBindings for parameter binding configuration
+ */
+export type RouteOptions<Path extends string = string> = {
+    /** Short summary of the endpoint */
+    summary?: string;
+    /** Detailed description of the endpoint */
+    description?: string;
+    /** Tags for grouping endpoints in documentation */
+    tags?: string[];
+    /** Unique identifier for the operation */
+    operationId?: string;
+    /** Whether the endpoint is deprecated */
+    deprecated?: boolean;
+    /** Security requirements for the endpoint */
+    security?: SecurityRequirementObject[];
+    /** Validation configuration for request parts */
+    validate?: RouteValidate;
+    /** Parameter binding configuration */
+    bindings?: RouteBindings<Path>;
+    /** Response specifications by status code */
+    responses?: ResponsesSpec;
+    /** Default success status code */
+    successStatus?: number;
+    /** Allow additional custom properties */
+    [k: string]: unknown;
+};
+//# sourceMappingURL=route-options.d.ts.map

package/dist/contracts/route-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-options.d.ts","sourceRoot":"","sources":["../../src/contracts/route-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACzB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,CAAC,IAAI,SAAS,MAAM,IAAI;IAC/C,qCAAqC;IACrC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,MAAM,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI;IACvD,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAEvC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAE/B,6CAA6C;IAC7C,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,yCAAyC;IACzC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,CAAC"}

package/dist/contracts/route-options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=route-options.js.map

package/dist/contracts/route-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-options.js","sourceRoot":"","sources":["../../src/contracts/route-options.ts"],"names":[],"mappings":""}

package/dist/contracts/route-typing.d.ts

@@ -0,0 +1,25 @@
+import type { Schema } from '../validation/native/schema.js';
+type InferSchema<S> = S extends Schema<infer T> ? T : never;
+export type QueryOf<R> = R extends {
+    options: {
+        validate?: {
+            query?: infer S;
+        };
+    };
+} ? InferSchema<S> : never;
+export type BodyOf<R> = R extends {
+    options: {
+        validate?: {
+            body?: infer S;
+        };
+    };
+} ? InferSchema<S> : never;
+export type ParamsOf<R> = R extends {
+    options: {
+        validate?: {
+            params?: infer S;
+        };
+    };
+} ? InferSchema<S> : never;
+export {};
+//# sourceMappingURL=route-typing.d.ts.map

package/dist/contracts/route-typing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-typing.d.ts","sourceRoot":"","sources":["../../src/contracts/route-typing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AAE7D,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5D,MAAM,MAAM,OAAO,CAAC,CAAC,IACnB,CAAC,SAAS;IAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAErF,MAAM,MAAM,MAAM,CAAC,CAAC,IAClB,CAAC,SAAS;IAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAEpF,MAAM,MAAM,QAAQ,CAAC,CAAC,IACpB,CAAC,SAAS;IAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC"}

package/dist/contracts/route-typing.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=route-typing.js.map

package/dist/contracts/route-typing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-typing.js","sourceRoot":"","sources":["../../src/contracts/route-typing.ts"],"names":[],"mappings":""}

package/dist/contracts/validator.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Path to a validation issue within the request data.
+ *
+ * Represents the location of a validation failure using an array
+ * where each element is a property name or array index.
+ *
+ * @example
+ * ```typescript
+ * // For body: { user: { email: 'invalid' } }
+ * const path: ValidationPath = ['body', 'user', 'email'];
+ *
+ * // For query: { filters: { page: 'not-a-number' } }
+ * const path: ValidationPath = ['query', 'filters', 'page'];
+ *
+ * // For array: { items: [{ id: 'invalid' }] }
+ * const path: ValidationPath = ['body', 'items', 0, 'id'];
+ * ```
+ */
+export type ValidationPath = Array<string | number>;
+/**
+ * Individual validation issue with path and details.
+ *
+ * Represents a single validation failure with information about
+ * where it occurred, what was expected, and what was received.
+ */
+export type ValidationIssue = {
+    /** Path to the invalid data within the request */
+    path: ValidationPath;
+    /** Human-readable error message */
+    message: string;
+    /** Machine-readable error code */
+    code?: string;
+    /** Expected value or type */
+    expected?: unknown;
+    /** Received value that failed validation */
+    received?: unknown;
+};
+/**
+ * Result of a validation operation.
+ *
+ * This discriminated union represents either a successful validation
+ * with the validated value, or a failed validation with issues.
+ *
+ * @template T - The expected type after successful validation
+ *
+ * @example
+ * ```typescript
+ * // Successful validation
+ * const success: ValidationResult<User> = {
+ *   ok: true,
+ *   value: { id: '123', name: 'John Doe', email: 'john@example.com' }
+ * };
+ *
+ * // Failed validation
+ * const failure: ValidationResult<User> = {
+ *   ok: false,
+ *   issues: [
+ *     { path: ['body', 'email'], message: 'Invalid email format', code: 'invalid_string' }
+ *   ]
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in validation logic
+ * const result = validator.validateBody(request.body, 'createUserSchema');
+ *
+ * if (!result.ok) {
+ *   throw new ValidationError('Invalid user data', result.issues);
+ * }
+ *
+ * const validatedUser = result.value;
+ * ```
+ */
+export type ValidationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+/**
+ * Optional pluggable validator interface.
+ *
+ * You can implement adapters later (zod/ajv/valibot).
+ *
+ * This interface defines the contract for validation services
+ * that can be plugged into the Adorn API framework.
+ *
+ * @example
+ * ```typescript
+ * // Custom validator implementation
+ * class MyValidator implements Validator {
+ *   validateBody<T>(body: unknown, schemaId: string): ValidationResult<T> {
+ *     // Implement body validation logic
+ *   }
+ *
+ *   validateQuery<T>(query: unknown, schemaId: string): ValidationResult<T> {
+ *     // Implement query validation logic
+ *   }
+ *
+ *   validateParams<T>(params: unknown, schemaId: string): ValidationResult<T> {
+ *     // Implement params validation logic
+ *   }
+ * }
+ *
+ * // Usage in Express adapter
+ * const app = createAdornExpressApp({
+ *   controllers: [UserController],
+ *   validator: new MyValidator()
+ * });
+ * ```
+ *
+ * @see ValidationResult for the result type
+ * @see ValidationIssue for issue details
+ */
+export interface Validator {
+    /**
+     * Validates request body against a schema.
+     *
+     * @template T - Expected type after validation
+     * @param body - Request body to validate
+     * @param schemaId - Identifier for the schema to use
+     * @returns Validation result
+     */
+    validateBody<T = unknown>(body: unknown, schemaId: string): ValidationResult<T>;
+    /**
+     * Validates query parameters against a schema.
+     *
+     * @template T - Expected type after validation
+     * @param query - Query parameters to validate
+     * @param schemaId - Identifier for the schema to use
+     * @returns Validation result
+     */
+    validateQuery<T = unknown>(query: unknown, schemaId: string): ValidationResult<T>;
+    /**
+     * Validates path parameters against a schema.
+     *
+     * @template T - Expected type after validation
+     * @param params - Path parameters to validate
+     * @param schemaId - Identifier for the schema to use
+     * @returns Validation result
+     */
+    validateParams<T = unknown>(params: unknown, schemaId: string): ValidationResult<T>;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/contracts/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/contracts/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,kDAAkD;IAClD,IAAI,EAAE,cAAc,CAAC;IACrB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAEhF;;;;;;;OAOG;IACH,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAElF;;;;;;;OAOG;IACH,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACrF"}

package/dist/contracts/validator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validator.js.map

package/dist/contracts/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/contracts/validator.ts"],"names":[],"mappings":""}

package/dist/core/binding/binder.d.ts

@@ -0,0 +1,74 @@
+import type { RequestContext } from '../../contracts/context.js';
+import type { RouteEntry } from '../registry/types.js';
+import type { CoerceMode } from './coerce/primitives.js';
+type HandlerFunction = (...args: unknown[]) => unknown;
+/**
+ * Prepared binding data after argument binding.
+ * Contains the processed params, query, and body data.
+ */
+export type BindingPrepared = {
+    /** Path parameters extracted and coerced from the URL */
+    params: Record<string, unknown>;
+    /** Query parameters extracted and processed from the URL query string */
+    query: Record<string, unknown>;
+    /** Request body parsed and processed */
+    body: unknown;
+};
+/**
+ * Result of the bindArgs function containing:
+ * - args: The arguments to pass to the handler function
+ * - prepared: The processed binding data
+ */
+export type BindArgsResult = {
+    /** Arguments to pass to the handler function in order */
+    args: unknown[];
+    /** Prepared binding data for reference */
+    prepared: BindingPrepared;
+};
+/**
+ * Options for the bindArgs function to control binding behavior.
+ */
+export type BindOptions = {
+    /** Coercion mode for automatic type conversion ('smart', 'strict', or 'none') */
+    coerce?: CoerceMode;
+    /** Whether to parse CSV values in query parameters */
+    csv?: boolean;
+    /** Whether to pass the request context as the last argument */
+    passContext?: boolean;
+};
+/**
+ * Binds request data to handler function arguments based on route configuration.
+ *
+ * This function automatically maps path parameters, query parameters, and request body
+ * to the handler function arguments based on the route's binding configuration and
+ * HTTP method conventions.
+ *
+ * @param route - The route entry containing metadata about the handler
+ * @param handler - The handler function to bind arguments for
+ * @param ctx - The request context containing params, query, and body
+ * @param opts - Binding options to control behavior
+ * @returns Object containing args to pass to handler and prepared binding data
+ *
+ * @example
+ * ```typescript
+ * // For a route like: @Get('/users/:id')
+ * // With handler: async getUser(id: string, ctx: RequestContext)
+ * const { args } = bindArgs(route, handler, requestContext);
+ * const result = await handler(...args); // Automatically passes id and ctx
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // For a POST route with body
+ * // @Post('/users')
+ * // async createUser(@Body() userData: CreateUserDto)
+ * const { args } = bindArgs(route, handler, requestContext);
+ * const result = await handler(...args); // Automatically passes parsed body
+ * ```
+ *
+ * @see RouteEntry for route metadata structure
+ * @see RequestContext for request data structure
+ */
+export declare function bindArgs(route: RouteEntry, handler: HandlerFunction, ctx: RequestContext, opts?: BindOptions): BindArgsResult;
+export {};
+//# sourceMappingURL=binder.d.ts.map

package/dist/core/binding/binder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binder.d.ts","sourceRoot":"","sources":["../../../src/core/binding/binder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,KAAK,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,wCAAwC;IACxC,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yDAAyD;IACzD,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,sDAAsD;IACtD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,cAAc,EACnB,IAAI,GAAE,WAAgB,GACrB,cAAc,CAoEhB"}