adorn-api 1.0.1 → 1.0.2

package/dist/contracts/openapi-v3.d.ts

@@ -1,77 +1,538 @@
+/**
+ * Complete OpenAPI 3.0.3 document structure.
+ *
+ * This type represents the root OpenAPI document that contains
+ * all API metadata, paths, operations, and components.
+ *
+ * @see https://spec.openapis.org/oas/v3.0.3
+ *
+ * @example
+ * ```typescript
+ * const openApiDoc: OpenApiDocument = {
+ *   openapi: '3.0.3',
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     description: 'API for user management'
+ *   },
+ *   servers: [
+ *     { url: 'https://api.example.com/v1', description: 'Production server' }
+ *   ],
+ *   paths: {
+ *     '/users': {
+ *       get: {
+ *         summary: 'List users',
+ *         responses: {
+ *           '200': { description: 'List of users' }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   components: {
+ *     schemas: {
+ *       User: {
+ *         type: 'object',
+ *         properties: {
+ *           id: { type: 'string', format: 'uuid' },
+ *           name: { type: 'string' }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export type OpenApiDocument = {
+    /** OpenAPI specification version */
     openapi: '3.0.3' | (string & {});
+    /** API metadata including title, version, and description */
     info: {
         title: string;
         version: string;
         description?: string;
     };
+    /** Array of server objects */
     servers?: Array<{
         url: string;
         description?: string;
     }>;
+    /** Paths and operations */
     paths: Record<string, PathItemObject>;
+    /** Reusable components */
     components?: ComponentsObject;
 };
+/**
+ * Reusable components for OpenAPI specification.
+ *
+ * Contains schemas, security schemes, and other reusable
+ * components that can be referenced throughout the document.
+ *
+ * @example
+ * ```typescript
+ * const components: ComponentsObject = {
+ *   schemas: {
+ *     User: {
+ *       type: 'object',
+ *       properties: {
+ *         id: { type: 'string', format: 'uuid' },
+ *         name: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   securitySchemes: {
+ *     bearerAuth: {
+ *       type: 'http',
+ *       scheme: 'bearer',
+ *       bearerFormat: 'JWT'
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export type ComponentsObject = {
+    /** Reusable schema definitions */
     schemas?: Record<string, SchemaObject>;
+    /** Security scheme definitions */
+    securitySchemes?: Record<string, SecuritySchemeObject>;
 };
+/**
+ * Path item containing HTTP method operations.
+ *
+ * Maps HTTP methods to their corresponding operation objects
+ * for a specific path.
+ *
+ * @example
+ * ```typescript
+ * const pathItem: PathItemObject = {
+ *   get: {
+ *     summary: 'Get user',
+ *     responses: { '200': { description: 'User found' } }
+ *   },
+ *   post: {
+ *     summary: 'Create user',
+ *     responses: { '201': { description: 'User created' } }
+ *   }
+ * };
+ * ```
+ */
 export type PathItemObject = Partial<Record<HttpMethod, OperationObject>>;
+/**
+ * HTTP methods supported by OpenAPI.
+ *
+ * Standard HTTP methods that can be used in path items.
+ */
 export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * Operation object describing an API endpoint.
+ *
+ * Contains all information about a single API operation
+ * including parameters, request body, responses, and security.
+ *
+ * @example
+ * ```typescript
+ * const operation: OperationObject = {
+ *   operationId: 'getUserById',
+ *   summary: 'Get user by ID',
+ *   description: 'Retrieves a user by their unique identifier',
+ *   tags: ['Users'],
+ *   deprecated: false,
+ *   security: [{ bearerAuth: [] }],
+ *   parameters: [
+ *     {
+ *       name: 'id',
+ *       in: 'path',
+ *       required: true,
+ *       schema: { type: 'string', format: 'uuid' }
+ *     }
+ *   ],
+ *   responses: {
+ *     '200': {
+ *       description: 'User found',
+ *       content: {
+ *         'application/json': {
+ *           schema: { $ref: '#/components/schemas/User' }
+ *         }
+ *       }
+ *     },
+ *     '404': { description: 'User not found' }
+ *   }
+ * };
+ * ```
+ */
 export type OperationObject = {
+    /** Unique identifier for the operation */
     operationId?: string;
+    /** Short summary of the operation */
     summary?: string;
+    /** Detailed description of the operation */
     description?: string;
+    /** Tags for grouping operations */
     tags?: string[];
+    /** Whether the operation is deprecated */
     deprecated?: boolean;
+    /** Security requirements */
+    security?: SecurityRequirementObject[];
+    /** Parameters for the operation */
     parameters?: ParameterObject[];
+    /** Request body specification */
     requestBody?: RequestBodyObject;
+    /** Responses by status code */
     responses: Record<string, ResponseObject>;
 };
