expediate 1.0.5 → 1.0.6

package/dist/cjs/openapi.js

@@ -1,485 +0,0 @@
-/* Copyright 2021 Fabien Bavent
- *
- * Permission is hereby granted, free of charge, to any person obtaining a
- * copy of this software and associated documentation files (the "Software"),
- * to deal in the Software without restriction, including without limitation
- * the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the
- * Software is furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included
- * in all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
- * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
- * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
- * DEALINGS IN THE SOFTWARE.
- */
-'use strict';
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DESCRIBE_META = void 0;
-exports.serializeSpec = serializeSpec;
-exports.describe = describe;
-exports.openApiSpec = openApiSpec;
-// ── YAML serialiser (zero-dependency, block-style) ────────────────────────────
-/**
- * YAML reserved keywords that must be quoted as scalars so that YAML parsers
- * do not interpret them as the corresponding typed values.
- */
-const YAML_KW = new Set([
-    'true', 'false', 'yes', 'no', 'on', 'off', 'null', '~',
-]);
-/**
- * Pattern for "safe" plain scalars: they can be represented without quoting.
- * A scalar is safe when it:
- * - contains only letters, digits, `_`, `-`, `.` or `/`
- * - starts with a letter, `_`, `/`, or `$`
- * - is not a YAML reserved keyword
- * - does not look like a number
- */
-const SAFE_SCALAR = /^[a-zA-Z$_/][a-zA-Z0-9$_\-./]*$/;
-/** Pattern matching integer and floating-point number strings. */
-const LOOKS_LIKE_NUMBER = /^[-+]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$|^0x[0-9a-fA-F]+$|^0o[0-7]+$/;
-/**
- * Serialise a string as a YAML scalar value or key.
- *
- * The string is returned unquoted when it is a valid YAML plain scalar —
- * i.e. it cannot be misinterpreted as another type and does not contain
- * characters that would confuse a YAML parser.
- *
- * Otherwise the value is wrapped in double quotes with control characters,
- * backslashes, and `"` escaped so the output is always valid YAML 1.2.
- *
- * @param s - The string to serialise.
- */
-function yamlString(s) {
-    if (s === '')
-        return '""';
-    const needsQuote = 
-    // Would be misinterpreted as a YAML typed value.
-    YAML_KW.has(s.toLowerCase()) ||
-        LOOKS_LIKE_NUMBER.test(s) ||
-        // Starts with a YAML indicator that has special meaning at the start of a
-        // plain scalar (block context).
-        /^[-?:,[\]{}#&*!|>'"%@`~]/.test(s) ||
-        // Inline sequences that break block-mapping parsing.
-        s.includes(': ') ||
-        s.endsWith(':') ||
-        s.includes(' #') ||
-        // Leading / trailing whitespace.
-        s !== s.trim() ||
-        // Flow indicator characters anywhere — present in path patterns such as
-        // `/items/{id}` and must be quoted to avoid flow-collection ambiguity.
-        /[{}\[\]]/.test(s) ||
-        // Control characters.
-        /[\x00-\x1f\x7f]/.test(s);
-    if (!needsQuote)
-        return s;
-    // Double-quoted style: always valid, handles all edge cases.
-    return '"' +
-        s
-            .replace(/\\/g, '\\\\')
-            .replace(/"/g, '\\"')
-            .replace(/\n/g, '\\n')
-            .replace(/\r/g, '\\r')
-            .replace(/\t/g, '\\t')
-            .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`)
-        + '"';
-}
-/**
- * Serialise a mapping key as a YAML scalar.
- *
- * Uses the same quoting rules as {@link yamlString}.  Numbers as keys
- * (e.g. HTTP status codes `200`, `500`) are always quoted so that YAML
- * parsers do not interpret them as integer keys.
- */
-function yamlKey(key) {
-    return yamlString(key);
-}
-/**
- * Recursively serialise a JSON-compatible value into an array of YAML block
- * notation lines.
- *
- * Each returned line has **no leading indentation** — it is the caller's
- * responsibility to prefix nested lines with `'  '` (two spaces) when
- * embedding them inside a mapping value or sequence item.
- *
- * @param value - The value to serialise.
- */
-function toYamlLines(value) {
-    // ── Scalars ─────────────────────────────────────────────────────────────────
-    if (value === null || value === undefined)
-        return ['null'];
-    if (typeof value === 'boolean')
-        return [String(value)];
-    if (typeof value === 'number')
-        return [isFinite(value) ? String(value) : '.inf'];
-    if (typeof value === 'string')
-        return [yamlString(value)];
-    // ── Sequences ────────────────────────────────────────────────────────────────
-    if (Array.isArray(value)) {
-        if (value.length === 0)
-            return ['[]'];
-        const lines = [];
-        for (const item of value) {
-            const itemLines = toYamlLines(item);
-            // First line of the item goes on the same line as the dash.
-            lines.push(`- ${itemLines[0]}`);
-            // Subsequent lines are indented by two spaces (relative to the `-`).
-            for (const l of itemLines.slice(1))
-                lines.push(`  ${l}`);
-        }
-        return lines;
-    }
-    // ── Mappings ─────────────────────────────────────────────────────────────────
-    if (typeof value === 'object') {
-        const obj = value;
-        const entries = Object.entries(obj).filter(([, v]) => v !== undefined);
-        if (entries.length === 0)
-            return ['{}'];
-        const lines = [];
-        for (const [key, val] of entries) {
-            const k = yamlKey(key);
-            const valLines = toYamlLines(val);
-            // Inline only when the value is a scalar, null, or an empty collection
-            // (`{}` / `[]`).  Non-empty objects and arrays — even when they happen
-            // to serialise to a single line (e.g. `$ref: "#/..."`) — must go block
-            // style; inlining them produces ambiguous YAML like `key: $ref: "..."`.
-            const isComplex = typeof val === 'object' && val !== null;
-            const isEmptyCollection = valLines.length === 1 &&
-                (valLines[0] === '{}' || valLines[0] === '[]');
-            if (!isComplex || isEmptyCollection) {
-                // Scalar or empty collection: fits on the same line as the key.
-                lines.push(`${k}: ${valLines[0]}`);
-            }
-            else {
-                // Block style: key on its own line, value indented below.
-                lines.push(`${k}:`);
-                for (const l of valLines)
-                    lines.push(`  ${l}`);
-            }
-        }
-        return lines;
-    }
-    return [String(value)];
-}
-/**
- * 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).
- */
-function serializeSpec(doc, format = 'json') {
-    if (format === 'yaml')
-        return toYamlLines(doc).join('\n') + '\n';
-    return JSON.stringify(doc, null, 2);
-}
-// ---------------------------------------------------------------------------
-// Symbol for attaching metadata to handler functions
-// ---------------------------------------------------------------------------
-/**
- * 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.
- */
-exports.DESCRIBE_META = Symbol('expediate.openapi.meta');
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * 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.
- */
-function describe(handler, meta) {
-    // Wrap the handler so we have a fresh function object to attach metadata to,
-    // avoiding unexpected mutations of functions shared across route maps.
-    const described = function (params, body) {
-        return handler.apply(this, [params, body]);
-    };
-    // Attach metadata as a non-enumerable property so it is invisible to
-    // Object.keys() / JSON.stringify() and does not pollute the function's
-    // "own" enumerable surface.
-    Object.defineProperty(described, exports.DESCRIBE_META, {
-        value: meta,
-        enumerable: false,
-        configurable: true,
-        writable: false,
-    });
-    return described;
-}
-// ---------------------------------------------------------------------------
-// Internal path-translation helpers
-// ---------------------------------------------------------------------------
-/**
- * Convert an Express-style path pattern to an OpenAPI path pattern.
- *
- * - `:param` segments become `{param}`.
- * - An optional `basePath` prefix is prepended (with duplicate-slash guards).
- *
- * @example
- * ```ts
- * toOpenApiPath('/items/:id', '/api/v1') // → '/api/v1/items/{id}'
- * toOpenApiPath('/items',     '')         // → '/items'
- * ```
- */
-function toOpenApiPath(pattern, basePath) {
-    const converted = pattern.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, '{$1}');
-    if (!basePath)
-        return converted;
-    const base = basePath.replace(/\/+$/, '');
-    const path = converted.replace(/^\/+/, '/');
-    return base + (path.startsWith('/') ? path : `/${path}`);
-}
-/**
- * Extract named path parameters from an Express-style pattern as
- * {@link ParameterObject} entries with `in: 'path'` and `required: true`.
- *
- * Parameters already listed in `annotated` (by name) are skipped to avoid
- * duplicates when the caller has provided explicit metadata for them.
- *
- * @param pattern   - Express-style route pattern (e.g. `/items/:id`).
- * @param annotated - Explicit parameters provided by the caller (may be empty).
- */
-function extractPathParams(pattern, annotated) {
-    const annotatedNames = new Set(annotated.map(p => p.name));
-    const params = [];
-    for (const match of pattern.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
-        const name = match[1];
-        if (!annotatedNames.has(name)) {
-            params.push({
-                name,
-                in: 'path',
-                required: true,
-                schema: { type: 'string' },
-            });
-        }
-    }
-    return params;
-}
-/**
- * Build an `operationId` string from an HTTP verb and a path pattern.
- *
- * The algorithm:
- * 1. Lowercase the verb (e.g. `'GET'` → `'get'`).
- * 2. Split the pattern on `/` and `:` (and `{` / `}` for pre-translated paths).
- * 3. CamelCase each non-empty segment (first-letter uppercase).
- * 4. Prefix each path-param segment with `'By'`.
- * 5. Join everything into a single camelCase string.
- *
- * @example
- * ```ts
- * buildOperationId('GET',    '/items')     // → 'getItems'
- * buildOperationId('GET',    '/items/:id') // → 'getItemsById'
- * buildOperationId('DELETE', '/a/:b/:c')   // → 'deleteAByBByC'
- * ```
- */
-function buildOperationId(verb, pattern) {
-    const parts = pattern.split(/[/:{} ]+/).filter(Boolean);
-    let result = verb.toLowerCase();
-    for (const part of parts) {
-        const isParam = pattern.includes(`:${part}`) || pattern.includes(`{${part}}`);
-        const pascal = part.charAt(0).toUpperCase() + part.slice(1);
-        result += isParam ? `By${pascal}` : pascal;
-    }
-    return result;
-}
-/**
- * Build the default responses for an operation when none are provided by the
- * caller.
- *
- * - `POST` → `201 No Content` (successful write with no response body).
- * - All other verbs → `200 OK` with a generic JSON response.
- * - `500` → always added as a reference to the built-in `ApiError` component.
- */
-function buildDefaultResponses(verb) {
-    const ok = verb === 'POST'
-        ? { description: 'Created' }
-        : { description: 'OK', content: { 'application/json': {} } };
-    return {
-        [verb === 'POST' ? '201' : '200']: ok,
-        '500': { $ref: '#/components/responses/ApiError' },
-    };
-}
-/**
- * Convert caller-provided `responses` metadata into the OpenAPI responses
- * map, injecting the built-in `ApiError` reference for `500` unless the
- * caller has explicitly provided one.
- */
-function buildAnnotatedResponses(responses) {
-    const result = { ...responses };
-    if (!result['500']) {
-        result['500'] = { $ref: '#/components/responses/ApiError' };
-    }
-    return result;
-}
-// ---------------------------------------------------------------------------
-// Core spec generator
-// ---------------------------------------------------------------------------
-/** The five HTTP verbs supported by `apiBuilder`. */
-const VERBS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
-/**
- * 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);
- * });
- * ```
- */
-function openApiSpec(service, opts) {
-    const basePath = opts.basePath ?? '';
-    const svcMeta = service.openapi;
-    const defaultTag = svcMeta?.tag;
-    // ── Components ──────────────────────────────────────────────────────────────
-    const builtinSchemas = {
-        ApiError: {
-            type: 'object',
-            properties: {
-                status: { type: 'integer', description: 'HTTP status code' },
-                message: { type: 'string', description: 'Human-readable error message' },
-                data: { description: 'Structured error payload (overrides message when present)' },
-            },
-        },
-    };
-    const builtinResponses = {
-        ApiError: {
-            description: 'API error response',
-            content: {
-                'application/json': { schema: { $ref: '#/components/schemas/ApiError' } },
-            },
-        },
-    };
-    // Merge schemas: built-ins ← service-level ← caller-level (last wins).
-    const schemas = {
-        ...builtinSchemas,
-        ...svcMeta?.schemas,
-        ...opts.schemas,
-    };
-    const responses = {
-        ...builtinResponses,
-        ...svcMeta?.responses,
-    };
-    // ── Tags ─────────────────────────────────────────────────────────────────────
-    const tags = [];
-    if (defaultTag) {
-        tags.push({ name: defaultTag, description: svcMeta?.tagDescription });
-    }
-    // ── Paths ────────────────────────────────────────────────────────────────────
-    const paths = {};
-    for (const verb of VERBS) {
-        const routeMap = service[verb];
-        if (!routeMap)
-            continue;
-        for (const [pattern, handler] of Object.entries(routeMap)) {
-            const openApiPath = toOpenApiPath(pattern, basePath);
-            if (!paths[openApiPath])
-                paths[openApiPath] = {};
-            // Retrieve attached metadata (if any).
-            const meta = handler[exports.DESCRIBE_META];
-            // ── Parameters ─────────────────────────────────────────────────────────
-            const annotatedParams = meta?.parameters ?? [];
-            const inferredParams = extractPathParams(pattern, annotatedParams);
-            const parameters = [...annotatedParams, ...inferredParams];
-            // ── Responses ──────────────────────────────────────────────────────────
-            const operationResponses = meta?.responses
-                ? buildAnnotatedResponses(meta.responses)
-                : buildDefaultResponses(verb);
-            // ── Operation object ───────────────────────────────────────────────────
-            const operation = {
-                operationId: meta?.operationId ?? buildOperationId(verb, pattern),
-                ...(meta?.summary && { summary: meta.summary }),
-                ...(meta?.description && { description: meta.description }),
-                ...(meta?.deprecated && { deprecated: true }),
-                ...(parameters.length > 0 && { parameters }),
-                ...(meta?.requestBody && { requestBody: meta.requestBody }),
-                responses: operationResponses,
-            };
-            // Apply default tag when the operation has no explicit tags.
-            const opTags = meta?.tags ?? (defaultTag ? [defaultTag] : undefined);
-            if (opTags)
-                operation['tags'] = opTags;
-            // Carry through any vendor extensions (x-* keys).
-            if (meta) {
-                for (const [k, v] of Object.entries(meta)) {
-                    if (k.startsWith('x-'))
-                        operation[k] = v;
-                }
-            }
-            paths[openApiPath][verb.toLowerCase()] = operation;
-        }
-    }
-    // ── Assemble document ────────────────────────────────────────────────────────
-    const doc = {
-        openapi: '3.1.0',
-        info: {
-            title: opts.title,
-            version: opts.version,
-            ...(opts.description && { description: opts.description }),
-        },
-        ...(opts.servers && { servers: opts.servers }),
-        ...(tags.length > 0 && { tags }),
-        paths,
-        components: { schemas, responses },
-    };
-    return doc;
-}