vovk 3.7.0 → 4.0.0-beta.0

package/dist/core/json-lines-responder.d.ts

@@ -4,10 +4,7 @@ export declare abstract class Responder {
     response: Response;
 }
 /**
- * A Responder subclass for streaming JSON Lines (JSONL) data.
- * @see https://vovk.dev/jsonlines
- * @param request The incoming Request object.
- * @param getResponse Optional function to create a custom Response object.
+ * Responder subclass for streaming JSON Lines. @see https://vovk.dev/jsonlines
  * @example
  * ```ts
  * import { JSONLinesResponder } from 'vovk';
@@ -16,19 +13,18 @@ export declare abstract class Responder {
  *   return new Response(responder.readableStream, { headers: responder.headers });
  * });
  *
- * // Send items
- * responder.send({ ... });
- * // Close the stream when done
- * responder.close();
- * // Or throw an error
+ * responder.send({ ... }); // send items
+ * responder.close(); // close the stream when done
  * responder.throw(new Error('Something went wrong'));
- * // get the Response object, headers, etc.
  * const { response, headers } = responder;
  * ```
  */
 export declare class JSONLinesResponder<T> extends Responder {
     private isClosed;
     private i;
+    private pendingSends;
+    private sendQueue;
+    private hasSent;
     private controller?;
     private readonly encoder;
     readonly readableStream: ReadableStream | null;
@@ -37,6 +33,6 @@ export declare class JSONLinesResponder<T> extends Responder {
     constructor(request?: Request | null, getResponse?: (responder: JSONLinesResponder<T>) => Response);
     readonly send: (item: T) => Promise<void>;
     sendLineOrError: (data: T | StreamAbortMessage) => void;
-    readonly close: () => void;
-    readonly throw: (e: unknown) => void;
+    readonly close: () => Promise<void>;
+    readonly throw: (e: unknown) => Promise<void>;
 }

package/dist/core/json-lines-responder.js

@@ -3,10 +3,7 @@ export class Responder {
     response;
 }
 /**
- * A Responder subclass for streaming JSON Lines (JSONL) data.
- * @see https://vovk.dev/jsonlines
- * @param request The incoming Request object.
- * @param getResponse Optional function to create a custom Response object.
+ * Responder subclass for streaming JSON Lines. @see https://vovk.dev/jsonlines
  * @example
  * ```ts
  * import { JSONLinesResponder } from 'vovk';
@@ -15,19 +12,19 @@ export class Responder {
  *   return new Response(responder.readableStream, { headers: responder.headers });
  * });
  *
- * // Send items
- * responder.send({ ... });
- * // Close the stream when done
- * responder.close();
- * // Or throw an error
+ * responder.send({ ... }); // send items
+ * responder.close(); // close the stream when done
  * responder.throw(new Error('Something went wrong'));
- * // get the Response object, headers, etc.
  * const { response, headers } = responder;
  * ```
  */
 export class JSONLinesResponder extends Responder {
     isClosed = false;
     i = 0;
+    pendingSends = new Set();
+    // sends are chained so unawaited calls keep their order, see send()
+    sendQueue = Promise.resolve();
+    hasSent = false;
     controller;
     // biome-ignore lint/correctness/noUnusedPrivateClassMembers: biome bug
     encoder;
@@ -63,15 +60,28 @@ export class JSONLinesResponder extends Responder {
         this.controller?.enqueue(encoder?.encode(''));
     }
     send = async (item) => {
+        // chaining keeps lines in call order even when send() is not awaited
+        const promise = this.sendQueue.then(async () => {
+            try {
+                if (!this.hasSent) {
+                    this.hasSent = true;
+                    // zero timeout lets withValidationLibrary set onBeforeSend before the first send,
+                    // otherwise immediate streaming would skip the first iteration validation
+                    await new Promise((resolve) => setTimeout(resolve, 0));
+                }
+                this.sendLineOrError(await this.onBeforeSend(item, this.i++));
+            }
+            catch (e) {
+                this.throw(e);
+            }
+        });
+        this.sendQueue = promise;
+        this.pendingSends.add(promise);
         try {
-            // onBeforeSend is set by withValidationLibrary if iteration validation is provided
-            // in case if data is streamed immediately in a controller/service, we're going to lose the first iteration validation
-            // the await with zero timeout ensures onBeforeSend is set before the first send
-            await new Promise((resolve) => setTimeout(resolve, 0));
-            this.sendLineOrError(await this.onBeforeSend(item, this.i++));
+            await promise;
         }
-        catch (e) {
-            this.throw(e);
+        finally {
+            this.pendingSends.delete(promise);
         }
     };
     sendLineOrError = (data) => {
@@ -80,14 +90,26 @@ export class JSONLinesResponder extends Responder {
             return;
         controller?.enqueue(encoder?.encode(`${JSON.stringify(data)}\n`));
     };
-    close = () => {
-        const { controller } = this;
+    close = async () => {
+        if (this.isClosed)
+            return;
+        // let unawaited send() calls finish first, per the documented send-then-close pattern
+        while (this.pendingSends.size) {
+            await Promise.allSettled([...this.pendingSends]);
+        }
         if (this.isClosed)
             return;
         this.isClosed = true;
-        controller?.close();
+        this.controller?.close();
     };
     throw = (e) => {
+        // same rule as a non streaming handler, an error without a statusCode is internal
+        const isExpected = typeof e?.statusCode === 'number';
+        if (!isExpected && process.env.NODE_ENV === 'production') {
+            console.error('🐺 Unhandled error in a Vovk stream:', e);
+            this.sendLineOrError({ isError: true, reason: 'Internal server error' });
+            return this.close();
+        }
         this.sendLineOrError({ isError: true, reason: e instanceof Error ? e.message : e });
         return this.close();
     };

package/dist/core/vovk-app.d.ts

@@ -1,5 +1,5 @@
+import type { DecoratorOptions, RouteHandler, VovkController } from '../types/core.js';
 import { HttpMethod, HttpStatus } from '../types/enums.js';
-import type { RouteHandler, VovkController, DecoratorOptions } from '../types/core.js';
 declare class VovkApp {
     #private;
     private static getHeadersFromDecoratorOptions;

package/dist/core/vovk-app.js

@@ -1,10 +1,10 @@
 var _a;
-import { HttpException } from './http-exception.js';
-import { JSONLinesResponder, Responder } from './json-lines-responder.js';
-import { reqQuery } from '../req/req-query.js';
+import { parseBody } from '../req/parse-body.js';
 import { reqMeta } from '../req/req-meta.js';
+import { reqQuery } from '../req/req-query.js';
 import { HttpMethod, HttpStatus } from '../types/enums.js';
-import { parseBody } from '../req/parse-body.js';
+import { HttpException } from './http-exception.js';
+import { JSONLinesResponder, Responder } from './json-lines-responder.js';
 class VovkApp {
     static getHeadersFromDecoratorOptions(options) {
         if (!options)
@@ -12,7 +12,8 @@ class VovkApp {
         const corsHeaders = {
             'access-control-allow-origin': '*',
             'access-control-allow-methods': 'GET, POST, PUT, DELETE, OPTIONS, HEAD',
-            'access-control-allow-headers': 'content-type, authorization',
+            // x-meta is ours, the client sends it whenever meta is set
+            'access-control-allow-headers': 'content-type, authorization, x-meta',
         };
         const headers = {
             ...(options.cors ? corsHeaders : {}),
@@ -62,23 +63,29 @@ class VovkApp {
     #routeRegexCache = new Map();
     #routeSegmentsCache = new Map();
     #routeParamPositionsCache = new Map();
-    #routeMatchCache = new Map();
+    // matches are only valid for the handlers map they were resolved against, so scope by its identity
+    #routeMatchCache = new WeakMap();
+    // concrete paths come from the URL, cap the per handlers map cache so it can't grow forever
+    static #ROUTE_MATCH_CACHE_LIMIT = 1000;
     #getHandler = ({ handlers, path, params, }) => {
         let methodParams = {};
         if (Object.keys(params).length === 0) {
             return { handler: handlers[''], methodParams };
         }
+        // a decoded "/" inside one segment makes the joined path ambiguous, /files/a%2Fb vs /files/a/b
+        const hasEncodedSlash = path.some((segment) => segment.includes('/'));
         const pathStr = path.join('/');
         // Fast path: Check if this exact path has been matched before
-        const cachedMatch = this.#routeMatchCache.get(pathStr);
+        let matchCache = hasEncodedSlash ? undefined : this.#routeMatchCache.get(handlers);
+        const cachedMatch = matchCache?.get(pathStr);
         if (cachedMatch) {
             return {
                 handler: handlers[cachedMatch.route],
                 methodParams: cachedMatch.params,
             };
         }
-        // Check for direct static route match
-        let methodKey = handlers[pathStr] ? pathStr : null;
+        // Check for direct static route match, hasOwn so /toString doesn't resolve a prototype member
+        let methodKey = !hasEncodedSlash && Object.hasOwn(handlers, pathStr) ? pathStr : null;
         if (!methodKey) {
             const methodKeys = [];
             const pathLength = path.length;
@@ -140,7 +147,8 @@ class VovkApp {
                         if (!regex) {
                             const regexPattern = routeSegment
                                 .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-                                .replace(/\\{(\w+)\\}/g, '(?<$1>[^/]+)');
+                                // matched per segment, so a decoded "/" from %2F belongs to the value
+                                .replace(/\\{(\w+)\\}/g, '(?<$1>[\\s\\S]+)');
                             regex = new RegExp(`^${regexPattern}$`);
                             this.#routeRegexCache.set(routeSegment, regex);
                         }
@@ -177,9 +185,16 @@ class VovkApp {
                 throw new HttpException(HttpStatus.INTERNAL_SERVER_ERROR, `Conflicting routes found: ${methodKeys.join(', ')}`);
             }
             [methodKey] = methodKeys;
-            // Cache successful matches
-            if (methodKey) {
-                this.#routeMatchCache.set(pathStr, { route: methodKey, params: methodParams });
+            // Cache successful matches, an ambiguous joined path must not become a cache key
+            if (methodKey && !hasEncodedSlash) {
+                if (!matchCache) {
+                    matchCache = new Map();
+                    this.#routeMatchCache.set(handlers, matchCache);
+                }
+                if (matchCache.size >= _a.#ROUTE_MATCH_CACHE_LIMIT) {
+                    matchCache.delete(matchCache.keys().next().value);
+                }
+                matchCache.set(pathStr, { route: methodKey, params: methodParams });
             }
         }
         if (methodKey) {
@@ -217,7 +232,20 @@ class VovkApp {
             headerList = null;
         }
         const xMeta = headerList?.get('x-meta');
-        const xMetaHeader = xMeta && JSON.parse(xMeta);
+        let xMetaHeader = null;
+        if (xMeta) {
+            try {
+                xMetaHeader = JSON.parse(xMeta);
+            }
+            catch {
+                // malformed client input is a 400, not an uncaught SyntaxError
+                return this.#respondWithError({
+                    req,
+                    statusCode: HttpStatus.BAD_REQUEST,
+                    message: 'Invalid x-meta request header',
+                });
+            }
+        }
         if (xMetaHeader)
             reqMeta(req, { xMetaHeader });
         const { handler, methodParams } = this.#getHandler({ handlers, path, params });
@@ -240,7 +268,8 @@ class VovkApp {
         try {
             await staticMethod._options?.before?.call(controller, req);
             await onBefore?.(req);
-            const result = await staticMethod.call(controller, req, methodParams);
+            // dispatch via the latest wrapper so decorators applied above the HTTP decorator still run
+            const result = await (staticMethod._sourceMethod?.wrapper ?? staticMethod).call(controller, req, methodParams);
             if (result instanceof Response) {
                 await onSuccess?.(result, req);
                 // set headers from decorator options
@@ -279,6 +308,13 @@ class VovkApp {
                         }
                     }
                     catch (e) {
+                        // the outer catch already returned the response, so onError has to run here
+                        try {
+                            await controller._onError?.(e, req);
+                        }
+                        catch (onErrorError) {
+                            console.error('An error caught in onError handler:', onErrorError);
+                        }
                         return responder.throw(e);
                     }
                     return responder.close();
@@ -296,11 +332,21 @@ class VovkApp {
                 await controller._onError?.(err, req);
             }
             catch (onErrorError) {
-                // eslint-disable-next-line no-console
                 console.error('An error caught in onError handler:', onErrorError);
             }
             if (err.message !== 'NEXT_REDIRECT' && err.message !== 'NEXT_NOT_FOUND') {
                 const statusCode = err.statusCode || HttpStatus.INTERNAL_SERVER_ERROR;
+                // an error without a statusCode is internal, its message and cause stay on the server in production
+                const isExpected = typeof err.statusCode === 'number';
+                if (!isExpected && process.env.NODE_ENV === 'production') {
+                    console.error('🐺 Unhandled error in a Vovk handler:', err);
+                    return this.#respondWithError({
+                        req,
+                        statusCode,
+                        message: 'Internal server error',
+                        options: staticMethod._options,
+                    });
+                }
                 return this.#respondWithError({
                     req,
                     statusCode,

package/dist/index.d.ts

@@ -1,26 +1,24 @@
-export { HttpException } from './core/http-exception.js';
-export { createDecorator } from './core/create-decorator.js';
+export { createFetcher, fetcher } from './client/fetcher.js';
+export { progressive } from './client/progressive.js';
 export { controllersToStaticParams } from './core/controllers-to-static-params.js';
-export { multitenant } from './core/multitenant.js';
-export { JSONLinesResponder } from './core/json-lines-responder.js';
-export { toDownloadResponse } from './core/to-download-response.js';
-export { get, post, put, patch, del, head, options, prefix, cloneControllerMetadata } from './core/decorators.js';
+export { createDecorator } from './core/create-decorator.js';
 export { decorate } from './core/decorate.js';
-export { progressive } from './client/progressive.js';
-export { fetcher, createFetcher } from './client/fetcher.js';
+export { cloneControllerMetadata, del, get, head, options, patch, post, prefix, put } from './core/decorators.js';
+export { HttpException } from './core/http-exception.js';
 export { initSegment } from './core/init-segment.js';
+export { JSONLinesResponder } from './core/json-lines-responder.js';
+export { multitenant } from './core/multitenant.js';
+export { toDownloadResponse } from './core/to-download-response.js';
 export { operation } from './openapi/operation.js';
-export { createValidateOnClient } from './validation/create-validate-on-client.js';
-export { procedure } from './validation/procedure.js';
-export { ToModelOutput } from './tools/to-model-output.js';
-export { createTool } from './tools/create-tool.js';
 export { deriveTools } from './tools/derive-tools.js';
-export { HttpStatus, HttpMethod } from './types/enums.js';
-export type { VovkBody, VovkQuery, VovkParams, VovkInput, VovkReturnType, VovkYieldType, VovkOutput, VovkIteration, } from './types/inference.js';
-export type { VovkRequest } from './types/request.js';
-export type { VovkJSONSchemaBase } from './types/json-schema.js';
+export { ToModelOutput } from './tools/to-model-output.js';
+export type { VovkFetcher } from './types/client.js';
 export type { VovkConfig } from './types/config.js';
 export type { VovkSchema } from './types/core.js';
-export type { VovkFetcher } from './types/client.js';
+export { HttpMethod, HttpStatus } from './types/enums.js';
+export type { VovkBody, VovkInput, VovkIteration, VovkOutput, VovkParams, VovkQuery, VovkReturnType, VovkYieldType, } from './types/inference.js';
+export type { VovkJSONSchemaBase } from './types/json-schema.js';
+export type { VovkRequest } from './types/request.js';
 export type { VovkValidateOnClient } from './types/validation.js';
-export type { VovkTool } from './types/tools.js';
+export { createValidateOnClient } from './validation/create-validate-on-client.js';
+export { procedure } from './validation/procedure.js';

package/dist/index.js

@@ -1,24 +1,23 @@
 // core
-export { HttpException } from './core/http-exception.js';
-export { createDecorator } from './core/create-decorator.js';
-export { controllersToStaticParams } from './core/controllers-to-static-params.js';
-export { multitenant } from './core/multitenant.js';
-export { JSONLinesResponder } from './core/json-lines-responder.js';
-export { toDownloadResponse } from './core/to-download-response.js';
-export { get, post, put, patch, del, head, options, prefix, cloneControllerMetadata } from './core/decorators.js';
-export { decorate } from './core/decorate.js';
+export { createFetcher, fetcher } from './client/fetcher.js';
 // client
 export { progressive } from './client/progressive.js';
-export { fetcher, createFetcher } from './client/fetcher.js';
+export { controllersToStaticParams } from './core/controllers-to-static-params.js';
+export { createDecorator } from './core/create-decorator.js';
+export { decorate } from './core/decorate.js';
+export { cloneControllerMetadata, del, get, head, options, patch, post, prefix, put } from './core/decorators.js';
+export { HttpException } from './core/http-exception.js';
 export { initSegment } from './core/init-segment.js';
+export { JSONLinesResponder } from './core/json-lines-responder.js';
+export { multitenant } from './core/multitenant.js';
+export { toDownloadResponse } from './core/to-download-response.js';
 // openapi
 export { operation } from './openapi/operation.js';
-// validation
-export { createValidateOnClient } from './validation/create-validate-on-client.js';
-export { procedure } from './validation/procedure.js';
+export { deriveTools } from './tools/derive-tools.js';
 // tools
 export { ToModelOutput } from './tools/to-model-output.js';
-export { createTool } from './tools/create-tool.js';
-export { deriveTools } from './tools/derive-tools.js';
 // types
-export { HttpStatus, HttpMethod } from './types/enums.js';
+export { HttpMethod, HttpStatus } from './types/enums.js';
+// validation
+export { createValidateOnClient } from './validation/create-validate-on-client.js';
+export { procedure } from './validation/procedure.js';

package/dist/internal.d.ts

@@ -1,18 +1,20 @@
-export { deepExtend } from './utils/deep-extend.js';
+export { readableStreamToAsyncIterable } from './client/default-stream-handler.js';
 export { resolveGeneratorConfigValues } from './core/resolve-generator-config-values.js';
-export { createCodeSamples } from './samples/create-code-samples.js';
-export { withValidationLibrary } from './validation/with-validation-library.js';
-export { validationSchemasObjectToSingleValidationSchema } from './validation/validation-schemas-object-to-single-validation-schema.js';
-export { operation } from './openapi/operation.js';
-export { openAPIToVovkSchema } from './openapi/openapi-to-vovk-schema/index.js';
+export { vovkApp } from './core/vovk-app.js';
 export { applyComponentsSchemas, reattachMixinDefs, } from './openapi/openapi-to-vovk-schema/apply-components-schemas.js';
+export { openAPIToVovkSchema } from './openapi/openapi-to-vovk-schema/index.js';
+export { operation } from './openapi/operation.js';
 export { vovkSchemaToOpenAPI } from './openapi/vovk-schema-to-openapi.js';
-export { readableStreamToAsyncIterable } from './client/default-stream-handler.js';
-export { VovkSchemaIdEnum } from './types/enums.js';
+export { createCodeSamples } from './samples/create-code-samples.js';
 export type { MCPModelOutput } from './tools/to-model-output-mcp.js';
-export type { VovkErrorResponse, VovkMetaSchema, VovkSegmentSchema, VovkControllerSchema, VovkHandlerSchema, VovkValidationType, } from './types/core.js';
-export type { VovkTypedProcedure } from './types/validation.js';
-export type { VovkOutputConfig, VovkReadmeConfig, VovkSamplesConfig, VovkPackageJson, VovkOpenAPIMixin, VovkOpenAPIMixinNormalized, VovkStrictConfig, VovkBundleConfig, VovkSegmentConfig, } from './types/config.js';
+export type { VovkFetcherOptions, VovkRPCModule, VovkStreamAsyncIterable } from './types/client.js';
+export type { VovkBundleConfig, VovkOpenAPIMixin, VovkOpenAPIMixinNormalized, VovkOutputConfig, VovkPackageJson, VovkReadmeConfig, VovkSamplesConfig, VovkSegmentConfig, VovkStrictConfig, } from './types/config.js';
+export type { VovkControllerSchema, VovkErrorResponse, VovkHandlerSchema, VovkMetaSchema, VovkSegmentSchema, VovkValidationType, } from './types/core.js';
+export { VovkSchemaIdEnum } from './types/enums.js';
 export type { VovkOperationObject } from './types/operation.js';
-export type { VovkRPCModule, VovkFetcherOptions, VovkStreamAsyncIterable } from './types/client.js';
+export type { StandardToolV0 } from './types/standard-tool.js';
 export type { IsAny, IsNotAny } from './types/utils.js';
+export type { VovkTypedProcedure } from './types/validation.js';
+export { deepExtend } from './utils/deep-extend.js';
+export { validationSchemasObjectToSingleValidationSchema } from './validation/validation-schemas-object-to-single-validation-schema.js';
+export { withValidationLibrary } from './validation/with-validation-library.js';

package/dist/internal.js

@@ -1,12 +1,13 @@
 // internal exports for other packages and tests
-export { deepExtend } from './utils/deep-extend.js';
+export { readableStreamToAsyncIterable } from './client/default-stream-handler.js';
 export { resolveGeneratorConfigValues } from './core/resolve-generator-config-values.js';
-export { createCodeSamples } from './samples/create-code-samples.js';
-export { withValidationLibrary } from './validation/with-validation-library.js';
-export { validationSchemasObjectToSingleValidationSchema } from './validation/validation-schemas-object-to-single-validation-schema.js';
-export { operation } from './openapi/operation.js';
-export { openAPIToVovkSchema } from './openapi/openapi-to-vovk-schema/index.js';
+export { vovkApp } from './core/vovk-app.js';
 export { applyComponentsSchemas, reattachMixinDefs, } from './openapi/openapi-to-vovk-schema/apply-components-schemas.js';
+export { openAPIToVovkSchema } from './openapi/openapi-to-vovk-schema/index.js';
+export { operation } from './openapi/operation.js';
 export { vovkSchemaToOpenAPI } from './openapi/vovk-schema-to-openapi.js';
-export { readableStreamToAsyncIterable } from './client/default-stream-handler.js';
+export { createCodeSamples } from './samples/create-code-samples.js';
 export { VovkSchemaIdEnum } from './types/enums.js';
+export { deepExtend } from './utils/deep-extend.js';
+export { validationSchemasObjectToSingleValidationSchema } from './validation/validation-schemas-object-to-single-validation-schema.js';
+export { withValidationLibrary } from './validation/with-validation-library.js';

package/dist/openapi/error.js

@@ -1,5 +1,5 @@
-import { HttpStatus } from '../types/enums.js';
 import { createDecorator } from '../core/create-decorator.js';
+import { HttpStatus } from '../types/enums.js';
 const statusDisplayText = {
     [HttpStatus.NULL]: 'Error',
     [HttpStatus.CONTINUE]: 'Continue',
@@ -43,7 +43,7 @@ const statusDisplayText = {
     [HttpStatus.UNPROCESSABLE_ENTITY]: 'Unprocessable Entity',
     [HttpStatus.FAILED_DEPENDENCY]: 'Failed Dependency',
     [HttpStatus.PRECONDITION_REQUIRED]: 'Precondition Required',
-    [HttpStatus.TOO_MANY_TRequestS]: 'Too Many Requests',
+    [HttpStatus.TOO_MANY_REQUESTS]: 'Too Many Requests',
     [HttpStatus.INTERNAL_SERVER_ERROR]: 'Internal Server Error',
     [HttpStatus.NOT_IMPLEMENTED]: 'Not Implemented',
     [HttpStatus.BAD_GATEWAY]: 'Bad Gateway',

package/dist/openapi/openapi-to-vovk-schema/apply-components-schemas.d.ts

@@ -1,17 +1,6 @@
 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, 
-/**
- * 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 applyComponentsSchemas(schema: VovkJSONSchemaBase, components: ComponentsObject['schemas'], mixinName: string, emitDefs?: boolean): VovkJSONSchemaBase | VovkJSONSchemaBase[];
 export declare function reattachMixinDefs(slot: VovkJSONSchemaBase | undefined, segment: {
     segmentType?: string;
     segmentName: string;

package/dist/openapi/openapi-to-vovk-schema/apply-components-schemas.js

@@ -15,11 +15,8 @@ function cloneJSON(obj) {
     return result;
 }
 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.
- */
+// true (default): embed the ref closure in `$defs`, self-contained (AJV + Rust);
+// false: keep `#/components/schemas/X` refs, no `$defs` (avoids the per-handler dup that overflows big specs)
 emitDefs = true) {
     const key = 'components/schemas';
     if (!components || !Object.keys(components).length)
@@ -75,11 +72,8 @@ emitDefs = true) {
     // 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.
- */
+// re-attaches a response slot's `$defs` closure at render time (Rust needs self-contained schemas);
+// pulls components from the segment's shared meta, no-op for non-mixin
 export function reattachMixinDefs(slot, segment) {
     if (!slot || segment?.segmentType !== 'mixin')
         return slot;

package/dist/openapi/openapi-to-vovk-schema/index.d.ts

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

package/dist/openapi/openapi-to-vovk-schema/index.js

@@ -1,8 +1,8 @@
+import { schemaToTsType } from '../../samples/schema-to-ts-type.js';
+import { VovkSchemaIdEnum } from '../../types/enums.js';
 import { applyComponentsSchemas } from './apply-components-schemas.js';
 import { inlineRefs } from './inline-refs.js';
 import { pruneComponentsSchemas } from './prune-components-schemas.js';
-import { VovkSchemaIdEnum } from '../../types/enums.js';
-import { schemaToTsType } from '../../samples/schema-to-ts-type.js';
 function getTsTypeString(contentType, schema) {
     const tsTypes = new Set(contentType.flatMap((ct) => {
         switch (ct) {
@@ -20,8 +20,24 @@ function getTsTypeString(contentType, schema) {
     }));
     return [...tsTypes].join(' | ') || schemaToTsType(schema);
 }
+// a spec is third party input, its x-tsType would land in the generated client as raw TS
+function stripXTsType(value) {
+    if (Array.isArray(value))
+        return value.map(stripXTsType);
+    if (!value || typeof value !== 'object')
+        return value;
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+        if (key === 'x-tsType')
+            continue;
+        result[key] = stripXTsType(val);
+    }
+    return result;
+}
 export function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName, getMethodName, filterOperations, pruneComponents, errorMessageKey, segmentName, }) {
     segmentName = segmentName ?? '';
+    // x-tsType is emitted verbatim into the generated client, only ours may reach it
+    openAPIObject = stripXTsType(openAPIObject);
     const forceApiRoot = apiRoot ||
         (openAPIObject.servers?.[0]?.url ??
             ('host' in openAPIObject
@@ -161,10 +177,8 @@ export function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }
         });
     });
     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.
+        // reassign with fresh objects only, the caller's spec shares references so its
+        // components.schemas must stay untouched; walking the whole controllers tree keeps every kept $ref resolvable
         segment.meta = {
             openAPIObject: {
                 ...noPathsOpenAPIObject,

package/dist/openapi/openapi-to-vovk-schema/inline-refs.d.ts

@@ -1,9 +1,2 @@
 import type { OpenAPIObject } from 'openapi3-ts/oas31';
-/**
- * Resolves $ref references at the first level only (except for components/schemas references)
- * For arrays, checks each item at the first level
- * @param obj - The object to process (may contain $ref properties)
- * @param openAPIObject - The complete OpenAPI document containing definitions
- * @returns The object with resolved references (except components/schemas)
- */
 export declare function inlineRefs<T extends object>(obj: unknown, openAPIObject: OpenAPIObject): T | null;

package/dist/openapi/openapi-to-vovk-schema/inline-refs.js

@@ -1,10 +1,4 @@
-/**
- * Resolves $ref references at the first level only (except for components/schemas references)
- * For arrays, checks each item at the first level
- * @param obj - The object to process (may contain $ref properties)
- * @param openAPIObject - The complete OpenAPI document containing definitions
- * @returns The object with resolved references (except components/schemas)
- */
+// resolves $ref at the first level only (skips components/schemas refs), arrays checked per item
 export function inlineRefs(obj, openAPIObject) {
     // Handle null or undefined
     if (obj === null || obj === undefined) {
@@ -63,12 +57,7 @@ export function inlineRefs(obj, openAPIObject) {
     // For regular objects without $ref, return as-is (no recursion)
     return obj;
 }
-/**
- * Resolves a JSON Reference ($ref) to its target value
- * @param ref - The reference string (e.g., "#/components/parameters/id")
- * @param openAPIObject - The complete OpenAPI document
- * @returns The resolved value or undefined if not found
- */
+// resolves a local $ref like "#/components/parameters/id", undefined if not found
 function resolveRef(ref, openAPIObject) {
     // Handle only local references (starting with #)
     if (!ref.startsWith('#/')) {

package/dist/openapi/openapi-to-vovk-schema/prune-components-schemas.d.ts

@@ -1,7 +1,2 @@
 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']>;