@honorestjs/contract/dist/builder/endpoint.d.ts

Contract-first API definitions for HonorestJS - Framework-agnostic contract definitions with full type safety

import type { ZodSchema } from 'zod';
/**
 * HTTP methods supported by endpoints
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
/**
 * Endpoint definition structure
 * Defines the complete specification for a single API endpoint
 */
export interface EndpointDefinition {
    /**
     * HTTP method for this endpoint
     * @example 'GET' | 'POST' | 'PUT' | 'DELETE'
     */
    method: HttpMethod;
    /**
     * Endpoint path (relative to contract path)
     * Supports path parameters using colon syntax
     * @example '/:id' | '/users/:userId/posts/:postId' | '/'
     */
    path: string;
    /**
     * Path parameters schema
     * Validates route parameters (e.g., :id in path)
     * @example z.object({ id: z.string().uuid() })
     */
    params?: ZodSchema;
    /**
     * Query parameters schema
     * Validates URL query string parameters
     * @example z.object({ page: z.number(), limit: z.number() })
     */
    query?: ZodSchema;
    /**
     * Request body schema
     * Validates the request payload
     * @example z.object({ name: z.string(), email: z.string().email() })
     */
    body?: ZodSchema;
    /**
     * Request headers schema
     * Validates specific headers required by this endpoint
     * @example z.object({ 'x-api-key': z.string() })
     */
    headers?: ZodSchema;
    /**
     * Response schema
     * Defines and validates the successful response structure
     * @example z.object({ id: z.string(), name: z.string() })
     */
    output: ZodSchema;
    /**
     * Error response schemas (keyed by HTTP status code)
     * Defines possible error responses for this endpoint
     * @example { 404: z.object({ message: z.string() }) }
     */
    errors?: Record<number, ZodSchema>;
    /**
     * Detailed description of the endpoint
     * Used for documentation generation
     */
    description?: string;
    /**
     * Short summary of the endpoint
     * Used as a brief title in documentation
     */
    summary?: string;
    /**
     * Tags for grouping endpoints
     * Used to organize endpoints in documentation
     * @example ['users', 'admin']
     */
    tags?: string[];
    /**
     * Mark endpoint as deprecated
     * Indicates this endpoint should not be used in new code
     */
    deprecated?: boolean;
    /**
     * Example requests and responses
     * Used for documentation and testing
     */
    examples?: {
        request?: unknown;
        response?: unknown;
    };
}
/**
 * Branded endpoint type - a definition with a runtime marker
 */
export type Endpoint<T extends EndpointDefinition = EndpointDefinition> = T & {
    readonly __endpoint: unique symbol;
};
/**
 * Creates an endpoint definition
 *
 * An endpoint represents a single API operation with its complete specification
 * including request/response schemas, HTTP method, path, and documentation.
 *
 * @param definition - The endpoint specification
 * @returns An endpoint object with type inference helpers
 *
 * @example
 * ```typescript
 * const getUser = endpoint({
 *   method: 'GET',
 *   path: '/:id',
 *   params: z.object({ id: z.string().uuid() }),
 *   output: z.object({
 *     id: z.string().uuid(),
 *     name: z.string(),
 *     email: z.string().email()
 *   }),
 *   description: 'Get a user by ID',
 *   errors: {
 *     404: z.object({ message: z.string() })
 *   }
 * })
 * ```
 */
export declare function endpoint<const T extends EndpointDefinition>(definition: T): Endpoint<T>;
/**
 * Type guard to check if a value is an endpoint
 */
export declare function isEndpoint(value: unknown): value is Endpoint;
//# sourceMappingURL=endpoint.d.ts.map