adorn-api 1.0.1 → 1.0.3

package/dist/contracts/reply.js

@@ -1,4 +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) {
-    return !!x && typeof x === 'object' && x.__adornReply === true && typeof x.status === 'number';
+    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

@@ -1 +1 @@
-{"version":3,"file":"reply.js","sourceRoot":"","sources":["../../src/contracts/reply.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAAS,CAAC,YAAY,KAAK,IAAI,IAAI,OAAQ,CAAS,CAAC,MAAM,KAAK,QAAQ,CAAC;AACnH,CAAC"}
+{"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

@@ -3,12 +3,12 @@ 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: any;
+    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<any> ? {
+export type NormalizeRes<X> = X extends Schema<unknown> ? {
     content: {
         'application/json': {
             schema: X;
@@ -18,10 +18,10 @@ export type NormalizeRes<X> = X extends Schema<any> ? {
 export type ContentOf<X> = NormalizeRes<X> extends {
     content: infer C;
 } ? C : never;
-export type SchemaFromContent<C> = C extends Record<PropertyKey, any> ? ('application/json' extends keyof C ? C['application/json'] extends {
-    schema: infer S extends Schema<any>;
+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<any>;
+    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 {

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

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

package/dist/contracts/responses.d.ts

@@ -1,18 +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: Schema<any>;
+    /** 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: Schema<any>;
+    /** 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>;
-    schema?: Schema<any>;
+    /** Legacy schema property (use content instead for proper media type handling) */
+    schema?: Schema<unknown>;
 };
-export type ResponsesSpec = Record<string, ResponseSpec | Schema<any>>;
+/**
+ * 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

@@ -1 +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,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC"}
+{"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/route-options.d.ts

@@ -1,24 +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 = {
-    params?: Schema<any>;
-    query?: Schema<any>;
-    body?: Schema<any>;
+    /** 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

@@ -1 +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;AAEvE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,IAAI,SAAS,MAAM,IAAI;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAE/B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,CAAC"}
+{"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/validator.d.ts

@@ -1,11 +1,77 @@
+/**
+ * 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;
@@ -15,11 +81,66 @@ export type ValidationResult<T> = {
 };
 /**
  * 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

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/contracts/validator.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AAEpD,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,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;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAChF,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAClF,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACrF"}
+{"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/core/binding/binder.d.ts

@@ -1,19 +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;
 };
-export declare function bindArgs(route: RouteEntry, handler: Function, ctx: RequestContext, opts?: BindOptions): BindArgsResult;
+/**
+ * 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

@@ -1 +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,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAgB,QAAQ,CACtB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,QAAQ,EACjB,GAAG,EAAE,cAAc,EACnB,IAAI,GAAE,WAAgB,GACrB,cAAc,CAoEhB"}
+{"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"}

package/dist/core/binding/binder.js

@@ -2,6 +2,39 @@ import { HttpError } from '../errors/http-error.js';
 import { getPathTokenNames } from './rules/inferFromPath.js';
 import { conventionForMethod } from './rules/inferFromHttpMethod.js';
 import { coerceObjectSmart, coerceValueSmart } from './coerce/arrays.js';
+/**
+ * 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 function bindArgs(route, handler, ctx, opts = {}) {
     const passContext = opts.passContext ?? true;
     const coerceMode = opts.coerce ?? 'smart';