aspi 2.0.1 → 2.1.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.

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,
@@ -322,8 +322,8 @@ var Request = class {
       ...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;
   }
@@ -680,7 +680,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 +943,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;
   }
   /**
@@ -1217,8 +1269,9 @@ var Request = class {
     return {
       response,
       status: response.status,
-      statusText: getHttpErrorStatus(response.status),
-      responseData
+      statusLabel: getHttpErrorStatus(response.status),
+      responseData,
+      statusText: response.statusText
     };
   }
   /**
@@ -1286,7 +1339,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi2 = class {
+var Aspi = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1613,7 +1666,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.

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;
 } : {
@@ -1081,7 +1082,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;
     }>>;
     /**
@@ -1718,7 +1719,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.

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;
 } : {
@@ -1081,7 +1082,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;
     }>>;
     /**
@@ -1718,7 +1719,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.

package/dist/index.js

@@ -294,8 +294,8 @@ var Request = class {
       ...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;
   }
@@ -652,7 +652,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 +915,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;
   }
   /**
@@ -1189,8 +1241,9 @@ var Request = class {
     return {
       response,
       status: response.status,
-      statusText: getHttpErrorStatus(response.status),
-      responseData
+      statusLabel: getHttpErrorStatus(response.status),
+      responseData,
+      statusText: response.statusText
     };
   }
   /**
@@ -1258,7 +1311,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi2 = class {
+var Aspi = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1585,7 +1638,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.
@@ -1614,7 +1667,7 @@ var Aspi2 = class {
   }
 };
 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.1.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"
+  }
+}