vovk 3.4.0 → 3.5.0

package/dist/internal.d.ts

@@ -5,6 +5,7 @@ export { withValidationLibrary } from './validation/withValidationLibrary.js';
 export { validationSchemasObjectToSingleValidationSchema } from './validation/validationSchemasObjectToSingleValidationSchema.js';
 export { operation } from './openapi/operation.js';
 export { openAPIToVovkSchema } from './openapi/openAPIToVovkSchema/index.js';
+export { applyComponentsSchemas, reattachMixinDefs, } from './openapi/openAPIToVovkSchema/applyComponentsSchemas.js';
 export { vovkSchemaToOpenAPI } from './openapi/vovkSchemaToOpenAPI.js';
 export { readableStreamToAsyncIterable } from './client/defaultStreamHandler.js';
 export { VovkSchemaIdEnum } from './types/enums.js';

package/dist/internal.js

@@ -6,6 +6,7 @@ export { withValidationLibrary } from './validation/withValidationLibrary.js';
 export { validationSchemasObjectToSingleValidationSchema } from './validation/validationSchemasObjectToSingleValidationSchema.js';
 export { operation } from './openapi/operation.js';
 export { openAPIToVovkSchema } from './openapi/openAPIToVovkSchema/index.js';
+export { applyComponentsSchemas, reattachMixinDefs, } from './openapi/openAPIToVovkSchema/applyComponentsSchemas.js';
 export { vovkSchemaToOpenAPI } from './openapi/vovkSchemaToOpenAPI.js';
 export { readableStreamToAsyncIterable } from './client/defaultStreamHandler.js';
 export { VovkSchemaIdEnum } from './types/enums.js';

package/dist/openapi/openAPIToVovkSchema/applyComponentsSchemas.d.ts

@@ -1,3 +1,23 @@
 import type { ComponentsObject } from 'openapi3-ts/oas31';
 import type { VovkJSONSchemaBase } from '../../types/json-schema.js';
-export declare function applyComponentsSchemas(schema: VovkJSONSchemaBase, components: ComponentsObject['schemas'], mixinName: string): VovkJSONSchemaBase | VovkJSONSchemaBase[];
+export declare function applyComponentsSchemas(schema: VovkJSONSchemaBase, components: ComponentsObject['schemas'], mixinName: string, 
+/**
+ * true (default): embed the ref closure in `$defs` (self-contained — for AJV + Rust).
+ * false: keep `#/components/schemas/X`, emit no `$defs` (response slots, typed via
+ * `x-tsType`) — avoids the per-handler dup that overflows JSON.stringify on big specs.
+ */
+emitDefs?: boolean): VovkJSONSchemaBase | VovkJSONSchemaBase[];
+/**
+ * Re-attach a response slot's `$defs` closure at render time, for generators that
+ * resolve `$ref` against a self-contained schema (Rust). Pulls components from the
+ * segment's shared meta → identical to the `emitDefs=true` slot. No-op for non-mixin.
+ */
+export declare function reattachMixinDefs(slot: VovkJSONSchemaBase | undefined, segment: {
+    segmentType?: string;
+    segmentName: string;
+    meta?: {
+        openAPIObject?: {
+            components?: ComponentsObject;
+        };
+    };
+}): VovkJSONSchemaBase | VovkJSONSchemaBase[] | undefined;

package/dist/openapi/openAPIToVovkSchema/applyComponentsSchemas.js

@@ -14,14 +14,22 @@ function cloneJSON(obj) {
     }
     return result;
 }
