vovk 3.0.0-beta.4 → 3.0.0-beta.6

package/client/types.ts

@@ -0,0 +1,116 @@
+import type {
+  _KnownAny as KnownAny,
+  _HttpMethod as HttpMethod,
+  _ControllerStaticMethod,
+  _VovkControllerBody,
+  _VovkControllerQuery,
+  _VovkControllerParams,
+} from '../types';
+import { _StreamResponse as StreamResponse } from '../StreamResponse';
+import type { NextResponse } from 'next/server';
+
+export type _StaticMethodInput<T extends _ControllerStaticMethod> = (_VovkControllerBody<T> extends undefined | void
+  ? { body?: undefined }
+  : _VovkControllerBody<T> extends null
+    ? { body?: null }
+    : { body: _VovkControllerBody<T> }) &
+  (_VovkControllerQuery<T> extends undefined | void ? { query?: undefined } : { query: _VovkControllerQuery<T> }) &
+  (_VovkControllerParams<T> extends undefined | void ? { params?: undefined } : { params: _VovkControllerParams<T> });
+
+type ToPromise<T> = T extends PromiseLike<unknown> ? T : Promise<T>;
+
+export type _StreamAsyncIterator<T> = {
+  status: number;
+  [Symbol.dispose](): Promise<void> | void;
+  [Symbol.asyncDispose](): Promise<void> | void;
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+  cancel: () => Promise<void> | void;
+};
+
+type StaticMethodReturn<T extends _ControllerStaticMethod> =
+  ReturnType<T> extends NextResponse<infer U> | Promise<NextResponse<infer U>>
+    ? U
+    : ReturnType<T> extends Response | Promise<Response>
+      ? unknown
+      : ReturnType<T>;
+
+type StaticMethodReturnPromise<T extends _ControllerStaticMethod> = ToPromise<StaticMethodReturn<T>>;
+
+type ClientMethod<
+  T extends (...args: KnownAny[]) => void | object | StreamResponse<STREAM> | Promise<StreamResponse<STREAM>>,
+  OPTS extends Record<string, KnownAny>,
+  STREAM extends KnownAny = unknown,
+> = <R>(
+  options: (_StaticMethodInput<T> extends { body?: undefined | null; query?: undefined; params?: undefined }
+    ? unknown
+    : Parameters<T>[0] extends void
+      ? _StaticMethodInput<T>['params'] extends object
+        ? { params: _StaticMethodInput<T>['params'] }
+        : unknown
+      : _StaticMethodInput<T>) &
+    (Partial<
+      OPTS & {
+        transform: (staticMethodReturn: Awaited<StaticMethodReturn<T>>) => R;
+      }
+    > | void)
+) => ReturnType<T> extends
+  | Promise<StreamResponse<infer U>>
+  | StreamResponse<infer U>
+  | Iterator<infer U>
+  | AsyncIterator<infer U>
+  ? Promise<_StreamAsyncIterator<U>>
+  : R extends object
+    ? Promise<R>
+    : StaticMethodReturnPromise<T>;
+
+type OmitNever<T> = {
+  [K in keyof T as T[K] extends never ? never : K]: T[K];
+};
+
+type _VovkClientWithNever<T, OPTS extends { [key: string]: KnownAny }> = {
+  [K in keyof T]: T[K] extends (...args: KnownAny) => KnownAny ? ClientMethod<T[K], OPTS> : never;
+};
+
+export type _VovkClient<T, OPTS extends { [key: string]: KnownAny }> = OmitNever<_VovkClientWithNever<T, OPTS>>;
+
+export type _VovkClientFetcher<OPTS extends Record<string, KnownAny> = Record<string, never>, T = KnownAny> = (
+  options: {
+    name: keyof T;
+    httpMethod: HttpMethod;
+    getEndpoint: (data: {
+      prefix: string;
+      segmentName: string;
+      params: { [key: string]: string };
+      query: { [key: string]: string };
+    }) => string;
+    validate: (input: { body?: unknown; query?: unknown; endpoint: string }) => void | Promise<void>;
+    defaultStreamHandler: (response: Response) => Promise<_StreamAsyncIterator<unknown>>;
+    defaultHandler: (response: Response) => Promise<unknown>;
+  },
+  input: {
+    body: unknown;
+    query: { [key: string]: string };
+    params: { [key: string]: string };
+  } & OPTS
+) => KnownAny;
+
+// `RequestInit` is the type of options passed to fetch function
+export interface _VovkDefaultFetcherOptions extends Omit<RequestInit, 'body' | 'method'> {
+  reactNative?: { textStreaming: boolean };
+  prefix?: string;
+  segmentName: string;
+  disableClientValidation?: boolean;
+  validateOnClient?: _VovkValidateOnClient;
+  fetcher?: _VovkClientFetcher;
+}
+
+export type _VovkValidateOnClient = (
+  input: { body?: unknown; query?: unknown; endpoint: string },
+  validators: { body?: unknown; query?: unknown }
+) => void | Promise<void>;
+
+export type _VovkClientOptions<OPTS extends Record<string, KnownAny> = Record<string, never>> = {
+  fetcher?: _VovkClientFetcher<OPTS>;
+  validateOnClient?: _VovkValidateOnClient;
+  defaultOptions?: Partial<OPTS>;
+};

