typedapi-client-helpers 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 /**
- * Standard result wrapper for API calls.
+ * Standard result wrapper returned by generated API wrapper methods.
  *
  * When `ok` is true, the request succeeded and `response` contains the expected data.
  * When `ok` is false, the request failed and `error` contains the thrown or returned error value.
@@ -14,6 +14,22 @@ type ApiResult<T> = {
     response?: T;
     error: unknown;
 };
+/**
+ * Narrowed success branch of `ApiResult<T>`.
+ *
+ * Use this type for success callbacks or helper functions that should only receive successful API results.
+ */
+type ApiSuccessResult<T> = Extract<ApiResult<T>, {
+    ok: true;
+}>;
+/**
+ * Narrowed error branch of `ApiResult<T>`.
+ *
+ * Use this type for error callbacks or helper functions that should only receive failed API results.
+ */
+type ApiErrorResult<T> = Extract<ApiResult<T>, {
+    ok: false;
+}>;
 
 /**
  * Supported filter input types used by typed filter forms.
@@ -87,11 +103,37 @@ declare enum ContentType {
     Text = "text/plain"
 }
 
+/**
+ * Extracts the successful response body type from a generated API method promise.
+ *
+ * Example: `Promise<HttpResponse<Product, Error>>` becomes `Product`.
+ */
 type ExtractResponse<T> = T extends Promise<HttpResponse$1<infer Response, unknown>> ? Response : never;
+/**
+ * Extracts the error response body type from a generated API method promise.
+ *
+ * Example: `Promise<HttpResponse<Product, ApiError>>` becomes `ApiError`.
+ */
+type ExtractError<T> = T extends Promise<HttpResponse$1<unknown, infer Error>> ? Error : never;
+/**
+ * Extracts the item type from an array, otherwise returns the original type.
+ *
+ * Example: `Product[]` becomes `Product`, while `Product` stays `Product`.
+ */
 type UnwrapArray<T> = T extends readonly (infer Item)[] ? Item : T;
+/**
+ * Extracts the item type from common paginated response shapes.
+ *
+ * Example: `{ data?: Product[] }` becomes `Product`.
+ */
 type ExtractDataIfPaginated<T> = T extends {
     data?: readonly (infer Item)[] | null;
 } ? Item : T;
+/**
+ * Keys that can be used as sort fields for an API response type.
+ *
+ * For paginated responses this uses the keys of the item inside `data`.
+ */
 type SortableKeys<T> = keyof UnwrapArray<ExtractDataIfPaginated<T>>;
 /**
  * Removes the optional RequestParams argument from the end
@@ -105,10 +147,7 @@ type SortableKeys<T> = keyof UnwrapArray<ExtractDataIfPaginated<T>>;
  *
  * [data: CreateSupplierParams]
  */
-type WithoutRequestParams<T extends readonly unknown[]> = T extends readonly [
-    ...infer Arguments,
-    RequestParams?
-] ? Arguments : T;
+type WithoutRequestParams<T extends readonly unknown[]> = T extends readonly [...infer Arguments, RequestParams?] ? Arguments : T;
 
 /**
  * Extended fetch response returned by the generated HTTP client.
@@ -126,14 +165,35 @@ interface HttpResponse<D extends unknown, E extends unknown = unknown> extends R
  */
 type RuntimeRequestParams = Record<string, unknown>;
 
