vovk 3.0.4 → 3.1.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/core/controllersToStaticParams.js

@@ -13,7 +13,7 @@ export function controllersToStaticParams(c, slug = 'vovk') {
         { [slug]: ['_schema_'] },
         ...Object.values(controllers).flatMap((controller) => {
             const handlers = controller._handlers;
-            const splitPrefix = controller._prefix?.split('/') ?? [];
+            const splitPrefix = controller.prefix?.split('/') ?? [];
             return Object.entries(handlers ?? {}).flatMap(([name, handler]) => {
                 const staticParams = controller._handlersMetadata?.[name]?.staticParams;
                 if (staticParams?.length) {

package/dist/core/decorate.d.ts

@@ -0,0 +1,43 @@
+import type { KnownAny } from '../types/utils.js';
+/**
+ * Metadata stored on a handler by HTTP decorators and custom decorators when used outside decorator context (via decorate).
+ */
+export type DecorateMetadata = {
+    httpMethod?: string;
+    path?: string;
+    options?: KnownAny;
+    decoratorAppliers?: ((controller: KnownAny, propertyKey: string) => void)[];
+};
+/**
+ * Applies decorators to a handler without using decorator syntax.
+ * Returns an object with `.handle()` to register the handler function.
+ *
+ * When the last argument is a procedure result (has `.handle`), its `.handle()` is proxied.
+ * Otherwise, `.handle()` wraps a plain handler directly.
+ *
+ * @example With procedure
+ * ```ts
+ * static handleParams = decorate(
+ *   put('x/{foo}/{bar}/y'),
+ *   authGuard(null),
+ *   procedure({ params: z.object({ foo: z.string(), bar: z.string() }) })
+ * ).handle(async (req) => req.vovk.params());
+ * ```
+ *
+ * @example Without procedure
+ * ```ts
+ * static getMethod = decorate(
+ *   get(),
+ * ).handle(async () => {
+ *   return { method: 'get' };
+ * });
+ * ```
+ */
+export declare function decorate<H extends {
+    handle: (...args: KnownAny[]) => KnownAny;
+}>(...args: [...unknown[], H]): {
+    handle: H['handle'];
+};
+export declare function decorate(...args: unknown[]): {
+    handle: <T extends (...args: KnownAny[]) => KnownAny>(fn: T) => T;
+};

package/dist/core/decorate.js

@@ -0,0 +1,24 @@
+export function decorate(...args) {
+    if (args.length === 0)
+        throw new Error('decorate() requires at least one argument');
+    const last = args[args.length - 1];
+    const hasProcedure = typeof last === 'function' && 'handle' in last && typeof last.handle === 'function';
+    const procedureResult = hasProcedure ? last : null;
+    const decoratorFns = (hasProcedure ? args.slice(0, -1) : args);
+    for (const decoratorFn of decoratorFns) {
+        if (typeof decoratorFn !== 'function') {
+            throw new Error('All decorator arguments to decorate() must be functions');
+        }
+    }
+    return {
+        handle(fn) {
+            const handler = procedureResult ? procedureResult.handle(fn) : fn;
+            handler._decorateMetadata = handler._decorateMetadata ?? {};
+            handler._decorateMetadata.decoratorAppliers = handler._decorateMetadata.decoratorAppliers ?? [];
+            for (const decoratorFn of decoratorFns) {
+                handler._decorateMetadata.decoratorAppliers.push(decoratorFn);
+            }
+            return handler;
+        },
+    };
+}

package/dist/core/decorators.js

@@ -84,7 +84,7 @@ export const prefix = (givenPath = '') => {
     const path = trimPath(givenPath);
     return (givenTarget, _context) => {
         const controller = givenTarget;
-        controller._prefix = path;
+        controller.prefix = path;
         return givenTarget;
     };
 };

package/dist/core/getSchema.js

@@ -8,7 +8,7 @@ export async function getControllerSchema(controller, rpcModuleName, exposeValid
     return {
         rpcModuleName,
         originalControllerName: controller.name,
-        prefix: controller._prefix ?? '',
+        prefix: controller.prefix ?? '',
         handlers,
     };
 }

package/dist/core/initSegment.js

@@ -4,12 +4,39 @@ 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 ?? {});
+    const controllerSet = new Set(controllerEntries.map(([, c]) => c));
+    // Sort so parent controllers are initialized before their children
+    controllerEntries.sort(([, a], [, b]) => {
+        return (Number(controllerSet.has(Object.getPrototypeOf(a))) -
+            Number(controllerSet.has(Object.getPrototypeOf(b))));
+    });
+    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 deferred decorate() decorator appliers in reverse order (bottom-up, matching stacked decorator semantics)
+        for (const key of Object.getOwnPropertyNames(controller)) {
+            const appliers = controller[key]?._decorateMetadata
+                ?.decoratorAppliers;
+            if (appliers) {
+                for (let i = appliers.length - 1; i >= 0; i--) {
+                    appliers[i](controller, key);
+                }
+            }
+        }
+        // Re-clone metadata if this controller extends another registered controller
+        // (cloneControllerMetadata() runs at class-definition time, before decorate() metadata is applied)
+        const parent = Object.getPrototypeOf(controller);
+        if (controllerSet.has(parent) && parent._handlers) {
+            controller._handlers = { ...parent._handlers, ...controller._handlers };
+            controller._handlersMetadata = { ...parent._handlersMetadata, ...controller._handlersMetadata };
+            for (const methods of Object.values(vovkApp.routes)) {
+                methods.set(controller, { ...(methods.get(parent) ?? {}), ...methods.get(controller) });
+            }
+        }
     }
     async function GET_DEV(req, data) {
         const params = await data.params;

package/dist/core/vovkApp.js

@@ -194,7 +194,7 @@ class VovkApp {
         controllers.forEach((staticMethods, controller) => {
             if (segmentName !== controller._segmentName)
                 return;
-            const prefix = controller._prefix ?? '';
+            const prefix = controller.prefix ?? '';
             Object.entries(staticMethods ?? {}).forEach(([path, staticMethod]) => {
                 const fullPath = [prefix, path].filter(Boolean).join('/');
                 handlers[fullPath] = { staticMethod, controller };

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 { decorate } from './core/decorate.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 { decorate } from './core/decorate.js';
 // client
 export { progressive } from './client/progressive.js';
 export { fetcher, createFetcher } from './client/fetcher.js';

package/dist/types/core.d.ts

@@ -86,7 +86,7 @@ export type StreamAbortMessage = {
 export type VovkControllerInternal = {
     _segmentName: string;
     _rpcModuleName?: VovkControllerSchema['rpcModuleName'];
-    _prefix?: VovkControllerSchema['prefix'];
+    prefix?: VovkControllerSchema['prefix'];
     _handlers: VovkControllerSchema['handlers'];
     _handlersMetadata?: Record<string, {
         staticParams?: Record<string, string>[];

package/package.json

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