package/createDecorator.ts

@@ -0,0 +1,65 @@
+import type {
+  _HandlerMetadata as HandlerMetadata,
+  _KnownAny as KnownAny,
+  _VovkController as VovkController,
+  _VovkRequest as VovkRequest,
+} from './types';
+
+type Next = () => Promise<unknown>;
+
+export function _createDecorator<ARGS extends unknown[], REQUEST = VovkRequest>(
+  handler: null | ((this: VovkController, req: REQUEST, next: Next, ...args: ARGS) => unknown),
+  initHandler?: (
+    this: VovkController,
+    ...args: ARGS
+  ) =>
+    | Omit<HandlerMetadata, 'path' | 'httpMethod'>
+    | ((handlerMetadata: HandlerMetadata | null) => Omit<HandlerMetadata, 'path' | 'httpMethod'>)
+    | null
+    | undefined
+) {
+  return function decoratorCreator(...args: ARGS) {
+    return function decorator(target: KnownAny, propertyKey: string) {
+      const controller = target as VovkController;
+
+      const originalMethod = controller[propertyKey] as ((...args: KnownAny) => KnownAny) & {
+        _sourceMethod?: (...args: KnownAny) => KnownAny;
+      };
+      if (typeof originalMethod !== 'function') {
+        throw new Error(`Unable to decorate: ${propertyKey} is not a function`);
+      }
+      const sourceMethod = originalMethod._sourceMethod ?? originalMethod;
+
+      const handlerMetadata: HandlerMetadata | null = controller._handlers?.[propertyKey] ?? null;
+      const initResultReturn = initHandler?.call(controller, ...args);
+      const initResult = typeof initResultReturn === 'function' ? initResultReturn(handlerMetadata) : initResultReturn;
+
+      controller._handlers = {
+        ...controller._handlers,
+        [propertyKey]: {
+          ...handlerMetadata,
+          // avoid override of path and httpMethod
+          ...(initResult?.clientValidators ? { clientValidators: initResult.clientValidators } : {}),
+          ...(initResult?.customMetadata ? { customMetadata: initResult.customMetadata } : {}),
+        },
+      };
+
+      const method = function method(req: REQUEST, params?: unknown) {
+        const next: Next = async () => {
+          return (await originalMethod.call(controller, req, params)) as unknown;
+        };
+
+        return handler ? handler.call(controller, req, next, ...args) : next();
+      };
+
+      method._controller = controller;
+
+      // TODO define internal method type
+      (originalMethod as unknown as { _controller: VovkController })._controller = controller;
+
+      controller[propertyKey] = method;
+
+      method._sourceMethod = sourceMethod;
+    };
+  };
+}

package/createSegment.ts

