expediate 1.0.4 → 1.0.5

package/dist/openapi.d.ts

@@ -0,0 +1,290 @@
+import type { ServiceMethod, ServiceInstance, ServiceDefinition } from './apis.js';
+/**
+ * A JSON Schema object (subset of draft-07 / OpenAPI 3.1 Schema Object).
+ *
+ * Only the properties most commonly used to describe API request/response
+ * bodies are listed; the index signature allows any additional keyword.
+ */
+export interface JsonSchema {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+    format?: string;
+    description?: string;
+    example?: unknown;
+    enum?: unknown[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+    allOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    $ref?: string;
+    [key: string]: unknown;
+}
+/**
+ * An OpenAPI 3.1 Parameter Object describing a single parameter (path, query,
+ * header, or cookie).
+ */
+export interface ParameterObject {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    schema?: JsonSchema;
+    example?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * An OpenAPI 3.1 Request Body Object.
+ */
+export interface RequestBodyObject {
+    description?: string;
+    required?: boolean;
+    content: Record<string, {
+        schema?: JsonSchema;
+        example?: unknown;
+    }>;
+}
+/**
+ * An OpenAPI 3.1 Response Object (value in the `responses` map).
+ */
+export interface ResponseObject {
+    description: string;
+    content?: Record<string, {
+        schema?: JsonSchema;
+        example?: unknown;
+    }>;
+    headers?: Record<string, {
+        description?: string;
+        schema?: JsonSchema;
+    }>;
+}
+/**
+ * Per-operation metadata that can be attached to a service method handler
+ * via {@link describe}.
+ *
+ * All fields are optional — any subset can be provided. Unspecified fields are
+ * inferred from the route definition (path params auto-detected, default
+ * responses assigned by HTTP verb).
+ */
+export interface OperationMeta {
+    /** Short summary of what the operation does (shown in UI tooling). */
+    summary?: string;
+    /** Longer description (Markdown supported). */
+    description?: string;
+    /** Override the auto-generated `operationId`. */
+    operationId?: string;
+    /** Tag group names (used for UI grouping). */
+    tags?: string[];
+    /**
+     * Parameter overrides / additions.
+     *
+     * Parameters provided here are merged with the auto-detected path
+     * parameters by `name`. Query, header, and cookie parameters must be
+     * provided here — they are never auto-inferred.
+     */
+    parameters?: ParameterObject[];
+    /** Request body descriptor. Provide when the method consumes a body. */
+    requestBody?: RequestBodyObject;
+    /**
+     * Response descriptors keyed by HTTP status code string.
+     *
+     * When provided, these replace the default response set entirely. The
+     * framework always injects a `'500'` reference to the built-in `ApiError`
+     * component unless you explicitly supply a `'500'` key here.
+     */
+    responses?: Record<string, ResponseObject>;
+    /** Mark as deprecated in the generated spec. */
+    deprecated?: boolean;
+    /** Additional vendor extensions (keys should start with `x-`). */
+    [key: string]: unknown;
+}
+/**
+ * Service-level OpenAPI metadata declared in the `openapi` field of a
+ * {@link ServiceDefinition}.
+ *
+ * These fields contribute to the top-level `info`, `tags`, `servers`, and
+ * `components` sections of the generated document, as well as a default tag
+ * that is applied to every operation produced from the service definition.
+ */
+export interface OpenApiServiceMeta {
+    /** Default tag applied to all operations from this service. */
+    tag?: string;
+    /** Description shown alongside the tag in UI tooling. */
+    tagDescription?: string;
+    /**
+     * Reusable JSON Schema definitions merged into `components.schemas`.
+     * Use `{ $ref: '#/components/schemas/MyModel' }` in operation metadata to
+     * reference them.
+     */
+    schemas?: Record<string, JsonSchema>;
+    /**
+     * Reusable response definitions merged into `components.responses`.
+     * Use `{ $ref: '#/components/responses/NotFound' }` in `responses` to
+     * reference them.
+     */
+    responses?: Record<string, ResponseObject>;
+}
+/**
+ * Top-level options passed to {@link openApiSpec}.
+ *
+ * Controls the `info` block and optionally overrides default servers or
+ * merges additional components into the generated document.
+ */
+export interface SpecOptions {
+    /** API title (required by the OpenAPI spec). */
+    title: string;
+    /** Semver version string (e.g. `'1.0.0'`). */
+    version: string;
+    /** Optional API description (Markdown supported). */
+    description?: string;
+    /**
+     * Base path prefix prepended to every route when converting service
+     * patterns to OpenAPI paths (e.g. `'/api/v1'`).
+     */
+    basePath?: string;
+    /** Server list (defaults to `[{ url: '/' }]` when absent). */
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    /**
+     * Additional schemas merged into `components.schemas` (takes precedence
+     * over service-level `openapi.schemas` of the same name).
+     */
+    schemas?: Record<string, JsonSchema>;
+}
+/**
+ * A minimal OpenAPI 3.1.0 document as produced by {@link openApiSpec}.
+ *
+ * Only the sections generated by the framework are typed here; extra sections
+ * (e.g. `security`, `externalDocs`) can be added by spreading the result.
+ */
+export interface OpenApiDocument {
+    openapi: '3.1.0';
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    paths: Record<string, Record<string, unknown>>;
+    components: {
+        schemas: Record<string, JsonSchema>;
+        responses: Record<string, ResponseObject>;
+    };
+}
+/**
+ * The output format for a serialised OpenAPI document.
+ *
+ * - `'json'` — compact, widely supported, default.
+ * - `'yaml'` — human-readable block YAML 1.2 (no external dependencies).
+ */
+export type SpecFormat = 'json' | 'yaml';
+/**
+ * Serialise an {@link OpenApiDocument} to either JSON or YAML.
+ *
+ * - `'json'` — pretty-printed with 2-space indentation.
+ * - `'yaml'` — block-style YAML 1.2, produced by a zero-dependency serialiser
+ *   built into expediate.
+ *
+ * @param doc    - The document to serialise.
+ * @param format - Output format (`'json'` by default).
+ */
+export declare function serializeSpec(doc: OpenApiDocument, format?: SpecFormat): string;
+/**
+ * Unique symbol used as a non-enumerable property key on handler functions
+ * that have been annotated via {@link describe}.
+ *
+ * Using a `unique symbol` (rather than a plain string key) prevents accidental
+ * collisions with user-defined properties on handler objects.
+ */
+export declare const DESCRIBE_META: unique symbol;
+/**
+ * Annotate a service method handler with OpenAPI operation metadata.
+ *
+ * The metadata is attached to the returned function via a non-enumerable
+ * property keyed by {@link DESCRIBE_META}.  The returned function is otherwise
+ * identical to `handler` — it can be used directly in a `ServiceDefinition`
+ * route map.
+ *
+ * ```ts
+ * GET: {
+ *   '/items/:id': describe(
+ *     function (this: TodoService, p) {
+ *       return this.findOrFail(p.id);
+ *     },
+ *     {
+ *       summary: 'Get a single item by ID',
+ *       tags: ['items'],
+ *       parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+ *       responses: {
+ *         '200': { description: 'The item', content: { 'application/json': { schema: { $ref: '#/components/schemas/Item' } } } },
+ *         '404': { description: 'Not found' },
+ *       },
+ *     },
+ *   ),
+ * }
+ * ```
+ *
+ * @param handler - The service method to annotate.
+ * @param meta    - OpenAPI operation metadata.
+ * @returns The same handler function, with metadata attached.
+ */
+export declare function describe<TInstance extends ServiceInstance = ServiceInstance>(handler: ServiceMethod<TInstance>, meta: OperationMeta): ServiceMethod<TInstance>;
+/**
+ * Generate an OpenAPI 3.1.0 document from a {@link ServiceDefinition}.
+ *
+ * Route handlers that have been annotated with {@link describe} contribute
+ * rich operation metadata (summary, description, parameters, requestBody,
+ * responses).  Unannotated handlers receive sensible defaults automatically.
+ *
+ * The generated document always includes:
+ * - An `ApiError` schema (shape: `{ status?, message?, data? }`) in
+ *   `components.schemas`.
+ * - An `ApiError` response (`500` reference) in `components.responses`.
+ *
+ * Caller-supplied `opts.schemas` and service-level `openapi.schemas` are
+ * deep-merged on top of the built-in components (caller schemas take
+ * precedence over service schemas, which take precedence over built-ins).
+ *
+ * @param service - The service definition to document.
+ * @param opts    - Top-level spec options (title, version, basePath, …).
+ * @returns A fully-formed OpenAPI 3.1.0 document object.
+ *
+ * @example
+ * ```ts
+ * const spec = openApiSpec(todoDefinition, {
+ *   title:    'Todo API',
+ *   version:  '1.0.0',
+ *   basePath: '/api',
+ * });
+ *
+ * app.get('/openapi.json', (_req, res) => {
+ *   res.json(spec);
+ * });
+ * ```
+ */
+export declare function openApiSpec<TInstance extends ServiceInstance = ServiceInstance>(service: ServiceDefinition<TInstance>, opts: SpecOptions): OpenApiDocument;
+declare module './apis.js' {
+    interface ServiceDefinition<TInstance extends ServiceInstance> {
+        /**
+         * Service-level OpenAPI metadata.
+         *
+         * When provided, contributes a default tag (applied to all operations),
+         * reusable schema definitions, and reusable response definitions to the
+         * generated spec document.
+         *
+         * @see {@link OpenApiServiceMeta}
+         */
+        openapi?: OpenApiServiceMeta;
+    }
+}
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

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