vovk 3.0.4 → 3.1.0

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/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/package.json

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