@@ -0,0 +1,239 @@
+/* eslint-disable no-console */
+import { _Segment as Segment } from './Segment';
+import {
+  _HttpMethod as HttpMethod,
+  type _KnownAny as KnownAny,
+  type _RouteHandler as RouteHandler,
+  type _VovkController as VovkController,
+  type _VovkWorker as VovkWorker,
+  type _DecoratorOptions as DecoratorOptions,
+  type _VovkRequest as VovkRequest,
+  type _VovkMetadata as VovkMetadata,
+} from './types';
+
+const trimPath = (path: string) => path.trim().replace(/^\/|\/$/g, '');
+const isClass = (func: unknown) => typeof func === 'function' && /class/.test(func.toString());
+const toKebabCase = (str: string) => {
+  return (
+    str
+      // Insert a hyphen before each uppercase letter, then convert to lowercase
+      .replace(/([A-Z])/g, '-$1')
+      .toLowerCase()
+      // Remove any leading hyphen if the original string started with an uppercase letter
+      .replace(/^-/, '')
+  );
+};
+
+export function _createSegment() {
+  const r = new Segment();
+
+  const getDecoratorCreator = (httpMethod: HttpMethod) => {
+    const assignMetadata = (
+      controller: VovkController,
+      propertyKey: string,
+      path: string,
+      options?: DecoratorOptions
+    ) => {
+      if (typeof window !== 'undefined') {
+        throw new Error(
+          'Decorators are intended for server-side use only. You have probably imported a controller on the client-side.'
+        );
+      }
+      if (!isClass(controller)) {
+        let decoratorName = httpMethod.toLowerCase();
+        if (decoratorName === 'delete') decoratorName = 'del';
+        throw new Error(
+          `Decorator must be used on a static class method. Check the controller method named "${propertyKey}" used with @${decoratorName}.`
+        );
+      }
+
+      const methods: Record<string, RouteHandler> = r._routes[httpMethod].get(controller) ?? {};
+      r._routes[httpMethod].set(controller, methods);
+
+      controller._handlers = {
+        ...controller._handlers,
+        [propertyKey]: {
+          ...(controller._handlers ?? {})[propertyKey],
+          path,
+          httpMethod,
+        },
+      };
+
+      const originalMethod = controller[propertyKey] as ((...args: KnownAny) => KnownAny) & {
+        _controller: VovkController;
+        _sourceMethod?: (...args: KnownAny) => KnownAny;
+      };
+
+      originalMethod._controller = controller;
+      originalMethod._sourceMethod = originalMethod._sourceMethod ?? originalMethod;
+
+      methods[path] = controller[propertyKey] as RouteHandler;
+      methods[path]._options = options;
+    };
+
+    function decoratorCreator(givenPath = '', options?: DecoratorOptions) {
+      const path = trimPath(givenPath);
+
+      function decorator(givenTarget: KnownAny, propertyKey: string) {
+        const target = givenTarget as VovkController;
+        assignMetadata(target, propertyKey, path, options);
+      }
+
+      return decorator;
+    }
+
+    const auto = (options?: DecoratorOptions) => {
+      function decorator(givenTarget: KnownAny, propertyKey: string) {
+        const controller = givenTarget as VovkController;
+        const methods: Record<string, RouteHandler> = r._routes[httpMethod].get(controller) ?? {};
+        r._routes[httpMethod].set(controller, methods);
+
+        controller._handlers = {
+          ...controller._handlers,
+          [propertyKey]: {
+            ...(controller._handlers ?? {})[propertyKey],
+            httpMethod,
+          },
+        };
+
+        assignMetadata(controller, propertyKey, toKebabCase(propertyKey), options);
+      }
+
+      return decorator;
+    };
+
+    const enhancedDecoratorCreator = decoratorCreator as {
+      (...args: Parameters<typeof decoratorCreator>): ReturnType<typeof decoratorCreator>;
+      auto: typeof auto;
+    };
+
+    enhancedDecoratorCreator.auto = auto;
+
+    return enhancedDecoratorCreator;
+  };
+
+  const prefix = (givenPath = '') => {
+    const path = trimPath(givenPath);
+
+    return (givenTarget: KnownAny) => {
+      const controller = givenTarget as VovkController;
+      controller._prefix = path;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return givenTarget;
+    };
+  };
+
+  const getMetadata = (options: {
+    emitMetadata?: boolean;
+    segmentName?: string;
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    controllers: Record<string, Function>;
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    workers?: Record<string, Function>;
+    exposeValidation?: boolean;
+  }) => {
+    const exposeValidation = options?.exposeValidation ?? true;
+    const emitMetadata = options.emitMetadata ?? true;
+    const metadata: VovkMetadata = {
+      emitMetadata,
+      segmentName: options.segmentName ?? '',
+      controllers: {},
+      workers: {},
+    };
+
+    if (!emitMetadata) return metadata;
+
+    for (const [controllerName, controller] of Object.entries(options.controllers) as [string, VovkController][]) {
+      metadata.controllers[controllerName] = {
+        _controllerName: controllerName,
+        _prefix: controller._prefix ?? '',
+        _handlers: {
+          ...(exposeValidation
+            ? controller._handlers
+            : Object.fromEntries(
+                Object.entries(controller._handlers).map(([key, value]) => [
+                  key,
+                  { ...value, clientValidators: undefined },
+                ])
+              )),
+        },
+      };
+    }
+
+    for (const [workerName, worker] of Object.entries(options.workers ?? {}) as [string, VovkWorker][]) {
+      metadata.workers[workerName] = {
+        _workerName: workerName,
+        _handlers: { ...worker._handlers },
+      };
+    }
+
+    return metadata;
+  };
+
+  const initVovk = (options: {
+    segmentName?: string;
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    controllers: Record<string, Function>;
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    workers?: Record<string, Function>;
+    exposeValidation?: boolean;
+    emitMetadata?: boolean;
+    onError?: (err: Error, req: VovkRequest) => void | Promise<void>;
+    onMetadata?: (metadata: VovkMetadata) => void | Promise<void>;
+  }) => {
+    for (const [controllerName, controller] of Object.entries(options.controllers) as [string, VovkController][]) {
+      controller._controllerName = controllerName;
+      controller._activated = true;
+      controller._onError = options?.onError;
+    }
+
+    // Wait for metadata to be set (it can be set after decorators are called with another setTimeout)
+    setTimeout(() => {
+      const metadata = getMetadata(options);
+
+      if (process.env.NODE_ENV === 'development') {
+        const VOVK_PORT = process.env.VOVK_PORT || (parseInt(process.env.PORT || '3000') + 6969).toString();
+        const url = `http://localhost:${VOVK_PORT}/__metadata`;
+        void fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ metadata }),
+        })
+          .then((resp) => {
+            if (!resp.ok) {
+              console.error(`🐺 Failed to send metadata to ${url}. Response is not OK. ${resp.statusText}`);
+            }
+          })
+          .catch((err) => {
+            console.error(`🐺 Failed to send metadata to ${url}. ${err}`);
+          });
+      }
+
+      if (options?.onMetadata) {
+        void options.onMetadata(metadata);
+      }
+    }, 10);
+
+    return {
+      GET: r.GET,
+      POST: r.POST,
+      PUT: r.PUT,
+      PATCH: r.PATCH,
+      DELETE: r.DELETE,
+      HEAD: r.HEAD,
+      OPTIONS: r.OPTIONS,
+    };
+  };
+
+  return {
+    get: getDecoratorCreator(HttpMethod.GET),
+    post: getDecoratorCreator(HttpMethod.POST),
+    put: getDecoratorCreator(HttpMethod.PUT),
+    patch: getDecoratorCreator(HttpMethod.PATCH),
+    del: getDecoratorCreator(HttpMethod.DELETE),
+    head: getDecoratorCreator(HttpMethod.HEAD),
+    options: getDecoratorCreator(HttpMethod.OPTIONS),
+    prefix,
+    initVovk,
+  };
+}

