aspi 2.7.0 → 2.9.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, request body, or query params failed schema validation (when `.schema()`, `.bodySchema()`, or `.querySchema()` 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
@@ -250,6 +250,39 @@ console.log(api.get('/todos').setQueryParams({ page: '2' }).url());
 // → https://api.example.com/todos?page=2
 ```
 
+#### Query schema validation
+
+Just like request bodies, query parameters can be validated with `.querySchema()`. The schema transforms the input and `setQueryParams()` is typed to accept only the schema's input shape.
+
+```ts
+import { z } from 'zod';
+
+const ListTodosQuery = z.object({
+  page: z.number().default(1),
+  limit: z.number().default(10),
+  sort: z.enum(['asc', 'desc']).default('asc'),
+});
+
+const result = await api
+  .get('/todos')
+  .querySchema(ListTodosQuery)
+  .setQueryParams({ page: 1, limit: 20 })
+  .withResult()
+  .json();
+
+// If validation fails, error.tag === 'schemaParseError' and no network call is made
+Result.match(result, {
+  onOk: ({ data }) => console.log(data),
+  onErr: (err) => {
+    if (err.tag === 'schemaParseError') {
+      console.error('Invalid query params:', err.data);
+    }
+  },
+});
+```
+
+If the schema transforms values (e.g. applying defaults or coercion), the transformed output is what gets serialized into the URL. Async schema validators are also supported.
+
 ### Headers
 
 ```ts
@@ -309,6 +342,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,13 +358,15 @@ 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
     }
   },
 });
 ```
 
+> `.querySchema()` and `.bodySchema()` work the same way — they validate at the edge of the request builder and short-circuit the network call on failure, producing a `schemaParseError` in the error union.
+
 ---
 
 ## Middleware
@@ -530,9 +567,10 @@ 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.
+Per-request methods (`api.get('/…').setQueryParams(…)`, `.schema(…)`, `.querySchema(…)`, `.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,12 @@ var Request = class {
   #timeoutMs;
   #shouldBeResult = false;
   #bodySchemaIssues = [];
+  #bodySchemaAsyncResult = null;
+  #bodySchemaAsyncBody = null;
+  #querySchema = null;
+  #querySchemaIssues = [];
+  #querySchemaAsyncResult = null;
+  #querySchemaAsyncParams = null;
   #throwOnError = false;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
@@ -478,9 +484,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);
@@ -677,6 +683,26 @@ var Request = class {
     };
     return this;
   }
+  /**
+   * Sets a validation schema for the query parameters using a StandardSchemaV1 schema.
+   * @template TSchema Type parameter extending StandardSchemaV1
+   * @param schema The schema to validate query parameters against
+   * @returns The request instance for chaining with updated error type
+   * @example
+   * const querySchema = z.object({
+   *   page: z.number(),
+   *   limit: z.number()
+   * });
+   *
+   * const request = new Request('/users', config);
+   * request
+   *   .querySchema(querySchema)
+   *   .setQueryParams({ page: 1, limit: 10 });
+   */
+  querySchema(schema) {
+    this.#querySchema = schema;
+    return this;
+  }
   /**
    * Sets the query parameters for the request URL.
    *
@@ -711,29 +737,19 @@ var Request = class {
    * request.setQueryParams(qp);
    */
   setQueryParams(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));
+    if (this.#querySchema) {
+      const data = this.#querySchema["~standard"].validate(params);
+      if (data instanceof Promise) {
+        this.#querySchemaAsyncResult = data;
+        this.#querySchemaAsyncParams = params;
+      } else if (data.issues) {
+        this.#querySchemaIssues = data.issues;
+      } else {
+        this.#queryParams = this.#valueToQueryParams(data.value);
       }
     } else {
-      qp = new URLSearchParams();
+      this.#queryParams = this.#valueToQueryParams(params);
     }
