@zayne-labs/callapi 1.8.20 → 1.8.21

package/dist/esm/index.d.ts

@@ -1,22 +1,22 @@
-import { AnyFunction, AnyString, ApplyStrictConfig, ApplyURLBasedConfig, BaseCallApiConfig, BaseCallApiExtraOptions, BaseCallApiSchemaAndConfig, BaseCallApiSchemaRoutes, CallApiConfig, CallApiExtraOptions, CallApiExtraOptionsForHooks, CallApiParameters, CallApiPlugin, CallApiRequestOptions, CallApiRequestOptionsForHooks, CallApiResult, CallApiResultErrorVariant, CallApiResultSuccessVariant, CallApiSchema, CallApiSchemaConfig, DedupeOptions, DefaultDataType, DefaultPluginArray, DefaultThrowOnError, ErrorContext, GetCurrentRouteSchema, GetCurrentRouteSchemaKey, HTTPError, Hooks, HooksOrHooksArray, InferInitURL, InferParamsFromRoute, InferSchemaResult, PluginExtraOptions, PluginHooks, PluginHooksWithMoreOptions, PluginInitContext, PossibleHTTPError, PossibleJavaScriptError, PossibleJavaScriptOrValidationError, PossibleValidationError, Register, RequestContext, RequestStreamContext, ResponseContext, ResponseErrorContext, ResponseStreamContext, ResponseTypeUnion, ResultModeUnion, RetryOptions, SuccessContext, ThrowOnErrorUnion, URLOptions, ValidationError, Writeable } from "./common-Vd9i_nPc.js";
+import { AnyFunction, AnyString, ApplyStrictConfig, ApplyURLBasedConfig, BaseCallApiConfig, BaseCallApiExtraOptions, BaseCallApiSchemaAndConfig, BaseCallApiSchemaRoutes, CallApiConfig, CallApiExtraOptions, CallApiExtraOptionsForHooks, CallApiParameters, CallApiPlugin, CallApiRequestOptions, CallApiRequestOptionsForHooks, CallApiResult, CallApiResultErrorVariant, CallApiResultSuccessVariant, CallApiSchema, CallApiSchemaConfig, DedupeOptions, DefaultDataType, DefaultPluginArray, DefaultThrowOnError, ErrorContext, GetCurrentRouteSchema, GetCurrentRouteSchemaKey, HTTPError, Hooks, HooksOrHooksArray, InferInitURL, InferParamsFromRoute, InferSchemaResult, PluginExtraOptions, PluginHooks, PluginHooksWithMoreOptions, PluginInitContext, PossibleHTTPError, PossibleJavaScriptError, PossibleJavaScriptOrValidationError, PossibleValidationError, Register, RequestContext, RequestStreamContext, ResponseContext, ResponseErrorContext, ResponseStreamContext, ResponseTypeUnion, ResultModeUnion, RetryOptions, SuccessContext, ThrowOnErrorUnion, URLOptions, ValidationError, Writeable } from "./common-C-kIzPcz.js";
 
 //#region src/createFetchClient.d.ts
 
 declare const createFetchClient: <TBaseData = DefaultDataType, TBaseErrorData = DefaultDataType, TBaseResultMode extends ResultModeUnion = ResultModeUnion, TBaseThrowOnError extends ThrowOnErrorUnion = DefaultThrowOnError, TBaseResponseType extends ResponseTypeUnion = ResponseTypeUnion, const TBaseSchemaAndConfig extends BaseCallApiSchemaAndConfig = BaseCallApiSchemaAndConfig, const TBasePluginArray extends CallApiPlugin[] = DefaultPluginArray, TComputedBaseSchemaConfig extends CallApiSchemaConfig = NonNullable<Writeable<TBaseSchemaAndConfig["config"], "deep">>, TComputedBaseSchemaRoutes extends BaseCallApiSchemaRoutes = Writeable<TBaseSchemaAndConfig["routes"], "deep">>(initBaseConfig?: BaseCallApiConfig<TBaseData, TBaseErrorData, TBaseResultMode, TBaseThrowOnError, TBaseResponseType, TBaseSchemaAndConfig, TBasePluginArray>) => <TData = TBaseData, TErrorData = TBaseErrorData, TResultMode extends ResultModeUnion = TBaseResultMode, TThrowOnError extends ThrowOnErrorUnion = TBaseThrowOnError, TResponseType extends ResponseTypeUnion = TBaseResponseType, const TSchemaConfig extends CallApiSchemaConfig = TComputedBaseSchemaConfig, TInitURL extends InferInitURL<TComputedBaseSchemaRoutes, TSchemaConfig> = InferInitURL<TComputedBaseSchemaRoutes, TSchemaConfig>, TCurrentRouteSchemaKey extends GetCurrentRouteSchemaKey<TSchemaConfig, TInitURL> = GetCurrentRouteSchemaKey<TSchemaConfig, TInitURL>, const TSchema extends CallApiSchema = GetCurrentRouteSchema<TComputedBaseSchemaRoutes, TCurrentRouteSchemaKey>, const TPluginArray extends CallApiPlugin[] = TBasePluginArray>(initURL: TInitURL, config?: CallApiConfig<InferSchemaResult<TSchema["data"], TData>, InferSchemaResult<TSchema["errorData"], TErrorData>, TResultMode, TThrowOnError, TResponseType, TComputedBaseSchemaRoutes, TSchema, TComputedBaseSchemaConfig, TSchemaConfig, TInitURL, TCurrentRouteSchemaKey, TBasePluginArray, TPluginArray> | undefined) => CallApiResult<InferSchemaResult<TSchema["data"], TData>, InferSchemaResult<TSchema["errorData"], TErrorData>, TResultMode, TThrowOnError, TResponseType>;
