@tpzdsp/next-toolkit 1.6.0 → 1.8.0

package/src/http/logger.ts

@@ -0,0 +1,163 @@
+import type { BetterFetchPlugin, RequestContext } from '@better-fetch/fetch';
+
+import { Header } from './constants';
+
+// Tries to print the request/response body as a string, and clamps the length it it's too long.
+const preview = (data: unknown, maxLength: number): string | null => {
+  if (data == null) {
+    return null;
+  }
+
+  try {
+    let str = typeof data === 'string' ? data : JSON.stringify(data);
+
+    if (str.length > maxLength) {
+      str = str.slice(0, maxLength) + '…';
+    }
+
+    return str;
+  } catch {
+    return '[unserializable]';
+  }
+};
+
+type RequestMeta = {
+  requestId: string;
+};
+type MetaContext = RequestContext & {
+  meta: RequestMeta;
+};
+
+const UNKNOWN_ID = '???';
+
+/**
+ * Config options for the logger.
+ */
+type RequestLoggerOptions = {
+  /**
+   * Enables/Disabled the logger. Can be a function/async function to toggle the logger dynamically
+   */
+  enabled?: boolean | (() => Promise<boolean> | boolean);
+  /**
+   * Controls how much of the request and response body is shown in the logs.
+   */
+  maxPreviewLength?: number;
+};
+
+/**
+ * A logger for the fetch functions that prints detailed information on each request and respective response.
+ * Each request is given a unique ID which is paired with a response to make finding matching request/response pairs easier.
+ *
+ * It currently, prints the method, url, `Accept` and `Content-Type` headers, and the body of the request, and it prints the
+ * `Content-Type` header, status code, response body and duration of the response, for both successful and failed responses.
+ */
+export const requestLogger = (options?: RequestLoggerOptions): BetterFetchPlugin => {
+  const enabled =
+    typeof options?.enabled !== 'function' ? () => options?.enabled ?? true : options?.enabled;
+
+  const maxPreview = options?.maxPreviewLength ?? 150;
+
+  const timings = new Map<string, number>();
+
+  const genId = () => crypto.randomUUID().split('-')[0].toUpperCase();
+
+  return {
+    id: 'logger',
+    name: 'Logger',
+    version: '0.1.0',
+    hooks: {
+      hookOptions: {
+        cloneResponse: true,
+      },
+
+      onRequest: async (context) => {
+        if (!(await enabled?.())) {
+          return;
+        }
+
+        const metaContext = context as MetaContext;
+
+        metaContext.meta = metaContext.meta ?? {};
+
+        const id = genId();
+
+        metaContext.meta.requestId = id;
+        context.headers.set(Header.XRequestId, id);
+
+        timings.set(id, performance.now());
+
+        const { url, method, body, headers } = context;
+
+        const bodyPreview = body ? preview(body, maxPreview) : '';
+        const contentType = headers.get(Header.ContentType) ?? 'N/A';
+        const accept = headers.get(Header.Accept) ?? 'N/A';
+
+        const message =
+          `🚀 [${method}] (${id}) ${url}\n` +
+          `\t↳ Content-Type: ${contentType}\n` +
+          `\t↳ Accept: ${accept}` +
+          (bodyPreview ? `\n\t↳ Body: ${bodyPreview}` : '');
+
+        console.log(message);
+      },
+
+      onSuccess: async (context) => {
+        if (!(await enabled?.())) {
+          return;
+        }
+
+        const { response, data, request } = context;
+
+        const id = (request as MetaContext).meta.requestId ?? UNKNOWN_ID;
+
+        const status = response.status;
+        const bodyPreview = preview(data, maxPreview);
+        const contentType = response.headers.get(Header.ContentType) ?? 'N/A';
+        const duration = (performance.now() - (timings.get(id) ?? 0)).toFixed(1);
+
+        const message =
+          `✅ [${request.method}] (${id}) ${request.url}\n` +
+          `\t↳ Status: ${status} (${duration}ms)\n` +
+          `\t↳ Respone Content-Type: ${contentType}\n` +
+          `\t↳ Response: ${bodyPreview}`;
+
+        console.log(message);
+      },
+
+      onRetry: async (ctx) => {
+        if (!(await enabled?.())) {
+          return;
+        }
+
+        const id = (ctx.request as MetaContext).meta.requestId ?? UNKNOWN_ID;
+
+        console.warn(
+          `🔁 [${ctx.request.method}] (${id}) Retrying ${ctx.request.url}... Attempt: ${
+            (ctx.request.retryAttempt ?? 0) + 1
+          }`,
+        );
+      },
+
+      onError: async (context) => {
+        if (!(await enabled?.())) {
+          return;
+        }
+
+        const { response, error, request } = context;
+
+        const id = (request as MetaContext).meta.requestId ?? UNKNOWN_ID;
+
+        const status = response?.status ?? 'unknown';
+        const errorPreview = preview(error, maxPreview);
+        const duration = (performance.now() - (timings.get(id) ?? 0)).toFixed(1);
+
+        const message =
+          `❌ [${request.method}] (${id}) ${request.url}\n` +
+          `\t↳ Status: ${status} (${duration}ms)\n` +
+          `\t↳ Error: ${errorPreview}`;
+
+        console.error(message);
+      },
+    },
+  };
+};

