@dereekb/util 10.1.29 → 10.2.0

package/fetch/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@dereekb/util/fetch",
-  "version": "10.1.29",
-  "type": "commonjs",
+  "version": "10.2.0",
+  ".": {
+    "types": "./src/index.d.ts",
+    "node": {
+      "require": "./index.cjs.js",
+      "import": "./index.mjs"
+    },
+    "browser": {
+      "require": "./index.cjs.js",
+      "import": "./index.esm.js"
+    },
+    "default": "./index.cjs.js"
+  },
   "peerDependencies": {
     "@dereekb/util": "*"
   },
-  "main": "./src/index.js"
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js"
 }

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

@@ -1,4 +1,11 @@
 import { BaseError } from 'make-error';
+/**
+ * Thrown by a FetchRequestFactory if one of the async request initialization steps fails.
+ */
+export declare class FetchRequestFactoryError extends BaseError {
+    readonly error: Error | string | unknown;
+    constructor(error: Error | string | unknown);
+}
 /**
  * Wraps the input fetch function to always pass the fetch response promise to requireOkResponse().
  *

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

@@ -1,4 +1,4 @@
-import { type Factory, type MapFunction, type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { type Factory, type MapFunction, type Maybe, type WebsiteUrl, type PromiseOrValue, type GetterOrValue } from '@dereekb/util';
 import { type ConfiguredFetchWithTimeout, type RequestInitWithTimeout } from './fetch.type';
 /**
  * Interface used for creating fetch related resource factories.
@@ -64,11 +64,11 @@ export interface FetchRequestFactoryInput {
     /**
      * Base request info to add to each value.
      */
-    baseRequest?: RequestInit;
+    baseRequest?: GetterOrValue<PromiseOrValue<RequestInit>>;
     /**
      * Default timeout to add to requestInit values.
      *
-     * NOTE: This timeout is not used by this fetchRequest directly, but instead
+     * NOTE: This timeout is not used by this fetchRequest directly, but is added to the baseRequest.
      */
     timeout?: number;
     /**
@@ -78,8 +78,8 @@ export interface FetchRequestFactoryInput {
      */
     requestInitFactory?: FetchRequestInitFactory;
 }
-export type FetchRequestInitFactory = (currRequest: Request, init?: RequestInit) => RequestInitWithTimeout | undefined;
-export type FetchRequestFactory = (input: RequestInfo | URL, init?: RequestInit | undefined) => Request;
+export type FetchRequestInitFactory = (currRequest: PromiseOrValue<Request>, init?: PromiseOrValue<RequestInit>) => PromiseOrValue<RequestInitWithTimeout | undefined>;
+export type FetchRequestFactory = (input: RequestInfo | URL, init?: RequestInit | undefined) => PromiseOrValue<Request>;
 export type AbortControllerFactory = Factory<AbortController>;
 export declare function fetchRequestFactory(config: FetchRequestFactoryInput): FetchRequestFactory;
 export declare function mergeRequestInits<T extends RequestInit>(base: T, requestInit?: T | undefined): T;

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