package/dist/.npmignore

@@ -0,0 +1 @@
+!*

package/dist/HttpException.d.ts

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

package/dist/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/dist/README.md

@@ -0,0 +1,111 @@
+<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>
+
+<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', 
+  }),
+})
+```

package/dist/Segment.d.ts

@@ -0,0 +1,27 @@
+import { _HttpMethod as HttpMethod, type _RouteHandler as RouteHandler, type _VovkController as VovkController, type _VovkRequest as VovkRequest } from './types';
+export declare class _Segment {
+    #private;
+    private static getHeadersFromOptions;
+    _routes: Record<HttpMethod, Map<VovkController, Record<string, RouteHandler>>>;
+    GET: (req: VovkRequest, data: {
+        params: Record<string, string[]>;
+    }) => Promise<Response>;
+    POST: (req: VovkRequest, data: {
+        params: Record<string, string[]>;
+    }) => Promise<Response>;
+    PUT: (req: VovkRequest, data: {
+        params: Record<string, string[]>;
+    }) => Promise<Response>;
+    PATCH: (req: VovkRequest, data: {
+        params: Record<string, string[]>;
+    }) => Promise<Response>;
+    DELETE: (req: VovkRequest, data: {
+        params: Record<string, string[]>;
+    }) => Promise<Response>;
+    HEAD: (req: VovkRequest, data: {
+        params: Record<string, string[]>;
+    }) => Promise<Response>;
+    OPTIONS: (req: VovkRequest, data: {
+        params: Record<string, string[]>;
+    }) => Promise<Response>;
+}