@dereekb/util 13.0.6 → 13.1.0

package/fetch/index.esm.js

@@ -1,5 +1,5 @@
 import { BaseError } from 'make-error';
-import { removeTrailingSlashes, asGetter, multiValueMapBuilder, filterMaybeArrayValues, isWebsiteUrlWithPrefix, fixMultiSlashesInSlashPath, isPromiseLike, cachedGetter, FIRST_PAGE, mapIdentityFunction, performTasksFromFactoryInParallelFunction, performAsyncTasks, mergeObjects, filterEmptyPojoValues, useIterableOrValue, isEmptyIterable, fixExtraQueryParameters, forEachInIterable, forEachKeyValue, isIterable } from '@dereekb/util';
+import { removeTrailingSlashes, asGetter, multiValueMapBuilder, filterMaybeArrayValues, isWebsiteUrlWithPrefix, fixMultiSlashesInSlashPath, isPromiseLike, asArray, urlWithoutParameters, cachedGetter, FIRST_PAGE, mapIdentityFunction, performTasksFromFactoryInParallelFunction, performAsyncTasks, mergeObjects, filterEmptyPojoValues, useIterableOrValue, isEmptyIterable, fixExtraQueryParameters, forEachInIterable, forEachKeyValue, isIterable } from '@dereekb/util';
 import { safeParse } from 'fast-content-type-parse';
 
 function _assert_this_initialized$3(self) {
@@ -276,7 +276,7 @@ function _array_like_to_array$2(arr, len) {
 function _array_with_holes$2(arr) {
     if (Array.isArray(arr)) return arr;
 }
-function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
+function asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
         var value = info.value;
@@ -290,16 +290,16 @@ function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
         Promise.resolve(value).then(_next, _throw);
     }
 }
-function _async_to_generator$3(fn) {
+function _async_to_generator$4(fn) {
     return function() {
         var self = this, args = arguments;
         return new Promise(function(resolve, reject) {
             var gen = fn.apply(self, args);
             function _next(value) {
-                asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, "next", value);
+                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "next", value);
             }
             function _throw(err) {
-                asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, "throw", err);
+                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "throw", err);
             }
             _next(undefined);
         });
@@ -401,7 +401,7 @@ function _unsupported_iterable_to_array$2(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$2(o, minLen);
 }