-type ApiSuccessHandler<TResponse> = (response: TResponse) => void | Promise<void>;
-type ApiErrorHandler<TError = unknown> = (error: TError) => void | Promise<void>;
-type ApiMethodCallbacks<TResponse, TError = unknown> = {
+/**
+ * Function called after a generated wrapper method receives a successful API result.
+ *
+ * The callback receives the success-only branch of `ApiResult<TResponse>`.
+ */
+type ApiSuccessHandler<TResponse> = (result: ApiSuccessResult<TResponse>) => void | Promise<void>;
+/**
+ * Function called after a generated wrapper method receives a failed API result.
+ *
+ * The callback receives the error-only branch of `ApiResult<TResponse>`.
+ */
+type ApiErrorHandler<TResponse> = (result: ApiErrorResult<TResponse>) => void | Promise<void>;
+/**
+ * Optional callback and request-parameter object accepted by generated API wrapper methods.
+ *
+ * `onSuccess` runs for successful responses, `onError` runs for failed responses,
+ * and `params` is forwarded to the generated HTTP client.
+ */
+type ApiMethodCallbacks<TResponse> = {
     onSuccess?: ApiSuccessHandler<TResponse>;
-    onError?: ApiErrorHandler<TError>;
+    onError?: ApiErrorHandler<TResponse>;
     params?: RequestParams;
 };
 
+/**
+ * Sort direction value accepted by generated query objects.
+ *
+ * APIs often expose sort direction as either a string enum or numeric enum, so both are supported.
+ */
 type SortDirection = number | string;
 /**
  * Builds a typed query object from filter form values, pagination, and sorting.
@@ -148,23 +208,53 @@ declare function buildQuery<TQuery, TSortModel = keyof TQuery>(filters: FilterFo
  * Extracts wrapper-only arguments in this order:
  * original API arguments, onSuccess, onError, request params.
  */
-declare function extractArgsCallbacksAndParams<TArgs extends readonly unknown[], TSuccess, TError = unknown>(argsWithCallbacks: [
+declare function extractArgsToastsAndParams<TArgs extends readonly unknown[], TResponse>(argsWithCallbacks: [
+    ...TArgs,
+    ApiSuccessHandler<TResponse>?,
+    ApiErrorHandler<TResponse>?,
+    RuntimeRequestParams?
+]): {
+    args: TArgs;
+    onSuccess?: ApiSuccessHandler<TResponse>;
+    onError?: ApiErrorHandler<TResponse>;
+    params?: RuntimeRequestParams;
+};
+
+/**
+ * Extracts wrapper arguments in this order:
+ *
+ * 1. Original API arguments
+ * 2. Optional success callback
+ * 3. Optional error callback
+ * 4. Optional request params
+ */
+declare function extractArgsCallbacksAndParams<TArgs extends unknown[], TResponse, _TError = unknown>(argsWithCallbacks: [
     ...TArgs,
-    ApiSuccessHandler<TSuccess>?,
-    ApiErrorHandler<TError>?,
+    ApiSuccessHandler<TResponse>?,
+    ApiErrorHandler<TResponse>?,
     RuntimeRequestParams?
 ]): {
     args: TArgs;
-    onSuccess?: ApiSuccessHandler<TSuccess>;
-    onError?: ApiErrorHandler<TError>;
+    onSuccess?: ApiSuccessHandler<TResponse>;
+    onError?: ApiErrorHandler<TResponse>;
     params?: RuntimeRequestParams;
 };
 
-type HandleApiResponseOptions<TResponse, TError = unknown> = {
+/**
+ * Optional callbacks used while converting a generated HTTP response into `ApiResult<TResponse>`.
+ *
+ * `onSuccess` is called with `ApiSuccessResult<TResponse>` and `onError` is called with `ApiErrorResult<TResponse>`.
+ */
+type HandleApiResponseOptions<TResponse> = {
     onSuccess?: ApiSuccessHandler<TResponse>;
-    onError?: ApiErrorHandler<TError>;
+    onError?: ApiErrorHandler<TResponse>;
 };
-declare function handleApiResponse<TResponse, TError = unknown>(call: () => Promise<HttpResponse<TResponse, TError>>, options?: HandleApiResponseOptions<TResponse, TError>): Promise<ApiResult<TResponse>>;
+/**
+ * Executes a generated API request and converts the result into `ApiResult<TResponse>`.
+ *
+ * Successful responses return `{ ok: true, status, response }`. Failed responses and thrown errors return `{ ok: false, status, error }`.
+ */
+declare function handleApiResponse<TResponse, TError>(call: () => Promise<HttpResponse<TResponse, TError>>, options?: HandleApiResponseOptions<TResponse>): Promise<ApiResult<TResponse>>;
 
 /** Values supported by the generated API SortDirection enum. */
 type ApiSortDirection = "Default" | "Ascending" | "Descending";
@@ -195,4 +285,4 @@ declare function getSortDirectionFromSortType(sortType: SortType | null | undefi
  */
 declare function toFormData<T extends object>(payload: T): FormData;
 
-export { type ApiErrorHandler, type ApiMethodCallbacks, type ApiResult, type ApiSortDirection, type ApiSuccessHandler, type ExtractDataIfPaginated, type ExtractResponse, type FilterFormValues, type FilterType, type HandleApiResponseOptions, type HttpResponse, type OptionValue, type RuntimeRequestParams, type SortDirection, type SortType, type SortableKeys, type UnwrapArray, type WithoutRequestParams, buildQuery, extractArgsCallbacksAndParams, getSortDirectionFromSortType, getSortTypeFromSortDirection, handleApiResponse, sortTypes, toFormData };
+export { type ApiErrorHandler, type ApiErrorResult, type ApiMethodCallbacks, type ApiResult, type ApiSortDirection, type ApiSuccessHandler, type ApiSuccessResult, type ExtractDataIfPaginated, type ExtractError, type ExtractResponse, type FilterFormValues, type FilterType, type HandleApiResponseOptions, type HttpResponse, type OptionValue, type RuntimeRequestParams, type SortDirection, type SortType, type SortableKeys, type UnwrapArray, type WithoutRequestParams, buildQuery, extractArgsCallbacksAndParams, extractArgsToastsAndParams, getSortDirectionFromSortType, getSortTypeFromSortDirection, handleApiResponse, sortTypes, toFormData };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Standard result wrapper for API calls.
+ * Standard result wrapper returned by generated API wrapper methods.
  *
  * When `ok` is true, the request succeeded and `response` contains the expected data.
  * When `ok` is false, the request failed and `error` contains the thrown or returned error value.
@@ -14,6 +14,22 @@ type ApiResult<T> = {
     response?: T;
     error: unknown;
 };
+/**
+ * Narrowed success branch of `ApiResult<T>`.
+ *
+ * Use this type for success callbacks or helper functions that should only receive successful API results.
+ */
+type ApiSuccessResult<T> = Extract<ApiResult<T>, {
+    ok: true;
+}>;
+/**
+ * Narrowed error branch of `ApiResult<T>`.
+ *
+ * Use this type for error callbacks or helper functions that should only receive failed API results.
+ */
+type ApiErrorResult<T> = Extract<ApiResult<T>, {
+    ok: false;
+}>;
 
 /**
  * Supported filter input types used by typed filter forms.
@@ -87,11 +103,37 @@ declare enum ContentType {
     Text = "text/plain"
 }
 
+/**
+ * Extracts the successful response body type from a generated API method promise.
+ *
+ * Example: `Promise<HttpResponse<Product, Error>>` becomes `Product`.
+ */
 type ExtractResponse<T> = T extends Promise<HttpResponse$1<infer Response, unknown>> ? Response : never;
+/**
+ * Extracts the error response body type from a generated API method promise.
+ *
+ * Example: `Promise<HttpResponse<Product, ApiError>>` becomes `ApiError`.
+ */
+type ExtractError<T> = T extends Promise<HttpResponse$1<unknown, infer Error>> ? Error : never;
+/**
+ * Extracts the item type from an array, otherwise returns the original type.
+ *
+ * Example: `Product[]` becomes `Product`, while `Product` stays `Product`.
+ */
 type UnwrapArray<T> = T extends readonly (infer Item)[] ? Item : T;
+/**
+ * Extracts the item type from common paginated response shapes.
+ *
+ * Example: `{ data?: Product[] }` becomes `Product`.
+ */
 type ExtractDataIfPaginated<T> = T extends {
     data?: readonly (infer Item)[] | null;
 } ? Item : T;
+/**
+ * Keys that can be used as sort fields for an API response type.
+ *
+ * For paginated responses this uses the keys of the item inside `data`.
+ */
 type SortableKeys<T> = keyof UnwrapArray<ExtractDataIfPaginated<T>>;
 /**
  * Removes the optional RequestParams argument from the end
@@ -105,10 +147,7 @@ type SortableKeys<T> = keyof UnwrapArray<ExtractDataIfPaginated<T>>;
  *
  * [data: CreateSupplierParams]
  */
-type WithoutRequestParams<T extends readonly unknown[]> = T extends readonly [
-    ...infer Arguments,
-    RequestParams?
-] ? Arguments : T;
+type WithoutRequestParams<T extends readonly unknown[]> = T extends readonly [...infer Arguments, RequestParams?] ? Arguments : T;
 
 /**
  * Extended fetch response returned by the generated HTTP client.
@@ -126,14 +165,35 @@ interface HttpResponse<D extends unknown, E extends unknown = unknown> extends R
  */
 type RuntimeRequestParams = Record<string, unknown>;
 
-type ApiSuccessHandler<TResponse> = (response: TResponse) => void | Promise<void>;
-type ApiErrorHandler<TError = unknown> = (error: TError) => void | Promise<void>;
-type ApiMethodCallbacks<TResponse, TError = unknown> = {
+/**
+ * Function called after a generated wrapper method receives a successful API result.
+ *
+ * The callback receives the success-only branch of `ApiResult<TResponse>`.
+ */
+type ApiSuccessHandler<TResponse> = (result: ApiSuccessResult<TResponse>) => void | Promise<void>;
+/**
+ * Function called after a generated wrapper method receives a failed API result.
+ *
+ * The callback receives the error-only branch of `ApiResult<TResponse>`.
+ */
+type ApiErrorHandler<TResponse> = (result: ApiErrorResult<TResponse>) => void | Promise<void>;
+/**
+ * Optional callback and request-parameter object accepted by generated API wrapper methods.
+ *
+ * `onSuccess` runs for successful responses, `onError` runs for failed responses,
+ * and `params` is forwarded to the generated HTTP client.
+ */
+type ApiMethodCallbacks<TResponse> = {
     onSuccess?: ApiSuccessHandler<TResponse>;
-    onError?: ApiErrorHandler<TError>;
+    onError?: ApiErrorHandler<TResponse>;
     params?: RequestParams;
 };
 
+/**
+ * Sort direction value accepted by generated query objects.
+ *
+ * APIs often expose sort direction as either a string enum or numeric enum, so both are supported.
+ */
 type SortDirection = number | string;
 /**
  * Builds a typed query object from filter form values, pagination, and sorting.
@@ -148,23 +208,53 @@ declare function buildQuery<TQuery, TSortModel = keyof TQuery>(filters: FilterFo
  * Extracts wrapper-only arguments in this order:
  * original API arguments, onSuccess, onError, request params.
  */
-declare function extractArgsCallbacksAndParams<TArgs extends readonly unknown[], TSuccess, TError = unknown>(argsWithCallbacks: [
+declare function extractArgsToastsAndParams<TArgs extends readonly unknown[], TResponse>(argsWithCallbacks: [
+    ...TArgs,
+    ApiSuccessHandler<TResponse>?,
+    ApiErrorHandler<TResponse>?,
+    RuntimeRequestParams?
+]): {
+    args: TArgs;
+    onSuccess?: ApiSuccessHandler<TResponse>;
+    onError?: ApiErrorHandler<TResponse>;
+    params?: RuntimeRequestParams;
+};
+
+/**
+ * Extracts wrapper arguments in this order:
+ *
+ * 1. Original API arguments
+ * 2. Optional success callback
+ * 3. Optional error callback
+ * 4. Optional request params
+ */
+declare function extractArgsCallbacksAndParams<TArgs extends unknown[], TResponse, _TError = unknown>(argsWithCallbacks: [
     ...TArgs,
-    ApiSuccessHandler<TSuccess>?,
-    ApiErrorHandler<TError>?,
+    ApiSuccessHandler<TResponse>?,
+    ApiErrorHandler<TResponse>?,
     RuntimeRequestParams?
 ]): {
     args: TArgs;
-    onSuccess?: ApiSuccessHandler<TSuccess>;
-    onError?: ApiErrorHandler<TError>;
+    onSuccess?: ApiSuccessHandler<TResponse>;
+    onError?: ApiErrorHandler<TResponse>;
     params?: RuntimeRequestParams;
 };
 
-type HandleApiResponseOptions<TResponse, TError = unknown> = {
+/**
+ * Optional callbacks used while converting a generated HTTP response into `ApiResult<TResponse>`.
+ *
+ * `onSuccess` is called with `ApiSuccessResult<TResponse>` and `onError` is called with `ApiErrorResult<TResponse>`.
+ */
+type HandleApiResponseOptions<TResponse> = {
     onSuccess?: ApiSuccessHandler<TResponse>;
-    onError?: ApiErrorHandler<TError>;
+    onError?: ApiErrorHandler<TResponse>;
 };
-declare function handleApiResponse<TResponse, TError = unknown>(call: () => Promise<HttpResponse<TResponse, TError>>, options?: HandleApiResponseOptions<TResponse, TError>): Promise<ApiResult<TResponse>>;
+/**
+ * Executes a generated API request and converts the result into `ApiResult<TResponse>`.
+ *
+ * Successful responses return `{ ok: true, status, response }`. Failed responses and thrown errors return `{ ok: false, status, error }`.
+ */
+declare function handleApiResponse<TResponse, TError>(call: () => Promise<HttpResponse<TResponse, TError>>, options?: HandleApiResponseOptions<TResponse>): Promise<ApiResult<TResponse>>;
 
 /** Values supported by the generated API SortDirection enum. */
 type ApiSortDirection = "Default" | "Ascending" | "Descending";
@@ -195,4 +285,4 @@ declare function getSortDirectionFromSortType(sortType: SortType | null | undefi
  */
 declare function toFormData<T extends object>(payload: T): FormData;
 
-export { type ApiErrorHandler, type ApiMethodCallbacks, type ApiResult, type ApiSortDirection, type ApiSuccessHandler, type ExtractDataIfPaginated, type ExtractResponse, type FilterFormValues, type FilterType, type HandleApiResponseOptions, type HttpResponse, type OptionValue, type RuntimeRequestParams, type SortDirection, type SortType, type SortableKeys, type UnwrapArray, type WithoutRequestParams, buildQuery, extractArgsCallbacksAndParams, getSortDirectionFromSortType, getSortTypeFromSortDirection, handleApiResponse, sortTypes, toFormData };
+export { type ApiErrorHandler, type ApiErrorResult, type ApiMethodCallbacks, type ApiResult, type ApiSortDirection, type ApiSuccessHandler, type ApiSuccessResult, type ExtractDataIfPaginated, type ExtractError, type ExtractResponse, type FilterFormValues, type FilterType, type HandleApiResponseOptions, type HttpResponse, type OptionValue, type RuntimeRequestParams, type SortDirection, type SortType, type SortableKeys, type UnwrapArray, type WithoutRequestParams, buildQuery, extractArgsCallbacksAndParams, extractArgsToastsAndParams, getSortDirectionFromSortType, getSortTypeFromSortDirection, handleApiResponse, sortTypes, toFormData };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,oBAAoB,CAAC"}