vovk 3.0.3 → 3.1.0

package/dist/core/applyDecoratorAdapter.d.ts

@@ -0,0 +1,7 @@
+import type { VovkController } from '../types/core.js';
+import type { KnownAny } from '../types/utils.js';
+/**
+ * Adapts a decorator callback to work with experimental, 2018-09, and TC39 Stage 3 decorator formats.
+ * The callback receives (controller, propertyKey) when the class and field/method value are available.
+ */
+export declare function applyDecoratorAdapter(arg1: unknown, arg2: unknown, callback: (controller: VovkController, propertyKey: string) => void): KnownAny;

package/dist/core/applyDecoratorAdapter.js

@@ -0,0 +1,50 @@
+/**
+ * Adapts a decorator callback to work with experimental, 2018-09, and TC39 Stage 3 decorator formats.
+ * The callback receives (controller, propertyKey) when the class and field/method value are available.
+ */
+export function applyDecoratorAdapter(arg1, arg2, callback) {
+    // Experimental decorators: (target, propertyKey: string)
+    if (typeof arg2 === 'string') {
+        callback(arg1, arg2);
+        return;
+    }
+    // TC39 Stage 3: (value, context: { kind, name, addInitializer })
+    if (typeof arg2 === 'object' && arg2 !== null && 'name' in arg2) {
+        const ctx = arg2;
+        const propertyKey = String(ctx.name);
+        if (ctx.kind === 'field') {
+            return function (initialValue) {
+                this[propertyKey] = initialValue;
+                callback(this, propertyKey);
+                return this[propertyKey];
+            };
+        }
+        ctx.addInitializer(function () {
+            callback(this, propertyKey);
+        });
+        return;
+    }
+    // 2018-09 proposal: (descriptor: { kind, key, placement, initializer? })
+    if (typeof arg1 === 'object' && arg1 !== null && 'kind' in arg1 && 'key' in arg1) {
+        const desc = arg1;
+        const propertyKey = String(desc.key);
+        if (desc.kind === 'field') {
+            const origInit = desc.initializer;
+            return {
+                ...desc,
+                initializer() {
+                    const value = origInit?.call(this);
+                    this[propertyKey] = value;
+                    callback(this, propertyKey);
+                    return this[propertyKey];
+                },
+            };
+        }
+        return {
+            ...desc,
+            finisher(klass) {
+                callback(klass, propertyKey);
+            },
+        };
+    }
+}

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,34 @@
+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 immediately in reverse order (bottom-up, matching stacked decorator semantics)
+        let result = last;
+        for (let i = decoratorFns.length - 1; i >= 0; i--) {
+            const transformed = decoratorFns[i](result);
+            if (transformed !== undefined) {
+                result = transformed;
+            }
+        }
+        return result;
+    }
+    // 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/core/createDecorator.d.ts

@@ -2,17 +2,11 @@ import type { VovkHandlerSchema, VovkController } from '../types/core.js';
 import type { VovkRequest } from '../types/request.js';
 import type { KnownAny } from '../types/utils.js';
 type Next = () => Promise<unknown>;
-/** Minimal shape shared by all TC39 Stage 3 decorator context objects. */
-type _Stage3Context = {
-    kind: string;
-    name: string | symbol;
-    addInitializer: (fn: () => void) => void;
-};
 /**
  * Creates a custom decorator for Vovk controllers.
  * @see https://vovk.dev/decorator
  */
 export declare function createDecorator<TArgs extends unknown[], TRequest = VovkRequest>(handler: null | ((this: VovkController, req: TRequest, next: Next, ...args: TArgs) => unknown), initHandler?: (this: VovkController, ...args: TArgs) => Omit<VovkHandlerSchema, 'path' | 'httpMethod'> | ((handlerSchema: VovkHandlerSchema | null, options: {
     handlerName: string;
-}) => Omit<Partial<VovkHandlerSchema>, 'path' | 'httpMethod'>) | null | undefined): (...args: TArgs) => (target: KnownAny, propertyKeyOrContext: string | _Stage3Context) => void;
+}) => Omit<Partial<VovkHandlerSchema>, 'path' | 'httpMethod'>) | null | undefined): (...args: TArgs) => (target: KnownAny, propertyKeyOrContext?: unknown) => KnownAny;
 export {};

package/dist/core/createDecorator.js

