aspi 2.9.1 → 2.10.0

package/dist/index.cjs

@@ -332,6 +332,7 @@ var Request = class {
   #querySchemaAsyncResult = null;
   #querySchemaAsyncParams = null;
   #throwOnError = false;
+  #queryParamSerializer;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
     this.#path = path;
@@ -344,6 +345,7 @@ var Request = class {
     this.#customErrorCbs = { ...requestOptions?.errorCbs || {} };
     this.#throwOnError = requestOptions.throwOnError || false;
     this.#shouldBeResult = requestOptions.shouldBeResult || false;
+    this.#queryParamSerializer = requestOptions.queryParamSerializer;
     this.#capabilities = [...capabilities];
   }
   /**
@@ -1092,6 +1094,11 @@ var Request = class {
       return qp;
     }
     if (typeof value === "object" && value !== null) {
+      if (this.#queryParamSerializer) {
+        return this.#valueToQueryParams(
+          this.#queryParamSerializer(value)
+        );
+      }
       const qp = new URLSearchParams();
       for (const [key, val] of Object.entries(
         value
@@ -1642,11 +1649,13 @@ var Aspi2 = class {
   #customErrorCbs = {};
   #throwOnError = false;
   #shouldBeResult = false;
+  #queryParamSerializer;
   #capabilities = [];
   constructor(config) {
-    const { retryConfig, ...requestInit } = config;
+    const { retryConfig, queryParamSerializer, ...requestInit } = config;
     this.#globalRequestInit = requestInit;
     this.#retryConfig = retryConfig;
+    this.#queryParamSerializer = queryParamSerializer;
   }
   /**
    * Sets or overrides the base URL used for all subsequent API requests.
@@ -1697,7 +1706,8 @@ var Aspi2 = class {
         errorCbs: this.#customErrorCbs,
         throwOnError: this.#throwOnError,
         shouldBeResult: this.#shouldBeResult,
-        retryConfig: this.#retryConfig
+        retryConfig: this.#retryConfig,
+        queryParamSerializer: this.#queryParamSerializer
       },
       this.#capabilities
     );

package/dist/index.d.cts

@@ -156,6 +156,9 @@ type BaseURL = string | URL;
  * is intended to be passed alongside a `RequestInit` object when initializing
  * an Aspi instance.
  */
+type QueryParamSerializerInput = Record<string, unknown>;
+type QueryParamSerializerResult = URLSearchParams | string | Iterable<[string, string]>;
+type QueryParamSerializer = (params: QueryParamSerializerInput) => QueryParamSerializerResult;
 type AspiConfigBase = {
     /**
      * The base URL for all Aspi requests.
@@ -165,6 +168,34 @@ type AspiConfigBase = {
      * Optional retry configuration applied to all requests.
      */
     retryConfig?: AspiRetryConfig<AspiRequestInit>;
+    /**
+     * Optional custom serializer for object-style query parameters passed to
+     * `setQueryParams`. Receives the parsed/validated param object and must return
+     * a value that Aspi can turn into query params (`URLSearchParams`, a query
+     * string, or an iterable of `[key, value]` tuples).
+     *
+     * When omitted, arrays are stringified using the default
+     * `URLSearchParams` behaviour (`tag=a%2Cb%2Cc`).
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({
+     *   baseUrl: 'https://api.example.com',
+     *   queryParamSerializer: (params) => {
+     *     const qp = new URLSearchParams();
+     *     for (const [key, value] of Object.entries(params)) {
+     *       if (Array.isArray(value)) {
+     *         for (const item of value) qp.append(key, String(item));
+     *       } else {
+     *         qp.append(key, String(value));
+     *       }
+     *     }
+     *     return qp;
+     *   },
+     * });
+     * ```
+     */
+    queryParamSerializer?: QueryParamSerializer;
 };
 /**
  * Configuration for an Aspi instance (without request body).
@@ -285,6 +316,7 @@ type RequestOptions<TRequest extends AspiRequestInit> = {
     errorCbs?: ErrorCallbacks;
     throwOnError?: boolean;
     shouldBeResult?: boolean;
+    queryParamSerializer?: QueryParamSerializer;
 };
 /**
  * Record of custom error callbacks keyed by HTTP status code.
@@ -2086,4 +2118,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 Prettify, Request, type RequestOptions, type RequestTransformer, result as Result, type SchemaParseError, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isSchemaParseError };
+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, type QueryParamSerializer, type QueryParamSerializerInput, type QueryParamSerializerResult, Request, type RequestOptions, type RequestTransformer, result as Result, type SchemaParseError, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isSchemaParseError };

package/dist/index.d.ts

@@ -156,6 +156,9 @@ type BaseURL = string | URL;
  * is intended to be passed alongside a `RequestInit` object when initializing
  * an Aspi instance.
  */
+type QueryParamSerializerInput = Record<string, unknown>;
+type QueryParamSerializerResult = URLSearchParams | string | Iterable<[string, string]>;
+type QueryParamSerializer = (params: QueryParamSerializerInput) => QueryParamSerializerResult;
 type AspiConfigBase = {
     /**
      * The base URL for all Aspi requests.
@@ -165,6 +168,34 @@ type AspiConfigBase = {
      * Optional retry configuration applied to all requests.
      */
     retryConfig?: AspiRetryConfig<AspiRequestInit>;
+    /**
+     * Optional custom serializer for object-style query parameters passed to
+     * `setQueryParams`. Receives the parsed/validated param object and must return
+     * a value that Aspi can turn into query params (`URLSearchParams`, a query
+     * string, or an iterable of `[key, value]` tuples).
+     *
+     * When omitted, arrays are stringified using the default
+     * `URLSearchParams` behaviour (`tag=a%2Cb%2Cc`).
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({
+     *   baseUrl: 'https://api.example.com',
+     *   queryParamSerializer: (params) => {
+     *     const qp = new URLSearchParams();
+     *     for (const [key, value] of Object.entries(params)) {
+     *       if (Array.isArray(value)) {
+     *         for (const item of value) qp.append(key, String(item));
+     *       } else {
+     *         qp.append(key, String(value));
+     *       }
+     *     }
+     *     return qp;
+     *   },
+     * });
+     * ```
+     */
+    queryParamSerializer?: QueryParamSerializer;
 };
 /**
  * Configuration for an Aspi instance (without request body).
@@ -285,6 +316,7 @@ type RequestOptions<TRequest extends AspiRequestInit> = {
     errorCbs?: ErrorCallbacks;
     throwOnError?: boolean;
     shouldBeResult?: boolean;
+    queryParamSerializer?: QueryParamSerializer;
 };
 /**
  * Record of custom error callbacks keyed by HTTP status code.
@@ -2086,4 +2118,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 Prettify, Request, type RequestOptions, type RequestTransformer, result as Result, type SchemaParseError, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isSchemaParseError };
+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, type QueryParamSerializer, type QueryParamSerializerInput, type QueryParamSerializerResult, Request, type RequestOptions, type RequestTransformer, result as Result, type SchemaParseError, getHttpErrorStatus, httpErrors, isAspiError, isCustomError, isJSONParseError, isSchemaParseError };

package/dist/index.js

@@ -302,6 +302,7 @@ var Request = class {
   #querySchemaAsyncResult = null;
   #querySchemaAsyncParams = null;
   #throwOnError = false;
+  #queryParamSerializer;
   #capabilities = [];
   constructor(method, path, requestOptions, capabilities = []) {
     this.#path = path;
@@ -314,6 +315,7 @@ var Request = class {
     this.#customErrorCbs = { ...requestOptions?.errorCbs || {} };
     this.#throwOnError = requestOptions.throwOnError || false;
     this.#shouldBeResult = requestOptions.shouldBeResult || false;
+    this.#queryParamSerializer = requestOptions.queryParamSerializer;
     this.#capabilities = [...capabilities];
   }
   /**
@@ -1062,6 +1064,11 @@ var Request = class {
       return qp;
     }
     if (typeof value === "object" && value !== null) {
+      if (this.#queryParamSerializer) {
+        return this.#valueToQueryParams(
+          this.#queryParamSerializer(value)
+        );
+      }
       const qp = new URLSearchParams();
       for (const [key, val] of Object.entries(
         value
@@ -1612,11 +1619,13 @@ var Aspi2 = class {
   #customErrorCbs = {};
   #throwOnError = false;
   #shouldBeResult = false;
+  #queryParamSerializer;
   #capabilities = [];
   constructor(config) {
-    const { retryConfig, ...requestInit } = config;
+    const { retryConfig, queryParamSerializer, ...requestInit } = config;
     this.#globalRequestInit = requestInit;
     this.#retryConfig = retryConfig;
+    this.#queryParamSerializer = queryParamSerializer;
   }
   /**
    * Sets or overrides the base URL used for all subsequent API requests.
@@ -1667,7 +1676,8 @@ var Aspi2 = class {
         errorCbs: this.#customErrorCbs,
         throwOnError: this.#throwOnError,
         shouldBeResult: this.#shouldBeResult,
-        retryConfig: this.#retryConfig
+        retryConfig: this.#retryConfig,
+        queryParamSerializer: this.#queryParamSerializer
       },
       this.#capabilities
     );

package/package.json

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