typedapi-client-helpers 0.1.7 → 0.1.9

package/README.md

@@ -2,7 +2,7 @@
 
 `typedapi-client-helpers` generates a typed TypeScript API client from an OpenAPI/Swagger document and adds reusable helper types and functions for API results, callbacks, filtering, sorting, request parameters, and multipart uploads.
 
-The package is meant for frontend projects that want a generated API client while still keeping the generated files inside their own source tree.
+The package is intended for frontend projects that want a generated API client while still keeping generated files inside their own source tree.
 
 ## Installation
 
@@ -28,7 +28,13 @@ Run the generator:
 npm run generate:api
 ```
 
-By default the generator reads the Swagger document from `https://localhost:7000/swagger/v1/swagger.json` and writes the generated API client to `src/api`.
+By default, the generator reads the Swagger document from `https://localhost:7000/swagger/v1/swagger.json` and writes the generated API client to `src/api`.
+
+You can also run the command directly:
+
+```bash
+npx typedapi-generate
+```
 
 ## Configuration
 
@@ -44,7 +50,7 @@ Configuration can be supplied in the `config` section of your `package.json`, wi
     "apiOutput": "src/api",
     "typedApiUseTypeOnlyImports": true,
     "typedApiUseFilterFormValues": false,
-    "typedApiDefaultFunctionsPath": "../../defaultApiFunctions",
+    "typedApiDefaultFunctionsPath": "src/defaultApiFunctions",
     "typedApiDefaultSuccessHandler": "handleGoodResult",
     "typedApiDefaultErrorHandler": "handleErrors"
   }
@@ -62,19 +68,22 @@ Configuration can be supplied in the `config` section of your `package.json`, wi
 | `apiOutput`                     | `src/api`                                        | Directory where the generated API files are written.                                                                           |
 | `typedApiUseTypeOnlyImports`    | `false`                                          | Generates `import type` statements for imports that are only used as types.                                                    |
 | `typedApiUseFilterFormValues`   | `false`                                          | Generates paginated methods that accept `FilterFormValues[]`, page values, and sort values instead of a prebuilt query object. |
-| `typedApiDefaultFunctionsPath`  | `../../defaultApiFunctions`                      | Import path used by generated method files for shared success and error handlers.                                              |
+| `typedApiDefaultFunctionsPath`  | `src/defaultApiFunctions`                        | Import path used by generated method files for shared success and error handlers.                                              |
 | `typedApiDefaultSuccessHandler` | `handleGoodResult`                               | Name of the default success handler function imported into generated methods.                                                  |
 | `typedApiDefaultErrorHandler`   | `handleErrors`                                   | Name of the default error handler function imported into generated methods.                                                    |
 
 ### Environment variables
 
-| Environment variable               | Description                                                     |
-| ---------------------------------- | --------------------------------------------------------------- |
-| `SWAGGER_URL`                      | URL of the OpenAPI/Swagger document.                            |
-| `SWAGGER_FILE`                     | Local path to an OpenAPI/Swagger document.                      |
-| `API_OUTPUT`                       | Directory where generated API files are written.                |
-| `TYPED_API_USE_TYPE_ONLY_IMPORTS`  | Enables type-only imports when set to `true`.                   |
-| `TYPED_API_USE_FILTER_FORM_VALUES` | Enables filter-form based paginated methods when set to `true`. |
+| Environment variable                | Description                                        |
+| ----------------------------------- | -------------------------------------------------- |
+| `SWAGGER_URL`                       | URL of the OpenAPI/Swagger document.               |
+| `SWAGGER_FILE`                      | Local path to an OpenAPI/Swagger document.         |
+| `API_OUTPUT`                        | Directory where generated API files are written.   |
+| `TYPED_API_USE_TYPE_ONLY_IMPORTS`   | Enables type-only imports when set to `true`.      |
+| `TYPED_API_USE_FILTER_FORM_VALUES`  | Enables filter-form based paginated methods.       |
+| `TYPED_API_DEFAULT_FUNCTIONS_PATH`  | Path to the shared default callback handler file.  |
+| `TYPED_API_DEFAULT_SUCCESS_HANDLER` | Export name of the shared default success handler. |
+| `TYPED_API_DEFAULT_ERROR_HANDLER`   | Export name of the shared default error handler.   |
 
 Example:
 
@@ -88,6 +97,7 @@ SWAGGER_URL=https://localhost:7000/swagger/v1/swagger.json npm run generate:api
 npm run generate:api --swagger-url=https://localhost:7000/swagger/v1/swagger.json
 npm run generate:api --swagger-file=swagger/openapi.json
 npm run generate:api --api-output=src/api
