vovk 3.0.0-draft.52 → 3.0.0-draft.54

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> vovk@3.0.0-draft.52 build
+> vovk@3.0.0-draft.54 build
 > tsc
 
 \

package/.turbo/turbo-tsc.log

@@ -1,6 +1,6 @@
 
 
-> vovk@3.0.0-draft.49 tsc
+> vovk@3.0.0-draft.53 tsc
 > tsc --noEmit
 
 \

package/README.md

@@ -1 +1,24 @@
-Description is coming soon.
+<p align="center"> 
+  <picture>
+    <source width="300" media="(prefers-color-scheme: dark)" srcset="https://vovk.dev/vovk-logo-white.svg">
+    <source width="300" media="(prefers-color-scheme: light)" srcset="https://vovk.dev/vovk-logo.svg">
+    <img width="300" alt="vovk" src="https://vovk.dev/vovk-logo.svg">
+  </picture><br>
+  <strong>REST + RPC = ♥️</strong>
+</p>
+
+<p align="center">
+  Back-end meta-framework for <a href="https://nextjs.org/docs/app">Next.js</a>
+</p>
+
+---
+
+## vovk [![npm version](https://badge.fury.io/js/vovk.svg)](https://www.npmjs.com/package/vovk)
+
+The main library with [zero dependencies](https://bundlephobia.com/result?p=vovk) that's going to be used in production. It provides a wrapper for Next.js API routes, internal RPC API, utilities and types.
+
+```sh
+npm install vovk
+```
+
+For more information, please visit the [getting started guide](https://vovk.dev/getting-started) or check out the [Vovk.ts examples](https://vovk-examples.vercel.app/).

package/dist/client/createRPC.d.ts

@@ -1,4 +1,3 @@
 import { type VovkControllerSchema, type KnownAny } from '../types';
 import { type VovkClientOptions, type VovkClient, type VovkDefaultFetcherOptions } from './types';
-export declare const ARRAY_QUERY_KEY = "_vovkarr";
 export declare const createRPC: <T, OPTS extends Record<string, KnownAny> = VovkDefaultFetcherOptions>(controllerSchema: VovkControllerSchema, segmentName?: string, options?: VovkClientOptions<OPTS>) => VovkClient<T, OPTS>;

package/dist/client/createRPC.js

@@ -3,39 +3,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRPC = exports.ARRAY_QUERY_KEY = void 0;
+exports.createRPC = void 0;
 const defaultFetcher_1 = __importDefault(require("./defaultFetcher"));
 const defaultHandler_1 = require("./defaultHandler");
 const defaultStreamHandler_1 = require("./defaultStreamHandler");
-// TODO Ugly workaround. Need your ideas how to distinguish between array and non-array query params
-exports.ARRAY_QUERY_KEY = '_vovkarr';
+const serializeQuery_1 = __importDefault(require("../utils/serializeQuery"));
 const trimPath = (path) => path.trim().replace(/^\/|\/$/g, '');
 const getHandlerPath = (endpoint, params, query) => {
     let result = endpoint;
     for (const [key, value] of Object.entries(params ?? {})) {
         result = result.replace(`:${key}`, value);
     }
-    const searchParams = new URLSearchParams();
-    let hasQuery = false;
-    const arrayKeys = [];
-    for (const [key, value] of Object.entries(query ?? {})) {
-        if (typeof value === 'undefined')
-            continue;
-        if (value instanceof Array) {
-            arrayKeys.push(key);
-            for (const val of value) {
-                searchParams.append(key, val);
-            }
-        }
-        else {
-            searchParams.set(key, value);
-        }
-        hasQuery = true;
-    }
-    if (arrayKeys.length) {
-        searchParams.set(exports.ARRAY_QUERY_KEY, arrayKeys.join(','));
-    }
-    return `${result}${hasQuery ? '?' : ''}${searchParams.toString()}`;
+    const queryStr = query ? (0, serializeQuery_1.default)(query) : null;
+    return `${result}${queryStr ? '?' : ''}${queryStr}`;
 };
 const createRPC = (controllerSchema, segmentName, options) => {
     const schema = controllerSchema;
@@ -46,7 +26,8 @@ const createRPC = (controllerSchema, segmentName, options) => {
         throw new Error(`Unable to clientize. No schema for controller ${String(schema?.controllerName)} provided`);
     const controllerPrefix = trimPath(schema.prefix ?? '');
     const { fetcher: settingsFetcher = defaultFetcher_1.default } = options ?? {};
-    for (const [staticMethodName, { path, httpMethod, validation }] of Object.entries(schema.handlers)) {
+    for (const [staticMethodName, handlerSchema] of Object.entries(schema.handlers)) {
+        const { path, httpMethod, validation } = handlerSchema;
         const getEndpoint = ({ apiRoot, params, query, }) => {
             const mainPrefix = (apiRoot.startsWith('http://') || apiRoot.startsWith('https://') || apiRoot.startsWith('/') ? '' : '/') +
                 (apiRoot.endsWith('/') ? apiRoot : `${apiRoot}/`) +
@@ -85,6 +66,7 @@ const createRPC = (controllerSchema, segmentName, options) => {
                 return Promise.resolve(fetcherPromise);
             return input.transform ? fetcherPromise.then(input.transform) : fetcherPromise;
         };
+        handler.schema = handlerSchema;
         // @ts-expect-error TODO
         client[staticMethodName] = handler;
     }

package/dist/client/index.d.ts

@@ -1,4 +1,2 @@
-import { createRPC } from './createRPC';
-import type { VovkClientFetcher, VovkClientOptions, VovkDefaultFetcherOptions, VovkValidateOnClient } from './types';
-export { createRPC };
-export type { VovkClientFetcher, VovkClientOptions, VovkDefaultFetcherOptions, VovkValidateOnClient };
+export { createRPC } from './createRPC';
+export type { VovkClientFetcher, VovkClientOptions, VovkDefaultFetcherOptions, VovkValidateOnClient } from './types';

package/dist/client/index.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRPC = void 0;
-const createRPC_1 = require("./createRPC");
+var createRPC_1 = require("./createRPC");
 Object.defineProperty(exports, "createRPC", { enumerable: true, get: function () { return createRPC_1.createRPC; } });

package/dist/client/types.d.ts

@@ -1,4 +1,4 @@
-import type { KnownAny, HttpMethod, ControllerStaticMethod, VovkControllerBody, VovkControllerQuery, VovkControllerParams } from '../types';
+import type { KnownAny, HttpMethod, ControllerStaticMethod, VovkControllerBody, VovkControllerQuery, VovkControllerParams, VovkHandlerSchema } from '../types';
 import type { StreamJSONResponse } from '../StreamJSONResponse';
 import type { NextResponse } from 'next/server';
 export type StaticMethodInput<T extends ControllerStaticMethod> = (VovkControllerBody<T> extends undefined | void ? {
@@ -26,7 +26,7 @@ export type StreamAsyncIterator<T> = {
 };
 type StaticMethodReturn<T extends ControllerStaticMethod> = ReturnType<T> extends NextResponse<infer U> | Promise<NextResponse<infer U>> ? U : ReturnType<T> extends Response | Promise<Response> ? Awaited<ReturnType<T>> : ReturnType<T>;
 type StaticMethodReturnPromise<T extends ControllerStaticMethod> = ToPromise<StaticMethodReturn<T>>;
-type ClientMethod<T extends (...args: KnownAny[]) => void | object | StreamJSONResponse<STREAM> | Promise<StreamJSONResponse<STREAM>>, OPTS extends Record<string, KnownAny>, STREAM extends KnownAny = unknown> = <R>(options: (StaticMethodInput<T> extends {
+type ClientMethod<T extends (...args: KnownAny[]) => void | object | StreamJSONResponse<STREAM> | Promise<StreamJSONResponse<STREAM>>, OPTS extends Record<string, KnownAny>, STREAM extends KnownAny = unknown> = (<R>(options: (StaticMethodInput<T> extends {
     body?: undefined | null;
     query?: undefined;
     params?: undefined;
@@ -34,7 +34,9 @@ type ClientMethod<T extends (...args: KnownAny[]) => void | object | StreamJSONR
     params: StaticMethodInput<T>['params'];
 } : unknown : StaticMethodInput<T>) & (Partial<OPTS & {
     transform: (staticMethodReturn: Awaited<StaticMethodReturn<T>>) => R;
-}> | void)) => ReturnType<T> extends Promise<StreamJSONResponse<infer U>> | StreamJSONResponse<infer U> | Iterator<infer U> | AsyncIterator<infer U> ? Promise<StreamAsyncIterator<U>> : R extends object ? Promise<R> : StaticMethodReturnPromise<T>;
+}> | void)) => ReturnType<T> extends Promise<StreamJSONResponse<infer U>> | StreamJSONResponse<infer U> | Iterator<infer U> | AsyncIterator<infer U> ? Promise<StreamAsyncIterator<U>> : R extends object ? Promise<R> : StaticMethodReturnPromise<T>) & {
+    schema: VovkHandlerSchema;
+};
 type OmitNever<T> = {
     [K in keyof T as T[K] extends never ? never : K]: T[K];
 };

package/dist/createDecorator.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerSchema, KnownAny, VovkController, VovkRequest } from './types';
+import type { VovkHandlerSchema, KnownAny, VovkController, VovkRequest } from './types';
 type Next = () => Promise<unknown>;
-export declare function createDecorator<ARGS extends unknown[], REQUEST = VovkRequest>(handler: null | ((this: VovkController, req: REQUEST, next: Next, ...args: ARGS) => unknown), initHandler?: (this: VovkController, ...args: ARGS) => Omit<HandlerSchema, 'path' | 'httpMethod'> | ((handlerSchema: HandlerSchema | null) => Omit<HandlerSchema, 'path' | 'httpMethod'>) | null | undefined): (...args: ARGS) => (target: KnownAny, propertyKey: string) => void;
+export declare function createDecorator<ARGS extends unknown[], REQUEST = VovkRequest>(handler: null | ((this: VovkController, req: REQUEST, next: Next, ...args: ARGS) => unknown), initHandler?: (this: VovkController, ...args: ARGS) => Omit<VovkHandlerSchema, 'path' | 'httpMethod'> | ((handlerSchema: VovkHandlerSchema | null) => Omit<VovkHandlerSchema, 'path' | 'httpMethod'>) | null | undefined): (...args: ARGS) => (target: KnownAny, propertyKey: string) => void;
 export {};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { createVovkApp } from './createVovkApp';
-import { HttpStatus as HttpStatus, HttpMethod as HttpMethod, type VovkErrorResponse, type VovkRequest, type VovkBody, type VovkQuery, type VovkParams, type VovkReturnType, type VovkYieldType, type VovkControllerBody, type VovkControllerQuery, type VovkControllerParams, type VovkControllerYieldType, type VovkSchema, type VovkWorkerSchema, type VovkControllerSchema } from './types';
+import { HttpStatus as HttpStatus, HttpMethod as HttpMethod, type VovkErrorResponse, type VovkRequest, type VovkBody, type VovkQuery, type VovkParams, type VovkReturnType, type VovkYieldType, type VovkControllerBody, type VovkControllerQuery, type VovkControllerParams, type VovkControllerYieldType, type VovkSchema, type VovkWorkerSchema, type VovkControllerSchema, type VovkHandlerSchema } from './types';
 import { type VovkClientOptions, type VovkClientFetcher, type VovkDefaultFetcherOptions, type VovkValidateOnClient, createRPC } from './client';
 import { HttpException } from './HttpException';
 import { createDecorator } from './createDecorator';
@@ -7,7 +7,7 @@ import { StreamJSONResponse } from './StreamJSONResponse';
 import { worker, createWPC } from './worker';
 import { generateStaticAPI } from './utils/generateStaticAPI';
 import { setClientValidatorsForHandler } from './utils/setClientValidatorsForHandler';
-export { type VovkClientFetcher, type VovkDefaultFetcherOptions, type VovkValidateOnClient, type VovkSchema, type VovkErrorResponse, type VovkRequest, type VovkControllerBody, type VovkControllerQuery, type VovkControllerParams, type VovkControllerYieldType, type VovkBody, type VovkQuery, type VovkParams, type VovkYieldType, type VovkReturnType, type VovkClientOptions, type VovkWorkerSchema, type VovkControllerSchema, StreamJSONResponse, HttpException, HttpStatus, HttpMethod, createVovkApp, createDecorator, worker, createWPC, createRPC, generateStaticAPI, setClientValidatorsForHandler, };
+export { type VovkClientFetcher, type VovkDefaultFetcherOptions, type VovkValidateOnClient, type VovkSchema, type VovkErrorResponse, type VovkRequest, type VovkControllerBody, type VovkControllerQuery, type VovkControllerParams, type VovkControllerYieldType, type VovkBody, type VovkQuery, type VovkParams, type VovkYieldType, type VovkReturnType, type VovkClientOptions, type VovkWorkerSchema, type VovkControllerSchema, type VovkHandlerSchema, StreamJSONResponse, HttpException, HttpStatus, HttpMethod, createVovkApp, createDecorator, worker, createWPC, createRPC, generateStaticAPI, setClientValidatorsForHandler, };
 export declare const get: {
     (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: import("./types").KnownAny, propertyKey: string) => void>;
     auto: (options?: import("./types").DecoratorOptions) => (givenTarget: import("./types").KnownAny, propertyKey: string) => void;

package/dist/types.d.ts

@@ -3,7 +3,7 @@ import type { StreamJSONResponse } from './StreamJSONResponse';
 import { StreamAsyncIterator } from './client/types';
 export type KnownAny = any;
 export type StaticClass = Function;
-export type HandlerSchema = {
+export type VovkHandlerSchema = {
     path: string;
     httpMethod: HttpMethod;
     validation?: {
@@ -16,7 +16,7 @@ export type VovkControllerSchema = {
     controllerName: string;
     originalControllerName: string;
     prefix?: string;
-    handlers: Record<string, HandlerSchema>;
+    handlers: Record<string, VovkHandlerSchema>;
 };
 export type VovkWorkerSchema = {
     workerName: string;
@@ -77,7 +77,7 @@ export interface VovkRequest<BODY = undefined, QUERY extends object | undefined
         form: <T = KnownAny>() => Promise<T>;
     };
 }
-export type ControllerStaticMethod<REQ extends VovkRequest<KnownAny, KnownAny> = VovkRequest<undefined, Record<string, string | string[]>>, PARAMS extends {
+export type ControllerStaticMethod<REQ extends VovkRequest<KnownAny, KnownAny> = VovkRequest<undefined, Record<string, KnownAny>>, PARAMS extends {
     [key: string]: string;
 } = KnownAny> = ((req: REQ, params: PARAMS) => unknown) & {
     _controller?: VovkController;

package/dist/utils/parseQuery.d.ts

@@ -0,0 +1,25 @@
+import type { KnownAny } from '../types';
+/**
+ * Deserialize a bracket-based query string into an object.
+ *
+ * Supports:
+ *   - Key/value pairs with nested brackets (e.g. "a[b][0]=value")
+ *   - Arrays with empty bracket (e.g. "arr[]=1&arr[]=2")
+ *   - Mixed arrays of objects, etc.
+ *
+ * @example
+ *   parseQuery("x=xx&y[0]=yy&y[1]=uu&z[f]=x&z[u][0]=uu&z[u][1]=xx&z[d][x]=ee")
+ *   => {
+ *        x: "xx",
+ *        y: ["yy", "uu"],
+ *        z: {
+ *          f: "x",
+ *          u: ["uu", "xx"],
+ *          d: { x: "ee" }
+ *        }
+ *      }
+ *
+ * @param queryString - The raw query string (e.g. location.search.slice(1))
+ * @returns           - A nested object representing the query params
+ */
+export default function parseQuery(queryString: string): Record<string, KnownAny>;

package/dist/utils/parseQuery.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = parseQuery;
+/**
+ * Parse a bracket-based key (e.g. "z[d][0][x]" or "arr[]")
+ * into an array of path segments (strings or special push-markers).
+ *
+ * Example: "z[d][0][x]" => ["z", "d", "0", "x"]
+ * Example: "arr[]"      => ["arr", "" ]  // "" indicates "push" onto array
+ */
+function parseKey(key) {
+    // The first segment is everything up to the first '[' (or the entire key if no '[')
+    const segments = [];
+    const topKeyMatch = key.match(/^([^[\]]+)/);
+    if (topKeyMatch) {
+        segments.push(topKeyMatch[1]);
+    }
+    else {
+        // If it starts with brackets, treat it as empty? (edge case)
+        segments.push('');
+    }
+    // Now capture all bracket parts: [something], [0], []
+    const bracketRegex = /\[([^[\]]*)\]/g;
+    let match;
+    while ((match = bracketRegex.exec(key)) !== null) {
+        // match[1] is the content inside the brackets
+        segments.push(match[1]);
+    }
+    return segments;
+}
+/**
+ * Recursively set a value in a nested object/array, given a path of segments.
+ * - If segment is numeric => treat as array index
+ * - If segment is empty "" => push to array
+ * - Else => object property
+ */
+function setValue(obj, path, value) {
+    let current = obj;
+    for (let i = 0; i < path.length; i++) {
+        const segment = path[i];
+        // If we're at the last segment, set the value
+        if (i === path.length - 1) {
+            if (segment === '') {
+                // Empty bracket => push
+                if (!Array.isArray(current)) {
+                    current = [];
+                }
+                current.push(value);
+            }
+            else if (!isNaN(Number(segment))) {
+                // Numeric segment => array index
+                const idx = Number(segment);
+                if (!Array.isArray(current)) {
+                    current = [];
+                }
+                current[idx] = value;
+            }
+            else {
+                // Object property
+                current[segment] = value;
+            }
+        }
+        else {
+            // Not the last segment: descend into existing structure or create it
+            const nextSegment = path[i + 1];
+            if (segment === '') {
+                // Empty bracket => push
+                if (!Array.isArray(current)) {
+                    // Convert the current node into an array, if not one
+                    current = [];
+                }
+                // If we are not at the last path, we need a placeholder object or array
+                // for the next segment. We'll push something and move current to that.
+                if (current.length === 0) {
+                    // nothing in array yet
+                    current.push(typeof nextSegment === 'string' && !isNaN(Number(nextSegment)) ? [] : {});
+                }
+                else if (typeof nextSegment === 'string' && !isNaN(Number(nextSegment))) {
+                    // next is numeric => we want an array
+                    if (!Array.isArray(current[current.length - 1])) {
+                        current[current.length - 1] = [];
+                    }
+                }
+                else {
+                    // next is not numeric => we want an object
+                    if (typeof current[current.length - 1] !== 'object') {
+                        current[current.length - 1] = {};
+                    }
+                }
+                current = current[current.length - 1];
+            }
+            else if (!isNaN(Number(segment))) {
+                // segment is numeric => array index
+                const idx = Number(segment);
+                if (!Array.isArray(current)) {
+                    current = [];
+                }
+                if (current[idx] === undefined) {
+                    // Create placeholder for next segment
+                    current[idx] = typeof nextSegment === 'string' && !isNaN(Number(nextSegment)) ? [] : {};
+                }
+                current = current[idx];
+            }
+            else {
+                // segment is an object key
+                if (current[segment] === undefined) {
+                    // Create placeholder
+                    current[segment] = typeof nextSegment === 'string' && !isNaN(Number(nextSegment)) ? [] : {};
+                }
+                current = current[segment];
+            }
+        }
+    }
+}
+/**
+ * Deserialize a bracket-based query string into an object.
+ *
+ * Supports:
+ *   - Key/value pairs with nested brackets (e.g. "a[b][0]=value")
+ *   - Arrays with empty bracket (e.g. "arr[]=1&arr[]=2")
+ *   - Mixed arrays of objects, etc.
+ *
+ * @example
+ *   parseQuery("x=xx&y[0]=yy&y[1]=uu&z[f]=x&z[u][0]=uu&z[u][1]=xx&z[d][x]=ee")
+ *   => {
+ *        x: "xx",
+ *        y: ["yy", "uu"],
+ *        z: {
+ *          f: "x",
+ *          u: ["uu", "xx"],
+ *          d: { x: "ee" }
+ *        }
+ *      }
+ *
+ * @param queryString - The raw query string (e.g. location.search.slice(1))
+ * @returns           - A nested object representing the query params
+ */
+function parseQuery(queryString) {
+    const result = {};
+    if (!queryString)
+        return result;
+    // Split into key=value pairs
+    const pairs = queryString
+        .replace(/^\?/, '') // Remove leading "?" if present
+        .split('&');
+    for (const pair of pairs) {
+        const [rawKey, rawVal = ''] = pair.split('=');
+        const decodedKey = decodeURIComponent(rawKey || '');
+        const decodedVal = decodeURIComponent(rawVal);
+        // Parse bracket notation
+        const pathSegments = parseKey(decodedKey);
+        // Insert into the result object
+        setValue(result, pathSegments, decodedVal);
+    }
+    return result;
+}

package/dist/utils/reqQuery.js

@@ -1,25 +1,10 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = reqQuery;
-const createRPC_1 = require("../client/createRPC");
+const parseQuery_1 = __importDefault(require("./parseQuery"));
 function reqQuery(req) {
-    const queryArr = req.nextUrl.searchParams.get(createRPC_1.ARRAY_QUERY_KEY)?.split(',') ?? null;
-    const entries = [...req.nextUrl.searchParams.entries()];
-    const query = entries.reduce((acc, [key, value]) => {
-        if (key === createRPC_1.ARRAY_QUERY_KEY)
-            return acc;
-        if (queryArr?.includes(key)) {
-            if (!(key in acc)) {
-                acc[key] = [value];
-            }
-            else {
-                acc[key].push(value);
-            }
-        }
-        else {
-            acc[key] = value;
-        }
-        return acc;
-    }, {});
-    return query;
+    return (0, parseQuery_1.default)(req.nextUrl.search);
 }

package/dist/utils/serializeQuery.d.ts

@@ -0,0 +1,13 @@
+import type { KnownAny } from '../types';
+/**
+ * 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 default function serializeQuery(obj: Record<string, KnownAny>): string;

package/dist/utils/serializeQuery.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = serializeQuery;
+/**
+ * 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
+ */
+function buildParams(key, value) {
+    if (value === null || value === undefined) {
+        return []; // skip null/undefined values entirely
+    }
+    // If value is an object or array, we need to recurse
+    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}[]`
+             */
+            return value.flatMap((v, i) => {
+                const newKey = `${key}[${i}]`;
+                return buildParams(newKey, v);
+            });
+        }
+        // Plain object case
+        return Object.keys(value).flatMap((k) => {
+            const newKey = `${key}[${k}]`;
+            return buildParams(newKey, value[k]);
+        });
+    }
+    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 "?")
+ */
+function serializeQuery(obj) {
+    if (!obj || typeof obj !== 'object')
+        return '';
+    // Collect query segments
+    const segments = [];
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            const value = obj[key];
+            segments.push(...buildParams(key, value));
+        }
+    }
+    return segments.join('&');
+}

package/dist/worker/createWPC.d.ts

@@ -1,2 +1,2 @@
 import type { WorkerPromiseInstance } from './types';
-export declare function createWPC<T extends object>(currentWorker: Worker | null, workerSchema: object): WorkerPromiseInstance<T>;
+export declare function createWPC<T extends object>(workerSchema: object, currentWorker?: Worker): WorkerPromiseInstance<T>;

package/dist/worker/createWPC.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWPC = createWPC;
-function createWPC(currentWorker, workerSchema) {
+function createWPC(workerSchema, currentWorker) {
     if (!workerSchema)
         throw new Error('Worker schema is not provided');
     const schema = workerSchema;
@@ -23,7 +23,7 @@ function createWPC(currentWorker, workerSchema) {
         instance.worker = worker;
         return instance;
     };
-    instance.fork = (worker) => createWPC(worker, schema);
+    instance.fork = (worker) => createWPC(schema, worker);
     for (const methodName of Object.keys(schema.handlers)) {
         const { isGenerator } = schema.handlers[methodName];
         if (isGenerator) {

package/dist/worker/index.d.ts

@@ -1,3 +1,2 @@
-import { worker } from './worker';
-import { createWPC } from './createWPC';
-export { worker, createWPC };
+export { worker } from './worker';
+export { createWPC } from './createWPC';

package/dist/worker/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWPC = exports.worker = void 0;
-const worker_1 = require("./worker");
+var worker_1 = require("./worker");
 Object.defineProperty(exports, "worker", { enumerable: true, get: function () { return worker_1.worker; } });
-const createWPC_1 = require("./createWPC");
+var createWPC_1 = require("./createWPC");
 Object.defineProperty(exports, "createWPC", { enumerable: true, get: function () { return createWPC_1.createWPC; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vovk",
-  "version": "3.0.0-draft.52",
+  "version": "3.0.0-draft.54",
   "main": "dist/index.js",
   "description": "RESTful RPC for Next.js - Transforms Next.js into a powerful REST API platform with RPC capabilities.",
   "repository": {

package/src/client/createRPC.ts

@@ -10,9 +10,7 @@ import { type VovkClientOptions, type VovkClient, type VovkDefaultFetcherOptions
 import defaultFetcher from './defaultFetcher';
 import { defaultHandler } from './defaultHandler';
 import { defaultStreamHandler } from './defaultStreamHandler';
-
-// TODO Ugly workaround. Need your ideas how to distinguish between array and non-array query params
-export const ARRAY_QUERY_KEY = '_vovkarr';
+import serializeQuery from '../utils/serializeQuery';
 
 const trimPath = (path: string) => path.trim().replace(/^\/|\/$/g, '');
 
@@ -26,27 +24,9 @@ const getHandlerPath = <T extends ControllerStaticMethod>(
     result = result.replace(`:${key}`, value as string);
   }
 
-  const searchParams = new URLSearchParams();
-  let hasQuery = false;
-  const arrayKeys: string[] = [];
-  for (const [key, value] of Object.entries(query ?? {})) {
-    if (typeof value === 'undefined') continue;
-    if (value instanceof Array) {
-      arrayKeys.push(key);
-      for (const val of value) {
-        searchParams.append(key, val);
-      }
-    } else {
-      searchParams.set(key, value);
-    }
-    hasQuery = true;
-  }
+  const queryStr = query ? serializeQuery(query) : null;
 
-  if (arrayKeys.length) {
-    searchParams.set(ARRAY_QUERY_KEY, arrayKeys.join(','));
-  }
-
-  return `${result}${hasQuery ? '?' : ''}${searchParams.toString()}`;
+  return `${result}${queryStr ? '?' : ''}${queryStr}`;
 };
 
 export const createRPC = <T, OPTS extends Record<string, KnownAny> = VovkDefaultFetcherOptions>(
@@ -62,7 +42,8 @@ export const createRPC = <T, OPTS extends Record<string, KnownAny> = VovkDefault
   const controllerPrefix = trimPath(schema.prefix ?? '');
   const { fetcher: settingsFetcher = defaultFetcher } = options ?? {};
 
-  for (const [staticMethodName, { path, httpMethod, validation }] of Object.entries(schema.handlers)) {
+  for (const [staticMethodName, handlerSchema] of Object.entries(schema.handlers)) {
+    const { path, httpMethod, validation } = handlerSchema;
     const getEndpoint = ({
       apiRoot,
       params,
@@ -125,6 +106,8 @@ export const createRPC = <T, OPTS extends Record<string, KnownAny> = VovkDefault
       return input.transform ? fetcherPromise.then(input.transform) : fetcherPromise;
     };
 
+    handler.schema = handlerSchema;
+
     // @ts-expect-error TODO
     client[staticMethodName] = handler;
   }

package/src/client/index.ts

@@ -1,5 +1,2 @@
-import { createRPC } from './createRPC';
-import type { VovkClientFetcher, VovkClientOptions, VovkDefaultFetcherOptions, VovkValidateOnClient } from './types';
-
-export { createRPC };
-export type { VovkClientFetcher, VovkClientOptions, VovkDefaultFetcherOptions, VovkValidateOnClient };
+export { createRPC } from './createRPC';
+export type { VovkClientFetcher, VovkClientOptions, VovkDefaultFetcherOptions, VovkValidateOnClient } from './types';

package/src/client/types.ts

@@ -5,6 +5,7 @@ import type {
   VovkControllerBody,
   VovkControllerQuery,
   VovkControllerParams,
+  VovkHandlerSchema,
 } from '../types';
 import type { StreamJSONResponse } from '../StreamJSONResponse';
 import type { NextResponse } from 'next/server';
@@ -40,7 +41,7 @@ type ClientMethod<
   T extends (...args: KnownAny[]) => void | object | StreamJSONResponse<STREAM> | Promise<StreamJSONResponse<STREAM>>,
   OPTS extends Record<string, KnownAny>,
   STREAM extends KnownAny = unknown,
-> = <R>(
+> = (<R>(
   options: (StaticMethodInput<T> extends { body?: undefined | null; query?: undefined; params?: undefined }
     ? unknown
     : Parameters<T>[0] extends void
@@ -61,7 +62,9 @@ type ClientMethod<
   ? Promise<StreamAsyncIterator<U>>
   : R extends object
     ? Promise<R>
-    : StaticMethodReturnPromise<T>;
+    : StaticMethodReturnPromise<T>) & {
+  schema: VovkHandlerSchema;
+};
 
 type OmitNever<T> = {
   [K in keyof T as T[K] extends never ? never : K]: T[K];

package/src/createDecorator.ts

@@ -1,4 +1,4 @@
-import type { HandlerSchema, KnownAny, VovkController, VovkRequest } from './types';
+import type { VovkHandlerSchema, KnownAny, VovkController, VovkRequest } from './types';
 
 type Next = () => Promise<unknown>;
 
@@ -8,8 +8,8 @@ export function createDecorator<ARGS extends unknown[], REQUEST = VovkRequest>(
     this: VovkController,
     ...args: ARGS
   ) =>
-    | Omit<HandlerSchema, 'path' | 'httpMethod'>
-    | ((handlerSchema: HandlerSchema | null) => Omit<HandlerSchema, 'path' | 'httpMethod'>)
+    | Omit<VovkHandlerSchema, 'path' | 'httpMethod'>
+    | ((handlerSchema: VovkHandlerSchema | null) => Omit<VovkHandlerSchema, 'path' | 'httpMethod'>)
     | null
     | undefined
 ) {
@@ -25,7 +25,7 @@ export function createDecorator<ARGS extends unknown[], REQUEST = VovkRequest>(
       }
       const sourceMethod = originalMethod._sourceMethod ?? originalMethod;
 
-      const handlerSchema: HandlerSchema | null = controller._handlers?.[propertyKey] ?? null;
+      const handlerSchema: VovkHandlerSchema | null = controller._handlers?.[propertyKey] ?? null;
       const initResultReturn = initHandler?.call(controller, ...args);
       const initResult = typeof initResultReturn === 'function' ? initResultReturn(handlerSchema) : initResultReturn;
 

package/src/index.ts

@@ -16,6 +16,7 @@ import {
   type VovkSchema,
   type VovkWorkerSchema,
   type VovkControllerSchema,
+  type VovkHandlerSchema,
 } from './types';
 import {
   type VovkClientOptions,
@@ -50,6 +51,7 @@ export {
   type VovkClientOptions,
   type VovkWorkerSchema,
   type VovkControllerSchema,
+  type VovkHandlerSchema,
   StreamJSONResponse,
   HttpException,
   HttpStatus,

package/src/types.ts

@@ -6,7 +6,7 @@ export type KnownAny = any; // eslint-disable-line @typescript-eslint/no-explici
 
 export type StaticClass = Function; // eslint-disable-line @typescript-eslint/no-unsafe-function-type
 
-export type HandlerSchema = {
+export type VovkHandlerSchema = {
   path: string;
   httpMethod: HttpMethod;
   validation?: { query?: KnownAny; body?: KnownAny };
@@ -17,7 +17,7 @@ export type VovkControllerSchema = {
   controllerName: string;
   originalControllerName: string;
   prefix?: string;
-  handlers: Record<string, HandlerSchema>;
+  handlers: Record<string, VovkHandlerSchema>;
 };
 
 export type VovkWorkerSchema = {
@@ -107,7 +107,7 @@ export interface VovkRequest<BODY = undefined, QUERY extends object | undefined
 }
 
 export type ControllerStaticMethod<
-  REQ extends VovkRequest<KnownAny, KnownAny> = VovkRequest<undefined, Record<string, string | string[]>>,
+  REQ extends VovkRequest<KnownAny, KnownAny> = VovkRequest<undefined, Record<string, KnownAny>>,
   PARAMS extends { [key: string]: string } = KnownAny,
 > = ((req: REQ, params: PARAMS) => unknown) & {
   _controller?: VovkController;

package/src/utils/parseQuery.ts

@@ -0,0 +1,160 @@
+import type { KnownAny } from '../types';
+
+/**
+ * Parse a bracket-based key (e.g. "z[d][0][x]" or "arr[]")
+ * into an array of path segments (strings or special push-markers).
+ *
+ * Example: "z[d][0][x]" => ["z", "d", "0", "x"]
+ * Example: "arr[]"      => ["arr", "" ]  // "" indicates "push" onto array
+ */
+function parseKey(key: string): string[] {
+  // The first segment is everything up to the first '[' (or the entire key if no '[')
+  const segments: string[] = [];
+  const topKeyMatch = key.match(/^([^[\]]+)/);
+  if (topKeyMatch) {
+    segments.push(topKeyMatch[1]);
+  } else {
+    // If it starts with brackets, treat it as empty? (edge case)
+    segments.push('');
+  }
+
+  // Now capture all bracket parts: [something], [0], []
+  const bracketRegex = /\[([^[\]]*)\]/g;
+  let match: RegExpExecArray | null;
+  while ((match = bracketRegex.exec(key)) !== null) {
+    // match[1] is the content inside the brackets
+    segments.push(match[1]);
+  }
+
+  return segments;
+}
+
+/**
+ * Recursively set a value in a nested object/array, given a path of segments.
+ * - If segment is numeric => treat as array index
+ * - If segment is empty "" => push to array
+ * - Else => object property
+ */
+function setValue(obj: Record<string, KnownAny>, path: string[], value: KnownAny): void {
+  let current: KnownAny = obj;
+
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+
+    // If we're at the last segment, set the value
+    if (i === path.length - 1) {
+      if (segment === '') {
+        // Empty bracket => push
+        if (!Array.isArray(current)) {
+          current = [];
+        }
+        current.push(value);
+      } else if (!isNaN(Number(segment))) {
+        // Numeric segment => array index
+        const idx = Number(segment);
+        if (!Array.isArray(current)) {
+          current = [];
+        }
+        current[idx] = value;
+      } else {
+        // Object property
+        current[segment] = value;
+      }
+    } else {
+      // Not the last segment: descend into existing structure or create it
+      const nextSegment = path[i + 1];
+
+      if (segment === '') {
+        // Empty bracket => push
+        if (!Array.isArray(current)) {
+          // Convert the current node into an array, if not one
+          current = [];
+        }
+        // If we are not at the last path, we need a placeholder object or array
+        // for the next segment. We'll push something and move current to that.
+        if (current.length === 0) {
+          // nothing in array yet
+          current.push(typeof nextSegment === 'string' && !isNaN(Number(nextSegment)) ? [] : {});
+        } else if (typeof nextSegment === 'string' && !isNaN(Number(nextSegment))) {
+          // next is numeric => we want an array
+          if (!Array.isArray(current[current.length - 1])) {
+            current[current.length - 1] = [];
+          }
+        } else {
+          // next is not numeric => we want an object
+          if (typeof current[current.length - 1] !== 'object') {
+            current[current.length - 1] = {};
+          }
+        }
+        current = current[current.length - 1];
+      } else if (!isNaN(Number(segment))) {
+        // segment is numeric => array index
+        const idx = Number(segment);
+        if (!Array.isArray(current)) {
+          current = [];
+        }
+        if (current[idx] === undefined) {
+          // Create placeholder for next segment
+          current[idx] = typeof nextSegment === 'string' && !isNaN(Number(nextSegment)) ? [] : {};
+        }
+        current = current[idx];
+      } else {
+        // segment is an object key
+        if (current[segment] === undefined) {
+          // Create placeholder
+          current[segment] = typeof nextSegment === 'string' && !isNaN(Number(nextSegment)) ? [] : {};
+        }
+        current = current[segment];
+      }
+    }
+  }
+}
+
+/**
+ * Deserialize a bracket-based query string into an object.
+ *
+ * Supports:
+ *   - Key/value pairs with nested brackets (e.g. "a[b][0]=value")
+ *   - Arrays with empty bracket (e.g. "arr[]=1&arr[]=2")
+ *   - Mixed arrays of objects, etc.
+ *
+ * @example
+ *   parseQuery("x=xx&y[0]=yy&y[1]=uu&z[f]=x&z[u][0]=uu&z[u][1]=xx&z[d][x]=ee")
+ *   => {
+ *        x: "xx",
+ *        y: ["yy", "uu"],
+ *        z: {
+ *          f: "x",
+ *          u: ["uu", "xx"],
+ *          d: { x: "ee" }
+ *        }
+ *      }
+ *
+ * @param queryString - The raw query string (e.g. location.search.slice(1))
+ * @returns           - A nested object representing the query params
+ */
+export default function parseQuery(queryString: string): Record<string, KnownAny> {
+  const result: Record<string, KnownAny> = {};
+
+  if (!queryString) return result;
+
+  // Split into key=value pairs
+  const pairs = queryString
+    .replace(/^\?/, '') // Remove leading "?" if present
+    .split('&');
+
+  for (const pair of pairs) {
+    const [rawKey, rawVal = ''] = pair.split('=');
+
+    const decodedKey = decodeURIComponent(rawKey || '');
+    const decodedVal = decodeURIComponent(rawVal);
+
+    // Parse bracket notation
+    const pathSegments = parseKey(decodedKey);
+
+    // Insert into the result object
+    setValue(result, pathSegments, decodedVal);
+  }
+
+  return result;
+}

package/src/utils/reqQuery.ts

@@ -1,26 +1,6 @@
-import { ARRAY_QUERY_KEY } from '../client/createRPC';
 import type { KnownAny, VovkRequest } from '../types';
+import parseQuery from './parseQuery';
 
 export default function reqQuery<T extends object | undefined>(req: VovkRequest<KnownAny, T>): T {
-  type Query = NonNullable<T>;
-  const queryArr = (req.nextUrl.searchParams.get(ARRAY_QUERY_KEY as keyof T) as string | undefined)?.split(',') ?? null;
-  const entries = [...req.nextUrl.searchParams.entries()] as [string, string][];
-  const query = entries.reduce(
-    (acc, [key, value]) => {
-      if (key === ARRAY_QUERY_KEY) return acc;
-      if (queryArr?.includes(key)) {
-        if (!(key in acc)) {
-          acc[key] = [value];
-        } else {
-          (acc[key] as string[]).push(value);
-        }
-      } else {
-        acc[key] = value;
-      }
-      return acc;
-    },
-    {} as Record<string, string | string[]>
-  );
-
-  return query as Query;
+  return parseQuery(req.nextUrl.search) as NonNullable<T>;
 }

package/src/utils/serializeQuery.ts

@@ -0,0 +1,69 @@
+import type { KnownAny } from '../types';
+
+/**
+ * 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
+ */
+function buildParams(key: string, value: KnownAny): string[] {
+  if (value === null || value === undefined) {
+    return []; // skip null/undefined values entirely
+  }
+
+  // If value is an object or array, we need to recurse
+  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}[]`
+       */
+      return value.flatMap((v, i) => {
+        const newKey = `${key}[${i}]`;
+        return buildParams(newKey, v);
+      });
+    }
+
+    // Plain object case
+    return Object.keys(value).flatMap((k) => {
+      const newKey = `${key}[${k}]`;
+      return buildParams(newKey, value[k]);
+    });
+  }
+
+  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 "?")
+ */
+export default function serializeQuery(obj: Record<string, KnownAny>): string {
+  if (!obj || typeof obj !== 'object') return '';
+
+  // Collect query segments
+  const segments: string[] = [];
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const value = obj[key];
+      segments.push(...buildParams(key, value));
+    }
+  }
+
+  return segments.join('&');
+}

package/src/worker/createWPC.ts

@@ -1,10 +1,7 @@
 import type { VovkWorkerSchema } from '../types';
 import type { WorkerInput, WorkerOutput, WorkerPromiseInstance } from './types';
 
-export function createWPC<T extends object>(
-  currentWorker: Worker | null,
-  workerSchema: object
-): WorkerPromiseInstance<T> {
+export function createWPC<T extends object>(workerSchema: object, currentWorker?: Worker): WorkerPromiseInstance<T> {
   if (!workerSchema) throw new Error('Worker schema is not provided');
   const schema = workerSchema as T & VovkWorkerSchema;
   const instance = {
@@ -26,7 +23,7 @@ export function createWPC<T extends object>(
     return instance;
   };
 
-  instance.fork = (worker: Worker) => createWPC<T>(worker, schema);
+  instance.fork = (worker: Worker) => createWPC<T>(schema, worker);
 
   for (const methodName of Object.keys(schema.handlers) as (keyof T & string)[]) {
     const { isGenerator } = schema.handlers[methodName];

package/src/worker/index.ts

@@ -1,4 +1,2 @@
-import { worker } from './worker';
-import { createWPC } from './createWPC';
-
-export { worker, createWPC };
+export { worker } from './worker';
+export { createWPC } from './createWPC';