vovk 3.0.0-draft.17 → 3.0.0-draft.170

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/cjs/HttpException.d.ts

@@ -0,0 +1,7 @@
+import type { HttpStatus } from './types.js';
+export declare class HttpException extends Error {
+  statusCode: HttpStatus;
+  message: string;
+  cause?: unknown;
+  constructor(statusCode: HttpStatus, message: string, cause?: unknown);
+}

package/cjs/HttpException.js

@@ -0,0 +1,15 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.HttpException = void 0;
+class HttpException extends Error {
+  statusCode;
+  message;
+  cause;
+  constructor(statusCode, message, cause) {
+    super(message);
+    this.statusCode = statusCode;
+    this.message = message;
+    this.cause = cause;
+  }
+}
+exports.HttpException = HttpException;

package/cjs/JSONLinesResponse.d.ts

@@ -0,0 +1,14 @@
+import type { headers } from 'next/headers';
+import type { KnownAny, StreamAbortMessage } from './types.js';
+import './utils/shim.js';
+export declare class JSONLinesResponse<T> extends Response {
+  isClosed: boolean;
+  controller?: ReadableStreamDefaultController;
+  readonly encoder: TextEncoder;
+  readonly readableStream: ReadableStream;
+  constructor(requestHeaders: Awaited<ReturnType<typeof headers>>, init?: ResponseInit);
+  send(data: T | StreamAbortMessage): void;
+  close(): void;
+  throw(e: KnownAny): void;
+  [Symbol.dispose](): void;
+}

package/cjs/JSONLinesResponse.js

