aspi 2.8.0 → 2.9.1

package/README.md

@@ -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                                                         |
-| `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                                       |
+| 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
 
@@ -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
@@ -332,6 +365,8 @@ Result.match(result, {
 });
 ```
 
+> `.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
@@ -535,7 +570,7 @@ These methods are available on the `Aspi` instance and affect all requests creat
 | `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

@@ -327,6 +327,10 @@ var Request = class {
   #bodySchemaIssues = [];
   #bodySchemaAsyncResult = null;
   #bodySchemaAsyncBody = null;
+  #querySchema = null;
+  #querySchemaIssues = [];
+  #querySchemaAsyncResult = null;
+  #querySchemaAsyncParams = null;
   #throwOnError = false;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
@@ -679,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.
    *
@@ -713,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;
   }
   /**
@@ -1061,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);
@@ -1235,6 +1276,21 @@ var Request = class {
         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 {

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;
     }>>;
     /**

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;
     }>>;
     /**

package/dist/index.js

@@ -297,6 +297,10 @@ var Request = class {
   #bodySchemaIssues = [];
   #bodySchemaAsyncResult = null;
   #bodySchemaAsyncBody = null;
+  #querySchema = null;
+  #querySchemaIssues = [];
+  #querySchemaAsyncResult = null;
+  #querySchemaAsyncParams = null;
   #throwOnError = false;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
@@ -649,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.
    *
@@ -683,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;
   }
   /**
@@ -1031,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);
@@ -1205,6 +1246,21 @@ var Request = class {
         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 {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aspi",
   "description": "Rest API client for typescript projects with chain of responsibility design pattern.",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "module": "src/index.ts",
   "type": "module",
   "devDependencies": {
@@ -13,7 +13,7 @@
     "zod": "^3.24.1"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": ">=5"
   },
   "author": {
     "email": "harshpareek91@gmai.com",