typedapi-client-helpers 0.1.3 → 0.1.5

package/README.md

@@ -1,36 +1,33 @@
 # typedapi-client-helpers
 
-Reusable TypeScript helpers for generated typed OpenAPI clients.
-
-## What this package includes
-
-* `typedapi-generate` CLI command
-* OpenAPI TypeScript client generation
-* Typed API wrapper methods
-* Typed query and pagination helpers
-* `ApiResult<T>` response wrapper
-* Toast helpers using `react-toastify`
-* `TypedApiToastProvider`
-* `buildQuery` helper for filters, paging, and sorting
-* `toFormData` helper for file uploads
-* Unauthorized handling for `401` responses
-* Sort direction conversion helpers
+Generate a typed TypeScript API client from an OpenAPI/Swagger document and use reusable helpers for API responses, filtering, sorting, pagination, callbacks, and multipart form data.
 
-## Installation
+The generated client uses the native `fetch` API and is created inside your own project, so the generated models and methods remain available for inspection and customization.
 
-```bash
-npm install typedapi-client-helpers
-```
+## Features
+
+* Generates TypeScript models and API methods from OpenAPI
+* Uses the native `fetch` API
+* Generates methods grouped by OpenAPI tags
+* Creates typed wrapper methods around generated requests
+* Returns a consistent `ApiResult<T>`
+* Supports success and error callbacks
+* Supports custom request parameters and headers
+* Supports query parameters, pagination, filtering, and sorting
+* Converts upload payloads to `FormData`
+* Supports local Swagger files and remote Swagger URLs
+* Supports type-only imports
+* Works with TypeScript frontend projects such as React, Angular, and Vue
 
-This package expects React to already be installed:
+## Installation
 
 ```bash
-npm install react react-dom react-toastify
+npm install typedapi-client-helpers
 ```
 
-## Generate API files
+## Add the generator command
 
-Add a script to your project:
+Add the following script to your project's `package.json`:
 
 ```json
 {
@@ -40,33 +37,41 @@ Add a script to your project:
 }
 ```
 
-Run:
+You can then generate the API client with:
 
 ```bash
 npm run generate:api
 ```
 
-By default, the generator reads Swagger from:
+## Configuration
 
-```text
-https://localhost:7000/swagger/v1/swagger.json
-```
+The generator can be configured through the `config` property in your project's `package.json`.
 
-and writes generated files to:
+### Generate from a Swagger URL
 