-function _ts_generator$3(thisArg, body) {
+function _ts_generator$4(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
         sent: function() {
@@ -552,9 +552,9 @@ function _ts_generator$3(thisArg, body) {
     }
     var makeFetchRequest = fetchRequestFactory(config);
     return function(input, init) {
-        return _async_to_generator$3(function() {
+        return _async_to_generator$4(function() {
             var request, response;
-            return _ts_generator$3(this, function(_state) {
+            return _ts_generator$4(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         return [
@@ -601,9 +601,9 @@ function fetchRequestFactory(config) {
         return result;
     } : undefined;
     function asFetchRequest(input) {
-        return _async_to_generator$3(function() {
+        return _async_to_generator$4(function() {
             var awaitedInput, _tmp;
-            return _ts_generator$3(this, function(_state) {
+            return _ts_generator$4(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         if (!isPromiseLike(input)) return [
@@ -641,9 +641,9 @@ function fetchRequestFactory(config) {
         })();
     }
     var buildRequestWithFixedUrl = buildUrl ? function(input) {
-        return _async_to_generator$3(function() {
+        return _async_to_generator$4(function() {
             var relativeUrl, baseRequest, request, url;
-            return _ts_generator$3(this, function(_state) {
+            return _ts_generator$4(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         if (!(typeof input === 'string')) return [
@@ -703,9 +703,9 @@ function fetchRequestFactory(config) {
     var buildRequestInit;
     if (inputBaseRequest != null || timeout != null) {
         var computeBaseRequest = function computeBaseRequest() {
-            return _async_to_generator$3(function() {
+            return _async_to_generator$4(function() {
                 var computedBaseRequest, baseRequest;
-                return _ts_generator$3(this, function(_state) {
+                return _ts_generator$4(this, function(_state) {
                     switch(_state.label){
                         case 0:
                             return [
@@ -726,9 +726,9 @@ function fetchRequestFactory(config) {
             })();
         };
         var combineRequestInits = function combineRequestInits(request, requestInit) {
-            return _async_to_generator$3(function() {
+            return _async_to_generator$4(function() {
                 var baseRequest, merged, _tmp, timeout;
-                return _ts_generator$3(this, function(_state) {
+                return _ts_generator$4(this, function(_state) {
                     switch(_state.label){
                         case 0:
                             return [
@@ -777,9 +777,9 @@ function fetchRequestFactory(config) {
         };
     }
     return function(input, init) {
-        return _async_to_generator$3(function() {
+        return _async_to_generator$4(function() {
             var fixedRequest, request, e;
-            return _ts_generator$3(this, function(_state) {
+            return _ts_generator$4(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         _state.trys.push([
@@ -881,17 +881,200 @@ function isFetchRequest(input) {
     return Boolean(input.url);
 }
 
-function fetchUploadFile(input) {
-    var _input_method;
-    var inputFetch = input.fetch, url = input.url, inputBody = input.body;
-    var useFetch = inputFetch !== null && inputFetch !== void 0 ? inputFetch : fetch;
-    return useFetch(url, {
-        method: (_input_method = input.method) !== null && _input_method !== void 0 ? _input_method : 'POST',
-        body: inputBody.body,
-        headers: {
-            'Content-Type': inputBody.mimeType
+function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator$3(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _ts_generator$3(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
         }
-    });
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Creates a File object from the given input.
+ *
+ * @example
+ * makeFileForFetch({ content: pdfBuffer, fileName: 'doc.pdf', mimeType: 'application/pdf' })
+ */ function makeFileForFetch(input) {
+    var options = {};
+    if (input.mimeType) {
+        options.type = input.mimeType;
+    }
+    if (input.lastModified != null) {
+        options.lastModified = input.lastModified;
+    }
+    return new File(asArray(input.content), input.fileName, options);
+}
+function fetchFileFromUrl(input, safe) {
+    return _async_to_generator$3(function() {
+        var url, mimeType, inputFetch, useFetch, response, result, _ref, _ref1, _input_fileName, buffer, responseMimeType, fileName, options;
+        return _ts_generator$3(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    url = input.url, mimeType = input.mimeType, inputFetch = input.fetch;
+                    useFetch = inputFetch !== null && inputFetch !== void 0 ? inputFetch : fetch;
+                    return [
+                        4,
+                        useFetch(url, {
+                            method: 'GET'
+                        })
+                    ];
+                case 1:
+                    response = _state.sent();
+                    if (!!response.ok) return [
+                        3,
+                        2
+                    ];
+                    if (!safe) {
+                        throw new Error("Failed to fetch file from ".concat(url, ": ").concat(response.status, " ").concat(response.statusText));
+                    }
+                    return [
+                        3,
+                        4
+                    ];
+                case 2:
+                    return [
+                        4,
+                        response.arrayBuffer()
+                    ];
+                case 3:
+                    buffer = _state.sent();
+                    responseMimeType = (_ref = mimeType !== null && mimeType !== void 0 ? mimeType : response.headers.get('content-type')) !== null && _ref !== void 0 ? _ref : undefined;
+                    fileName = (_ref1 = (_input_fileName = input.fileName) !== null && _input_fileName !== void 0 ? _input_fileName : urlWithoutParameters(url).split('/').pop()) !== null && _ref1 !== void 0 ? _ref1 : 'file';
+                    options = responseMimeType ? {
+                        type: responseMimeType
+                    } : {};
+                    result = new File([
+                        buffer
+                    ], fileName, options);
+                    _state.label = 4;
+                case 4:
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    })();
 }
 /**
  * Parses the file response and returns the response wrapped in a FetchFileResponse object.
@@ -909,6 +1092,20 @@ function fetchUploadFile(input) {
         mimeType: contentType === null || contentType === void 0 ? void 0 : contentType.type
     };
 }
+/**
+ * @deprecated Use makeFileForFetch() with FormData and context.fetch() instead.
+ */ function fetchUploadFile(input) {
+    var _input_method;
+    var inputFetch = input.fetch, url = input.url, inputBody = input.body;
+    var useFetch = inputFetch !== null && inputFetch !== void 0 ? inputFetch : fetch;
+    return useFetch(url, {
+        method: (_input_method = input.method) !== null && _input_method !== void 0 ? _input_method : 'POST',
+        body: inputBody.body,
+        headers: {
+            'Content-Type': inputBody.mimeType
+        }
+    });
+}
 
 function asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, key, arg) {
     try {
@@ -1722,10 +1919,30 @@ function _ts_generator(thisArg, body) {
     }
 }
 /**
- * Iterates through the pages of a created FetchPage instance by each item individually.
+ * Iterates through all pages of a paginated fetch and processes each item individually.
  *
- * @param config
- * @returns
+ * Built on top of {@link iterateFetchPagesByItems}, this function handles per-item granularity
+ * by extracting items from each page and delegating to {@link performAsyncTasks}. Items are
+ * processed sequentially by default to preserve ordering guarantees, but can be parallelized
+ * via `iteratePerformTasksConfig`.
+ *
+ * Each item's callback receives a global index that reflects its position across all pages,
+ * not just within the current page.
+ *
+ * @param config - Configuration specifying the fetch page source, item extraction, and per-item callback
+ * @returns Combined result from {@link iterateFetchPagesByItems} including page/item counts and per-item task results
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFetchPagesByEachItem({
+ *   fetchPageFactory: myPageFactory,
+ *   input: { query: 'active' },
+ *   readItemsFromPageResult: (r) => r.result.items,
+ *   iterateEachPageItem: async (item, index, pageResult) => {
+ *     return processItem(item);
+ *   }
+ * });
+ * ```
  */ function iterateFetchPagesByEachItem(config) {
     return _async_to_generator(function() {
         var iterateEachPageItem, iteratePerformTasksConfig;
@@ -1771,10 +1988,32 @@ function _ts_generator(thisArg, body) {
     })();
 }
 /**
- * Iterates through the pages of a created FetchPage instance.
+ * Iterates through paginated fetch results at the item batch level.
  *
- * @param config
- * @returns
+ * Fetches pages sequentially (or in parallel via `maxParallelPages`), extracts items
+ * from each page using `readItemsFromPageResult`, optionally filters them, then
+ * passes the batch to `iteratePageItems`. Tracks both raw loaded counts and
+ * post-filter visited counts, terminating when either limit is reached or pages
+ * are exhausted.
+ *
+ * For per-item processing instead of batch processing, use {@link iterateFetchPagesByEachItem}.
+ *
+ * @param config - Configuration specifying fetch source, item extraction, filtering, limits, and batch callback
+ * @returns Result with page count and item counters (loaded and visited)
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFetchPagesByItems({
+ *   fetchPageFactory: myPageFactory,
+ *   input: { status: 'active' },
+ *   readItemsFromPageResult: (r) => r.result.records,
+ *   filterPageItems: (items) => items.filter(x => x.isValid),
+ *   iterateItemsLimit: 500,
+ *   iteratePageItems: async (items, pageResult, totalVisited) => {
+ *     await bulkInsert(items);
+ *   }
+ * });
+ * ```
  */ function iterateFetchPagesByItems(config) {
     return _async_to_generator(function() {
         var readItemsFromPageResult, inputTotalIterateItemsLimit, inputTotalLoadItemLimit, inputFilterPageItems, iteratePageItems, iterateItemsLimit, loadItemLimit, filterPageItems, totalItemsLoaded, totalItemsVisited, hasReachedFinalItem, fetchPagesConfig, iterateFetchPagesResult;
@@ -2377,4 +2616,4 @@ var fetchJsonRequestInit = fetchJsonRequestInitFunction();
     }
 });
 
-export { DEFAULT_FETCH_HANDLER, DEFAULT_FETCH_REQUEST_FACTORY, FETCH_PAGE_FACTORY_DEFAULT_MAX_PAGE, FetchPageLimitReachedError, FetchPageNoNextPageError, FetchRequestFactoryError, FetchResponseError, FetchTimeoutError, JsonResponseParseError, configureFetch, fetchApiFetchService, fetchJsonBodyString, fetchJsonFunction, fetchJsonRequestInit, fetchJsonRequestInitFunction, fetchOk, fetchPageFactory, fetchRequestFactory, fetchService, fetchTimeout, fetchURL, fetchURLQueryKeyValueStringTuples, fetchURLSearchParamsObjectToURLSearchParams, fetchUploadFile, headersToHeadersTuple, isFetchRequest, isURL, isURLSearchParams, iterateFetchPages, iterateFetchPagesByEachItem, iterateFetchPagesByItems, makeUrlSearchParams, mergeMakeUrlSearchParamsOptions, mergeRequestHeaders, mergeRequestInits, parseFetchFileResponse, queryParamsToSearchParams, rateLimitedFetchHandler, requireOkResponse, returnNullHandleFetchJsonParseErrorFunction, throwJsonResponseParseErrorFunction };
+export { DEFAULT_FETCH_HANDLER, DEFAULT_FETCH_REQUEST_FACTORY, FETCH_PAGE_FACTORY_DEFAULT_MAX_PAGE, FetchPageLimitReachedError, FetchPageNoNextPageError, FetchRequestFactoryError, FetchResponseError, FetchTimeoutError, JsonResponseParseError, configureFetch, fetchApiFetchService, fetchFileFromUrl, fetchJsonBodyString, fetchJsonFunction, fetchJsonRequestInit, fetchJsonRequestInitFunction, fetchOk, fetchPageFactory, fetchRequestFactory, fetchService, fetchTimeout, fetchURL, fetchURLQueryKeyValueStringTuples, fetchURLSearchParamsObjectToURLSearchParams, fetchUploadFile, headersToHeadersTuple, isFetchRequest, isURL, isURLSearchParams, iterateFetchPages, iterateFetchPagesByEachItem, iterateFetchPagesByItems, makeFileForFetch, makeUrlSearchParams, mergeMakeUrlSearchParamsOptions, mergeRequestHeaders, mergeRequestInits, parseFetchFileResponse, queryParamsToSearchParams, rateLimitedFetchHandler, requireOkResponse, returnNullHandleFetchJsonParseErrorFunction, throwJsonResponseParseErrorFunction };

package/fetch/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/fetch",
-  "version": "13.0.6",
+  "version": "13.1.0",
   "peerDependencies": {
-    "@dereekb/util": "13.0.6",
+    "@dereekb/util": "13.1.0",
     "make-error": "^1.3.0",
     "fast-content-type-parse": "^3.0.0"
   },

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

@@ -1,45 +1,72 @@
-import { type ContentTypeMimeType, type Maybe, type MimeTypeWithoutParameters } from '@dereekb/util';
+import { type ArrayOrValue, type ContentTypeMimeType, type Maybe, type MimeTypeWithoutParameters } from '@dereekb/util';
 import { safeParse as parseContentType } from 'fast-content-type-parse';
 import { type FetchMethod } from './fetch.type';
 /**
- * Input for fetchUploadFile().
+ * Input for makeFileForFetch().
  */
-export interface FetchUploadFile {
+export interface MakeFileForFetchInput {
     /**
-     * URL to upload the file to.
+     * File content. Can be a string, ArrayBuffer, Blob, or array of BlobParts.
      */
-    readonly url: string;
+    readonly content: ArrayOrValue<BlobPart>;
     /**
-     * Fetch function to use.
+     * File name including extension.
      *
-     * Defaults to the global fetch function.
+     * @example 'document.pdf'
      */
-    readonly fetch?: typeof fetch;
+    readonly fileName: string;
     /**
-     * Method to use. Defaults to 'POST'.
+     * MIME type of the file.
+     *
+     * @example 'application/pdf'
      */
-    readonly method?: FetchMethod;
+    readonly mimeType?: ContentTypeMimeType;
     /**
-     * Body data to upload.
+     * Last modified timestamp in milliseconds.
      */
-    readonly body: FetchUploadFileBody;
+    readonly lastModified?: number;
 }
 /**
- * A mime type and body pair to upload.
+ * Creates a File object from the given input.
+ *
+ * @example
+ * makeFileForFetch({ content: pdfBuffer, fileName: 'doc.pdf', mimeType: 'application/pdf' })
  */
-export interface FetchUploadFileBody {
+export declare function makeFileForFetch(input: MakeFileForFetchInput): File;
+/**
+ * Input for fetchFileFromUrl().
+ */
+export interface FetchFileFromUrlInput {
     /**
-     * The mime type of the body content to upload.
+     * URL to download the file from.
      */
-    readonly mimeType: ContentTypeMimeType;
+    readonly url: string;
     /**
-     * The body, passed to fetch.
+     * File name to use for the resulting File object.
      *
-     * Can be a Uint8Array, Buffer, FormData, string, etc.
+     * If not provided, attempts to derive the name from the URL path or falls back to 'file'.
      */
-    readonly body: BodyInit;
+    readonly fileName?: Maybe<string>;
+    /**
+     * MIME type override. If not provided, uses the Content-Type from the response.
+     */
+    readonly mimeType?: Maybe<ContentTypeMimeType>;
+    /**
+     * Fetch function to use. Defaults to the global fetch.
+     */
+    readonly fetch?: Maybe<typeof fetch>;
 }
-export declare function fetchUploadFile(input: FetchUploadFile): Promise<Response>;
+/**
+ * Downloads a file from the given URL and returns it as a File object.
+ *
+ * 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)
+ */
+export declare function fetchFileFromUrl(input: FetchFileFromUrlInput): Promise<File>;
+export declare function fetchFileFromUrl(input: FetchFileFromUrlInput, safe: true): Promise<Maybe<File>>;
 export type FetchFileResponseContentType = ReturnType<typeof parseContentType>;
 export interface FetchFileResponse {
     /**
@@ -66,3 +93,23 @@ export interface FetchFileResponse {
  * @returns
  */
 export declare function parseFetchFileResponse(response: Response): FetchFileResponse;
+/**
+ * @deprecated Use makeFileForFetch() with FormData instead.
+ */
+export interface FetchUploadFile {
+    readonly url: string;
+    readonly fetch?: typeof fetch;
+    readonly method?: FetchMethod;
+    readonly body: FetchUploadFileBody;
+}
+/**
+ * @deprecated Use makeFileForFetch() with FormData instead.
+ */
+export interface FetchUploadFileBody {
+    readonly mimeType: ContentTypeMimeType;
+    readonly body: BodyInit;
+}
+/**
+ * @deprecated Use makeFileForFetch() with FormData and context.fetch() instead.
+ */
+export declare function fetchUploadFile(input: FetchUploadFile): Promise<Response>;