aspi 2.0.1 → 2.2.0

package/README.md

@@ -3,13 +3,14 @@
 A tiny, type‑safe wrapper around the native **fetch** API that gives you a clean, monadic interface for HTTP requests.
 It ships with **zero runtime dependencies**, a **tiny bundle size**, and full **TypeScript** support out of the box.
 
-> **Why use Aspi?**
-> • End‑to‑end TypeScript typings (request + response)
-> • No extra weight – only a thin wrapper around `fetch`
-> • Chain‑of‑responsibility middleware support via `use`
-> • Result‑based error handling (values as errors)
-> • Built‑in retry, header helpers, query‑string handling, and schema validation (Zod, Arktype, Valibot)
-> • Flexible error mapping with `error` and convenience shortcuts
+**Why use Aspi?**
+
+- End‑to‑end TypeScript typings (request + response)
+- No extra weight – only a thin wrapper around `fetch`
+- Chain‑of‑responsibility middleware support via `use`
+- Result‑based error handling (values as errors)
+- Built‑in retry, header helpers, query‑string handling, and schema validation (Zod, Arktype, Valibot)
+- Flexible error mapping with `error` and convenience shortcuts
 
 ---
 
@@ -66,6 +67,67 @@ getTodo(1);
 
 ---
 
+## Why Aspi?
+
+Most real‑world codebases end up with one or more of these issues:
+
+1. **Inconsistent error handling**
+   - Some utilities throw raw `Error`/`AxiosError`.
+   - Others return `{ ok: false, error }` or `null` or a custom union.
+   - Callers don’t know whether to use `try/catch`, check `ok`, or both.
+
+2. **Retry logic duplicated everywhere**
+   - Each service rolls its own `while (attempt <= retries)` loop.
+   - Status codes, backoff strategies, and retry limits slowly diverge over time.
+   - There is no single place to see “how do we retry HTTP calls in this app?”.
+
+3. **Validation pushed far from the network boundary**
+   - Request payloads are sometimes validated, sometimes not.
+   - Response validation happens deep in the business logic (if at all).
+   - JSON parse errors leak as raw `SyntaxError`, not structured errors.
+
+4. **Configuration scattered across factories and interceptors**
+   - Base URL helpers, auth decorators, error mappers, retry plugins, and logging interceptors all live in different files.
+   - Global state / interceptors can make it hard to tell what a given request will actually do.
+
+5. **Type systems are bolted on, not designed in**
+   - Generic HTTP clients often expose `any` for responses.
+   - Error flows are not encoded in the type system, forcing manual guards and casting.
+
+## How Aspi fixes them
+
+Aspi’s design centers around three things:
+
+1. **Mode‑driven responses**
+
+   You decide at call‑site how you want to consume responses:
+   - `withResult()` → `json/text/blob` return a `Result.Result<Ok, ErrorUnion>`.
+   - `throwable()` → `json/text/blob` return `AspiPlainResponse` and throw on failure.
+   - Default → `json/text/blob` return `[ok, err]` tuples.
+
+   All error variants are **tagged** so they can be safely narrowed by `error.tag`.
+
+2. **Centralized, configurable retry layer**
+
+   Retry behavior is described declaratively:
+   - `retries`: max attempts.
+   - `retryDelay`: number or function `(attempt, maxAttempts, request, response) => delayMs`.
+   - `retryOn`: list of HTTP status codes that should trigger a retry.
+   - `retryWhile`: predicate `(request, response) => boolean` for custom retry conditions.
+   - `onRetry`: hook invoked after each retry attempt.
+
+   This configuration can be applied globally (`Aspi.setRetry`) and overridden per request (`Request.setRetry`).
+
+3. **Validation at the transport boundary**
+
+   Using a `StandardSchemaV1` interface, Aspi integrates with schema libraries (e.g. Zod, Valibot) to:
+   - Validate request bodies with `bodySchema` + `bodyJson` **before** the network call.
+   - Validate responses with `schema()` + `json()` **after** JSON parsing.
+
+   These failures appear as tagged `parseError` values with structured issue lists, not random runtime exceptions.
+
+---
+
 ## Using the `Result` monad
 
 If you prefer a single `Result` value instead of a tuple, call **`.withResult()`** before a body‑parser method.
@@ -475,6 +537,220 @@ class Request<
 
 ---
 
