vovk 3.0.0-draft.6 → 3.0.0-draft.61

package/src/client/createRPC.ts

@@ -0,0 +1,119 @@
+import {
+  type VovkControllerSchema,
+  type ControllerStaticMethod,
+  type VovkControllerParams,
+  type VovkControllerQuery,
+  type KnownAny,
+} from '../types';
+import { type VovkClientOptions, type VovkClient, type VovkDefaultFetcherOptions, VovkValidateOnClient } from './types';
+
+import defaultFetcher from './defaultFetcher';
+import { defaultHandler } from './defaultHandler';
+import { defaultStreamHandler } from './defaultStreamHandler';
+import serializeQuery from '../utils/serializeQuery';
+
+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 queryStr = query ? serializeQuery(query) : null;
+
+  return `${result}${queryStr ? '?' : ''}${queryStr}`;
+};
+
+const createRPC = <T, OPTS extends Record<string, KnownAny> = VovkDefaultFetcherOptions>(
+  controllerSchema: VovkControllerSchema,
+  segmentName?: string,
+  options?: VovkClientOptions<OPTS>
+): VovkClient<T, OPTS> => {
+  const schema = controllerSchema as T & VovkControllerSchema;
+  const client = {} as VovkClient<T, OPTS>;
+  if (!schema) throw new Error(`Unable to clientize. Controller schema is not provided`);
+  if (!schema.handlers)
+    throw new Error(`Unable to clientize. No schema for controller ${String(schema?.controllerName)} provided`);
+  const controllerPrefix = trimPath(schema.prefix ?? '');
+  const { fetcher: settingsFetcher = defaultFetcher } = options ?? {};
+
+  for (const [staticMethodName, handlerSchema] of Object.entries(schema.handlers)) {
+    const { path, httpMethod, validation } = handlerSchema;
+    const getEndpoint = ({
+      apiRoot,
+      params,
+      query,
+    }: {
+      apiRoot: string;
+      params: { [key: string]: string };
+      query: { [key: string]: string };
+    }) => {
+      const mainPrefix =
+        (apiRoot.startsWith('http://') || apiRoot.startsWith('https://') || apiRoot.startsWith('/') ? '' : '/') +
+        (apiRoot.endsWith('/') ? apiRoot : `${apiRoot}/`) +
+        (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 }, validation ?? {});
+      };
+
+      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 ?? {},
+        // 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;
+    };
+
+    handler.schema = handlerSchema;
+    handler.controllerSchema = schema;
+
+    // @ts-expect-error TODO
+    client[staticMethodName] = handler;
+  }
+
+  return client;
+};
+
+export default createRPC;

package/src/client/defaultFetcher.ts

@@ -0,0 +1,61 @@
+import type { VovkDefaultFetcherOptions, VovkClientFetcher } from './types';
+import { HttpStatus } from '../types';
+import { HttpException } from '../HttpException';
+
+export const DEFAULT_ERROR_MESSAGE = 'Unknown error at the 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, apiRoot = '/api', ...options }
+) => {
+  const endpoint = getEndpoint({ apiRoot, 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);
+  }
+
+  const contentType = response.headers.get('content-type');
+
+  
+
+  if (contentType?.startsWith('application/json')) {
+    return defaultHandler(response);
+  }
+
+  if (contentType === 'text/plain; format=jsonlines') {
+    return defaultStreamHandler(response);
+  }
+
+  return response;
+};
+
+export default defaultFetcher;

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 { VovkStreamAsyncIterable } 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<VovkStreamAsyncIterable<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,9 @@
+export { default as createRPC } from './createRPC';
+export type {
+  VovkClient,
+  VovkClientFetcher,
+  VovkClientOptions,
+  VovkDefaultFetcherOptions,
+  VovkValidateOnClient,
+  VovkStreamAsyncIterable,
+} from './types';

package/src/client/types.ts

@@ -0,0 +1,120 @@
+import type {
+  KnownAny,
+  HttpMethod,
+  ControllerStaticMethod,
+  VovkControllerBody,
+  VovkControllerQuery,
+  VovkControllerParams,
+  VovkHandlerSchema,
+  VovkControllerSchema,
+} 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 VovkStreamAsyncIterable<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<VovkStreamAsyncIterable<U>>
+  : R extends object
+    ? Promise<R>
+    : StaticMethodReturnPromise<T>) & {
+  schema: VovkHandlerSchema;
+  controllerSchema: VovkControllerSchema;
+};
+
+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<VovkStreamAsyncIterable<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 { VovkHandlerSchema, 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<VovkHandlerSchema, 'path' | 'httpMethod'>
+    | ((handlerSchema: VovkHandlerSchema | null) => Omit<Partial<VovkHandlerSchema>, '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: VovkHandlerSchema | 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,
+  VovkHandlerSchema,
+} 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] as Partial<VovkHandlerSchema>),
+          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>;
+    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,
+  };
+}