vovk 3.0.0-draft.21 → 3.0.0-draft.211

package/mjs/openapi/openAPIToVovkSchema.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAPIToVovkSchema = openAPIToVovkSchema;
+const types_1 = require("../types");
+const generateFnName_1 = require("./generateFnName");
+const camelCase_1 = require("../utils/camelCase");
+// fast clone JSON object while ignoring Date, RegExp, and Function types
+function cloneJSON(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(cloneJSON);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value instanceof Date || value instanceof RegExp || typeof value === 'function')
+            continue;
+        result[key] = cloneJSON(value);
+    }
+    return result;
+}
+function applyComponents(schema, components) {
+    if (!components || !Object.keys(components).length)
+        return schema;
+    // Create a deep copy of the schema
+    const result = cloneJSON(schema);
+    // Initialize $defs if it doesn't exist
+    result.$defs = result.$defs || {};
+    // Set to track components we've added to $defs
+    const addedComponents = new Set();
+    // Process a schema object and replace $refs
+    function processSchema(obj) {
+        if (!obj || typeof obj !== 'object')
+            return obj;
+        // Create a new object/array to avoid modifying the input
+        const newObj = Array.isArray(obj) ? [...obj] : { ...obj };
+        // Check for $ref
+        if (newObj.$ref && typeof newObj.$ref === 'string' && newObj.$ref.startsWith('#/components/schemas/')) {
+            const componentName = newObj.$ref.replace('#/components/schemas/', '');
+            newObj.$ref = `#/$defs/${componentName}`;
+            // Add the component to $defs if not already added
+            if (!addedComponents.has(componentName) && components[componentName]) {
+                addedComponents.add(componentName);
+                // TODO: IMPORTANT! Deep copy to avoid mutation issues
+                result.$defs[componentName] = processSchema(cloneJSON(components[componentName]));
+            }
+        }
+        // Process properties/items recursively
+        if (Array.isArray(newObj)) {
+            for (let i = 0; i < newObj.length; i++) {
+                newObj[i] = processSchema(newObj[i]);
+            }
+        }
+        else {
+            for (const key in newObj) {
+                if (Object.prototype.hasOwnProperty.call(newObj, key)) {
+                    newObj[key] = processSchema(newObj[key]);
+                }
+            }
+        }
+        return newObj;
+    }
+    // Process the main schema
+    return processSchema(result);
+}
+const getNamesNestJS = (operationObject) => {
+    const operationId = operationObject.operationId;
+    if (!operationId) {
+        throw new Error('Operation ID is required for NestJS module name generation');
+    }
+    const controllerHandlerMatch = operationId?.match(/^([A-Z][a-zA-Z0-9]*)_([a-zA-Z0-9_]+)/);
+    if (!controllerHandlerMatch) {
+        throw new Error(`Invalid operationId format for NestJS: ${operationId}`);
+    }
+    return controllerHandlerMatch.slice(1, 3);
+};
+const normalizeGetModuleName = (getModuleName) => {
+    if (getModuleName === 'nestjs-operation-id') {
+        getModuleName = (operationObject) => getNamesNestJS(operationObject)[0];
+    }
+    else if (typeof getModuleName === 'string') {
+        const moduleName = getModuleName;
+        getModuleName = () => moduleName;
+    }
+    else if (typeof getModuleName !== 'function') {
+        throw new Error('getModuleName must be a function or one of the predefined strings');
+    }
+    return getModuleName;
+};
+const normalizeGetMethodName = (getMethodName) => {
+    if (getMethodName === 'nestjs-operation-id') {
+        getMethodName = (operationObject) => getNamesNestJS(operationObject)[1];
+    }
+    else if (getMethodName === 'camel-case-operation-id') {
+        getMethodName = ({ operationObject }) => {
+            const operationId = operationObject.operationId;
+            if (!operationId) {
+                throw new Error('Operation ID is required for camel-case method name generation');
+            }
+            return (0, camelCase_1.camelCase)(operationId);
+        };
+    }
+    else if (getMethodName === 'auto') {
+        getMethodName = ({ operationObject, method, path }) => {
+            const operationId = operationObject.operationId;
+            const isSnakeCase = operationId && /^[a-z][a-z0-9_]+$/.test(operationId);
+            return isSnakeCase ? (0, camelCase_1.camelCase)(operationId) : (0, generateFnName_1.generateFnName)(method, path);
+        };
+    }
+    else if (typeof getMethodName !== 'function') {
+        throw new Error('getMethodName must be a function or one of the predefined strings');
+    }
+    return getMethodName;
+};
+function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName = 'api', getMethodName = 'auto', }) {
+    const forceApiRoot = apiRoot ?? openAPIObject.servers?.[0]?.url;
+    if (!forceApiRoot) {
+        throw new Error('API root URL is required in OpenAPI configuration');
+    }
+    const schema = {
+        $schema: types_1.VovkSchemaIdEnum.SCHEMA,
+        segments: {
+            '': {
+                $schema: types_1.VovkSchemaIdEnum.SEGMENT,
+                emitSchema: true,
+                segmentName: '',
+                forceApiRoot,
+                controllers: {},
+            },
+        },
+        meta: {
+            $schema: types_1.VovkSchemaIdEnum.META,
+            config: {
+                $schema: types_1.VovkSchemaIdEnum.CONFIG,
+            },
+            openapi: openAPIObject,
+        },
+    };
+    const segment = schema.segments[''];
+    getModuleName = normalizeGetModuleName(getModuleName);
+    getMethodName = normalizeGetMethodName(getMethodName);
+    return Object.entries(openAPIObject.paths ?? {}).reduce((acc, [path, operations]) => {
+        Object.entries(operations ?? {}).forEach(([method, operation]) => {
+            const rpcModuleName = getModuleName({
+                method: method.toUpperCase(),
+                path,
+                openAPIObject,
+                operationObject: operation,
+            });
+            const handlerName = getMethodName({
+                method: method.toUpperCase(),
+                path,
+                openAPIObject,
+                operationObject: operation,
+            });
+            segment.controllers[rpcModuleName] ??= {
+                rpcModuleName,
+                handlers: {},
+            };
+            // TODO: how to utilize ReferenceObject?
+            const queryProperties = operation.parameters?.filter((p) => p.in === 'query') ?? null;
+            const pathProperties = operation.parameters?.filter((p) => p.in === 'path') ?? null;
+            const query = queryProperties?.length
+                ? {
+                    type: 'object',
+                    properties: Object.fromEntries(queryProperties.map((p) => [p.name, p.schema])),
+                    required: queryProperties.filter((p) => p.required).map((p) => p.name),
+                }
+                : null;
+            const params = pathProperties?.length
+                ? {
+                    type: 'object',
+                    properties: Object.fromEntries(pathProperties.map((p) => [p.name, p.schema])),
+                    required: pathProperties.filter((p) => p.required).map((p) => p.name),
+                }
+                : null;
+            // TODO: how to utilize ReferenceObject?
+            const body = operation.requestBody?.content['application/json']?.schema ?? null;
+            const output = operation.responses?.['200']?.content?.['application/json']?.schema ??
+                operation.responses?.['201']?.content?.['application/json']?.schema ??
+                null;
+            // TODO: "iteration" validation
+            // TODO: FormData
+            segment.controllers[rpcModuleName].handlers[handlerName] = {
+                httpMethod: method.toUpperCase(),
+                path,
+                openapi: operation,
+                validation: {
+                    ...(query && { query: applyComponents(query, openAPIObject.components?.schemas) }),
+                    ...(params && { params: applyComponents(params, openAPIObject.components?.schemas) }),
+                    ...(body && { body: applyComponents(body, openAPIObject.components?.schemas) }),
+                    ...(output && { output: applyComponents(output, openAPIObject.components?.schemas) }),
+                },
+            };
+        });
+        return acc;
+    }, schema);
+}