-declare const callApi: <TData = unknown, TErrorData = unknown, TResultMode extends ResultModeUnion = ResultModeUnion, TThrowOnError extends ThrowOnErrorUnion = boolean, TResponseType extends ResponseTypeUnion = ResponseTypeUnion, const TSchemaConfig extends CallApiSchemaConfig = CallApiSchemaConfig, TInitURL extends ApplyStrictConfig<TSchemaConfig, ApplyURLBasedConfig<TSchemaConfig, AnyString | "delete/" | "get/" | "patch/" | "post/" | "put/">> = ApplyStrictConfig<TSchemaConfig, ApplyURLBasedConfig<TSchemaConfig, AnyString | "delete/" | "get/" | "patch/" | "post/" | "put/">>, TCurrentRouteSchemaKey extends GetCurrentRouteSchemaKey<TSchemaConfig, TInitURL> = GetCurrentRouteSchemaKey<TSchemaConfig, TInitURL>, const TSchema extends CallApiSchema = GetCurrentRouteSchema<{
+declare const callApi: <TData = unknown, TErrorData = unknown, TResultMode extends ResultModeUnion = ResultModeUnion, TThrowOnError extends ThrowOnErrorUnion = boolean, TResponseType extends ResponseTypeUnion = ResponseTypeUnion, const TSchemaConfig extends CallApiSchemaConfig = CallApiSchemaConfig, TInitURL extends ApplyStrictConfig<TSchemaConfig, ApplyURLBasedConfig<TSchemaConfig, AnyString | "@delete/" | "@get/" | "@patch/" | "@post/" | "@put/">> = ApplyStrictConfig<TSchemaConfig, ApplyURLBasedConfig<TSchemaConfig, AnyString | "@delete/" | "@get/" | "@patch/" | "@post/" | "@put/">>, TCurrentRouteSchemaKey extends GetCurrentRouteSchemaKey<TSchemaConfig, TInitURL> = GetCurrentRouteSchemaKey<TSchemaConfig, TInitURL>, const TSchema extends CallApiSchema = GetCurrentRouteSchema<{
   [x: AnyString]: CallApiSchema | undefined;
-  "delete/"?: CallApiSchema | undefined;
-  "get/"?: CallApiSchema | undefined;
-  "patch/"?: CallApiSchema | undefined;
-  "post/"?: CallApiSchema | undefined;
-  "put/"?: CallApiSchema | undefined;
+  "@delete/"?: CallApiSchema | undefined;
+  "@get/"?: CallApiSchema | undefined;
+  "@patch/"?: CallApiSchema | undefined;
+  "@post/"?: CallApiSchema | undefined;
+  "@put/"?: CallApiSchema | undefined;
 }, TCurrentRouteSchemaKey>, const TPluginArray extends CallApiPlugin[] = DefaultPluginArray>(initURL: TInitURL, config?: CallApiConfig<InferSchemaResult<TSchema["data"], TData>, InferSchemaResult<TSchema["errorData"], TErrorData>, TResultMode, TThrowOnError, TResponseType, {
   [x: AnyString]: CallApiSchema | undefined;
-  "delete/"?: CallApiSchema | undefined;
-  "get/"?: CallApiSchema | undefined;
-  "patch/"?: CallApiSchema | undefined;
-  "post/"?: CallApiSchema | undefined;
-  "put/"?: CallApiSchema | undefined;
+  "@delete/"?: CallApiSchema | undefined;
+  "@get/"?: CallApiSchema | undefined;
+  "@patch/"?: CallApiSchema | undefined;
+  "@post/"?: CallApiSchema | undefined;
+  "@put/"?: CallApiSchema | undefined;
 }, TSchema, CallApiSchemaConfig, TSchemaConfig, TInitURL, TCurrentRouteSchemaKey, DefaultPluginArray, TPluginArray> | undefined) => CallApiResult<InferSchemaResult<TSchema["data"], TData>, InferSchemaResult<TSchema["errorData"], TErrorData>, TResultMode, TThrowOnError, TResponseType>;
 //#endregion
 //#region src/defineHelpers.d.ts

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-import { HTTPError, ValidationError, createCombinedSignal, createTimeoutSignal, dedupeDefaults, defineEnum, deterministicHashFn, getBody, getFetchImpl, getHeaders, hookDefaults, isArray, isFunction, isHTTPErrorInstance, isObject, isPlainObject, isReadableStream, isString, isValidationErrorInstance, requestOptionDefaults, responseDefaults, retryDefaults, splitBaseConfig, splitConfig, toQueryString, waitFor } from "./utils-C4H57FX_.js";
+import { HTTPError, ValidationError, createCombinedSignal, createTimeoutSignal, dedupeDefaults, defineEnum, deterministicHashFn, getBody, getFetchImpl, getHeaders, hookDefaults, isArray, isFunction, isHTTPErrorInstance, isObject, isPlainObject, isReadableStream, isString, isValidationErrorInstance, requestOptionDefaults, responseDefaults, retryDefaults, splitBaseConfig, splitConfig, toQueryString, waitFor } from "./utils-DZe23qYR.js";
 
 //#region src/result.ts
 const getResponseType = (response, parser) => ({
@@ -107,13 +107,13 @@ const hookRegistries = {
 	onSuccess: /* @__PURE__ */ new Set(),
 	onValidationError: /* @__PURE__ */ new Set()
 };
-const composeAllHooks = (hooksArray, mergedHooksExecutionMode) => {
+const composeAllHooks = (hooksArray, hooksExecutionMode) => {
 	const mergedHook = async (ctx) => {
-		if (mergedHooksExecutionMode === "sequential") {
+		if (hooksExecutionMode === "sequential") {
 			for (const hook of hooksArray) await hook?.(ctx);
 			return;
 		}
-		if (mergedHooksExecutionMode === "parallel") await Promise.all(hooksArray.map((uniqueHook) => uniqueHook?.(ctx)));
+		if (hooksExecutionMode === "parallel") await Promise.all(hooksArray.map((uniqueHook) => uniqueHook?.(ctx)));
 	};
 	return mergedHook;
 };
@@ -241,21 +241,69 @@ const toStreamableResponse = async (context) => {
 
 //#endregion
 //#region src/dedupe.ts
-const getAbortErrorMessage = (dedupeKey, fullURL) => {
-	return dedupeKey ? `Duplicate request detected - Aborted previous request with key '${dedupeKey}' as a new request was initiated` : `Duplicate request detected - Aborted previous request to '${fullURL}' as a new request with identical options was initiated`;
+const resolveDedupeKey = (dedupeKey, context) => {
+	if (isFunction(dedupeKey)) return dedupeKey(context);
+	return dedupeKey ?? null;
 };
+const getAbortErrorMessage = (dedupeKey, context) => {
+	if (dedupeKey) return `Duplicate request detected - Aborted previous request with key '${resolveDedupeKey(dedupeKey, context)}' as a new request was initiated`;
+	return `Duplicate request detected - Aborted previous request to '${context.options.fullURL}' as a new request with identical options was initiated`;
+};
+/**
+* @description Creates and manages the deduplication strategy for a request.
+*
+* This is the core function that implements request deduplication logic. It handles
+* cache management, key generation, and provides strategy-specific handlers for
+* cancel and defer operations.
+*
+* **Key Responsibilities:**
+* - Generates or resolves deduplication keys
+* - Manages cache scope (local vs global)
+* - Provides strategy handlers (cancel, defer)
+* - Handles cache cleanup operations
+*
+* **Performance Optimizations:**
+* - Includes a small delay (0.1ms) for simultaneous request handling
+* - Lazy cache creation for global scopes
+* - Efficient cache key resolution
+*
+* **Internal Usage:**
+* This function is used internally by the CallApi system and is not intended
+* for direct use in application code. It's called automatically during request
+* processing when deduplication is enabled.
+*
+* @param context - Extended request context with deduplication-specific properties
+* @returns Promise resolving to deduplication strategy handlers and metadata
+*
+* @example
+* ```ts
+* // This is used internally, but conceptually:
+* const strategy = await createDedupeStrategy({
+*   ...requestContext,
+*   $GlobalRequestInfoCache: globalCache,
+*   $LocalRequestInfoCache: localCache,
+*   newFetchController: new AbortController()
+* });
+*
+* // Use the returned strategy
+* await strategy.handleRequestCancelStrategy();
+* const response = await strategy.handleRequestDeferStrategy({ options, request });
+* strategy.removeDedupeKeyFromCache();
+* ```
+*/
 const createDedupeStrategy = async (context) => {
 	const { $GlobalRequestInfoCache: $GlobalRequestInfoCache$1, $LocalRequestInfoCache, baseConfig, config, newFetchController, options: globalOptions, request: globalRequest } = context;
 	const dedupeStrategy = globalOptions.dedupeStrategy ?? dedupeDefaults.dedupeStrategy;
-	const generateDedupeKey = () => {
+	const getDedupeKey = () => {
 		const shouldHaveDedupeKey = dedupeStrategy === "cancel" || dedupeStrategy === "defer";
 		if (!shouldHaveDedupeKey) return null;
+		if (globalOptions.dedupeKey) return resolveDedupeKey(globalOptions.dedupeKey, context);
 		return `${globalOptions.fullURL}-${deterministicHashFn({
 			options: globalOptions,
 			request: globalRequest
 		})}`;
 	};
-	const dedupeKey = globalOptions.dedupeKey ?? generateDedupeKey();
+	const dedupeKey = getDedupeKey();
 	const dedupeCacheScope = globalOptions.dedupeCacheScope ?? dedupeDefaults.dedupeCacheScope;
 	const dedupeCacheScopeKey = globalOptions.dedupeCacheScopeKey ?? dedupeDefaults.dedupeCacheScopeKey;
 	if (dedupeCacheScope === "global" && !$GlobalRequestInfoCache$1.has(dedupeCacheScopeKey)) $GlobalRequestInfoCache$1.set(dedupeCacheScopeKey, /* @__PURE__ */ new Map());
@@ -270,7 +318,7 @@ const createDedupeStrategy = async (context) => {
 	const handleRequestCancelStrategy = () => {
 		const shouldCancelRequest = prevRequestInfo && dedupeStrategy === "cancel";
 		if (!shouldCancelRequest) return;
-		const message = getAbortErrorMessage(globalOptions.dedupeKey, globalOptions.fullURL);
+		const message = getAbortErrorMessage(globalOptions.dedupeKey, context);
 		const reason = new DOMException(message, "AbortError");
 		prevRequestInfo.controller.abort(reason);
 		return Promise.resolve();
@@ -486,8 +534,8 @@ const initializePlugins = async (context) => {
 			clonedHookRegistries[key].add(pluginHook);
 		}
 	};
-	const mergedHooksExecutionOrder = options.mergedHooksExecutionOrder ?? hookDefaults.mergedHooksExecutionOrder;
-	if (mergedHooksExecutionOrder === "mainHooksBeforePlugins") addMainHooks();
+	const hookRegistrationOrder = options.hooksRegistrationOrder ?? hookDefaults.hooksRegistrationOrder;
+	if (hookRegistrationOrder === "mainFirst") addMainHooks();
 	const { currentRouteSchemaKey, mainInitURL } = getCurrentRouteSchemaKeyAndMainInitURL({
 		baseExtraOptions: baseConfig,
 		extraOptions: config,
@@ -529,14 +577,14 @@ const initializePlugins = async (context) => {
 		if (!plugin.hooks) continue;
 		addPluginHooks(plugin.hooks);
 	}
-	if (mergedHooksExecutionOrder === "mainHooksAfterPlugins") addMainHooks();
+	if (hookRegistrationOrder === "pluginsFirst") addMainHooks();
 	const resolvedHooks = {};
 	for (const [key, hookRegistry] of Object.entries(clonedHookRegistries)) {
 		if (hookRegistry.size === 0) continue;
 		const flattenedHookArray = [...hookRegistry].flat();
 		if (flattenedHookArray.length === 0) continue;
-		const mergedHooksExecutionMode = options.mergedHooksExecutionMode ?? hookDefaults.mergedHooksExecutionMode;
-		const composedHook = composeAllHooks(flattenedHookArray, mergedHooksExecutionMode);
+		const hooksExecutionMode = options.hooksExecutionMode ?? hookDefaults.hooksExecutionMode;
+		const composedHook = composeAllHooks(flattenedHookArray, hooksExecutionMode);
 		resolvedHooks[key] = composedHook;
 	}
 	return {
@@ -623,14 +671,39 @@ const mergeUrlWithQuery = (url, query) => {
 	return `${url}${questionMark}${queryString}`;
 };
 /**
-* @description
-* Extracts the method from the URL if it is a schema modifier.
+* @description Extracts the HTTP method from method-prefixed route patterns.
+*
+* Analyzes URLs that start with method modifiers (e.g., "@get/", "@post/") and extracts
+* the HTTP method for use in API requests. This enables method specification directly
+* in route definitions.
+*
+* @param initURL - The URL string to analyze for method modifiers
+* @returns The extracted HTTP method (lowercase) if found, otherwise undefined
+*
+* @example
+* ```typescript
+* // Method extraction from prefixed routes
+* extractMethodFromURL("@get/users");        // Returns: "get"
+* extractMethodFromURL("@post/users");       // Returns: "post"
+* extractMethodFromURL("@put/users/:id");    // Returns: "put"
+* extractMethodFromURL("@delete/users/:id"); // Returns: "delete"
+* extractMethodFromURL("@patch/users/:id");  // Returns: "patch"
+*
+* // No method modifier
+* extractMethodFromURL("/users");            // Returns: undefined
+* extractMethodFromURL("users");             // Returns: undefined
+*
+* // Invalid or unsupported methods
+* extractMethodFromURL("@invalid/users");    // Returns: undefined
+* extractMethodFromURL("@/users");           // Returns: undefined
 *
-* @param initURL - The URL to extract the method from.
-* @returns The method if it is a schema modifier, otherwise undefined.
+* // Edge cases
+* extractMethodFromURL(undefined);           // Returns: undefined
+* extractMethodFromURL("");                  // Returns: undefined
+* ```
 */
 const extractMethodFromURL = (initURL) => {
-	if (!initURL?.startsWith("@")) return;
+	if (!initURL || initURL.startsWith("@")) return;
 	const method = initURL.split("@")[1]?.split("/")[0];
 	if (!method || !routeKeyMethods.includes(method)) return;
 	return method;
@@ -646,7 +719,7 @@ const normalizeURL = (initURL) => {
 	const normalizedURL = initURL.replace(`@${methodFromURL}/`, "/");
 	return normalizedURL;
 };
-const getFullURL = (options) => {
+const getFullAndNormalizedURL = (options) => {
 	const { baseURL, initURL, params, query } = options;
 	const normalizedInitURL = normalizeURL(initURL);
 	const urlWithMergedParams = mergeUrlWithParams(normalizedInitURL, params);
@@ -693,7 +766,7 @@ const createFetchClient = (initBaseConfig = {}) => {
 			options: mergedExtraOptions,
 			request: mergedRequestOptions
 		});
-		const { fullURL, normalizedInitURL } = getFullURL({
+		const { fullURL, normalizedInitURL } = getFullAndNormalizedURL({
 			baseURL: resolvedOptions.baseURL,
 			initURL: resolvedInitURL,
 			params: resolvedOptions.params,
@@ -864,7 +937,7 @@ const createFetchClient = (initBaseConfig = {}) => {
 			}
 			let message = error?.message;
 			if (error instanceof DOMException && error.name === "AbortError") {
-				message = getAbortErrorMessage(options.dedupeKey, options.fullURL);
+				message = getAbortErrorMessage(options.dedupeKey, errorContext);
 				!shouldThrowOnError && console.error(`${error.name}:`, message);
 			}
 			if (error instanceof DOMException && error.name === "TimeoutError") {