package/src/http/proxy.ts

@@ -0,0 +1,269 @@
+import { type NextRequest, NextResponse } from 'next/server';
+
+import { type FetchSchemaRoutes, type Schema } from '@better-fetch/fetch';
+
+import {
+  Header,
+  HttpMethod,
+  isJsonMimeType,
+  isTextMimeType,
+  MimeType,
+  SPECIAL_FORM_DATA_TYPE,
+  SPECIAL_FORM_DOWNLOAD_POST,
+  type HttpMethods,
+} from './constants';
+import { normalizeError } from './fetch';
+import type {
+  EmptyRoutePrefixes,
+  OptionsWithInput,
+  SchemaRouteOutput,
+  SchemaRoutes,
+} from './query';
+import { ApiError } from '../errors/ApiError';
+
+/**
+ * The type of the Next.JS route handler function.
+ * Currently only works when inder the path `/proxy/[...path]/`
+ */
+type ProxyMethod = (
+  request: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> },
+) => Promise<NextResponse>;
+
+/**
+ * The invidiual method route handlers that we export.
+ */
+type ProxyMethods = {
+  GET: ProxyMethod;
+  POST: ProxyMethod;
+};
+
+/**
+ * Each route in a fetch schema must have a corresponding handler. This type defines the *arguments* passed from the proxy
+ * to the the handler. The arguments depend on what inputs are defined in the schema, so the handler can have a mix
+ * of `query` and `body` arguments.
+ */
+type ProxyEndpointHandlerArguments<
+  Routes extends SchemaRoutes,
+  Route extends keyof Routes,
+  SchemaInputs = OptionsWithInput<Routes, Route>,
+> = object &
+  (SchemaInputs extends { query: unknown } ? { query: SchemaInputs['query'] } : object) &
+  (SchemaInputs extends { body: unknown } ? { body: SchemaInputs['body'] } : object);
+
+/**
+ * Defines the type of the actual handler, with the arguments from above.
+ * It will infer the output type from the schema, otherwise it defaults to `unknown`. The function allows
+ * both the output type and a `NextResponse` containing the output type to be returned, which allows for
+ * flexibility (for example, if we wanted to return a stream of data instead).
+ */
+type ProxyEndpointHandler<
+  Routes extends SchemaRoutes,
+  Route extends keyof Routes,
+  SchemaOutput = SchemaRouteOutput<Routes, Route>,
+> = (
+  args: ProxyEndpointHandlerArguments<Routes, Route>,
+) => Promise<SchemaOutput | NextResponse<SchemaOutput>>;
+
+/**
+ * Defines handlers for every route in a given fetch schema.
+ */
+type ProxyEndpointHandlers<S extends Schema> = {
+  [K in keyof Omit<S['schema'], EmptyRoutePrefixes>]: ProxyEndpointHandler<S['schema'], K>;
+};
+
+const ERORR_PREFIX = '[ProxyError]';
+
+// Tiny bit of duplication from `better-fetch` as it has this functionality, but as this is a proxy
+// and the request isnt *received* by `better-fetch`, we have to do it ourselves.
+/**
+ * Parses a request body depending on the `Content-Type` header.
+ *
+ * @param request Incoming request.
+ * @returns The parsed body, or throws an error if the header is missing or the mime type is unknown.
+ */
+const parseRequestBody = async (request: Request): Promise<unknown> => {
+  const contentType = request.headers.get(Header.ContentType);
+
+  switch (true) {
+    case isJsonMimeType(contentType):
+      return await request.json();
+
+    case contentType === MimeType.Form: {
+      const data = await request.formData();
+
+      if (data.get(SPECIAL_FORM_DATA_TYPE) === SPECIAL_FORM_DOWNLOAD_POST) {
+        return JSON.parse((data.get('body') as string) ?? '{}');
+      }
+
+      return Object.fromEntries(data.entries());
+    }
+
+    case isTextMimeType(contentType):
+      return await request.text();
+
+    default:
+      throw ApiError.unprocessableContent(
+        contentType
+          ? `${ERORR_PREFIX} Request has unsupported Content-Type header: ${contentType}`
+          : `${ERORR_PREFIX} Request missing Content-Type header`,
+      );
+  }
+};
+
+/**
+ * Creates a `NextResponse` from a given body, with the correct content type from
+ * the `Accept` header of the request.
+ *
+ * @param body The body to be returned.
+ * @param request The incoming request.
+ * @returns The response (defaults to `text/plain` if the header is missing or the mime type is unknown)
+ */
+const makeResponse = (body: unknown, request: Request): NextResponse => {
+  const accept = request.headers.get(Header.Accept) ?? MimeType.Text;
+
+  let responseBody: BodyInit;
+
+  switch (true) {
+    case isJsonMimeType(accept):
+      responseBody = JSON.stringify(body);
+      break;
+
+    case isTextMimeType(accept):
+      responseBody = typeof body === 'string' ? body : String(body);
+      break;
+
+    default:
+      console.warn(
+        `Request to ${request.url} made with unhandled Accept header ${accept}. Defaulting to text/plain.`,
+      );
+
+      responseBody = '';
+      break;
+  }
+
+  return new NextResponse(responseBody, {
+    headers: {
+      [Header.ContentType]: accept,
+    },
+  });
+};
+
+/**
+ * Creates a schema-driven proxy for Next.JS route handlers that forwards requests to
+ * internal endpoint handlers while enforcing type safety and transforming results.
+ *
+ * This function is designed to be used in `app` route handlers in Next.js,
+ * allowing you to hide requests to the real API behind a controlled backend layer.
+ * The proxy automatically handles:
+ * - Parsing request bodies based on `Content-Type` headers
+ * - Returning responses in the correct format based on the request's `Accept` header
+ * - Mapping incoming requests to the correct handler based on the fetch schema
+ * - Normalizing errors into consistent `ApiError` objects with proper HTTP status codes
+ *
+ * The proxy methods (`GET` and `POST`) are automatically generated from a `better-fetch` schema,
+ * ensuring that only valid routes and HTTP methods are accessible.
+ *
+ * @template S - A `better-fetch` schema describing routes, inputs, and outputs.
+ * @param schema - The fetch schema used to validate and route incoming requests.
+ * @param endpointHandlers - An object mapping schema routes to handler functions, which process
+ *   the request and return a typed response or a `NextResponse`.
+ * @returns An object containing `GET` and `POST` handlers suitable for Next.js route exports:
+ * ```ts
+ * export const { GET, POST } = proxy;
+ * ```
+ *
+ * @example
+ * ```ts
+ * const proxy = createProxy(apiSchema, {
+ *   'proxy/users': async ({ query }) => fetchUsers(query),
+ *   'proxy/user/new': async ({ body }) => createUser(body),
+ * });
+ *
+ * export const { GET, POST } = proxy;
+ * ```
+ *
+ * @remarks
+ * - This proxy is fully type-safe: route inputs and outputs are inferred from the schema.
+ * - Only routes defined in the schema are accessible; invalid routes will return a 404.
+ * - Errors thrown by handlers or during processing are normalized to structured API errors.
+ */
+export const createProxy = <S extends Schema>(
+  schema: S,
+  endpointHandlers: ProxyEndpointHandlers<S>,
+): ProxyMethods => {
+  // Factory function that returns an inner function which is the individual Next.JS route handler.
+  // This route handler takes the incoming request, parses the body depending on the `Content-Type` header,
+  // passes it to the matching route handler, and then responds in the correcy type using the `Accept` header.
+  const makeVerbHandler =
+    (verb: HttpMethods): ProxyMethod =>
+    // route handler function
+    async (request, { params }) => {
+      const debugRequestId = request.headers.get(Header.XRequestId);
+
+      if (debugRequestId) {
+        console.log(
+          `[Proxy ${verb.toUpperCase()}]: (${debugRequestId}) Client request to ${request.url}`,
+        );
+      }
+
+      try {
+        const { path } = await params;
+        // add `proxy/` back as it's lost when requesting this route but required to match
+        // up to an individual handler
+        const endpoint = `proxy/${path.join('/')}`;
+
+        // check if the request to the proxy matches a valid route in the schema
+        const route = schema.schema[endpoint as keyof FetchSchemaRoutes];
+
+        if (!route) {
+          throw ApiError.notFound(`${ERORR_PREFIX} Unknown route: ${endpoint}`);
+        }
+
+        if (route.method?.toLowerCase() !== verb) {
+          throw ApiError.notAllowed(
+            `${ERORR_PREFIX} ${endpoint} is ${route.method?.toLowerCase()}, got ${verb}`,
+          );
+        }
+
+        // get the matching route handler
+        const handler = endpointHandlers[endpoint as keyof typeof endpointHandlers];
+
+        if (!handler) {
+          throw ApiError.notImplemented(`${ERORR_PREFIX} No handler for ${endpoint}`);
+        }
+
+        // We don't need to validate the following data as this is our internal proxy and we control what we pass to the proxy,
+        // and what we return.
+        // Typescript will enforce the correct object shape when we fetch this proxy, so we can be sure they're correct.
+        // It should be trivial to add validation if we do find that we are passing invalid data often.
+        let handlerArgs: Record<string, unknown> = {};
+
+        if (verb === HttpMethod.Post && 'input' in route) {
+          handlerArgs.body = await parseRequestBody(request);
+        }
+
+        if ('query' in route) {
+          handlerArgs.query = Object.fromEntries(request.nextUrl.searchParams.entries());
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await handler(handlerArgs as any);
+
+        // pass through the response otherwise make the correct response with the `Accept` header
+        return response instanceof NextResponse ? response : makeResponse(response, request);
+      } catch (error) {
+        const apiError = await normalizeError(error);
+
+        // use the `status` field to set the status of the response
+        // this is important as just throwing an error will always return a 500
+        // but we want to return a specific payload with a specific status
+        return NextResponse.json(apiError, { status: apiError.status });
+      }
+    };
+
+  return {
+    GET: makeVerbHandler(HttpMethod.Get),
+    POST: makeVerbHandler(HttpMethod.Post),
+  };
+};