vovk 3.0.0-draft.46 → 3.0.0-draft.460

package/LICENSE

@@ -16,7 +16,7 @@
     "nextjs",
     "router"
   ],
-  "author": "Andrii Gubanov",
+  "author": "Andrey Gubanov",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/finom/vovk/issues"

package/README.md

@@ -4,109 +4,21 @@
     <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>RESTful RPC for Next.js</strong>
-  
+  <strong>RESTful + RPC = ♥️</strong>
 </p>
 
 <p align="center">
-  Transforms <a href="https://nextjs.org/docs/app">Next.js</a> into a powerful REST API platform with RPC capabilities. 
-  <br><br>
-  ℹ️ Improved syntax for Zod and DTO validation is coming soon. Stay tuned!
+  Back-end meta-framework for <a href="https://nextjs.org/docs/app">Next.js</a>
 </p>
 
-<p align="center">
-  <a href="https://vovk.dev/">Documentation</a>&nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://discord.gg/qdT8WEHUuP">Discord</a>&nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://github.com/finom/vovk-examples">Code Examples</a>&nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://github.com/finom/vovk-zod">vovk-zod</a>&nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://github.com/finom/vovk-hello-world">vovk-hello-world</a>&nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://github.com/finom/vovk-react-native-example">vovk-react-native-example</a>
-</p>
-<p align="center">
-  <a href="https://www.npmjs.com/package/vovk"><img src="https://badge.fury.io/js/vovk.svg" alt="npm version" /></a>&nbsp;
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg" alt="TypeScript" /></a>&nbsp;
-  <a href="https://github.com/finom/vovk/actions/workflows/main.yml"><img src="https://github.com/finom/vovk/actions/workflows/main.yml/badge.svg" alt="Build status" /></a>
-</p>
+---
 
- <br />
+## vovk [![npm version](https://badge.fury.io/js/vovk.svg)](https://www.npmjs.com/package/vovk)
 
-Example back-end Controller Class:
+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.
 
