@zayne-labs/callapi 1.16.0 → 1.16.3

package/README.md

@@ -7,7 +7,7 @@
 <p align="center">
    <!-- <a href="https://deno.bundlejs.com/badge?q=@zayne-labs/callapi,@zayne-labs/callapi&treeshake=%5B*%5D,%5B%7B+createFetchClient+%7D%5D&config=%7B%22compression%22:%7B%22type%22:%22brotli%22,%22quality%22:11%7D%7D"><img src="https://deno.bundlejs.com/badge?q=@zayne-labs/callapi,@zayne-labs/callapi&treeshake=%5B*%5D,%5B%7B+createFetchClient+%7D%5D&config=%7B%22compression%22:%7B%22type%22:%22brotli%22,%22quality%22:11%7D%7D" alt="bundle size"></a> -->
    <a href="https://www.npmjs.com/package/@zayne-labs/callapi"><img src="https://img.shields.io/npm/v/@zayne-labs/callapi?style=flat&color=EFBA5F" alt="npm version"></a>
-   <a href="https://github.com/zayne-labs/callapi/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@zayne-labs/callapi?style=flat&color=EFBA5F" alt="license"></a>
+   <a href="https://github.com/zayne-labs/callapi/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@zayne-labs/callapi?style=flat&color=EFBA5F" alt="license"></a>
    <a href="https://www.npmjs.com/package/@zayne-labs/callapi"><img src="https://img.shields.io/npm/dm/@zayne-labs/callapi?style=flat&color=EFBA5F" alt="downloads per month"></a>
    <a href="https://github.com/zayne-labs/callapi/graphs/commit-activity"><img src="https://img.shields.io/github/commit-activity/m/zayne-labs/callapi?style=flat&color=EFBA5F" alt="commit activity"></a>
    <a href="https://deepwiki.com/zayne-labs/callapi"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
@@ -29,7 +29,7 @@
 
 Fetch is too basic for real apps. You end up writing the same boilerplate: error handling, retries, deduplication, response parsing etc. CallApi handles all of that and practically more.
 
-**Drop-in replacement for fetch. Under 6KB. All kinds of convenience features. Zero dependencies.**
+**Fetch-style API. ~7KB. All kinds of convenience features. Zero dependencies.**
 
 ```js
 import { callApi } from "@zayne-labs/callapi";
@@ -45,7 +45,7 @@ User spam-clicks a button? Handled. No race conditions.
 
 ```js
 const req1 = callApi("/api/user");
-const req2 = callApi("/api/user"); // Cancels req1 (can be configured to share it's response instead)
+const req2 = callApi("/api/user"); // Cancels req1 (can be configured to share its response instead)
 ```
 
 ### Smart Response Parsing
@@ -58,17 +58,24 @@ const { data } = await callApi("/api/data"); // JSON? Parsed.
 
 ### Error Handling
 
-Structured errors make robust error handling trivial.
+Errors are returned, not thrown, so every failure is handled in one place.
 
 ```js
+import { isHTTPError, isValidationError } from "@zayne-labs/callapi/utils";
+
 const { data, error } = await callApi("/api/users");
 
