@fgrzl/fetch 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -361,6 +361,93 @@ declare class NetworkError extends FetchError {
     constructor(message: string, url: string, cause?: Error);
 }
 
+/**
+ * @fileoverview Query parameter utilities for FetchClient
+ *
+ * Provides utilities for building URL query strings from JavaScript objects
+ * with proper handling of arrays, undefined values, and URL encoding.
+ */
+/**
+ * Query parameter value types that can be converted to URL parameters.
+ * Arrays are handled specially with multiple parameter entries.
+ */
+type QueryValue = string | number | boolean | null | undefined | QueryValue[];
+/**
+ * Object representing query parameters for URL construction.
+ */
+type QueryParams = Record<string, QueryValue>;
+/**
+ * Builds a URL query string from a JavaScript object.
+ *
+ * Features:
+ * - ✅ Proper URL encoding via native URLSearchParams
+ * - ✅ Array handling with multiple parameter entries
+ * - ✅ Undefined value filtering (excluded from output)
+ * - ✅ Type coercion to strings for all values
+ *
+ * @param query - Object containing query parameters
+ * @returns URL-encoded query string (without leading '?')
+ *
+ * @example Basic usage:
+ * ```typescript
+ * buildQueryParams({ name: 'John', age: 30 })
+ * // → "name=John&age=30"
+ * ```
+ *
+ * @example Array handling:
+ * ```typescript
+ * buildQueryParams({ tags: ['typescript', 'javascript'], active: true })
+ * // → "tags=typescript&tags=javascript&active=true"
+ * ```
+ *
+ * @example Undefined filtering:
+ * ```typescript
+ * buildQueryParams({ name: 'John', email: undefined, age: null })
+ * // → "name=John&age=null" (undefined excluded, null converted to string)
+ * ```
+ *
+ * @example Real-world API usage:
+ * ```typescript
+ * const filters = {
+ *   status: ['active', 'pending'],
+ *   limit: 50,
+ *   offset: 0,
+ *   search: searchTerm || undefined // Conditionally included
+ * };
+ *
+ * const queryString = buildQueryParams(filters);
+ * // → "status=active&status=pending&limit=50&offset=0"
+ * // (search excluded if searchTerm is undefined)
+ * ```
+ */
+declare function buildQueryParams(query: QueryParams): string;
+/**
+ * Appends query parameters to a URL, handling existing query strings properly.
+ *
+ * @param baseUrl - The base URL to append parameters to
+ * @param query - Object containing query parameters
+ * @returns Complete URL with query parameters appended
+ *
+ * @example Basic URL building:
+ * ```typescript
+ * appendQueryParams('/api/users', { limit: 10, active: true })
+ * // → "/api/users?limit=10&active=true"
+ * ```
+ *
+ * @example Existing query parameters:
+ * ```typescript
+ * appendQueryParams('/api/users?sort=name', { limit: 10 })
+ * // → "/api/users?sort=name&limit=10"
+ * ```
+ *
+ * @example Empty query object:
+ * ```typescript
+ * appendQueryParams('/api/users', {})
+ * // → "/api/users" (no change)
+ * ```
+ */
+declare function appendQueryParams(baseUrl: string, query: QueryParams): string;
+
 /**
  * @fileoverview Authentication middleware types and configuration.
  */
