vovk 3.0.0-draft.7 → 3.0.0-draft.70

package/src/VovkApp.ts

@@ -0,0 +1,240 @@
+import type { NextRequest } from 'next/server';
+import {
+  HttpMethod,
+  HttpStatus,
+  type RouteHandler,
+  type VovkErrorResponse,
+  type VovkController,
+  type DecoratorOptions,
+  type KnownAny,
+  type VovkRequest,
+} from './types';
+import { HttpException } from './HttpException';
+import { StreamJSONResponse } from './StreamJSONResponse';
+import reqQuery from './utils/reqQuery';
+import reqMeta from './utils/reqMeta';
+import reqForm from './utils/reqForm';
+
+export class VovkApp {
+  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 = async (req: NextRequest, data: { params: Promise<Record<string, string[]>> }) =>
+    this.#callMethod(HttpMethod.GET, req, await data.params);
+
+  POST = async (req: NextRequest, data: { params: Promise<Record<string, string[]>> }) =>
+    this.#callMethod(HttpMethod.POST, req, await data.params);
+
+  PUT = async (req: NextRequest, data: { params: Promise<Record<string, string[]>> }) =>
+    this.#callMethod(HttpMethod.PUT, req, await data.params);
+
+  PATCH = async (req: NextRequest, data: { params: Promise<Record<string, string[]>> }) =>
+    this.#callMethod(HttpMethod.PATCH, req, await data.params);
+
+  DELETE = async (req: NextRequest, data: { params: Promise<Record<string, string[]>> }) =>
+    this.#callMethod(HttpMethod.DELETE, req, await data.params);
+
+  HEAD = async (req: NextRequest, data: { params: Promise<Record<string, string[]>> }) =>
+    this.#callMethod(HttpMethod.HEAD, req, await data.params);
+
+  OPTIONS = async (req: NextRequest, data: { params: Promise<Record<string, string[]>> }) =>
+    this.#callMethod(HttpMethod.OPTIONS, req, await data.params);
+
+  respond = (status: HttpStatus, body: unknown, options?: DecoratorOptions) => {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: {
+        'Content-Type': 'application/json',
+        ...VovkApp.getHeadersFromOptions(options),
+      },
+    });
+  };
+
+  #respondWithError = (statusCode: HttpStatus, message: string, options?: DecoratorOptions, cause?: unknown) => {
+    return this.respond(
+      statusCode,
+      {
+        cause,
+        statusCode,
+        message,
+        isError: true,
+      } satisfies VovkErrorResponse,
+      options
+    );
+  };
+
+  #callMethod = async (httpMethod: HttpMethod, nextReq: NextRequest, params: Record<string, string[]>) => {
+    const req = nextReq as unknown as VovkRequest;
+    const controllers = this.routes[httpMethod];
+    const methodParams: Record<string, string> = {};
+    const path = params[Object.keys(params)[0]];
+
+    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 as VovkRequest),
+      meta: <T = KnownAny>(meta?: T | null) => reqMeta<T>(req, meta),
+      form: <T = KnownAny>() => reqForm<T>(req),
+    };
+
+    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 StreamJSONResponse({
+          headers: {
+            ...StreamJSONResponse.defaultHeaders,
+            ...VovkApp.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, err.cause);
+      }
+
+      throw e; // if NEXT_REDIRECT or NEXT_NOT_FOUND, rethrow it
+    }
+  };
+}

package/src/client/createRPC.ts

@@ -0,0 +1,120 @@
+import {
+  type VovkControllerSchema,
+  type ControllerStaticMethod,
+  type VovkControllerParams,
+  type VovkControllerQuery,
+  type KnownAny,
+  type HttpMethod,
+} 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: httpMethod as 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,69 @@
+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, {
+        body,
+        query,
+        params,
+        endpoint,
+      });
+    }
+  }
+
+  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, {
+      body,
+      query,
+      params,
+      endpoint,
+    });
+  }
+
+  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>;
+};