package/mjs/openapi/vovkSchemaToOpenAPI.d.ts

@@ -0,0 +1,9 @@
+import type { OpenAPIObject } from 'openapi3-ts/oas31';
+import { type CodeSamplePackageJson } from '../utils/createCodeExamples';
+import { type VovkSchema } from '../types';
+export declare function vovkSchemaToOpenAPI({ rootEntry, schema: fullSchema, openAPIObject, package: packageJson, }: {
+    rootEntry: string;
+    schema: VovkSchema;
+    openAPIObject?: Partial<OpenAPIObject>;
+    package?: CodeSamplePackageJson;
+}): OpenAPIObject;

package/mjs/openapi/vovkSchemaToOpenAPI.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vovkSchemaToOpenAPI = vovkSchemaToOpenAPI;
+const json_schema_sampler_1 = require("@stoplight/json-schema-sampler");
+const createCodeExamples_1 = require("../utils/createCodeExamples");
+const types_1 = require("../types");
+function extractComponents(schema) {
+    if (!schema)
+        return [undefined, {}];
+    const components = {};
+    // Function to collect components and replace $refs recursively
+    const process = (obj, path = []) => {
+        if (!obj || typeof obj !== 'object')
+            return obj;
+        // Handle arrays
+        if (Array.isArray(obj)) {
+            return obj.map((item) => process(item, path));
+        }
+        // Create a copy to modify
+        const result = {};
+        Object.entries({ ...obj.definitions, ...obj.$defs }).forEach(([key, value]) => {
+            components[key] = process(value, [...path, key]);
+        });
+        // Process all properties
+        for (const [key, value] of Object.entries(obj ?? {})) {
+            // Skip already processed special properties
+            if (key === '$defs' || key === 'definitions')
+                continue;
+            if (key === '$ref' && typeof value === 'string') {
+                // Extract the component name from the reference
+                const refParts = value.split('/');
+                const refName = refParts[refParts.length - 1];
+                // Replace with component reference
+                result[key] = `#/components/schemas/${refName}`;
+            }
+            else {
+                // Recursively process other properties
+                result[key] = process(value, [...path, key]);
+            }
+        }
+        return result;
+    };
+    const processedSchema = process(schema);
+    return [processedSchema, components];
+}
+function vovkSchemaToOpenAPI({ rootEntry, schema: fullSchema, openAPIObject = {}, package: packageJson = { name: 'vovk-client' }, }) {
+    const paths = {};
+    const components = {};
+    for (const [segmentName, segmentSchema] of Object.entries(fullSchema.segments ?? {})) {
+        for (const c of Object.values(segmentSchema.controllers)) {
+            for (const [handlerName, h] of Object.entries(c.handlers ?? {})) {
+                if (h.openapi) {
+                    const [queryValidation, queryComponents] = extractComponents(h?.validation?.query);
+                    const [bodyValidation, bodyComponents] = extractComponents(h?.validation?.body);
+                    const [paramsValidation, paramsComponents] = extractComponents(h?.validation?.params);
+                    const [outputValidation, outputComponents] = extractComponents(h?.validation?.output);
+                    const [iterationValidation, iterationComponents] = extractComponents(h?.validation?.iteration);
+                    // TODO: Handle name conflicts?
+                    Object.assign(components, queryComponents, bodyComponents, paramsComponents, outputComponents, iterationComponents);
+                    const { ts, rs, py } = (0, createCodeExamples_1.createCodeExamples)({
+                        package: packageJson,
+                        handlerName,
+                        handlerSchema: h,
+                        controllerSchema: c,
+                    });
+                    const queryParameters = queryValidation && 'type' in queryValidation && 'properties' in queryValidation
+                        ? Object.entries(queryValidation.properties ?? {}).map(([propName, propSchema]) => ({
+                            name: propName,
+                            in: 'query',
+                            required: queryValidation.required ? queryValidation.required.includes(propName) : false,
+                            schema: propSchema,
+                        }))
+                        : null;
+                    const pathParameters = paramsValidation && 'type' in paramsValidation && 'properties' in paramsValidation
+                        ? Object.entries(paramsValidation.properties ?? {}).map(([propName, propSchema]) => ({
+                            name: propName,
+                            in: 'path',
+                            required: paramsValidation.required ? paramsValidation.required.includes(propName) : false,
+                            schema: propSchema,
+                        }))
+                        : null;
+                    const path = '/' +
+                        [rootEntry.replace(/^\/+|\/+$/g, ''), segmentName, c.prefix, h.path]
+                            .filter(Boolean)
+                            .join('/')
+                            .replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+                    paths[path] = paths[path] ?? {};
+                    const httpMethod = h.httpMethod.toLowerCase();
+                    paths[path][httpMethod] ??= {};
+                    paths[path][httpMethod] = {
+                        ...h.openapi,
+                        ...paths[path][httpMethod],
+                        'x-codeSamples': [
+                            ...(paths[path][httpMethod]['x-codeSamples'] ?? []),
+                            ...(h.openapi['x-codeSamples'] ?? []),
+                            {
+                                label: 'TypeScript RPC',
+                                lang: 'typescript',
+                                source: ts,
+                            },
+                            {
+                                label: 'Python RPC',
+                                lang: 'python',
+                                source: py,
+                            },
+                            {
+                                label: 'Rust RPC',
+                                lang: 'rust',
+                                source: rs,
+                            },
+                        ],
+                        ...(queryParameters || pathParameters
+                            ? {
+                                parameters: h.openapi.parameters ?? [...(queryParameters || []), ...(pathParameters || [])],
+                            }
+                            : {}),
+                        ...(paths[path][httpMethod].parameters
+                            ? {
+                                parameters: paths[path][httpMethod].parameters,
+                            }
+                            : {}),
+                        ...(outputValidation && 'type' in outputValidation && 'properties' in outputValidation
+                            ? {
+                                responses: {
+                                    200: {
+                                        description: 'description' in outputValidation ? outputValidation.description : 'Success',
+                                        content: {
+                                            'application/json': {
+                                                schema: outputValidation,
+                                            },
+                                        },
+                                    },
+                                    ...h.openapi?.responses,
+                                },
+                            }
+                            : {}),
+                        ...(iterationValidation && 'type' in iterationValidation && 'properties' in iterationValidation
+                            ? {
+                                responses: {
+                                    200: {
+                                        description: 'description' in iterationValidation ? iterationValidation.description : 'JSON Lines response',
+                                        content: {
+                                            'application/jsonl': {
+                                                schema: {
+                                                    ...iterationValidation,
+                                                    examples: iterationValidation.examples ?? [
+                                                        [
+                                                            JSON.stringify((0, json_schema_sampler_1.sample)(iterationValidation)),
+                                                            JSON.stringify((0, json_schema_sampler_1.sample)(iterationValidation)),
+                                                            JSON.stringify((0, json_schema_sampler_1.sample)(iterationValidation)),
+                                                        ].join('\n'),
+                                                    ],
+                                                },
+                                            },
+                                        },
+                                    },
+                                    ...h.openapi?.responses,
+                                },
+                            }
+                            : {}),
+                        ...(paths[path][httpMethod].responses
+                            ? {
+                                responses: paths[path][httpMethod].responses,
+                            }
+                            : {}),
+                        ...(bodyValidation && 'type' in bodyValidation && 'properties' in bodyValidation
+                            ? {
+                                requestBody: h.openapi?.requestBody ?? {
+                                    description: 'description' in bodyValidation ? bodyValidation.description : 'Request body',
+                                    required: true,
+                                    content: {
+                                        'application/json': {
+                                            schema: bodyValidation,
+                                        },
+                                    },
+                                },
+                            }
+                            : {}),
+                        ...(paths[path][httpMethod].requestBody
+                            ? {
+                                requestBody: paths[path][httpMethod].requestBody,
+                            }
+                            : {}),
+                        tags: paths[path][httpMethod].tags ?? h.openapi?.tags,
+                    };
+                }
+            }
+        }
+    }
+    return {
+        ...openAPIObject,
+        openapi: '3.1.0',
+        info: {
+            title: packageJson?.description ?? 'API',
+            version: packageJson?.version ?? '0.0.1',
+            ...openAPIObject?.info,
+        },
+        components: {
+            schemas: {
+                ...(openAPIObject?.components?.schemas ?? components),
+                HttpStatus: {
+                    type: 'integer',
+                    description: 'HTTP status code',
+                    enum: Object.keys(types_1.HttpStatus)
+                        .map((k) => types_1.HttpStatus[k])
+                        .filter(Boolean)
+                        .filter((v) => typeof v === 'number'),
+                },
+                VovkErrorResponse: {
+                    type: 'object',
+                    description: 'Vovk error response',
+                    properties: {
+                        cause: {
+                            description: 'Error cause of any shape',
+                        },
+                        statusCode: {
+                            $ref: '#/components/schemas/HttpStatus',
+                        },
+                        message: {
+                            type: 'string',
+                            description: 'Error message',
+                        },
+                        isError: {
+                            type: 'boolean',
+                            const: true,
+                            description: 'Indicates that this object represents an error',
+                        },
+                    },
+                    required: ['statusCode', 'message', 'isError'],
+                    additionalProperties: false,
+                },
+                ...openAPIObject?.components?.schemas,
+            },
+        },
+        paths,
+    };
+}