+npm run generate:api --typed-api-use-filter-form-values=true
 ```
 
 ## Generated structure
@@ -136,6 +146,39 @@ if (result.ok) {
 
 Checking `result.ok` narrows the result automatically.
 
+## Generated method argument order
+
+Generated wrappers preserve the original generated API arguments and then add optional wrapper-only arguments at the end.
+
+For query methods:
+
+```ts
+await getSuppliers(query, onSuccess, onError, params);
+```
+
+For non-query methods:
+
+```ts
+await updateSupplier(id, body, onSuccess, onError, params);
+```
+
+For filter-form paginated methods when `typedApiUseFilterFormValues` is enabled:
+
+```ts
+await getSuppliers(
+  filters,
+  page,
+  pageSize,
+  sortBy,
+  sortDirection,
+  onSuccess,
+  onError,
+  params,
+);
+```
+
+The final `params` object is forwarded to the generated HTTP client and can contain values such as headers or other request options.
+
 ## Success and error callbacks
 
 Callbacks receive the full result object, not just the raw response or error.
@@ -268,15 +311,16 @@ Arrays are appended as repeated fields, files keep their filename, primitives be
 
 ### Utility functions
 
-| Export                             | Description                                                                                                      |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `buildQuery<TQuery, TSortModel>()` | Builds a query object from filter form values, page values, and sort values.                                     |
-| `extractArgsCallbacksAndParams()`  | Splits wrapper arguments into original API arguments, success callback, error callback, and request params.      |
-| `extractArgsToastsAndParams()`     | Backwards-compatible alias-style extractor for wrapper arguments with success/error handlers and request params. |
-| `handleApiResponse()`              | Executes a generated API call and converts the response or thrown error into `ApiResult<T>`.                     |
-| `getSortTypeFromSortDirection()`   | Converts an API sort direction into a UI `SortType`.                                                             |
-| `getSortDirectionFromSortType()`   | Converts a UI `SortType` into an API sort direction.                                                             |
-| `toFormData()`                     | Converts an object payload into `FormData`.                                                                      |
+| Export                             | Description                                                                                                 |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `buildQuery<TQuery, TSortModel>()` | Builds a query object from filter form values, page values, and sort values.                                |
+| `extractArgsCallbacksAndParams()`  | Splits wrapper arguments into original API arguments, success callback, error callback, and request params. |
+| `extractArgsToastsAndParams()`     | Backwards-compatible extractor for wrapper arguments with success/error handlers and request params.        |
+| `handleApiResponse()`              | Executes a generated API call and converts the response or thrown error into `ApiResult<T>`.                |
+| `HandleApiResponseOptions<T>`      | Options object for passing success and error callbacks to `handleApiResponse`.                              |
+| `getSortTypeFromSortDirection()`   | Converts an API sort direction into a UI `SortType`.                                                        |
+| `getSortDirectionFromSortType()`   | Converts a UI `SortType` into an API sort direction.                                                        |
+| `toFormData()`                     | Converts an object payload into `FormData`.                                                                 |
 
 ### Default callback functions
 

package/dist/index.d.cts

@@ -207,6 +207,8 @@ declare function buildQuery<TQuery, TSortModel = keyof TQuery>(filters: FilterFo
 /**
  * Extracts wrapper-only arguments in this order:
  * original API arguments, onSuccess, onError, request params.
+ *
+ * Kept for backwards compatibility with generated files that used toast-oriented naming.
  */
 declare function extractArgsToastsAndParams<TArgs extends readonly unknown[], TResponse>(argsWithCallbacks: [
     ...TArgs,

package/dist/index.d.ts

@@ -207,6 +207,8 @@ declare function buildQuery<TQuery, TSortModel = keyof TQuery>(filters: FilterFo
 /**
  * Extracts wrapper-only arguments in this order:
  * original API arguments, onSuccess, onError, request params.
+ *
+ * Kept for backwards compatibility with generated files that used toast-oriented naming.
  */
 declare function extractArgsToastsAndParams<TArgs extends readonly unknown[], TResponse>(argsWithCallbacks: [
     ...TArgs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedapi-client-helpers",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Reusable typed OpenAPI client helpers.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,7 +19,7 @@
   "homepage": "https://github.com/Stef-Buurman/TypedApi/tree/main/npm/typed-api-client#readme",
   "config": {
     "apiOutput": "src/api",
-    "typedApiDefaultFunctionsPath": "../../defaultApiFunctions",
+    "typedApiDefaultFunctionsPath": "src/defaultApiFunctions",
     "typedApiDefaultSuccessHandler": "handleGoodResult",
     "typedApiDefaultErrorHandler": "handleErrors"
   },

package/scripts/generate-api-minimal.mjs

@@ -73,15 +73,17 @@ function getStringSetting(...values) {
   return undefined;
 }
 
-const fallbackDefaultFunctionsPath = "../../defaultApiFunctions";
+const fallbackDefaultFunctionsPath = "defaultApiFunctions";
 
-const defaultFunctionsPath = getStringSetting(
+const defaultFunctionsPathSetting = getStringSetting(
   process.env.TYPED_API_DEFAULT_FUNCTIONS_PATH,
   process.env.npm_config_typed_api_default_functions_path,
   config.typedApiDefaultFunctionsPath,
   fallbackDefaultFunctionsPath,
 );
 
+const defaultFunctionsFilePath = path.resolve(cwd, defaultFunctionsPathSetting);
+
 const defaultSuccessHandlerName = getStringSetting(
   process.env.TYPED_API_DEFAULT_SUCCESS_HANDLER,
   process.env.npm_config_typed_api_default_success_handler,
@@ -194,23 +196,18 @@ function resolveImportFilePath(fromDirectory, importPath) {
   return candidates.find((candidate) => fs.existsSync(candidate));
 }
 
-function createDefaultFunctionsFileIfMissing(fromDirectory, importPath) {
-  if (!importPath.startsWith(".")) {
-    return undefined;
-  }
-
-  const basePath = path.resolve(fromDirectory, importPath);
-  const extension = path.extname(basePath);
-  const filePath = extension ? basePath : `${basePath}.ts`;
+function createDefaultFunctionsFileIfMissing(filePath) {
+  const extension = path.extname(filePath);
+  const resolvedFilePath = extension ? filePath : `${filePath}.ts`;
 
-  if (fs.existsSync(filePath)) {
-    return filePath;
+  if (fs.existsSync(resolvedFilePath)) {
+    return resolvedFilePath;
   }
 
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.mkdirSync(path.dirname(resolvedFilePath), { recursive: true });
 
   fs.writeFileSync(
-    filePath,
+    resolvedFilePath,
     `
 ${createImportStatement({
   names: ["ApiErrorResult", "ApiSuccessResult"],
@@ -234,10 +231,22 @@ export function ${defaultErrorHandlerName}<T>(
   );
 
   console.log(
-    `Created default API handler file: ${path.relative(process.cwd(), filePath)}`,
+    `Created default API handler file: ${path.relative(process.cwd(), resolvedFilePath)}`,
   );
 
-  return filePath;
+  return resolvedFilePath;
+}
+
+function toRelativeImportPath(fromDirectory, filePath) {
+  let relativePath = path.relative(fromDirectory, filePath);
+
+  if (!relativePath.startsWith(".")) {
+    relativePath = `./${relativePath}`;
+  }
+
+  relativePath = relativePath.replaceAll(path.sep, "/");
+
+  return relativePath.replace(/\.(ts|tsx|js|jsx)$/, "");
 }
 
 function escapeRegExp(value) {
@@ -284,19 +293,8 @@ function fileExportsName(source, exportName) {
 
 function resolveDefaultHandlers(importFromDirectory) {
   const defaultFunctionsFile =
-    resolveImportFilePath(importFromDirectory, defaultFunctionsPath) ??
-    createDefaultFunctionsFileIfMissing(
-      importFromDirectory,
-      defaultFunctionsPath,
-    );
-
-  if (!defaultFunctionsFile) {
-    console.warn(
-      `Default API handlers were not imported because "${defaultFunctionsPath}" is not a relative path and could not be created automatically.`,
-    );
-
-    return undefined;
-  }
+    resolveImportFilePath(importFromDirectory, defaultFunctionsFilePath) ??
+    createDefaultFunctionsFileIfMissing(defaultFunctionsFilePath);
 
   const source = fs.readFileSync(defaultFunctionsFile, "utf8");
   const hasSuccessHandler = fileExportsName(source, defaultSuccessHandlerName);
@@ -319,7 +317,10 @@ function resolveDefaultHandlers(importFromDirectory) {
   }
 
   return {
-    defaultFunctionsPath,
+    defaultFunctionsPath: toRelativeImportPath(
+      importFromDirectory,
+      defaultFunctionsFile,
+    ),
     defaultSuccessHandlerName,
     defaultErrorHandlerName,
   };