@@ -0,0 +1,57 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.JSONLinesResponse = void 0;
+require('./utils/shim.js');
+class JSONLinesResponse extends Response {
+  isClosed = false;
+  controller;
+  encoder;
+  readableStream;
+  constructor(requestHeaders, init) {
+    const encoder = new TextEncoder();
+    let readableController;
+    const readableStream = new ReadableStream({
+      cancel: () => {
+        this.isClosed = true;
+      },
+      start: (controller) => {
+        readableController = controller;
+      },
+    });
+    if (!requestHeaders) {
+      throw new Error('Request headers are required');
+    }
+    const accept = requestHeaders.get('accept');
+    super(readableStream, {
+      ...init,
+      headers: {
+        ...init?.headers,
+        'Content-Type': accept?.includes('application/jsonl')
+          ? 'application/jsonl; charset=utf-8'
+          : 'text/plain; charset=utf-8',
+      },
+    });
+    this.readableStream = readableStream;
+    this.encoder = encoder;
+    this.controller = readableController;
+  }
+  send(data) {
+    const { controller, encoder } = this;
+    if (this.isClosed) return;
+    return controller?.enqueue(encoder.encode(JSON.stringify(data) + '\n'));
+  }
+  close() {
+    const { controller } = this;
+    if (this.isClosed) return;
+    this.isClosed = true;
+    controller?.close();
+  }
+  throw(e) {
+    this.send({ isError: true, reason: e instanceof Error ? e.message : e });
+    return this.close();
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
+}
+exports.JSONLinesResponse = JSONLinesResponse;

package/cjs/VovkApp.d.ts

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

package/cjs/VovkApp.js

@@ -0,0 +1,199 @@
+'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_js_1 = require('./types.js');
+const HttpException_js_1 = require('./HttpException.js');
+const JSONLinesResponse_js_1 = require('./JSONLinesResponse.js');
+const reqQuery_js_1 = __importDefault(require('./utils/reqQuery.js'));
+const reqMeta_js_1 = __importDefault(require('./utils/reqMeta.js'));
+const reqForm_js_1 = __importDefault(require('./utils/reqForm.js'));
+const headers_1 = require('next/headers');
+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(types_js_1.HttpMethod.GET, req, await data.params);
+  POST = async (req, data) => this.#callMethod(types_js_1.HttpMethod.POST, req, await data.params);
+  PUT = async (req, data) => this.#callMethod(types_js_1.HttpMethod.PUT, req, await data.params);
+  PATCH = async (req, data) => this.#callMethod(types_js_1.HttpMethod.PATCH, req, await data.params);
+  DELETE = async (req, data) => this.#callMethod(types_js_1.HttpMethod.DELETE, req, await data.params);
+  HEAD = async (req, data) => this.#callMethod(types_js_1.HttpMethod.HEAD, req, await data.params);
+  OPTIONS = async (req, data) => this.#callMethod(types_js_1.HttpMethod.OPTIONS, req, await data.params);
+  respond = (status, body, options) => {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: {
+        'content-type': 'application/json',
+        ..._a.getHeadersFromOptions(options),
+      },
+    });
+  };
+  #respondWithError = (statusCode, message, options, cause) => {
+    return this.respond(
+      statusCode,
+      {
+        cause,
+        statusCode,
+        message,
+        isError: true,
+      },
+      options
+    );
+  };
+  #getHandler = ({ handlers, path, params }) => {
+    const methodParams = {};
+    if (Object.keys(params).length === 0) {
+      return { handler: handlers[''], methodParams };
+    }
+    const allMethodKeys = Object.keys(handlers);
+    let methodKeys = [];
+    const pathStr = path.join('/');
+    methodKeys = allMethodKeys
+      // First, try to match literal routes exactly.
+      .filter((p) => {
+        if (p.includes(':')) return false; // Skip parameterized paths
+        return p === pathStr;
+      });
+    if (!methodKeys.length) {
+      methodKeys = allMethodKeys.filter((p) => {
+        const routeSegments = p.split('/');
+        if (routeSegments.length !== path.length) return false;
+        for (let i = 0; i < routeSegments.length; i++) {
+          const routeSegment = routeSegments[i];
+          const pathSegment = path[i];
+          if (routeSegment.startsWith(':')) {
+            const parameter = routeSegment.slice(1);
+            if (parameter in methodParams) {
+              throw new HttpException_js_1.HttpException(
+                types_js_1.HttpStatus.INTERNAL_SERVER_ERROR,
+                `Duplicate parameter "${parameter}" at ${p}`
+              );
+            }
+            // If it's a parameterized segment, capture the parameter value.
+            methodParams[parameter] = pathSegment;
+          } else if (routeSegment !== pathSegment) {
+            // If it's a literal segment and it does not match the corresponding path segment, return false.
+            return false;
+          }
+        }
+        return true;
+      });
+    }
+    if (methodKeys.length > 1) {
+      throw new HttpException_js_1.HttpException(
+        types_js_1.HttpStatus.INTERNAL_SERVER_ERROR,
+        `Conflicting routes found: ${methodKeys.join(', ')}`
+      );
+    }
+    const [methodKey] = methodKeys;
+    if (methodKey) {
+      return { handler: handlers[methodKey], methodParams };
+    }
+    return { handler: null, methodParams };
+  };
+  #callMethod = async (httpMethod, nextReq, params) => {
+    const req = nextReq;
+    const controllers = this.routes[httpMethod];
+    const path = params[Object.keys(params)[0]];
+    const handlers = {};
+    controllers.forEach((staticMethods, controller) => {
+      const prefix = controller._prefix ?? '';
+      if (!controller._activated) {
+        throw new HttpException_js_1.HttpException(
+          types_js_1.HttpStatus.INTERNAL_SERVER_ERROR,
+          `Controller "${controller.name}" found but not activated`
+        );
+      }
+      Object.entries(staticMethods).forEach(([path, staticMethod]) => {
+        const fullPath = [prefix, path].filter(Boolean).join('/');
+        handlers[fullPath] = { staticMethod, controller };
+      });
+    });
+    const { handler, methodParams } = this.#getHandler({ handlers, path, params });
+    if (!handler) {
+      return this.#respondWithError(
+        types_js_1.HttpStatus.NOT_FOUND,
+        `${Object.keys(handlers)} - Route ${path.join('/')} is not found`
+      );
+    }
+    const { staticMethod, controller } = handler;
+    req.vovk = {
+      body: () => req.json(),
+      query: () => (0, reqQuery_js_1.default)(req),
+      meta: (meta) => (0, reqMeta_js_1.default)(req, meta),
+      form: () => (0, reqForm_js_1.default)(req),
+      params: () => methodParams,
+    };
+    try {
+      await staticMethod._options?.before?.call(controller, req);
+      const result = await staticMethod.call(controller, req, methodParams);
+      const isIterator =
+        typeof result === 'object' &&
+        !!result &&
+        ((Reflect.has(result, Symbol.iterator) && typeof result[Symbol.iterator] === 'function') ||
+          (Reflect.has(result, Symbol.asyncIterator) && typeof result[Symbol.asyncIterator] === 'function'));
+      if (isIterator && !(result instanceof Array)) {
+        const streamResponse = new JSONLinesResponse_js_1.JSONLinesResponse(await (0, headers_1.headers)(), {
+          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();
+        })();
+        return streamResponse;
+      }
+      if (result instanceof Response) {
+        return result;
+      }
+      return this.respond(200, result ?? null, 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_js_1.HttpStatus.INTERNAL_SERVER_ERROR;
+        return this.#respondWithError(statusCode, err.message, staticMethod._options, 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,11 @@
+import type { KnownAny, VovkSchema } from '../types.js';
+import type { VovkClientOptions, VovkClient, VovkDefaultFetcherOptions } from './types.js';
+export declare const createRPC: <
+  T,
+  OPTS extends Record<string, KnownAny> = VovkDefaultFetcherOptions<Record<string, never>>,
+>(
+  schema: VovkSchema,
+  segmentName: string,
+  rpcModuleName: string,
+  options?: VovkClientOptions<OPTS>
+) => VovkClient<T, OPTS>;

package/cjs/client/createRPC.js

@@ -0,0 +1,92 @@
+'use strict';
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.createRPC = void 0;
+const fetcher_js_1 = require('./fetcher.js');
+const defaultHandler_js_1 = require('./defaultHandler.js');
+const defaultStreamHandler_js_1 = require('./defaultStreamHandler.js');
+const serializeQuery_js_1 = __importDefault(require('../utils/serializeQuery.js'));
+const trimPath = (path) => path.trim().replace(/^\/|\/$/g, '');
+const getHandlerPath = (endpoint, params, query) => {
+  let result = endpoint;
+  const queryStr = query ? (0, serializeQuery_js_1.default)(query) : null;
+  for (const [key, value] of Object.entries(params ?? {})) {
+    result = result.replace(`:${key}`, value);
+  }
+  return `${result}${queryStr ? '?' : ''}${queryStr}`;
+};
+const createRPC = (schema, segmentName, rpcModuleName, options) => {
+  const segmentNamePath = options?.segmentNameOverride ?? segmentName;
+  const segmentSchema = schema.segments[segmentName];
+  if (!segmentSchema) throw new Error(`Unable to create RPC object. Segment schema is missing. Check client template.`);
+  const controllerSchema = schema.segments[segmentName]?.controllers[rpcModuleName];
+  const client = {};
+  if (!controllerSchema)
+    throw new Error(`Unable to create RPC object. Controller schema is missing. Check client template.`);
+  const controllerPrefix = trimPath(controllerSchema.prefix ?? '');
+  const { fetcher: settingsFetcher = fetcher_js_1.fetcher } = options ?? {};
+  for (const [staticMethodName, handlerSchema] of Object.entries(controllerSchema.handlers)) {
+    const { path, httpMethod, validation } = handlerSchema;
+    const getEndpoint = ({ apiRoot, params, query }) => {
+      const endpoint = [
+        apiRoot.startsWith('http://') || apiRoot.startsWith('https://') || apiRoot.startsWith('/') ? '' : '/',
+        apiRoot,
+        segmentNamePath,
+        getHandlerPath([controllerPrefix, path].filter(Boolean).join('/'), params, query),
+      ]
+        .filter(Boolean)
+        .join('/');
+      return endpoint;
+    };
+    const handler = (input = {}) => {
+      const fetcher = input.fetcher ?? settingsFetcher;
+      const validate = async ({ body, query, params, endpoint }) => {
+        const validateOnClient = input.validateOnClient ?? options?.validateOnClient;
+        if (validateOnClient && validation) {
+          if (typeof validateOnClient !== 'function') {
+            throw new Error('validateOnClient must be a function');
+          }
+          await validateOnClient({ body, query, params, endpoint }, validation, schema);
+        }
+      };
+      const internalOptions = {
+        name: staticMethodName,
+        httpMethod: httpMethod,
+        getEndpoint,
+        validate,
+        defaultHandler: defaultHandler_js_1.defaultHandler,
+        defaultStreamHandler: defaultStreamHandler_js_1.defaultStreamHandler,
+      };
+      const internalInput = {
+        ...options?.defaultOptions,
+        ...input,
+        body: input.body ?? null,
+        query: input.query ?? {},
+        params: input.params ?? {},
+        // TS workaround
+        fetcher: undefined,
+        validateOnClient: undefined,
+      };
+      delete internalInput.fetcher;
+      delete internalInput.validateOnClient;
+      if (!fetcher) throw new Error('Fetcher is not provided');
+      const fetcherPromise = fetcher(internalOptions, internalInput);
+      if (!(fetcherPromise instanceof Promise)) return Promise.resolve(fetcherPromise);
+      return input.transform ? fetcherPromise.then(input.transform) : fetcherPromise;
+    };
+    handler.schema = handlerSchema;
+    handler.controllerSchema = controllerSchema;
+    handler.segmentSchema = segmentSchema;
+    handler.fullSchema = schema;
+    handler.isRPC = true;
+    handler.path = [segmentNamePath, controllerPrefix, path].filter(Boolean).join('/');
+    // @ts-expect-error TODO
+    client[staticMethodName] = handler;
+  }
+  return client;
+};
+exports.createRPC = createRPC;

package/cjs/client/defaultHandler.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultHandler';
+export declare const defaultHandler: (response: Response) => Promise<unknown>;

package/cjs/client/defaultHandler.js

@@ -0,0 +1,25 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.defaultHandler = exports.DEFAULT_ERROR_MESSAGE = void 0;
+const HttpException_js_1 = require('../HttpException.js');
+exports.DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultHandler';
+const defaultHandler = async (response) => {
+  let result;
+  try {
+    result = await response.json();
+  } catch (e) {
+    // handle parsing errors
+    throw new HttpException_js_1.HttpException(response.status, e?.message ?? exports.DEFAULT_ERROR_MESSAGE);
+  }
+  if (!response.ok) {
+    // handle server errors
+    const errorResponse = result;
+    throw new HttpException_js_1.HttpException(
+      response.status,
+      errorResponse?.message ?? exports.DEFAULT_ERROR_MESSAGE,
+      errorResponse?.cause
+    );
+  }
+  return result;
+};
+exports.defaultHandler = defaultHandler;

package/cjs/client/defaultStreamHandler.d.ts

@@ -0,0 +1,4 @@
+import type { VovkStreamAsyncIterable } from './types.js';
+import '../utils/shim.js';
+export declare const DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultStreamHandler';
+export declare const defaultStreamHandler: (response: Response) => Promise<VovkStreamAsyncIterable<unknown>>;