@@ -0,0 +1,116 @@
+import { type CachedGetter, type Maybe, type Page, type PromiseOrValue } from '@dereekb/util';
+import { FetchRequestFactoryError } from './error';
+export declare class FetchPageNoNextPageError extends FetchRequestFactoryError {
+    readonly page: FetchPage<unknown, unknown>;
+    constructor(page: FetchPage<unknown, unknown>);
+}
+export declare class FetchPageLimitReachedError extends FetchRequestFactoryError {
+    readonly page: FetchPage<unknown, unknown>;
+    readonly limit: number;
+    constructor(page: FetchPage<unknown, unknown>, limit: number);
+}
+/**
+ * Query/Search cursor string.
+ *
+ * Used by some APIs for pagination.
+ */
+export type FetchPageCursor = string;
+export interface FetchPage<I, O> {
+    /**
+     * Input for this page.
+     */
+    readonly input: I;
+    /**
+     * Fetches the next page of results.
+     *
+     * If the page of results has been returned, returns the same reference and does not perform the fetch request again.
+     *
+     * If there are no pages to return, calling this will throw a FetchPageNoNextPageError error.
+     */
+    readonly fetchNext: CachedGetter<Promise<FetchNextPage<I, O>>>;
+}
+export interface FetchPageResultInfo extends Page {
+    /**
+     * Cursor for this page, if applicable.
+     */
+    readonly cursor?: Maybe<FetchPageCursor>;
+    /**
+     * Whether or not there are more results to fetch.
+     *
+     * If not defined, is assumed this info is not available and will default to true.
+     *
+     * Defaults to true.
+     */
+    readonly hasNext?: Maybe<boolean>;
+}
+export interface FetchPageResults<O> extends FetchPageResultInfo {
+    /**
+     * Result for this page.
+     */
+    readonly result: O;
+}
+export interface FetchNextPage<I, O> extends FetchPageResults<O>, FetchPage<I, O> {
+    /**
+     * Previous page.
+     *
+     * Undefined if this is the first page.
+     */
+    readonly previous?: Maybe<FetchNextPage<I, O>>;
+    /**
+     * Whether or not the max page has been reached.
+     */
+    readonly isAtMaxPage?: boolean;
+}
+export interface FetchPageFactoryConfig<I, O> {
+    /**
+     * The configured Fetch function that takes in the input and returns a results.
+     */
+    readonly fetch: (input: I) => Promise<O>;
+    /**
+     * Returns the page results from the result.
+     *
+     * The page number is ignored as it is inferred from the previous page.
+     *
+     * @param result
+     * @returns
+     */
+    readonly readFetchPageResultInfo: (result: O) => PromiseOrValue<Omit<FetchPageResultInfo, 'page'>>;
+    /**
+     * Creates new input for the next page that is merged with the previous input.
+     *
+     * Returns undefined if the next page should not be loaded.
+     *
+     * @param result
+     * @returns
+     */
+    readonly buildInputForNextPage: (pageResult: Partial<FetchPageResults<O>>, input: I) => PromiseOrValue<Maybe<Partial<I>>>;
+    /**
+     * The default max page to load up to.
+     *
+     * Defaults to 100. Pass null to disable the max page amount.
+     */
+    readonly defaultMaxPage?: Maybe<number>;
+}
+export interface FetchPageFactoryOptions<I, O> {
+    /**
+     * The max number of pages to load.
+     *
+     * Pass null to disable the max page amount.
+     */
+    readonly maxPage?: Maybe<number>;
+}
+/**
+ * Creates a new FetchPage instance.
+ */
+export type FetchPageFactory<I, O> = (input: I, options?: FetchPageFactoryOptions<I, O>) => FetchPage<I, O>;
+/**
+ * Default max page for a FetchPageFactory.
+ */
+export declare const FETCH_PAGE_FACTORY_DEFAULT_MAX_PAGE = 100;
+/**
+ * Creates a new FetchPageFactory from the input.
+ *
+ * @param config
+ * @returns
+ */
+export declare function fetchPageFactory<I, O>(config: FetchPageFactoryConfig<I, O>): FetchPageFactory<I, O>;

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

@@ -1,6 +1,7 @@
 export * from './error';
 export * from './fetch';
 export * from './fetch.type';
+export * from './fetch.page';
 export * from './json';
 export * from './provider';
 export * from './timeout';

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

@@ -16,6 +16,12 @@ export declare function fetchJsonBodyString(body: FetchJsonBody | undefined): st
 export interface FetchJsonInput extends Omit<RequestInit, 'body'> {
     method: FetchMethod;
     body?: FetchJsonBody | undefined;
+    /**
+     * Optional intercept function to intercept/transform the response.
+     *
+     * Does not override any other configured interceptor and occurs after those configured interceptors.
+     */
+    interceptResponse?: FetchJsonInterceptJsonResponseFunction;
 }
 export type FetchJsonInputMapFunction = MapSameFunction<FetchJsonInput>;
 export type FetchJsonGetFunction = <R>(url: FetchURLInput) => Promise<R>;
@@ -25,11 +31,21 @@ 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 HandleFetchJsonParseErrorFunction = (response: Response) => string | null | never;
 export declare const throwJsonResponseParseErrorFunction: HandleFetchJsonParseErrorFunction;
 export declare const returnNullHandleFetchJsonParseErrorFunction: HandleFetchJsonParseErrorFunction;
 export interface FetchJsonFunctionConfig extends FetchJsonRequestInitFunctionConfig {
-    handleFetchJsonParseErrorFunction?: HandleFetchJsonParseErrorFunction;
+    /**
+     * Optional intercept function to transform all response JSON before returning the result.
+     *
+     * Useful for cases where an API returns errors with a 200 response.
+     */
+    readonly interceptJsonResponse?: FetchJsonInterceptJsonResponseFunction;
+    /**
+     * Optional function to handle JSON parsing errors.
+     */
+    readonly handleFetchJsonParseErrorFunction?: HandleFetchJsonParseErrorFunction;
 }
 /**
  * Creates a FetchJsonFunction from the input ConfiguredFetch.