-    this.#queryParams = qp;
     return this;
   }
   /**
@@ -1059,6 +1075,33 @@ var Request = class {
     );
     return this.#mapResponse(output);
   }
+  #valueToQueryParams(value) {
+    if (value instanceof URLSearchParams) {
+      return new URLSearchParams(value);
+    }
+    if (typeof value === "string") {
+      return new URLSearchParams(value);
+    }
+    if (Array.isArray(value)) {
+      const qp = new URLSearchParams();
+      for (const entry of value) {
+        if (Array.isArray(entry) && entry.length === 2) {
+          qp.append(String(entry[0]), String(entry[1]));
+        }
+      }
+      return qp;
+    }
+    if (typeof value === "object" && value !== null) {
+      const qp = new URLSearchParams();
+      for (const [key, val] of Object.entries(
+        value
+      )) {
+        qp.append(key, String(val));
+      }
+      return qp;
+    }
+    return new URLSearchParams();
+  }
   #url() {
     if (this.#path.startsWith("http://") || this.#path.startsWith("https://")) {
       const absolute = new URL(this.#path);
@@ -1158,6 +1201,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,11 +1261,36 @@ 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)
       );
     }
+    if (this.#querySchemaAsyncResult) {
+      const data = await this.#querySchemaAsyncResult;
+      if (data.issues) {
+        this.#querySchemaIssues = data.issues;
+      } else {
+        this.#queryParams = this.#valueToQueryParams(data.value);
+      }
+      this.#querySchemaAsyncResult = null;
+      this.#querySchemaAsyncParams = null;
+    }
+    if (this.#querySchemaIssues.length) {
+      return err(
+        new CustomError("schemaParseError", this.#querySchemaIssues)
+      );
+    }
     const request = this.#request();
     const { retries, retryDelay, retryOn, retryWhile, onRetry } = this.#sanitisedRetryConfig();
     try {
@@ -1312,10 +1423,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 +1635,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi = class {
+var Aspi2 = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1887,6 +1995,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

@@ -1139,6 +1139,28 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     error<Tag extends string, A extends {}>(tag: Tag, status: HttpErrorStatus, cb: CustomErrorCb<TRequest, A>): Request<Method, TRequest, Merge<Omit<Opts, "error">, {
         error: { [K in Tag | keyof Opts["error"]]: K extends Tag ? CustomError<Tag, A> : Opts["error"][K]; };
     }>>;
+    /**
+     * Sets a validation schema for the query parameters using a StandardSchemaV1 schema.
+     * @template TSchema Type parameter extending StandardSchemaV1
+     * @param schema The schema to validate query parameters against
+     * @returns The request instance for chaining with updated error type
+     * @example
+     * const querySchema = z.object({
+     *   page: z.number(),
+     *   limit: z.number()
+     * });
+     *
+     * const request = new Request('/users', config);
+     * request
+     *   .querySchema(querySchema)
+     *   .setQueryParams({ page: 1, limit: 10 });
+     */
+    querySchema<TSchema extends StandardSchemaV1>(schema: TSchema): Request<Method, TRequest, Omit<Opts, "querySchema"> & {
+        querySchema: TSchema;
+        error: Opts["error"] & {
+            schemaParseError: CustomError<"schemaParseError", StandardSchemaV1.FailureResult["issues"]>;
+        };
+    }>;
     /**
      * Sets the query parameters for the request URL.
      *
@@ -1172,7 +1194,9 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      * const qp = new URLSearchParams({ page: '1' });
      * request.setQueryParams(qp);
      */
-    setQueryParams<T = any>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
+    setQueryParams<T extends Opts extends {
+        querySchema: infer S extends StandardSchemaV1;
+    } ? StandardSchemaV1.InferInput<S> : any>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
         queryParams: T;
     }>>;
     /**
@@ -1564,6 +1588,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 +2033,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

@@ -1139,6 +1139,28 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     error<Tag extends string, A extends {}>(tag: Tag, status: HttpErrorStatus, cb: CustomErrorCb<TRequest, A>): Request<Method, TRequest, Merge<Omit<Opts, "error">, {
         error: { [K in Tag | keyof Opts["error"]]: K extends Tag ? CustomError<Tag, A> : Opts["error"][K]; };
     }>>;
+    /**
+     * Sets a validation schema for the query parameters using a StandardSchemaV1 schema.
+     * @template TSchema Type parameter extending StandardSchemaV1
+     * @param schema The schema to validate query parameters against
+     * @returns The request instance for chaining with updated error type
+     * @example
+     * const querySchema = z.object({
+     *   page: z.number(),
+     *   limit: z.number()
+     * });
+     *
+     * const request = new Request('/users', config);
+     * request
+     *   .querySchema(querySchema)
+     *   .setQueryParams({ page: 1, limit: 10 });
+     */
+    querySchema<TSchema extends StandardSchemaV1>(schema: TSchema): Request<Method, TRequest, Omit<Opts, "querySchema"> & {
+        querySchema: TSchema;
+        error: Opts["error"] & {
+            schemaParseError: CustomError<"schemaParseError", StandardSchemaV1.FailureResult["issues"]>;
+        };
+    }>;
     /**
      * Sets the query parameters for the request URL.
      *
@@ -1172,7 +1194,9 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      * const qp = new URLSearchParams({ page: '1' });
      * request.setQueryParams(qp);
      */
