vovk 3.4.0 → 3.4.1

package/dist/core/compose.d.ts

@@ -0,0 +1,38 @@
+import type { KnownAny } from '../types/utils.js';
+/**
+ * Metadata stored on a handler by HTTP decorators and custom decorators when used outside decorator context (via compose).
+ */
+export type ComposeMetadata = {
+    httpMethod?: string;
+    path?: string;
+    options?: KnownAny;
+    decoratorAppliers?: ((controller: KnownAny, propertyKey: string) => void)[];
+};
+/**
+ * Composes decorators and a handler/class into a single value.
+ *
+ * For method-level composition, decorators are stored and applied later by initSegment.
+ * For class-level composition, decorators like prefix() and cloneControllerMetadata()
+ * are applied immediately to the class in reverse order (matching stacked decorator semantics).
+ *
+ * @example Method-level
+ * ```ts
+ * static handleParams = compose(
+ *   put('x/{foo}/{bar}/y'),
+ *   authGuard(null),
+ *   procedure({ params: z.object({ foo: z.string(), bar: z.string() }) })
+ *     .handle(async (req) => req.vovk.params())
+ * );
+ * ```
+ *
+ * @example Class-level
+ * ```ts
+ * const MyController = compose(
+ *   prefix('users'),
+ *   cloneControllerMetadata(),
+ *   class extends ParentController {}
+ * );
+ * export default MyController;
+ * ```
+ */
+export declare function compose<T>(...args: [...unknown[], T]): T;

package/dist/core/compose.js

@@ -0,0 +1,31 @@
+export function compose(...args) {
+    if (args.length === 0)
+        throw new Error('compose() requires at least one argument');
+    const last = args[args.length - 1];
+    const decoratorFns = args.slice(0, -1);
+    if (typeof last !== 'function') {
+        throw new Error('The last argument to compose() must be a function, handler, or class');
+    }
+    for (const decoratorFn of decoratorFns) {
+        if (typeof decoratorFn !== 'function') {
+            throw new Error('All arguments to compose() except the last must be decorator functions');
+        }
+    }
+    // Detect class: native ES class constructors' toString() starts with "class"
+    if (last.toString().startsWith('class ')) {
+        // Apply class decorators in reverse order (bottom-up, matching stacked decorator semantics).
+        // Decorators mutate and return the same class, so .name is preserved.
+        for (let i = decoratorFns.length - 1; i >= 0; i--) {
+            decoratorFns[i](last);
+        }
+        return last;
+    }
+    // Method-level compose: store decorator appliers for deferred execution by initSegment
+    const handler = last;
+    handler._composeMetadata = handler._composeMetadata ?? {};
+    handler._composeMetadata.decoratorAppliers = handler._composeMetadata.decoratorAppliers ?? [];
+    for (const decoratorFn of decoratorFns) {
+        handler._composeMetadata.decoratorAppliers.push(decoratorFn);
+    }
+    return handler;
+}

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.js

@@ -140,10 +140,11 @@ 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),
                     }),
                 },
             };