aspi 2.7.0 → 2.8.0

package/README.md

@@ -12,7 +12,7 @@ Zero runtime dependencies. Three response modes. Full error-union types.
 ## Features
 
 - **Zero dependencies** — thin wrapper around the platform `fetch` API
-- **Three response modes** — tuple `[data, error]`, `Result` monad, or `throwable` (your choice per call)
+- **Three response modes** — tuple `[data, error]`, `Result` monad, or `throwable` (your choice per call, plus explicit `.withTuple()` to reset)
 - **Typed error unions** — every error variant is tagged and narrowable at compile time
 - **Custom error mapping** — map any HTTP status code to a structured, typed error object
 - **Retry with back-off** — fixed or dynamic delay, status-code filtering, custom predicates
@@ -65,7 +65,7 @@ if (data) console.log(data.title);
 
 ## Response modes
 
-Every request can be consumed in one of three modes. Switch mode by calling `.withResult()` or `.throwable()` before the body-parser method.
+Every request can be consumed in one of three modes. Switch mode by calling `.withResult()`, `.throwable()`, or `.withTuple()` before the body-parser method.
 
 ### 1. Tuple mode (default)
 
@@ -106,7 +106,7 @@ try {
 }
 ```
 
-> `throwable()` and `withResult()` are mutually exclusive — the **last one called wins**.
+> `throwable()`, `withResult()`, and `withTuple()` are mutually exclusive — the **last one called wins**. Use `.withTuple()` to explicitly reset back to the default tuple mode after a previous `.withResult()` or `.throwable()`.
 
 ---
 
@@ -116,12 +116,12 @@ try {
 
 Every response mode surfaces the same tagged error variants:
 
-| Tag              | When                                                         |
-| ---------------- | ------------------------------------------------------------ |
-| `aspiError`      | Any non-2xx response with no matching custom handler         |
-| `jsonParseError` | Response body could not be parsed as JSON                    |
-| `parseError`     | Response failed schema validation (when `.schema()` is used) |
-| _custom_         | Any tag you define via `.error()` or a convenience shortcut  |
+| Tag                | When                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| `aspiError`        | Any non-2xx response with no matching custom handler                                              |
+| `jsonParseError`   | Response body could not be parsed as JSON                                                         |
+| `schemaParseError` | Response (or request body) failed schema validation (when `.schema()` or `.bodySchema()` is used) |
+| _custom_           | Any tag you define via `.error()` or a convenience shortcut                                       |
 
 ### Custom error mapping
 
@@ -228,7 +228,7 @@ const [data, error] = await api
   .bodyJson({ name: 'Alice', email: 'alice@example.com' })
   .json<User>();
 
-// If bodyJson fails validation, error.tag === 'parseError'
+// If bodyJson fails validation, error.tag === 'schemaParseError'
 ```
 
 ### Query parameters