@@ -1,3 +1,4 @@
+import { applyDecoratorAdapter } from './applyDecoratorAdapter.js';
 /**
  * Creates a custom decorator for Vovk controllers.
  * @see https://vovk.dev/decorator
@@ -5,16 +6,7 @@
 export function createDecorator(handler, initHandler) {
     return function decoratorCreator(...args) {
         return function decorator(target, propertyKeyOrContext) {
-            if (typeof propertyKeyOrContext === 'object' && propertyKeyOrContext !== null && 'kind' in propertyKeyOrContext) {
-                // TC39 Stage 3 decorator — defer to addInitializer where `this` is the class
-                const propertyKey = String(propertyKeyOrContext.name);
-                propertyKeyOrContext.addInitializer(function () {
-                    applyDecorator(this, propertyKey);
-                });
-                return;
-            }
-            // Experimental decorator — target is the class for static members
-            applyDecorator(target, propertyKeyOrContext);
+            return applyDecoratorAdapter(target, propertyKeyOrContext, applyDecorator);
             function applyDecorator(controller, propertyKey) {
                 const originalMethod = controller[propertyKey];
                 if (typeof originalMethod !== 'function') {

package/dist/core/decorators.d.ts

@@ -1,11 +1,5 @@
 import type { DecoratorOptions } from '../types/core.js';
 import type { KnownAny } from '../types/utils.js';
-/** Minimal shape shared by all TC39 Stage 3 decorator context objects. */
-type _Stage3Context = {
-    kind: string;
-    name: string | symbol;
-    addInitializer: (fn: () => void) => void;
-};
 /**
  * Prefix for all routes in the controller.
  */