+/**
+ * Parameter object for operation parameters.
+ *
+ * Describes a single parameter that can be passed
+ * in path, query, header, or cookie.
+ *
+ * @example
+ * ```typescript
+ * // Path parameter
+ * const pathParam: ParameterObject = {
+ *   name: 'id',
+ *   in: 'path',
+ *   required: true,
+ *   schema: { type: 'string', format: 'uuid' }
+ * };
+ *
+ * // Query parameter
+ * const queryParam: ParameterObject = {
+ *   name: 'limit',
+ *   in: 'query',
+ *   required: false,
+ *   schema: { type: 'integer', minimum: 1, maximum: 100 }
+ * };
+ *
+ * // Header parameter
+ * const headerParam: ParameterObject = {
+ *   name: 'X-Request-ID',
+ *   in: 'header',
+ *   required: false,
+ *   schema: { type: 'string' }
+ * };
+ * ```
+ */
 export type ParameterObject = {
+    /** Parameter name */
     name: string;
+    /** Parameter location */
     in: 'path' | 'query' | 'header' | 'cookie';
+    /** Whether parameter is required */
     required?: boolean;
+    /** Parameter schema or reference */
     schema?: SchemaObject | ReferenceObject;
 };
+/**
+ * Request body object for operation input.
+ *
+ * Describes the request body including content types
+ * and schemas for different media types.
+ *
+ * @example
+ * ```typescript
+ * const requestBody: RequestBodyObject = {
+ *   required: true,
+ *   content: {
+ *     'application/json': {
+ *       schema: {
+ *         type: 'object',
+ *         properties: {
+ *           name: { type: 'string' },
+ *           email: { type: 'string', format: 'email' }
+ *         },
+ *         required: ['name', 'email']
+ *       }
+ *     },
+ *     'application/xml': {
+ *       schema: { type: 'string' }
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export type RequestBodyObject = {
+    /** Whether request body is required */
     required?: boolean;
+    /** Content by media type */
     content: Record<string, MediaTypeObject>;
 };
+/**
+ * Response object for operation outputs.
+ *
+ * Describes a single response including status code,
+ * headers, and content for different media types.
+ *
+ * @example
+ * ```typescript
+ * const response: ResponseObject = {
+ *   description: 'User created successfully',
+ *   headers: {
+ *     'Location': {
+ *       description: 'URL of the created user',
+ *       schema: { type: 'string', format: 'uri' }
+ *     }
+ *   },
+ *   content: {
+ *     'application/json': {
+ *       schema: { $ref: '#/components/schemas/User' },
+ *       example: {
+ *         id: '550e8400-e29b-41d4-a716-446655440000',
+ *         name: 'John Doe',
+ *         email: 'john@example.com'
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export type ResponseObject = {
+    /** Response description */
     description: string;
+    /** Response headers */
     headers?: Record<string, HeaderObject>;
+    /** Response content by media type */
     content?: Record<string, MediaTypeObject>;
 };
+/**
+ * Header object for response headers.
+ *
+ * Describes a single response header including
+ * its schema and whether it's required.
+ *
+ * @example
+ * ```typescript
+ * const header: HeaderObject = {
+ *   required: true,
+ *   description: 'Unique request identifier',
+ *   schema: { type: 'string', format: 'uuid' }
+ * };
+ * ```
+ */
 export type HeaderObject = {
+    /** Whether header is required */
     required?: boolean;
+    /** Header description */
     description?: string;
+    /** Header schema or reference */
     schema?: SchemaObject | ReferenceObject;
 };
+/**
+ * Media type object for request/response content.
+ *
+ * Describes the structure and examples for
+ * a specific media type.
+ *
+ * @example
+ * ```typescript
+ * const mediaType: MediaTypeObject = {
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       id: { type: 'string', format: 'uuid' },
+ *       name: { type: 'string' }
+ *     }
+ *   },
+ *   example: {
+ *     id: '550e8400-e29b-41d4-a716-446655440000',
+ *     name: 'John Doe'
+ *   }
+ * };
+ * ```
+ */
 export type MediaTypeObject = {
+    /** Media type schema or reference */
     schema?: SchemaObject | ReferenceObject;
+    /** Example value */
     example?: unknown;
 };