@@ -309,6 +309,8 @@ Aspi integrates with any library that implements the [StandardSchemaV1](https://
 
 Attach a schema with `.schema()` before the body-parser. The inferred output type is used automatically — you don't need to pass a generic.
 
+Aspi supports both **synchronous and asynchronous** `validate` implementations, so schema libraries that return `Promise<Result>` work out of the box.
+
 ```ts
 import { z } from 'zod';
 
@@ -323,7 +325,7 @@ const result = await api.get('/todos/1').withResult().schema(TodoSchema).json();
 Result.match(result, {
   onOk: ({ data }) => console.log(data.title), // data: { id: number; title: string; completed: boolean }
   onErr: (err) => {
-    if (err.tag === 'parseError') {
+    if (err.tag === 'schemaParseError') {
       console.error('Validation failed:', err.data); // StandardSchemaV1 issue list
     }
   },
@@ -530,6 +532,7 @@ These methods are available on the `Aspi` instance and affect all requests creat
 | `useCapability(cap)`      | Register a capability                        |
 | `withResult()`            | Switch all requests to Result mode           |
 | `throwable()`             | Switch all requests to throwable mode        |
+| `withTuple()`             | Switch all requests back to tuple mode       |
 | `.error(tag, status, cb)` | Map an HTTP status to a typed error          |
 
 Per-request methods (`api.get('/…').setQueryParams(…)`, `.schema(…)`, `.bodyJson(…)`, etc.) override the global config for that call only.

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: () => Aspi,
+  Aspi: () => Aspi2,
   AspiError: () => AspiError,
   CustomError: () => CustomError,
   Request: () => Request,
@@ -325,6 +325,8 @@ var Request = class {
   #timeoutMs;
   #shouldBeResult = false;
   #bodySchemaIssues = [];
+  #bodySchemaAsyncResult = null;
+  #bodySchemaAsyncBody = null;
   #throwOnError = false;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
@@ -478,9 +480,9 @@ var Request = class {
     if (this.#bodySchema) {
       const data = this.#bodySchema["~standard"].validate(body);
       if (data instanceof Promise) {
-        throw new Error("Schema validation should not return a promise");
-      }
-      if (data.issues) {
+        this.#bodySchemaAsyncResult = data;
+        this.#bodySchemaAsyncBody = body;
+      } else if (data.issues) {
         this.#bodySchemaIssues = data.issues;
       } else {
         this.#localRequestInit.body = JSON.stringify(data.value);
@@ -1158,6 +1160,49 @@ var Request = class {
     this.#shouldBeResult = true;
     return this;
   }
+  /**
+   * Switches the request into **tuple** mode (the default).
+   *
+   * In tuple mode the response helpers (`json`, `text`, `blob`, …) resolve to a
+   * tuple `[value, error]` where exactly one element is non‑null. This is useful
+   * when you want an explicit opt‑in method to reset from `withResult()` or
+   * `throwable()` back to the default tuple behaviour.
+   *
+   * Calling `withTuple` disables both Result mode and throwable mode.
+   *
+   * @returns {Request<
+   *   Method,
+   *   TRequest,
+   *   Merge<
+   *     Omit<Opts, 'withResult' | 'throwable'>,
+   *     {
+   *       withResult: false;
+   *       throwable: false;
+   *     }
+   *   >
+   * >} The same {@link Request} instance, now typed with `withResult: false` and
+   * `throwable: false` for fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const request = new Request('/users', config);
+   *
+   * const [user, err] = await request
+   *   .withTuple() // explicitly use tuple mode
+   *   .json<User>();
+   *
+   * if (err) {
+   *   console.error(err);
+   * } else {
+   *   console.log(user);
+   * }
+   * ```
+   */
+  withTuple() {
+    this.#throwOnError = false;
+    this.#shouldBeResult = false;
+    return this;
+  }
   #mapResponse(value) {
     if (this.#shouldBeResult) {
       return value;
@@ -1175,6 +1220,16 @@ var Request = class {
     return response.ok || response.status >= 300 && response.status < 400;
   }
   async #makeRequest(responseParser, isJson = false) {
+    if (this.#bodySchemaAsyncResult) {
+      const data = await this.#bodySchemaAsyncResult;
+      if (data.issues) {
+        this.#bodySchemaIssues = data.issues;
+      } else {
+        this.#localRequestInit.body = JSON.stringify(data.value);
+      }
+      this.#bodySchemaAsyncResult = null;
+      this.#bodySchemaAsyncBody = null;
+    }
     if (this.#bodySchemaIssues.length) {
       return err(
         new CustomError("schemaParseError", this.#bodySchemaIssues)
@@ -1312,10 +1367,7 @@ var Request = class {
         );
       }
       if (isJson && this.#schema) {
-        const data = this.#schema["~standard"].validate(responseData);
-        if (data instanceof Promise) {
-          throw new Error("Schema validation should not return a promise");
-        }
+        const data = await this.#schema["~standard"].validate(responseData);
         if (data.issues) {
           return err(new CustomError("schemaParseError", data.issues));
         }
@@ -1527,7 +1579,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi = class {
+var Aspi2 = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1887,6 +1939,20 @@ var Aspi = class {
     this.#throwOnError = false;
     return this;
   }
+  /**
+   * Configures all subsequent requests to return the default tuple `[value, error]`.
+   *
+   * This is the default behaviour, but `withTuple()` is provided as an explicit
+   * reset when you have previously called {@link withResult} or {@link throwable}
+   * on the {@link Aspi} instance.
+   *
+   * @returns The Aspi instance with tuple handling enabled.
+   */
+  withTuple() {
+    this.#shouldBeResult = false;
+    this.#throwOnError = false;
+    return this;
+  }
   /**
    * Registers a capability on this {@link Aspi} instance.
    *

package/dist/index.d.cts

@@ -1564,6 +1564,48 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Switches the request into **tuple** mode (the default).
+     *
+     * In tuple mode the response helpers (`json`, `text`, `blob`, …) resolve to a
+     * tuple `[value, error]` where exactly one element is non‑null. This is useful
+     * when you want an explicit opt‑in method to reset from `withResult()` or
+     * `throwable()` back to the default tuple behaviour.
+     *
+     * Calling `withTuple` disables both Result mode and throwable mode.
+     *
+     * @returns {Request<
+     *   Method,
+     *   TRequest,
+     *   Merge<
+     *     Omit<Opts, 'withResult' | 'throwable'>,
+     *     {
+     *       withResult: false;
+     *       throwable: false;
+     *     }
+     *   >
+     * >} The same {@link Request} instance, now typed with `withResult: false` and
+     * `throwable: false` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const request = new Request('/users', config);
+     *
+     * const [user, err] = await request
+     *   .withTuple() // explicitly use tuple mode
+     *   .json<User>();
+     *
+     * if (err) {
+     *   console.error(err);
+     * } else {
+     *   console.log(user);
+     * }
+     * ```
+     */
+    withTuple(): Request<Method, TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
+        withResult: false;
+        throwable: false;
+    }>>;
     /**
      * Returns the underlying {@link AspiRequest} object that will be used for the fetch call.
      *
@@ -1967,6 +2009,19 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Configures all subsequent requests to return the default tuple `[value, error]`.
+     *
+     * This is the default behaviour, but `withTuple()` is provided as an explicit
+     * reset when you have previously called {@link withResult} or {@link throwable}
+     * on the {@link Aspi} instance.
+     *
+     * @returns The Aspi instance with tuple handling enabled.
+     */
+    withTuple(): Aspi<TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
+        withResult: false;
+        throwable: false;
+    }>>;
     /**
      * Registers a capability on this {@link Aspi} instance.
      *

package/dist/index.d.ts

@@ -1564,6 +1564,48 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Switches the request into **tuple** mode (the default).
+     *
+     * In tuple mode the response helpers (`json`, `text`, `blob`, …) resolve to a
+     * tuple `[value, error]` where exactly one element is non‑null. This is useful
+     * when you want an explicit opt‑in method to reset from `withResult()` or
+     * `throwable()` back to the default tuple behaviour.
+     *
+     * Calling `withTuple` disables both Result mode and throwable mode.
+     *
+     * @returns {Request<
+     *   Method,
+     *   TRequest,
+     *   Merge<
+     *     Omit<Opts, 'withResult' | 'throwable'>,
+     *     {
+     *       withResult: false;
+     *       throwable: false;
+     *     }
+     *   >
+     * >} The same {@link Request} instance, now typed with `withResult: false` and
+     * `throwable: false` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const request = new Request('/users', config);
+     *
+     * const [user, err] = await request
+     *   .withTuple() // explicitly use tuple mode
+     *   .json<User>();
+     *
+     * if (err) {
+     *   console.error(err);
+     * } else {
+     *   console.log(user);
+     * }
+     * ```
+     */
+    withTuple(): Request<Method, TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
+        withResult: false;
+        throwable: false;
+    }>>;
     /**
      * Returns the underlying {@link AspiRequest} object that will be used for the fetch call.
      *
@@ -1967,6 +2009,19 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Configures all subsequent requests to return the default tuple `[value, error]`.
+     *
+     * This is the default behaviour, but `withTuple()` is provided as an explicit
+     * reset when you have previously called {@link withResult} or {@link throwable}
+     * on the {@link Aspi} instance.
+     *
+     * @returns The Aspi instance with tuple handling enabled.
+     */
+    withTuple(): Aspi<TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
+        withResult: false;
+        throwable: false;
+    }>>;
     /**
      * Registers a capability on this {@link Aspi} instance.
      *

package/dist/index.js

@@ -295,6 +295,8 @@ var Request = class {
   #timeoutMs;
   #shouldBeResult = false;
   #bodySchemaIssues = [];
+  #bodySchemaAsyncResult = null;
+  #bodySchemaAsyncBody = null;
   #throwOnError = false;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
@@ -448,9 +450,9 @@ var Request = class {
     if (this.#bodySchema) {
       const data = this.#bodySchema["~standard"].validate(body);
       if (data instanceof Promise) {
-        throw new Error("Schema validation should not return a promise");
-      }
-      if (data.issues) {
+        this.#bodySchemaAsyncResult = data;
+        this.#bodySchemaAsyncBody = body;
+      } else if (data.issues) {
         this.#bodySchemaIssues = data.issues;
       } else {
         this.#localRequestInit.body = JSON.stringify(data.value);
@@ -1128,6 +1130,49 @@ var Request = class {
     this.#shouldBeResult = true;
     return this;
   }
+  /**
+   * Switches the request into **tuple** mode (the default).
+   *
+   * In tuple mode the response helpers (`json`, `text`, `blob`, …) resolve to a
+   * tuple `[value, error]` where exactly one element is non‑null. This is useful
+   * when you want an explicit opt‑in method to reset from `withResult()` or
+   * `throwable()` back to the default tuple behaviour.
+   *
+   * Calling `withTuple` disables both Result mode and throwable mode.
+   *
+   * @returns {Request<
+   *   Method,
+   *   TRequest,
+   *   Merge<
+   *     Omit<Opts, 'withResult' | 'throwable'>,
+   *     {
+   *       withResult: false;
+   *       throwable: false;
+   *     }
+   *   >
+   * >} The same {@link Request} instance, now typed with `withResult: false` and
+   * `throwable: false` for fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const request = new Request('/users', config);
+   *
+   * const [user, err] = await request
+   *   .withTuple() // explicitly use tuple mode
+   *   .json<User>();
+   *
+   * if (err) {
+   *   console.error(err);
+   * } else {
+   *   console.log(user);
+   * }
+   * ```
+   */
+  withTuple() {
+    this.#throwOnError = false;
+    this.#shouldBeResult = false;
+    return this;
+  }
   #mapResponse(value) {
     if (this.#shouldBeResult) {
       return value;
@@ -1145,6 +1190,16 @@ var Request = class {
     return response.ok || response.status >= 300 && response.status < 400;
   }
   async #makeRequest(responseParser, isJson = false) {
+    if (this.#bodySchemaAsyncResult) {
+      const data = await this.#bodySchemaAsyncResult;
+      if (data.issues) {
+        this.#bodySchemaIssues = data.issues;
+      } else {
+        this.#localRequestInit.body = JSON.stringify(data.value);
+      }
+      this.#bodySchemaAsyncResult = null;
+      this.#bodySchemaAsyncBody = null;
+    }
     if (this.#bodySchemaIssues.length) {
       return err(
         new CustomError("schemaParseError", this.#bodySchemaIssues)
@@ -1282,10 +1337,7 @@ var Request = class {
         );
       }
       if (isJson && this.#schema) {
-        const data = this.#schema["~standard"].validate(responseData);
-        if (data instanceof Promise) {
-          throw new Error("Schema validation should not return a promise");
-        }
+        const data = await this.#schema["~standard"].validate(responseData);
         if (data.issues) {
           return err(new CustomError("schemaParseError", data.issues));
         }
@@ -1497,7 +1549,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi = class {
+var Aspi2 = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1857,6 +1909,20 @@ var Aspi = class {
     this.#throwOnError = false;
     return this;
   }
+  /**
+   * Configures all subsequent requests to return the default tuple `[value, error]`.
+   *
+   * This is the default behaviour, but `withTuple()` is provided as an explicit
+   * reset when you have previously called {@link withResult} or {@link throwable}
+   * on the {@link Aspi} instance.
+   *
+   * @returns The Aspi instance with tuple handling enabled.
+   */
+  withTuple() {
+    this.#shouldBeResult = false;
+    this.#throwOnError = false;
+    return this;
+  }
   /**
    * Registers a capability on this {@link Aspi} instance.
    *
@@ -1900,7 +1966,7 @@ var Aspi = class {
   }
 };
 export {
-  Aspi,
+  Aspi2 as 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.7.0",
+  "version": "2.8.0",
   "module": "src/index.ts",
   "type": "module",
   "devDependencies": {