aspi 2.6.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,
@@ -30,7 +30,7 @@ __export(index_exports, {
   isAspiError: () => isAspiError,
   isCustomError: () => isCustomError,
   isJSONParseError: () => isJSONParseError,
-  isParseError: () => isParseError
+  isSchemaParseError: () => isSchemaParseError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -110,12 +110,12 @@ var isAspiError = (error) => {
 var isCustomError = (error) => {
   return error instanceof CustomError;
 };
-var isParseError = (error) => {
-  return error instanceof CustomError && error.tag === "parseError";
-};
 var isJSONParseError = (error) => {
   return error instanceof CustomError && error.tag === "jsonParseError";
 };
+var isSchemaParseError = (error) => {
+  return error instanceof CustomError && error.tag === "schemaParseError";
+};
 
 // src/result.ts
 var result_exports = {};
@@ -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,8 +1220,20 @@ 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("parseError", this.#bodySchemaIssues));
+      return err(
+        new CustomError("schemaParseError", this.#bodySchemaIssues)
+      );
     }
     const request = this.#request();
     const { retries, retryDelay, retryOn, retryWhile, onRetry } = this.#sanitisedRetryConfig();
@@ -1310,12 +1367,9 @@ 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("parseError", data.issues));
+          return err(new CustomError("schemaParseError", data.issues));
         }
         return ok({
           data: data.value,
@@ -1525,7 +1579,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi = class {
+var Aspi2 = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1885,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.
    *
@@ -1939,5 +2007,5 @@ var Aspi = class {
   isAspiError,
   isCustomError,
   isJSONParseError,
-  isParseError
+  isSchemaParseError
 });

package/dist/index.d.cts

@@ -1,3 +1,64 @@
+/**
+ * Standard Schema is a common interface designed to be implemented by JavaScript and TypeScript schema libraries.
+ * Will support multiple schema validators including Zod, Valibot, and ArkType
+ * https://standardschema.dev/
+ */
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
 /**
  * Standard HTTP /**
  * Common HTTP error status codes with their numeric values.
@@ -364,14 +425,16 @@ interface JSONParseError extends CustomError<'jsonParseError', {
 }> {
 }
 /**
- * Type alias for a schema validation parse error.
- * Emitted when either the request body schema or the response schema fails validation.
+ * Interface representing a schema validation error (body or response).
+ * @interface SchemaParseError
+ * @extends {CustomError<'schemaParseError', ReadonlyArray<StandardSchemaV1.Issue>>}
  */
-type ParseError = CustomError<'parseError', unknown>;
+interface SchemaParseError extends CustomError<'schemaParseError', ReadonlyArray<StandardSchemaV1.Issue>> {
+}
 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>;
-declare const isParseError: (error: unknown) => error is ParseError;
 declare const isJSONParseError: (error: unknown) => error is JSONParseError;
+declare const isSchemaParseError: (error: unknown) => error is SchemaParseError;
 
 /**
  * Arguments passed to a capability factory.
@@ -756,67 +819,6 @@ declare namespace result {
   export { type result_Err as Err, type result_Ok as Ok, type result_Result as Result, result_catchAllErrors as catchAllErrors, result_catchError as catchError, result_catchErrors as catchErrors, result_err as err, result_getErrorOrNull as getErrorOrNull, result_getOrElse as getOrElse, result_getOrNull as getOrNull, result_getOrThrow as getOrThrow, result_getOrThrowWith as getOrThrowWith, result_isErr as isErr, result_isOk as isOk, result_map as map, result_mapErr as mapErr, result_match as match, result_ok as ok, result_pipe as pipe };
 }
 
-/**
- * Standard Schema is a common interface designed to be implemented by JavaScript and TypeScript schema libraries.
- * Will support multiple schema validators including Zod, Valibot, and ArkType
- * https://standardschema.dev/
- */
-/** The Standard Schema interface. */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-    /** The Standard Schema properties. */
-    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
-}
-declare namespace StandardSchemaV1 {
-    /** The Standard Schema properties interface. */
-    interface Props<Input = unknown, Output = Input> {
-        /** The version number of the standard. */
-        readonly version: 1;
-        /** The vendor name of the schema library. */
-        readonly vendor: string;
-        /** Validates unknown input values. */
-        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        /** Inferred types associated with the schema. */
-        readonly types?: Types<Input, Output> | undefined;
-    }
-    /** The result interface of the validate function. */
-    type Result<Output> = SuccessResult<Output> | FailureResult;
-    /** The result interface if validation succeeds. */
-    interface SuccessResult<Output> {
-        /** The typed output value. */
-        readonly value: Output;
-        /** The non-existent issues. */
-        readonly issues?: undefined;
-    }
-    /** The result interface if validation fails. */
-    interface FailureResult {
-        /** The issues of failed validation. */
-        readonly issues: ReadonlyArray<Issue>;
-    }
-    /** The issue interface of the failure output. */
-    interface Issue {
-        /** The error message of the issue. */
-        readonly message: string;
-        /** The path of the issue, if any. */
-        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-    }
-    /** The path segment interface of the issue. */
-    interface PathSegment {
-        /** The key representing a path segment. */
-        readonly key: PropertyKey;
-    }
-    /** The Standard Schema types interface. */
-    interface Types<Input = unknown, Output = Input> {
-        /** The input type of the schema. */
-        readonly input: Input;
-        /** The output type of the schema. */
-        readonly output: Output;
-    }
-    /** Infers the input type of a Standard Schema. */
-    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
-    /** Infers the output type of a Standard Schema. */
-    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
-}
-
 /**
  * A class for building and executing HTTP requests with customizable options and error handling.
  * @template Method The HTTP method type (GET, POST, etc.)
@@ -937,7 +939,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     bodySchema<TSchema extends StandardSchemaV1>(schema: TSchema): Request<Method, TRequest, Omit<Opts, "bodySchema"> & {
         bodySchema: TSchema;
         error: Opts["error"] & {
-            parseError: CustomError<"parseError", StandardSchemaV1.FailureResult["issues"]>;
+            schemaParseError: CustomError<"schemaParseError", StandardSchemaV1.FailureResult["issues"]>;
         };
     }>;
     /**
@@ -1209,7 +1211,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     schema<TSchema extends StandardSchemaV1>(schema: TSchema): Request<Method, TRequest, Merge<Omit<Opts, "schema">, {
         schema: TSchema;
         error: Merge<Opts["error"], {
-            parseError: CustomError<"parseError", StandardSchemaV1.FailureResult["issues"]>;
+            schemaParseError: CustomError<"schemaParseError", StandardSchemaV1.FailureResult["issues"]>;
         }>;
     }>>;
     /**
@@ -1562,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.
      *
@@ -1965,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.
      *
@@ -2005,4 +2062,4 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
     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, type Capability, type CapabilityArgs, CustomError, type CustomErrorCb, type ErrorCallbacks, type HttpErrorCodes, type HttpErrorStatus, type HttpMethods, type JSONParseError, type Merge, type ParseError, type Prettify, Request, type RequestOptions, type RequestTransformer, result as Result, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isParseError };
+export { Aspi, type AspiConfigBase, AspiError, type AspiPlainResponse, type AspiRequest, type AspiRequestInit, type AspiRequestInitWithoutBodyAndMethod, type AspiResponse, type AspiResultOk, type AspiRetryConfig, type BaseURL, type Capability, type CapabilityArgs, 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, type SchemaParseError, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isSchemaParseError };

package/dist/index.d.ts

@@ -1,3 +1,64 @@
+/**
+ * Standard Schema is a common interface designed to be implemented by JavaScript and TypeScript schema libraries.
+ * Will support multiple schema validators including Zod, Valibot, and ArkType
+ * https://standardschema.dev/
+ */
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
 /**
  * Standard HTTP /**
  * Common HTTP error status codes with their numeric values.
@@ -364,14 +425,16 @@ interface JSONParseError extends CustomError<'jsonParseError', {
 }> {
 }
 /**
- * Type alias for a schema validation parse error.
- * Emitted when either the request body schema or the response schema fails validation.
+ * Interface representing a schema validation error (body or response).
+ * @interface SchemaParseError
+ * @extends {CustomError<'schemaParseError', ReadonlyArray<StandardSchemaV1.Issue>>}
  */
-type ParseError = CustomError<'parseError', unknown>;
+interface SchemaParseError extends CustomError<'schemaParseError', ReadonlyArray<StandardSchemaV1.Issue>> {
+}
 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>;
-declare const isParseError: (error: unknown) => error is ParseError;
 declare const isJSONParseError: (error: unknown) => error is JSONParseError;
+declare const isSchemaParseError: (error: unknown) => error is SchemaParseError;
 
 /**
  * Arguments passed to a capability factory.
@@ -756,67 +819,6 @@ declare namespace result {
   export { type result_Err as Err, type result_Ok as Ok, type result_Result as Result, result_catchAllErrors as catchAllErrors, result_catchError as catchError, result_catchErrors as catchErrors, result_err as err, result_getErrorOrNull as getErrorOrNull, result_getOrElse as getOrElse, result_getOrNull as getOrNull, result_getOrThrow as getOrThrow, result_getOrThrowWith as getOrThrowWith, result_isErr as isErr, result_isOk as isOk, result_map as map, result_mapErr as mapErr, result_match as match, result_ok as ok, result_pipe as pipe };
 }
 
-/**
- * Standard Schema is a common interface designed to be implemented by JavaScript and TypeScript schema libraries.
- * Will support multiple schema validators including Zod, Valibot, and ArkType
- * https://standardschema.dev/
- */
-/** The Standard Schema interface. */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-    /** The Standard Schema properties. */
-    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
-}
-declare namespace StandardSchemaV1 {
-    /** The Standard Schema properties interface. */
-    interface Props<Input = unknown, Output = Input> {
-        /** The version number of the standard. */
-        readonly version: 1;
-        /** The vendor name of the schema library. */
-        readonly vendor: string;
-        /** Validates unknown input values. */
-        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        /** Inferred types associated with the schema. */
-        readonly types?: Types<Input, Output> | undefined;
-    }
-    /** The result interface of the validate function. */
-    type Result<Output> = SuccessResult<Output> | FailureResult;
-    /** The result interface if validation succeeds. */
-    interface SuccessResult<Output> {
-        /** The typed output value. */
-        readonly value: Output;
-        /** The non-existent issues. */
-        readonly issues?: undefined;
-    }
-    /** The result interface if validation fails. */
-    interface FailureResult {
-        /** The issues of failed validation. */
-        readonly issues: ReadonlyArray<Issue>;
-    }
-    /** The issue interface of the failure output. */
-    interface Issue {
-        /** The error message of the issue. */
-        readonly message: string;
-        /** The path of the issue, if any. */
-        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-    }
-    /** The path segment interface of the issue. */
-    interface PathSegment {
-        /** The key representing a path segment. */
-        readonly key: PropertyKey;
-    }
-    /** The Standard Schema types interface. */
-    interface Types<Input = unknown, Output = Input> {
-        /** The input type of the schema. */
-        readonly input: Input;
-        /** The output type of the schema. */
-        readonly output: Output;
-    }
-    /** Infers the input type of a Standard Schema. */
-    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
-    /** Infers the output type of a Standard Schema. */
-    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
-}
-
 /**
  * A class for building and executing HTTP requests with customizable options and error handling.
  * @template Method The HTTP method type (GET, POST, etc.)
@@ -937,7 +939,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     bodySchema<TSchema extends StandardSchemaV1>(schema: TSchema): Request<Method, TRequest, Omit<Opts, "bodySchema"> & {
         bodySchema: TSchema;
         error: Opts["error"] & {
-            parseError: CustomError<"parseError", StandardSchemaV1.FailureResult["issues"]>;
+            schemaParseError: CustomError<"schemaParseError", StandardSchemaV1.FailureResult["issues"]>;
         };
     }>;
     /**
@@ -1209,7 +1211,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     schema<TSchema extends StandardSchemaV1>(schema: TSchema): Request<Method, TRequest, Merge<Omit<Opts, "schema">, {
         schema: TSchema;
         error: Merge<Opts["error"], {
-            parseError: CustomError<"parseError", StandardSchemaV1.FailureResult["issues"]>;
+            schemaParseError: CustomError<"schemaParseError", StandardSchemaV1.FailureResult["issues"]>;
         }>;
     }>>;
     /**
@@ -1562,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.
      *
@@ -1965,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.
      *
@@ -2005,4 +2062,4 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
     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, type Capability, type CapabilityArgs, CustomError, type CustomErrorCb, type ErrorCallbacks, type HttpErrorCodes, type HttpErrorStatus, type HttpMethods, type JSONParseError, type Merge, type ParseError, type Prettify, Request, type RequestOptions, type RequestTransformer, result as Result, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isParseError };
+export { Aspi, type AspiConfigBase, AspiError, type AspiPlainResponse, type AspiRequest, type AspiRequestInit, type AspiRequestInitWithoutBodyAndMethod, type AspiResponse, type AspiResultOk, type AspiRetryConfig, type BaseURL, type Capability, type CapabilityArgs, 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, type SchemaParseError, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isSchemaParseError };

package/dist/index.js

@@ -80,12 +80,12 @@ var isAspiError = (error) => {
 var isCustomError = (error) => {
   return error instanceof CustomError;
 };
-var isParseError = (error) => {
-  return error instanceof CustomError && error.tag === "parseError";
-};
 var isJSONParseError = (error) => {
   return error instanceof CustomError && error.tag === "jsonParseError";
 };
+var isSchemaParseError = (error) => {
+  return error instanceof CustomError && error.tag === "schemaParseError";
+};
 
 // src/result.ts
 var result_exports = {};
@@ -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,8 +1190,20 @@ 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("parseError", this.#bodySchemaIssues));
+      return err(
+        new CustomError("schemaParseError", this.#bodySchemaIssues)
+      );
     }
     const request = this.#request();
     const { retries, retryDelay, retryOn, retryWhile, onRetry } = this.#sanitisedRetryConfig();
@@ -1280,12 +1337,9 @@ 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("parseError", data.issues));
+          return err(new CustomError("schemaParseError", data.issues));
         }
         return ok({
           data: data.value,
@@ -1495,7 +1549,7 @@ var Request = class {
 };
 
 // src/aspi.ts
-var Aspi = class {
+var Aspi2 = class {
   #globalRequestInit;
   #middlewares = [];
   #retryConfig;
@@ -1855,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.
    *
@@ -1898,7 +1966,7 @@ var Aspi = class {
   }
 };
 export {
-  Aspi,
+  Aspi2 as Aspi,
   AspiError,
   CustomError,
   Request,
@@ -1908,5 +1976,5 @@ export {
   isAspiError,
   isCustomError,
   isJSONParseError,
-  isParseError
+  isSchemaParseError
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aspi",
   "description": "Rest API client for typescript projects with chain of responsibility design pattern.",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "module": "src/index.ts",
   "type": "module",
   "devDependencies": {