+## Result utilities
+
+`Result<T, E>` is a small tagged-union helper used throughout Aspi to represent success or failure without throwing.
+
+```ts
+type Ok<T> = { __tag: 'ok'; value: T };
+type Err<E> = { __tag: 'err'; error: E };
+type Result<T, E> = Ok<T> | Err<E>;
+```
+
+Creating Results
+
+```ts
+import * as Result from './result';
+
+const success = Result.ok(42);
+const failure = Result.err('not found');
+```
+
+Checking and Extracting
+
+```ts
+if (Result.isOk(success)) {
+  console.log(success.value); // 42
+}
+
+if (Result.isErr(failure)) {
+  console.error(failure.error); // "not found"
+}
+
+const valueOrNull = Result.getOrNull(success); // 42 | null
+const errorOrNull = Result.getErrorOrNull(failure); // "not found" | null
+
+const valueOrFallback = Result.getOrElse(failure, 0); // 0
+
+// Throwing
+const mustHaveValue = Result.getOrThrow(success); // 42
+// Result.getOrThrow(failure) throws "not found"
+```
+
+Transforming
+
+```ts
+// map value
+const doubled = Result.map(success, (n) => n * 2); // ok(84)
+
+// map error
+const upperError = Result.mapErr(failure, (e) => e.toUpperCase()); // err("NOT FOUND")
+
+// pattern matching
+const message = Result.match(success, {
+  onOk: (n) => `Got ${n}`,
+  onErr: (e) => `Error: ${e}`,
+});
+// "Got 42"
+```
+
+Tagged error helpers
+When your error type is a union with a tag field, you can use helpers to handle specific variants:
+
+```ts
+type HttpError =
+  | { tag: 'BAD_REQUEST'; details?: string }
+  | { tag: 'UNAUTHORIZED' }
+  | { tag: 'NOT_FOUND' };
+
+const result: Result<number, HttpError> = Result.err({
+  tag: 'NOT_FOUND',
+});
+
+// Handle a specific tag
+Result.catchError(result, 'NOT_FOUND', (e) => {
+  console.log('Missing resource');
+});
+
+// Handle multiple tags
+Result.catchErrors(result, {
+  BAD_REQUEST: (e) => console.log('Invalid input'),
+  UNAUTHORIZED: () => console.log('Please log in'),
+});
+```
+
+Pipe Utility
+
+```ts
+import { pipe } from './result';
+
+const label = pipe(
+  12345,
+  (cents) => cents / 100,
+  (amount) => amount.toFixed(2),
+  (str) => `$${str}`,
+);
+// "$123.45"
+```
+
+---
+
+## Experimental capabilities
+
+> **Experimental:** This API is still evolving. Names and behavior may change in minor versions.
+
+Capabilities are small plugins that wrap the low‑level fetch call for each request. They let you implement cross‑cutting behavior (logging, retries, token refresh, tracing, etc.) without changing Aspi core.
+
+```ts
+import type { Capability } from './interceptor';
+import { Aspi } from './aspi';
+
+// Capability signature
+const myCapability: Capability = ({ request }) => ({
+  async run(runner) {
+    // Called before fetch
+    console.log('→', request.path);
+
+    const res = await runner(); // performs fetch(url, requestInit)
+
+    // Called after fetch
+    console.log('←', res.status, res.statusText);
+
+    return res;
+  },
+});
+```
+
+Registering capabilities
+Capabilities are attached at the Aspi client level and apply to all requests created from that instance:
+
+```ts
+const api = new Aspi({ baseUrl: 'https://api.example.com' }).useCapability(
+  myCapability,
+);
+
+const user = await api.get('/users/1').throwable().json<User>();
+```
+
+You can register multiple capabilities; they execute in the order they were added, each wrapping the next:
+
+```ts
+const api = new Aspi({ baseUrl: 'https://api.example.com' })
+  .useCapability(loggingCapability)
+  .useCapability(tracingCapability)
+  .useCapability(refreshTokenCapability);
+```
+
+Example: token refresh (simplified)
+
+```ts
+import type { Capability } from './interceptor';
+import { Aspi } from './aspi';
+import * as Result from './result';
+
+let tokens: { accessToken: string | null; refreshToken: string | null } = {
+  accessToken: null,
+  refreshToken: null,
+};
+
+async function refreshTokenRequest(refreshToken: string) {
+  const res = await new Aspi({ baseUrl: 'https://auth.example.com' })
+    .post('/refresh')
+    .bodyJson({ refreshToken })
+    .withResult()
+    .json<{ accessToken: string; refreshToken: string }>();
+
+  await Result.match(res, {
+    onOk: ({ data }) => {
+      tokens = data;
+    },
+    onErr: (err) => {
+      tokens = { accessToken: null, refreshToken: null };
+      throw err;
+    },
+  });
+}
+
+export const refreshTokenCapability: Capability = ({ request }) => {
+  let isRefreshing = false;
+
+  return {
+    async run(runner) {
+      // First try
+      const first = await runner();
+
+      if (first.status !== 401) {
+        return first;
+      }
+
+      // No refresh token → just propagate 401
+      if (!tokens.refreshToken || isRefreshing) {
+        return first;
+      }
+
+      isRefreshing = true;
+      try {
+        await refreshTokenRequest(tokens.refreshToken);
+      } finally {
+        isRefreshing = false;
+      }
+
+      if (!tokens.accessToken) {
+        return first;
+      }
+
+      // Inject new Authorization header and retry once
+      request.requestInit.headers = {
+        ...request.requestInit.headers,
+        Authorization: `Bearer ${tokens.accessToken}`,
+      };
+
+      return runner();
+    },
+  };
+};
+```
+
 ## License
 
 MIT © Aspi contributors

package/dist/index.cjs

@@ -20,7 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  Aspi: () => Aspi2,
+  Aspi: () => Aspi,
   AspiError: () => AspiError,
   CustomError: () => CustomError,
   Request: () => Request,
