@tpzdsp/next-toolkit 1.6.0 → 1.7.0

package/src/http/query.ts

@@ -0,0 +1,287 @@
+import {
+  type BetterFetch,
+  type CreateFetchOption,
+  type FetchSchemaRoutes,
+  type FetchSchema,
+  type StandardSchemaV1,
+  type InferOptions,
+  type Schema,
+  type BetterFetchOption,
+} from '@better-fetch/fetch';
+import {
+  useQuery,
+  useSuspenseQuery,
+  type QueryKey,
+  type UseQueryOptions,
+  type UseQueryResult,
+  type UseSuspenseQueryOptions,
+  type UseSuspenseQueryResult,
+} from '@tanstack/react-query';
+
+import type { ApiError } from '../errors';
+
+export type EmptyRoutePrefixes = '@get/' | '@post/' | '@put/' | '@patch/' | '@delete/';
+
+/**
+ * NOTE: In this file there are mentions of two kinds of schemas:
+ * - `validation schema`: A schema from a library like `zod`.
+ * - `fetch schema`: A schema from the `better-fetch` library that defines the endpoints of a specific API.
+ */
+
+// The library allows you to prefix routes with a special string to indicate the response type,
+// but the implementation means they can show up on their own as valid routes, so we remove them to prevent that.
+export type SchemaRoutes = Omit<FetchSchemaRoutes, EmptyRoutePrefixes>;
+
+// Get any routes from a fetch schema that define a body as a validation schema.
+type RoutesWithOutput<Routes> = {
+  [K in keyof Routes]: Routes[K] extends { output: unknown } ? K : never;
+}[keyof Routes];
+
+// Get any routes that DON'T define an output type as a validation schema by removing any that DO.
+type RoutesWithoutOutput<Routes> = Exclude<keyof Routes, RoutesWithOutput<Routes>>;
+
+// Get any routes from a fetch schema that define any inputs (body, query params, etc) as a validation schema.
+type RoutesWithInput<Routes> = {
+  [K in keyof Routes]: Routes[K] extends
+    | { input?: unknown } // body
+    | { params?: unknown }
+    | { query?: unknown }
+    ? K
+    : never;
+}[keyof Routes];
+
+// `better-fetch` options that prevent any body, query params, etc being passed in.
+// This is `body` instead of `input` as it is overriding fields from the *options* NOT the schema.
+type OptionsNoInputOutput = Omit<BetterFetchOption, 'query' | 'params' | 'body' | 'method'>;
+
+// Get the options out of the schema, excluding the output type. This is basically the opposite of above, as it does
+// include the inputs, like body, query params, etc.
+export type OptionsWithInput<
+  Schema extends SchemaRoutes | undefined,
+  Route extends keyof Schema,
+> = Schema extends SchemaRoutes
+  ? Schema[Route] extends FetchSchema
+    ? InferOptions<Schema[Route], Route>
+    : object
+  : object;
+
+// Extracts the ouput of a validation schema given a list of routes from a fetch schema.
+export type SchemaRouteOutput<
+  Schema extends SchemaRoutes | undefined,
+  Route extends keyof Schema,
+> = Schema extends SchemaRoutes
+  ? Schema[Route] extends FetchSchema
+    ? Schema[Route]['output'] extends StandardSchemaV1
+      ? StandardSchemaV1.InferOutput<Schema[Route]['output']>
+      : unknown
+    : unknown
+  : unknown;
+
+// Extracts the routes of a fetch schema from a config object.
+type SchemaRoutesOf<Option extends CreateFetchOption> = Option extends {
+  schema: { schema: infer Routes };
+}
+  ? Routes
+  : undefined;
+
+// We provide the `queryFn` and `queryKeys` automatically, so no need to let the user provide them.
+type OmitReactQueryKeys = 'queryKey' | 'queryFn';
+
+/**
+ * A higher-order type that creates React Query hooks (`useBetterQuerySafe` and `useBetterSuspenseQuery`)
+ * from a given `BetterFetch` fetch instance.
+ *
+ * This type uses **function overloads** to support two different ways of determining the
+ * query’s output type:
+ *
+ * 1. **Schema-inferred output** — If the provided route in the fetch schema defines an `output`
+ *    validation schema (e.g. a Zod schema), the hook automatically infers the result type from
+ *    that schema. This applies to routes captured by `RoutesWithOutput`.
+ *
+ *    ```ts
+ *    const { useBetterQuerySafe } = reactQueryBetterFetch(api);
+ *    const query = useBetterQuerySafe('/users'); // Output inferred from schema
+ *    ```
+ *
+ * 2. **Manually specified output** — If the route does **not** define an `output` schema,
+ *    the caller can manually specify the expected output type using the first generic parameter.
+ *    This applies to routes captured by `RoutesWithoutOutput`.
+ *
+ *    ```ts
+ *    const query = useBetterQuerySafe<User[]>('/users'); // Output type provided manually
+ *    ```
+ *
+ * This dual overload approach provides flexibility — it enables strict type inference
+ * where schema information is available, while still allowing convenient explicit typing for routes
+ * that lack schema-based output definitions.
+ */
+type ReactQueryBetterFetch = <
+  Option extends CreateFetchOption & { schema: Schema },
+  Routes extends SchemaRoutes | undefined = SchemaRoutesOf<Option>,
+>(
+  instance: BetterFetch<Option>,
+) => {
+  // Safe query (error NOT thrown)
+
+  // Overload that uses schema output (`RoutesWithOutput`)
+  useBetterQuerySafe<
+    Error = ApiError,
+    Route extends RoutesWithOutput<Routes> = RoutesWithOutput<Routes>,
+  >(
+    route: Route,
+    // If the route requires an input, then expect options that provide that input, otherwise just expect options without inputs.
+    fetchOptions?: Route extends RoutesWithInput<Routes>
+      ? OptionsWithInput<Routes, Route>
+      : OptionsNoInputOutput,
+    queryOptions?: Omit<
+      UseQueryOptions<unknown, Error, SchemaRouteOutput<Routes, Route>, QueryKey>,
+      OmitReactQueryKeys
+    >,
+  ): UseQueryResult<SchemaRouteOutput<Routes, Route>, Error>;
+
+  // Overload that allows manual output type instead of schema (`RoutesWithoutOutput`)
+  useBetterQuerySafe<
+    Output,
+    Error = ApiError,
+    Route extends RoutesWithoutOutput<Routes> = RoutesWithoutOutput<Routes>,
+  >(
+    route: Route,
+    fetchOptions?: Route extends RoutesWithInput<Routes>
+      ? OptionsWithInput<Routes, Route>
+      : OptionsNoInputOutput,
+    queryOptions?: Omit<UseQueryOptions<unknown, Error, Output, QueryKey>, OmitReactQueryKeys>,
+  ): UseQueryResult<Output, Error>;
+
+  // Suspense query (error thrown)
+
+  // Overload that uses schema output (`RoutesWithOutput`)
+  useBetterSuspenseQuery<
+    Route extends RoutesWithOutput<Routes>,
+    Output = SchemaRouteOutput<Routes, Route>,
+  >(
+    route: Route,
+    fetchOptions?: Route extends RoutesWithInput<Routes>
+      ? OptionsWithInput<Routes, Route>
+      : OptionsNoInputOutput,
+    queryOptions?: Omit<
+      UseSuspenseQueryOptions<unknown, never, Output, QueryKey>,
+      OmitReactQueryKeys
+    >,
+  ): UseSuspenseQueryResult<Output>;
+
+  // Overload that allows manual output type instead of schema (`RoutesWithoutOutput`)
+  useBetterSuspenseQuery<
+    Output,
+    Route extends RoutesWithoutOutput<Routes> = RoutesWithoutOutput<Routes>,
+  >(
+    route: Route,
+    fetchOptions?: Route extends RoutesWithInput<Routes>
+      ? OptionsWithInput<Routes, Route>
+      : OptionsNoInputOutput,
+    queryOptions?: Omit<
+      UseSuspenseQueryOptions<unknown, never, Output, QueryKey>,
+      OmitReactQueryKeys
+    >,
+  ): UseSuspenseQueryResult<Output>;
+};
+
+/**
+ * A wrapper around React Query that integrates with `better-fetch` for fully typed,
+ * schema-validated data fetching.
+ *
+ * It provides two hooks:
+ * - `useBetterQuerySafe` – standard React Query hook (errors handled in result)
+ * - `useBetterSuspenseQuery` – suspense-based version (errors thrown)
+ *
+ * These hooks automatically infer input and output types from the provided `better-fetch`
+ * schema where possible. If a route does not define an output schema, you can manually
+ * specify the expected output type via the first generic parameter.
+ *
+ * ⚠️ **Type inference notes:**
+ * Because of the strict type relationships between schemas, routes, and query options,
+ * invalid parameter types or missing generic arguments can sometimes produce confusing
+ * TypeScript errors (e.g. mentioning `never` types).
+ * If you encounter this, double-check that:
+ * - The route key is valid for the given schema.
+ * - All fetch/query option types align with the route definition.
+ * - An explicit output type is provided when the schema does not define one.
+ */
+
+export const reactQueryBetterFetch: ReactQueryBetterFetch = <
+  Option extends CreateFetchOption,
+  Routes extends SchemaRoutes | undefined = SchemaRoutesOf<Option>,
+>(
+  instance: BetterFetch<Option>,
+) => {
+  // The types on `BetterFetch<Option>` are extremely strict, too strict to easily
+  // prevent errors if we just called `instance`, so cast it to `any` for now to
+  // prevent type errors at the call site.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const anyInstance = instance as any;
+
+  /**
+   * React Query hook for performing a `better-fetch` request safely (errors are returned, not thrown).
+   *
+   * Automatically infers input and output types from the schema, or allows manual output typing.
+   * Wraps {@link https://tanstack.com/query/latest/docs/react/reference/useQuery useQuery} internally.
+   *
+   * @param route - The API route key defined in the `better-fetch` schema.
+   * @param fetchOptions - Optional request options (e.g. `body`, `params`, `query`) inferred from the schema.
+   * @param queryOptions - React Query options passed to `useQuery`, excluding `queryKey` and `queryFn`
+   *   which are handled automatically.
+   *
+   * @returns A standard React Query result object (`UseQueryResult`), with strongly typed data and error.
+   */
+  const useBetterQuerySafe = (
+    route: keyof Routes,
+    fetchOptions?: InferOptions<FetchSchema, ''>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    queryOptions?: Omit<UseQueryOptions<unknown, any, any, QueryKey>, OmitReactQueryKeys>,
+  ) => {
+    return useQuery({
+      ...queryOptions,
+      queryKey: [
+        route,
+        fetchOptions?.body,
+        fetchOptions?.params,
+        fetchOptions?.query,
+        fetchOptions?.headers,
+      ],
+      queryFn: () => anyInstance(route, fetchOptions),
+    });
+  };
+
+  /**
+   * React Query hook for performing a `better-fetch` request using Suspense mode.
+   *
+   * Behaves like `useBetterQuerySafe` but integrates with React Suspense — errors are thrown instead of returned.
+   * Wraps {@link https://tanstack.com/query/latest/docs/react/reference/useSuspenseQuery useSuspenseQuery} internally.
+   *
+   * @param route - The API route key defined in the `better-fetch` schema.
+   * @param fetchOptions - Optional request options (e.g. `body`, `params`, `query`) inferred from the schema.
+   * @param queryOptions - React Query options passed to `useSuspenseQuery`, excluding `queryKey` and `queryFn`
+   *   which are handled automatically.
+   *
+   * @returns A React Query suspense result (`UseSuspenseQueryResult`) with strongly typed data.
+   */
+  const useBetterSuspenseQuery = <Route extends keyof Routes>(
+    route: Route,
+    fetchOptions?: InferOptions<FetchSchema, ''>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    queryOptions?: Omit<UseQueryOptions<unknown, never, any, QueryKey>, OmitReactQueryKeys>,
+  ) => {
+    return useSuspenseQuery({
+      ...queryOptions,
+      queryKey: [
+        route,
+        fetchOptions?.body,
+        fetchOptions?.params,
+        fetchOptions?.query,
+        fetchOptions?.headers,
+      ],
+      queryFn: () => anyInstance(route, fetchOptions),
+    });
+  };
+
+  return { useBetterQuerySafe, useBetterSuspenseQuery };
+};

