vovk 3.0.0-draft.5 → 3.0.0-draft.50

package/src/client/defaultHandler.ts

@@ -0,0 +1,23 @@
+import { type VovkErrorResponse } from '../types';
+import { 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
+    const errorResponse = result as VovkErrorResponse;
+    throw new HttpException(response.status, errorResponse?.message ?? DEFAULT_ERROR_MESSAGE, errorResponse?.cause);
+  }
+
+  return result;
+};

package/src/client/defaultStreamHandler.ts

@@ -0,0 +1,88 @@
+import { HttpStatus, type VovkErrorResponse } from '../types';
+import type { StreamAsyncIterator } from './types';
+import { HttpException } from '../HttpException';
+import '../utils/shim';
+
+export const DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultStreamHandler';
+
+export const defaultStreamHandler = async (response: Response): Promise<StreamAsyncIterator<unknown>> => {
+  if (!response.ok) {
+    let result: unknown;
+    try {
+      result = await response.json();
+    } catch {
+      // ignore parsing errors
+    }
+    // handle server errors
+    throw new HttpException(response.status, (result as VovkErrorResponse).message ?? DEFAULT_ERROR_MESSAGE);
+  }
+
+  if (!response.body) throw new HttpException(HttpStatus.NULL, 'Stream body is falsy. Check your controller code.');
+
+  const reader = response.body.getReader();
+
+  // if streaming is too rapid, we need to make sure that the loop is stopped
+  let canceled = false;
+
+  async function* asyncIterator() {
+    let prepend = '';
+
+    while (true) {
+      let value: Uint8Array | undefined;
+      let done = false;
+
+      try {
+        ({ value, done } = await reader.read());
+      } catch (error) {
+        await reader.cancel();
+        const err = new Error('Stream error. ' + String(error));
+        err.cause = error;
+        throw err;
+      }
+
+      if (done) {
+        return;
+      }
+
+      // typeof value === 'number' is a workaround for React Native
+      const string = typeof value === 'number' ? String.fromCharCode(value) : new TextDecoder().decode(value);
+      prepend += string;
+      const lines = prepend.split('\n').filter(Boolean);
+      for (const line of lines) {
+        let data;
+        try {
+          data = JSON.parse(line) as object;
+          prepend = '';
+        } catch {
+          break;
+        }
+
+        if (data) {
+          if ('isError' in data && 'reason' in data) {
+            const upcomingError = data.reason;
+            await reader.cancel();
+
+            if (typeof upcomingError === 'string') {
+              throw new Error(upcomingError);
+            }
+
+            throw upcomingError;
+          } else if (!canceled) {
+            yield data;
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    status: response.status,
+    [Symbol.asyncIterator]: asyncIterator,
+    [Symbol.dispose]: () => reader.cancel(),
+    [Symbol.asyncDispose]: () => reader.cancel(),
+    cancel: () => {
+      canceled = true;
+      return reader.cancel();
+    },
+  };
+};

package/src/client/index.ts

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

package/src/client/types.ts

@@ -0,0 +1,115 @@
+import type {
+  KnownAny,
+  HttpMethod,
+  ControllerStaticMethod,
+  VovkControllerBody,
+  VovkControllerQuery,
+  VovkControllerParams,
+} from '../types';
+import type { StreamJSONResponse } from '../StreamJSONResponse';
+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>
+      ? 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 { 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<StreamJSONResponse<infer U>>
+  | StreamJSONResponse<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: {
+      apiRoot: 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 };
+  apiRoot?: 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/src/createDecorator.ts

@@ -0,0 +1,60 @@
+import type { HandlerSchema, KnownAny, VovkController, 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<HandlerSchema, 'path' | 'httpMethod'>
+    | ((handlerSchema: HandlerSchema | null) => Omit<HandlerSchema, '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 handlerSchema: HandlerSchema | null = controller._handlers?.[propertyKey] ?? null;
+      const initResultReturn = initHandler?.call(controller, ...args);
+      const initResult = typeof initResultReturn === 'function' ? initResultReturn(handlerSchema) : initResultReturn;
+
+      controller._handlers = {
+        ...controller._handlers,
+        [propertyKey]: {
+          ...handlerSchema,
+          // avoid override of path and httpMethod
+          ...(initResult?.validation ? { validation: initResult.validation } : {}),
+          ...(initResult?.custom ? { custom: initResult.custom } : {}),
+        },
+      };
+
+      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/src/createVovkApp.ts

@@ -0,0 +1,167 @@
+import { VovkApp as VovkApp } from './VovkApp';
+import {
+  HttpMethod,
+  type KnownAny,
+  type RouteHandler,
+  type VovkController,
+  type DecoratorOptions,
+  type VovkRequest,
+  type StaticClass,
+} from './types';
+import getSchema from './utils/getSchema';
+
+const trimPath = (path: string) => path.trim().replace(/^\/|\/$/g, '');
+const isClass = (func: unknown) => typeof func === 'function' && /class/.test(func.toString());
+const toKebabCase = (str: string) =>
+  str
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+
+export function createVovkApp() {
+  const vovkApp = new VovkApp();
+
+  const createHTTPDecorator = (httpMethod: HttpMethod) => {
+    const assignSchema = (
+      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> = vovkApp.routes[httpMethod].get(controller) ?? {};
+      vovkApp.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;
+        assignSchema(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> = vovkApp.routes[httpMethod].get(controller) ?? {};
+        vovkApp.routes[httpMethod].set(controller, methods);
+
+        controller._handlers = {
+          ...controller._handlers,
+          [propertyKey]: {
+            ...(controller._handlers ?? {})[propertyKey],
+            httpMethod,
+          },
+        };
+
+        assignSchema(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;
+
+      return givenTarget;
+    };
+  };
+
+  const initVovk = (options: {
+    segmentName?: string;
+    controllers: Record<string, StaticClass>;
+    workers?: Record<string, StaticClass>;
+    exposeValidation?: boolean;
+    emitSchema?: boolean;
+    onError?: (err: Error, req: VovkRequest) => 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;
+    }
+
+    async function GET_DEV(req: VovkRequest, data: { params: Promise<Record<string, string[]>> }) {
+      const params = await data.params;
+      if (params[Object.keys(params)[0]]?.[0] === '_schema_') {
+        // Wait for schema to be set (it can be set after decorators are called with another setTimeout)
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        const schema = getSchema(options);
+        return vovkApp.respond(200, { schema });
+      }
+      return vovkApp.GET(req, data);
+    }
+
+    return {
+      GET: process.env.NODE_ENV === 'development' ? GET_DEV : vovkApp.GET,
+      POST: vovkApp.POST,
+      PUT: vovkApp.PUT,
+      PATCH: vovkApp.PATCH,
+      DELETE: vovkApp.DELETE,
+      HEAD: vovkApp.HEAD,
+      OPTIONS: vovkApp.OPTIONS,
+    };
+  };
+
+  return {
+    get: createHTTPDecorator(HttpMethod.GET),
+    post: createHTTPDecorator(HttpMethod.POST),
+    put: createHTTPDecorator(HttpMethod.PUT),
+    patch: createHTTPDecorator(HttpMethod.PATCH),
+    del: createHTTPDecorator(HttpMethod.DELETE),
+    head: createHTTPDecorator(HttpMethod.HEAD),
+    options: createHTTPDecorator(HttpMethod.OPTIONS),
+    prefix,
+    initVovk,
+  };
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+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 {
+  type VovkClientOptions,
+  type VovkClientFetcher,
+  type VovkDefaultFetcherOptions,
+  type VovkValidateOnClient,
+  createRPC,
+} from './client';
+import { HttpException } from './HttpException';
+import { createDecorator } from './createDecorator';
+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 const { get, post, put, patch, del, head, options, prefix, initVovk } = createVovkApp();