vovk 2.1.1-beta.13 → 2.1.1-beta.20

package/HttpException.ts

@@ -0,0 +1,16 @@
+import type { _HttpStatus as HttpStatus } from './types';
+
+export class _HttpException extends Error {
+  statusCode: HttpStatus;
+
+  message: string;
+
+  cause?: unknown;
+
+  constructor(statusCode: HttpStatus, message: string, cause?: unknown) {
+    super(message);
+    this.statusCode = statusCode;
+    this.message = message;
+    this.cause = cause;
+  }
+}

package/README.md

@@ -1,111 +1,3 @@
-<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>RESTful RPC for Next.js</strong>
-  
-</p>
+# vovk package 
 
-<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!
-</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 />
-
-Example back-end Controller Class:
-
-```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,
-    });
-  }
-}
-```
-
-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', 
-  }),
-})
-```
+Description coming soon.

package/Segment.ts

@@ -0,0 +1,238 @@
+import {
+  _HttpMethod as HttpMethod,
+  _HttpStatus as HttpStatus,
+  type _RouteHandler as RouteHandler,
+  type _VovkErrorResponse as VovkErrorResponse,
+  type _VovkController as VovkController,
+  type _DecoratorOptions as DecoratorOptions,
+  type _VovkRequest as VovkRequest,
+  type _KnownAny as _KnownAny,
+} from './types';
+import { _HttpException as HttpException } from './HttpException';
+import { _StreamResponse as StreamResponse } from './StreamResponse';
+import reqQuery from './utils/reqQuery';
+import reqMeta from './utils/reqMeta';
+
+export class _Segment {
+  private static getHeadersFromOptions(options?: DecoratorOptions) {
+    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: Record<HttpMethod, Map<VovkController, Record<string, RouteHandler>>> = {
+    GET: new Map(),
+    POST: new Map(),
+    PUT: new Map(),
+    PATCH: new Map(),
+    DELETE: new Map(),
+    HEAD: new Map(),
+    OPTIONS: new Map(),
+  };
+
+  GET = (req: VovkRequest, data: { params: Record<string, string[]> }) => {
+    return this.#callMethod(HttpMethod.GET, req, data.params);
+  };
+  POST = (req: VovkRequest, data: { params: Record<string, string[]> }) =>
+    this.#callMethod(HttpMethod.POST, req, data.params);
+
+  PUT = (req: VovkRequest, data: { params: Record<string, string[]> }) =>
+    this.#callMethod(HttpMethod.PUT, req, data.params);
+
+  PATCH = (req: VovkRequest, data: { params: Record<string, string[]> }) =>
+    this.#callMethod(HttpMethod.PATCH, req, data.params);
+
+  DELETE = (req: VovkRequest, data: { params: Record<string, string[]> }) =>
+    this.#callMethod(HttpMethod.DELETE, req, data.params);
+
+  HEAD = (req: VovkRequest, data: { params: Record<string, string[]> }) =>
+    this.#callMethod(HttpMethod.HEAD, req, data.params);
+
+  OPTIONS = (req: VovkRequest, data: { params: Record<string, string[]> }) =>
+    this.#callMethod(HttpMethod.OPTIONS, req, data.params);
+
+  #respond = (status: HttpStatus, body: unknown, options?: DecoratorOptions) => {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: {
+        'Content-Type': 'application/json',
+        ..._Segment.getHeadersFromOptions(options),
+      },
+    });
+  };
+
+  #respondWithError = (statusCode: HttpStatus, message: string, options?: DecoratorOptions) => {
+    return this.#respond(
+      statusCode,
+      {
+        statusCode,
+        message,
+        isError: true,
+      } satisfies VovkErrorResponse,
+      options
+    );
+  };
+
+  #callMethod = async (httpMethod: HttpMethod, req: VovkRequest, params: Record<string, string[]>) => {
+    const controllers = this._routes[httpMethod];
+    const methodParams: Record<string, string> = {};
+    const path = params[Object.keys(params)[0]];
+
+    if (params[Object.keys(params)[0]]?.[0] === '_vovk-ping_') {
+      return this.#respond(200, { message: 'pong' });
+    }
+
+    const handlers: Record<string, { staticMethod: RouteHandler; controller: VovkController }> = {};
+    controllers.forEach((staticMethods, controller) => {
+      const prefix = controller._prefix ?? '';
+
+      if (!controller._activated) {
+        throw new HttpException(
+          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 getHandler = () => {
+      if (Object.keys(params).length === 0) {
+        return handlers[''];
+      }
+
+      const allMethodKeys = Object.keys(handlers);
+
+      let methodKeys: string[] = [];
+
+      methodKeys = allMethodKeys
+        // First, try to match literal routes exactly.
+        .filter((p) => {
+          if (p.includes(':')) return false; // Skip parameterized paths
+          return p === path.join('/');
+        });
+
+      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(HttpStatus.INTERNAL_SERVER_ERROR, `Duplicate parameter "${parameter}"`);
+              }
+
+              // 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(HttpStatus.INTERNAL_SERVER_ERROR, `Conflicting routes found: ${methodKeys.join(', ')}`);
+      }
+
+      const [methodKey] = methodKeys;
+
+      if (methodKey) {
+        return handlers[methodKey];
+      }
+
+      return null;
+    };
+
+    const handler = getHandler();
+
+    if (!handler) {
+      return this.#respondWithError(HttpStatus.NOT_FOUND, `Route ${path.join('/')} is not found`);
+    }
+
+    const { staticMethod, controller } = handler;
+
+    req.vovk = {
+      body: () => req.json(),
+      query: () => reqQuery(req),
+      meta: <T = _KnownAny>(metadata?: T | null) => reqMeta<T>(req, metadata),
+    };
+
+    try {
+      const result = await staticMethod.call(controller, req, methodParams);
+
+      const isIterator =
+        typeof result === 'object' &&
+        !!result &&
+        ((Reflect.has(result, Symbol.iterator) &&
+          typeof (result as Iterable<unknown>)[Symbol.iterator] === 'function') ||
+          (Reflect.has(result, Symbol.asyncIterator) &&
+            typeof (result as AsyncIterable<unknown>)[Symbol.asyncIterator] === 'function'));
+
+      if (isIterator && !(result instanceof Array)) {
+        const streamResponse = new StreamResponse({
+          headers: {
+            ...StreamResponse.defaultHeaders,
+            ..._Segment.getHeadersFromOptions(staticMethod._options),
+          },
+        });
+
+        void (async () => {
+          try {
+            for await (const chunk of result as AsyncGenerator<unknown>) {
+              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 as HttpException;
+      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 ?? HttpStatus.INTERNAL_SERVER_ERROR;
+        return this.#respondWithError(statusCode, err.message, staticMethod._options);
+      }
+
+      throw e; // if NEXT_REDIRECT or NEXT_NOT_FOUND, rethrow it
+    }
+  };
+}

package/StreamResponse.ts

@@ -0,0 +1,61 @@
+import { _KnownAny as KnownAny, _StreamAbortMessage as StreamAbortMessage } from './types';
+import './utils/shim';
+
+export class _StreamResponse<T> extends Response {
+  public static defaultHeaders = {
+    'Content-Type': 'text/plain; charset=utf-8',
+  };
+
+  public isClosed = false;
+
+  public controller?: ReadableStreamDefaultController;
+
+  public readonly encoder: TextEncoder;
+
+  public readonly readableStream: ReadableStream;
+
+  constructor(init?: ResponseInit) {
+    const encoder = new TextEncoder();
+    let readableController: ReadableStreamDefaultController;
+
+    const readableStream = new ReadableStream({
+      cancel: () => {
+        this.isClosed = true;
+      },
+      start: (controller) => {
+        readableController = controller;
+      },
+    });
+
+    super(readableStream, {
+      ...init,
+      headers: init?.headers ?? _StreamResponse.defaultHeaders,
+    });
+
+    this.readableStream = readableStream;
+    this.encoder = encoder;
+    this.controller = readableController!;
+  }
+
+  public send(data: T | StreamAbortMessage) {
+    const { controller, encoder } = this;
+    if (this.isClosed) return;
+    return controller?.enqueue(encoder.encode(JSON.stringify(data) + '\n'));
+  }
+
+  public close() {
+    const { controller } = this;
+    if (this.isClosed) return;
+    this.isClosed = true;
+    controller?.close();
+  }
+
+  public throw(e: KnownAny) {
+    this.send({ isError: true, reason: e instanceof Error ? e.message : (e as unknown) });
+    return this.close();
+  }
+
+  public [Symbol.dispose]() {
+    this.close();
+  }
+}

package/client/clientizeController.ts

@@ -0,0 +1,141 @@
+import {
+  type _VovkControllerMetadata as VovkControllerMetadata,
+  type _ControllerStaticMethod as ControllerStaticMethod,
+  type _VovkControllerParams as VovkControllerParams,
+  type _VovkControllerQuery as VovkControllerQuery,
+  type _KnownAny as KnownAny,
+} from '../types';
+import {
+  type _VovkClientOptions as VovkClientOptions,
+  type _VovkClient as VovkClient,
+  type _VovkDefaultFetcherOptions as VovkDefaultFetcherOptions,
+  _VovkValidateOnClient,
+} from './types';
+
+import defaultFetcher from './defaultFetcher';
+import { _defaultHandler as defaultHandler } from './defaultHandler';
+import { _defaultStreamHandler as defaultStreamHandler } from './defaultStreamHandler';
+
+export const ARRAY_QUERY_KEY = '_vovkarr';
+
+const trimPath = (path: string) => path.trim().replace(/^\/|\/$/g, '');
+
+const getHandlerPath = <T extends ControllerStaticMethod>(
+  endpoint: string,
+  params?: VovkControllerParams<T>,
+  query?: VovkControllerQuery<T>
+) => {
+  let result = endpoint;
+  for (const [key, value] of Object.entries(params ?? {})) {
+    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 (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(ARRAY_QUERY_KEY, arrayKeys.join(','));
+  }
+
+  return `${result}${hasQuery ? '?' : ''}${searchParams.toString()}`;
+};
+
+export const _clientizeController = <T, OPTS extends Record<string, KnownAny> = VovkDefaultFetcherOptions>(
+  givenController: VovkControllerMetadata,
+  segmentName: string,
+  options?: VovkClientOptions<OPTS>
+): VovkClient<T, OPTS> => {
+  const controller = givenController as T & VovkControllerMetadata;
+  const client = {} as VovkClient<T, OPTS>;
+  if (!controller) throw new Error(`Unable to clientize. Controller metadata is not provided`);
+  const metadata = controller._handlers;
+  if (!metadata)
+    throw new Error(`Unable to clientize. No metadata for controller ${String(controller?._controllerName)}`);
+  const controllerPrefix = trimPath(controller._prefix ?? '');
+  const { fetcher: settingsFetcher = defaultFetcher } = options ?? {};
+
+  for (const [staticMethodName, { path, httpMethod, clientValidators }] of Object.entries(metadata)) {
+    const getEndpoint = ({
+      prefix,
+      params,
+      query,
+    }: {
+      prefix: string;
+      params: { [key: string]: string };
+      query: { [key: string]: string };
+    }) => {
+      const mainPrefix =
+        (prefix.startsWith('http://') || prefix.startsWith('https://') || prefix.startsWith('/') ? '' : '/') +
+        (prefix.endsWith('/') ? prefix : `${prefix}/`) +
+        (segmentName ? `${segmentName}/` : '');
+      return mainPrefix + getHandlerPath([controllerPrefix, path].filter(Boolean).join('/'), params, query);
+    };
+
+    const handler = (
+      input: {
+        body?: unknown;
+        query?: { [key: string]: string };
+        params?: { [key: string]: string };
+        validateOnClient?: _VovkValidateOnClient;
+        fetcher?: VovkClientOptions<OPTS>['fetcher'];
+        transform?: (response: unknown) => unknown;
+      } & OPTS = {} as OPTS
+    ) => {
+      const fetcher = input.fetcher ?? settingsFetcher;
+      const validate = async ({ body, query, endpoint }: { body?: unknown; query?: unknown; endpoint: string }) => {
+        await (input.validateOnClient ?? options?.validateOnClient)?.(
+          { body, query, endpoint },
+          clientValidators ?? {}
+        );
+      };
+
+      const internalOptions: Parameters<typeof fetcher>[0] = {
+        name: staticMethodName as keyof T,
+        httpMethod,
+        getEndpoint,
+        validate,
+        defaultHandler,
+        defaultStreamHandler,
+      };
+      const internalInput = {
+        ...options?.defaultOptions,
+        ...input,
+        body: input.body ?? null,
+        query: input.query ?? {},
+        params: input.params ?? {},
+        segmentName,
+        // 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) as Promise<unknown>;
+
+      if (!(fetcherPromise instanceof Promise)) return Promise.resolve(fetcherPromise);
+
+      return input.transform ? fetcherPromise.then(input.transform) : fetcherPromise;
+    };
+
+    // @ts-expect-error TODO: Fix this
+    client[staticMethodName] = handler;
+  }
+
+  return client;
+};

package/client/defaultFetcher.ts

@@ -0,0 +1,60 @@
+import type {
+  _VovkDefaultFetcherOptions as VovkDefaultFetcherOptions,
+  _VovkClientFetcher as VovkClientFetcher,
+} from './types';
+import { _HttpStatus as HttpStatus } from '../types';
+import { _HttpException as HttpException } from '../HttpException';
+
+export const DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultFetcher';
+
+// defaultFetcher uses HttpException class to throw errors of fake HTTP status 0 if client-side error occurs
+// For normal HTTP errors, it uses message and status code from the response of VovkErrorResponse type
+const defaultFetcher: VovkClientFetcher<VovkDefaultFetcherOptions> = async (
+  { httpMethod, getEndpoint, validate, defaultHandler, defaultStreamHandler },
+  { params, query, body, prefix = '/api', segmentName, ...options }
+) => {
+  const endpoint = getEndpoint({ prefix, segmentName, params, query });
+
+  if (!options.disableClientValidation) {
+    try {
+      await validate({ body, query, endpoint });
+    } catch (e) {
+      // if HttpException is thrown, rethrow it
+      if (e instanceof HttpException) throw e;
+      // otherwise, throw HttpException with status 0
+      throw new HttpException(HttpStatus.NULL, (e as Error).message ?? DEFAULT_ERROR_MESSAGE);
+    }
+  }
+
+  const init: RequestInit = {
+    method: httpMethod,
+    ...options,
+  };
+
+  if (body instanceof FormData) {
+    init.body = body as BodyInit;
+  } else if (body) {
+    init.body = JSON.stringify(body);
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetch(endpoint, init);
+  } catch (e) {
+    // handle network errors
+    throw new HttpException(HttpStatus.NULL, (e as Error)?.message ?? DEFAULT_ERROR_MESSAGE);
+  }
+
+  if (response.headers.get('content-type')?.includes('application/json')) {
+    return defaultHandler(response);
+  }
+
+  if (response.headers.get('content-type')?.includes('text/plain; charset=utf-8')) {
+    return defaultStreamHandler(response);
+  }
+
+  return response;
+};
+
+export default defaultFetcher;

package/client/defaultHandler.ts

@@ -0,0 +1,22 @@
+import { type _VovkErrorResponse as VovkErrorResponse } from '../types';
+import { _HttpException as HttpException } from '../HttpException';
+
+export const DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultHandler';
+
+export const _defaultHandler = async (response: Response) => {
+  let result: unknown;
+
+  try {
+    result = await response.json();
+  } catch (e) {
+    // handle parsing errors
+    throw new HttpException(response.status, (e as Error)?.message ?? DEFAULT_ERROR_MESSAGE);
+  }
+
+  if (!response.ok) {
+    // handle server errors
+    throw new HttpException(response.status, (result as VovkErrorResponse)?.message ?? DEFAULT_ERROR_MESSAGE);
+  }
+
+  return result;
+};