@dereekb/util 13.11.13 → 13.11.15

package/fetch/src/lib/fetch.url.d.ts

@@ -34,9 +34,9 @@ export interface MakeUrlSearchParamsOptions {
 /**
  * Creates URLSearchParams from the input objects. The input objects are merged together.
  *
- * @param input - one or more objects (or nullish values) whose key-value pairs become search parameters
- * @param options - optional configuration for filtering, omitting keys, and space encoding
- * @returns a URLSearchParams instance built from the merged and filtered input
+ * @param input - One or more objects (or nullish values) whose key-value pairs become search parameters.
+ * @param options - Optional configuration for filtering, omitting keys, and space encoding.
+ * @returns A URLSearchParams instance built from the merged and filtered input.
  */
 export declare function makeUrlSearchParams(input: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): URLSearchParams;
 /**
@@ -47,9 +47,9 @@ export declare function makeUrlSearchParams(input: Maybe<ArrayOrValue<Maybe<obje
  * RFC 3986 percent-encoded output (`%20` for spaces) instead of the
  * `application/x-www-form-urlencoded` default (`+` for spaces).
  *
- * @param input - objects to encode as query parameters
- * @param options - encoding options
- * @returns the encoded query string (without a leading `?`)
+ * @param input - Objects to encode as query parameters.
+ * @param options - Encoding options.
+ * @returns The encoded query string (without a leading `?`)
  */
 export declare function makeUrlSearchParamsString(input: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): string;
 /**
@@ -60,6 +60,11 @@ export declare function makeUrlSearchParamsString(input: Maybe<ArrayOrValue<Mayb
  * {@link MakeUrlSearchParamsOptions} such as `omitKeys`, `filterEmptyValues`, and
  * `useUrlSearchSpaceHandling`.
  *
+ * @param url - The URL string to update.
+ * @param params - New search parameters to merge into the URL.
+ * @param options - Optional configuration for filtering, omitting keys, and space encoding.
+ * @returns The URL string with updated query parameters.
+ *
  * @example
  * ```typescript
  * // Add params to a URL with no query string
@@ -74,17 +79,12 @@ export declare function makeUrlSearchParamsString(input: Maybe<ArrayOrValue<Mayb
  * updateUrlSearchParams('https://example.com', { scope: 'openid profile' }, { useUrlSearchSpaceHandling: true });
  * // => 'https://example.com?scope=openid%20profile'
  * ```
- *
- * @param url - the URL string to update
- * @param params - new search parameters to merge into the URL
- * @param options - optional configuration for filtering, omitting keys, and space encoding
- * @returns the URL string with updated query parameters
  */
 export declare function updateUrlSearchParams(url: string, params: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): string;
 /**
  * Merges an array of MakeUrlSearchParamsOptions into a single MakeUrlSearchParamsOptions value.
  *
- * @param options - one or more options objects whose omitKeys sets are combined
- * @returns a single MakeUrlSearchParamsOptions with the union of all omitKeys
+ * @param options - One or more options objects whose omitKeys sets are combined.
+ * @returns A single MakeUrlSearchParamsOptions with the union of all omitKeys.
  */
 export declare function mergeMakeUrlSearchParamsOptions(options: ArrayOrValue<Maybe<MakeUrlSearchParamsOptions>>): MakeUrlSearchParamsOptions;

package/fetch/src/lib/json.d.ts

@@ -1,4 +1,4 @@
-import { type MapSameFunction } from '@dereekb/util';
+import { type MapSameFunction, type Maybe } from '@dereekb/util';
 import { type FetchMethod, type ConfiguredFetch } from './fetch.type';
 import { type FetchURLInput } from './url';
 export type FetchJsonBody = string | object;
@@ -12,10 +12,10 @@ export declare class JsonResponseParseError extends Error {
  * @param body
  * @returns
  */
-export declare function fetchJsonBodyString(body: FetchJsonBody | undefined): string | undefined;
+export declare function fetchJsonBodyString(body: Maybe<FetchJsonBody>): Maybe<string>;
 export interface FetchJsonInput extends Omit<RequestInit, 'body'> {
     readonly method: FetchMethod;
-    readonly body?: FetchJsonBody | undefined;
+    readonly body?: Maybe<FetchJsonBody>;
     /**
      * Optional intercept function to intercept/transform the response.
      *
@@ -32,7 +32,7 @@ export type FetchJsonWithInputFunction = <R>(url: FetchURLInput, input: FetchJso
  */
 export type FetchJsonFunction = FetchJsonGetFunction & FetchJsonMethodAndBodyFunction & FetchJsonWithInputFunction;
 export type FetchJsonInterceptJsonResponseFunction = (json: unknown, response: Response) => unknown;
-export type HandleFetchJsonParseErrorFunction = (response: Response) => string | null | never;
+export type HandleFetchJsonParseErrorFunction = (response: Response) => Maybe<string>;
 export declare const throwJsonResponseParseErrorFunction: HandleFetchJsonParseErrorFunction;
 export declare const returnNullHandleFetchJsonParseErrorFunction: HandleFetchJsonParseErrorFunction;
 export interface FetchJsonFunctionConfig extends FetchJsonRequestInitFunctionConfig {
@@ -50,9 +50,9 @@ export interface FetchJsonFunctionConfig extends FetchJsonRequestInitFunctionCon
 /**
  * Creates a FetchJsonFunction from the input ConfiguredFetch.
  *
- * @param fetch - the configured fetch function to use for making HTTP requests
- * @param inputConfig - optional configuration or error handler for JSON parsing; when a function is provided it is used as the parse error handler
- * @returns a FetchJsonFunction that performs requests and parses JSON responses
+ * @param fetch - The configured fetch function to use for making HTTP requests.
+ * @param inputConfig - Optional configuration or error handler for JSON parsing; when a function is provided it is used as the parse error handler.
+ * @returns A FetchJsonFunction that performs requests and parses JSON responses.
  */
 export declare function fetchJsonFunction(fetch: ConfiguredFetch, inputConfig?: FetchJsonFunctionConfig | HandleFetchJsonParseErrorFunction): FetchJsonFunction;
 export interface FetchJsonRequestInitFunctionConfig {
@@ -61,19 +61,19 @@ export interface FetchJsonRequestInitFunctionConfig {
      *
      * Defaults to GET
      */
-    defaultMethod?: string;
+    readonly defaultMethod?: string;
     /**
      * Optional map function to modify the FetchJsonInput before it is finalized into a RequestInit value.
      */
-    mapFetchJsonInput?: FetchJsonInputMapFunction;
+    readonly mapFetchJsonInput?: FetchJsonInputMapFunction;
 }
-export type FetchJsonRequestInitFunction = (methodOrInput?: string | FetchJsonInput | undefined, body?: FetchJsonBody) => RequestInit;
+export type FetchJsonRequestInitFunction = (methodOrInput?: Maybe<string | FetchJsonInput>, body?: FetchJsonBody) => RequestInit;
 /**
  * Creates a {@link FetchJsonRequestInitFunction} that converts method/body inputs into a fully formed {@link RequestInit},
  * applying the configured default method and optional input mapping.
  *
- * @param config - optional configuration specifying the default HTTP method and an input mapping function
- * @returns a function that produces a {@link RequestInit} from a method string or {@link FetchJsonInput}
+ * @param config - Default-method and input-mapping overrides applied by the generated function.
+ * @returns Reusable builder that resolves a `RequestInit` for each request.
  */
 export declare function fetchJsonRequestInitFunction(config?: FetchJsonRequestInitFunctionConfig): FetchJsonRequestInitFunction;
 export declare const fetchJsonRequestInit: FetchJsonRequestInitFunction;

package/fetch/src/lib/timeout.d.ts

@@ -9,7 +9,7 @@ export declare class FetchTimeoutError extends BaseError {
  * is present on the RequestInit or Request and no abort signal is already provided,
  * an AbortController is created to abort the request after the specified duration.
  *
- * @param inputFetch - the fetch function to wrap with timeout behavior
- * @returns a wrapped fetch function that enforces timeouts via AbortController
+ * @param inputFetch - The fetch function to wrap with timeout behavior.
+ * @returns A wrapped fetch function that enforces timeouts via AbortController.
  */
 export declare function fetchTimeout(inputFetch: typeof fetch): typeof fetch;

package/fetch/src/lib/url.d.ts

@@ -15,28 +15,28 @@ export type FetchURLInput = SimpleFetchURLInput | FetchURLConfiguration;
  * Resolves a FetchURLInput to a URL string. Handles plain strings, URL objects, and
  * FetchURLConfiguration objects by appending query parameters when provided.
  *
- * @param input - a string, URL, or FetchURLConfiguration to resolve
- * @returns the resolved URL as a string
+ * @param input - URL source to normalize; may already be a string or carry query parameters to append.
+ * @returns Fully resolved request URL ready to pass to `fetch`.
  */
 export declare function fetchURL(input: FetchURLInput): string;
 /**
  * Type guard that checks whether the given value is a URL instance.
  *
- * @param input - the value to test
- * @returns true if the input is a URL instance
+ * @param input - The value to test.
+ * @returns True if the input is a URL instance.
  */
 export declare function isURL(input: unknown): input is URL;
 /**
  * Type guard that checks whether the given value is a URLSearchParams instance.
  *
- * @param input - the value to test
- * @returns true if the input is a URLSearchParams instance
+ * @param input - The value to test.
+ * @returns True if the input is a URLSearchParams instance.
  */
 export declare function isURLSearchParams(input: unknown): input is URLSearchParams;
 export type FetchURLQueryParamsInput = URLSearchParams | FetchURLSearchParamsObject | Iterable<FetchURLQueryKeyValueStringTuple> | Iterable<FetchURLQueryKeyValueTuple> | string;
 export type FetchURLQueryKeyValueStringTuple = [string, string];
 /**
- * Converts the input
+ * Converts the input.
  *
  * @param input
  * @returns
@@ -49,8 +49,8 @@ export type FetchURLQueryKeyValueTupleKeyValue = string | number | boolean;
  * Converts a FetchURLQueryParamsInput value (URLSearchParams, string, iterable of tuples, or
  * params object) into a URLSearchParams instance.
  *
- * @param input - the query parameters input to convert
- * @returns a URLSearchParams instance representing the input
+ * @param input - The query parameters input to convert.
+ * @returns A URLSearchParams instance representing the input.
  */
 export declare function queryParamsToSearchParams(input: FetchURLQueryParamsInput): URLSearchParams;
 export type FetchURLSearchTupleValueKey = string | number;
@@ -60,7 +60,7 @@ export type FetchURLSearchParamsObject = Partial<Record<FetchURLQueryKeyValueTup
  * Converts a FetchURLSearchParamsObject (a plain key-value record) into a URLSearchParams instance,
  * expanding array values into multiple entries for the same key and filtering out null/undefined values.
  *
- * @param input - the params object to convert
- * @returns a URLSearchParams instance representing the input object
+ * @param input - The params object to convert.
+ * @returns A URLSearchParams instance representing the input object.
  */
 export declare function fetchURLSearchParamsObjectToURLSearchParams(input: FetchURLSearchParamsObject): URLSearchParams;