@zayne-labs/callapi 1.6.24 → 1.7.0

package/README.md

@@ -1,8 +1,19 @@
-# CallApi
-
-[![Build Size](https://img.shields.io/bundlephobia/minzip/@zayne-labs/callapi?label=bundle%20size&style=flat&colorA=000000&colorB=000000)](https://bundlephobia.com/result?p=@zayne-labs/callapi)[![Version](https://img.shields.io/npm/v/@zayne-labs/callapi?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@zayne-labs/callapi)
-
-CallApi Fetch is an extra-lightweight wrapper over fetch that provides quality of life improvements beyond the bare fetch api, while keeping the API familiar.
+<h1 align="center">CallApi - Advanced Fetch Client</h1>
+
+<p align="center">
+   <img src="../../apps/docs/public/logo.png" alt="CallApi Logo" width="50%">
+</p>
+
+<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/call-api/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/call-api/graphs/commit-activity"><img src="https://img.shields.io/github/commit-activity/m/zayne-labs/call-api?style=flat&color=EFBA5F" alt="commit activity"></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>
+</p>
+
+<p align="center">
+CallApi Fetch is an extra-lightweight wrapper over fetch that provides quality of life improvements beyond the bare fetch api, while keeping the API familiar.</p>
 
 It takes in a url and a request options object, just like fetch, but with some additional options to make your life easier. Check out the [API Reference](https://zayne-labs-callapi.netlify.app/docs/latest/all-options) for a quick look at each option.
 

package/dist/cjs/{error-DIHsfUiJ.d.cts → error-C7M77J6L.d.cts}

@@ -1,5 +1,41 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
+type StreamProgressEvent = {
+    /**
+     * Current chunk of data being streamed
+     */
+    chunk: Uint8Array;
+    /**
+     * Progress in percentage
+     */
+    progress: number;
+    /**
+     * Total size of data in bytes
+     */
+    totalBytes: number;
+    /**
+     * Amount of data transferred so far
+     */
+    transferredBytes: number;
+};
+type RequestStreamContext = {
+    event: StreamProgressEvent;
+    options: CombinedCallApiExtraOptions;
+    request: CallApiRequestOptionsForHooks;
+    requestInstance: Request;
+};
+type ResponseStreamContext = {
+    event: StreamProgressEvent;
+    options: CombinedCallApiExtraOptions;
+    request: CallApiRequestOptionsForHooks;
+    response: Response;
+};
+declare global {
+    interface ReadableStream<R> {
+        [Symbol.asyncIterator]: () => AsyncIterableIterator<R>;
+    }
+}
+
 type ValueOrFunctionResult<TValue> = TValue | (() => TValue);
 /**
  * Bearer Or Token authentication
@@ -243,7 +279,10 @@ interface CallApiPlugin<TData = never, TErrorData = never> {
 declare const definePlugin: <TPlugin extends CallApiPlugin | AnyFunction<CallApiPlugin>>(plugin: TPlugin) => TPlugin;
 type Plugins<TPluginArray extends CallApiPlugin[]> = TPluginArray;
 
-declare const fetchSpecificKeys: ("body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window")[];
+type ModifiedRequestInit = RequestInit & {
+    duplex?: "full" | "half" | "none";
+};
+declare const fetchSpecificKeys: ("body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "duplex")[];
 declare const getDefaultOptions: () => {
     baseURL: string;
     bodySerializer: {
@@ -335,7 +374,7 @@ type ResultModeOption<TErrorData, TResultMode extends ResultModeUnion> = TErrorD
 };
 
 type FetchSpecificKeysUnion = Exclude<(typeof fetchSpecificKeys)[number], "body" | "headers" | "method">;
-type CallApiRequestOptions<TSchemas extends CallApiSchemas = DefaultMoreOptions> = BodyOption<TSchemas> & HeadersOption<TSchemas> & MethodOption<TSchemas> & Pick<RequestInit, FetchSpecificKeysUnion>;
+type CallApiRequestOptions<TSchemas extends CallApiSchemas = DefaultMoreOptions> = BodyOption<TSchemas> & HeadersOption<TSchemas> & MethodOption<TSchemas> & Pick<ModifiedRequestInit, FetchSpecificKeysUnion>;
 type CallApiRequestOptionsForHooks<TSchemas extends CallApiSchemas = DefaultMoreOptions> = Omit<CallApiRequestOptions<TSchemas>, "headers"> & {
     headers?: Record<string, string | undefined>;
 };
@@ -356,6 +395,10 @@ interface Interceptors<TData = DefaultDataType, TErrorData = DefaultDataType, TM
      *  Interceptor that will be called when an error occurs during the fetch request.
      */
     onRequestError?: (context: RequestErrorContext & WithMoreOptions<TMoreOptions>) => Awaitable<unknown>;
+    /**
+     * Interceptor that will be called when upload stream progress is tracked
+     */
+    onRequestStream?: (context: RequestStreamContext & WithMoreOptions<TMoreOptions>) => Awaitable<unknown>;
     /**
      * Interceptor that will be called when any response is received from the api, whether successful or not
      */
@@ -364,6 +407,10 @@ interface Interceptors<TData = DefaultDataType, TErrorData = DefaultDataType, TM
      *  Interceptor that will be called when an error response is received from the api.
      */
     onResponseError?: (context: ResponseErrorContext<TErrorData> & WithMoreOptions<TMoreOptions>) => Awaitable<unknown>;
+    /**
+     * Interceptor that will be called when download stream progress is tracked
+     */
+    onResponseStream?: (context: ResponseStreamContext & WithMoreOptions<TMoreOptions>) => Awaitable<unknown>;
     /**
      * Interceptor that will be called when a request is retried.
      */
@@ -418,6 +465,14 @@ type ExtraOptions<TData = DefaultDataType, TErrorData = DefaultDataType, TResult
      * @default "Failed to fetch data from server!"
      */
     defaultErrorMessage?: string;
+    /**
+     * If true, forces the calculation of the total byte size from the request or response body, in case the content-length header is not present or is incorrect.
+     * @default false
+     */
+    forceStreamSizeCalc?: boolean | {
+        request?: boolean;
+        response?: boolean;
+    };
     /**
      * Resolved request URL
      */
@@ -481,7 +536,7 @@ type CallApiExtraOptions<TData = DefaultDataType, TErrorData = DefaultDataType,
 };
 declare const optionsEnumToOmitFromBase: ("dedupeKey" | "extend")[];
 type BaseCallApiExtraOptions<TBaseData = DefaultDataType, TBaseErrorData = DefaultDataType, TBaseResultMode extends ResultModeUnion = ResultModeUnion, TBaseThrowOnError extends boolean = DefaultThrowOnError, TBaseResponseType extends ResponseTypeUnion = ResponseTypeUnion, TBasePluginArray extends CallApiPlugin[] = DefaultPluginArray, TBaseSchemas extends CallApiSchemas = DefaultMoreOptions> = Omit<Partial<CallApiExtraOptions<TBaseData, TBaseErrorData, TBaseResultMode, TBaseThrowOnError, TBaseResponseType, TBasePluginArray, TBaseSchemas>>, (typeof optionsEnumToOmitFromBase)[number]>;
-type CombinedCallApiExtraOptions = BaseCallApiExtraOptions & CallApiExtraOptions;
+type CombinedCallApiExtraOptions = Interceptors & Omit<BaseCallApiExtraOptions & CallApiExtraOptions, keyof Interceptors>;
 type BaseCallApiConfig<TBaseData = DefaultDataType, TBaseErrorData = DefaultDataType, TBaseResultMode extends ResultModeUnion = ResultModeUnion, TBaseThrowOnError extends boolean = DefaultThrowOnError, TBaseResponseType extends ResponseTypeUnion = ResponseTypeUnion, TBasePluginArray extends CallApiPlugin[] = DefaultPluginArray, TBaseSchemas extends CallApiSchemas = DefaultMoreOptions> = (CallApiRequestOptions<TBaseSchemas> & BaseCallApiExtraOptions<TBaseData, TBaseErrorData, TBaseResultMode, TBaseThrowOnError, TBaseResponseType, TBasePluginArray, TBaseSchemas>) | ((context: {
     initURL: string;
     options: CallApiExtraOptions;
@@ -569,7 +624,7 @@ type ResultModeMap<TData = DefaultDataType, TErrorData = DefaultDataType, TRespo
     allWithoutResponse: CallApiResultSuccessVariant<TComputedData>["data" | "error"] | CallApiResultErrorVariant<TComputedErrorData>["data" | "error"];
     onlyError: CallApiResultSuccessVariant<TComputedData>["error"] | CallApiResultErrorVariant<TComputedErrorData>["error"];
     onlyResponse: CallApiResultErrorVariant<TComputedErrorData>["response"] | CallApiResultSuccessVariant<TComputedData>["response"];
-    onlyResponseWithException: CallApiResultSuccessVariant<TComputedErrorData>["response"];
+    onlyResponseWithException: CallApiResultSuccessVariant<TComputedData>["response"];
     onlySuccess: CallApiResultErrorVariant<TComputedErrorData>["data"] | CallApiResultSuccessVariant<TComputedData>["data"];
     onlySuccessWithException: CallApiResultSuccessVariant<TComputedData>["data"];
 }>;

package/dist/cjs/index.cjs

@@ -89,7 +89,7 @@ var HTTPError = class extends Error {
   }
 };
 
-// src/utils/type-guards.ts
+// src/utils/guards.ts
 var isHTTPErrorInstance = (error) => {
   return (
     // prettier-ignore
@@ -97,6 +97,7 @@ var isHTTPErrorInstance = (error) => {
   );
 };
 var isArray = (value) => Array.isArray(value);
+var isObject = (value) => typeof value === "object" && value !== null;
 var hasObjectPrototype = (value) => {
   return Object.prototype.toString.call(value) === "[object Object]";
 };
@@ -137,6 +138,9 @@ var isSerializable = (value) => {
 var isFunction = (value) => typeof value === "function";
 var isQueryString = (value) => isString(value) && value.includes("=");
 var isString = (value) => typeof value === "string";
+var isReadableStream = (value) => {
+  return value instanceof ReadableStream;
+};
 
 // src/auth.ts
 var getValue = (value) => {
@@ -186,6 +190,7 @@ var optionsEnumToOmitFromBase = defineEnum(["extend", "dedupeKey"]);
 var fetchSpecificKeys = defineEnum([
   "body",
   "integrity",
+  "duplex",
   "method",
   "headers",
   "signal",
@@ -328,6 +333,108 @@ var waitUntil = (delay) => {
   return promise;
 };
 
+// src/stream.ts
+var createProgressEvent = (options) => {
+  const { chunk, totalBytes, transferredBytes } = options;
+  return {
+    chunk,
+    progress: Math.round(transferredBytes / totalBytes * 100) || 0,
+    totalBytes,
+    transferredBytes
+  };
+};
+var calculateTotalBytesFromBody = async (requestBody, existingTotalBytes) => {
+  let totalBytes = existingTotalBytes;
+  if (!requestBody) {
+    return totalBytes;
+  }
+  for await (const chunk of requestBody) {
+    totalBytes += chunk.byteLength;
+  }
+  return totalBytes;
+};
+var toStreamableRequest = async (context) => {
+  const { options, request, requestInstance } = context;
+  if (!options.onRequestStream || !requestInstance.body) return;
+  const contentLength = requestInstance.headers.get("content-length") ?? new Headers(request.headers).get("content-length") ?? request.body?.size;
+  let totalBytes = Number(contentLength ?? 0);
+  const shouldForceContentLengthCalc = isObject(options.forceStreamSizeCalc) ? options.forceStreamSizeCalc.request : options.forceStreamSizeCalc;
+  if (!contentLength && shouldForceContentLengthCalc) {
+    totalBytes = await calculateTotalBytesFromBody(requestInstance.clone().body, totalBytes);
+  }
+  let transferredBytes = 0;
+  await executeHooks(
+    options.onRequestStream({
+      event: createProgressEvent({ chunk: new Uint8Array(), totalBytes, transferredBytes }),
+      options,
+      request,
+      requestInstance
+    })
+  );
+  const body = requestInstance.body;
+  void new ReadableStream({
+    start: async (controller) => {
+      if (!body) return;
+      for await (const chunk of body) {
+        transferredBytes += chunk.byteLength;
+        totalBytes = Math.max(totalBytes, transferredBytes);
+        await executeHooks(
+          options.onRequestStream?.({
+            event: createProgressEvent({ chunk, totalBytes, transferredBytes }),
+            options,
+            request,
+            requestInstance
+          })
+        );
+        controller.enqueue(chunk);
+      }
+      controller.close();
+    }
+  });
+};
+var toStreamableResponse = async (context) => {
+  const { options, request, response } = context;
+  if (!options.onResponseStream || !response.body) {
+    return response;
+  }
+  const contentLength = response.headers.get("content-length");
+  let totalBytes = Number(contentLength ?? 0);
+  const shouldForceContentLengthCalc = isObject(options.forceStreamSizeCalc) ? options.forceStreamSizeCalc.response : options.forceStreamSizeCalc;
+  if (!contentLength && shouldForceContentLengthCalc) {
+    totalBytes = await calculateTotalBytesFromBody(response.clone().body, totalBytes);
+  }
+  let transferredBytes = 0;
+  await executeHooks(
+    options.onResponseStream({
+      event: createProgressEvent({ chunk: new Uint8Array(), totalBytes, transferredBytes }),
+      options,
+      request,
+      response
+    })
+  );
+  const body = response.body;
+  const stream = new ReadableStream({
+    start: async (controller) => {
+      if (!body) return;
+      for await (const chunk of body) {
+        transferredBytes += chunk.byteLength;
+        totalBytes = Math.max(totalBytes, transferredBytes);
+        await executeHooks(
+          options.onResponseStream?.({
+            event: createProgressEvent({ chunk, totalBytes, transferredBytes }),
+            options,
+            request,
+            response
+          })
+        );
+        controller.enqueue(chunk);
+      }
+      controller.close();
+    }
+  });
+  return new Response(stream, response);
+};
+
 // src/dedupe.ts
 var createDedupeStrategy = async (context) => {
   const { $RequestInfoCache, newFetchController, options, request } = context;
@@ -352,12 +459,29 @@ var createDedupeStrategy = async (context) => {
     prevRequestInfo.controller.abort(reason);
     return Promise.resolve();
   };
-  const handleRequestDeferStrategy = () => {
+  const handleRequestDeferStrategy = async () => {
     const fetchApi = getFetchImpl(options.customFetchImpl);
     const shouldUsePromiseFromCache = prevRequestInfo && options.dedupeStrategy === "defer";
-    const responsePromise = shouldUsePromiseFromCache ? prevRequestInfo.responsePromise : fetchApi(options.fullURL, request);
+    const requestInstance = new Request(
+      options.fullURL,
+      isReadableStream(request.body) && !request.duplex ? { ...request, duplex: "half" } : request
+    );
+    void toStreamableRequest({
+      options,
+      request,
+      requestInstance: requestInstance.clone()
+    });
+    const responsePromise = shouldUsePromiseFromCache ? prevRequestInfo.responsePromise : (
+      // eslint-disable-next-line unicorn/no-nested-ternary -- Allow
+      isReadableStream(request.body) ? fetchApi(requestInstance.clone()) : fetchApi(options.fullURL, request)
+    );
     $RequestInfoCacheOrNull?.set(dedupeKey, { controller: newFetchController, responsePromise });
-    return responsePromise;
+    const streamableResponse = toStreamableResponse({
+      options,
+      request,
+      response: await responsePromise
+    });
+    return streamableResponse;
   };
   const removeDedupeKeyFromCache = () => $RequestInfoCacheOrNull?.delete(dedupeKey);
   return {
@@ -372,7 +496,8 @@ var definePlugin = (plugin) => {
   return plugin;
 };
 var createMergedHook = (hooks, mergedHooksExecutionMode) => {
-  return async (ctx) => {
+  if (hooks.length === 0) return;
+  const mergedHook = async (ctx) => {
     if (mergedHooksExecutionMode === "sequential") {
       for (const hook of hooks) {
         await hook?.(ctx);
@@ -384,13 +509,16 @@ var createMergedHook = (hooks, mergedHooksExecutionMode) => {
       await Promise.all(hookArray.map((uniqueHook) => uniqueHook?.(ctx)));
     }
   };
+  return mergedHook;
 };
 var hooksEnum = {
   onError: /* @__PURE__ */ new Set(),
   onRequest: /* @__PURE__ */ new Set(),
   onRequestError: /* @__PURE__ */ new Set(),
+  onRequestStream: /* @__PURE__ */ new Set(),
   onResponse: /* @__PURE__ */ new Set(),
   onResponseError: /* @__PURE__ */ new Set(),
+  onResponseStream: /* @__PURE__ */ new Set(),
   onRetry: /* @__PURE__ */ new Set(),
   onSuccess: /* @__PURE__ */ new Set()
 };
@@ -455,7 +583,7 @@ var initializePlugins = async (context) => {
   }
   const resolvedHooks = {};
   for (const [key, hookRegistry] of Object.entries(hookRegistries)) {
-    const flattenedHookArray = [...hookRegistry].flat();
+    const flattenedHookArray = [...hookRegistry].flat().filter(Boolean);
     const mergedHook = createMergedHook(flattenedHookArray, options.mergedHooksExecutionMode);
     resolvedHooks[key] = mergedHook;
   }
@@ -517,45 +645,45 @@ var getExponentialDelay = (currentAttemptCount, options) => {
   return Math.min(exponentialDelay, maxDelay);
 };
 var createRetryStrategy = (ctx) => {
-  const currentRetryCount = ctx.options["~retryCount"] ?? 0;
+  const { options } = ctx;
+  const currentRetryCount = options["~retryCount"] ?? 0;
   const getDelay = () => {
-    if (ctx.options.retryStrategy === "exponential") {
-      return getExponentialDelay(currentRetryCount, ctx.options);
+    if (options.retryStrategy === "exponential") {
+      return getExponentialDelay(currentRetryCount, options);
     }
-    return getLinearDelay(ctx.options);
+    return getLinearDelay(options);
   };
   const shouldAttemptRetry = async () => {
-    const customRetryCondition = await ctx.options.retryCondition?.(ctx) ?? true;
-    const maxRetryAttempts = ctx.options.retryAttempts ?? 0;
+    const customRetryCondition = await options.retryCondition?.(ctx) ?? true;
+    const maxRetryAttempts = options.retryAttempts ?? 0;
     const baseRetryCondition = maxRetryAttempts > currentRetryCount && customRetryCondition;
     if (ctx.error.name !== "HTTPError") {
       return baseRetryCondition;
     }
     const includesMethod = (
       // eslint-disable-next-line no-implicit-coercion -- Boolean doesn't narrow
-      !!ctx.request.method && ctx.options.retryMethods?.includes(ctx.request.method)
+      !!ctx.request.method && options.retryMethods?.includes(ctx.request.method)
     );
     const includesCodes = (
       // eslint-disable-next-line no-implicit-coercion -- Boolean doesn't narrow
-      !!ctx.response?.status && ctx.options.retryStatusCodes?.includes(ctx.response.status)
+      !!ctx.response?.status && options.retryStatusCodes?.includes(ctx.response.status)
     );
     return includesCodes && includesMethod && baseRetryCondition;
   };
   const executeRetryHook = async (shouldThrowOnError) => {
     try {
-      if (!isFunction(ctx.options.onRetry)) return;
-      await executeHooks(ctx.options.onRetry(ctx));
+      return await executeHooks(options.onRetry?.(ctx));
     } catch (error) {
-      const { getErrorResult } = resolveErrorResult({
-        cloneResponse: ctx.options.cloneResponse,
-        defaultErrorMessage: ctx.options.defaultErrorMessage,
+      const { apiDetails } = resolveErrorResult({
+        cloneResponse: options.cloneResponse,
+        defaultErrorMessage: options.defaultErrorMessage,
         error,
-        resultMode: ctx.options.resultMode
+        resultMode: options.resultMode
       });
       if (shouldThrowOnError) {
         throw error;
       }
-      return getErrorResult();
+      return apiDetails;
     }
   };
   return {
@@ -698,7 +826,7 @@ var createFetchClient = (baseConfig = {}) => {
     const { handleRequestCancelStrategy, handleRequestDeferStrategy, removeDedupeKeyFromCache } = await createDedupeStrategy({ $RequestInfoCache, newFetchController, options, request });
     await handleRequestCancelStrategy();
     try {
-      await executeHooks(options.onRequest({ options, request }));
+      await executeHooks(options.onRequest?.({ options, request }));
       request.headers = mergeAndResolveHeaders({
         auth: options.auth,
         body: request.body,
@@ -734,11 +862,11 @@ var createFetchClient = (baseConfig = {}) => {
         data: validSuccessData,
         options,
         request,
-        response: options.cloneResponse ? response.clone() : response
+        response
       };
       await executeHooks(
-        options.onSuccess(successContext),
-        options.onResponse({ ...successContext, error: null })
+        options.onSuccess?.(successContext),
+        options.onResponse?.({ ...successContext, error: null })
       );
       return await resolveSuccessResult({
         data: successContext.data,
@@ -773,33 +901,33 @@ var createFetchClient = (baseConfig = {}) => {
           return callApi2(initURL, updatedOptions);
         }
         if (shouldThrowOnError) {
-          throw apiDetails.error;
+          throw error;
         }
         return customInfo ? getErrorResult(customInfo) : getErrorResult();
       };
       if (isHTTPErrorInstance(error)) {
         await executeHooks(
-          options.onResponseError(errorContext),
-          options.onError(errorContext),
-          options.onResponse({ ...errorContext, data: null })
+          options.onResponseError?.(errorContext),
+          options.onError?.(errorContext),
+          options.onResponse?.({ ...errorContext, data: null })
         );
         return await handleRetryOrGetResult();
       }
       if (error instanceof DOMException && error.name === "AbortError") {
         const { message, name } = error;
-        console.error(`${name}:`, message);
+        !shouldThrowOnError && console.error(`${name}:`, message);
         return await handleRetryOrGetResult();
       }
       if (error instanceof DOMException && error.name === "TimeoutError") {
         const message = `Request timed out after ${options.timeout}ms`;
-        console.error(`${error.name}:`, message);
+        !shouldThrowOnError && console.error(`${error.name}:`, message);
         return await handleRetryOrGetResult({ message });
       }
       await executeHooks(
         // == At this point only the request errors exist, so the request error interceptor is called
-        options.onRequestError(errorContext),
+        options.onRequestError?.(errorContext),
         // == Also call the onError interceptor
-        options.onError(errorContext)
+        options.onError?.(errorContext)
       );
       return await handleRetryOrGetResult();
     } finally {