@fgrzl/fetch 1.1.0 → 1.3.0-alpha.3

package/dist/index.d.ts

@@ -59,6 +59,20 @@ interface FetchClientOptions {
      * - 'omit': Never send cookies
      */
     credentials?: RequestCredentials;
+    /**
+     * Base URL for relative requests.
+     *
+     * When set, all relative URLs (not starting with http:// or https://) will be
+     * prefixed with this base URL. Absolute URLs are used as-is.
+     *
+     * @example
+     * ```typescript
+     * const client = new FetchClient({ baseUrl: 'https://api.example.com' });
+     * await client.get('/users'); // → GET https://api.example.com/users
+     * await client.get('https://other-api.com/data'); // → GET https://other-api.com/data
+     * ```
+     */
+    baseUrl?: string;
 }
 
 /**
@@ -115,12 +129,45 @@ type FetchMiddleware = (request: RequestInit & {
 declare class FetchClient {
     private middlewares;
     private credentials;
+    private baseUrl;
     constructor(config?: FetchClientOptions);
     use(middleware: FetchMiddleware): this;
+    /**
+     * Set or update the base URL for this client instance.
+     *
+     * When a base URL is set, relative URLs will be resolved against it.
+     * Absolute URLs will continue to work unchanged.
+     *
+     * @param baseUrl - The base URL to set, or undefined to clear it
+     * @returns The client instance for method chaining
+     *
+     * @example Set base URL:
+     * ```typescript
+     * const client = new FetchClient();
+     * client.setBaseUrl('https://api.example.com');
+     *
+     * // Now relative URLs work
+     * await client.get('/users'); // → GET https://api.example.com/users
+     * ```
+     *
+     * @example Chain with middleware:
+     * ```typescript
+     * const client = useProductionStack(new FetchClient())
+     *   .setBaseUrl(process.env.API_BASE_URL);
+     * ```
+     */
+    setBaseUrl(baseUrl?: string): this;
     request<T = unknown>(url: string, init?: RequestInit): Promise<FetchResponse<T>>;
     private coreFetch;
     private parseResponse;
     private buildUrlWithParams;
+    /**
+     * Resolves a URL with the base URL if it's relative and base URL is configured
+     * @param url - The URL to resolve
+     * @returns The resolved URL
+     * @private
+     */
+    private resolveUrl;
     /**
      * HEAD request with query parameter support.
      *
@@ -314,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.
  */
@@ -1410,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';
@@ -1430,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

@@ -3,16 +3,46 @@ var FetchClient = class {
   constructor(config = {}) {
     this.middlewares = [];
     this.credentials = config.credentials ?? "same-origin";
+    this.baseUrl = config.baseUrl;
   }
   use(middleware) {
     this.middlewares.push(middleware);
     return this;
   }
+  /**
+   * Set or update the base URL for this client instance.
+   *
+   * When a base URL is set, relative URLs will be resolved against it.
+   * Absolute URLs will continue to work unchanged.
+   *
+   * @param baseUrl - The base URL to set, or undefined to clear it
+   * @returns The client instance for method chaining
+   *
+   * @example Set base URL:
+   * ```typescript
+   * const client = new FetchClient();
+   * client.setBaseUrl('https://api.example.com');
+   *
+   * // Now relative URLs work
+   * await client.get('/users'); // → GET https://api.example.com/users
+   * ```
+   *
+   * @example Chain with middleware:
+   * ```typescript
+   * const client = useProductionStack(new FetchClient())
+   *   .setBaseUrl(process.env.API_BASE_URL);
+   * ```
+   */
+  setBaseUrl(baseUrl) {
+    this.baseUrl = baseUrl;
+    return this;
+  }
   async request(url, init = {}) {
+    const resolvedUrl = this.resolveUrl(url);
     let index = 0;
     const execute = async (request) => {
-      const currentRequest = request || { ...init, url };
-      const currentUrl = currentRequest.url || url;
+      const currentRequest = request || { ...init, url: resolvedUrl };
+      const currentUrl = currentRequest.url || resolvedUrl;
       if (index >= this.middlewares.length) {
         const { url: _, ...requestInit } = currentRequest;
         return this.coreFetch(requestInit, currentUrl);
@@ -96,20 +126,48 @@ var FetchClient = class {
     if (!params) {
       return url;
     }
-    const urlObj = new URL(
-      url,
-      url.startsWith("http") ? void 0 : "http://localhost"
-    );
+    const resolvedUrl = this.resolveUrl(url);
+    if (!resolvedUrl.startsWith("http://") && !resolvedUrl.startsWith("https://") && !resolvedUrl.startsWith("//")) {
+      const searchParams = new URLSearchParams();
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null) {
+          searchParams.set(key, String(value));
+        }
+      });
+      const queryString = searchParams.toString();
+      return queryString ? `${resolvedUrl}?${queryString}` : resolvedUrl;
+    }
+    const urlObj = new URL(resolvedUrl);
     Object.entries(params).forEach(([key, value]) => {
       if (value !== void 0 && value !== null) {
         urlObj.searchParams.set(key, String(value));
       }
     });
-    if (!url.startsWith("http")) {
-      return urlObj.pathname + urlObj.search;
-    }
     return urlObj.toString();
   }
+  /**
+   * Resolves a URL with the base URL if it's relative and base URL is configured
+   * @param url - The URL to resolve
+   * @returns The resolved URL
+   * @private
+   */
+  resolveUrl(url) {
+    if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("//")) {
+      return url;
+    }
+    if (!this.baseUrl) {
+      return url;
+    }
+    try {
+      const baseUrl = new URL(this.baseUrl);
+      const resolvedUrl = new URL(url, baseUrl);
+      return resolvedUrl.toString();
+    } catch {
+      throw new Error(
+        `Invalid URL: Unable to resolve "${url}" with baseUrl "${this.baseUrl}"`
+      );
+    }
+  }
   // 🎯 PIT OF SUCCESS: Convenience methods with smart defaults
   /**
    * HEAD request with query parameter support.
@@ -1022,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({
@@ -1056,6 +1148,8 @@ export {
   FetchError,
   HttpError,
   NetworkError,
+  appendQueryParams,
+  buildQueryParams,
   createAuthenticationMiddleware,
   createAuthorizationMiddleware,
   createCacheMiddleware,