+/**
+ * Reference object for reusable components.
+ *
+ * Allows referencing other parts of the OpenAPI
+ * document using JSON references.
+ *
+ * @example
+ * ```typescript
+ * // Reference to a schema component
+ * const schemaRef: ReferenceObject = {
+ *   $ref: '#/components/schemas/User'
+ * };
+ *
+ * // Reference to a security scheme
+ * const securityRef: ReferenceObject = {
+ *   $ref: '#/components/securitySchemes/bearerAuth'
+ * };
+ * ```
+ */
 export type ReferenceObject = {
+    /** JSON reference to another component */
     $ref: string;
 };
+/**
+ * Security requirement object.
+ *
+ * Specifies which security schemes are required
+ * for an operation.
+ *
+ * @example
+ * ```typescript
+ * // Bearer token security requirement
+ * const securityReq: SecurityRequirementObject = {
+ *   bearerAuth: []
+ * };
+ *
+ * // Multiple security schemes (OR relationship)
+ * const multiSecurityReq: SecurityRequirementObject = {
+ *   bearerAuth: [],
+ *   apiKey: []
+ * };
+ *
+ * // Security scheme with scopes (OAuth2)
+ * const oauthSecurityReq: SecurityRequirementObject = {
+ *   oauth2: ['read', 'write']
+ * };
+ * ```
+ */
+export type SecurityRequirementObject = Record<string, string[]>;
+/**
+ * Security scheme object.
+ *
+ * Defines authentication/authorization schemes
+ * that can be used by operations.
+ *
+ * @example
+ * ```typescript
+ * // Bearer token security scheme
+ * const bearerScheme: SecuritySchemeObject = {
+ *   type: 'http',
+ *   scheme: 'bearer',
+ *   bearerFormat: 'JWT',
+ *   description: 'Bearer token authentication'
+ * };
+ *
+ * // API key security scheme
+ * const apiKeyScheme: SecuritySchemeObject = {
+ *   type: 'apiKey',
+ *   name: 'X-API-Key',
+ *   in: 'header',
+ *   description: 'API key authentication'
+ * };
+ *
+ * // OAuth2 security scheme
+ * const oauthScheme: SecuritySchemeObject = {
+ *   type: 'oauth2',
+ *   flows: {
+ *     authorizationCode: {
+ *       authorizationUrl: 'https://auth.example.com/authorize',
+ *       tokenUrl: 'https://auth.example.com/token',
+ *       scopes: {
+ *         read: 'Read access',
+ *         write: 'Write access'
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export type SecuritySchemeObject = {
+    /** Type of security scheme */
+    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+    /** Description of the security scheme */
+    description?: string;
+    /** Name of the header, query, or cookie parameter */
+    name?: string;
+    /** Location of the API key */
+    in?: 'query' | 'header' | 'cookie';
+    /** HTTP scheme (for type: http) */
+    scheme?: string;
+    /** Bearer format (for type: http with bearer scheme) */
+    bearerFormat?: string;
+    /** OAuth2 flows */
+    flows?: Record<string, unknown>;
+    /** OpenID Connect URL */
+    openIdConnectUrl?: string;
+};
+/**
+ * Schema object for data structure definition.
+ *
+ * Defines the structure, validation, and constraints
+ * for data used in parameters, request bodies, and responses.
+ *
+ * @example
+ * ```typescript
+ * // Simple object schema
+ * const userSchema: SchemaObject = {
+ *   type: 'object',
+ *   properties: {
+ *     id: { type: 'string', format: 'uuid' },
+ *     name: { type: 'string', minLength: 3 },
+ *     email: { type: 'string', format: 'email' },
+ *     age: { type: 'integer', minimum: 18 }
+ *   },
+ *   required: ['name', 'email']
+ * };
+ *
+ * // Array schema
+ * const usersArraySchema: SchemaObject = {
+ *   type: 'array',
+ *   items: { $ref: '#/components/schemas/User' },
+ *   minItems: 1,
+ *   maxItems: 100
+ * };
+ *
+ * // String with validation
+ * const usernameSchema: SchemaObject = {
+ *   type: 'string',
+ *   minLength: 3,
+ *   maxLength: 32,
+ *   pattern: '^[a-zA-Z0-9_]+$'
+ * };
+ *
+ * // Union schema
+ * const resultSchema: SchemaObject = {
+ *   anyOf: [
+ *     { $ref: '#/components/schemas/User' },
+ *     { $ref: '#/components/schemas/Error' }
+ *   ]
+ * };
+ * ```
+ */
 export type SchemaObject = {
+    /** Data type */
     type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    /** Format for primitive types */
     format?: string;
+    /** Whether value can be null */
     nullable?: boolean;
+    /** Minimum length for strings */
     minLength?: number;
+    /** Maximum length for strings */
     maxLength?: number;
+    /** Regular expression pattern for strings */
     pattern?: string;
+    /** Minimum value for numbers */
     minimum?: number;
+    /** Maximum value for numbers */
     maximum?: number;
+    /** Minimum number of items for arrays */
     minItems?: number;
+    /** Maximum number of items for arrays */
     maxItems?: number;
+    /** Object properties */
     properties?: Record<string, SchemaObject | ReferenceObject>;
+    /** Required properties */
     required?: string[];
+    /** Additional properties policy */
     additionalProperties?: boolean | SchemaObject | ReferenceObject;
+    /** Array items schema */
     items?: SchemaObject | ReferenceObject;
+    /** Enum values */
     enum?: Array<string | number | boolean | null>;
+    /** Any of the schemas (logical OR) */
     anyOf?: Array<SchemaObject | ReferenceObject>;
+    /** One of the schemas (exclusive OR) */
     oneOf?: Array<SchemaObject | ReferenceObject>;
+    /** All of the schemas (logical AND) */
     allOf?: Array<SchemaObject | ReferenceObject>;
 };
 //# sourceMappingURL=openapi-v3.d.ts.map