-```text
-src/api
+```json
+{
+  "scripts": {
+    "generate:api": "typedapi-generate"
+  },
+  "config": {
+    "swaggerUrl": "https://localhost:7000/swagger/v1/swagger.json",
+    "apiOutput": "src/api",
+    "typedApiUseTypeOnlyImports": true,
+    "typedApiUseFilterFormValues": false
+  }
+}
 ```
 
-## Configuration
-
-Configure the generator in your `package.json`:
+### Generate from a local Swagger file
 
 ```json
 {
+  "scripts": {
+    "generate:api": "typedapi-generate"
+  },
   "config": {
-    "swaggerUrl": "https://localhost:7000/swagger/v1/swagger.json",
-    "swaggerFile": "./swagger.json",
+    "swaggerFile": "swagger/openapi.json",
     "apiOutput": "src/api",
     "typedApiUseTypeOnlyImports": true,
     "typedApiUseFilterFormValues": false
@@ -74,94 +79,598 @@ Configure the generator in your `package.json`:
 }
 ```
 
-### Available Settings
+When `swaggerFile` is configured, it takes precedence over `swaggerUrl`.
+
+## Configuration options
+
+| Option                        | Default                                          | Description                                              |
+| ----------------------------- | ------------------------------------------------ | -------------------------------------------------------- |
+| `swaggerUrl`                  | `https://localhost:7000/swagger/v1/swagger.json` | URL of the OpenAPI document                              |
+| `swaggerFile`                 | —                                                | Path to a local OpenAPI document                         |
+| `apiOutput`                   | `src/api`                                        | Directory where the generated API is written             |
+| `typedApiUseTypeOnlyImports`  | `false`                                          | Generates `import type` statements for type-only imports |
+| `typedApiUseFilterFormValues` | `false`                                          | Generates filter-form arguments for paginated methods    |
+
+## Environment variables
 
-| Setting                       | Description                                                      | Default                                          |
-| ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
-| `swaggerUrl`                  | URL to the Swagger/OpenAPI document                              | `https://localhost:7000/swagger/v1/swagger.json` |
-| `swaggerFile`                 | Local Swagger/OpenAPI file. Overrides `swaggerUrl` when provided | Not set                                          |
-| `apiOutput`                   | Output directory for generated files                             | `src/api`                                        |
-| `typedApiUseTypeOnlyImports`  | Uses `import type` statements when possible                      | `false`                                          |
-| `typedApiUseFilterFormValues` | Generates pagination methods using `FilterFormValues[]`          | `false`                                          |
+Configuration can also be supplied through environment variables.
 
-### Environment Variables
+| Environment variable               | Description                                              |
+| ---------------------------------- | -------------------------------------------------------- |
+| `SWAGGER_URL`                      | URL of the OpenAPI document                              |
+| `SWAGGER_FILE`                     | Path to a local OpenAPI document                         |
+| `API_OUTPUT`                       | Generated API output directory                           |
+| `TYPED_API_USE_TYPE_ONLY_IMPORTS`  | Enables type-only imports when set to `true`             |
+| `TYPED_API_USE_FILTER_FORM_VALUES` | Enables filter-form method generation when set to `true` |
+
+Example:
 
 ```bash
 SWAGGER_URL=https://localhost:7000/swagger/v1/swagger.json npm run generate:api
-SWAGGER_FILE=./swagger.json npm run generate:api
-API_OUTPUT=src/api npm run generate:api
-TYPED_API_USE_TYPE_ONLY_IMPORTS=true npm run generate:api
-TYPED_API_USE_FILTER_FORM_VALUES=true npm run generate:api
 ```
 
-## Usage
+Command-line npm configuration is also supported:
+
+```bash
+npm run generate:api --swagger-url=https://localhost:7000/swagger/v1/swagger.json
+```
+
+```bash
+npm run generate:api --swagger-file=swagger/openapi.json
+```
+
+```bash
+npm run generate:api --api-output=src/api
+```
+
+## Generated structure
+
+Running the generator creates an API directory similar to:
+
+```text
+src/
+└── api/
+    ├── generated/
+    │   ├── data-contracts.ts
+    │   ├── http-client.ts
+    │   ├── Product.ts
+    │   ├── ProductRoute.ts
+    │   ├── Supplier.ts
+    │   └── SupplierRoute.ts
+    ├── methods/
+    │   ├── Product.api.ts
+    │   └── Supplier.api.ts
+    └── index.ts
+```
+
+The `generated` directory contains the client produced from the OpenAPI document.
+
+The `methods` directory contains typed wrapper functions that:
 
-Import generated API functions:
+* Handle successful and failed responses
+* Return `ApiResult<T>`
+* Support success and error callbacks
+* Accept custom request parameters
+* Convert multipart request objects to `FormData`
+
+## Export the generated API
+
+Create or update `src/api/index.ts` so consumers can import the generated types and methods from one location:
+
+```ts
+export * from "./generated/data-contracts";
+export * from "./generated/http-client";
+
+export * from "./methods/Product.api";
+export * from "./methods/Supplier.api";
+```
+
+The exact method files depend on the tags in your OpenAPI document.
+
+## Calling generated methods
+
+Generated wrapper methods return a typed `ApiResult<T>`.
 
 ```ts
-import { getProducts } from "./api";
+import { getSuppliers } from "./api";
 
-const result = await getProducts();
+const result = await getSuppliers({
+  pageNumber: 1,
+  pageSize: 25,
+});
 
 if (result.ok) {
-    console.log(result.response);
+  console.log(result.response);
+} else {
+  console.error(result.status, result.error);
 }
 ```
 
-### Toast Notifications
+`ApiResult<T>` is a discriminated union:
 
 ```ts
-await createProduct(product, {
-    toastSuccess: {
-        title: "Saved",
-        message: "Product created successfully."
-    },
-    toastError: {
-        title: "Error",
-        message: "Unable to create product."
+type ApiResult<T> =
+  | {
+      ok: true;
+      status: number;
+      response: T;
     }
+  | {
+      ok: false;
+      status: number;
+      response?: T;
+      error: unknown;
+    };
+```
+
+Checking `result.ok` automatically narrows the result to either the successful or failed response type.
+
+## Success and error callbacks
+
+Generated methods support optional success and error callbacks.
+
+```ts
+import { getSuppliers } from "./api";
+
+const result = await getSuppliers(
+  {
+    pageNumber: 1,
+    pageSize: 25,
+  },
+  async (response) => {
+    console.log("Suppliers loaded:", response);
+  },
+  async (error) => {
+    console.error("Unable to load suppliers:", error);
+  },
+);
+```
+
+The method still returns an `ApiResult<T>`, even when callbacks are provided.
+
+## Create and update requests
+
+Body-based API methods keep the argument types generated from the OpenAPI document.
+
+```ts
+import { createSupplier } from "./api";
+
+const result = await createSupplier({
+  id: "supplier-1",
+  name: "Example Supplier",
+  active: true,
+  countryCode: "NL",
+  email: "supplier@example.com",
+  rating: 4.5,
 });
+
+if (!result.ok) {
+  console.error("Supplier creation failed:", result.error);
+}
+```
+
+Callbacks can be added after the generated API arguments:
+
+```ts
+await createSupplier(
+  {
+    id: "supplier-1",
+    name: "Example Supplier",
+    active: true,
+    countryCode: "NL",
+    email: "supplier@example.com",
+    rating: 4.5,
+  },
+  (supplier) => {
+    console.log("Created supplier:", supplier);
+  },
+  (error) => {
+    console.error("Creation failed:", error);
+  },
+);
+```
+
+## Custom request parameters
+
+The final argument of a generated wrapper method can contain request configuration supported by the generated HTTP client.
+
+For example, custom headers can be supplied as follows:
+
+```ts
+import { getSuppliers } from "./api";
+
+const result = await getSuppliers(
+  {
+    pageNumber: 1,
+    pageSize: 25,
+  },
+  undefined,
+  undefined,
+  {
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  },
+);
 ```
 
-Add the provider once in your application:
+## Filter-form generation
 
-```tsx
-import { TypedApiToastProvider } from "typedapi-client-helpers";
+Set `typedApiUseFilterFormValues` to `true` to generate paginated methods that accept filter-form values rather than a query object.
 
-function App() {
-    return (
-        <>
-            <TypedApiToastProvider />
-            {/* application */}
-        </>
-    );
+```json
+{
+  "config": {
+    "swaggerUrl": "https://localhost:7000/swagger/v1/swagger.json",
+    "apiOutput": "src/api",
+    "typedApiUseFilterFormValues": true
+  }
 }
 ```
 
-### File Uploads
+A generated paginated method can then be called with filters, pagination, and sorting:
+
+```ts
+import type { FilterFormValues } from "typedapi-client-helpers";
+import {
+  getSuppliers,
+  type GetSuppliersQuery,
+} from "./api";
+
+const filters: FilterFormValues<GetSuppliersQuery>[] = [
+  {
+    name: "Supplier name",
+    filterName: "name",
+    type: "string",
+    value: "Example",
+    isAList: false,
+  },
+  {
+    name: "Active",
+    filterName: "active",
+    type: "boolean",
+    value: true,
+    isAList: false,
+  },
+];
+
+const result = await getSuppliers(
+  filters,
+  1,
+  25,
+  "name",
+  "Ascending",
+);
+```
+
+Empty filter values are ignored automatically.
+
+## Supported filter types
+
+```ts
+type FilterType =
+  | "number"
+  | "date"
+  | "string"
+  | "timespan"
+  | "boolean"
+  | "boolean-button"
+  | "OptionValue";
+```
+
+A filter configuration uses the following structure:
+
+```ts
+interface FilterFormValues<TQuery> {
+  name: string;
+  filterName: keyof TQuery;
+  filterNameMax?: keyof TQuery;
+  type: FilterType;
+  value:
+    | number
+    | string
+    | Date
+    | boolean
+    | null
+    | OptionValue[]
+    | string[];
+  maxValue?: number | string | Date | null;
+  isAList: boolean;
+}
+```
+
+## Range filters
+
+Use `filterNameMax` and `maxValue` to create range filters:
+
+```ts
+const filters: FilterFormValues<GetSuppliersQuery>[] = [
+  {
+    name: "Minimum rating",
+    filterName: "minimumRating",
+    filterNameMax: "maximumRating",
+    type: "number",
+    value: 3,
+    maxValue: 5,
+    isAList: false,
+  },
+];
+```
+
+## Option filters
+
+Option-based filters display a name while sending a separate value to the API.
+
+```ts
+import type {
+  FilterFormValues,
+  OptionValue,
+} from "typedapi-client-helpers";
+
+const countries: OptionValue[] = [
+  {
+    name: "Netherlands",
+    value: "NL",
+  },
+  {
+    name: "Belgium",
+    value: "BE",
+  },
+];
+
+const filters: FilterFormValues<GetSuppliersQuery>[] = [
+  {
+    name: "Countries",
+    filterName: "countryCodes",
+    type: "OptionValue",
+    value: countries,
+    isAList: true,
+  },
+];
+```
+
+The generator sends the values `"NL"` and `"BE"` rather than the display names.
+
+## Using `buildQuery` directly
+
+The `buildQuery` helper can also be used without generated filter-form methods.
+
+```ts
+import {
+  buildQuery,
+  type FilterFormValues,
+} from "typedapi-client-helpers";
+
+interface ProductQuery {
+  name?: string;
+  minimumPrice?: number;
+  maximumPrice?: number;
+  pageNumber?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortDirection?: string;
+}
+
+const filters: FilterFormValues<ProductQuery>[] = [
+  {
+    name: "Name",
+    filterName: "name",
+    type: "string",
+    value: "Laptop",
+    isAList: false,
+  },
+  {
+    name: "Price",
+    filterName: "minimumPrice",
+    filterNameMax: "maximumPrice",
+    type: "number",
+    value: 500,
+    maxValue: 1500,
+    isAList: false,
+  },
+];
+
+const query = buildQuery<ProductQuery>(
+  filters,
+  1,
+  25,
+  "name",
+  "Ascending",
+);
+```
+
+The result is equivalent to:
+
+```ts
+{
+  name: "Laptop",
+  minimumPrice: 500,
+  maximumPrice: 1500,
+  pageNumber: 1,
+  pageSize: 25,
+  sortBy: "name",
+  sortDirection: "Ascending"
+}
+```
+
+## Sorting helpers
+
+The package includes helpers for converting between UI sort states and API sort directions.
+
+```ts
+import {
+  getSortDirectionFromSortType,
+  getSortTypeFromSortDirection,
+} from "typedapi-client-helpers";
+
+const apiDirection =
+  getSortDirectionFromSortType("Neutral");
+
+// "Default"
+
+const uiSortType =
+  getSortTypeFromSortDirection("Descending");
+
+// "Descending"
+```
+
+Supported UI sort states are:
+
+```ts
+type SortType =
+  | "Default"
+  | "Neutral"
+  | "Ascending"
+  | "Descending";
+```
+
+`Neutral` is a UI-only state and is converted to `Default` before it is sent to the API.
+
+## File uploads
+
+Multipart methods are detected during generation. Their payloads are converted to `FormData` automatically.
+
+```ts
+import { uploadDocument } from "./api";
+
+const result = await uploadDocument({
+  file: selectedFile,
+  description: "Supplier contract",
+});
+```
+
+The `toFormData` helper supports:
+
+* `File`
+* `Blob`
+* Arrays of files or values
+* Strings
+* Numbers
+* Booleans
+* Nested objects
+
+Nested objects are serialized as JSON strings.
+
+You can also use the helper directly:
 
 ```ts
 import { toFormData } from "typedapi-client-helpers";
 
 const formData = toFormData({
-    file,
-    description: "Import file"
+  file: selectedFile,
+  tags: ["contract", "supplier"],
+  metadata: {
+    department: "Purchasing",
+  },
 });
 ```
 
-## Recommended Project Setup
+## Handling HTTP responses directly
 
-```text
-src/
-├── api/
-│   ├── clients/
-│   ├── models/
-│   └── index.ts
-├── pages/
-├── components/
-└── services/
+The `handleApiResponse` helper can wrap any compatible generated HTTP request:
+
+```ts
+import {
+  handleApiResponse,
+  type HttpResponse,
+} from "typedapi-client-helpers";
+
+interface Product {
+  id: string;
+  name: string;
+}
+
+async function requestProduct(): Promise<
+  HttpResponse<Product>
+> {
+  // Return a compatible generated HTTP response.
+  throw new Error("Implement request");
+}
+
+const result = await handleApiResponse(
+  () => requestProduct(),
+  {
+    onSuccess: (product) => {
+      console.log(product);
+    },
+    onError: (error) => {
+      console.error(error);
+    },
+  },
+);
 ```
 
-## Notes
+The response body is parsed as JSON when the response content type contains `application/json`. Empty responses, including HTTP `204` responses, return `undefined`.
+
+## Regenerating the client
 
-Generated files should not be manually modified. Regenerate them whenever the backend OpenAPI specification changes.
+Run the generator whenever the OpenAPI document changes:
+
+```bash
+npm run generate:api
+```
+
+The existing generated and method directories inside the configured API output are replaced during generation. Keep custom application code outside those generated directories.
+
+## Recommended workflow
+
+1. Start the backend API.
+2. Confirm that its OpenAPI document is available.
+3. Run the API generator.
+4. Build or start the frontend application.
+
+Example:
+
+```bash
+npm run generate:api
+npm run dev
+```
+
+## Package exports
+
+The package exports the following reusable types and helpers:
+
+```ts
+import {
+  buildQuery,
+  getSortDirectionFromSortType,
+  getSortTypeFromSortDirection,
+  handleApiResponse,
+  sortTypes,
+  toFormData,
+} from "typedapi-client-helpers";
+
+import type {
+  ApiErrorHandler,
+  ApiMethodCallbacks,
+  ApiResult,
+  ApiSuccessHandler,
+  FilterFormValues,
+  FilterType,
+  HttpResponse,
+  OptionValue,
+  SortType,
+} from "typedapi-client-helpers";
+```
+
+Generated API models and methods are written into your project and should be imported from your configured API output directory:
+
+```ts
+import {
+  createSupplier,
+  getSuppliers,
+  type SupplierModel,
+} from "./api";
+```
+
+## TypeScript
+
+The package includes generated declaration files and can be used directly in TypeScript projects.
+
+```ts
+import type {
+  ApiResult,
+  FilterFormValues,
+  SortType,
+} from "typedapi-client-helpers";
+```