-export function applyComponentsSchemas(schema, components, mixinName) {
+export function applyComponentsSchemas(schema, components, mixinName, 
+/**
+ * true (default): embed the ref closure in `$defs` (self-contained — for AJV + Rust).
+ * false: keep `#/components/schemas/X`, emit no `$defs` (response slots, typed via
+ * `x-tsType`) — avoids the per-handler dup that overflows JSON.stringify on big specs.
+ */
+emitDefs = true) {
     const key = 'components/schemas';
     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 || {};
+    // Initialize $defs only when embedding (self-contained slots).
+    if (emitDefs) {
+        result.$defs = result.$defs || {};
+    }
     // Set to track components we've added to $defs
     const addedComponents = new Set();
     // Process a schema object and replace $refs
@@ -38,18 +46,22 @@ export function applyComponentsSchemas(schema, components, mixinName) {
         if ($ref && typeof $ref === 'string' && $ref.startsWith(`#/${key}/`)) {
             const componentName = $ref.replace(`#/${key}/`, '');
             if (components?.[componentName]) {
-                newObj.$ref = `#/$defs/${componentName}`;
+                // Set `x-tsType` so TS resolves the ref without local `$defs`.
                 newObj['x-tsType'] ??= `Mixins.${upperFirst(camelCase(mixinName))}.${upperFirst(camelCase(componentName))}`;
+                if (emitDefs) {
+                    // Self-contained slot: local $defs + embedded closure.
+                    newObj.$ref = `#/$defs/${componentName}`;
+                    if (!addedComponents.has(componentName)) {
+                        addedComponents.add(componentName);
+                        if (result.$defs) {
+                            result.$defs[componentName] = processSchema(cloneJSON(components[componentName]));
+                        }
+                    }
+                }
+                // emitDefs === false: keep `#/components/schemas/X`, no `$defs` (lives once in meta).
             }
             else {
-                delete newObj.$ref; // Remove $ref if component not found (Telegram API has Type $refs that is not defined in components)
-            }
-            // Add the component to $defs if not already added
-            if (!addedComponents.has(componentName) && components?.[componentName]) {
-                addedComponents.add(componentName);
-                if (result.$defs) {
-                    result.$defs[componentName] = processSchema(cloneJSON(components[componentName]));
-                }
+                delete newObj.$ref; // $ref to a component not in components (e.g. Telegram API)
             }
         }
         // Process properties recursively
@@ -63,3 +75,16 @@ export function applyComponentsSchemas(schema, components, mixinName) {
     // Process the main schema
     return processSchema(result);
 }
+/**
+ * Re-attach a response slot's `$defs` closure at render time, for generators that
+ * resolve `$ref` against a self-contained schema (Rust). Pulls components from the
+ * segment's shared meta → identical to the `emitDefs=true` slot. No-op for non-mixin.
+ */
+export function reattachMixinDefs(slot, segment) {
+    if (!slot || segment?.segmentType !== 'mixin')
+        return slot;
+    const components = segment.meta?.openAPIObject?.components?.schemas;
+    if (!components)
+        return slot;
+    return applyComponentsSchemas(slot, components, segment.segmentName, true);
+}

package/dist/openapi/openAPIToVovkSchema/index.d.ts

@@ -1,5 +1,5 @@
 import type { VovkSchema } from '../../types/core.js';
 import type { VovkOpenAPIMixinNormalized } from '../../types/config.js';
-export declare function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName, getMethodName, errorMessageKey, segmentName, }: VovkOpenAPIMixinNormalized & {
+export declare function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName, getMethodName, filterOperations, pruneComponents, errorMessageKey, segmentName, }: VovkOpenAPIMixinNormalized & {
     segmentName?: string;
 }): VovkSchema;

package/dist/openapi/openAPIToVovkSchema/index.js

@@ -1,5 +1,6 @@
 import { applyComponentsSchemas } from './applyComponentsSchemas.js';
 import { inlineRefs } from './inlineRefs.js';
+import { pruneComponentsSchemas } from './pruneComponentsSchemas.js';
 import { VovkSchemaIdEnum } from '../../types/enums.js';
 import { schemaToTsType } from '../../samples/schemaToTsType.js';
 function getTsTypeString(contentType, schema) {
@@ -19,7 +20,7 @@ function getTsTypeString(contentType, schema) {
     }));
     return [...tsTypes].join(' | ') || schemaToTsType(schema);
 }
-export function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName, getMethodName, errorMessageKey, segmentName, }) {
+export function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName, getMethodName, filterOperations, pruneComponents, errorMessageKey, segmentName, }) {
     segmentName = segmentName ?? '';
     const forceApiRoot = apiRoot ||
         (openAPIObject.servers?.[0]?.url ??
@@ -47,10 +48,19 @@ export function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }
         },
     };
     const segment = schema.segments[segmentName];