-if (error) {
-	console.log(error.name); // "HTTPError", "ValidationError"
-	console.log(error.errorData); // Actual API response
+if (isHTTPError(error)) {
+	console.log(error.errorData); // The API's error response body
+}
+
+if (isValidationError(error)) {
+	console.log(error.errorData); // The schema validation issues
 }
 ```
 
+Prefer try/catch? Set `throwOnError: true`.
+
 ### Retries
 
 Supports exponential backoff and custom retry conditions.
@@ -102,9 +109,13 @@ const callMainApi = createFetchClient({
 });
 
 // Fully typed + validated
-const user = await callMainApi("/users/:id", {
+const { data: user, error } = await callMainApi("/users/:id", {
 	params: { id: 123 },
 });
+
+if (!error) {
+	user.name; // string
+}
 ```
 
 ### Hooks
@@ -129,21 +140,27 @@ const api = createFetchClient({
 
 Extend functionality with setup, hooks, and middleware.
 
-```js
-const metricsPlugin = definePlugin({
+```ts
+import { createFetchClient, type GetCallApiContext } from "@zayne-labs/callapi";
+import { definePluginWithContext } from "@zayne-labs/callapi/utils";
+
+// Types the metadata this plugin reads and writes
+type MetricsContext = GetCallApiContext<{ Meta: { startTime?: number } }>;
+
+const metricsPlugin = definePluginWithContext<MetricsContext>()({
 	id: "metrics",
 	name: "Metrics Plugin",
 
 	setup: ({ options }) => ({
 		options: {
 			...options,
-			meta: { startTime: Date.now() },
+			meta: { ...options.meta, startTime: Date.now() },
 		},
 	}),
 
 	hooks: {
 		onSuccess: ({ options }) => {
-			const duration = Date.now() - options.meta.startTime;
+			const duration = Date.now() - (options.meta?.startTime ?? Date.now());
 
 			console.info(`Request took ${duration}ms`);
 		},
@@ -213,10 +230,12 @@ const api = createFetchClient({
 
 - **TypeScript-first** - Full inference everywhere
 - **Familiar API** - If you know fetch, you know CallApi
-- **Actually small** - Zero dependencies and Under 6KB, unlike other 50kb libs in the wild
+- **Actually small** - Zero dependencies and ~7KB (minified + brotli)
 - **Fast** - Built on native Web APIs
 - **Works everywhere** - Browsers, Node 18+, Deno, Bun, Cloudflare Workers
 
+Coming from axios, ky or ofetch? See [how CallApi compares](https://zayne-labs-callapi.vercel.app/docs/comparisons).
+
 ## License
 
 MIT © [Ryan Zayne](https://github.com/ryan-zayne)

package/dist/{callapi-context-NF0HXJwF.d.ts → callapi-context-Gh3YMTYJ.d.ts}

@@ -172,7 +172,7 @@ type DedupeOptions = {
    *
    * // URL and method only - ignore headers and body
    * const userData = callApi("/api/user/123", {
-   *   dedupeKey: (context) => `${context.options.method}:${context.options.fullURL}`
+   *   dedupeKey: (context) => `${context.request.method}:${context.options.fullURL}`
    * });
    *
    * // Include specific headers in deduplication
@@ -226,7 +226,7 @@ type DedupeOptions = {
    * // Dynamic strategy based on request
    * const smartClient = createFetchClient({
    *   dedupeStrategy: (context) => {
-   *     return context.options.method === "GET" ? "defer" : "cancel";
+   *     return context.request.method === "GET" ? "defer" : "cancel";
    *   }
    * });
    *
@@ -697,8 +697,6 @@ type SharedExtraOptions<TCallApiContext extends CallApiContext = DefaultCallApiC
    * Supports multiple authentication patterns:
    * - String: Direct authorization header value
    * - Auth object: Structured authentication configuration
-   *
-   * ```
    */
   auth?: AuthOption;
   /**
@@ -797,7 +795,10 @@ type SharedExtraOptions<TCallApiContext extends CallApiContext = DefaultCallApiC
    */
   customFetchImpl?: FetchImpl;
   /**
-   * Enable debug mode for the request.
+   * Log development warnings to the console.
+   *
+   * Currently warns when the resolved URL is relative, which fails during server-side rendering
+   * unless an absolute `baseURL` is set.
    *
    * @default true
    */
@@ -808,7 +809,7 @@ type SharedExtraOptions<TCallApiContext extends CallApiContext = DefaultCallApiC
    * Can be a static string or a function that receives error context
    * to generate dynamic error messages based on the response.
    *
-   * @default "Failed to fetch data from server!"
+   * @default "Request failed unexpectedly"
    *
    * @example
    * ```ts
@@ -1043,7 +1044,7 @@ type BaseCallApiExtraOptions<TBaseCallApiContext extends CallApiContext = Defaul
    * @example
    * ```ts
    * // Skip all automatic merging - full manual control
-   * const client = callApi.create((ctx) => ({
+   * const client = createFetchClient((ctx) => ({
    *   skipAutoMergeFor: "all",
    *
    *   // Manually decide what to merge
@@ -1056,7 +1057,7 @@ type BaseCallApiExtraOptions<TBaseCallApiContext extends CallApiContext = Defaul
    * }));
    *
    * // Skip options merging - manual plugin/hook control
-   * const client = callApi.create((ctx) => ({
+   * const client = createFetchClient((ctx) => ({
    *   skipAutoMergeFor: "options",
    *
    *   // Manually control which plugins to use
@@ -1070,7 +1071,7 @@ type BaseCallApiExtraOptions<TBaseCallApiContext extends CallApiContext = Defaul
    * }));
    *
    * // Skip request merging - manual request control
-   * const client = callApi.create((ctx) => ({
+   * const client = createFetchClient((ctx) => ({
    *   skipAutoMergeFor: "request",
    *
    *   // Extra options still auto-merge (plugins, hooks, etc.)
@@ -1113,10 +1114,13 @@ type CallApiExtraOptions<TCallApiContext extends CallApiContext = DefaultCallApi
   /**
    * Array of instance-specific CallApi plugins or a function to configure plugins.
    *
-   * Instance plugins are added to the base plugins and provide functionality
-   * specific to this particular API instance. Can be a static array or a function
-   * that receives base plugins and returns the instance plugins.
+   * A static array replaces the base plugins for this request. To keep them, pass a function
+   * that receives the base plugins and returns the full list.
    *
+   * @example
+   * ```ts
+   * plugins: ({ basePlugins }) => [...basePlugins, metricsPlugin]
+   * ```
    */
   plugins?: TPluginArray | ((context: InferExtendPluginContext<TBasePluginArray>) => TPluginArray);
   /**
@@ -1239,37 +1243,31 @@ type InferMetaOption<TSchema extends CallApiSchema, TCallApiContext extends Call
    *
    * @example
    * ```ts
-   * const callMainApi = callApi.create({
+   * const callMainApi = createFetchClient({
    * 	baseURL: "https://main-api.com",
-   * 	onResponseError: ({ response, options }) => {
+   * 	onResponseError: ({ options }) => {
    * 		if (options.meta?.userId) {
    * 			console.error(`User ${options.meta.userId} made an error`);
    * 		}
    * 	},
    * });
    *
-   * const response = await callMainApi({
-   * 	url: "https://example.com/api/data",
+   * await callMainApi("/api/data", {
    * 	meta: { userId: "123" },
    * });
    *
    * // Use case: Request tracking
-   * const result = await callMainApi({
-   *   url: "https://example.com/api/data",
-   *   meta: {
-   *     requestId: generateId(),
-   *     source: "user-dashboard",
-   *     priority: "high"
-   *   }
+   * await callMainApi("/api/data", {
+   * 	meta: {
+   * 		requestId: generateId(),
+   * 		source: "user-dashboard",
+   * 	},
    * });
    *
-   * // Use case: Feature flags
-   * const client = callApi.create({
-   *   baseURL: "https://api.example.com",
-   *   meta: {
-   *     features: ["newUI", "betaFeature"],
-   *     experiment: "variantA"
-   *   }
+   * // Use case: Default metadata for every request from a client
+   * const client = createFetchClient({
+   * 	baseURL: "https://api.example.com",
+   * 	meta: { experiment: "variantA" },
    * });
    * ```
    */
@@ -1535,11 +1533,6 @@ interface RetryOptions<TErrorData> {
    * @deprecated **WARNING**: This property is used internally to track retries. Please abstain from reading or modifying it.
    */
   readonly ["~retryAttemptCount"]?: number;
-  /**
-   * Use a valid `Retry-After` response header instead of the configured retry delay
-   * @default false
-   */
-  respectRetryAfter?: boolean;
   /**
    * Number of allowed retry attempts on HTTP errors
    * @default 0
@@ -1587,16 +1580,31 @@ type RetryManagerContext = {
 };
 //#endregion
 //#region src/refetch.d.ts
-declare const refetchAttemptTrackerSymbol: unique symbol;
 interface RefetchOptions {
   /**
-   * Tracks if the refetching of the request should be attempted
+   * Tracks the number of times the request has already been refetched internally
    * @internal
-   * @deprecated **WARNING**: This property is used internally to track retries. Please abstain from reading or modifying it.
+   * @deprecated **WARNING**: This property is used internally to track refetches. Please abstain from reading or modifying it.
+   */
+  readonly ["~refetchAttemptCount"]?: number;
+  /**
+   * Maximum number of times `refetch()` can re-run the original request.
+   *
+   * Guards against infinite loops, e.g. when a token refresh keeps failing with `401`.
+   * Once the limit is reached, `refetch()` does nothing.
+   * Can be overridden for a single call with `refetch({ maxAttempts })`.
+   *
+   * @default 1
    */
-  [refetchAttemptTrackerSymbol]?: boolean;
+  refetchAttempts?: number;
 }
-type RefetchFn = () => void;
+type RefetchFnOptions = {
+  /**
+   * Overrides the `refetchAttempts` option for this `refetch()` call.
+   */
+  maxAttempts?: number;
+};
+type RefetchFn = (refetchOptions?: RefetchFnOptions) => void;
 type RefetchManagerResult = {
   handleRefetch: () => Promise<CallApiResultLoose<unknown, unknown>> | null;
   refetch: RefetchFn;
@@ -1917,4 +1925,4 @@ type InferMetaFromTag<TTaggedType, TFallback = never> = TTaggedType extends Cont
 type InferExtraOptionsFromTag<TTaggedType> = TTaggedType extends ContextTag<unknown, infer TCallApiContext extends CallApiContext> ? unknown extends TCallApiContext["InferredExtraOptions"] ? never : TCallApiContext["InferredExtraOptions"] : never;
 //#endregion
 export { PossibleValidationError as $, DefaultCallApiContext as $t, isHTTPErrorInstance as A, ValidationError as At, defineSchema as B, FallBackRouteSchemaKey as Bt, SuccessContext as C, CallApiResult as Ct, metaHelper as D, InstanceContext as Dt, extraOptionsHelper as E, GetBaseSchemaRoutes as Et, defineFallbackRouteSchema as F, CallApiSchema as Ft, toSearchParams as G, DedupeOptions as Gt, defineSchemaRoutes as H, FetchImpl as Ht, defineInstanceConfig as I, CallApiSchemaConfig as It, CallApiResultSuccessVariant as J, CommonRequestHeaders as Jt, CallApiResultErrorVariant as K, AnyString as Kt, defineMainSchema as L, InferSchemaInput as Lt, isValidationError as M, BaseCallApiSchemaAndConfig as Mt, isValidationErrorInstance as N, BaseCallApiSchemaRoutes as Nt, objectifyHeaders as O, Register as Ot, defineBaseConfig as P, BaseSchemaRouteKeyPrefixes as Pt, PossibleJavaScriptError as Q, Writeable as Qt, definePlugin as R, InferSchemaOutput as Rt, ResponseStreamContext as S, CallApiRequestOptions as St, RetryOptions as T, GetBaseSchemaConfig as Tt, toFormData as U, FetchMiddlewareContext as Ut, defineSchemaConfig as V, fallBackRouteSchemaKey as Vt, toQueryString as W, Middlewares as Wt, InferCallApiResult as X, NoInferUnMasked as Xt, GetResponseType as Y, DistributiveOmit as Yt, PossibleHTTPError as Z, UnionToIntersection as Zt, HooksOrHooksArray as _, BaseCallApiConfig as _t, GetCallApiContextRequired as a, Body as at, ResponseContext as b, CallApiExtraOptions as bt, MetaWithContextTag as c, HeadersOption as ct, PluginMiddlewares as d, InferInitURL as dt, DefaultMetaObject as en, ResponseTypeMap as et, PluginSetupContext as f, InferParamsFromRoute as ft, Hooks as g, AuthOption as gt, ErrorContext as h, ThrowOnErrorBoolean as ht, GetCallApiContext as i, ApplyURLBasedConfig as it, isJavascriptError as j, URLOptions as jt, isHTTPError as k, HTTPError as kt, CallApiPlugin as l, InferAllMainRouteKeys as lt, CallApiRequestOptionsForHooks as m, SerializableObject as mt, ContextTag as n, fetchSpecificKeys as nn, ResultModeType as nt, InferExtraOptionsFromTag as o, GetCurrentRouteSchema as ot, CallApiExtraOptionsForHooks as p, SerializableArray as pt, CallApiResultSuccessOrErrorVariant as q, CommonContentTypes as qt, ExtraOptionsWithContextTag as r, ApplyStrictConfig as rt, InferMetaFromTag as s, GetCurrentRouteSchemaKey as st, CallApiContext as t, DefaultPluginArray as tn, ResponseTypeType as tt, PluginHooks as u, InferAllMainRoutes as ut, RequestContext as v, BaseCallApiExtraOptions as vt, RefetchOptions as w, CallApiResultLoose as wt, ResponseErrorContext as x, CallApiParameters as xt, RequestStreamContext as y, CallApiConfig as yt, definePluginWithContext as z, InferSchemaResult as zt };
-//# sourceMappingURL=callapi-context-NF0HXJwF.d.ts.map
+//# sourceMappingURL=callapi-context-Gh3YMTYJ.d.ts.map

package/dist/constants/index.d.ts

@@ -1,4 +1,4 @@
-import { Bt as FallBackRouteSchemaKey, Vt as fallBackRouteSchemaKey, nn as fetchSpecificKeys, v as RequestContext } from "../callapi-context-NF0HXJwF.js";
+import { Bt as FallBackRouteSchemaKey, Vt as fallBackRouteSchemaKey, nn as fetchSpecificKeys, v as RequestContext } from "../callapi-context-Gh3YMTYJ.js";
 //#region src/constants/defaults.d.ts
 export declare const extraOptionDefaults: Readonly<Readonly<{
   bodySerializer: {
@@ -12,7 +12,7 @@ export declare const extraOptionDefaults: Readonly<Readonly<{
   dedupeStrategy: "cancel";
   defaultHTTPErrorMessage: "Request failed unexpectedly";
   hooksExecutionMode: "parallel";
-  respectRetryAfter: false;
+  refetchAttempts: 1;
   responseParser: (text: string, reviver?: (this: any, key: string, value: any) => any) => any;
   responseType: "json";
   resultMode: "all";

package/dist/constants/index.js

@@ -1,2 +1,2 @@
-import { U as fetchSpecificKeys, n as requestOptionDefaults, t as extraOptionDefaults, z as fallBackRouteSchemaKey } from "../constants-KCmRZnc7.js";
+import { U as fetchSpecificKeys, n as requestOptionDefaults, t as extraOptionDefaults, z as fallBackRouteSchemaKey } from "../constants-PKigNOpK.js";
 export { extraOptionDefaults, fallBackRouteSchemaKey, fetchSpecificKeys, requestOptionDefaults };

package/dist/{constants-KCmRZnc7.js → constants-PKigNOpK.js}

@@ -713,7 +713,7 @@ const extraOptionDefaults = Object.freeze(defineEnum({
 	dedupeStrategy: "cancel",
 	defaultHTTPErrorMessage: "Request failed unexpectedly",
 	hooksExecutionMode: "parallel",
-	respectRetryAfter: false,
+	refetchAttempts: 1,
 	responseParser: JSON.parse,
 	responseType: "json",
 	resultMode: "all",
@@ -729,4 +729,4 @@ const requestOptionDefaults = Object.freeze(defineEnum({ method: "GET" }));
 //#endregion
 export { defineSchemaRoutes as A, isArray as B, defineFallbackRouteSchema as C, definePluginWithContext as D, definePlugin as E, handleConfigValidation as F, isString as H, handleSchemaValidation as I, HTTPError as L, toQueryString as M, toSearchParams as N, defineSchema as O, getCurrentRouteSchemaKeyAndMainInitURL as P, ValidationError as R, defineBaseConfig as S, defineMainSchema as T, fetchSpecificKeys as U, isFunction as V, isHTTPError as _, getBody as a, isValidationError as b, getMethod as c, splitConfig as d, waitFor as f, objectifyHeaders as g, metaHelper as h, createTimeoutSignal as i, toFormData as j, defineSchemaConfig as k, getResolvedHeaders as l, extraOptionsHelper as m, requestOptionDefaults as n, getFetchImpl as o, getFullAndNormalizedURL as p, createCombinedSignal as r, getHeaders as s, extraOptionDefaults as t, omitKeys as u, isHTTPErrorInstance as v, defineInstanceConfig as w, isValidationErrorInstance as x, isJavascriptError as y, fallBackRouteSchemaKey as z };
 
-//# sourceMappingURL=constants-KCmRZnc7.js.map
+//# sourceMappingURL=constants-PKigNOpK.js.map