vovk 3.7.0 → 4.0.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to `vovk` are documented here. This file is the canonical record: noteworthy changes only, one short line each, linked to the pull request or commit that made them. GitHub Releases are not used.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 4.0.0-beta.0 - unreleased
+
+A cleanup major: removals and renames, no new APIs.
+
+### Removed
+
+- `toolsByName`: `deriveTools` returns the tools array only ([#28](https://github.com/finom/vovk/pull/28))
+- `VovkTool`, `createTool`, `parameters`, `type` and `inputSchemas`: replaced by the `StandardToolV0` convention ([#27](https://github.com/finom/vovk/pull/27))
+- `vovk/createRPC` and `vovk/createValidateOnClient` subpath aliases: use `vovk/create-rpc` and `vovk/create-validate-on-client` ([b7dc4b2](https://github.com/finom/vovk/commit/b7dc4b2a))
+- Dead `nestjs-operation-id` name-strategy literals ([3f84c25](https://github.com/finom/vovk/commit/3f84c253))
+
+### Changed
+
+- `HttpStatus.TOO_MANY_TRequestS` renamed to `TOO_MANY_REQUESTS` ([c739e4b](https://github.com/finom/vovk/commit/c739e4bc))
+- Production error responses carry no internal detail; `onError` still receives the full error ([d0be248](https://github.com/finom/vovk/commit/d0be2482), [419cf7f](https://github.com/finom/vovk/commit/419cf7f6))
+- A declared `contentType` is enforced even without a body schema; disabling body validation opts out ([444644b](https://github.com/finom/vovk/commit/444644b8), [27edb95](https://github.com/finom/vovk/commit/27edb95e))
+
+### Fixed
+
+- Stacked decorators all run: HTTP routes dispatch through the outermost wrapper ([18ce506](https://github.com/finom/vovk/commit/18ce5063))
+- Prototype members such as `constructor` no longer resolve as route handlers ([8fa67bb](https://github.com/finom/vovk/commit/8fa67bb0))
+- The route match cache is scoped to its handlers map, fixing cross-method poisoning ([6db95ff](https://github.com/finom/vovk/commit/6db95ff5))
+- Path params are percent-encoded, and an encoded slash stays inside its param ([d2d9046](https://github.com/finom/vovk/commit/d2d90464), [0cb5aa4](https://github.com/finom/vovk/commit/0cb5aa40))
+- Chained `withDefaults` deep-merges instead of replacing nested options ([4f53fc7](https://github.com/finom/vovk/commit/4f53fc78))
+- `Headers` instances and `init.signal` survive RPC options ([fc61920](https://github.com/finom/vovk/commit/fc619204))
+- Streaming: mid-stream errors reach `onError`, the error envelope stays out of `onIterate`, an abandoned iterator releases the stream ([b440310](https://github.com/finom/vovk/commit/b4403106), [06e99fa](https://github.com/finom/vovk/commit/06e99faa), [06b9c00](https://github.com/finom/vovk/commit/06b9c007))
+- Falsy handler output (`false`, `0`, `''`, `null`) is accepted when an output schema is set ([dc8c6a3](https://github.com/finom/vovk/commit/dc8c6a38))
+- Derived tools materialize `Response` and generator results, and failures reach `onError` ([7b7f1b8](https://github.com/finom/vovk/commit/7b7f1b87), [ff18ee5](https://github.com/finom/vovk/commit/ff18ee5d))
+- Derived path/query parameters and `components.schemas` merge with user-declared ones ([d86bae0](https://github.com/finom/vovk/commit/d86bae0b), [6a174ac](https://github.com/finom/vovk/commit/6a174ac1))
+- Malformed `x-meta` responds 400, `x-meta` is allowed in default CORS headers, non-ASCII meta is escaped ([5327a32](https://github.com/finom/vovk/commit/5327a327), [e34acae](https://github.com/finom/vovk/commit/e34acaea), [be58398](https://github.com/finom/vovk/commit/be583983))
+
+### Security
+
+- `x-tsType` is stripped from third-party OpenAPI specs on ingestion; a crafted value could inject executable code into the generated client ([c5e63cd](https://github.com/finom/vovk/commit/c5e63cd7))
+- Query parsing hardened: prototype-polluting keys dropped, pairs split at the first `=`, a large index cannot size a huge array ([46aaadf](https://github.com/finom/vovk/commit/46aaadf7), [03522f3](https://github.com/finom/vovk/commit/03522f3f), [14bbc17](https://github.com/finom/vovk/commit/14bbc179))
+- A non-index bracket key such as `?a[-1]=x` no longer discards the value; it becomes an object key, matching `qs`
+
+### Upgrading from 3.x
+
+1. Replace `HttpStatus.TOO_MANY_TRequestS` with `HttpStatus.TOO_MANY_REQUESTS`.
+2. Replace imports from `vovk/createRPC` and `vovk/createValidateOnClient` with `vovk/create-rpc` and `vovk/create-validate-on-client`.
+3. If you destructured `toolsByName` from `deriveTools`, build the map yourself from the returned array.
+4. If you used `createTool` / `VovkTool` / `inputSchemas`, move to the `StandardToolV0` shape.
+5. If you relied on error responses carrying internal messages in production, read them from `onError` instead.
+6. The composed client no longer comes from the `vovk-client` package; see the `vovk-cli` changelog.
+
+## 3.7.0 - 2026-06-11
+
+- Kebab-case file naming and subpath exports across packages; camelCase aliases such as `vovk/createRPC` kept for compatibility ([#23](https://github.com/finom/vovk/pull/23))
+
+## 3.5.0 - 2026-06-10
+
+- `openAPIMixin.filterOperations` and `pruneComponents`: generate only the operations you call and drop components nothing references ([#22](https://github.com/finom/vovk/pull/22))
+
+## 3.4.0 - 2026-05-30
+
+- Merged `inputSchema`, one Standard Schema for body, query and params; per-slot `inputSchemas` deprecated ([#16](https://github.com/finom/vovk/pull/16))
+- `VovkTool` follows the `standard-tool` convention, and `execute` takes per-call `meta` ([#18](https://github.com/finom/vovk/pull/18), [#19](https://github.com/finom/vovk/pull/19), [#20](https://github.com/finom/vovk/pull/20))
+
+## 3.2.2 - 2026-04-03
+
+- Fetcher `onSuccess`/`onError` assignable after initialization ([#3](https://github.com/finom/vovk/pull/3)), the `VovkInput` type ([#1](https://github.com/finom/vovk/pull/1)), and `.fn` LPC calls inside Next.js server actions ([#2](https://github.com/finom/vovk/pull/2))
+
+## 3.1.3 - 2026-03-21
+
+- `decorate()` and `static prefix`: controllers and procedures without decorator syntax ([docs](https://vovk.dev/decorator-overview))
+
+Earlier history predates this changelog; see the git tags.

package/dist/client/create-rpc.d.ts

@@ -1,9 +1,9 @@
 import type { VovkHandlerSchema } from '../internal.js';
+import type { VovkFetcher, VovkFetcherOptions, VovkRPCModule } from '../types/client.js';
 import type { VovkRequest } from '../types/request.js';
-import type { VovkRPCModule, VovkFetcher, VovkFetcherOptions } from '../types/client.js';
-import type { CombinedSpec } from '../types/validation.js';
 import type { KnownAny } from '../types/utils.js';
-export type { VovkHandlerSchema, VovkRequest, CombinedSpec };
+import type { CombinedSpec } from '../types/validation.js';
+export type { CombinedSpec, VovkHandlerSchema, VovkRequest };
 /**
  * Creates a client-side RPC module for interacting with server-side controllers.
  * @see https://vovk.dev/typescript

package/dist/client/create-rpc.js

@@ -1,14 +1,15 @@
-import { fetcher as defaultFetcher } from './fetcher.js';
+import { deepExtend } from '../utils/deep-extend.js';
 import { defaultHandler } from './default-handler.js';
 import { defaultStreamHandler } from './default-stream-handler.js';
+import { fetcher as defaultFetcher } from './fetcher.js';
 import { serializeQuery } from './serialize-query.js';
-import { deepExtend } from '../utils/deep-extend.js';
 const trimPath = (path) => path.trim().replace(/^\/|\/$/g, '');
 const getHandlerPath = (endpoint, params, query) => {
     let result = endpoint;
     const queryStr = query ? serializeQuery(query) : null;
     for (const [key, value] of Object.entries(params ?? {})) {
-        result = result.replace(`{${key}}`, value);
+        // encode so a value stays one path segment, the callback form also keeps $& from being a replacement pattern
+        result = result.replaceAll(`{${key}}`, () => encodeURIComponent(String(value)));
     }
     return `${result}${queryStr ? `?${queryStr}` : ''}`;
 };
@@ -26,7 +27,6 @@ export const createRPC = (givenSchema, segmentName, rpcModuleName, givenFetcher,
     let controllerSchema = schema.segments[segmentName]?.controllers[rpcModuleName];
     const client = {};
     if (!controllerSchema) {
-        // eslint-disable-next-line no-console
         console.warn(`🐺 Unable to create RPC module. Controller schema is missing for module "${rpcModuleName}" from segment "${segmentName}". Assuming that schema is not ready yet and a segment is importing an uncompiled RPC module.`);
         controllerSchema = {
             rpcModuleName,
@@ -134,10 +134,8 @@ export const createRPC = (givenSchema, segmentName, rpcModuleName, givenFetcher,
     }
     Object.defineProperty(client, 'withDefaults', {
         value: (newOptions) => {
-            return createRPC(schema, segmentName, rpcModuleName, givenFetcher, {
-                ...options,
-                ...newOptions,
-            });
+            // deep merge to match per-call option merging, so chained defaults don't clobber nested keys
+            return createRPC(schema, segmentName, rpcModuleName, givenFetcher, deepExtend({}, options, newOptions));
         },
         enumerable: false,
         writable: false,

package/dist/client/default-stream-handler.d.ts

@@ -1,11 +1,7 @@
 import type { VovkStreamAsyncIterable } from '../types/client.js';
 import '../utils/shim.js';
 export declare const DEFAULT_ERROR_MESSAGE = "An unknown error at the default stream handler";
-/**
- * Converts a ReadableStream of JSON Lines into a VovkStreamAsyncIterable.
- * This is the core streaming logic extracted for reuse outside of HTTP contexts.
- * @see https://vovk.dev/jsonlines
- */
+/** ReadableStream of JSON Lines to VovkStreamAsyncIterable, reusable outside HTTP contexts. @see https://vovk.dev/jsonlines */
 export declare const readableStreamToAsyncIterable: <T = unknown>({ readableStream, abortController, }: {
     readableStream: ReadableStream<Uint8Array | string>;
     abortController?: AbortController;

package/dist/client/default-stream-handler.js

@@ -1,12 +1,8 @@
-import { HttpStatus } from '../types/enums.js';
 import { HttpException } from '../core/http-exception.js';
+import { HttpStatus } from '../types/enums.js';
 import '../utils/shim.js';
 export const DEFAULT_ERROR_MESSAGE = 'An unknown error at the default stream handler';
-/**
- * Converts a ReadableStream of JSON Lines into a VovkStreamAsyncIterable.
- * This is the core streaming logic extracted for reuse outside of HTTP contexts.
- * @see https://vovk.dev/jsonlines
- */
+/** ReadableStream of JSON Lines to VovkStreamAsyncIterable, reusable outside HTTP contexts. @see https://vovk.dev/jsonlines */
 export const readableStreamToAsyncIterable = ({ readableStream, abortController, }) => {
     const reader = readableStream.getReader();
     const subscribers = new Set();
@@ -16,6 +12,8 @@ export const readableStreamToAsyncIterable = ({ readableStream, abortController,
     let streamError = null;
     let errorIndex = -1;
     let primaryStarted = false;
+    // consumers currently iterating, the last one to leave early releases the connection
+    let activeIterators = 0;
     const cachedItems = [];
     const waiters = [];
     // --- Helper functions ---
@@ -66,11 +64,7 @@ export const readableStreamToAsyncIterable = ({ readableStream, abortController,
                 return false;
             }
             if (data) {
-                subscribers.forEach((cb) => {
-                    if (!abortController?.signal.aborted)
-                        cb(data, iterationIndex);
-                });
-                iterationIndex++;
+                // the error envelope is a control message, not data, subscribers must not see it
                 if (typeof data === 'object' && data !== null && 'isError' in data && 'reason' in data) {
                     const upcomingError = data.reason;
                     abortController?.abort(upcomingError);
@@ -78,7 +72,12 @@ export const readableStreamToAsyncIterable = ({ readableStream, abortController,
                     setStreamError(error);
                     return true;
                 }
-                else if (!abortController?.signal.aborted) {
+                subscribers.forEach((cb) => {
+                    if (!abortController?.signal.aborted)
+                        cb(data, iterationIndex);
+                });
+                iterationIndex++;
+                if (!abortController?.signal.aborted) {
                     cachedItems.push(data);
                     notifyWaiters();
                 }
@@ -148,51 +147,60 @@ export const readableStreamToAsyncIterable = ({ readableStream, abortController,
             primaryStarted = true;
             void runPrimaryReader();
         }
+        activeIterators++;
         let index = 0;
-        while (true) {
-            // Check error first
-            if (streamError && index >= errorIndex) {
-                throw streamError;
-            }
-            // Clean exit on abort without error
-            if (abortController?.signal.aborted && isAbortedWithoutError) {
-                return;
-            }
-            // Yield from cache if available
-            if (index < cachedItems.length) {
-                yield cachedItems[index++];
-                continue;
-            }
-            // Stream finished
-            if (streamExhausted) {
-                return;
-            }
-            // Wait for next item or completion
-            const result = await new Promise((resolve, reject) => {
-                // Re-check state inside promise to handle race conditions
+        try {
+            while (true) {
+                // Check error first
                 if (streamError && index >= errorIndex) {
-                    reject(streamError);
-                    return;
+                    throw streamError;
                 }
+                // Clean exit on abort without error
                 if (abortController?.signal.aborted && isAbortedWithoutError) {
-                    resolve({ value: undefined, done: true });
                     return;
                 }
+                // Yield from cache if available
                 if (index < cachedItems.length) {
-                    resolve({ value: cachedItems[index], done: false });
-                    return;
+                    yield cachedItems[index++];
+                    continue;
                 }
+                // Stream finished
                 if (streamExhausted) {
-                    resolve({ value: undefined, done: true });
                     return;
                 }
-                waiters.push({ index, resolve, reject });
-            });
-            if (result.done) {
-                return;
+                // Wait for next item or completion
+                const result = await new Promise((resolve, reject) => {
+                    // Re-check state inside promise to handle race conditions
+                    if (streamError && index >= errorIndex) {
+                        reject(streamError);
+                        return;
+                    }
+                    if (abortController?.signal.aborted && isAbortedWithoutError) {
+                        resolve({ value: undefined, done: true });
+                        return;
+                    }
+                    if (index < cachedItems.length) {
+                        resolve({ value: cachedItems[index], done: false });
+                        return;
+                    }
+                    if (streamExhausted) {
+                        resolve({ value: undefined, done: true });
+                        return;
+                    }
+                    waiters.push({ index, resolve, reject });
+                });
+                if (result.done) {
+                    return;
+                }
+                index++;
+                yield result.value;
             }
-            index++;
-            yield result.value;
+        }
+        finally {
+            activeIterators--;
+            // a consumer that stopped early must release the connection, same as dispose does
+            if (activeIterators === 0 && !streamExhausted)
+                disposeStream('Stream iteration stopped');
         }
     }
     // --- Public API ---

package/dist/client/fetcher.d.ts

@@ -1,5 +1,5 @@
 import { HttpException } from '../core/http-exception.js';
-import type { VovkFetcherOptions, VovkFetcher } from '../types/client.js';
+import type { VovkFetcher, VovkFetcherOptions } from '../types/client.js';
 import type { VovkHandlerSchema } from '../types/core.js';
 export declare const DEFAULT_ERROR_MESSAGE = "Unknown error at default fetcher";
 export type { VovkFetcher };

package/dist/client/fetcher.js

@@ -1,7 +1,48 @@
-import { HttpStatus } from '../types/enums.js';
 import { HttpException } from '../core/http-exception.js';
+import { HttpStatus } from '../types/enums.js';
 import { fileNameToDisposition } from '../utils/file-name-to-disposition.js';
 export const DEFAULT_ERROR_MESSAGE = 'Unknown error at default fetcher';
+// header values must be ByteString, escape non-ASCII as \uXXXX which JSON.parse reads natively
+const toAsciiJson = (value) => JSON.stringify(value).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+// invokes emitError once for errors that surface during stream consumption, after the fetcher has returned
+function wrapStreamErrors(stream, emitError) {
+    let emitted = false;
+    const emitOnce = async (error) => {
+        if (emitted)
+            return;
+        emitted = true;
+        await emitError(error);
+    };
+    const getIterator = stream[Symbol.asyncIterator].bind(stream);
+    const asPromise = stream.asPromise.bind(stream);
+    return Object.assign(stream, {
+        [Symbol.asyncIterator]: () => {
+            const iterator = getIterator();
+            return {
+                next: async () => {
+                    try {
+                        return await iterator.next();
+                    }
+                    catch (error) {
+                        await emitOnce(error);
+                        throw error;
+                    }
+                },
+                return: iterator.return?.bind(iterator),
+                throw: iterator.throw?.bind(iterator),
+            };
+        },
+        asPromise: async () => {
+            try {
+                return await asPromise();
+            }
+            catch (error) {
+                await emitOnce(error);
+                throw error;
+            }
+        },
+    });
+}
 /**
  * Creates a customizable fetcher function for client requests.
  * @see https://vovk.dev/imports
@@ -62,7 +103,7 @@ export function createFetcher({ prepareRequestInit, transformResponse, onSuccess
                 accept: 'application/jsonl, application/json',
                 ...(resolvedContentType ? { 'content-type': resolvedContentType } : {}),
                 ...(resolvedFileName ? { 'content-disposition': fileNameToDisposition(resolvedFileName) } : {}),
-                ...(meta ? { 'x-meta': JSON.stringify(meta) } : {}),
+                ...(meta ? { 'x-meta': toAsciiJson(meta) } : {}),
             };
             // Normalize user headers to lowercase keys via Headers API (handles plain objects, arrays, and Headers instances)
             const userHeaders = init?.headers ? Object.fromEntries(new Headers(init.headers).entries()) : {};
@@ -87,7 +128,10 @@ export function createFetcher({ prepareRequestInit, transformResponse, onSuccess
                 requestInit.body = JSON.stringify(body);
             }
             const abortController = new AbortController();
-            requestInit.signal = abortController.signal;
+            // keep the internal controller for stream disposal but let a user-provided init.signal abort too
+            requestInit.signal = init?.signal
+                ? AbortSignal.any([abortController.signal, init.signal])
+                : abortController.signal;
             requestInit = prepareRequestInit ? await prepareRequestInit(requestInit, inputOptions) : requestInit;
             try {
                 response = await fetch(endpoint, requestInit);
@@ -103,7 +147,12 @@ export function createFetcher({ prepareRequestInit, transformResponse, onSuccess
             }
             const contentType = interpretAs ?? response.headers.get('content-type');
             if (contentType?.startsWith('application/jsonl')) {
-                respData = defaultStreamHandler({ response, abortController });
+                // route mid-stream errors to onError callbacks, which otherwise never see them
+                respData = wrapStreamErrors(defaultStreamHandler({ response, abortController }), async (error) => {
+                    for (const cb of onErrorCallbacks) {
+                        await cb(error, inputOptions, { response, init: requestInit, respData, schema });
+                    }
+                });
             }
             else if (contentType?.startsWith('application/json')) {
                 respData = await defaultHandler({ response, schema });

package/dist/client/progressive.d.ts

@@ -6,10 +6,6 @@ type PromisifyProperties<T> = {
     [K in keyof T]: Promise<T[K]>;
 };
 type TransformUnionToPromises<T> = PromisifyProperties<UnionToIntersection<T>>;
-/**
- * Implements progressive fetching by returning a proxy object where each property is a promise
- * that resolves when the corresponding value is available from the stream.
- * @see https://vovk.dev/jsonlines
- */
+/** Proxy object where each property is a promise resolving once the value arrives from the stream. @see https://vovk.dev/jsonlines */
 export declare function progressive<T extends (...args: KnownAny[]) => Promise<VovkStreamAsyncIterable<KnownAny>>>(fn: T, ...args: undefined extends Parameters<T>[0] ? [arg?: Parameters<T>[0]] : [arg: Parameters<T>[0]]): TransformUnionToPromises<VovkYieldType<T>>;
 export {};

package/dist/client/progressive.js

@@ -1,11 +1,9 @@
-/**
- * Implements progressive fetching by returning a proxy object where each property is a promise
- * that resolves when the corresponding value is available from the stream.
- * @see https://vovk.dev/jsonlines
- */
+/** Proxy object where each property is a promise resolving once the value arrives from the stream. @see https://vovk.dev/jsonlines */
 export function progressive(fn, ...args) {
     const [arg] = args;
     const reg = {};
+    let finalState = null;
+    const missingKeyError = (key) => new Error(`The connection was closed without sending a value for "${key}"`);
     void fn(arg)
         .then(async (result) => {
         for await (const item of result) {
@@ -23,15 +21,17 @@ export function progressive(fn, ...args) {
                 }
             }
         }
+        finalState = { type: 'done' };
         Object.keys(reg).forEach((key) => {
             if (reg[key].isSettled)
                 return;
             reg[key].isSettled = true;
-            reg[key].reject(new Error(`The connection was closed without sending a value for "${key}"`));
+            reg[key].reject(missingKeyError(key));
         });
         return result;
     })
         .catch((error) => {
+        finalState = { type: 'error', error };
         Object.keys(reg).forEach((key) => {
             if (reg[key].isSettled)
                 return;
@@ -45,12 +45,22 @@ export function progressive(fn, ...args) {
             if (prop in reg) {
                 return reg[prop].promise;
             }
+            // symbols and a non-yielded then are inspection or await probes, not stream keys
+            if (typeof prop === 'symbol' || prop === 'then') {
+                return undefined;
+            }
             const { promise, resolve, reject } = Promise.withResolvers();
             reg[prop] = { resolve, reject, promise, isSettled: false };
+            // the stream already finished, settle immediately instead of hanging forever
+            if (finalState) {
+                reg[prop].isSettled = true;
+                promise.catch(() => { });
+                reject(finalState.type === 'error' ? finalState.error : missingKeyError(prop));
+            }
             return promise;
         },
-        ownKeys: () => {
-            throw new Error('Getting own keys is not possible as they are dynamically created');
-        },
+        has: (_target, prop) => prop in reg,
+        ownKeys: () => Reflect.ownKeys(reg),
+        getOwnPropertyDescriptor: (_target, prop) => prop in reg ? { enumerable: true, configurable: true, value: reg[prop].promise } : undefined,
     });
 }

package/dist/client/serialize-query.d.ts

@@ -1,13 +1,2 @@
 import type { KnownAny } from '../types/utils.js';
-/**
- * Serialize a nested object (including arrays, arrays of objects, etc.)
- * into a bracket-based query string.
- *
- * @example
- *   serializeQuery({ x: 'xx', y: [1, 2], z: { f: 'x' } })
- *   => "x=xx&y[0]=1&y[1]=2&z[f]=x"
- *
- * @param obj - The input object to be serialized
- * @returns   - A bracket-based query string (without leading "?")
- */
 export declare function serializeQuery(obj: Record<string, KnownAny>): string;

package/dist/client/serialize-query.js

@@ -1,10 +1,4 @@
-/**
- * Recursively build query parameters from an object.
- *
- * @param key      - The query key so far (e.g. 'user', 'user[0]', 'user[0][name]')
- * @param value    - The current value to serialize
- * @returns        - An array of `key=value` strings
- */
+// recursively builds "key=value" strings, key grows like 'user', 'user[0]', 'user[0][name]'
 function buildParams(key, value) {
     if (value === null || value === undefined) {
         return []; // skip null/undefined values entirely
@@ -13,16 +7,7 @@ function buildParams(key, value) {
     if (typeof value === 'object') {
         // Array case
         if (Array.isArray(value)) {
-            /**
-             * We use index-based bracket notation here:
-             *   e.g. for value = ['aa', 'bb'] and key = 'foo'
-             *   => "foo[0]=aa&foo[1]=bb"
-             *
-             * If you prefer "foo[]=aa&foo[]=bb" style, replace:
-             *   `${key}[${i}]`
-             * with:
-             *   `${key}[]`
-             */
+            // index-based brackets: ['aa', 'bb'] + 'foo' -> "foo[0]=aa&foo[1]=bb"
             return value.flatMap((v, i) => {
                 const newKey = `${key}[${i}]`;
                 return buildParams(newKey, v);
@@ -36,17 +21,8 @@ function buildParams(key, value) {
     }
     return [`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`];
 }
-/**
- * Serialize a nested object (including arrays, arrays of objects, etc.)
- * into a bracket-based query string.
- *
- * @example
- *   serializeQuery({ x: 'xx', y: [1, 2], z: { f: 'x' } })
- *   => "x=xx&y[0]=1&y[1]=2&z[f]=x"
- *
- * @param obj - The input object to be serialized
- * @returns   - A bracket-based query string (without leading "?")
- */
+// nested object to a bracket query string (no leading "?"),
+// e.g. { x: 'xx', y: [1, 2], z: { f: 'x' } } -> "x=xx&y[0]=1&y[1]=2&z[f]=x"
 export function serializeQuery(obj) {
     if (!obj || typeof obj !== 'object')
         return '';

package/dist/core/controllers-to-static-params.d.ts

@@ -1,7 +1,6 @@
 import type { StaticClass } from '../types/utils.js';
 /**
- * Generates static API of the given controllers for a static segment.
- * @see https://vovk.dev/segment
+ * Static params for the controllers of a static segment. @see https://vovk.dev/segment
  * @example
  * ```ts
  * export function generateStaticParams() {

package/dist/core/controllers-to-static-params.js

@@ -1,6 +1,5 @@
 /**
- * Generates static API of the given controllers for a static segment.
- * @see https://vovk.dev/segment
+ * Static params for the controllers of a static segment. @see https://vovk.dev/segment
  * @example
  * ```ts
  * export function generateStaticParams() {

package/dist/core/create-decorator.d.ts

@@ -1,4 +1,4 @@
-import type { VovkHandlerSchema, VovkController } from '../types/core.js';
+import type { VovkController, VovkHandlerSchema } from '../types/core.js';
 import type { VovkRequest } from '../types/request.js';
 import type { KnownAny } from '../types/utils.js';
 type Next = () => Promise<unknown>;

package/dist/core/decorate.d.ts

@@ -9,12 +9,8 @@ export type DecorateMetadata = {
     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.
- *
+ * Applies decorators without decorator syntax; `.handle()` registers the handler
+ * (proxied when the last arg is a procedure result, wraps a plain handler otherwise).
  * @example With procedure
  * ```ts
  * static handleParams = decorate(

package/dist/core/decorators.js

@@ -1,8 +1,8 @@
-import { vovkApp } from './vovk-app.js';
-import { trimPath } from '../utils/trim-path.js';
+import { HttpMethod } from '../types/enums.js';
 import { toKebabCase } from '../utils/to-kebab-case.js';
+import { trimPath } from '../utils/trim-path.js';
 import { applyDecoratorAdapter } from './apply-decorator-adapter.js';
-import { HttpMethod } from '../types/enums.js';
+import { vovkApp } from './vovk-app.js';
 const isClass = (func) => typeof func === 'function' && /class/.test(func.toString());
 const assignSchema = ({ controller, propertyKey, path, options, httpMethod, }) => {
     if (typeof window !== 'undefined') {

package/dist/core/get-schema.d.ts

@@ -1,4 +1,4 @@
-import type { VovkSegmentSchema, VovkController } from '../types/core.js';
+import type { VovkController, VovkSegmentSchema } from '../types/core.js';
 import type { StaticClass } from '../types/utils.js';
 export declare function getControllerSchema(controller: VovkController, rpcModuleName: string, exposeValidation: boolean): Promise<{
     rpcModuleName: string;

package/dist/core/get-schema.js

@@ -2,9 +2,7 @@ import { VovkSchemaIdEnum } from '../types/enums.js';
 export async function getControllerSchema(controller, rpcModuleName, exposeValidation) {
     const handlers = exposeValidation
         ? (controller._handlers ?? {})
-        : Object.fromEntries(
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        Object.entries(controller._handlers ?? {}).map(([key, { validation: _v, ...value }]) => [key, value]));
+        : Object.fromEntries(Object.entries(controller._handlers ?? {}).map(([key, { validation: _v, ...value }]) => [key, value]));
     return {
         rpcModuleName,
         originalControllerName: controller.name,

package/dist/core/http-exception.d.ts

@@ -1,7 +1,7 @@
 import type { VovkErrorResponse } from '../types/core.js';
 import type { HttpStatus } from '../types/enums.js';
 /**
- * Represents an HTTP exception with a status code and message.
+ * HTTP exception with a status code and message.
  * @example
  * ```ts
  * throw new HttpException(HttpStatus.BAD_REQUEST, 'Invalid request data');

package/dist/core/http-exception.js

@@ -1,5 +1,5 @@
 /**
- * Represents an HTTP exception with a status code and message.
+ * HTTP exception with a status code and message.
  * @example
  * ```ts
  * throw new HttpException(HttpStatus.BAD_REQUEST, 'Invalid request data');

package/dist/core/init-segment.js

@@ -1,6 +1,6 @@
-import { vovkApp } from './vovk-app.js';
 import { trimPath } from '../utils/trim-path.js';
 import { getSchema } from './get-schema.js';
+import { vovkApp } from './vovk-app.js';
 export const initSegment = (options) => {
     const segmentName = trimPath(options.segmentName ?? '');
     options.segmentName = segmentName;