package/dist/contracts/openapi-v3.d.ts.map

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

package/dist/contracts/reply.d.ts

@@ -1,11 +1,119 @@
+/**
+ * Valid types for HTTP response headers.
+ */
 export type ReplyHeaderValue = string | number | boolean;
+/**
+ * Collection of HTTP response headers.
+ *
+ * Key-value pairs where keys are header names and values are
+ * header values of valid types.
+ *
+ * @example
+ * ```typescript
+ * const headers: ReplyHeaders = {
+ *   'Content-Type': 'application/json',
+ *   'Cache-Control': 'no-cache',
+ *   'X-Request-ID': 'abc-123-def'
+ * };
+ * ```
+ */
 export type ReplyHeaders = Record<string, ReplyHeaderValue>;
+/**
+ * Typed HTTP response object used by Adorn API.
+ *
+ * This type represents a complete HTTP response with status code,
+ * body, headers, and content type. It's used throughout the framework
+ * to return responses from controllers and handlers.
+ *
+ * @template TBody - Type of the response body
+ * @template TStatus - HTTP status code (must be a number literal)
+ *
+ * @example
+ * ```typescript
+ * // Simple JSON response
+ * const successResponse: Reply<User, 200> = {
+ *   __adornReply: true,
+ *   status: 200,
+ *   body: { id: '123', name: 'John Doe' },
+ *   headers: { 'Content-Type': 'application/json' }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error response
+ * const errorResponse: Reply<ErrorDetails, 404> = {
+ *   __adornReply: true,
+ *   status: 404,
+ *   body: { error: 'Not Found', code: 'USER_NOT_FOUND' },
+ *   headers: { 'Content-Type': 'application/json' }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Response with custom headers
+ * const responseWithHeaders: Reply<string, 201> = {
+ *   __adornReply: true,
+ *   status: 201,
+ *   body: 'Resource created',
+ *   headers: {
+ *     'Location': '/resources/123',
+ *     'X-Resource-ID': '123'
+ *   },
+ *   contentType: 'text/plain'
+ * };
+ * ```
+ *
+ * @see isReply for type guard function
+ */
 export type Reply<TBody = unknown, TStatus extends number = number> = {
+    /** Brand property to identify Adorn reply objects */
     readonly __adornReply: true;
+    /** HTTP status code */
     readonly status: TStatus;
+    /** Response body */
     readonly body?: TBody;
+    /** Response headers */
     readonly headers?: ReplyHeaders;
+    /** Content type header (convenience property) */
     readonly contentType?: string;
 };
-export declare function isReply(x: unknown): x is Reply<any, any>;
+/**
+ * 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 declare function isReply(x: unknown): x is Reply<unknown, number>;
 //# sourceMappingURL=reply.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../src/contracts/reply.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE5D,MAAM,MAAM,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI;IACpE,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAExD"}
+{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../src/contracts/reply.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI;IACpE,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC;IAC5B,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,oBAAoB;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,uBAAuB;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAI/D"}