@sapporta/rest-open-api 3.52.1 → 3.52.2

package/index.esm.js

@@ -0,0 +1,668 @@
+import { isStandardSchema, isAppRouteOtherResponse, isAppRoute } from '@sapporta/rest-core';
+
+const schemaToParameter = (schema, where, required, key, jsonQuery) => {
+    let description = undefined;
+    if ('description' in schema) {
+        description = schema['description'];
+        delete schema['description'];
+    }
+    let examples = undefined;
+    if ('mediaExamples' in schema) {
+        examples = schema['mediaExamples'];
+        delete schema['mediaExamples'];
+    }
+    const isDeepObject = 'properties' in schema;
+    if (jsonQuery) {
+        return {
+            name: key,
+            in: where,
+            ...(description && { description }),
+            ...(required && { required }),
+            content: {
+                'application/json': {
+                    schema,
+                    ...(examples && { examples }),
+                },
+            },
+        };
+    }
+    else {
+        return {
+            name: key,
+            in: where,
+            ...(examples && { examples }),
+            ...(description && { description }),
+            ...(required && { required }),
+            ...(isDeepObject && !jsonQuery && { style: 'deepObject' }),
+            schema,
+        };
+    }
+};
+/**
+ * Convert a @type {SchemaObject} to an array of @type {ParameterObject}
+ *
+ * @param schema - Zod 4 JSON schema output
+ * @param where - The location of the parameters
+ * @param jsonQuery - Whether the schema is a JSON query
+ * @returns The parameters for the schema
+ */
+const schemaObjectToParameters = (schema, where, jsonQuery = false) => {
+    var _a;
+    const parameters = [];
+    if (schema.type === 'object') {
+        const requiredSet = new Set((_a = schema.required) !== null && _a !== void 0 ? _a : []);
+        const properties = schema.properties;
+        if (!properties) {
+            return [];
+        }
+        for (const [key, value] of Object.entries(properties)) {
+            parameters.push(schemaToParameter(value, where, requiredSet.has(key), key, jsonQuery));
+        }
+    }
+    return parameters;
+};
+
+/**
+ * We build up the params from both the path and the schema.
+ *
+ * This builds up the record of name -> parameter object.
+ */
+const getParamsFromPathOnly = (path) => {
+    var _a;
+    const params = new Map();
+    const paramsInPath = ((_a = path.match(/:([^/]+)/g)) === null || _a === void 0 ? void 0 : _a.map((param) => param.slice(1))) || [];
+    for (const param of paramsInPath) {
+        params.set(param, {
+            name: param,
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+        });
+    }
+    return params;
+};
+/**
+ * Should return schema params as priority, and then path params as fallback
+ *
+ * @param pathParams - params inferred from the path i.e. just from the string
+ * @param schemaParams - params from the schema
+ */
+const mergeParams = (pathParams, schemaParams) => {
+    const resultMap = new Map();
+    for (const [name, param] of pathParams.entries()) {
+        resultMap.set(name, param);
+    }
+    for (const [name, param] of schemaParams.entries()) {
+        resultMap.set(name, param);
+    }
+    return Array.from(resultMap.values());
+};
+const syncFunc$4 = ({ transformSchema, appRoute, id, concatenatedPath, }) => {
+    const schema = appRoute.pathParams;
+    const paramsMap = getParamsFromPathOnly(appRoute.path);
+    const transformedSchema = transformSchema({
+        schema,
+        appRoute,
+        id,
+        concatenatedPath,
+        type: 'path',
+    });
+    if (!transformedSchema) {
+        return Array.from(paramsMap.values());
+    }
+    const schemaParams = schemaObjectToParameters(transformedSchema, 'path');
+    const schemaParamsMap = new Map(schemaParams.map((param) => [param.name, param]));
+    return mergeParams(paramsMap, schemaParamsMap);
+};
+const asyncFunc$4 = async ({ transformSchema, appRoute, id, concatenatedPath, }) => {
+    const schema = appRoute.pathParams;
+    const paramsMap = getParamsFromPathOnly(appRoute.path);
+    const transformedSchema = await transformSchema({
+        schema,
+        appRoute,
+        id,
+        concatenatedPath,
+        type: 'path',
+    });
+    if (!transformedSchema) {
+        return Array.from(paramsMap.values());
+    }
+    const schemaParams = schemaObjectToParameters(transformedSchema, 'path');
+    const schemaParamsMap = new Map(schemaParams.map((param) => [param.name, param]));
+    return mergeParams(paramsMap, schemaParamsMap);
+};
+const getPathParameterSchema = {
+    sync: syncFunc$4,
+    async: asyncFunc$4,
+};
+
+const syncFunc$3 = ({ transformSchema, appRoute, id, concatenatedPath, }) => {
+    const schema = appRoute.headers;
+    if (schema === null) {
+        return [];
+    }
+    if (schema === undefined) {
+        return [];
+    }
+    if (typeof schema === 'symbol') {
+        return [];
+    }
+    if (isStandardSchema(schema)) {
+        const transformedSchema = transformSchema({
+            schema,
+            appRoute,
+            id,
+            concatenatedPath,
+            type: 'header',
+        });
+        if (!transformedSchema) {
+            return [];
+        }
+        return schemaObjectToParameters(transformedSchema, 'header');
+    }
+    const parameters = [];
+    for (const [key, subSchema] of Object.entries(schema)) {
+        if (isStandardSchema(subSchema)) {
+            const transformedSchema = transformSchema({
+                schema: subSchema,
+                appRoute,
+                id,
+                concatenatedPath,
+                type: 'header',
+            });
+            if (!transformedSchema) {
+                return [];
+            }
+            parameters.push(...schemaObjectToParameters(transformedSchema, 'header'));
+        }
+    }
+    return parameters;
+};
+const asyncFunc$3 = async ({ transformSchema, appRoute, id, concatenatedPath, }) => {
+    var _a;
+    const schema = appRoute.headers;
+    if (schema === null) {
+        return [];
+    }
+    if (schema === undefined) {
+        return [];
+    }
+    if (typeof schema === 'symbol') {
+        return [];
+    }
+    if (isStandardSchema(schema)) {
+        const transformedSchema = await transformSchema({
+            schema,
+            appRoute,
+            id,
+            concatenatedPath,
+            type: 'header',
+        });
+        if (!transformedSchema) {
+            return [];
+        }
+        return schemaObjectToParameters(transformedSchema, 'header');
+    }
+    const parameters = [];
+    for (const [key, subSchema] of Object.entries(schema)) {
+        if (isStandardSchema(subSchema)) {
+            const transformedSchema = await transformSchema({
+                schema: subSchema,
+                appRoute,
+                id,
+                concatenatedPath,
+                type: 'header',
+            });
+            if (!transformedSchema) {
+                continue;
+            }
+            const validateEmptyResult = subSchema['~standard'].validate(undefined);
+            if (validateEmptyResult instanceof Promise) {
+                throw new Error('Schema validation must be synchronous');
+            }
+            const isRequired = Boolean((_a = validateEmptyResult.issues) === null || _a === void 0 ? void 0 : _a.length);
+            const asParameter = schemaToParameter(transformedSchema, 'header', isRequired, key, false);
+            parameters.push(asParameter);
+        }
+    }
+    return parameters;
+};
+const getHeaderParameterSchema = {
+    sync: syncFunc$3,
+    async: asyncFunc$3,
+};
+
+const syncFunc$2 = ({ transformSchema, appRoute, id, concatenatedPath, jsonQuery = false, }) => {
+    const schema = appRoute.query;
+    const isSchema = isStandardSchema(schema);
+    if (!isSchema) {
+        return [];
+    }
+    const transformedSchema = transformSchema({
+        schema,
+        appRoute,
+        id,
+        concatenatedPath,
+        type: 'query',
+    });
+    if (!transformedSchema) {
+        return [];
+    }
+    return schemaObjectToParameters(transformedSchema, 'query', jsonQuery);
+};
+const asyncFunc$2 = async ({ transformSchema, appRoute, id, concatenatedPath, jsonQuery = false, }) => {
+    const schema = appRoute.query;
+    const isSchema = isStandardSchema(schema);
+    if (!isSchema) {
+        return [];
+    }
+    const transformedSchema = await transformSchema({
+        schema,
+        appRoute,
+        id,
+        concatenatedPath,
+        type: 'query',
+    });
+    if (!transformedSchema) {
+        return [];
+    }
+    return schemaObjectToParameters(transformedSchema, 'query', jsonQuery);
+};
+const getQueryParameterSchema = {
+    sync: syncFunc$2,
+    async: asyncFunc$2,
+};
+
+const syncFunc$1 = ({ transformSchema, appRoute, id, concatenatedPath, }) => {
+    const schema = 'body' in appRoute ? appRoute.body : undefined;
+    const transformedSchema = transformSchema({
+        schema,
+        appRoute,
+        id,
+        concatenatedPath,
+        type: 'body',
+    });
+    if (!transformedSchema) {
+        return null;
+    }
+    return transformedSchema;
+};
+const asyncFunc$1 = async ({ transformSchema, appRoute, id, concatenatedPath, }) => {
+    const schema = 'body' in appRoute ? appRoute.body : undefined;
+    const transformedSchema = await transformSchema({
+        schema,
+        appRoute,
+        id,
+        concatenatedPath,
+        type: 'body',
+    });
+    return transformedSchema;
+};
+const getBodySchema = {
+    sync: syncFunc$1,
+    async: asyncFunc$1,
+};
+
+/**
+ * Recursively step through the router and get all the individual routes with their paths etc.
+ */
+const getPathsFromRouter = (router, pathHistory) => {
+    const paths = [];
+    Object.keys(router).forEach((key) => {
+        const value = router[key];
+        if (isAppRoute(value)) {
+            const pathWithPathParams = value.path.replace(/:(\w+)/g, '{$1}');
+            paths.push({
+                id: key,
+                path: pathWithPathParams,
+                route: value,
+                paths: pathHistory !== null && pathHistory !== void 0 ? pathHistory : [],
+            });
+        }
+        else {
+            paths.push(...getPathsFromRouter(value, [...(pathHistory !== null && pathHistory !== void 0 ? pathHistory : []), key]));
+        }
+    });
+    return paths;
+};
+const syncFunc = ({ contract, transformSchema, jsonQuery, }) => {
+    const paths = getPathsFromRouter(contract);
+    const results = [];
+    for (const path of paths) {
+        const concatenatedPath = [...path.paths, path.id].join('.');
+        const pathParams = getPathParameterSchema.sync({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+        });
+        const headerParams = getHeaderParameterSchema.sync({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+        });
+        const querySchema = getQueryParameterSchema.sync({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+            jsonQuery: !!jsonQuery,
+        });
+        const bodySchema = getBodySchema.sync({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+        });
+        const responses = {};
+        for (const [statusCode, _response] of Object.entries(path.route.responses)) {
+            const schemaValidator = isAppRouteOtherResponse(_response)
+                ? _response.body
+                : _response;
+            const responseSchema = transformSchema({
+                schema: schemaValidator,
+                appRoute: path.route,
+                id: path.id,
+                concatenatedPath,
+                type: 'response',
+            });
+            if (responseSchema) {
+                responses[statusCode] = responseSchema;
+            }
+        }
+        results.push({
+            ...path,
+            schemaResults: {
+                path: pathParams,
+                headers: headerParams,
+                query: querySchema,
+                body: bodySchema,
+                responses,
+            },
+        });
+    }
+    return results;
+};
+const asyncFunc = async ({ contract, transformSchema, jsonQuery, }) => {
+    const paths = getPathsFromRouter(contract);
+    const results = [];
+    for (const path of paths) {
+        const concatenatedPath = [...path.paths, path.id].join('.');
+        const pathParams = await getPathParameterSchema.async({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+        });
+        const headerParams = await getHeaderParameterSchema.async({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+        });
+        const querySchema = await getQueryParameterSchema.async({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+            jsonQuery: !!jsonQuery,
+        });
+        const bodySchema = await getBodySchema.async({
+            transformSchema,
+            appRoute: path.route,
+            id: path.id,
+            concatenatedPath,
+        });
+        const responses = {};
+        for (const [statusCode, _response] of Object.entries(path.route.responses)) {
+            const schemaValidator = isAppRouteOtherResponse(_response)
+                ? _response.body
+                : _response;
+            const responseSchema = await transformSchema({
+                schema: schemaValidator,
+                appRoute: path.route,
+                id: path.id,
+                concatenatedPath,
+                type: 'response',
+            });
+            if (responseSchema) {
+                responses[statusCode] = responseSchema;
+            }
+        }
+        results.push({
+            ...path,
+            schemaResults: {
+                path: pathParams,
+                headers: headerParams,
+                query: querySchema,
+                body: bodySchema,
+                responses,
+            },
+        });
+    }
+    return results;
+};
+const performContractTraversal = {
+    sync: syncFunc,
+    async: asyncFunc,
+};
+
+const convertSchemaObjectToMediaTypeObject = (input) => {
+    const { mediaExamples: examples, ...schema } = input;
+    return {
+        schema,
+        ...(examples && { examples }),
+    };
+};
+const extractReferenceSchemas = (schema, referenceSchemas) => {
+    var _a, _b, _c;
+    if (schema.allOf) {
+        schema.allOf = (_a = schema.allOf) === null || _a === void 0 ? void 0 : _a.map((subSchema) => extractReferenceSchemas(subSchema, referenceSchemas));
+    }
+    if (schema.anyOf) {
+        schema.anyOf = (_b = schema.anyOf) === null || _b === void 0 ? void 0 : _b.map((subSchema) => extractReferenceSchemas(subSchema, referenceSchemas));
+    }
+    if (schema.oneOf) {
+        schema.oneOf = (_c = schema.oneOf) === null || _c === void 0 ? void 0 : _c.map((subSchema) => extractReferenceSchemas(subSchema, referenceSchemas));
+    }
+    if (schema.not) {
+        schema.not = extractReferenceSchemas(schema.not, referenceSchemas);
+    }
+    if (schema.items) {
+        schema.items = extractReferenceSchemas(schema.items, referenceSchemas);
+    }
+    if (schema.properties) {
+        schema.properties = Object.entries(schema.properties).reduce((prev, [propertyName, schema]) => {
+            prev[propertyName] = extractReferenceSchemas(schema, referenceSchemas);
+            return prev;
+        }, {});
+    }
+    if (schema.additionalProperties) {
+        schema.additionalProperties =
+            typeof schema.additionalProperties != 'boolean'
+                ? extractReferenceSchemas(schema.additionalProperties, referenceSchemas)
+                : schema.additionalProperties;
+    }
+    if (schema.title) {
+        const nullable = schema.nullable;
+        schema.nullable = undefined;
+        if (schema.title in referenceSchemas) {
+            if (JSON.stringify(referenceSchemas[schema.title]) !==
+                JSON.stringify(schema)) {
+                throw new Error(`Schema title '${schema.title}' already exists with a different schema`);
+            }
+        }
+        else {
+            referenceSchemas[schema.title] = schema;
+        }
+        if (nullable) {
+            schema = {
+                nullable: true,
+                allOf: [
+                    {
+                        $ref: `#/components/schemas/${schema.title}`,
+                    },
+                ],
+            };
+        }
+        else {
+            schema = {
+                $ref: `#/components/schemas/${schema.title}`,
+            };
+        }
+    }
+    return schema;
+};
+
+/**
+ * Generate OpenAPI specification from ts-rest router
+ *
+ * @param router - The ts-rest router to generate OpenAPI from
+ * @param apiDoc - Base OpenAPI document configuration
+ * @param options - Generation options
+ * @param options.setOperationId - Whether to set operation IDs (true, false, or 'concatenated-path')
+ * @param options.jsonQuery - Enable JSON query parameters, [see](/docs/open-api#json-query-params)
+ * @param options.operationMapper - Function to customize OpenAPI operations. Receives the operation object, app route, and operation ID
+ * @returns OpenAPI specification object
+ */
+function generateOpenApi(router, apiDoc, options) {
+    const paths = performContractTraversal.sync({
+        contract: router,
+        transformSchema: options === null || options === void 0 ? void 0 : options.schemaTransformer,
+        jsonQuery: !!(options === null || options === void 0 ? void 0 : options.jsonQuery),
+    });
+    return traversedPathsToOpenApi(paths, apiDoc, {
+        setOperationId: options === null || options === void 0 ? void 0 : options.setOperationId,
+        jsonQuery: options === null || options === void 0 ? void 0 : options.jsonQuery,
+        operationMapper: options === null || options === void 0 ? void 0 : options.operationMapper,
+    });
+}
+/**
+ * Generate OpenAPI specification from ts-rest router with custom schema transformer
+ *
+ * @param router - The ts-rest router to generate OpenAPI from
+ * @param apiDoc - Base OpenAPI document configuration
+ * @param options - Generation options
+ * @param options.setOperationId - Whether to set operation IDs (true, false, or 'concatenated-path')
+ * @param options.jsonQuery - Enable JSON query parameters, [see](/docs/open-api#json-query-params)
+ * @param options.operationMapper - Function to customize OpenAPI operations. Receives the operation object, app route, and operation ID
+ * @param options.schemaTransformer - Custom schema transformer function.
+ */
+async function generateOpenApiAsync(router, apiDoc, options) {
+    const paths = await performContractTraversal.async({
+        contract: router,
+        transformSchema: options.schemaTransformer,
+        jsonQuery: !!options.jsonQuery,
+    });
+    return traversedPathsToOpenApi(paths, apiDoc, {
+        setOperationId: options.setOperationId,
+        jsonQuery: options.jsonQuery,
+        operationMapper: options.operationMapper,
+    });
+}
+/**
+ * Inner function to be reused by both sync and async functions
+ */
+const traversedPathsToOpenApi = (paths, apiDoc, options) => {
+    var _a, _b, _c;
+    const mapMethod = {
+        GET: 'get',
+        POST: 'post',
+        PUT: 'put',
+        DELETE: 'delete',
+        PATCH: 'patch',
+    };
+    const operationIds = new Map();
+    const referenceSchemas = {};
+    const pathObject = {};
+    for (const path of paths) {
+        if (options.setOperationId === true) {
+            const existingOp = operationIds.get(path.id);
+            if (existingOp) {
+                throw new Error(`Route '${path.id}' already defined under ${existingOp.join('.')}`);
+            }
+            operationIds.set(path.id, path.paths);
+        }
+        const _bodySchema = path.schemaResults.body;
+        const bodySchema = _bodySchema && typeof _bodySchema === 'object' && 'title' in _bodySchema
+            ? extractReferenceSchemas(path.schemaResults.body, referenceSchemas)
+            : path.schemaResults.body;
+        const responses = {};
+        for (const [statusCode, response] of Object.entries(path.route.responses)) {
+            const contentType = isAppRouteOtherResponse(response)
+                ? response.contentType
+                : 'application/json';
+            const responseSchemaObject = path.schemaResults.responses[statusCode];
+            const responseSchemaObjectWithReferences = responseSchemaObject
+                ? extractReferenceSchemas(responseSchemaObject, referenceSchemas)
+                : null;
+            responses[statusCode] = {
+                ...(responseSchemaObjectWithReferences
+                    ? {
+                        content: {
+                            [contentType]: {
+                                ...convertSchemaObjectToMediaTypeObject(responseSchemaObjectWithReferences),
+                            },
+                        },
+                    }
+                    : {}),
+            };
+        }
+        const contentType = ((_a = path.route) === null || _a === void 0 ? void 0 : _a.method) !== 'GET' && 'contentType' in path.route
+            ? (_c = (_b = path.route) === null || _b === void 0 ? void 0 : _b.contentType) !== null && _c !== void 0 ? _c : 'application/json'
+            : 'application/json';
+        const pathOperation = {
+            description: path.route.description,
+            summary: path.route.summary,
+            deprecated: path.route.deprecated,
+            tags: path.paths,
+            parameters: [
+                ...path.schemaResults.path,
+                ...path.schemaResults.headers,
+                ...path.schemaResults.query,
+            ],
+            ...(options.setOperationId
+                ? {
+                    operationId: options.setOperationId === 'concatenated-path'
+                        ? [...path.paths, path.id].join('.')
+                        : path.id,
+                }
+                : {}),
+            ...(bodySchema
+                ? {
+                    requestBody: {
+                        description: 'Body',
+                        content: {
+                            [contentType]: {
+                                ...convertSchemaObjectToMediaTypeObject(bodySchema),
+                            },
+                        },
+                    },
+                }
+                : {}),
+            responses,
+        };
+        pathObject[path.path] = {
+            ...pathObject[path.path],
+            [mapMethod[path.route.method]]: options.operationMapper
+                ? options.operationMapper(pathOperation, path.route, path.id)
+                : pathOperation,
+        };
+    }
+    if (Object.keys(referenceSchemas).length) {
+        apiDoc['components'] = {
+            schemas: {
+                ...referenceSchemas,
+            },
+            ...apiDoc['components'],
+        };
+    }
+    return {
+        openapi: '3.0.2',
+        paths: pathObject,
+        ...apiDoc,
+    };
+};
+
+export { generateOpenApi, generateOpenApiAsync };

package/package.json

@@ -1,21 +1,31 @@
 {
   "name": "@sapporta/rest-open-api",
-  "version": "3.52.1",
+  "version": "3.52.2",
   "description": "Sapporta-maintained ts-rest OpenAPI generator for Zod 4 contracts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/sapporta/sapporta-rest.git",
+    "url": "https://github.com/jasim/sapporta-rest.git",
     "directory": "libs/ts-rest/open-api"
   },
   "license": "MIT",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "main": "./index.cjs.js",
+  "module": "./index.esm.js",
   "dependencies": {
-    "@sapporta/rest-core": "workspace:*",
     "openapi3-ts": "^2.0.2"
   },
-  "peerDependencies": {
+  "devDependencies": {
     "zod": "^4.0.0"
   },
-  "devDependencies": {
+  "peerDependencies": {
+    "@sapporta/rest-core": "~3.52.0",
     "zod": "^4.0.0"
   }
 }

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/ts-rest-open-api';
+export { SchemaTransformer, SchemaTransformerAsync, SchemaTransformerSync, } from './lib/types';