-    setQueryParams<T = any>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
+    setQueryParams<T extends Opts extends {
+        querySchema: infer S extends StandardSchemaV1;
+    } ? StandardSchemaV1.InferInput<S> : any>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
         queryParams: T;
     }>>;
     /**
@@ -1564,6 +1588,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 +2033,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,12 @@ var Request = class {
   #timeoutMs;
   #shouldBeResult = false;
   #bodySchemaIssues = [];
+  #bodySchemaAsyncResult = null;
+  #bodySchemaAsyncBody = null;
+  #querySchema = null;
+  #querySchemaIssues = [];
+  #querySchemaAsyncResult = null;
+  #querySchemaAsyncParams = null;
   #throwOnError = false;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
@@ -448,9 +454,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);
@@ -647,6 +653,26 @@ var Request = class {
     };
     return this;
   }
+  /**
+   * Sets a validation schema for the query parameters using a StandardSchemaV1 schema.
+   * @template TSchema Type parameter extending StandardSchemaV1
+   * @param schema The schema to validate query parameters against
+   * @returns The request instance for chaining with updated error type
+   * @example
+   * const querySchema = z.object({
+   *   page: z.number(),
+   *   limit: z.number()
+   * });
+   *
+   * const request = new Request('/users', config);
+   * request
+   *   .querySchema(querySchema)
+   *   .setQueryParams({ page: 1, limit: 10 });
+   */
+  querySchema(schema) {
+    this.#querySchema = schema;
+    return this;
+  }
   /**
    * Sets the query parameters for the request URL.
    *
@@ -681,29 +707,19 @@ var Request = class {
    * request.setQueryParams(qp);
    */
   setQueryParams(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));
+    if (this.#querySchema) {
+      const data = this.#querySchema["~standard"].validate(params);
+      if (data instanceof Promise) {
+        this.#querySchemaAsyncResult = data;
+        this.#querySchemaAsyncParams = params;
+      } else if (data.issues) {
+        this.#querySchemaIssues = data.issues;
+      } else {
+        this.#queryParams = this.#valueToQueryParams(data.value);
       }
     } else {
-      qp = new URLSearchParams();
+      this.#queryParams = this.#valueToQueryParams(params);
     }
-    this.#queryParams = qp;
     return this;
   }
   /**
@@ -1029,6 +1045,33 @@ var Request = class {
     );
     return this.#mapResponse(output);
   }
+  #valueToQueryParams(value) {
+    if (value instanceof URLSearchParams) {
+      return new URLSearchParams(value);
+    }
+    if (typeof value === "string") {
+      return new URLSearchParams(value);
+    }
+    if (Array.isArray(value)) {
+      const qp = new URLSearchParams();
+      for (const entry of value) {
+        if (Array.isArray(entry) && entry.length === 2) {
+          qp.append(String(entry[0]), String(entry[1]));
+        }
+      }
+      return qp;
+    }
+    if (typeof value === "object" && value !== null) {
+      const qp = new URLSearchParams();
+      for (const [key, val] of Object.entries(
+        value
+      )) {
+        qp.append(key, String(val));
+      }
+      return qp;
+    }
+    return new URLSearchParams();
+  }
   #url() {
     if (this.#path.startsWith("http://") || this.#path.startsWith("https://")) {
       const absolute = new URL(this.#path);
@@ -1128,6 +1171,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,11 +1231,36 @@ 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)
       );
     }
+    if (this.#querySchemaAsyncResult) {
+      const data = await this.#querySchemaAsyncResult;
+      if (data.issues) {
+        this.#querySchemaIssues = data.issues;
+      } else {
+        this.#queryParams = this.#valueToQueryParams(data.value);
+      }
+      this.#querySchemaAsyncResult = null;
+      this.#querySchemaAsyncParams = null;
+    }
+    if (this.#querySchemaIssues.length) {
+      return err(
+        new CustomError("schemaParseError", this.#querySchemaIssues)
+      );
+    }
     const request = this.#request();
     const { retries, retryDelay, retryOn, retryWhile, onRetry } = this.#sanitisedRetryConfig();
     try {
@@ -1282,10 +1393,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 +1605,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi = class {
+var Aspi2 = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1857,6 +1965,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 +2022,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.9.0",
   "module": "src/index.ts",
   "type": "module",
   "devDependencies": {