@@ -1457,6 +1544,18 @@ declare function useBasicStack(client: FetchClient, config: {
  * const activeUsers = await api.get('/api/users', { status: 'active', limit: 10 });
  * ```
  *
+ * @example Set base URL for API-specific clients:
+ * ```typescript
+ * import api from '@fgrzl/fetch';
+ *
+ * // Configure base URL dynamically
+ * api.setBaseUrl('https://api.example.com');
+ *
+ * // Now all relative URLs are prefixed automatically
+ * const users = await api.get('/users');        // → GET https://api.example.com/users
+ * const posts = await api.get('/posts');        // → GET https://api.example.com/posts
+ * ```
+ *
  * @example Configure authentication:
  * ```typescript
  * import api from '@fgrzl/fetch';
@@ -1477,7 +1576,22 @@ declare function useBasicStack(client: FetchClient, config: {
  *   tokenProvider: () => getJWTToken()
  * });
  * ```
+ *
+ * @example Production-ready API client with base URL:
+ * ```typescript
+ * import { FetchClient, useProductionStack } from '@fgrzl/fetch';
+ *
+ * // One-liner production setup with base URL
+ * const apiClient = useProductionStack(new FetchClient(), {
+ *   auth: { tokenProvider: () => getAuthToken() },
+ *   retry: { maxRetries: 3 },
+ *   logging: { level: 'info' }
+ * }).setBaseUrl(process.env.API_BASE_URL || 'https://api.example.com');
+ *
+ * // Ready to use with full production features
+ * const users = await apiClient.get('/users');
+ * ```
  */
 declare const api: FetchClient;
 
-export { type AuthTokenProvider, type AuthenticationOptions, type AuthorizationOptions, type CacheEntry, type CacheKeyGenerator, type CacheOptions, type CacheStorage, FetchClient, type FetchClientOptions, FetchError, type FetchResponse, HttpError, type FetchMiddleware as InterceptMiddleware, type LogLevel, type Logger, type LoggingOptions, NetworkError, type RateLimitAlgorithm, type RateLimitOptions, type RetryOptions, type UnauthorizedHandler, createAuthenticationMiddleware, createAuthorizationMiddleware, createCacheMiddleware, createLoggingMiddleware, createRateLimitMiddleware, createRetryMiddleware, api as default, useAuthentication, useAuthorization, useBasicStack, useCSRF, useCache, useDevelopmentStack, useLogging, useProductionStack, useRateLimit, useRetry };
+export { type AuthTokenProvider, type AuthenticationOptions, type AuthorizationOptions, type CacheEntry, type CacheKeyGenerator, type CacheOptions, type CacheStorage, FetchClient, type FetchClientOptions, FetchError, type FetchResponse, HttpError, type FetchMiddleware as InterceptMiddleware, type LogLevel, type Logger, type LoggingOptions, NetworkError, type QueryParams, type QueryValue, type RateLimitAlgorithm, type RateLimitOptions, type RetryOptions, type UnauthorizedHandler, appendQueryParams, buildQueryParams, createAuthenticationMiddleware, createAuthorizationMiddleware, createCacheMiddleware, createLoggingMiddleware, createRateLimitMiddleware, createRetryMiddleware, api as default, useAuthentication, useAuthorization, useBasicStack, useCSRF, useCache, useDevelopmentStack, useLogging, useProductionStack, useRateLimit, useRetry };

package/dist/index.js

@@ -1080,6 +1080,40 @@ var NetworkError = class extends FetchError {
   }
 };
 
+// src/client/query.ts
+function buildQueryParams(query) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0) {
+      if (Array.isArray(value)) {
+        value.forEach((item) => {
+          if (item !== void 0) {
+            params.append(key, String(item));
+          }
+        });
+      } else {
+        params.set(key, String(value));
+      }
+    }
+  }
+  return params.toString();
+}
+function appendQueryParams(baseUrl, query) {
+  const queryString = buildQueryParams(query);
+  if (!queryString) {
+    return baseUrl;
+  }
+  const fragmentIndex = baseUrl.indexOf("#");
+  if (fragmentIndex !== -1) {
+    const urlPart = baseUrl.substring(0, fragmentIndex);
+    const fragmentPart = baseUrl.substring(fragmentIndex);
+    const separator2 = urlPart.includes("?") ? "&" : "?";
+    return `${urlPart}${separator2}${queryString}${fragmentPart}`;
+  }
+  const separator = baseUrl.includes("?") ? "&" : "?";
+  return `${baseUrl}${separator}${queryString}`;
+}
+
 // src/index.ts
 var api = useProductionStack(
   new FetchClient({
@@ -1114,6 +1148,8 @@ export {
   FetchError,
   HttpError,
   NetworkError,
+  appendQueryParams,
+  buildQueryParams,
   createAuthenticationMiddleware,
   createAuthorizationMiddleware,
   createCacheMiddleware,