@dereekb/util 13.4.0 → 13.4.1

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

@@ -29,8 +29,8 @@ export interface MakeFileForFetchInput {
 /**
  * Creates a File object from the given input.
  *
- * @example
- * makeFileForFetch({ content: pdfBuffer, fileName: 'doc.pdf', mimeType: 'application/pdf' })
+ * @param input - configuration containing the file content, name, optional MIME type, and last modified timestamp
+ * @returns a File object constructed from the provided input
  */
 export declare function makeFileForFetch(input: MakeFileForFetchInput): File;
 /**
@@ -61,9 +61,8 @@ export interface FetchFileFromUrlInput {
  *
  * When safe is true, returns undefined instead of throwing on fetch failure.
  *
- * @example
- * const file = await fetchFileFromUrl({ url: 'https://example.com/doc.pdf' })
- * formData.append('file', file)
+ * @param input - configuration containing the URL, optional file name, MIME type override, and fetch function
+ * @returns the downloaded content as a File object, or undefined in safe mode on failure
  */
 export declare function fetchFileFromUrl(input: FetchFileFromUrlInput): Promise<File>;
 export declare function fetchFileFromUrl(input: FetchFileFromUrlInput, safe: true): Promise<Maybe<File>>;
@@ -111,5 +110,8 @@ export interface FetchUploadFileBody {
 }
 /**
  * @deprecated Use makeFileForFetch() with FormData and context.fetch() instead.
+ *
+ * @param input - configuration containing the upload URL, fetch function, HTTP method, and file body
+ * @returns a promise resolving to the fetch Response
  */
 export declare function fetchUploadFile(input: FetchUploadFile): Promise<Response>;

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

@@ -30,4 +30,11 @@ export interface RateLimitedFetchHandlerConfig<T extends PromiseRateLimiter> {
      */
     updateWithResponse(response: Response, fetchResponseError?: Maybe<FetchResponseError>): PromiseOrValue<boolean>;
 }
+/**
+ * Creates a FetchHandler that enforces rate limiting via the provided PromiseRateLimiter and supports
+ * automatic retry when the server signals throttling.
+ *
+ * @param config - configuration containing the rate limiter, retry settings, and response handler
+ * @returns a RateLimitedFetchHandler that rate-limits outgoing requests and retries on throttle responses
+ */
 export declare function rateLimitedFetchHandler<T extends PromiseRateLimiter>(config: RateLimitedFetchHandlerConfig<T>): RateLimitedFetchHandler<T>;

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
- * @param omitKeys
- * @returns
+ * @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;
 /**
@@ -54,5 +54,8 @@ export declare function makeUrlSearchParams(input: Maybe<ArrayOrValue<Maybe<obje
 export declare function makeUrlSearchParamsString(input: 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
  */
 export declare function mergeMakeUrlSearchParamsOptions(options: ArrayOrValue<Maybe<MakeUrlSearchParamsOptions>>): MakeUrlSearchParamsOptions;

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

@@ -31,7 +31,7 @@ export type FetchJsonWithInputFunction = <R>(url: FetchURLInput, input: FetchJso
  * Used to fetch from the input url and retrieve a JSON response.
  */
 export type FetchJsonFunction = FetchJsonGetFunction & FetchJsonMethodAndBodyFunction & FetchJsonWithInputFunction;
-export type FetchJsonInterceptJsonResponseFunction = (json: any, response: Response) => any;
+export type FetchJsonInterceptJsonResponseFunction = (json: unknown, response: Response) => unknown;
 export type HandleFetchJsonParseErrorFunction = (response: Response) => string | null | never;
 export declare const throwJsonResponseParseErrorFunction: HandleFetchJsonParseErrorFunction;
 export declare const returnNullHandleFetchJsonParseErrorFunction: HandleFetchJsonParseErrorFunction;
@@ -49,6 +49,10 @@ 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
  */
 export declare function fetchJsonFunction(fetch: ConfiguredFetch, inputConfig?: FetchJsonFunctionConfig | HandleFetchJsonParseErrorFunction): FetchJsonFunction;
 export interface FetchJsonRequestInitFunctionConfig {
@@ -64,5 +68,12 @@ export interface FetchJsonRequestInitFunctionConfig {
     mapFetchJsonInput?: FetchJsonInputMapFunction;
 }
 export type FetchJsonRequestInitFunction = (methodOrInput?: string | FetchJsonInput | undefined, 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}
+ */
 export declare function fetchJsonRequestInitFunction(config?: FetchJsonRequestInitFunctionConfig): FetchJsonRequestInitFunction;
 export declare const fetchJsonRequestInit: FetchJsonRequestInitFunction;

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

@@ -4,4 +4,12 @@ export declare class FetchTimeoutError extends BaseError {
     readonly timeout: number;
     constructor(response: Response, timeout: number);
 }
+/**
+ * Wraps a fetch function to add automatic timeout/abort support. If a timeout value
+ * 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
+ */
 export declare function fetchTimeout(inputFetch: typeof fetch): typeof fetch;

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

@@ -11,8 +11,27 @@ export interface FetchURLConfiguration {
     queryParams?: FetchURLQueryParamsInput;
 }
 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
+ */
 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
+ */
 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
+ */
 export declare function isURLSearchParams(input: unknown): input is URLSearchParams;
 export type FetchURLQueryParamsInput = URLSearchParams | FetchURLSearchParamsObject | Iterable<FetchURLQueryKeyValueStringTuple> | Iterable<FetchURLQueryKeyValueTuple> | string;
 export type FetchURLQueryKeyValueStringTuple = [string, string];
@@ -26,8 +45,22 @@ export declare function fetchURLQueryKeyValueStringTuples(input: Iterable<FetchU
 export type FetchURLQueryKeyValueTuple = [Maybe<FetchURLQueryKeyValueTupleKey>, Maybe<ArrayOrValue<Maybe<FetchURLQueryKeyValueTupleKeyValue>>>];
 export type FetchURLQueryKeyValueTupleKey = string | number;
 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
+ */
 export declare function queryParamsToSearchParams(input: FetchURLQueryParamsInput): URLSearchParams;
 export type FetchURLSearchTupleValueKey = string | number;
 export type FetchURLSearchTupleValue = string | number;
 export type FetchURLSearchParamsObject = Partial<Record<FetchURLQueryKeyValueTupleKey, Maybe<ArrayOrValue<FetchURLQueryKeyValueTupleKeyValue>>>>;
+/**
+ * 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
+ */
 export declare function fetchURLSearchParamsObjectToURLSearchParams(input: FetchURLSearchParamsObject): URLSearchParams;