-```ts
-// /src/modules/post/PostController.ts
-import { get, prefix, type VovkRequest } from 'vovk';
-import PostService from './PostService';
-
-@prefix('posts')
-export default class PostController {
-  /**
-   * Create a comment on a post
-   * POST /api/posts/:postId/comments
-   */
-  @post(':postId/comments')
-  static async createComment(
-    // decorate NextRequest type with body and query types
-    req: VovkRequest<{ content: string; userId: string }, { notificationType: 'push' | 'email' }>,
-    { postId }: { postId: string } // params
-  ) {
-    // use standard Next.js API to get body and query
-    const { content, userId } = await req.json();
-    const notificationType = req.nextUrl.searchParams.get('notificationType');
-
-    // perform the request to the database in a custom service
-    return PostService.createComment({
-      postId,
-      content,
-      userId,
-      notificationType,
-    });
-  }
-}
+```sh
+npm install vovk
 ```
 
-Example component that uses the auto-generated client library:
-
-```tsx
-'use client';
-import { useState } from 'react';
-import { PostController } from 'vovk-client';
-import type { VovkReturnType } from 'vovk';
-
-export default function Example() {
-  const [response, setResponse] = useState<VovkReturnType<typeof PostController.createComment>>();
-
-  return (
-    <>
-      <button
-        onClick={async () =>
-          setResponse(
-            await PostController.createComment({
-              body: {
-                content: 'Hello, World!',
-                userId: '1',
-              },
-              params: { postId: '69' },
-              query: { notificationType: 'push' },
-            })
-          )
-        }
-      >
-        Post a comment
-      </button>
-      <div>{JSON.stringify(response)}</div>
-    </>
-  );
-}
-```
-
-Alternatively, the resource can be fetched wit the regular `fetch` function:
-
-```ts
-fetch('/api/posts/69?notificationType=push', {
-  method: 'POST',
-  body: JSON.stringify({
-    content: 'Hello, World!',
-    userId: '1',
-  }),
-});
-```
+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/bin/index.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+
+console.warn(`Vovk CLI requires vovk-cli package. Running "npx vovk-cli ${process.argv.slice(2).join(' ')}" instead.`);
+
+spawn('npx', ['vovk-cli', ...process.argv.slice(2)], { stdio: 'inherit' }).on('exit', (code) => {
+  process.exit(code);
+});

package/cjs/JSONLinesResponse.d.ts

@@ -0,0 +1,19 @@
+import type { KnownAny, StreamAbortMessage } from './types';
+import './utils/shim';
+export declare class JSONLinesResponse<T> extends Response {
+    isClosed: boolean;
+    controller?: ReadableStreamDefaultController | null;
+    readonly encoder: TextEncoder | null;
+    readonly readableStream: ReadableStream | null;
+    private iteratorQueue;
+    private iteratorResolvers;
+    constructor(request?: Request, init?: ResponseInit);
+    send: (data: T | StreamAbortMessage) => void;
+    close: () => void;
+    throw: (e: KnownAny) => void;
+    [Symbol.dispose]: () => void;
+    [Symbol.asyncDispose]: () => void;
+    [Symbol.asyncIterator]: () => {
+        next: () => Promise<IteratorResult<T | StreamAbortMessage>>;
+    };
+}

package/cjs/JSONLinesResponse.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSONLinesResponse = void 0;
+require("./utils/shim");
+class JSONLinesResponse extends Response {
+    isClosed = false;
+    controller;
+    encoder;
+    readableStream;
+    iteratorQueue = [];
+    iteratorResolvers = [];
+    constructor(request, init) {
+        const encoder = new TextEncoder();
+        let readableController;
+        const readableStream = new ReadableStream({
+            cancel: () => {
+                this.isClosed = true;
+            },
+            start: (controller) => {
+                readableController = controller;
+            },
+        });
+        const accept = request?.headers?.get('accept');
+        super(readableStream, {
+            ...init,
+            headers: {
+                'content-type': !request || accept?.includes('application/jsonl')
+                    ? 'application/jsonl; charset=utf-8'
+                    : 'text/plain; charset=utf-8',
+                ...init?.headers,
+            },
+        });
+        this.readableStream = request ? readableStream : null;
+        this.encoder = request ? encoder : null;
+        this.controller = request ? readableController : null;
+        request?.signal?.addEventListener('abort', this.close, { once: true });
+        // this will make promise on the client-side to resolve immediately
+        this.controller?.enqueue(encoder?.encode(''));
+    }
+    send = (data) => {
+        const { controller, encoder } = this;
+        if (this.isClosed)
+            return;
+        // Enqueue to the ReadableStream
+        controller?.enqueue(encoder?.encode(JSON.stringify(data) + '\n'));
+        // Handle async iterator consumers
+        if (this.iteratorResolvers.length > 0) {
+            // If there's a pending next() call, resolve it immediately
+            const resolve = this.iteratorResolvers.shift();
+            resolve({ value: data, done: false });
+        }
+        else {
+            // Otherwise, queue the value for later consumption
+            this.iteratorQueue.push(data);
+        }
+    };
+    close = () => {
+        const { controller } = this;
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        controller?.close();
+        // Resolve all pending iterator next() calls with done: true
+        while (this.iteratorResolvers.length > 0) {
+            const resolve = this.iteratorResolvers.shift();
+            resolve({ done: true, value: undefined });
+        }
+    };
+    throw = (e) => {
+        this.send({ isError: true, reason: e instanceof Error ? e.message : e });
+        return this.close();
+    };
+    [Symbol.dispose] = () => this.close();
+    [Symbol.asyncDispose] = () => this.close();
+    [Symbol.asyncIterator] = () => {
+        return {
+            next: async () => {
+                // If we have queued values, return them immediately
+                if (this.iteratorQueue.length > 0) {
+                    const value = this.iteratorQueue.shift();
+                    return { value, done: false };
+                }
+                // If the stream is closed and no more values, we're done
+                if (this.isClosed) {
+                    return { done: true, value: undefined };
+                }
+                // Otherwise, wait for the next value or close
+                return new Promise((resolve) => {
+                    this.iteratorResolvers.push(resolve);
+                });
+            },
+        };
+    };
+}
+exports.JSONLinesResponse = JSONLinesResponse;

package/{VovkApp.d.ts → cjs/VovkApp.d.ts}

@@ -1,28 +1,34 @@
+import type { NextRequest } from 'next/server';
 import { HttpMethod, HttpStatus, type RouteHandler, type VovkController, type DecoratorOptions, type VovkRequest } from './types';
 export declare class VovkApp {
     #private;
     private static getHeadersFromOptions;
     routes: Record<HttpMethod, Map<VovkController, Record<string, RouteHandler>>>;
-    GET: (req: VovkRequest, data: {
+    GET: (req: NextRequest, data: {
         params: Promise<Record<string, string[]>>;
     }) => Promise<Response>;
-    POST: (req: VovkRequest, data: {
+    POST: (req: NextRequest, data: {
         params: Promise<Record<string, string[]>>;
     }) => Promise<Response>;
-    PUT: (req: VovkRequest, data: {
+    PUT: (req: NextRequest, data: {
         params: Promise<Record<string, string[]>>;
     }) => Promise<Response>;
-    PATCH: (req: VovkRequest, data: {
+    PATCH: (req: NextRequest, data: {
         params: Promise<Record<string, string[]>>;
     }) => Promise<Response>;
-    DELETE: (req: VovkRequest, data: {
+    DELETE: (req: NextRequest, data: {
         params: Promise<Record<string, string[]>>;
     }) => Promise<Response>;
-    HEAD: (req: VovkRequest, data: {
+    HEAD: (req: NextRequest, data: {
         params: Promise<Record<string, string[]>>;
     }) => Promise<Response>;
-    OPTIONS: (req: VovkRequest, data: {
+    OPTIONS: (req: NextRequest, data: {
         params: Promise<Record<string, string[]>>;
     }) => Promise<Response>;
-    respond: (status: HttpStatus, body: unknown, options?: DecoratorOptions) => Response;
+    respond: ({ statusCode, responseBody, options, }: {
+        req: VovkRequest;
+        statusCode: HttpStatus;
+        responseBody: unknown;
+        options?: DecoratorOptions;
+    }) => Promise<Response>;
 }

package/cjs/VovkApp.js

@@ -0,0 +1,304 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VovkApp = void 0;
+const types_1 = require("./types");
+const HttpException_1 = require("./HttpException");
+const JSONLinesResponse_1 = require("./JSONLinesResponse");
+const reqQuery_1 = __importDefault(require("./utils/reqQuery"));
+const reqMeta_1 = __importDefault(require("./utils/reqMeta"));
+const reqForm_1 = __importDefault(require("./utils/reqForm"));
+class VovkApp {
+    static getHeadersFromOptions(options) {
+        if (!options)
+            return {};
+        const corsHeaders = {
+            'access-control-allow-origin': '*',
+            'access-control-allow-methods': 'GET, POST, PUT, DELETE, OPTIONS, HEAD',
+            'access-control-allow-headers': 'content-type, authorization',
+        };
+        const headers = {
+            ...(options.cors ? corsHeaders : {}),
+            ...(options.headers ?? {}),
+        };
+        return headers;
+    }
+    routes = {
+        GET: new Map(),
+        POST: new Map(),
+        PUT: new Map(),
+        PATCH: new Map(),
+        DELETE: new Map(),
+        HEAD: new Map(),
+        OPTIONS: new Map(),
+    };
+    GET = async (req, data) => this.#callMethod({ httpMethod: types_1.HttpMethod.GET, req, params: await data.params });
+    POST = async (req, data) => this.#callMethod({ httpMethod: types_1.HttpMethod.POST, req, params: await data.params });
+    PUT = async (req, data) => this.#callMethod({ httpMethod: types_1.HttpMethod.PUT, req, params: await data.params });
+    PATCH = async (req, data) => this.#callMethod({ httpMethod: types_1.HttpMethod.PATCH, req, params: await data.params });
+    DELETE = async (req, data) => this.#callMethod({ httpMethod: types_1.HttpMethod.DELETE, req, params: await data.params });
+    HEAD = async (req, data) => this.#callMethod({ httpMethod: types_1.HttpMethod.HEAD, req, params: await data.params });
+    OPTIONS = async (req, data) => this.#callMethod({ httpMethod: types_1.HttpMethod.OPTIONS, req, params: await data.params });
+    respond = async ({ statusCode, responseBody, options, }) => {
+        const response = new Response(JSON.stringify(responseBody), {
+            status: statusCode,
+            headers: {
+                'content-type': 'application/json',
+                ..._a.getHeadersFromOptions(options),
+            },
+        });
+        return response;
+    };
+    #respondWithError = ({ req, statusCode, message, options, cause, }) => {
+        return this.respond({
+            req,
+            statusCode,
+            responseBody: {
+                cause,
+                statusCode,
+                message,
+                isError: true,
+            },
+            options,
+        });
+    };
+    #routeRegexCache = new Map();
+    #routeSegmentsCache = new Map();
+    #routeParamPositionsCache = new Map();
+    #routeMatchCache = new Map();
+    #getHandler = ({ handlers, path, params, }) => {
+        let methodParams = {};
+        if (Object.keys(params).length === 0) {
+            return { handler: handlers[''], methodParams };
+        }
+        const pathStr = path.join('/');
+        // Fast path: Check if this exact path has been matched before
+        const cachedMatch = this.#routeMatchCache.get(pathStr);
+        if (cachedMatch) {
+            return {
+                handler: handlers[cachedMatch.route],
+                methodParams: cachedMatch.params,
+            };
+        }
+        // Check for direct static route match
+        let methodKey = handlers[pathStr] ? pathStr : null;
+        if (!methodKey) {
+            const methodKeys = [];
+            const pathLength = path.length;
+            // First pass: group routes by length for quick filtering
+            const routesByLength = new Map();
+            for (const p of Object.keys(handlers)) {
+                let routeSegments = this.#routeSegmentsCache.get(p);
+                if (!routeSegments) {
+                    routeSegments = p.split('/');
+                    this.#routeSegmentsCache.set(p, routeSegments);
+                    // Pre-compute parameter positions for routes with parameters
+                    if (p.includes('{')) {
+                        const paramPositions = [];
+                        for (let i = 0; i < routeSegments.length; i++) {
+                            const segment = routeSegments[i];
+                            if (segment.includes('{')) {
+                                const paramMatch = segment.match(/\{(\w+)\}/);
+                                if (paramMatch) {
+                                    paramPositions.push({ index: i, paramName: paramMatch[1] });
+                                }
+                            }
+                        }
+                        this.#routeParamPositionsCache.set(p, paramPositions);
+                    }
+                }
+                const segmentLength = routeSegments.length;
+                if (segmentLength !== pathLength)
+                    continue;
+                const lengthRoutes = routesByLength.get(segmentLength) || [];
+                lengthRoutes.push(p);
+                routesByLength.set(segmentLength, lengthRoutes);
+            }
+            // Only process routes with matching segment count
+            const candidateRoutes = routesByLength.get(pathLength) || [];
+            for (const p of candidateRoutes) {
+                const routeSegments = this.#routeSegmentsCache.get(p);
+                const params = {};
+                // Fast path for routes with parameters
+                const paramPositions = this.#routeParamPositionsCache.get(p);
+                if (paramPositions) {
+                    let isMatch = true;
+                    // First check all non-parameter segments for a quick fail
+                    for (let i = 0; i < routeSegments.length; i++) {
+                        const routeSegment = routeSegments[i];
+                        if (!routeSegment.includes('{') && routeSegment !== path[i]) {
+                            isMatch = false;
+                            break;
+                        }
+                    }
+                    if (!isMatch)
+                        continue;
+                    // Now process parameter segments
+                    for (const { index, paramName } of paramPositions) {
+                        const routeSegment = routeSegments[index];
+                        const pathSegment = path[index];
+                        let regex = this.#routeRegexCache.get(routeSegment);
+                        if (!regex) {
+                            const regexPattern = routeSegment
+                                .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                                .replace(/\\{(\w+)\\}/g, '(?<$1>[^/]+)');
+                            regex = new RegExp(`^${regexPattern}$`);
+                            this.#routeRegexCache.set(routeSegment, regex);
+                        }
+                        const values = pathSegment.match(regex)?.groups;
+                        if (!values) {
+                            isMatch = false;
+                            break;
+                        }
+                        if (paramName in params) {
+                            throw new HttpException_1.HttpException(types_1.HttpStatus.INTERNAL_SERVER_ERROR, `Duplicate parameter "${paramName}" at ${p}`);
+                        }
+                        params[paramName] = values[paramName];
+                    }
+                    if (isMatch) {
+                        methodParams = params;
+                        methodKeys.push(p);
+                    }
+                }
+                else {
+                    // Static route - simple equality comparison for all segments
+                    let isMatch = true;
+                    for (let i = 0; i < routeSegments.length; i++) {
+                        if (routeSegments[i] !== path[i]) {
+                            isMatch = false;
+                            break;
+                        }
+                    }
+                    if (isMatch) {
+                        methodKeys.push(p);
+                    }
+                }
+            }
+            if (methodKeys.length > 1) {
+                throw new HttpException_1.HttpException(types_1.HttpStatus.INTERNAL_SERVER_ERROR, `Conflicting routes found: ${methodKeys.join(', ')}`);
+            }
+            [methodKey] = methodKeys;
+            // Cache successful matches
+            if (methodKey) {
+                this.#routeMatchCache.set(pathStr, { route: methodKey, params: methodParams });
+            }
+        }
+        if (methodKey) {
+            return { handler: handlers[methodKey], methodParams };
+        }
+        return { handler: null, methodParams };
+    };
+    #allHandlers = {};
+    #collectHandlers = (httpMethod) => {
+        const controllers = this.routes[httpMethod];
+        const handlers = {};
+        controllers.forEach((staticMethods, controller) => {
+            const prefix = controller._prefix ?? '';
+            Object.entries(staticMethods ?? {}).forEach(([path, staticMethod]) => {
+                const fullPath = [prefix, path].filter(Boolean).join('/');
+                handlers[fullPath] = { staticMethod, controller };
+            });
+        });
+        return handlers;
+    };
+    #callMethod = async ({ httpMethod, req: nextReq, params, }) => {
+        const req = nextReq;
+        const path = params[Object.keys(params)[0]];
+        const handlers = this.#allHandlers[httpMethod] ?? this.#collectHandlers(httpMethod);
+        this.#allHandlers[httpMethod] = handlers;
+        let headerList;
+        try {
+            headerList = nextReq.headers;
+        }
+        catch {
+            // this is static rendering environment, headers are not available
+            headerList = null;
+        }
+        const xMeta = headerList?.get('x-meta');
+        const xMetaHeader = xMeta && JSON.parse(xMeta);
+        if (xMetaHeader)
+            (0, reqMeta_1.default)(req, { xMetaHeader });
+        const { handler, methodParams } = this.#getHandler({ handlers, path, params });
+        if (!handler) {
+            return this.#respondWithError({
+                req,
+                statusCode: types_1.HttpStatus.NOT_FOUND,
+                message: `${Object.keys(handlers)} - Route ${path.join('/')} is not found`,
+            });
+        }
+        const { staticMethod, controller } = handler;
+        const { _onSuccess: onSuccess, _onBefore: onBefore } = controller;
+        req.vovk = {
+            body: () => req.json(),
+            query: () => (0, reqQuery_1.default)(req),
+            meta: (meta) => (0, reqMeta_1.default)(req, meta),
+            form: () => (0, reqForm_1.default)(req),
+            params: () => methodParams,
+        };
+        try {
+            await staticMethod._options?.before?.call(controller, req);
+            await onBefore?.(req);
+            const result = await staticMethod.call(controller, req, methodParams);
+            if (result instanceof Response) {
+                await onSuccess?.(result, req);
+                return result;
+            }
+            const isIterator = typeof result === 'object' &&
+                !!result &&
+                !(result instanceof Array) &&
+                ((Reflect.has(result, Symbol.iterator) &&
+                    typeof result[Symbol.iterator] === 'function') ||
+                    (Reflect.has(result, Symbol.asyncIterator) &&
+                        typeof result[Symbol.asyncIterator] === 'function'));
+            if (isIterator) {
+                const streamResponse = new JSONLinesResponse_1.JSONLinesResponse(req, {
+                    headers: {
+                        ..._a.getHeadersFromOptions(staticMethod._options),
+                    },
+                });
+                void (async () => {
+                    try {
+                        for await (const chunk of result) {
+                            streamResponse.send(chunk);
+                        }
+                    }
+                    catch (e) {
+                        return streamResponse.throw(e);
+                    }
+                    return streamResponse.close();
+                })();
+                await onSuccess?.(streamResponse, req);
+                return streamResponse;
+            }
+            const responseBody = result ?? null;
+            await onSuccess?.(responseBody, req);
+            return this.respond({ req, statusCode: 200, responseBody, options: staticMethod._options });
+        }
+        catch (e) {
+            const err = e;
+            try {
+                await controller._onError?.(err, req);
+            }
+            catch (onErrorError) {
+                // eslint-disable-next-line no-console
+                console.error(onErrorError);
+            }
+            if (err.message !== 'NEXT_REDIRECT' && err.message !== 'NEXT_NOT_FOUND') {
+                const statusCode = err.statusCode || types_1.HttpStatus.INTERNAL_SERVER_ERROR;
+                return this.#respondWithError({
+                    req,
+                    statusCode,
+                    message: err.message,
+                    options: staticMethod._options,
+                    cause: err.cause,
+                });
+            }
+            throw e; // if NEXT_REDIRECT or NEXT_NOT_FOUND, rethrow it
+        }
+    };
+}
+exports.VovkApp = VovkApp;
+_a = VovkApp;

package/cjs/client/createRPC.d.ts

@@ -0,0 +1,5 @@
+import type { KnownAny } from '../types';
+import type { VovkRPCModule, VovkFetcher, VovkFetcherOptions } from './types';
+export declare const createRPC: <T, OPTS extends Record<string, KnownAny> = Record<string, never>>(givenSchema: unknown, segmentName: string, rpcModuleName: string, givenFetcher?: VovkFetcher<OPTS> | Promise<{
+    fetcher: VovkFetcher<OPTS>;
+}>, options?: VovkFetcherOptions<OPTS>) => VovkRPCModule<T, OPTS>;