-    return Object.entries(paths ?? {}).reduce((acc, [path, operations]) => {
+    Object.entries(paths ?? {}).forEach(([path, operations]) => {
         Object.entries(operations ?? {})
             .filter(([, operation]) => operation && typeof operation === 'object')
             .forEach(([method, operation]) => {
+            if (filterOperations &&
+                !filterOperations({
+                    method: method.toUpperCase(),
+                    path,
+                    openAPIObject,
+                    operationObject: operation,
+                })) {
+                return;
+            }
             const rpcModuleName = getModuleName({
                 method: method.toUpperCase(),
                 path,
@@ -140,14 +150,30 @@ export function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }
                         body: applyComponentsSchemas(body, componentsSchemas, segmentName),
                     }),
                     ...(output && {
-                        output: applyComponentsSchemas(output, componentsSchemas, segmentName),
+                        // Response slot: not validated + typed via x-tsType → skip $defs (dedup).
+                        output: applyComponentsSchemas(output, componentsSchemas, segmentName, false),
                     }),
                     ...(iteration && {
-                        iteration: applyComponentsSchemas(iteration, componentsSchemas, segmentName),
+                        iteration: applyComponentsSchemas(iteration, componentsSchemas, segmentName, false),
                     }),
                 },
             };
         });
-        return acc;
-    }, schema);
+    });
+    if (pruneComponents && noPathsOpenAPIObject.components?.schemas) {
+        // Reassign with fresh objects only — `noPathsOpenAPIObject` shares references with the
+        // caller's spec, so the original `components.schemas` must stay untouched. Walking the
+        // whole controllers tree (validation slots + raw operation objects) keeps every `$ref`
+        // a kept handler carries resolvable against the pruned meta.
+        segment.meta = {
+            openAPIObject: {
+                ...noPathsOpenAPIObject,
+                components: {
+                    ...noPathsOpenAPIObject.components,
+                    schemas: pruneComponentsSchemas(segment.controllers, noPathsOpenAPIObject.components.schemas),
+                },
+            },
+        };
+    }
+    return schema;
 }

package/dist/openapi/openAPIToVovkSchema/pruneComponentsSchemas.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentsObject } from 'openapi3-ts/oas31';
+/**
+ * Shrinks a `components.schemas` dict to the transitive `$ref` closure of `roots`
+ * (BFS with a visited set — component graphs of large specs like Stripe are cyclic).
+ * Preserves the original key order for deterministic output.
+ */
+export declare function pruneComponentsSchemas(roots: unknown, componentsSchemas: NonNullable<ComponentsObject['schemas']>): NonNullable<ComponentsObject['schemas']>;

package/dist/openapi/openAPIToVovkSchema/pruneComponentsSchemas.js

@@ -0,0 +1,51 @@
+// Collect the trailing name of every `$ref` in the tree. Covers both pointer styles
+// the transform emits: `#/components/schemas/X` (response slots, raw operation objects)
+// and `#/$defs/X` (request slots embed components under their original names).
+function collectRefNames(node, into) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            collectRefNames(item, into);
+        }
+        return;
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key === '$ref' && typeof value === 'string') {
+            const name = value.split('/').pop();
+            if (name)
+                into.add(name);
+        }
+        else {
+            collectRefNames(value, into);
+        }
+    }
+}
+/**
+ * Shrinks a `components.schemas` dict to the transitive `$ref` closure of `roots`
+ * (BFS with a visited set — component graphs of large specs like Stripe are cyclic).
+ * Preserves the original key order for deterministic output.
+ */
+export function pruneComponentsSchemas(roots, componentsSchemas) {
+    const required = new Set();
+    collectRefNames(roots, required);
+    const queue = [...required];
+    const visited = new Set();
+    while (queue.length) {
+        const name = queue.pop();
+        if (!name || visited.has(name))
+            continue;
+        visited.add(name);
+        const component = componentsSchemas[name];
+        if (!component)
+            continue;
+        const refs = new Set();
+        collectRefNames(component, refs);
+        for (const ref of refs) {
+            required.add(ref);
+            if (!visited.has(ref))
+                queue.push(ref);
+        }
+    }
+    return Object.fromEntries(Object.entries(componentsSchemas).filter(([name]) => required.has(name)));
+}

package/dist/types/config.d.ts

@@ -88,6 +88,17 @@ export interface VovkOpenAPIMixin {
     apiRoot?: string;
     getModuleName?: 'nestjs-operation-id' | (string & {}) | 'api' | GetOpenAPINameFn;
     getMethodName?: 'nestjs-operation-id' | 'camel-case-operation-id' | 'auto' | GetOpenAPINameFn;
+    /**
+     * Keep only operations the predicate returns `true` for; omitted = keep all. Runs before
+     * `getModuleName`/`getMethodName`, so a module whose operations are all filtered out is never created.
+     */
+    filterOperations?: (config: Parameters<GetOpenAPINameFn>[0]) => boolean;
+    /**
+     * Prune `meta.openAPIObject.components.schemas` to the transitive `$ref` closure of the kept operations,
+     * shrinking the generated schema for large specs. Removes `Mixins.<Segment>.<Component>` types for
+     * components nothing kept references — keep `false` (default) if you import such types directly.
+     */
+    pruneComponents?: boolean;
     errorMessageKey?: string;
     mixinName?: string;
 }

package/package.json

@@ -7,7 +7,7 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "bin": {
     "vovk-cli-npx": "./bin/index.mjs"
   },