@@ -315,17 +315,19 @@ var Request = class {
   #shouldBeResult = false;
   #bodySchemaIssues = [];
   #throwOnError = false;
-  constructor(method, path, requestOptions) {
+  #capabilities = [];
+  constructor(method, path, requestOptions, capabilities = []) {
     this.#path = path;
     this.#middlewares = requestOptions.middlewares || [];
     this.#localRequestInit = {
       ...requestOptions.requestConfig,
       method
     };
-    this.#retryConfig = requestOptions.retryConfig;
-    this.#customErrorCbs = requestOptions.errorCbs || {};
+    this.#retryConfig = { ...requestOptions?.retryConfig || {} };
+    this.#customErrorCbs = { ...requestOptions?.errorCbs || {} };
     this.#throwOnError = requestOptions.throwOnError || false;
     this.#shouldBeResult = requestOptions.shouldBeResult || false;
+    this.#capabilities = [...capabilities];
   }
   /**
    * Sets the base URL for the request.
@@ -680,7 +682,29 @@ var Request = class {
    * request.setQueryParams(qp);
    */
   setQueryParams(params) {
-    this.#queryParams = new URLSearchParams(params);
+    let qp;
+    if (params instanceof URLSearchParams) {
+      qp = new URLSearchParams(params);
+    } else if (typeof params === "string") {
+      qp = new URLSearchParams(params);
+    } else if (Array.isArray(params)) {
+      qp = new URLSearchParams();
+      for (const entry of params) {
+        if (Array.isArray(entry) && entry.length === 2) {
+          qp.append(String(entry[0]), String(entry[1]));
+        }
+      }
+    } else if (typeof params === "object" && params !== null) {
+      qp = new URLSearchParams();
+      for (const [key, value] of Object.entries(
+        params
+      )) {
+        qp.append(key, String(value));
+      }
+    } else {
+      qp = new URLSearchParams();
+    }
+    this.#queryParams = qp;
     return this;
   }
   /**
@@ -921,11 +945,41 @@ var Request = class {
     return this.#mapResponse(output);
   }
   #url() {
+    if (this.#path.startsWith("http://") || this.#path.startsWith("https://")) {
+      const absolute = new URL(this.#path);
+      if (this.#queryParams) {
+        for (const [k, v] of this.#queryParams.entries()) {
+          absolute.searchParams.append(k, v);
+        }
+      }
+      return absolute.toString();
+    }
     const passedBaseUrl = typeof this.#localRequestInit.baseUrl === "string" ? this.#localRequestInit.baseUrl : this.#localRequestInit.baseUrl.toString();
-    const baseUrl = passedBaseUrl.replace(/\/+$/, "") ?? "";
-    const path = this.#path.replace(/^\/+/, "/");
-    const queryString = this.#queryParams ? `?${this.#queryParams.toString()}` : "";
-    const url = [baseUrl, path, queryString].filter(Boolean).join("");
+    const base = passedBaseUrl.replace(/\/+$/, "");
+    const [rawPathAndQuery, fragment] = this.#path.split("#", 2);
+    const [rawPath, existingQuery] = rawPathAndQuery.split("?", 2);
+    let path = rawPath || "";
+    path = path.replace(/^\/+/, "");
+    path = path.replace(/\/{2,}/g, "/");
+    path = path.replace(/\/+$/, "");
+    if (path) {
+      path = "/" + path.replace(/^\/+/, "");
+    }
+    const qs = new URLSearchParams(existingQuery ?? "");
+    if (this.#queryParams) {
+      for (const [k, v] of this.#queryParams.entries()) {
+        qs.append(k, v);
+      }
+    }
+    const queryString = qs.toString();
+    let url = base + path;
+    if (queryString) {
+      url += `?${queryString}`;
+    }
+    if (fragment) {
+      url += `#${fragment}`;
+    }
+    url = url.replace(/\/+$/, "");
     return url;
   }
   /**
@@ -1024,7 +1078,15 @@ var Request = class {
       let responseData = null;
       while (attempts <= retries) {
         try {
-          response = await fetch(url, requestInit);
+          if (this.#capabilities.length > 0) {
+            for (const capability of this.#capabilities) {
+              response = await capability({ request }).run(
+                () => fetch(url, requestInit)
+              );
+            }
+          } else {
+            response = await fetch(url, requestInit);
+          }
           responseData = await responseParser(response);
           if (responseData instanceof Error) {
             return err(responseData);
@@ -1217,8 +1279,9 @@ var Request = class {
     return {
       response,
       status: response.status,
-      statusText: getHttpErrorStatus(response.status),
-      responseData
+      statusLabel: getHttpErrorStatus(response.status),
+      responseData,
+      statusText: response.statusText
     };
   }
   /**
@@ -1283,16 +1346,62 @@ var Request = class {
     const cfg = this.#sanitisedRetryConfig();
     return { ...cfg };
   }
+  /**
+   * Registers a capability for this request.
+   *
+   * A capability is a small wrapper around the underlying `fetch` call that can
+   * intercept, inspect, or modify the request/response lifecycle. Each registered
+   * capability receives the constructed {@link AspiRequest} and can wrap the
+   * execution of the network call via its `run` method.
+   *
+   * Capabilities are applied in the order they are registered. For each HTTP
+   * call, the `Request` will:
+   *
+   * 1. Build an {@link AspiRequest} from the current configuration.
+   * 2. Create a runner: `() => fetch(url, requestInit)`.
+   * 3. Pass that runner through each capability in sequence, allowing them to:
+   *    - log or trace requests,
+   *    - implement retry/refresh logic,
+   *    - short‑circuit with synthetic responses, etc.
+   *
+   * @param capability - The capability factory to register. It will be invoked
+   *   for every execution of this request with the current {@link AspiRequest}.
+   *
+   * @returns This {@link Request} instance, enabling fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+   *
+   * const apiWithLogging = api.useCapability(({ request }) => ({
+   *   async run(runner) {
+   *     console.log('→', request.path, request.requestInit);
+   *     const res = await runner();
+   *     console.log('←', res.status, res.statusText);
+   *     return res;
+   *   },
+   * }));
+   *
+   * const result = await apiWithLogging
+   *   .get('/users')
+   *   .withResult()
+   *   .json();
+   * ```
+   */
+  useCapability(capability) {
+    return this.#capabilities.push(capability);
+  }
 };
 
 // src/aspi.ts