@@ -18,49 +12,48 @@ export declare function cloneControllerMetadata(): <T extends new (...args: Know
  * GET HTTP method decorator.
  */
 export declare const get: {
-    (givenPath?: string | undefined, options?: DecoratorOptions | undefined): (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
-    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
+    (givenPath?: string | undefined, options?: DecoratorOptions | undefined): (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
+    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
 };
 /**
  *  POST HTTP method decorator.
  */
 export declare const post: {
-    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
-    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
+    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
+    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
 };
 /**
  *  PUT HTTP method decorator.
  */
 export declare const put: {
-    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
-    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
+    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
+    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
 };
 /**
  *  PATCH HTTP method decorator.
  */
 export declare const patch: {
-    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
-    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
+    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
+    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
 };
 /**
  *  DELETE HTTP method decorator.
  */
 export declare const del: {
-    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
-    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
+    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
+    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
 };
 /**
  * HEAD HTTP method decorator.
  */
 export declare const head: {
-    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
-    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
+    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
+    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
 };
 /**
  * OPTIONS HTTP method decorator.
  */
 export declare const options: {
-    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
-    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext: string | _Stage3Context) => void;
+    (givenPath?: string | undefined, options?: Omit<DecoratorOptions, "staticParams"> | undefined): (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
+    auto: (options?: DecoratorOptions) => (givenTarget: unknown, propertyKeyOrContext?: unknown) => KnownAny;
 };
-export {};

package/dist/core/decorators.js

@@ -1,10 +1,9 @@
 import { vovkApp } from './vovkApp.js';
 import { trimPath } from '../utils/trimPath.js';
 import { toKebabCase } from '../utils/toKebabCase.js';
+import { applyDecoratorAdapter } from './applyDecoratorAdapter.js';
 import { HttpMethod } from '../types/enums.js';
 const isClass = (func) => typeof func === 'function' && /class/.test(func.toString());
-/** Detects whether the second decorator argument is a TC39 Stage 3 context object. */
-const _isStage3 = (arg) => typeof arg === 'object' && arg !== null && 'kind' in arg;
 const assignSchema = ({ controller, propertyKey, path, options, httpMethod, }) => {
     if (typeof window !== 'undefined') {
         throw new Error('HTTP decorators can be used on server-side only. You have probably imported a controller on the client-side.');
@@ -55,42 +54,22 @@ function createHTTPDecorator(httpMethod) {
     function decoratorFactory(givenPath = '', options) {
         const path = trimPath(givenPath);
         function decorator(givenTarget, propertyKeyOrContext) {
-            if (_isStage3(propertyKeyOrContext)) {
-                const propertyKey = String(propertyKeyOrContext.name);
-                propertyKeyOrContext.addInitializer(function () {
-                    assignSchema({ controller: this, propertyKey, path, options, httpMethod });
-                });
-                return;
-            }
-            const controller = givenTarget;
-            assignSchema({ controller, propertyKey: propertyKeyOrContext, path, options, httpMethod });
+            return applyDecoratorAdapter(givenTarget, propertyKeyOrContext, (controller, propertyKey) => {
+                assignSchema({ controller, propertyKey, path, options, httpMethod });
+            });
         }
         return decorator;
     }
     const auto = (options) => {
         function decorator(givenTarget, propertyKeyOrContext) {
-            if (_isStage3(propertyKeyOrContext)) {
-                const propertyKey = String(propertyKeyOrContext.name);
-                propertyKeyOrContext.addInitializer(function () {
-                    const controller = this;
-                    // validation is already assigned at procedure function
-                    const properties = Object.keys(controller._handlers?.[propertyKey]?.validation?.params?.properties ?? {});
-                    const kebabCasePath = toKebabCase(propertyKey);
-                    const path = properties.length
-                        ? `${kebabCasePath}/${properties.map((prop) => `{${prop}}`).join('/')}`
-                        : kebabCasePath;
-                    assignSchema({ controller, propertyKey, path, options, httpMethod });
-                });
-                return;
-            }
-            const controller = givenTarget;
-            // validation is already assigned at procedure function
-            const properties = Object.keys(controller._handlers?.[propertyKeyOrContext]?.validation?.params?.properties ?? {});
-            const kebabCasePath = toKebabCase(propertyKeyOrContext);
-            const path = properties.length
-                ? `${kebabCasePath}/${properties.map((prop) => `{${prop}}`).join('/')}`
-                : kebabCasePath;
-            assignSchema({ controller, propertyKey: propertyKeyOrContext, path, options, httpMethod });
+            return applyDecoratorAdapter(givenTarget, propertyKeyOrContext, (controller, propertyKey) => {
+                const properties = Object.keys(controller._handlers?.[propertyKey]?.validation?.params?.properties ?? {});
+                const kebabCasePath = toKebabCase(propertyKey);
+                const path = properties.length
+                    ? `${kebabCasePath}/${properties.map((prop) => `{${prop}}`).join('/')}`
+                    : kebabCasePath;
+                assignSchema({ controller, propertyKey, path, options, httpMethod });
+            });
         }
         return decorator;
     };

package/dist/core/initSegment.js

@@ -4,12 +4,43 @@ import { getSchema } from './getSchema.js';
 export const initSegment = (options) => {
     const segmentName = trimPath(options.segmentName ?? '');
     options.segmentName = segmentName;
-    for (const [rpcModuleName, controller] of Object.entries(options.controllers ?? {})) {
+    const controllerEntries = Object.entries(options.controllers ?? {});
+    // Phase 1: Apply compose metadata for all controllers
+    for (const [rpcModuleName, controller] of controllerEntries) {
         controller._segmentName = segmentName;
         controller._rpcModuleName = rpcModuleName;
         controller._onError = options?.onError;
         controller._onSuccess = options?.onSuccess;
         controller._onBefore = options?.onBefore;
+        // Apply compose() metadata: call decorator appliers for each composed handler
+        for (const key of Object.getOwnPropertyNames(controller)) {
+            const method = controller[key];
+            if (typeof method === 'function' && method._composeMetadata) {
+                const metadata = method._composeMetadata;
+                if (metadata.decoratorAppliers) {
+                    // Apply in reverse order to match decorator semantics (bottom-up)
+                    for (let i = metadata.decoratorAppliers.length - 1; i >= 0; i--) {
+                        // Call decorator function with (controller, propertyKey) simulating experimental decorator context
+                        metadata.decoratorAppliers[i](controller, key);
+                    }
+                }
+            }
+        }
+    }
+    // Phase 2: Re-clone metadata for controllers that extend another registered controller.
+    // This is needed because cloneControllerMetadata() may run before compose metadata is applied
+    // (e.g., when using class-level compose with a parent that uses method-level compose).
+    const controllerSet = new Set(controllerEntries.map(([, c]) => c));
+    for (const [, controller] of controllerEntries) {
+        const parent = Object.getPrototypeOf(controller);
+        if (parent && controllerSet.has(parent) && parent._handlers) {
+            controller._handlers = { ...parent._handlers, ...controller._handlers };
+            controller._handlersMetadata = { ...parent._handlersMetadata, ...controller._handlersMetadata };
+            Object.values(vovkApp.routes).forEach((methods) => {
+                const parentMethods = methods.get(parent) ?? {};
+                methods.set(controller, { ...parentMethods, ...methods.get(controller) });
+            });
+        }
     }
     async function GET_DEV(req, data) {
         const params = await data.params;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { multitenant } from './core/multitenant.js';
 export { JSONLinesResponder } from './core/JSONLinesResponder.js';
 export { toDownloadResponse } from './core/toDownloadResponse.js';
 export { get, post, put, patch, del, head, options, prefix, cloneControllerMetadata } from './core/decorators.js';
+export { compose } from './core/compose.js';
 export { progressive } from './client/progressive.js';
 export { fetcher, createFetcher } from './client/fetcher.js';
 export { initSegment } from './core/initSegment.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export { multitenant } from './core/multitenant.js';
 export { JSONLinesResponder } from './core/JSONLinesResponder.js';
 export { toDownloadResponse } from './core/toDownloadResponse.js';
 export { get, post, put, patch, del, head, options, prefix, cloneControllerMetadata } from './core/decorators.js';
+export { compose } from './core/compose.js';
 // client
 export { progressive } from './client/progressive.js';
 export { fetcher, createFetcher } from './client/fetcher.js';

package/dist/openapi/error.d.ts

@@ -1,6 +1,2 @@
 import { HttpStatus } from '../types/enums.js';
-export declare const error: (status: HttpStatus, message: string) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext: string | {
-    kind: string;
-    name: string | symbol;
-    addInitializer: (fn: () => void) => void;
-}) => void;
+export declare const error: (status: HttpStatus, message: string) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext?: unknown) => import("../types/utils.js").KnownAny;

package/dist/openapi/operation.d.ts

@@ -1,26 +1,10 @@
 import type { VovkOperationObject } from '../types/operation.js';
-export declare const operationDecorator: (openAPIOperationObject?: VovkOperationObject | undefined) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext: string | {
-    kind: string;
-    name: string | symbol;
-    addInitializer: (fn: () => void) => void;
-}) => void;
+export declare const operationDecorator: (openAPIOperationObject?: VovkOperationObject | undefined) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext?: unknown) => import("../types/utils.js").KnownAny;
 /**
  * OpenAPI operation decorator to add metadata to API operations. Also includes `error` and `tool` utilities.
  * @see https://vovk.dev/openapi
  */
-export declare const operation: ((openAPIOperationObject?: VovkOperationObject | undefined) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext: string | {
-    kind: string;
-    name: string | symbol;
-    addInitializer: (fn: () => void) => void;
-}) => void) & {
-    error: (status: import("../index.js").HttpStatus, message: string) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext: string | {
-        kind: string;
-        name: string | symbol;
-        addInitializer: (fn: () => void) => void;
-    }) => void;
-    tool: (toolOptions: import("../types/tools.js").VovkToolOptions) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext: string | {
-        kind: string;
-        name: string | symbol;
-        addInitializer: (fn: () => void) => void;
-    }) => void;
+export declare const operation: ((openAPIOperationObject?: VovkOperationObject | undefined) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext?: unknown) => import("../types/utils.js").KnownAny) & {
+    error: (status: import("../index.js").HttpStatus, message: string) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext?: unknown) => import("../types/utils.js").KnownAny;
+    tool: (toolOptions: import("../types/tools.js").VovkToolOptions) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext?: unknown) => import("../types/utils.js").KnownAny;
 };

package/dist/openapi/tool.d.ts

@@ -1,6 +1,2 @@
 import type { VovkToolOptions } from '../types/tools.js';
-export declare const tool: (toolOptions: VovkToolOptions) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext: string | {
-    kind: string;
-    name: string | symbol;
-    addInitializer: (fn: () => void) => void;
-}) => void;
+export declare const tool: (toolOptions: VovkToolOptions) => (target: import("../types/utils.js").KnownAny, propertyKeyOrContext?: unknown) => import("../types/utils.js").KnownAny;

package/package.json

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