@tpzdsp/next-toolkit 1.6.0 → 1.7.0

package/src/http/fetch.ts

@@ -0,0 +1,263 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import z from 'zod/v4';
+
+import {
+  createSchema as betterFetchCreateSchema,
+  createFetch as betterFetchCreateFetch,
+  type CreateFetchOption as BetterFetchCreateFetchOption,
+  type Schema,
+  type FetchSchema,
+  ValidationError,
+  BetterFetchError,
+  type BetterFetch,
+  type StandardSchemaV1,
+  type BetterFetchPlugin,
+} from '@better-fetch/fetch';
+
+import { ApiError } from '../errors';
+import { Header, isJsonMimeType, MimeType, type HttpMethods } from './constants';
+import { HttpStatus } from './constants';
+import { readJsonXLinesStream } from './stream';
+import type { ApiErrorSchemaOutput } from '../errors/ApiError';
+
+type NodeGlobal = {
+  process?: {
+    env?: Record<string, string | undefined>;
+  };
+};
+
+const isNodeEnvironment = (): boolean => {
+  const global = globalThis as NodeGlobal;
+
+  return typeof global.process?.env !== 'undefined';
+};
+
+const getNodeEnvVar = (key: string): string | undefined => {
+  if (!isNodeEnvironment()) {
+    return undefined;
+  }
+
+  const global = globalThis as NodeGlobal;
+
+  return global.process?.env?.[key];
+};
+
+const getAuth = (): CreateFetchOption['auth'] => {
+  const apiHasAuth = getNodeEnvVar('API_HAS_AUTH');
+  const apiUsername = getNodeEnvVar('API_USERNAME');
+  const apiPassword = getNodeEnvVar('API_PASSWORD');
+
+  if (apiHasAuth === 'true' && apiUsername && apiPassword) {
+    return {
+      type: 'Basic',
+      username: apiUsername,
+      password: apiPassword,
+    };
+  }
+
+  return undefined;
+};
+
+// Tries to gracefully format a value as a string, for printing in the logger
+const safeString = (value: unknown): string => {
+  try {
+    const string = typeof value === 'string' ? value : JSON.stringify(value);
+
+    if (!string) {
+      return String(value);
+    }
+
+    return string;
+  } catch {
+    return String(value);
+  }
+};
+
+// Captures any possible error from the fetch and turns it into an instance of our class, so all our errors are consistent
+export const normalizeError = async (
+  error: unknown,
+  options?: CreateFetchOption,
+): Promise<ApiError> => {
+  if (error instanceof ApiError) {
+    return error;
+  }
+
+  // Validation errors from schemas
+  if (error instanceof ValidationError) {
+    return new ApiError(
+      'Response schema validation failed.',
+      HttpStatus.BadRequest,
+      z.prettifyError(error),
+    );
+  }
+
+  // Upstream from better-fetch or when server responds with error
+  if (error instanceof BetterFetchError) {
+    // For some reason the library doesn't implement any functionality with the `errorSchema` option yet,
+    // so we do the validation ourselves (using the StandardSchemaV1 interface so it is zod-agnostic)
+    const parsed = await options?.errorSchema?.['~standard'].validate(error.error);
+
+    if (!parsed?.issues && parsed?.value) {
+      const { message, details } = parsed.value;
+
+      return new ApiError(message, error.status, details, {
+        // if we're reconstructing this error on the client from an error on the server, don't print the stack trace
+        rehydrated: typeof window !== 'undefined',
+      });
+    }
+
+    if (parsed?.issues) {
+      return new ApiError(error.statusText, error.status, z.prettifyError(parsed));
+    }
+
+    return new ApiError(
+      error.statusText,
+      error.status,
+      'Unknown error: validation returned empty result with no known issues reported.',
+    );
+  }
+
+  // Internal errors
+  if (error instanceof Error) {
+    return new ApiError(error.message, HttpStatus.InternalServerError, safeString(error.cause));
+  }
+
+  return ApiError.internalServerError('Unknown cause.');
+};
+
+// Override the options to enforce that an error schema is provided
+type CreateFetchOption = Omit<BetterFetchCreateFetchOption, 'errorSchema'> & {
+  errorSchema: StandardSchemaV1<unknown, ApiErrorSchemaOutput>;
+};
+
+// Override the schema options so we enforce a method is specified for each route
+type SchemaRoutes = Record<string, Omit<FetchSchema, 'method'> & { method: HttpMethods }>;
+
+/**
+ * Wrapper function around `@better-fetch/fetch` `createSchema` which creates a strict schema.
+ *
+ * A fetch schema is used to describe a list of routes, their HTTP method, inputs, and outputs.
+ *
+ * @param schema
+ * @param config
+ * @returns
+ */
+export const createSchema = <Routes extends SchemaRoutes>(schema: Routes) => {
+  return betterFetchCreateSchema(schema, {
+    strict: true,
+  });
+};
+
+// Utility type to merge two objects (used for merging schemas together)
+type MergeTwo<A, B> = {
+  [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never;
+};
+
+// Takes an array of schemas and merges all the routes together
+type MergeSchemasInner<T extends Schema[], Key extends keyof Schema> = T extends [
+  infer First extends Schema,
+  ...infer Rest extends Schema[],
+]
+  ? MergeTwo<First[Key], MergeSchemasInner<Rest, Key>>
+  : object;
+
+// Merges the schemas from an array, so multiple schemas can be provided.
+type MergeSchemas<T extends Schema[]> = {
+  schema: MergeSchemasInner<T, 'schema'>;
+  config: MergeSchemasInner<T, 'config'>;
+};
+
+// A custom plugin mainly used to fix a few bugs or add handling to extra content types, etc.
+const TOOLKIT_PLUGIN = {
+  id: 'toolkit-plugin',
+  name: 'Toolkit Plugin',
+  init: (url, options) => {
+    // If the body is `null` but no content type was supplied, it will try and detect it but error
+    // due to accessing a field on a null value. We handle this by setting the content type header
+    // if it doesn't exist and the body is null.
+    if (options?.body === null && !(options.headers as any)?.[Header.ContentType]) {
+      (options.headers as any)[Header.ContentType] = MimeType.Json;
+    }
+
+    return { url, options };
+  },
+  hooks: {
+    onRequest: (context) => {
+      // for some reason if you specify a JSON content type, better-fetch will not stringify the body
+      // but as we also have extra JSON mime types, we need to handle that
+      if (isJsonMimeType(context.headers.get(Header.ContentType))) {
+        context.body = JSON.stringify(context.body);
+      }
+
+      return context;
+    },
+    onResponse: (context) => {
+      if (context.response.headers.get(Header.ContentType)?.includes(MimeType.XJsonLines)) {
+        // `better-fetch` does not allow for handling of content types it doesn't know about, and it will
+        // always fall back to `.blob()`. We need to stream JSON X-Lines, so I do a hack to replace
+        // the blob function to return the streamed data instead. I am confident this is okay, as not only
+        // will it replace the function ONLY for this one content type, our custom plugin is always the LAST
+        // in the array, so it wouldn't mess with any other plugins that may use this.
+        (context.response as any).blob = async () => {
+          return await readJsonXLinesStream(context.response);
+        };
+      }
+
+      return context;
+    },
+  },
+} satisfies BetterFetchPlugin;
+
+/**
+ * Creates a fully typed and schema-validated fetch client by combining one or more `better-fetch` schemas.
+ *
+ * This wrapper extends the base `better-fetch` `createFetch` with:
+ * - **Automatic schema merging** — allows multiple schemas to be combined into one fetch instance.
+ * - **Enhanced error handling** — all thrown errors are normalized into consistent {@link ApiError} instances.
+ * - **Toolkit plugin** — adds extra handling for JSON content types, streaming JSON X-Lines responses,
+ *   and fixes some edge-case behaviors in the library.
+ * - **Automatic basic auth** — reads credentials from environment variables if available.
+ *
+ * The resulting client can be used exactly like a `better-fetch` instance, with full type inference
+ * for routes, inputs, and outputs derived from the merged schemas.
+ *
+ * @template Schemas - One or more `better-fetch` schemas to merge.
+ * @template Option - Configuration options, including enforced `errorSchema` type.
+ * @param schemas - An array of fetch schemas to merge into a single client.
+ * @param config - Optional configuration object passed to `better-fetch`, extended with defaults and plugins.
+ * @returns A `BetterFetch` instance with merged schema routes, automatic plugin registration, and normalized error handling.
+ *
+ * @see {@link https://github.com/better-fetch/better-fetch | better-fetch on GitHub}
+ */
+export const createFetch = <
+  Schemas extends Schema[],
+  Option extends CreateFetchOption = CreateFetchOption,
+>(
+  schemas: [...Schemas],
+  config?: Option,
+): BetterFetch<
+  Omit<Option, 'schema'> & {
+    schema: MergeSchemas<Schemas>;
+  }
+> => {
+  const mergedSchema = {
+    schema: Object.assign({}, ...schemas.map((s) => s.schema)),
+    config: Object.assign({}, ...schemas.map((s) => s.config)),
+  };
+
+  const instance = betterFetchCreateFetch({
+    schema: mergedSchema,
+    auth: getAuth(),
+    ...config,
+    plugins: [...(config?.plugins ?? []), TOOLKIT_PLUGIN],
+  });
+
+  // Wrap the fetcher to catch & normalize errors
+  return (async (...args) => {
+    try {
+      return await instance(...args);
+    } catch (err) {
+      throw await normalizeError(err, config);
+    }
+  }) as typeof instance;
+};

package/src/http/index.ts

@@ -0,0 +1,6 @@
+export * from './constants';
+export * from './logger';
+export * from './fetch';
+export * from './query';
+export * from './proxy';
+export * from './stream';

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),
+  };
+};