-var Aspi2 = class {
+var Aspi = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
   #customErrorCbs = {};
   #throwOnError = false;
   #shouldBeResult = false;
+  #capabilities = [];
   constructor(config) {
     const { retryConfig, ...requestInit } = config;
     this.#globalRequestInit = requestInit;
@@ -1335,17 +1444,22 @@ var Aspi2 = class {
     return this;
   }
   #createRequest(method, path) {
-    return new Request(method, path, {
-      requestConfig: {
-        ...this.#globalRequestInit,
-        method
+    return new Request(
+      method,
+      path,
+      {
+        requestConfig: {
+          ...this.#globalRequestInit,
+          method
+        },
+        middlewares: this.#middlewares,
+        errorCbs: this.#customErrorCbs,
+        throwOnError: this.#throwOnError,
+        shouldBeResult: this.#shouldBeResult,
+        retryConfig: this.#retryConfig
       },
-      middlewares: this.#middlewares,
-      errorCbs: this.#customErrorCbs,
-      throwOnError: this.#throwOnError,
-      shouldBeResult: this.#shouldBeResult,
-      retryConfig: this.#retryConfig
-    });
+      this.#capabilities
+    );
   }
   /**
    * Makes a GET request to the specified path
@@ -1613,7 +1727,7 @@ var Aspi2 = class {
    * api.internalServerError((req, res) => ({ message: 'Server error occurred' }));
    */
   internalServerError(cb) {
-    return this.error("internalServerErrorError", "INTERNAL_SERVER_ERROR", cb);
+    return this.error("internalServerError", "INTERNAL_SERVER_ERROR", cb);
   }
   /**
    * Sets the aspi to throw an error if the response status is not successful.
@@ -1640,6 +1754,47 @@ var Aspi2 = class {
     this.#throwOnError = false;
     return this;
   }
+  /**
+   * Registers a capability on this {@link Aspi} instance.
+   *
+   * A capability is a small, pluggable unit that can intercept and wrap the
+   * low‑level `fetch` call used by all requests created from this client.
+   * It is invoked for every request with the constructed {@link AspiRequest},
+   * and can:
+   *
+   * - inspect or mutate the outgoing request (e.g. inject auth headers),
+   * - inspect the raw {@link Response},
+   * - implement cross‑cutting concerns such as logging, tracing, retries,
+   *   or token refresh, and
+   * - short‑circuit the network call by returning a synthetic {@link Response}.
+   *
+   * Capabilities registered on the {@link Aspi} instance are propagated to every
+   * {@link Request} created via methods like {@link get}, {@link post}, etc.
+   * They are applied in the order they are registered.
+   *
+   * @param capability - The capability factory to install on this client.
+   *
+   * @returns This {@link Aspi} instance for fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+   *   .useCapability(({ request }) => ({
+   *     async run(runner) {
+   *       console.log('→', request.path);
+   *       const res = await runner();
+   *       console.log('←', res.status);
+   *       return res;
+   *     },
+   *   }));
+   *
+   * const user = await api.get('/users/1').throwable().json<User>();
+   * ```
+   */
+  useCapability(capability) {
+    this.#capabilities.push(capability);
+    return this;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -295,8 +295,9 @@ interface AspiRequest<T extends AspiRequestInit> {
  */
 type AspiResponse<TData = any, IsError extends boolean = false> = Merge<{
     status: HttpErrorCodes;
-    statusText: HttpErrorStatus;
+    statusLabel: HttpErrorStatus;
     response: Response;
+    statusText: string;
 }, IsError extends true ? {
     responseData: TData;
 } : {
@@ -365,6 +366,72 @@ interface JSONParseError extends CustomError<'jsonParseError', {
 declare const isAspiError: <TReq extends AspiRequestInit>(error: unknown) => error is AspiError<TReq>;
 declare const isCustomError: <Tag extends string, A>(error: unknown) => error is CustomError<Tag, A>;
 
+/**
+ * Arguments passed to a capability factory.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ */
+type CapabilityArgs<T extends AspiRequestInit = AspiRequestInit> = {
+    /**
+     * The fully constructed AspiRequest that will be used to execute `fetch`.
+     *
+     * You can:
+     * - inspect `request.path`, `request.requestInit`, `request.retryConfig`, etc.
+     * - mutate `request.requestInit.headers`, `signal`, or other properties
+     *   before the network call is made.
+     */
+    request: AspiRequest<AspiRequestInit>;
+};
+/**
+ * A capability is a small wrapper around the low-level `fetch` call that can
+ * intercept outgoing requests and incoming responses.
+ *
+ * It is a factory function that receives the current {@link AspiRequest}
+ * and returns an object exposing a single `run` method. The `run` method is
+ * responsible for invoking the provided `runner` (which performs the actual
+ * `fetch`) and may:
+ *
+ * - call `runner()` directly and return its result
+ * - call `runner()` multiple times (e.g. retry, refresh token then retry)
+ * - short‑circuit by *not* calling `runner()` and returning a synthetic
+ *   {@link Response} instead
+ *
+ * Capabilities are composed in the order they are registered via
+ * `Aspi.useCapability`, with each capability wrapping the next one in the
+ * chain.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ *
+ * @example
+ * ```ts
+ * // Simple logging capability
+ * const loggingCapability: Capability = ({ request }) => ({
+ *   async run(runner) {
+ *     console.log('→', request.path, request.requestInit);
+ *     const res = await runner();
+ *     console.log('←', res.status, res.statusText);
+ *     return res;
+ *   },
+ * });
+ *
+ * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+ *   .useCapability(loggingCapability);
+ * ```
+ */
+type Capability<T extends AspiRequestInit = AspiRequestInit> = ({ request, }: CapabilityArgs<T>) => {
+    /**
+     * Executes the next step in the capability chain.
+     *
+     * @param runner - A function that, when called, performs the actual
+     *   network request (or the next capability in the chain) and resolves to
+     *   a {@link Response}.
+     *
+     * @returns A promise resolving to the final {@link Response} that should be
+     *   used by Aspi for this request.
+     */
+    run: (runner: () => Promise<Response>) => Promise<Response>;
+};
+
 type Ok<T> = {
     __tag: 'ok';
     value: T;
@@ -767,7 +834,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     error: {};
 }> {
     #private;
-    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>);
+    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>, capabilities?: Capability[]);
     /**
      * Sets the base URL for the request.
      * @param url The base URL to set
@@ -1081,7 +1148,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      * const qp = new URLSearchParams({ page: '1' });
      * request.setQueryParams(qp);
      */
-    setQueryParams<T extends Record<string, string> | string[][] | string | URLSearchParams>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
+    setQueryParams<T = any>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
         queryParams: T;
     }>>;
     /**
@@ -1440,6 +1507,49 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         retryWhile: ((request: AspiRequest<TRequest>, response: AspiResponse) => boolean | Promise<boolean>) | undefined;
         onRetry: ((request: AspiRequest<TRequest>, response: AspiResponse) => void) | undefined;
     };
+    /**
+     * Registers a capability for this request.
+     *
+     * A capability is a small wrapper around the underlying `fetch` call that can
+     * intercept, inspect, or modify the request/response lifecycle. Each registered
+     * capability receives the constructed {@link AspiRequest} and can wrap the
+     * execution of the network call via its `run` method.
+     *
+     * Capabilities are applied in the order they are registered. For each HTTP
+     * call, the `Request` will:
+     *
+     * 1. Build an {@link AspiRequest} from the current configuration.
+     * 2. Create a runner: `() => fetch(url, requestInit)`.
+     * 3. Pass that runner through each capability in sequence, allowing them to:
+     *    - log or trace requests,
+     *    - implement retry/refresh logic,
+     *    - short‑circuit with synthetic responses, etc.
+     *
+     * @param capability - The capability factory to register. It will be invoked
+     *   for every execution of this request with the current {@link AspiRequest}.
+     *
+     * @returns This {@link Request} instance, enabling fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+     *
+     * const apiWithLogging = api.useCapability(({ request }) => ({
+     *   async run(runner) {
+     *     console.log('→', request.path, request.requestInit);
+     *     const res = await runner();
+     *     console.log('←', res.status, res.statusText);
+     *     return res;
+     *   },
+     * }));
+     *
+     * const result = await apiWithLogging
+     *   .get('/users')
+     *   .withResult()
+     *   .json();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): number;
 }
 
 /**
@@ -1718,7 +1828,7 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
      * api.internalServerError((req, res) => ({ message: 'Server error occurred' }));
      */
     internalServerError<A extends {}>(cb: CustomErrorCb<TRequest, A>): Aspi<TRequest, Prettify<Opts & {
-        error: { [K in keyof Opts["error"] | "internalServerErrorError"]: K extends "internalServerErrorError" ? CustomError<"internalServerErrorError", A> : Opts["error"][K]; };
+        error: { [K in "internalServerError" | keyof Opts["error"]]: K extends "internalServerError" ? CustomError<"internalServerError", A> : Opts["error"][K]; };
     }>>;
     /**
      * Sets the aspi to throw an error if the response status is not successful.
@@ -1743,6 +1853,44 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Registers a capability on this {@link Aspi} instance.
+     *
+     * A capability is a small, pluggable unit that can intercept and wrap the
+     * low‑level `fetch` call used by all requests created from this client.
+     * It is invoked for every request with the constructed {@link AspiRequest},
+     * and can:
+     *
+     * - inspect or mutate the outgoing request (e.g. inject auth headers),
+     * - inspect the raw {@link Response},
+     * - implement cross‑cutting concerns such as logging, tracing, retries,
+     *   or token refresh, and
+     * - short‑circuit the network call by returning a synthetic {@link Response}.
+     *
+     * Capabilities registered on the {@link Aspi} instance are propagated to every
+     * {@link Request} created via methods like {@link get}, {@link post}, etc.
+     * They are applied in the order they are registered.
+     *
+     * @param capability - The capability factory to install on this client.
+     *
+     * @returns This {@link Aspi} instance for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+     *   .useCapability(({ request }) => ({
+     *     async run(runner) {
+     *       console.log('→', request.path);
+     *       const res = await runner();
+     *       console.log('←', res.status);
+     *       return res;
+     *     },
+     *   }));
+     *
+     * const user = await api.get('/users/1').throwable().json<User>();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): this;
 }
 
 export { Aspi, type AspiConfigBase, AspiError, type AspiPlainResponse, type AspiRequest, type AspiRequestInit, type AspiRequestInitWithoutBodyAndMethod, type AspiResponse, type AspiResultOk, type AspiRetryConfig, type BaseURL, CustomError, type CustomErrorCb, type ErrorCallbacks, type HttpErrorCodes, type HttpErrorStatus, type HttpMethods, type JSONParseError, type Merge, type Prettify, Request, type RequestOptions, type RequestTransformer, result as Result, getHttpErrorStatus, httpErrors, isAspiError, isCustomError };

package/dist/index.d.ts

@@ -295,8 +295,9 @@ interface AspiRequest<T extends AspiRequestInit> {
  */
 type AspiResponse<TData = any, IsError extends boolean = false> = Merge<{
     status: HttpErrorCodes;
-    statusText: HttpErrorStatus;
+    statusLabel: HttpErrorStatus;
     response: Response;
+    statusText: string;
 }, IsError extends true ? {
     responseData: TData;
 } : {
@@ -365,6 +366,72 @@ interface JSONParseError extends CustomError<'jsonParseError', {
 declare const isAspiError: <TReq extends AspiRequestInit>(error: unknown) => error is AspiError<TReq>;
 declare const isCustomError: <Tag extends string, A>(error: unknown) => error is CustomError<Tag, A>;
 
+/**
+ * Arguments passed to a capability factory.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ */
+type CapabilityArgs<T extends AspiRequestInit = AspiRequestInit> = {
+    /**
+     * The fully constructed AspiRequest that will be used to execute `fetch`.
+     *
+     * You can:
+     * - inspect `request.path`, `request.requestInit`, `request.retryConfig`, etc.
+     * - mutate `request.requestInit.headers`, `signal`, or other properties
+     *   before the network call is made.
+     */
+    request: AspiRequest<AspiRequestInit>;
+};
+/**
+ * A capability is a small wrapper around the low-level `fetch` call that can
+ * intercept outgoing requests and incoming responses.
+ *
+ * It is a factory function that receives the current {@link AspiRequest}
+ * and returns an object exposing a single `run` method. The `run` method is
+ * responsible for invoking the provided `runner` (which performs the actual
+ * `fetch`) and may:
+ *
+ * - call `runner()` directly and return its result
+ * - call `runner()` multiple times (e.g. retry, refresh token then retry)
+ * - short‑circuit by *not* calling `runner()` and returning a synthetic
+ *   {@link Response} instead
+ *
+ * Capabilities are composed in the order they are registered via
+ * `Aspi.useCapability`, with each capability wrapping the next one in the
+ * chain.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ *
+ * @example
+ * ```ts
+ * // Simple logging capability
+ * const loggingCapability: Capability = ({ request }) => ({
+ *   async run(runner) {
+ *     console.log('→', request.path, request.requestInit);
+ *     const res = await runner();
+ *     console.log('←', res.status, res.statusText);
+ *     return res;
+ *   },
+ * });
+ *
+ * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+ *   .useCapability(loggingCapability);
+ * ```
+ */
+type Capability<T extends AspiRequestInit = AspiRequestInit> = ({ request, }: CapabilityArgs<T>) => {
+    /**
+     * Executes the next step in the capability chain.
+     *
+     * @param runner - A function that, when called, performs the actual
+     *   network request (or the next capability in the chain) and resolves to
+     *   a {@link Response}.
+     *
+     * @returns A promise resolving to the final {@link Response} that should be
+     *   used by Aspi for this request.
+     */
+    run: (runner: () => Promise<Response>) => Promise<Response>;
+};
+
 type Ok<T> = {
     __tag: 'ok';
     value: T;
@@ -767,7 +834,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     error: {};
 }> {
     #private;
-    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>);
+    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>, capabilities?: Capability[]);
     /**
      * Sets the base URL for the request.
      * @param url The base URL to set
@@ -1081,7 +1148,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      * const qp = new URLSearchParams({ page: '1' });
      * request.setQueryParams(qp);
      */
-    setQueryParams<T extends Record<string, string> | string[][] | string | URLSearchParams>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
+    setQueryParams<T = any>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
         queryParams: T;
     }>>;
     /**
@@ -1440,6 +1507,49 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         retryWhile: ((request: AspiRequest<TRequest>, response: AspiResponse) => boolean | Promise<boolean>) | undefined;
         onRetry: ((request: AspiRequest<TRequest>, response: AspiResponse) => void) | undefined;
     };
+    /**
+     * Registers a capability for this request.
+     *
+     * A capability is a small wrapper around the underlying `fetch` call that can
+     * intercept, inspect, or modify the request/response lifecycle. Each registered
+     * capability receives the constructed {@link AspiRequest} and can wrap the
+     * execution of the network call via its `run` method.
+     *
+     * Capabilities are applied in the order they are registered. For each HTTP
+     * call, the `Request` will:
+     *
+     * 1. Build an {@link AspiRequest} from the current configuration.
+     * 2. Create a runner: `() => fetch(url, requestInit)`.
+     * 3. Pass that runner through each capability in sequence, allowing them to:
+     *    - log or trace requests,
+     *    - implement retry/refresh logic,
+     *    - short‑circuit with synthetic responses, etc.
+     *
+     * @param capability - The capability factory to register. It will be invoked
+     *   for every execution of this request with the current {@link AspiRequest}.
+     *
+     * @returns This {@link Request} instance, enabling fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+     *
+     * const apiWithLogging = api.useCapability(({ request }) => ({
+     *   async run(runner) {
+     *     console.log('→', request.path, request.requestInit);
+     *     const res = await runner();
+     *     console.log('←', res.status, res.statusText);
+     *     return res;
+     *   },
+     * }));
+     *
+     * const result = await apiWithLogging
+     *   .get('/users')
+     *   .withResult()
+     *   .json();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): number;
 }
 
 /**
@@ -1718,7 +1828,7 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
      * api.internalServerError((req, res) => ({ message: 'Server error occurred' }));
      */
     internalServerError<A extends {}>(cb: CustomErrorCb<TRequest, A>): Aspi<TRequest, Prettify<Opts & {
-        error: { [K in keyof Opts["error"] | "internalServerErrorError"]: K extends "internalServerErrorError" ? CustomError<"internalServerErrorError", A> : Opts["error"][K]; };
+        error: { [K in "internalServerError" | keyof Opts["error"]]: K extends "internalServerError" ? CustomError<"internalServerError", A> : Opts["error"][K]; };
     }>>;
     /**
      * Sets the aspi to throw an error if the response status is not successful.
@@ -1743,6 +1853,44 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Registers a capability on this {@link Aspi} instance.
+     *
+     * A capability is a small, pluggable unit that can intercept and wrap the
+     * low‑level `fetch` call used by all requests created from this client.
+     * It is invoked for every request with the constructed {@link AspiRequest},
+     * and can:
+     *
+     * - inspect or mutate the outgoing request (e.g. inject auth headers),
+     * - inspect the raw {@link Response},
+     * - implement cross‑cutting concerns such as logging, tracing, retries,
+     *   or token refresh, and
+     * - short‑circuit the network call by returning a synthetic {@link Response}.
+     *
+     * Capabilities registered on the {@link Aspi} instance are propagated to every
+     * {@link Request} created via methods like {@link get}, {@link post}, etc.
+     * They are applied in the order they are registered.
+     *
+     * @param capability - The capability factory to install on this client.
+     *
+     * @returns This {@link Aspi} instance for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+     *   .useCapability(({ request }) => ({
+     *     async run(runner) {
+     *       console.log('→', request.path);
+     *       const res = await runner();
+     *       console.log('←', res.status);
+     *       return res;
+     *     },
+     *   }));
+     *
+     * const user = await api.get('/users/1').throwable().json<User>();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): this;
 }
 
 export { Aspi, type AspiConfigBase, AspiError, type AspiPlainResponse, type AspiRequest, type AspiRequestInit, type AspiRequestInitWithoutBodyAndMethod, type AspiResponse, type AspiResultOk, type AspiRetryConfig, type BaseURL, CustomError, type CustomErrorCb, type ErrorCallbacks, type HttpErrorCodes, type HttpErrorStatus, type HttpMethods, type JSONParseError, type Merge, type Prettify, Request, type RequestOptions, type RequestTransformer, result as Result, getHttpErrorStatus, httpErrors, isAspiError, isCustomError };

package/dist/index.js

@@ -287,17 +287,19 @@ var Request = class {
   #shouldBeResult = false;
   #bodySchemaIssues = [];
   #throwOnError = false;
-  constructor(method, path, requestOptions) {
+  #capabilities = [];
+  constructor(method, path, requestOptions, capabilities = []) {
     this.#path = path;
     this.#middlewares = requestOptions.middlewares || [];
     this.#localRequestInit = {
       ...requestOptions.requestConfig,
       method
     };
-    this.#retryConfig = requestOptions.retryConfig;
-    this.#customErrorCbs = requestOptions.errorCbs || {};
+    this.#retryConfig = { ...requestOptions?.retryConfig || {} };
+    this.#customErrorCbs = { ...requestOptions?.errorCbs || {} };
     this.#throwOnError = requestOptions.throwOnError || false;
     this.#shouldBeResult = requestOptions.shouldBeResult || false;
+    this.#capabilities = [...capabilities];
   }
   /**
    * Sets the base URL for the request.
@@ -652,7 +654,29 @@ var Request = class {
    * request.setQueryParams(qp);
    */
   setQueryParams(params) {
-    this.#queryParams = new URLSearchParams(params);
+    let qp;
+    if (params instanceof URLSearchParams) {
+      qp = new URLSearchParams(params);
+    } else if (typeof params === "string") {
+      qp = new URLSearchParams(params);
+    } else if (Array.isArray(params)) {
+      qp = new URLSearchParams();
+      for (const entry of params) {
+        if (Array.isArray(entry) && entry.length === 2) {
+          qp.append(String(entry[0]), String(entry[1]));
+        }
+      }
+    } else if (typeof params === "object" && params !== null) {
+      qp = new URLSearchParams();
+      for (const [key, value] of Object.entries(
+        params
+      )) {
+        qp.append(key, String(value));
+      }
+    } else {
+      qp = new URLSearchParams();
+    }
+    this.#queryParams = qp;
     return this;
   }
   /**
@@ -893,11 +917,41 @@ var Request = class {
     return this.#mapResponse(output);
   }
   #url() {
+    if (this.#path.startsWith("http://") || this.#path.startsWith("https://")) {
+      const absolute = new URL(this.#path);
+      if (this.#queryParams) {
+        for (const [k, v] of this.#queryParams.entries()) {
+          absolute.searchParams.append(k, v);
+        }
+      }
+      return absolute.toString();
+    }
     const passedBaseUrl = typeof this.#localRequestInit.baseUrl === "string" ? this.#localRequestInit.baseUrl : this.#localRequestInit.baseUrl.toString();
-    const baseUrl = passedBaseUrl.replace(/\/+$/, "") ?? "";
-    const path = this.#path.replace(/^\/+/, "/");
-    const queryString = this.#queryParams ? `?${this.#queryParams.toString()}` : "";
-    const url = [baseUrl, path, queryString].filter(Boolean).join("");
+    const base = passedBaseUrl.replace(/\/+$/, "");
+    const [rawPathAndQuery, fragment] = this.#path.split("#", 2);
+    const [rawPath, existingQuery] = rawPathAndQuery.split("?", 2);
+    let path = rawPath || "";
+    path = path.replace(/^\/+/, "");
+    path = path.replace(/\/{2,}/g, "/");
+    path = path.replace(/\/+$/, "");
+    if (path) {
+      path = "/" + path.replace(/^\/+/, "");
+    }
+    const qs = new URLSearchParams(existingQuery ?? "");
+    if (this.#queryParams) {
+      for (const [k, v] of this.#queryParams.entries()) {
+        qs.append(k, v);
+      }
+    }
+    const queryString = qs.toString();
+    let url = base + path;
+    if (queryString) {
+      url += `?${queryString}`;
+    }
+    if (fragment) {
+      url += `#${fragment}`;
+    }
+    url = url.replace(/\/+$/, "");
     return url;
   }
   /**
@@ -996,7 +1050,15 @@ var Request = class {
       let responseData = null;
       while (attempts <= retries) {
         try {
-          response = await fetch(url, requestInit);
+          if (this.#capabilities.length > 0) {
+            for (const capability of this.#capabilities) {
+              response = await capability({ request }).run(
+                () => fetch(url, requestInit)
+              );
+            }
+          } else {
+            response = await fetch(url, requestInit);
+          }
           responseData = await responseParser(response);
           if (responseData instanceof Error) {
             return err(responseData);
@@ -1189,8 +1251,9 @@ var Request = class {
     return {
       response,
       status: response.status,
-      statusText: getHttpErrorStatus(response.status),
-      responseData
+      statusLabel: getHttpErrorStatus(response.status),
+      responseData,
+      statusText: response.statusText
     };
   }
   /**
@@ -1255,16 +1318,62 @@ var Request = class {
     const cfg = this.#sanitisedRetryConfig();
     return { ...cfg };
   }
+  /**
+   * Registers a capability for this request.
+   *
+   * A capability is a small wrapper around the underlying `fetch` call that can
+   * intercept, inspect, or modify the request/response lifecycle. Each registered
+   * capability receives the constructed {@link AspiRequest} and can wrap the
+   * execution of the network call via its `run` method.
+   *
+   * Capabilities are applied in the order they are registered. For each HTTP
+   * call, the `Request` will:
+   *
+   * 1. Build an {@link AspiRequest} from the current configuration.
+   * 2. Create a runner: `() => fetch(url, requestInit)`.
+   * 3. Pass that runner through each capability in sequence, allowing them to:
+   *    - log or trace requests,
+   *    - implement retry/refresh logic,
+   *    - short‑circuit with synthetic responses, etc.
+   *
+   * @param capability - The capability factory to register. It will be invoked
+   *   for every execution of this request with the current {@link AspiRequest}.
+   *
+   * @returns This {@link Request} instance, enabling fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+   *
+   * const apiWithLogging = api.useCapability(({ request }) => ({
+   *   async run(runner) {
+   *     console.log('→', request.path, request.requestInit);
+   *     const res = await runner();
+   *     console.log('←', res.status, res.statusText);
+   *     return res;
+   *   },
+   * }));
+   *
+   * const result = await apiWithLogging
+   *   .get('/users')
+   *   .withResult()
+   *   .json();
+   * ```
+   */
+  useCapability(capability) {
+    return this.#capabilities.push(capability);
+  }
 };
 
 // src/aspi.ts
-var Aspi2 = class {
+var Aspi = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
   #customErrorCbs = {};
   #throwOnError = false;
   #shouldBeResult = false;
+  #capabilities = [];
   constructor(config) {
     const { retryConfig, ...requestInit } = config;
     this.#globalRequestInit = requestInit;
@@ -1307,17 +1416,22 @@ var Aspi2 = class {
     return this;
   }
   #createRequest(method, path) {
-    return new Request(method, path, {
-      requestConfig: {
-        ...this.#globalRequestInit,
-        method
+    return new Request(
+      method,
+      path,
+      {
+        requestConfig: {
+          ...this.#globalRequestInit,
+          method
+        },
+        middlewares: this.#middlewares,
+        errorCbs: this.#customErrorCbs,
+        throwOnError: this.#throwOnError,
+        shouldBeResult: this.#shouldBeResult,
+        retryConfig: this.#retryConfig
       },
-      middlewares: this.#middlewares,
-      errorCbs: this.#customErrorCbs,
-      throwOnError: this.#throwOnError,
-      shouldBeResult: this.#shouldBeResult,
-      retryConfig: this.#retryConfig
-    });
+      this.#capabilities
+    );
   }
   /**
    * Makes a GET request to the specified path
@@ -1585,7 +1699,7 @@ var Aspi2 = class {
    * api.internalServerError((req, res) => ({ message: 'Server error occurred' }));
    */
   internalServerError(cb) {
-    return this.error("internalServerErrorError", "INTERNAL_SERVER_ERROR", cb);
+    return this.error("internalServerError", "INTERNAL_SERVER_ERROR", cb);
   }
   /**
    * Sets the aspi to throw an error if the response status is not successful.
@@ -1612,9 +1726,50 @@ var Aspi2 = class {
     this.#throwOnError = false;
     return this;
   }
+  /**
+   * Registers a capability on this {@link Aspi} instance.
+   *
+   * A capability is a small, pluggable unit that can intercept and wrap the
+   * low‑level `fetch` call used by all requests created from this client.
+   * It is invoked for every request with the constructed {@link AspiRequest},
+   * and can:
+   *
+   * - inspect or mutate the outgoing request (e.g. inject auth headers),
+   * - inspect the raw {@link Response},
+   * - implement cross‑cutting concerns such as logging, tracing, retries,
+   *   or token refresh, and
+   * - short‑circuit the network call by returning a synthetic {@link Response}.
+   *
+   * Capabilities registered on the {@link Aspi} instance are propagated to every
+   * {@link Request} created via methods like {@link get}, {@link post}, etc.
+   * They are applied in the order they are registered.
+   *
+   * @param capability - The capability factory to install on this client.
+   *
+   * @returns This {@link Aspi} instance for fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+   *   .useCapability(({ request }) => ({
+   *     async run(runner) {
+   *       console.log('→', request.path);
+   *       const res = await runner();
+   *       console.log('←', res.status);
+   *       return res;
+   *     },
+   *   }));
+   *
+   * const user = await api.get('/users/1').throwable().json<User>();
+   * ```
+   */
+  useCapability(capability) {
+    this.#capabilities.push(capability);
+    return this;
+  }
 };
 export {
-  Aspi2 as Aspi,
+  Aspi,
   AspiError,
   CustomError,
   Request,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aspi",
   "description": "Rest API client for typescript projects with chain of responsibility design pattern.",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "module": "src/index.ts",
   "type": "module",
   "devDependencies": {
@@ -32,17 +32,6 @@
     "url": "git+https://github.com/harshtalks/aspi.git"
   },
   "homepage": "https://github.com/harshtalks/aspi",
-  "scripts": {
-    "ci": "bun run test:run && bun run build && bun run check-format && bun run lint",
-    "format": "prettier --write .",
-    "check-format": "prettier --check .",
-    "build": "tsup",
-    "lint": "tsc",
-    "local-release": "changeset version && changeset publish",
-    "prepublishOnly": "bun run ci",
-    "test": "vitest",
-    "test:run": "vitest run"
-  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -52,5 +41,15 @@
   },
   "files": [
     "dist"
-  ]
-}
+  ],
+  "scripts": {
+    "ci": "bun run test:run && bun run build && bun run check-format && bun run lint",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "build": "tsup",
+    "lint": "tsc",
+    "local-release": "changeset version && changeset publish",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}