package/src/http/stream.ts

@@ -0,0 +1,77 @@
+import { HttpStatus } from '@tpzdsp/next-toolkit/http';
+
+import { ApiError } from '../errors';
+
+/**
+ * Reads streamed JSON X-Lines data from a response object, ignoring any invalid JSON lines.
+ *
+ * @param data Incoming response
+ * @returns Decoded JSON object.
+ */
+export const readJsonXLinesStream = async <T>(data: Response): Promise<T[]> => {
+  if (data.status === HttpStatus.NoContent) {
+    return [];
+  }
+
+  const reader = data.body?.getReader();
+
+  if (!reader) {
+    throw ApiError.badRequest('No readable stream available.');
+  }
+
+  const decoder = new TextDecoder();
+  let buffer = '';
+  const parsedLines: T[] = [];
+
+  try {
+    while (reader) {
+      const { value, done } = await reader.read();
+
+      if (done) {
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      buffer = processBufferLines<T>(buffer, parsedLines);
+    }
+
+    // Handle any remaining buffered data
+    processFinalBuffer<T>(buffer, parsedLines);
+  } finally {
+    reader.releaseLock();
+  }
+
+  return parsedLines;
+};
+
+// Extract line processing logic to reduce complexity
+const processBufferLines = <T>(buffer: string, parsedLines: T[]): string => {
+  const lines = buffer.split('\n');
+  const remainingBuffer = lines.pop() ?? ''; // leftover for next chunk
+
+  lines.forEach((line) => {
+    if (line.trim()) {
+      parseAndAddLine<T>(line, parsedLines);
+    }
+  });
+
+  return remainingBuffer;
+};
+
+// Extract final buffer processing
+const processFinalBuffer = <T>(buffer: string, parsedLines: T[]): void => {
+  if (buffer.trim()) {
+    parseAndAddLine<T>(buffer, parsedLines);
+  }
+};
+
+// Extract JSON parsing logic
+const parseAndAddLine = <T>(line: string, parsedLines: T[]): void => {
+  try {
+    const parsed = JSON.parse(line) as T;
+
+    parsedLines.push(parsed);
+  } catch (error) {
+    console.warn('Invalid JSON line:', line, 'Error:', error);
+  }
+};

package/src/types/api.ts

@@ -1,3 +1,28 @@
+import z from 'zod/v4';
+
+/**
+ * Zod schema representing a standard API error response payload from
+ * external(non-proxy) APIs.
+ *
+ * - Validates that the API returns a `detail` field as a string.
+ * - Adds a default `message` for consistency when normalizing errors.
+ * - Used internally in `normalizeError` to convert external API errors
+ *   into a consistent shape (`{ message, detail }`) that the application
+ *   can safely work with.
+ *
+ * Note:
+ * - The schema does **not** include an HTTP status code; the status is
+ *   determined separately based on the response or context.
+ */
+export const ErrorWithDetailSchema = z
+  .strictObject({
+    detail: z.string(),
+  })
+  .transform(({ detail }) => ({
+    details: detail,
+    message: 'An error occurred in the API.',
+  }));
+
 // API related types
 export type ApiResponse<T = unknown> = {
   data: T;

package/src/utils/http.ts

@@ -1,34 +1,6 @@
+import { HttpMethod, MimeType } from '../http/constants';
 import type { Response, ApiFailure } from '../types/api';
 
-export const MimeTypes = {
-  Json: 'application/json',
-  JsonLd: 'application/ld+json',
-  GeoJson: 'application/geo+json',
-  Png: 'image/png',
-  XJsonLines: 'application/x-jsonlines',
-  Csv: 'text/csv',
-} as const;
-
-export const Http = {
-  Ok: 200,
-  Created: 201,
-  NoContent: 204,
-  BadRequest: 400,
-  Unauthorized: 401,
-  Forbidden: 403,
-  NotFound: 404,
-  NotAllowed: 405,
-  InternalServerError: 500,
-} as const;
-
-export const HttpMethod = {
-  Get: 'GET',
-  Post: 'POST',
-  Put: 'PUT',
-  Patch: 'PATCH',
-  Delete: 'DELETE',
-} as const;
-
 type NodeGlobal = {
   process?: {
     env?: Record<string, string | undefined>;
@@ -133,7 +105,7 @@ const post = <Ok, Error = ApiFailure>(
     method: HttpMethod.Post,
     body: JSON.stringify(body),
     headers: {
-      'Content-Type': MimeTypes.Json,
+      'Content-Type': MimeType.Json,
       ...options?.headers,
     },
   };

package/src/utils/schema.ts

@@ -0,0 +1,30 @@
+import type { StandardSchemaV1 } from '@better-fetch/fetch';
+
+/**
+ * Creates a schema from a TypeScript type that does no validation on its input.
+ * This is useful if we want to define a schema for the sake of a type but don't actually want to run any validation on it.
+ *
+ * An example use is if we want to give query parameters types in a fetch schema, but don't need to validate them as the input
+ * values are coming from an input we control, so we know they are already valid. This would still allow the query params to have
+ * a typescript type but stops any validation for speed.
+ *
+ * @param _schema Input schema
+ * @returns The input schema but without validation
+ */
+
+export const typeOnlySchema = <Input = unknown, Output = Input>(): StandardSchemaV1<
+  Input,
+  Output
+> => ({
+  '~standard': {
+    version: 1 as const,
+    vendor: 'no-validate',
+    validate: (value: unknown): StandardSchemaV1.Result<Output> => ({
+      value: value as Output,
+    }),
+    types: {
+      input: undefined as unknown as Input,
+      output: undefined as unknown as Output,
+    },
+  },
+});