@dereekb/rxjs 13.6.9 → 13.6.11

package/index.cjs.js

@@ -1,7 +1,575 @@
 'use strict';
 
-var rxjs = require('rxjs');
 var util = require('@dereekb/util');
+var rxjs = require('rxjs');
+
+function _class_call_check$9(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+// MARK: Abstract Loader
+/**
+ * Abstract asset loader that serves as a DI token in both Angular and NestJS.
+ *
+ * Accepts an {@link AssetPathRef} and returns an {@link AssetLoaderAssetInstance}
+ * for lazy Observable-based loading.
+ *
+ * Follows the same abstract-class-as-DI-token pattern as StorageObject.
+ * All concrete implementations are functional (factory functions returning
+ * objects satisfying this contract), except Angular's DbxCoreAssetLoader
+ * which requires @Injectable().
+ *
+ * @example
+ * ```ts
+ * // Angular: inject(AssetLoader)
+ * // NestJS:  @Inject(AssetLoader)
+ * const instance = loader.get(PROJECT_ASSETS.SCHOOL_DISTRICTS);
+ * instance.load().subscribe((data) => { ... });
+ * ```
+ */ var AssetLoader = function AssetLoader() {
+    _class_call_check$9(this, AssetLoader);
+} 
+;
+
+/**
+ * Creates a local {@link AssetLocalPathRef}.
+ *
+ * @example
+ * ```ts
+ * const DISTRICTS = localAsset('data/school-districts.json');
+ * // { sourceType: 'local', path: 'data/school-districts.json' }
+ * ```
+ *
+ * @param path - Relative path from the environment's base asset directory.
+ */ function localAsset(path) {
+    return {
+        sourceType: 'local',
+        path: path
+    };
+}
+/**
+ * Creates a remote {@link AssetRemotePathRef}.
+ *
+ * Remote assets always use absolute URLs with an http:// or https:// prefix.
+ * Throws if the provided URL does not have a valid prefix.
+ *
+ * @example
+ * ```ts
+ * const CDN = remoteAsset('https://cdn.example.com/geo.json');
+ * // { sourceType: 'remote', url: 'https://cdn.example.com/geo.json' }
+ * ```
+ *
+ * @param url - Absolute URL with http/https prefix to fetch the asset from.
+ * @throws Error if the URL does not have a valid http/https prefix.
+ */ function remoteAsset(url) {
+    if (!util.isWebsiteUrlWithPrefix(url)) {
+        throw new Error('remoteAsset() requires a URL with http:// or https:// prefix, got: "'.concat(url, '"'));
+    }
+    return {
+        sourceType: 'remote',
+        url: url
+    };
+}
+/**
+ * Creates a fluent builder for creating multiple local asset refs
+ * from the same folder.
+ *
+ * @example
+ * ```ts
+ * const DATA = assetFolder('data');
+ *
+ * const DISTRICTS = DATA.asset('school-districts.json');
+ * // { sourceType: 'local', path: 'data/school-districts.json' }
+ *
+ * const [A, B] = DATA.assets(['a.txt', 'b.txt']);
+ * // [
+ * //   { sourceType: 'local', path: 'data/a.txt' },
+ * //   { sourceType: 'local', path: 'data/b.txt' }
+ * // ]
+ * ```
+ *
+ * @param folder - Base folder path for the assets.
+ */ function assetFolder(folder) {
+    var normalizedFolder = folder.endsWith('/') ? folder : folder + '/';
+    var builder = {
+        asset: function asset(path) {
+            return localAsset("".concat(normalizedFolder).concat(path));
+        },
+        assets: function assets(paths) {
+            return paths.map(function(path) {
+                return localAsset("".concat(normalizedFolder).concat(path));
+            });
+        }
+    };
+    return builder;
+}
+/**
+ * Creates a fluent builder for creating multiple remote asset refs
+ * from the same base URL.
+ *
+ * The base URL must be a valid {@link WebsiteUrlWithPrefix}.
+ * Each child path is appended to produce a full absolute URL.
+ *
+ * @example
+ * ```ts
+ * const CDN = remoteAssetBaseUrl('https://cdn.example.com/assets');
+ *
+ * const GEO = CDN.asset('data/geo.json');
+ * // { sourceType: 'remote', url: 'https://cdn.example.com/assets/data/geo.json' }
+ *
+ * const [A, B] = CDN.assets(['a.json', 'b.json']);
+ * // [
+ * //   { sourceType: 'remote', url: 'https://cdn.example.com/assets/a.json' },
+ * //   { sourceType: 'remote', url: 'https://cdn.example.com/assets/b.json' }
+ * // ]
+ * ```
+ *
+ * @param baseUrl - Base URL with http/https prefix.
+ * @throws Error if the base URL does not have a valid http/https prefix.
+ */ function remoteAssetBaseUrl(baseUrl) {
+    if (!util.isWebsiteUrlWithPrefix(baseUrl)) {
+        throw new Error('remoteAssetBaseUrl() requires a URL with http:// or https:// prefix, got: "'.concat(baseUrl, '"'));
+    }
+    var normalizedBase = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/';
+    function resolveChildUrl(path) {
+        return new URL(path, normalizedBase).href;
+    }
+    var builder = {
+        asset: function asset(path) {
+            return remoteAsset(resolveChildUrl(path));
+        },
+        assets: function assets(paths) {
+            return paths.map(function(path) {
+                return remoteAsset(resolveChildUrl(path));
+            });
+        }
+    };
+    return builder;
+}
+
+/**
+ * Creates an {@link AssetLoaderAssetInstance} from a ref and a Promise-based get function.
+ *
+ * The returned {@link AssetLoaderAssetInstance.load} observable is cold — each subscription
+ * invokes the get function anew.
+ *
+ * @example
+ * ```ts
+ * const instance = assetLoaderAssetInstance(ref, (r) => fetch(r.path).then(res => res.arrayBuffer()));
+ * instance.load().subscribe((data) => { ... });
+ * ```
+ *
+ * @param ref - The asset path reference this instance represents.
+ * @param getFn - Promise-based function that loads the asset bytes.
+ */ function assetLoaderAssetInstance(ref, getFn) {
+    return {
+        ref: function ref1() {
+            return ref;
+        },
+        load: function load() {
+            return rxjs.defer(function() {
+                return rxjs.from(getFn(ref));
+            });
+        }
+    };
+}
+/**
+ * Creates an {@link AssetLoader} from a single {@link AssetLoaderGetFn}.
+ *
+ * This is the primary helper for building functional AssetLoader implementations
+ * from a Promise-based leaf loader.
+ *
+ * @example
+ * ```ts
+ * const loader = assetLoaderFromGetFn(async (ref) => {
+ *   const response = await fetch(resolveUrl(ref));
+ *   return response.arrayBuffer();
+ * });
+ * ```
+ *
+ * @param getFn - Promise-based function that loads any asset's bytes.
+ */ function assetLoaderFromGetFn(getFn) {
+    var loader = {
+        get: function get(ref) {
+            return assetLoaderAssetInstance(ref, getFn);
+        }
+    };
+    return loader;
+}
+
+/**
+ * Creates an {@link AssetLoader} that delegates to source-type-specific loaders.
+ *
+ * This is the primary composition point: wire a local loader and a remote
+ * loader together, and the delegated loader routes each {@link AssetPathRef}
+ * to the correct one based on {@link AssetPathRef.sourceType}.
+ *
+ * @example
+ * ```ts
+ * const loader = delegatedAssetLoader({
+ *   local: nodeJsLocalAssetLoader({ basePath: './assets' }),
+ *   remote: fetchAssetLoader({ baseUrl: 'https://api.example.com/assets/' })
+ * });
+ *
+ * loader.get(localAsset('data/districts.json'));   // → local loader
+ * loader.get(remoteAsset('data/geo.json'));        // → remote loader
+ * ```
+ *
+ * @param config - Specifies the local and remote delegate loaders.
+ */ function delegatedAssetLoader(config) {
+    var local = config.local, remote = config.remote;
+    var loader = {
+        get: function get(ref) {
+            var delegate = ref.sourceType === 'local' ? local : remote;
+            return delegate.get(ref);
+        }
+    };
+    return loader;
+}
+
+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 an {@link AssetLoader} that loads remote assets via HTTP fetch.
+ * Works in both browser and Node.js (Node 18+) environments.
+ *
+ * Remote refs always have absolute URLs, so no base URL resolution is needed.
+ *
+ * @example
+ * ```ts
+ * const loader = fetchAssetLoader();
+ * loader.get(remoteAsset('https://cdn.example.com/geo.json')).load().subscribe((data) => {
+ *   // loaded from https://cdn.example.com/geo.json
+ * });
+ *
+ * // With a custom fetch function:
+ * const loader = fetchAssetLoader({ fetch: myAuthenticatedFetch });
+ * ```
+ *
+ * @param config - Optional fetch configuration with custom fetch function.
+ */ function fetchAssetLoader() {
+    var config = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
+    var _config_fetch;
+    var fetchFn = (_config_fetch = config.fetch) !== null && _config_fetch !== void 0 ? _config_fetch : globalThis.fetch;
+    var getFn = function getFn(ref) {
+        return _async_to_generator$3(function() {
+            var remoteRef, url, response;
+            return _ts_generator$3(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        remoteRef = ref;
+                        url = remoteRef.url;
+                        return [
+                            4,
+                            fetchFn(url)
+                        ];
+                    case 1:
+                        response = _state.sent();
+                        if (!response.ok) {
+                            throw new Error("Failed to fetch asset from ".concat(url, ": ").concat(response.status, " ").concat(response.statusText));
+                        }
+                        return [
+                            2,
+                            response.arrayBuffer()
+                        ];
+                }
+            });
+        })();
+    };
+    return assetLoaderFromGetFn(getFn);
+}
+
+function asyncGeneratorStep$2(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$2(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _ts_generator$2(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 an {@link AssetLoader} backed by an in-memory map.
+ * Useful for testing without filesystem or network access.
+ *
+ * Assets are matched by reference identity — the same {@link AssetPathRef}
+ * object used to populate the map must be used to retrieve the data.
+ *
+ * @example
+ * ```ts
+ * const DISTRICTS = localAsset('districts.json');
+ * const loader = memoryAssetLoader(new Map([
+ *   [DISTRICTS, new TextEncoder().encode('[]').buffer]
+ * ]));
+ *
+ * loader.get(DISTRICTS).load().subscribe((data) => { ... });
+ * ```
+ *
+ * @param assets - Map of asset refs to their raw byte data.
+ */ function memoryAssetLoader(assets) {
+    var getFn = function getFn(ref) {
+        return _async_to_generator$2(function() {
+            var data;
+            return _ts_generator$2(this, function(_state) {
+                data = assets.get(ref);
+                if (!data) {
+                    throw new Error("Asset not found in memory loader: ".concat(JSON.stringify(ref)));
+                }
+                return [
+                    2,
+                    data
+                ];
+            });
+        })();
+    };
+    return assetLoaderFromGetFn(getFn);
+}
 
 function asObservable(valueOrObs) {
     if (rxjs.isObservable(valueOrObs)) {
@@ -6207,6 +6775,7 @@ function _define_property(obj, key, value) {
     };
 }
 
+exports.AssetLoader = AssetLoader;
 exports.DEFAULT_ASYNC_PUSHER_THROTTLE = DEFAULT_ASYNC_PUSHER_THROTTLE;
 exports.DEFAULT_FACTORY_TIMER_INTERVAL = DEFAULT_FACTORY_TIMER_INTERVAL;
 exports.DEFAULT_ITEM_PAGE_ITERATOR_MAX = DEFAULT_ITEM_PAGE_ITERATOR_MAX;
@@ -6232,6 +6801,9 @@ exports.areAllLoadingStatesFinishedLoading = areAllLoadingStatesFinishedLoading;
 exports.arrayValueFromFinishedLoadingState = arrayValueFromFinishedLoadingState;
 exports.asObservable = asObservable;
 exports.asObservableFromGetter = asObservableFromGetter;
+exports.assetFolder = assetFolder;
+exports.assetLoaderAssetInstance = assetLoaderAssetInstance;
+exports.assetLoaderFromGetFn = assetLoaderFromGetFn;
 exports.asyncPusher = asyncPusher;
 exports.asyncPusherCache = asyncPusherCache;
 exports.beginLoading = beginLoading;
@@ -6247,6 +6819,7 @@ exports.combineLatestMapFrom = combineLatestMapFrom;
 exports.combineLoadingStates = combineLoadingStates;
 exports.combineLoadingStatesStatus = combineLoadingStatesStatus;
 exports.currentValueFromLoadingState = currentValueFromLoadingState;
+exports.delegatedAssetLoader = delegatedAssetLoader;
 exports.distinctLoadingState = distinctLoadingState;
 exports.distinctUntilArrayLengthChanges = distinctUntilArrayLengthChanges;
 exports.distinctUntilHasDifferentValues = distinctUntilHasDifferentValues;
@@ -6265,6 +6838,7 @@ exports.errorOnEmissionsInPeriod = errorOnEmissionsInPeriod;
 exports.errorPageResult = errorPageResult;
 exports.errorResult = errorResult;
 exports.factoryTimer = factoryTimer;
+exports.fetchAssetLoader = fetchAssetLoader;
 exports.filterIfObjectValuesUnchanged = filterIfObjectValuesUnchanged;
 exports.filterItemsWithObservableDecision = filterItemsWithObservableDecision;
 exports.filterMaybe = filterMaybe;
@@ -6307,6 +6881,7 @@ exports.listLoadingStateContext = listLoadingStateContext;
 exports.loadingStateContext = loadingStateContext;
 exports.loadingStateFromObs = loadingStateFromObs;
 exports.loadingStateType = loadingStateType;
+exports.localAsset = localAsset;
 exports.makeCheckIsFunction = makeCheckIsFunction;
 exports.makeIsModifiedFunction = makeIsModifiedFunction;
 exports.makeIsModifiedFunctionObservable = makeIsModifiedFunctionObservable;
@@ -6328,6 +6903,7 @@ exports.mapMultipleLoadingStateResults = mapMultipleLoadingStateResults;
 exports.mappedPageItemIteration = mappedPageItemIteration;
 exports.maybeValueFromObservableOrValue = maybeValueFromObservableOrValue;
 exports.maybeValueFromObservableOrValueGetter = maybeValueFromObservableOrValueGetter;
+exports.memoryAssetLoader = memoryAssetLoader;
 exports.mergeLoadingStateWithError = mergeLoadingStateWithError;
 exports.mergeLoadingStateWithLoading = mergeLoadingStateWithLoading;
 exports.mergeLoadingStateWithValue = mergeLoadingStateWithValue;
@@ -6344,6 +6920,8 @@ exports.preventComplete = preventComplete;
 exports.promiseFromLoadingState = promiseFromLoadingState;
 exports.randomDelay = randomDelay;
 exports.randomDelayWithRandomFunction = randomDelayWithRandomFunction;
+exports.remoteAsset = remoteAsset;
+exports.remoteAssetBaseUrl = remoteAssetBaseUrl;
 exports.returnIfIs = returnIfIs;
 exports.scanBuildArray = scanBuildArray;
 exports.scanCount = scanCount;