@dereekb/rxjs 13.11.14 → 13.11.15

package/index.esm.js

@@ -33,14 +33,14 @@ function _class_call_check$9(instance, Constructor) {
 /**
  * Creates a local {@link AssetLocalPathRef}.
  *
+ * @param path - Relative path from the environment's base asset directory.
+ * @returns A local asset reference with the given path.
+ *
  * @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.
- * @returns A local asset reference with the given path.
  */ function localAsset(path) {
     return {
         sourceType: 'local',
@@ -53,15 +53,15 @@ function _class_call_check$9(instance, Constructor) {
  * Remote assets always use absolute URLs with an http:// or https:// prefix.
  * Throws if the provided URL does not have a valid prefix.
  *
+ * @param url - Absolute URL with http/https prefix to fetch the asset from.
+ * @returns A remote asset reference with the given URL.
+ * @throws {Error} If the URL does not have a valid http/https 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.
- * @returns A remote asset reference with the given URL.
- * @throws Error if the URL does not have a valid http/https prefix.
  */ function remoteAsset(url) {
     if (!isWebsiteUrlWithPrefix(url)) {
         throw new Error('remoteAsset() requires a URL with http:// or https:// prefix, got: "'.concat(url, '"'));
@@ -75,6 +75,9 @@ function _class_call_check$9(instance, Constructor) {
  * Creates a fluent builder for creating multiple local asset refs
  * from the same folder.
  *
+ * @param folder - Base folder path for the assets.
+ * @returns A fluent builder for creating local asset refs within the specified folder.
+ *
  * @example
  * ```ts
  * const DATA = assetFolder('data');
@@ -88,9 +91,6 @@ function _class_call_check$9(instance, Constructor) {
  * //   { sourceType: 'local', path: 'data/b.txt' }
  * // ]
  * ```
- *
- * @param folder - Base folder path for the assets.
- * @returns A fluent builder for creating local asset refs within the specified folder.
  */ function assetFolder(folder) {
     var normalizedFolder = folder.endsWith('/') ? folder : folder + '/';
     var builder = {
@@ -112,6 +112,10 @@ function _class_call_check$9(instance, Constructor) {
  * The base URL must be a valid {@link WebsiteUrlWithPrefix}.
  * Each child path is appended to produce a full absolute URL.
  *
+ * @param baseUrl - Base URL with http/https prefix.
+ * @returns A fluent builder for creating remote asset refs under the specified base URL.
+ * @throws {Error} If the base URL does not have a valid http/https prefix.
+ *
  * @example
  * ```ts
  * const CDN = remoteAssetBaseUrl('https://cdn.example.com/assets');
@@ -125,10 +129,6 @@ function _class_call_check$9(instance, Constructor) {
  * //   { sourceType: 'remote', url: 'https://cdn.example.com/assets/b.json' }
  * // ]
  * ```
- *
- * @param baseUrl - Base URL with http/https prefix.
- * @returns A fluent builder for creating remote asset refs under the specified base URL.
- * @throws Error if the base URL does not have a valid http/https prefix.
  */ function remoteAssetBaseUrl(baseUrl) {
     if (!isWebsiteUrlWithPrefix(baseUrl)) {
         throw new Error('remoteAssetBaseUrl() requires a URL with http:// or https:// prefix, got: "'.concat(baseUrl, '"'));
@@ -156,15 +156,15 @@ function _class_call_check$9(instance, Constructor) {
  * The returned {@link AssetLoaderAssetInstance.load} observable is cold — each subscription
  * invokes the get function anew.
  *
+ * @param ref - The asset path reference this instance represents.
+ * @param getFn - Promise-based function that loads the asset bytes.
+ * @returns An {@link AssetLoaderAssetInstance} with a cold observable that invokes getFn on each subscription.
+ *
  * @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.
- * @returns An {@link AssetLoaderAssetInstance} with a cold observable that invokes getFn on each subscription.
  */ function assetLoaderAssetInstance(ref, getFn) {
     return {
         ref: function ref1() {
@@ -183,6 +183,9 @@ function _class_call_check$9(instance, Constructor) {
  * This is the primary helper for building functional AssetLoader implementations
  * from a Promise-based leaf loader.
  *
+ * @param getFn - Promise-based function that loads any asset's bytes.
+ * @returns An {@link AssetLoader} that creates instances using the provided get function.
+ *
  * @example
  * ```ts
  * const loader = assetLoaderFromGetFn(async (ref) => {
@@ -190,9 +193,6 @@ function _class_call_check$9(instance, Constructor) {
  *   return response.arrayBuffer();
  * });
  * ```
- *
- * @param getFn - Promise-based function that loads any asset's bytes.
- * @returns An {@link AssetLoader} that creates instances using the provided get function.
  */ function assetLoaderFromGetFn(getFn) {
     var loader = {
         get: function get(ref) {
@@ -209,6 +209,9 @@ function _class_call_check$9(instance, Constructor) {
  * loader together, and the delegated loader routes each {@link AssetPathRef}
  * to the correct one based on {@link AssetPathRef.sourceType}.
  *
+ * @param config - Specifies the local and remote delegate loaders.
+ * @returns An {@link AssetLoader} that routes requests to the appropriate delegate based on source type.
+ *
  * @example
  * ```ts
  * const loader = delegatedAssetLoader({
@@ -219,9 +222,6 @@ function _class_call_check$9(instance, Constructor) {
  * 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.
- * @returns An {@link AssetLoader} that routes requests to the appropriate delegate based on source type.
  */ function delegatedAssetLoader(config) {
     var local = config.local, remote = config.remote;
     var loader = {
@@ -367,6 +367,9 @@ function _ts_generator$3(thisArg, body) {
  *
  * Remote refs always have absolute URLs, so no base URL resolution is needed.
  *
+ * @param config - Optional fetch configuration with custom fetch function.
+ * @returns An {@link AssetLoader} that loads remote assets via HTTP fetch.
+ *
  * @example
  * ```ts
  * const loader = fetchAssetLoader();
@@ -377,9 +380,6 @@ function _ts_generator$3(thisArg, body) {
  * // With a custom fetch function:
  * const loader = fetchAssetLoader({ fetch: myAuthenticatedFetch });
  * ```
- *
- * @param config - Optional fetch configuration with custom fetch function.
- * @returns An {@link AssetLoader} that loads remote assets via HTTP fetch.
  */ function fetchAssetLoader() {
     var config = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _config_fetch;
@@ -547,6 +547,9 @@ function _ts_generator$2(thisArg, body) {
  * Assets are matched by reference identity — the same {@link AssetPathRef}
  * object used to populate the map must be used to retrieve the data.
  *
+ * @param assets - Map of asset refs to their raw byte data.
+ * @returns An {@link AssetLoader} backed by the provided in-memory map.
+ *
  * @example
  * ```ts
  * const DISTRICTS = localAsset('districts.json');
@@ -556,9 +559,6 @@ function _ts_generator$2(thisArg, body) {
  *
  * loader.get(DISTRICTS).load().subscribe((data) => { ... });
  * ```
- *
- * @param assets - Map of asset refs to their raw byte data.
- * @returns An {@link AssetLoader} backed by the provided in-memory map.
  */ function memoryAssetLoader(assets) {
     var getFn = function getFn(ref) {
         return _async_to_generator$2(function() {
@@ -584,7 +584,7 @@ function asObservable(valueOrObs) {
 /**
  * RxJS operator that flattens an emitted {@link ObservableOrValue} into its unwrapped value via `switchMap`.
  *
- * @returns an operator that unwraps ObservableOrValue emissions
+ * @returns An operator that unwraps ObservableOrValue emissions.
  */ function valueFromObservableOrValue() {
     return switchMap(function(x) {
         return asObservable(x);
@@ -594,7 +594,7 @@ function asObservable(valueOrObs) {
  * RxJS operator that flattens an emitted Maybe<{@link ObservableOrValue}> into its unwrapped value,
  * emitting `undefined` when the input is nullish.
  *
- * @returns an operator that unwraps Maybe<ObservableOrValue> emissions
+ * @returns An operator that unwraps Maybe<ObservableOrValue> emissions.
  */ function maybeValueFromObservableOrValue() {
     return switchMap(function(x) {
         return x != null ? asObservable(x) : of(undefined);
@@ -607,7 +607,7 @@ function asObservableFromGetter(input, args) {
 /**
  * RxJS operator that flattens an emitted {@link ObservableOrValueGetter} into its resolved value via `switchMap`.
  *
- * @returns an operator that unwraps getter emissions
+ * @returns An operator that unwraps getter emissions.
  */ function valueFromObservableOrValueGetter() {
     return switchMap(function(x) {
         return asObservableFromGetter(x);
@@ -617,7 +617,7 @@ function asObservableFromGetter(input, args) {
  * RxJS operator that flattens an emitted Maybe<{@link ObservableOrValueGetter}> into its resolved value,
  * emitting `undefined` when the input is nullish.
  *
- * @returns an operator that unwraps Maybe<ObservableOrValueGetter> emissions, emitting undefined for nullish inputs
+ * @returns An operator that unwraps Maybe<ObservableOrValueGetter> emissions, emitting undefined for nullish inputs.
  */ function maybeValueFromObservableOrValueGetter() {
     return switchMap(function(x) {
         return x != null ? asObservableFromGetter(x) : of(undefined);
@@ -676,8 +676,9 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * Creates an {@link IsModifiedFunction} by inverting the result of an {@link IsEqualFunction}.
  *
- * @param isEqualFunction - equality check function to invert
- * @returns a function that returns true when the value has been modified
+ * @param isEqualFunction - Equality check function to invert.
+ * @returns Predicate that reports true whenever the underlying equality check signals inequality.
+ *
  * @__NO_SIDE_EFFECTS__
  */ function makeIsModifiedFunction(isEqualFunction) {
     return function(value) {
@@ -692,8 +693,9 @@ function _unsupported_iterable_to_array$b(o, minLen) {
  * Prefers `isModified` over `isEqual` (which is inverted), falling back to `defaultFunction`
  * or a function that always returns true.
  *
- * @param config - configuration with isModified, isEqual, and/or defaultFunction
- * @returns an observable of the resolved IsModifiedFunction
+ * @param config - Configuration with isModified, isEqual, and/or defaultFunction.
+ * @returns An observable of the resolved IsModifiedFunction.
+ *
  * @__NO_SIDE_EFFECTS__
  */ function makeIsModifiedFunctionObservable(config) {
     var isModified = config.isModified, isEqual = config.isEqual, defaultFunction = config.defaultFunction;
@@ -712,9 +714,10 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * Creates a function that returns the value if the check function returns true, otherwise undefined.
  *
- * @param isCheckFunction - optional check function
- * @param defaultValueOnMaybe - default result for null/undefined values
- * @returns a function that evaluates each value against the check function and returns it or undefined
+ * @param isCheckFunction - Optional check function.
+ * @param defaultValueOnMaybe - Default result for null/undefined values.
+ * @returns Function that yields the input value when it passes the check, or undefined otherwise.
+ *
  * @__NO_SIDE_EFFECTS__
  */ function makeReturnIfIsFunction(isCheckFunction, defaultValueOnMaybe) {
     return function(value) {
@@ -724,10 +727,10 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * Returns the value wrapped in an observable if the check function passes, otherwise emits undefined.
  *
- * @param isCheckFunction - optional check function
- * @param value - the value to check
- * @param defaultValueOnMaybe - default result for null/undefined values
- * @returns an observable that emits the value if the check passes, or undefined otherwise
+ * @param isCheckFunction - Optional check function.
+ * @param value - The value to check.
+ * @param defaultValueOnMaybe - Default result for null/undefined values.
+ * @returns An observable that emits the value if the check passes, or undefined otherwise.
  */ function returnIfIs(isCheckFunction, value, defaultValueOnMaybe) {
     return checkIs(isCheckFunction, value, defaultValueOnMaybe).pipe(map(function(x) {
         return x ? value : undefined;
@@ -736,9 +739,10 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * Creates a function that checks a value against the check function and returns an observable boolean.
  *
- * @param isCheckFunction - optional check function
- * @param defaultValueOnMaybe - default result for null/undefined values
- * @returns a function that evaluates each value against the check function and returns an observable boolean
+ * @param isCheckFunction - Optional check function.
+ * @param defaultValueOnMaybe - Default result for null/undefined values.
+ * @returns Function that emits whether the supplied value passes the check, falling back to the default for missing values.
+ *
  * @__NO_SIDE_EFFECTS__
  */ function makeCheckIsFunction(isCheckFunction, defaultValueOnMaybe) {
     return function(value) {
@@ -750,10 +754,10 @@ function _unsupported_iterable_to_array$b(o, minLen) {
  *
  * Returns `of(true)` when no check function is provided.
  *
- * @param isCheckFunction - optional check function
- * @param value - the value to check
- * @param defaultValueOnMaybe - default result for null/undefined values (defaults to false)
- * @returns an observable boolean indicating whether the value passes the check
+ * @param isCheckFunction - Optional check function.
+ * @param value - The value to check.
+ * @param defaultValueOnMaybe - Default result for null/undefined values (defaults to false)
+ * @returns An observable boolean indicating whether the value passes the check.
  */ function checkIs(isCheckFunction, value) {
     var defaultValueOnMaybe = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : false;
     var is = isCheckFunction ? value != null ? isCheckFunction(value) : of(defaultValueOnMaybe) : of(true);
@@ -763,7 +767,7 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * RxJS operator that filters out null and undefined values, only passing through defined values.
  *
- * @returns operator that filters out null and undefined emissions
+ * @returns Operator that filters out null and undefined emissions.
  */ function filterMaybe() {
     return filter(isMaybeSo);
 }
@@ -773,14 +777,14 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * RxJS operator that filters out null/undefined elements from an emitted array, keeping only defined values.
  *
- * @returns operator that maps each emitted array to a version with null/undefined elements removed
+ * @returns Operator that maps each emitted array to a version with null/undefined elements removed.
  */ function filterMaybeArray() {
     return map(filterMaybeArrayValues);
 }
 /**
  * RxJS operator that skips all leading null/undefined emissions, then passes all subsequent values through.
  *
- * @returns operator that skips all null/undefined emissions at the start of the stream
+ * @returns Operator that skips all null/undefined emissions at the start of the stream.
  */ function skipAllInitialMaybe() {
     return skipWhile(function(x) {
         return x == null;
@@ -789,15 +793,15 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * RxJS operator that skips only the first emission if it is null/undefined, then passes all subsequent values.
  *
- * @returns operator that skips the first null/undefined emission if it occurs at the start of the stream
+ * @returns Operator that skips the first null/undefined emission if it occurs at the start of the stream.
  */ function skipInitialMaybe() {
     return skipMaybes(1);
 }
 /**
  * RxJS operator that skips up to `maxToSkip` null/undefined emissions, then passes all subsequent values.
  *
- * @param maxToSkip - maximum number of null/undefined emissions to skip
- * @returns operator that skips the first N null/undefined emissions from the stream
+ * @param maxToSkip - Maximum number of null/undefined emissions to skip.
+ * @returns Operator that skips the first N null/undefined emissions from the stream.
  */ function skipMaybes(maxToSkip) {
     return skipWhile(function(x, i) {
         return x == null && i < maxToSkip;
@@ -806,8 +810,8 @@ function _unsupported_iterable_to_array$b(o, minLen) {
 /**
  * RxJS operator that switches to the emitted observable if defined, or emits the default value if null/undefined.
  *
- * @param defaultValue - fallback value when the observable is nullish (defaults to undefined)
- * @returns an operator that handles optional observables
+ * @param defaultValue - Fallback value when the observable is nullish (defaults to undefined)
+ * @returns An operator that handles optional observables.
  */ function switchMapMaybeDefault() {
     var defaultValue = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : undefined;
     return switchMap(function(x) {
@@ -828,8 +832,8 @@ function switchMapToDefault(defaultObs, useDefault) {
  * RxJS operator that resolves an observable/getter config input into a value, applying defaults
  * for `null`/`undefined`/`true` inputs and emitting `null` for `false`.
  *
- * @param config - configuration providing an optional default getter for null/undefined/true inputs
- * @returns operator that resolves each emitted getter into a value, using the default for nullish or true inputs
+ * @param config - Configuration providing an optional default getter for null/undefined/true inputs.
+ * @returns Operator that resolves each emitted getter into a value, using the default for nullish or true inputs.
  */ function switchMapObject(config) {
     var defaultGetter = config.defaultGetter;
     return switchMap(function(inputConfig) {
@@ -853,10 +857,13 @@ function switchMapWhileFalse(obs, otherwise) {
 }
 function switchMapOnBoolean(switchOnValue, obs, otherwise) {
     return switchMap(function(x) {
+        var result;
         if (x === switchOnValue) {
-            return asObservableFromGetter(obs);
+            result = asObservableFromGetter(obs);
+        } else {
+            result = otherwise == null ? EMPTY : asObservableFromGetter(otherwise);
         }
-        return otherwise == null ? EMPTY : asObservableFromGetter(otherwise);
+        return result;
     });
 }
 /**
@@ -864,7 +871,7 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
  *
  * Combines {@link filterMaybe} and `switchMap` to only subscribe to non-nullish observables.
  *
- * @returns operator that filters nullish observables and subscribes to the non-nullish ones
+ * @returns Operator that filters nullish observables and subscribes to the non-nullish ones.
  */ function switchMapFilterMaybe() {
     return function(source) {
         var subscriber = source.pipe(filterMaybe(), switchMap(function(x) {
@@ -876,7 +883,7 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
 /**
  * RxJS operator that switches to the emitted observable if defined, or emits `undefined` when the observable is nullish.
  *
- * @returns operator that switches to the emitted observable or emits undefined for null/undefined inputs
+ * @returns Operator that switches to the emitted observable or emits undefined for null/undefined inputs.
  */ function switchMapMaybe() {
     return function(source) {
         var subscriber = source.pipe(switchMap(function(x) {
@@ -888,17 +895,17 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
 /**
  * RxJS operator that applies a map function only when the emitted value is non-null/non-undefined.
  *
- * @param mapFn - function to transform defined values
- * @returns an operator that maps defined values and passes through undefined
+ * @param mapFn - Function to transform defined values.
+ * @returns An operator that maps defined values and passes through undefined.
  */ function mapMaybe(mapFn) {
     return mapIf(mapFn, isMaybeSo);
 }
 /**
  * RxJS operator that applies a map function only when the decision function returns true.
  *
- * @param mapFn - function to transform the value
- * @param decision - predicate that determines whether to apply the map
- * @returns an operator that conditionally maps values
+ * @param mapFn - Function to transform the value.
+ * @param decision - Predicate that determines whether to apply the map.
+ * @returns An operator that conditionally maps values.
  */ function mapIf(mapFn, decision) {
     return map(function(x) {
         return decision(x) ? mapFn(x) : undefined;
@@ -907,9 +914,9 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
 /**
  * Combines the source observable with another observable via `combineLatest`, then maps the pair to a result.
  *
- * @param combineObs - the secondary observable to combine with the source
- * @param mapFn - function that maps the source value and combined value to the output
- * @returns operator that combines the source with `combineObs` and maps each pair using `mapFn`
+ * @param combineObs - The secondary observable to combine with the source.
+ * @param mapFn - Function that maps the source value and combined value to the output.
+ * @returns Operator that combines the source with `combineObs` and maps each pair using `mapFn`
  */ function combineLatestMapFrom(combineObs, mapFn) {
     return function(obs) {
         return combineLatest([
@@ -926,10 +933,10 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
  *
  * If the delay is not provided, or is falsy, then the second value is never emitted.
  *
- * @param startWith - the value to emit immediately
- * @param endWith - the value to emit after the delay
- * @param delayTime - optional delay in milliseconds before emitting the second value
- * @returns an observable that emits `startWith` immediately and `endWith` after the delay (if provided)
+ * @param startWith - The value to emit immediately.
+ * @param endWith - The value to emit after the delay.
+ * @param delayTime - Optional delay in milliseconds before emitting the second value.
+ * @returns An observable that emits `startWith` immediately and `endWith` after the delay (if provided)
  */ function emitDelayObs(startWith, endWith, delayTime) {
     var obs = of(startWith);
     if (delayTime) {
@@ -940,9 +947,9 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
 /**
  * Emits a value after a given delay after every new emission.
  *
- * @param value - the value to emit after the delay
- * @param delayTime - duration in milliseconds before emitting the value
- * @returns operator that appends the given value after each source emission with the specified delay
+ * @param value - The value to emit after the delay.
+ * @param delayTime - Duration in milliseconds before emitting the value.
+ * @returns Operator that appends the given value after each source emission with the specified delay.
  */ function emitAfterDelay(value, delayTime) {
     return function(obs) {
         return obs.pipe(switchMap(function(x) {
@@ -957,7 +964,7 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
  * Uses {@link areEqualPOJOValues} for comparison, so the emitted objects should be plain objects
  * or compatible with deep value equality checks.
  *
- * @returns operator that filters out consecutive duplicate POJO emissions
+ * @returns Operator that filters out consecutive duplicate POJO emissions.
  *
  * @example
  * ```ts
@@ -1067,7 +1074,7 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             get: /**
      * Whether a subscription is currently being managed.
      *
-     * @returns true if a subscription is currently active
+     * @returns True if a subscription is currently active.
      */ function get() {
                 return Boolean(this._subscription);
             }
@@ -1084,7 +1091,7 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             /**
      * Replaces the current subscription with the given one, unsubscribing from the previous.
      *
-     * @param sub - new subscription to manage, or `undefined`/`void` to just unsubscribe
+     * @param sub - New subscription to manage, or `undefined`/`void` to just unsubscribe.
      */ key: "setSub",
             value: function setSub(sub) {
                 this.unsub();
@@ -1148,7 +1155,7 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             get: /**
      * Whether any subscriptions are currently being managed.
      *
-     * @returns true if one or more subscriptions are currently active
+     * @returns True if one or more subscriptions are currently active.
      */ function get() {
                 var _this__subscriptions;
                 return Boolean((_this__subscriptions = this._subscriptions) === null || _this__subscriptions === void 0 ? void 0 : _this__subscriptions.length);
@@ -1166,7 +1173,7 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             /**
      * Replaces all managed subscriptions with the given ones, unsubscribing from all previous.
      *
-     * @param subs - new subscription(s) to manage
+     * @param subs - New subscription(s) to manage.
      */ key: "setSubs",
             value: function setSubs(subs) {
                 this.unsub();
@@ -1177,7 +1184,7 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             /**
      * Adds subscription(s) to the managed set without affecting existing ones. Duplicate subscriptions are ignored.
      *
-     * @param subs - subscription(s) to add
+     * @param subs - Subscription(s) to add.
      */ key: "addSubs",
             value: function addSubs(subs) {
                 var _this__subscriptions;
@@ -1360,7 +1367,7 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             /**
      * Sets an initial filter observable that takes priority over the default filter.
      *
-     * @param filterObs - observable providing the initial filter value
+     * @param filterObs - Observable providing the initial filter value.
      */ key: "initWithFilter",
             value: function initWithFilter(filterObs) {
                 this._initialFilter.next(filterObs);
@@ -1371,7 +1378,7 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             /**
      * Sets the default filter, used as a fallback when no explicit or initial filter is active.
      *
-     * @param filter - default filter value, observable, or undefined to clear
+     * @param filter - Default filter value, observable, or undefined to clear.
      */ key: "setDefaultFilter",
             value: function setDefaultFilter(filter) {
                 this._defaultFilter.next(asObservable(filter));
@@ -1381,7 +1388,7 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             /**
      * Sets an explicit filter value that takes priority over the initial and default filters.
      *
-     * @param filter - the filter value to set
+     * @param filter - The filter value to set.
      */ key: "setFilter",
             value: function setFilter(filter) {
                 this._filter.next(filter);
@@ -1402,7 +1409,7 @@ function _unsupported_iterable_to_array$9(o, minLen) {
      * When enabled, any new emission from the initial filter observable clears the explicit
      * filter, causing `filter$` to fall back to the initial filter value.
      *
-     * @param initialFilterTakesPriority - whether initial filter changes should reset the explicit filter
+     * @param initialFilterTakesPriority - Whether initial filter changes should reset the explicit filter.
      */ key: "setInitialFilterTakesPriority",
             value: function setInitialFilterTakesPriority(initialFilterTakesPriority) {
                 this._initialFilterTakesPriority.next(initialFilterTakesPriority);
@@ -1416,15 +1423,18 @@ function _unsupported_iterable_to_array$9(o, minLen) {
                 var _this = this;
                 var _this__initialFilterSub, _subscription;
                 (_subscription = (_this__initialFilterSub = this._initialFilterSub).subscription) !== null && _subscription !== void 0 ? _subscription : _this__initialFilterSub.subscription = this._initialFilterTakesPriority.pipe(switchMap(function(clearFilterOnInitialFilterPush) {
+                    var result;
                     if (clearFilterOnInitialFilterPush) {
-                        return _this._initialFilter.pipe(switchMap(function(x) {
+                        result = _this._initialFilter.pipe(switchMap(function(x) {
                             return x !== null && x !== void 0 ? x : EMPTY;
                         }), filterMaybe(), map(function() {
                             return true;
                         }), skip(1) // skip the first emission
                         );
+                    } else {
+                        result = EMPTY;
                     }
-                    return EMPTY;
+                    return result;
                 }), defaultIfEmpty(false)).subscribe(function(clear) {
                     if (clear) {
                         _this.resetFilter();
@@ -1534,8 +1544,8 @@ function _unsupported_iterable_to_array$8(o, minLen) {
      *
      * Waits until a filter entry exists for the key, then switches to its filter stream.
      *
-     * @param key - filter map key to observe
-     * @returns observable that emits the current filter value for the key
+     * @param key - Filter map key to observe.
+     * @returns Observable that emits the current filter value for the key.
      */ key: "filterForKey",
             value: function filterForKey(key) {
                 return this._map.pipe(map(function(x) {
@@ -1549,8 +1559,8 @@ function _unsupported_iterable_to_array$8(o, minLen) {
             /**
      * Sets a default filter observable for the given key, used as a fallback when no explicit filter is set.
      *
-     * @param key - filter map key
-     * @param obs - default filter observable or value
+     * @param key - Filter map key.
+     * @param obs - Default filter observable or value.
      */ key: "addDefaultFilterObs",
             value: function addDefaultFilterObs(key, obs) {
                 this._itemForKey(key).setDefaultFilterObs(obs);
@@ -1561,8 +1571,8 @@ function _unsupported_iterable_to_array$8(o, minLen) {
      * Adds a filter observable for the given key. Multiple observables can be added per key
      * and their emissions are merged together.
      *
-     * @param key - filter map key
-     * @param obs - filter observable to add
+     * @param key - Filter map key.
+     * @param obs - Filter observable to add.
      */ key: "addFilterObs",
             value: function addFilterObs(key, obs) {
                 this._itemForKey(key).addFilterObs(obs);
@@ -1573,8 +1583,8 @@ function _unsupported_iterable_to_array$8(o, minLen) {
      * Creates a {@link FilterMapKeyInstance} bound to the given key, providing both
      * {@link FilterSource} and {@link FilterSourceConnector} interfaces for that key.
      *
-     * @param key - filter map key to bind
-     * @returns instance for interacting with the filter at the given key
+     * @param key - Filter map key to bind.
+     * @returns Instance for interacting with the filter at the given key.
      */ key: "makeInstance",
             value: function makeInstance(key) {
                 return new FilterMapKeyInstance(this, key);
@@ -1584,8 +1594,8 @@ function _unsupported_iterable_to_array$8(o, minLen) {
             /**
      * Creates an observable that emits a new {@link FilterMapKeyInstance} each time the key changes.
      *
-     * @param keyObs - observable of filter map keys
-     * @returns observable that emits instances for the current key
+     * @param keyObs - Observable of filter map keys.
+     * @returns Observable that emits instances for the current key.
      */ key: "instanceObsForKeyObs",
             value: function instanceObsForKeyObs(keyObs) {
                 var _this = this;
@@ -1655,7 +1665,7 @@ function _unsupported_iterable_to_array$8(o, minLen) {
             /**
      * Sets the default filter observable for this key.
      *
-     * @param filterObs - the observable to use as the default filter for this key
+     * @param filterObs - The observable to use as the default filter for this key.
      */ key: "initWithFilter",
             value: function initWithFilter(filterObs) {
                 this.dbxFilterMap.addDefaultFilterObs(this.key, filterObs);
@@ -1665,7 +1675,7 @@ function _unsupported_iterable_to_array$8(o, minLen) {
             /**
      * Connects a filter source, adding its filter observable to this key's merged filters.
      *
-     * @param filterSource - the filter source whose filter$ will be added to this key's merged stream
+     * @param filterSource - The filter source whose filter$ will be added to this key's merged stream.
      */ key: "connectWithSource",
             value: function connectWithSource(filterSource) {
                 this.dbxFilterMap.addFilterObs(this.key, filterSource.filter$);
@@ -1774,8 +1784,8 @@ var FilterMapItem = /*#__PURE__*/ function() {
  * into concrete filter values, then the `preset` field is removed from the result.
  * Filters without a preset are passed through unchanged.
  *
- * @param fn - function that expands a preset into concrete filter values
- * @returns mapping function that resolves presets and strips the preset field
+ * @param fn - Function that expands a preset into concrete filter values.
+ * @returns Mapping function that resolves presets and strips the preset field.
  *
  * @example
  * ```ts
@@ -1791,22 +1801,26 @@ var FilterMapItem = /*#__PURE__*/ function() {
  * const result = resolve({ preset: 'active' });
  * // result === { active: true }
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */ function makeMapFilterWithPresetFn(fn) {
     return function(filter) {
+        var result;
         if (filter.preset) {
-            var result = fn(filter);
-            delete result.preset;
-            return result;
+            var expanded = fn(filter);
+            delete expanded.preset;
+            result = expanded;
+        } else {
+            result = filter;
         }
-        return filter;
+        return result;
     };
 }
 /**
  * RxJS operator that resolves preset references in a filter stream using the provided mapping function.
  *
- * @param fn - function that expands a preset into concrete filter values
- * @returns operator that maps filter emissions, resolving any preset references
+ * @param fn - Function that expands a preset into concrete filter values.
+ * @returns Operator that maps filter emissions, resolving any preset references.
  */ function mapFilterWithPreset(fn) {
     return map(makeMapFilterWithPresetFn(fn));
 }
@@ -2031,8 +2045,8 @@ function _ts_generator$1(thisArg, body) {
  * Combines an iteration's `hasNext$` and `canLoadMore$` into a single observable that emits
  * `true` only when both conditions are met (more items exist and the page limit hasn't been reached).
  *
- * @param iteration - the iteration to check
- * @returns observable that emits `true` when more items can be loaded
+ * @param iteration - The iteration to check.
+ * @returns Observable that emits `true` when more items can be loaded.
  */ function iterationHasNextAndCanLoadMore(iteration) {
     return iteration.canLoadMore$.pipe(switchMap(function(canLoadMore) {
         return canLoadMore ? iteration.hasNext$ : of(false);
@@ -2043,12 +2057,11 @@ function _ts_generator$1(thisArg, body) {
  *
  * Falls back to the provided default limit if no max is configured on the iterator.
  *
- * @param iterator - the page iteration to advance
- * @param defaultLimit - fallback page limit if none is configured (defaults to 100)
- * @returns promise resolving to the last loaded page number
- *
- * @throws {Error} If neither a max page load limit nor a default limit is defined
- * @throws Rejects if the iteration encounters a loading error
+ * @param iterator - The page iteration to advance.
+ * @param defaultLimit - Fallback page limit if none is configured (defaults to 100)
+ * @returns Promise resolving to the last loaded page number.
+ * @throws {Error} If neither a max page load limit nor a default limit is defined.
+ * @throws {Error} Rejects if the iteration encounters a loading error.
  */ function iteratorNextPageUntilMaxPageLoadLimit(iterator) {
     var defaultLimit = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 100;
     return iteratorNextPageUntilPage(iterator, function() {
@@ -2064,11 +2077,10 @@ function _ts_generator$1(thisArg, body) {
  * Automatically pages through a {@link PageItemIteration} until the specified page number is reached,
  * respecting the iteration's max page load limit.
  *
- * @param iteration - the page iteration to advance
- * @param page - target page number (or getter returning one) representing total pages to load
- * @returns promise resolving to the last loaded page number
- *
- * @throws Rejects if the iteration encounters a loading error
+ * @param iteration - The page iteration to advance.
+ * @param page - Target page number (or getter returning one) representing total pages to load.
+ * @returns Promise resolving to the last loaded page number.
+ * @throws {Error} Rejects if the iteration encounters a loading error.
  */ function iteratorNextPageUntilPage(iteration, page) {
     var getPageLimit = asGetter(page);
     function checkPageLimit(page) {
@@ -2170,8 +2182,8 @@ function scanIntoArray() {
  * are incrementally appended. Useful when loading large datasets where the initial page and
  * subsequent pages come from different sources.
  *
- * @param init - function that receives the seed state and returns the accumulator config
- * @returns an operator that emits the growing array
+ * @param init - Function that receives the seed state and returns the accumulator config.
+ * @returns An operator that emits the growing array.
  */ function scanBuildArray(init) {
     return exhaustMap(function(seedState) {
         var _init = init(seedState), _init_seed = _init.seed, seed = _init_seed === void 0 ? [] : _init_seed, accumulatorObs = _init.accumulatorObs, _init_flattenArray = _init.flattenArray, flattenArray = _init_flattenArray === void 0 ? false : _init_flattenArray;
@@ -2193,8 +2205,8 @@ function scanIntoArray() {
 /**
  * RxJS operator that executes a side-effect on each element of the emitted array, then passes the array through.
  *
- * @param forEach - callback to run for each element, or null/undefined to pass through unchanged
- * @returns an operator that taps each element in emitted arrays
+ * @param forEach - Callback to run for each element, or null/undefined to pass through unchanged.
+ * @returns An operator that taps each element in emitted arrays.
  */ function mapForEach(forEach) {
     return forEach ? map(function(x) {
         return forEachWithArray(x, forEach);
@@ -2208,21 +2220,24 @@ function scanIntoArray() {
  *
  * Emits `[]` for empty arrays. When `onlyFirst` is true, takes only the first combined emission.
  *
- * @param mapFunction - function that maps each item to an ObservableInput
- * @param config - optional config (e.g., `onlyFirst`)
- * @returns an operator that async-maps each array element
+ * @param mapFunction - Function that maps each item to an ObservableInput.
+ * @param config - Optional config (e.g., `onlyFirst`)
+ * @returns An operator that async-maps each array element.
  */ function mapEachAsync(mapFunction, config) {
     var _ref = config !== null && config !== void 0 ? config : {}, _ref_onlyFirst = _ref.onlyFirst, onlyFirst = _ref_onlyFirst === void 0 ? false : _ref_onlyFirst;
     return switchMap(function(values) {
+        var result;
         if (values.length) {
             var mappedObs = values.map(mapFunction);
-            var result = combineLatest(mappedObs);
+            var combined = combineLatest(mappedObs);
             if (onlyFirst) {
-                result = result.pipe(first());
+                combined = combined.pipe(first());
             }
-            return result;
+            result = combined;
+        } else {
+            result = of([]);
         }
-        return of([]);
+        return result;
     });
 }
 
@@ -2232,6 +2247,9 @@ function scanIntoArray() {
  * The `from` value must be seen first; only then is the `to` value emitted. When `requireConsecutive`
  * is true, the two values must be adjacent emissions.
  *
+ * @param config - From/to values, optional comparator, and consecutive requirement.
+ * @returns An operator that emits on value transitions.
+ *
  * @example
  * ```ts
  * // Emit when transitioning from true to false
@@ -2239,9 +2257,6 @@ function scanIntoArray() {
  *   onMatchDelta({ from: true, to: false, requireConsecutive: true })
  * ).subscribe((val) => console.log('Transitioned to false'));
  * ```
- *
- * @param config - from/to values, optional comparator, and consecutive requirement
- * @returns an operator that emits on value transitions
  */ function onMatchDelta(config) {
     var inputIsSame = config.isMatch, from = config.from, to = config.to, requireConsecutive = config.requireConsecutive;
     var isMatch = inputIsSame !== null && inputIsSame !== void 0 ? inputIsSame : function(a, b) {
@@ -2300,16 +2315,16 @@ function scanIntoArray() {
 /**
  * Conditionally applies an operator. Returns the given pipe when `usePipe` is true, otherwise returns identity (pass-through).
  *
- * @param usePipe - whether to apply the pipe
- * @param pipe - the operator to conditionally apply
- * @returns the pipe or identity operator
+ * @param usePipe - Whether to apply the pipe.
+ * @param pipe - The operator to conditionally apply.
+ * @returns The pipe or identity operator.
  */ function pipeIf(usePipe, pipe) {
     return usePipe ? pipe : identity;
 }
 /**
  * RxJS operator that negates each emitted boolean value.
  *
- * @returns operator that maps each boolean emission to its negated value
+ * @returns Operator that maps each boolean emission to its negated value.
  */ function isNot() {
     return map(function(x) {
         return !x;
@@ -2318,7 +2333,7 @@ function scanIntoArray() {
 /**
  * RxJS operator that only emits when a boolean stream transitions from `true` to `false`.
  *
- * @returns operator that filters to only true-to-false transition emissions
+ * @returns Operator that filters to only true-to-false transition emissions.
  */ function onTrueToFalse() {
     return onMatchDelta({
         from: true,
@@ -2329,7 +2344,7 @@ function scanIntoArray() {
 /**
  * RxJS operator that only emits when a boolean stream transitions from `false` to `true`.
  *
- * @returns operator that filters to only false-to-true transition emissions
+ * @returns Operator that filters to only false-to-true transition emissions.
  */ function onFalseToTrue() {
     return onMatchDelta({
         from: false,
@@ -2343,9 +2358,9 @@ function scanIntoArray() {
  *
  * When `invert` is false, returns the original function unchanged.
  *
- * @param decisionFn - the decision function to invert
- * @param invert - whether to apply the inversion (defaults to true)
- * @returns the inverted (or original) decision function
+ * @param decisionFn - The decision function to invert.
+ * @param invert - Whether to apply the inversion (defaults to true)
+ * @returns The inverted (or original) decision function.
  */ function invertObservableDecision(decisionFn) {
     var invert = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : true;
     return invert ? function(value) {
@@ -2361,9 +2376,9 @@ function scanIntoArray() {
  * Items where the decision returns true are kept; others are removed. Results are throttled
  * to prevent excessive re-emissions.
  *
- * @param observableDecisionFunction - async predicate to evaluate each item
- * @param throttle - throttle duration in ms (defaults to 20)
- * @returns an operator that async-filters array elements
+ * @param observableDecisionFunction - Async predicate to evaluate each item.
+ * @param throttle - Throttle duration in ms (defaults to 20)
+ * @returns An operator that async-filters array elements.
  */ function filterItemsWithObservableDecision(observableDecisionFunction) {
     var throttle = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 20;
     var filterAndMap = filterAndMapFunction(function(x) {
@@ -2397,8 +2412,8 @@ function scanIntoArray() {
  * RxJS operator that maps each emission to a new {@link Expires} object with an expiration
  * time relative to the current moment.
  *
- * @param expiresIn - duration in milliseconds until expiration
- * @returns an `OperatorFunction` that maps each emission to an {@link Expires} object
+ * @param expiresIn - Duration in milliseconds until expiration.
+ * @returns An `OperatorFunction` that maps each emission to an {@link Expires} object.
  */ function toExpiration(expiresIn) {
     return map(function() {
         var now = new Date();
@@ -2414,7 +2429,7 @@ function scanIntoArray() {
 /**
  * RxJS operator that filters out emissions whose {@link Expires} value has already expired.
  *
- * @returns operator that only passes through non-expired emissions
+ * @returns Operator that only passes through non-expired emissions.
  */ function skipExpired() {
     return filter(function(expires) {
         return !expirationDetails({
@@ -2425,8 +2440,8 @@ function scanIntoArray() {
 /**
  * RxJS operator that skips emissions until the elapsed time since the emitted date/timestamp has exceeded `expiresIn`.
  *
- * @param expiresIn - duration in milliseconds
- * @returns operator that skips emissions until the time window has elapsed
+ * @param expiresIn - Duration in milliseconds.
+ * @returns Operator that skips emissions until the time window has elapsed.
  */ function skipUntilExpiration(expiresIn) {
     return filter(function(x) {
         return expirationDetails({
@@ -2438,8 +2453,8 @@ function scanIntoArray() {
 /**
  * RxJS operator that skips emissions after the elapsed time since the emitted date/timestamp has exceeded `expiresIn`.
  *
- * @param expiresIn - duration in milliseconds
- * @returns operator that passes through emissions only within the time window
+ * @param expiresIn - Duration in milliseconds.
+ * @returns Operator that passes through emissions only within the time window.
  */ function skipAfterExpiration(expiresIn) {
     return filter(function(x) {
         return !expirationDetails({
@@ -2451,9 +2466,9 @@ function scanIntoArray() {
 /**
  * RxJS operator that only takes emissions from the source within a time window after each emission from a watch observable.
  *
- * @param watch - observable whose emissions reset the time window
- * @param takeFor - duration in milliseconds of each time window
- * @returns operator that limits source emissions to the active time window after each watch emission
+ * @param watch - Observable whose emissions reset the time window.
+ * @param takeFor - Duration in milliseconds of each time window.
+ * @returns Operator that limits source emissions to the active time window after each watch emission.
  */ function skipUntilTimeElapsedAfterLastEmission(watch, takeFor) {
     return function(observable) {
         return watch.pipe(switchMap(function() {
@@ -2471,9 +2486,9 @@ function scanIntoArray() {
  * RxJS operator that skips emissions from the source for a duration after each emission from a watch observable,
  * then passes values through once the time has elapsed.
  *
- * @param watch - observable whose emissions reset the skip window
- * @param skipFor - duration in milliseconds to skip after each watch emission
- * @returns an operator that delays passing values through until time has elapsed since the last watch emission
+ * @param watch - Observable whose emissions reset the skip window.
+ * @param skipFor - Duration in milliseconds to skip after each watch emission.
+ * @returns An operator that delays passing values through until time has elapsed since the last watch emission.
  */ function takeAfterTimeElapsedSinceLastEmission(watch, skipFor) {
     return function(observable) {
         return watch.pipe(switchMap(function() {
@@ -2493,9 +2508,9 @@ function scanIntoArray() {
  *
  * After the timeout, the default value is prepended and the source continues normally.
  *
- * @param defaultValue - value or getter to use as the default
- * @param first - timeout in ms before emitting the default (defaults to 0)
- * @returns an operator that provides a fallback on slow emissions
+ * @param defaultValue - Value or getter to use as the default.
+ * @param first - Timeout in ms before emitting the default (defaults to 0)
+ * @returns An operator that provides a fallback on slow emissions.
  */ function timeoutStartWith(defaultValue) {
     var first = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 0;
     return function(source) {
@@ -2510,9 +2525,9 @@ function scanIntoArray() {
 /**
  * RxJS operator that executes a side-effect function if the source does not emit within the given timeout.
  *
- * @param timeoutDelay - timeout in ms before triggering the side-effect
- * @param useFn - side-effect function to call on timeout
- * @returns an operator that taps after timeout
+ * @param timeoutDelay - Timeout in ms before triggering the side-effect.
+ * @param useFn - Side-effect function to call on timeout.
+ * @returns An operator that taps after timeout.
  */ function tapAfterTimeout(timeoutDelay, useFn) {
     return timeout({
         first: timeoutDelay,
@@ -2524,9 +2539,9 @@ function scanIntoArray() {
 /**
  * RxJS operator that throws an error if the source does not emit within the given timeout.
  *
- * @param timeoutDelay - timeout in ms before throwing
- * @param error - getter that produces the error to throw
- * @returns an operator that throws on timeout
+ * @param timeoutDelay - Timeout in ms before throwing.
+ * @param error - Getter that produces the error to throw.
+ * @returns An operator that throws on timeout.
  */ function throwErrorAfterTimeout(timeoutDelay, error) {
     return timeout({
         first: timeoutDelay,
@@ -2545,6 +2560,9 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
  * Wraps `timer()` internally and maps each tick index through the factory. Optionally limits
  * the total number of emissions.
  *
+ * @param config - Timer configuration including factory, interval, wait, and limit.
+ * @returns An observable of factory-produced values.
+ *
  * @example
  * ```ts
  * const countdown$ = factoryTimer({
@@ -2554,9 +2572,6 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
  * });
  * // emits 10, 9, 8, ... 0
  * ```
- *
- * @param config - timer configuration including factory, interval, wait, and limit
- * @returns an observable of factory-produced values
  */ function factoryTimer(config) {
     var _config_wait = config.wait, wait = _config_wait === void 0 ? 0 : _config_wait, _config_interval = config.interval, interval = _config_interval === void 0 ? DEFAULT_FACTORY_TIMER_INTERVAL : _config_interval, limit = config.limit, factory = config.factory;
     var obs = timer(wait, interval);
@@ -2574,16 +2589,16 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
  * `distinctUntilChanged` variant for arrays that only emits when the set of keys extracted from
  * the array elements changes.
  *
- * @param readKey - function to extract one or more keys from each element
- * @returns an operator that filters out arrays with unchanged key sets
+ * @param readKey - Function to extract one or more keys from each element.
+ * @returns An operator that filters out arrays with unchanged key sets.
  */ function distinctUntilKeysChange(readKey) {
     return distinctUntilChanged(objectKeysEqualityComparatorFunction(readKey));
 }
 /**
  * `distinctUntilChanged` variant for single objects that only emits when the extracted key changes.
  *
- * @param readKey - function to extract a key from the emitted object
- * @returns an operator that filters out emissions with unchanged keys
+ * @param readKey - Function to extract a key from the emitted object.
+ * @returns An operator that filters out emissions with unchanged keys.
  */ function distinctUntilObjectKeyChange(readKey) {
     return distinctUntilChanged(objectKeyEqualityComparatorFunction(readKey));
 }
@@ -2595,9 +2610,9 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
  * delays emitting the new value until the previous destruction completes.
  * On unsubscription, the last emitted instance is also destroyed.
  *
- * @param destroy - function to clean up each replaced instance
- * @param wait - whether to wait for the previous destroy to complete before emitting
- * @returns an operator that manages instance lifecycle
+ * @param destroy - Function to clean up each replaced instance.
+ * @param wait - Whether to wait for the previous destroy to complete before emitting.
+ * @returns An operator that manages instance lifecycle.
  */ function cleanup(destroy) {
     var wait = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : false;
     return function(obs) {
@@ -2636,8 +2651,8 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
  * Accepts both {@link Destroyable} and {@link Maybe}<{@link Destroyable}> values,
  * skipping cleanup for nullish emissions.
  *
- * @param wait - whether to wait for the previous destroy to complete before emitting
- * @returns an operator that manages Destroyable lifecycle
+ * @param wait - Whether to wait for the previous destroy to complete before emitting.
+ * @returns An operator that manages Destroyable lifecycle.
  */ function cleanupDestroyable(wait) {
     return cleanup(function(x) {
         if (x) {
@@ -2651,13 +2666,13 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
  *
  * Only considers the first emission from the source. The result is shared via `shareReplay(1)`.
  *
+ * @returns An operator that tracks whether the first value has been emitted.
+ *
  * @example
  * ```ts
  * const loading$ = dataFetch$.pipe(isLoading());
  * // emits true initially, then false once dataFetch$ emits
  * ```
- *
- * @returns an operator that tracks whether the first value has been emitted
  */ function isLoading() {
     return function(source) {
         return source.pipe(first(), map(function() {
@@ -2685,8 +2700,8 @@ function tapLog(messageOrFunction) {
  *
  * Useful for simulating network latency or staggering requests.
  *
- * @param maxOrArgs - maximum delay in ms, or a full random number config
- * @returns an operator that delays each emission by a random amount
+ * @param maxOrArgs - Maximum delay in ms, or a full random number config.
+ * @returns An operator that delays each emission by a random amount.
  */ function randomDelay(maxOrArgs) {
     var makeRandomDelay = randomNumberFactory(maxOrArgs);
     return randomDelayWithRandomFunction(makeRandomDelay);
@@ -2694,9 +2709,10 @@ function tapLog(messageOrFunction) {
 /**
  * RxJS operator that adds a random delay using a custom random number generator.
  *
- * @param makeRandomDelay - factory that produces random delay values
- * @param scheduler - the scheduler to use for the delay (defaults to asyncScheduler)
- * @returns an operator that delays each emission
+ * @param makeRandomDelay - Factory that produces random delay values.
+ * @param scheduler - The scheduler to use for the delay (defaults to asyncScheduler)
+ * @returns An operator that delays each emission.
+ *
  * @__NO_SIDE_EFFECTS__
  */ function randomDelayWithRandomFunction(makeRandomDelay) {
     var scheduler = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : asyncScheduler;
@@ -2708,7 +2724,7 @@ function tapLog(messageOrFunction) {
 /**
  * `distinctUntilChanged` variant that only emits when the model's `id` property changes.
  *
- * @returns operator that suppresses consecutive emissions with the same model `id`
+ * @returns Operator that suppresses consecutive emissions with the same model `id`
  */ function distinctUntilModelIdChange() {
     return distinctUntilObjectKeyChange(function(x) {
         return x.id;
@@ -2717,7 +2733,7 @@ function tapLog(messageOrFunction) {
 /**
  * `distinctUntilChanged` variant that only emits when the model's `key` property changes.
  *
- * @returns operator that suppresses consecutive emissions with the same model `key`
+ * @returns Operator that suppresses consecutive emissions with the same model `key`
  */ function distinctUntilModelKeyChange() {
     return distinctUntilObjectKeyChange(function(x) {
         return x.key;
@@ -2728,8 +2744,8 @@ function tapLog(messageOrFunction) {
  * RxJS operator that extracts values from a keyed object using a keys observable,
  * returning only the values whose keys are present in both.
  *
- * @param keysObs - observable (or static value) of keys to intersect with
- * @returns an operator that maps a keyed object to an array of matching values
+ * @param keysObs - Observable (or static value) of keys to intersect with.
+ * @returns An operator that maps a keyed object to an array of matching values.
  */ function mapKeysIntersectionToArray(keysObs) {
     return switchMap(function(object) {
         return asObservable(keysObs).pipe(map(function(keys) {
@@ -2740,7 +2756,7 @@ function tapLog(messageOrFunction) {
 /**
  * `distinctUntilChanged` variant for `Map` instances that only emits when the set of map keys changes.
  *
- * @returns an operator that filters out Maps with unchanged key sets
+ * @returns An operator that filters out Maps with unchanged key sets.
  */ function distinctUntilMapHasDifferentKeys() {
     return distinctUntilChanged(mapsHaveSameKeys);
 }
@@ -2796,8 +2812,8 @@ function _object_spread_props$7(target, source) {
  * RxJS operator that counts emissions as they occur using `scan`, emitting the running count
  * after each emission (unlike `count()` which only emits on completion).
  *
- * @param startAt - initial count value (defaults to 0)
- * @returns an operator that emits the running emission count
+ * @param startAt - Initial count value (defaults to 0)
+ * @returns An operator that emits the running emission count.
  */ function scanCount() {
     var startAt = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : 0;
     return scan(function(count) {
@@ -2807,8 +2823,8 @@ function _object_spread_props$7(target, source) {
 /**
  * Creates a {@link factoryTimer} that emits incrementing numbers on an interval.
  *
- * @param config - timer and incrementing number configuration
- * @returns an observable of incrementing numbers
+ * @param config - Timer and incrementing number configuration.
+ * @returns An observable of incrementing numbers.
  */ function incrementingNumberTimer() {
     var config = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     return factoryTimer(_object_spread_props$7(_object_spread$7({}, config), {
@@ -2867,10 +2883,10 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  *
  * Emits the `initial` value first, then taps on the first emitted value to run the provided callback.
  *
- * @param tap - side-effect function called with the first value
- * @param initial - optional starting value emitted before the source
- * @param skipFirst - if true, skips tapping the initial value
- * @returns an operator that initializes the pipe with a tap
+ * @param tap - Side-effect function called with the first value.
+ * @param initial - Optional starting value emitted before the source.
+ * @param skipFirst - If true, skips tapping the initial value.
+ * @returns An operator that initializes the pipe with a tap.
  */ function initialize(tap, initial, skipFirst) {
     return function(source) {
         var subscriber = source.pipe(startWith(initial), tapFirst(function(x) {
@@ -2882,9 +2898,9 @@ function _unsupported_iterable_to_array$6(o, minLen) {
 /**
  * Executes a side-effect on the first emission from the observable, then passes all values through.
  *
- * @param tap - the side-effect function to call once
- * @param skipFirst - if true, skips the very first emission before tapping
- * @returns an operator that taps the first value
+ * @param tap - The side-effect function to call once.
+ * @param skipFirst - If true, skips the very first emission before tapping.
+ * @returns An operator that taps the first value.
  */ function tapFirst(tap) {
     var skipFirst = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : false;
     return skipWhile(function(value) {
@@ -2899,8 +2915,8 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  * The subscription will never have `complete()` called since it only triggers after unsubscription.
  * Use `finalize()` for additional cleanup.
  *
- * @param obs - the source observable to wrap
- * @returns an observable that only completes on unsubscription
+ * @param obs - The source observable to wrap.
+ * @returns An observable that only completes on unsubscription.
  */ function preventComplete(obs) {
     var complete = new BehaviorSubject(0);
     return combineLatest([
@@ -2918,14 +2934,14 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  *
  * Unlike `from()`, the promise/observable is not created until the first subscriber connects.
  *
+ * @param getter - Factory that returns a Promise or Observable.
+ * @returns A shared observable that defers execution until subscription.
+ *
  * @example
  * ```ts
  * const data$ = lazyFrom(() => fetch('/api/data').then(r => r.json()));
  * // The fetch is not called until data$ is subscribed to
  * ```
- *
- * @param getter - factory that returns a Promise or Observable
- * @returns a shared observable that defers execution until subscription
  */ function lazyFrom(getter) {
     return of(undefined).pipe(mergeMap(function() {
         return from(getter());
@@ -2937,9 +2953,9 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  *
  * Uses {@link filterUniqueFunction} to deduplicate emitted arrays by extracting a key from each item.
  *
- * @param readKey - function to extract the unique key from each item
- * @param additionalKeysInput - optional additional keys to include in the unique set
- * @returns an operator that emits deduplicated arrays
+ * @param readKey - Function to extract the unique key from each item.
+ * @param additionalKeysInput - Optional additional keys to include in the unique set.
+ * @returns An operator that emits deduplicated arrays.
  */ function filterUnique(readKey, additionalKeysInput) {
     var filterFn = filterUniqueFunction(readKey, additionalKeysInput);
     return map(function(x) {
@@ -2956,6 +2972,9 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  * Each call pushes a value onto the internal subject and returns the shared, throttled observable.
  * Useful for debouncing repeated calls while sharing a single observable output.
  *
+ * @param config - Optional throttle, distinct, and pipe settings.
+ * @returns An async pusher function.
+ *
  * @example
  * ```ts
  * const pusher = asyncPusher<string>({ throttle: 100 });
@@ -2965,9 +2984,6 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  * // clean up
  * pusher.destroy();
  * ```
- *
- * @param config - optional throttle, distinct, and pipe settings
- * @returns an async pusher function
  */ function asyncPusher() {
     var config = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _config_throttle = config.throttle, throttle = _config_throttle === void 0 ? DEFAULT_ASYNC_PUSHER_THROTTLE : _config_throttle, cleanupObs = config.cleanupObs, _config_distinct = config.distinct, distinct = _config_distinct === void 0 ? true : _config_distinct, pipeObs = config.pipe;
@@ -3013,8 +3029,8 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  *
  * The factory optionally accepts a cleanup observable — when it completes, the pusher is destroyed.
  *
- * @param config - optional config passed to the underlying async pusher
- * @returns a cached factory that produces an async pusher
+ * @param config - Optional config passed to the underlying async pusher.
+ * @returns A cached factory that produces an async pusher.
  */ function asyncPusherCache(config) {
     return cachedGetter(function(cleanupObs) {
         var pusher = asyncPusher(config);
@@ -3087,8 +3103,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Creates a function that takes a `Map` and combines the latest emissions from observables
  * created from each map value.
  *
- * @param mapToObs - function to transform each map value into an observable
- * @returns a function that converts a Map to a combined observable of results
+ * @param mapToObs - Function to transform each map value into an observable.
+ * @returns Operator-ready function that combines the per-entry observables into one emission of results.
  */ function combineLatestFromMapValuesObsFn(mapToObs) {
     var combineArrayFn = combineLatestFromArrayObsFn(mapToObs);
     return function(latestMap) {
@@ -3103,8 +3119,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * Returns `of([])` for empty arrays.
  *
- * @param mapToObs - function to transform each value into an observable
- * @returns a function that converts an array to a combined observable
+ * @param mapToObs - Function to transform each value into an observable.
+ * @returns Operator-ready function that combines the latest emissions from each derived observable.
  */ function combineLatestFromArrayObsFn(mapToObs) {
     return function(latest) {
         var newObs = latest.map(mapToObs);
@@ -3117,6 +3133,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Each key in the input object maps to an observable (or static value). The result observable
  * emits an object with the same keys, where each value is the latest emission from its source.
  *
+ * @param objectMap - An object whose values are observables or static values.
+ * @returns An observable that emits the resolved object.
+ *
  * @example
  * ```ts
  * const result$ = combineLatestFromObject({
@@ -3125,9 +3144,6 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * });
  * // emits { name: 'Alice', age: 30 }
  * ```
- *
- * @param objectMap - an object whose values are observables or static values
- * @returns an observable that emits the resolved object
  */ function combineLatestFromObject(objectMap) {
     var pairs = allKeyValueTuples(objectMap);
     var observables = pairs.map(function(x) {
@@ -3151,8 +3167,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
 /**
  * RxJS operator that maps an array of items to a `Map<K, T>` using the provided key reader.
  *
- * @param read - function to extract the key from each item
- * @returns an operator that converts an array into a keyed Map
+ * @param read - Function to extract the key from each item.
+ * @returns An operator that converts an array into a keyed Map.
  */ function keyValueMap(read) {
     return map(keyValueMapFactory(read));
 }
@@ -3160,8 +3176,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * RxJS operator that maps an array of items to a `Map<K, T>` using a multi-key reader,
  * allowing each item to appear under multiple keys.
  *
- * @param read - function to extract multiple keys from each item
- * @returns an operator that converts an array into a multi-keyed Map
+ * @param read - Function to extract multiple keys from each item.
+ * @returns An operator that converts an array into a multi-keyed Map.
  */ function multiKeyValueMap(read) {
     return map(multiKeyValueMapFactory(read));
 }
@@ -3172,6 +3188,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * Useful as a safety valve to detect infinite loops or runaway observables.
  *
+ * @param config - Period duration, max emissions, and error/fallback handling.
+ * @returns An operator that monitors emission frequency.
+ *
  * @example
  * ```ts
  * source$.pipe(
@@ -3179,9 +3198,6 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * ).subscribe();
  * // throws if more than 100 emissions occur within 1 second
  * ```
- *
- * @param config - period duration, max emissions, and error/fallback handling
- * @returns an operator that monitors emission frequency
  */ function errorOnEmissionsInPeriod(config) {
     var _config_period = config.period, period = _config_period === void 0 ? 1000 : _config_period, maxEmissionsPerPeriod = config.maxEmissionsPerPeriod, onError = config.onError, inputErrorFactory = config.errorFactory, inputErrorMessage = config.errorMessage, switchToObs = config.switchToObs;
     var errorMessage = inputErrorMessage !== null && inputErrorMessage !== void 0 ? inputErrorMessage : 'errorOnEmissionsInPeriod(): Too many emissions in time period.';
@@ -3190,8 +3206,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     } : undefined;
     return function(source) {
         var counter = timePeriodCounter(period);
+        var result;
         if (errorFactory) {
-            return source.pipe(map(function(x) {
+            result = source.pipe(map(function(x) {
                 if (counter() > maxEmissionsPerPeriod) {
                     var error = errorFactory();
                     onError === null || onError === void 0 ? void 0 : onError(error);
@@ -3199,19 +3216,21 @@ function _unsupported_iterable_to_array$5(o, minLen) {
                 }
                 return x;
             }));
+        } else {
+            // switchToObs was provided.
+            result = source.pipe(switchMap(function(x) {
+                return counter() > maxEmissionsPerPeriod ? switchToObs : of(x);
+            }));
         }
-        // switchToObs was provided.
-        return source.pipe(switchMap(function(x) {
-            return counter() > maxEmissionsPerPeriod ? switchToObs : of(x);
-        }));
+        return result;
     };
 }
 
 /**
  * RxJS operator that checks whether the emitted `Set` contains all values from the given observable.
  *
- * @param valuesObs - observable of values to check against
- * @returns an operator that emits true if all values are contained in the set
+ * @param valuesObs - Observable of values to check against.
+ * @returns An operator that emits true if all values are contained in the set.
  */ function setContainsAllValuesFrom(valuesObs) {
     return combineLatestMapFrom(valuesObs, function(set, values) {
         return setContainsAllValues(set, values !== null && values !== void 0 ? values : []);
@@ -3220,8 +3239,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
 /**
  * RxJS operator that checks whether the emitted `Set` contains any value from the given observable.
  *
- * @param valuesObs - observable of values to check against
- * @returns an operator that emits true if any value is contained in the set
+ * @param valuesObs - Observable of values to check against.
+ * @returns An operator that emits true if any value is contained in the set.
  */ function setContainsAnyValueFrom(valuesObs) {
     return combineLatestMapFrom(valuesObs, function(set, values) {
         return setContainsAnyValue(set, values !== null && values !== void 0 ? values : []);
@@ -3230,8 +3249,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
 /**
  * RxJS operator that checks whether the emitted `Set` contains none of the values from the given observable.
  *
- * @param valuesObs - observable of values to check against
- * @returns an operator that emits true if no values are contained in the set
+ * @param valuesObs - Observable of values to check against.
+ * @returns An operator that emits true if no values are contained in the set.
  */ function setContainsNoValueFrom(valuesObs) {
     return combineLatestMapFrom(valuesObs, function(set, values) {
         return setContainsNoneOfValue(set, values !== null && values !== void 0 ? values : []);
@@ -3240,7 +3259,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
 /**
  * `distinctUntilChanged` variant for iterables that only emits when the contained values change.
  *
- * @returns operator that suppresses consecutive iterable emissions with the same set of values
+ * @returns Operator that suppresses consecutive iterable emissions with the same set of values.
  */ function distinctUntilHasDifferentValues() {
     return distinctUntilChanged(hasSameValues);
 }
@@ -3248,8 +3267,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * `distinctUntilChanged` variant that extracts iterable values from the emitted item and only emits
  * when the set of extracted values changes.
  *
- * @param readValues - function to extract the iterable of values to compare
- * @returns operator that suppresses consecutive emissions whose extracted iterable values are the same
+ * @param readValues - Function to extract the iterable of values to compare.
+ * @returns Operator that suppresses consecutive emissions whose extracted iterable values are the same.
  */ function distinctUntilItemsHaveDifferentValues(readValues) {
     return distinctUntilItemsValueChanges(readValues, hasSameValues);
 }
@@ -3257,9 +3276,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * `distinctUntilChanged` variant that extracts values from the emitted item and compares them
  * using a custom equality comparator.
  *
- * @param readValues - function to extract the value to compare
- * @param isEqualComparator - custom equality function for the extracted values
- * @returns operator that suppresses consecutive emissions whose extracted values are considered equal
+ * @param readValues - Function to extract the value to compare.
+ * @param isEqualComparator - Custom equality function for the extracted values.
+ * @returns Operator that suppresses consecutive emissions whose extracted values are considered equal.
  */ function distinctUntilItemsValueChanges(readValues, isEqualComparator) {
     return distinctUntilChanged(compareEqualityWithValueFromItemsFunction(readValues, isEqualComparator));
 }
@@ -3270,6 +3289,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Combines the source array with the `search$` observable and applies the configured
  * search string filter function. When the search is null/undefined, all items pass through.
  *
+ * @param config - Search filter configuration with filter function and search$ observable.
+ * @returns An operator that filters arrays by search string.
+ *
  * @example
  * ```ts
  * const items$ = of(['apple', 'banana', 'cherry']);
@@ -3280,9 +3302,6 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * ).subscribe(console.log);
  * // ['banana']
  * ```
- *
- * @param config - search filter configuration with filter function and search$ observable
- * @returns an operator that filters arrays by search string
  */ function filterWithSearchString(config) {
     var filter = config.filter, search$ = config.search$;
     var filterFactory = searchStringFilterFunction(filter);
@@ -3297,8 +3316,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Subscribes to the observable, calls the provided function with the first emitted value,
  * then automatically unsubscribes.
  *
- * @param obs - the source observable
- * @param useFn - function to call with the first value
+ * @param obs - The source observable.
+ * @param useFn - Function to call with the first value.
  */ function useFirst(obs, useFn) {
     obs.pipe(first()).subscribe(useFn);
 }
@@ -3309,6 +3328,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * Useful for flattening an observable of optional loading contexts into a single stream of loading events.
  *
+ * @returns An RxJS operator that switches to the stream$ of each non-null LoadingContext.
+ *
  * @example
  * ```ts
  * const context$ = new BehaviorSubject<Maybe<LoadingContext>>(myLoadingContext);
@@ -3319,8 +3340,6 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * // emits LoadingContextEvent values from myLoadingContext.stream$
  * // emits undefined when context$ emits null/undefined
  * ```
- *
- * @returns an RxJS operator that switches to the stream$ of each non-null LoadingContext
  */ function switchMapMaybeLoadingContextStream() {
     return switchMap(function(x) {
         return x != null ? x.stream$ : of(undefined);
@@ -3402,6 +3421,10 @@ function _unsupported_iterable_to_array$4(o, minLen) {
 /**
  * Compares two {@link LoadingState} instances for shallow equality across all key properties.
  *
+ * @param a - First loading state.
+ * @param b - Second loading state.
+ * @returns True if loading, loadingProgress, error, and value are all strictly equal.
+ *
  * @example
  * ```ts
  * const a = successResult('hello');
@@ -3411,10 +3434,6 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  * const c = beginLoading();
  * isLoadingStateEqual(a, c); // false
  * ```
- *
- * @param a - first loading state
- * @param b - second loading state
- * @returns true if loading, loadingProgress, error, and value are all strictly equal
  */ function isLoadingStateEqual(a, b) {
     return a.loading === b.loading && a.loadingProgress === b.loadingProgress && a.error === b.error && a.value === b.value;
 }
@@ -3424,9 +3443,9 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  *
  * Does not compare the `value` property — only structural metadata.
  *
- * @param a - first loading error pair
- * @param b - second loading error pair
- * @returns true if both pairs have equivalent metadata
+ * @param a - First loading error pair.
+ * @param b - Second loading error pair.
+ * @returns True if both pairs have equivalent metadata.
  */ function isLoadingStateMetadataEqual(a, b) {
     return a.loading == b.loading && valuesAreBothNullishOrEquivalent(a.loadingProgress, b.loadingProgress) && valuesAreBothNullishOrEquivalent(a.error, b.error);
 }
@@ -3454,6 +3473,9 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  * Returns `LOADING` if still loading, `SUCCESS` if finished with a value key,
  * `ERROR` if finished with an error key, or `IDLE` if finished with neither.
  *
+ * @param loadingState - The loading state to classify.
+ * @returns The corresponding {@link LoadingStateType}
+ *
  * @example
  * ```ts
  * loadingStateType(beginLoading()); // LoadingStateType.LOADING
@@ -3461,9 +3483,6 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  * loadingStateType(errorResult(new Error())); // LoadingStateType.ERROR
  * loadingStateType({ loading: false }); // LoadingStateType.IDLE
  * ```
- *
- * @param loadingState - the loading state to classify
- * @returns the corresponding {@link LoadingStateType}
  */ function loadingStateType(loadingState) {
     var isLoading = !isLoadingStateFinishedLoading(loadingState);
     var type;
@@ -3486,6 +3505,9 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  * Returns `true` when `loading` is explicitly `false`, or when `loading` is not `true`
  * and either a value, error, or `null` value is present.
  *
+ * @param state - The loading state to check (may be null/undefined)
+ * @returns True if loading is complete.
+ *
  * @example
  * ```ts
  * isLoadingStateFinishedLoading(successResult('done')); // true
@@ -3493,9 +3515,6 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  * isLoadingStateFinishedLoading({ loading: false }); // true
  * isLoadingStateFinishedLoading(null); // false
  * ```
- *
- * @param state - the loading state to check (may be null/undefined)
- * @returns true if loading is complete
  */ function isLoadingStateFinishedLoading(state) {
     var result = false;
     if (state) {
@@ -3514,14 +3533,14 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  *
  * Represents a state where no loading has been initiated yet.
  *
+ * @returns A loading state with `loading: false` and no value or error.
+ *
  * @example
  * ```ts
  * const state = idleLoadingState();
  * // { loading: false }
  * loadingStateType(state); // LoadingStateType.IDLE
  * ```
- *
- * @returns a loading state with `loading: false` and no value or error
  */ function idleLoadingState() {
     return {
         loading: false
@@ -3537,9 +3556,9 @@ function beginLoading(state) {
 /**
  * Creates a {@link PageLoadingState} that is loading for the given page number.
  *
- * @param page - the page number being loaded
- * @param state - optional partial state to merge
- * @returns a page loading state with `loading: true`
+ * @param page - The page number being loaded.
+ * @param state - Optional partial state to merge.
+ * @returns A page loading state with `loading: true`
  */ function beginLoadingPage(page, state) {
     return state ? _object_spread_props$6(_object_spread$6({
         page: page
@@ -3553,14 +3572,14 @@ function beginLoading(state) {
 /**
  * Creates a successful {@link LoadingState} with the given value and `loading: false`.
  *
+ * @param value - The loaded value.
+ * @returns A loading state representing a successful result.
+ *
  * @example
  * ```ts
  * const state = successResult({ name: 'Alice' });
  * // { value: { name: 'Alice' }, loading: false }
  * ```
- *
- * @param value - the loaded value
- * @returns a loading state representing a successful result
  */ function successResult(value) {
     return {
         value: value,
@@ -3570,9 +3589,9 @@ function beginLoading(state) {
 /**
  * Creates a successful {@link PageLoadingState} for a specific page.
  *
- * @param page - the page number
- * @param value - the loaded value
- * @returns a page loading state representing success
+ * @param page - The page number.
+ * @param value - The loaded value.
+ * @returns A page loading state representing success.
  */ function successPageResult(page, value) {
     return _object_spread_props$6(_object_spread$6({}, successResult(value)), {
         page: page
@@ -3583,14 +3602,14 @@ function beginLoading(state) {
  *
  * Converts the input error to a {@link ReadableError} via {@link toReadableError}.
  *
+ * @param error - The error to wrap (string, Error, or ReadableError)
+ * @returns A loading state representing an error.
+ *
  * @example
  * ```ts
  * const state = errorResult(new Error('Not found'));
  * // { error: { message: 'Not found', ... }, loading: false }
  * ```
- *
- * @param error - the error to wrap (string, Error, or ReadableError)
- * @returns a loading state representing an error
  */ function errorResult(error) {
     return {
         error: toReadableError(error),
@@ -3600,9 +3619,9 @@ function beginLoading(state) {
 /**
  * Creates a {@link PageLoadingState} representing an error for a specific page.
  *
- * @param page - the page number
- * @param error - the error to include
- * @returns a page loading state representing an error
+ * @param page - The page number.
+ * @param error - The error to include.
+ * @returns A page loading state representing an error.
  */ function errorPageResult(page, error) {
     return _object_spread_props$6(_object_spread$6({}, errorResult(error)), {
         page: page
@@ -3611,28 +3630,28 @@ function beginLoading(state) {
 /**
  * Whether any of the given {@link LoadingState} instances are currently loading.
  *
+ * @param states - Array of loading states to check.
+ * @returns True if at least one state is loading.
+ *
  * @example
  * ```ts
  * isAnyLoadingStateInLoadingState([successResult(1), beginLoading()]); // true
  * isAnyLoadingStateInLoadingState([successResult(1), successResult(2)]); // false
  * ```
- *
- * @param states - array of loading states to check
- * @returns true if at least one state is loading
  */ function isAnyLoadingStateInLoadingState(states) {
     return reduceBooleansWithOr(states.map(isLoadingStateLoading), false);
 }
 /**
  * Whether all given {@link LoadingState} instances have finished loading.
  *
+ * @param states - Array of loading states to check.
+ * @returns True if every state has finished loading.
+ *
  * @example
  * ```ts
  * areAllLoadingStatesFinishedLoading([successResult(1), successResult(2)]); // true
  * areAllLoadingStatesFinishedLoading([successResult(1), beginLoading()]); // false
  * ```
- *
- * @param states - array of loading states to check
- * @returns true if every state has finished loading
  */ function areAllLoadingStatesFinishedLoading(states) {
     return reduceBooleansWithAnd(states.map(isLoadingStateFinishedLoading), true);
 }
@@ -3641,8 +3660,8 @@ function beginLoading(state) {
  *
  * When the target type is `IDLE`, returns `true` for null/undefined states.
  *
- * @param type - the loading state type to match against
- * @returns a predicate function for the given type
+ * @param type - The loading state type to match against.
+ * @returns A predicate function for the given type.
  */ function isLoadingStateWithStateType(type) {
     var defaultResult = type === LoadingStateType.IDLE;
     return function(state) {
@@ -3679,45 +3698,45 @@ function beginLoading(state) {
 /**
  * Type guard that checks whether a {@link LoadingState} has a non-undefined value, regardless of loading status.
  *
+ * @param state - The loading state to check.
+ * @returns True if the state has a defined (non-undefined) value.
+ *
  * @example
  * ```ts
  * isLoadingStateWithDefinedValue(successResult('hello')); // true
  * isLoadingStateWithDefinedValue(successResult(null)); // true (null is defined)
  * isLoadingStateWithDefinedValue(beginLoading()); // false
  * ```
- *
- * @param state - the loading state to check
- * @returns true if the state has a defined (non-undefined) value
  */ function isLoadingStateWithDefinedValue(state) {
     return state ? state.value !== undefined : false;
 }
 /**
  * Type guard that checks whether a {@link LoadingState} has a non-null error, regardless of loading status.
  *
+ * @param state - The loading state to check.
+ * @returns True if the state has an error.
+ *
  * @example
  * ```ts
  * isLoadingStateWithError(errorResult(new Error('fail'))); // true
  * isLoadingStateWithError(successResult('ok')); // false
  * ```
- *
- * @param state - the loading state to check
- * @returns true if the state has an error
  */ function isLoadingStateWithError(state) {
     return state ? state.error != null : false;
 }
 /**
  * Type guard that checks whether a {@link LoadingState} has finished loading and has a defined value.
  *
- * @param state - the loading state to check
- * @returns true if finished loading with a non-undefined value
+ * @param state - The loading state to check.
+ * @returns True if finished loading with a non-undefined value.
  */ function isLoadingStateFinishedLoadingWithDefinedValue(state) {
     return state ? isLoadingStateFinishedLoading(state) && state.value !== undefined : false;
 }
 /**
  * Type guard that checks whether a {@link LoadingState} has finished loading and has an error.
  *
- * @param state - the loading state to check
- * @returns true if finished loading with an error
+ * @param state - The loading state to check.
+ * @returns True if finished loading with an error.
  */ function isLoadingStateFinishedLoadingWithError(state) {
     return state ? isLoadingStateFinishedLoading(state) && state.error != null : false;
 }
@@ -3726,6 +3745,10 @@ function beginLoading(state) {
  *
  * Does not compare values — only structural metadata.
  *
+ * @param a - First page loading state.
+ * @param b - Second page loading state.
+ * @returns True if metadata is equivalent.
+ *
  * @example
  * ```ts
  * isPageLoadingStateMetadataEqual(
@@ -3738,10 +3761,6 @@ function beginLoading(state) {
  *   { page: 2 }
  * ); // false
  * ```
- *
- * @param a - first page loading state
- * @param b - second page loading state
- * @returns true if metadata is equivalent
  */ function isPageLoadingStateMetadataEqual(a, b) {
     return valuesAreBothNullishOrEquivalent(a.page, b.page) && a.loading == b.loading && valuesAreBothNullishOrEquivalent(a.error, b.error);
 }
@@ -3803,9 +3822,9 @@ function mergeLoadingStates() {
  *
  * Useful for resetting a state back to loading or idle without losing other metadata (e.g., page).
  *
- * @param state - the state to copy metadata from
- * @param loading - whether to mark as loading (defaults to true)
- * @returns a new state with value/error cleared
+ * @param state - The state to copy metadata from.
+ * @param loading - Whether to mark as loading (defaults to true)
+ * @returns A new state with value/error cleared.
  */ function mergeLoadingStateWithLoading(state) {
     var loading = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : true;
     return _object_spread_props$6(_object_spread$6({}, state), {
@@ -3817,9 +3836,9 @@ function mergeLoadingStates() {
 /**
  * Returns a copy of the state with the given value, `loading: false`, and error cleared.
  *
- * @param state - the state to copy metadata from
- * @param value - the new value to set
- * @returns a new state representing success
+ * @param state - The state to copy metadata from.
+ * @param value - The new value to set.
+ * @returns A new state representing success.
  */ function mergeLoadingStateWithValue(state, value) {
     return _object_spread_props$6(_object_spread$6({}, state), {
         value: value !== null && value !== void 0 ? value : undefined,
@@ -3830,9 +3849,9 @@ function mergeLoadingStates() {
 /**
  * Returns a copy of the state with the given error and `loading: false`.
  *
- * @param state - the state to copy metadata from
- * @param error - the error to set
- * @returns a new state representing an error
+ * @param state - The state to copy metadata from.
+ * @param error - The error to set.
+ * @returns A new state representing an error.
  */ function mergeLoadingStateWithError(state, error) {
     return _object_spread_props$6(_object_spread$6({}, state), {
         loading: false,
@@ -3844,10 +3863,9 @@ function mergeLoadingStates() {
  *
  * Returns `undefined` if any input is still loading or has an error.
  *
- * @param input - array of loading states to combine
- * @param config - mapping configuration with either `mapValues` or `mapState`
- * @returns the combined loading state, or undefined if inputs are not ready
- *
+ * @param input - Array of loading states to combine.
+ * @param config - Mapping configuration with either `mapValues` or `mapState`
+ * @returns The combined loading state, or undefined if inputs are not ready.
  * @throws {Error} When neither `mapValues` nor `mapState` is provided in the config.
  */ function mapMultipleLoadingStateResults(input, config) {
     var mapValues = config.mapValues, mapState = config.mapState;
@@ -3897,8 +3915,9 @@ function mapLoadingStateResults(input, config) {
  * Creates a function that extracts and maps the value from a {@link LoadingState}, returning undefined
  * when the state has no value.
  *
- * @param mapFn - function to transform the value and state into the output type
- * @returns a function that accepts a loading state and returns the mapped value or undefined
+ * @param mapFn - Function to transform the value and state into the output type.
+ * @returns Mapper that yields the transformed value when present, or undefined when the state has none.
+ *
  * @__NO_SIDE_EFFECTS__
  */ function mapLoadingStateValueFunction(mapFn) {
     return function(state) {
@@ -3991,6 +4010,10 @@ function _unsupported_iterable_to_array$3(o, minLen) {
  *
  * If firstOnly is provided, it will only take the first value the observable returns.
  *
+ * @param obs - The source observable to wrap.
+ * @param firstOnly - If true, only takes the first value from the observable.
+ * @returns An observable that emits {@link LoadingState} values representing the loading lifecycle.
+ *
  * @example
  * ```ts
  * // Wrap a data fetch observable into a LoadingState
@@ -3999,10 +4022,6 @@ function _unsupported_iterable_to_array$3(o, minLen) {
  * // Wrap an observable and only take the first emitted value
  * readonly singleValueState$ = loadingStateFromObs(this.data$, true);
  * ```
- *
- * @param obs - The source observable to wrap.
- * @param firstOnly - If true, only takes the first value from the observable.
- * @returns An observable that emits {@link LoadingState} values representing the loading lifecycle.
  */ function loadingStateFromObs(obs, firstOnly) {
     if (firstOnly) {
         obs = obs.pipe(first());
@@ -4027,6 +4046,8 @@ function combineLoadingStates() {
             return x[i] !== y[i];
         });
     }), map(function(states) {
+        // TODO(breaking-change): pass O explicitly (mergeLoadingStates<O>(...states, mergeFn)) or restructure the variadic signature so O is inferable without the cast.
+        // TODO: Fix eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- mergeLoadingStates is variadic; the generic O cannot be inferred from the call, so tsc widens the result to LoadingState<unknown> without this cast
         return mergeLoadingStates.apply(void 0, _to_consumable_array$1(states).concat([
             mergeFn
         ]));
@@ -4040,6 +4061,9 @@ function combineLoadingStates() {
  * If any source has an error, the error is propagated. If any source is still loading, the result is loading.
  * When all sources are successful, the result value is `true`.
  *
+ * @param sources - LoadingState observables whose statuses participate in the combined emission.
+ * @returns An observable emitting a {@link LoadingState}<boolean> representing the combined status.
+ *
  * @example
  * ```ts
  * const success$ = of(successResult(1));
@@ -4052,9 +4076,6 @@ function combineLoadingStates() {
  * const loading$ = of(beginLoading());
  * const status$ = combineLoadingStatesStatus([loading$, success$]);
  * ```
- *
- * @param sources - An array of LoadingState observables to combine.
- * @returns An observable emitting a {@link LoadingState}<boolean> representing the combined status.
  */ function combineLoadingStatesStatus(sources) {
     return combineLatest(sources).pipe(map(function(allLoadingStates) {
         var firstErrorState = allLoadingStates.find(function(x) {
@@ -4084,6 +4105,8 @@ function startWithBeginLoading(state) {
  *
  * Unlike {@link valueFromLoadingState}, this operator emits for every state change, regardless of whether the value is defined.
  *
+ * @returns An `OperatorFunction` that maps each {@link LoadingState} to its current value (or undefined).
+ *
  * @example
  * ```ts
  * // Expose the current (possibly undefined) value from a loading state
@@ -4092,8 +4115,6 @@ function startWithBeginLoading(state) {
  *   shareReplay(1)
  * );
  * ```
- *
- * @returns An `OperatorFunction` that maps each {@link LoadingState} to its current value (or undefined).
  */ function currentValueFromLoadingState() {
     return function(obs) {
         return obs.pipe(map(function(x) {
@@ -4107,6 +4128,8 @@ function startWithBeginLoading(state) {
  * Equivalent to piping {@link currentValueFromLoadingState} and `filterMaybeStrict()`.
  * Only emits when the value is defined, filtering out loading and error states without values.
  *
+ * @returns An `OperatorFunction` that emits only defined values from the {@link LoadingState}.
+ *
  * @example
  * ```ts
  * // Only emit when the loading state has a defined value
@@ -4115,8 +4138,6 @@ function startWithBeginLoading(state) {
  *   // only emits non-null/non-undefined values
  * );
  * ```
- *
- * @returns An `OperatorFunction` that emits only defined values from the {@link LoadingState}.
  */ function valueFromLoadingState() {
     return function(obs) {
         return obs.pipe(map(function(x) {
@@ -4129,6 +4150,8 @@ function startWithBeginLoading(state) {
  *
  * Filters to only emit when the state contains an error, then extracts and emits the {@link ReadableError}.
  *
+ * @returns An `OperatorFunction` that emits the {@link ReadableError} from error states.
+ *
  * @example
  * ```ts
  * // React to errors from a loading state
@@ -4137,8 +4160,6 @@ function startWithBeginLoading(state) {
  *   tap((error) => console.error('Loading failed:', error))
  * ).subscribe();
  * ```
- *
- * @returns An `OperatorFunction` that emits the {@link ReadableError} from error states.
  */ function errorFromLoadingState() {
     return function(obs) {
         return obs.pipe(filter(isLoadingStateWithError), map(function(x) {
@@ -4152,6 +4173,8 @@ function startWithBeginLoading(state) {
  * Passes through non-error states unchanged, but throws the error from any {@link LoadingStateWithError},
  * converting the loading state error into an observable error that can be caught with `catchError`.
  *
+ * @returns An `OperatorFunction` that passes through non-error states and throws on error states.
+ *
  * @example
  * ```ts
  * // Convert a LoadingState observable to a Promise, throwing on error states
@@ -4162,8 +4185,6 @@ function startWithBeginLoading(state) {
  *   )
  * );
  * ```
- *
- * @returns An `OperatorFunction` that passes through non-error states and throws on error states.
  */ function throwErrorFromLoadingStateError() {
     return function(obs) {
         return obs.pipe(map(function(x) {
@@ -4246,6 +4267,8 @@ function catchLoadingStateErrorWithOperator(operator) {
             if (isLoadingStateWithError(state)) {
                 // map the value using the error state
                 mappedObs = of(state).pipe(operator, // if the operator does not return nearly instantly, then return the current state, minus a value
+                // TODO(breaking-change): consider tightening this operator's generic constraints (or accepting Partial<L> for the placeholder) so the structural spread can satisfy L without the double cast.
+                // TODO: Fix eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- L is a generic Partial<PageLoadingState> subtype; the spread literal cannot structurally satisfy that intersection without this cast
                 timeoutStartWith(_object_spread_props$5(_object_spread$5({}, state), {
                     loading: true,
                     value: undefined
@@ -4308,6 +4331,9 @@ function distinctLoadingState(inputConfig) {
  * Waits for the first finished loading state, then resolves with the value. If the finished state
  * contains an error, the promise is rejected with that error.
  *
+ * @param obs - The observable emitting {@link LoadingState} values.
+ * @returns Resolves with the first finished value or rejects when the finished state carries an error.
+ *
  * @example
  * ```ts
  * // Await a loading state observable as a promise
@@ -4324,9 +4350,6 @@ function distinctLoadingState(inputConfig) {
  *   throw e;
  * });
  * ```
- *
- * @param obs - The observable emitting {@link LoadingState} values.
- * @returns A Promise that resolves with the value or rejects with the error.
  */ function promiseFromLoadingState(obs) {
     return firstValueFrom(obs.pipe(filter(isLoadingStateFinishedLoading))).then(function(x) {
         var result;
@@ -4345,9 +4368,9 @@ function distinctLoadingState(inputConfig) {
  * Determines the `loading` flag based on whether an error is present, whether the value is defined,
  * and the `showLoadingOnUndefinedValue` setting. Loading progress is only included while loading.
  *
- * @param state - the current loading state to convert into a context event
- * @param input - configuration input controlling how the loading flag is derived
- * @returns a loading state context event derived from the given state
+ * @param state - The current loading state to convert into a context event.
+ * @param input - Configuration input controlling how the loading flag is derived.
+ * @returns A loading state context event derived from the given state.
  */ var DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION = function DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION(state, input) {
     var showLoadingOnUndefinedValue = input.showLoadingOnUndefinedValue;
     var error = state.error, value = state.value, loadingProgress = state.loadingProgress;
@@ -4373,6 +4396,9 @@ function distinctLoadingState(inputConfig) {
  * Accepts either a raw observable or a {@link LoadingStateContextConfig} for fine-grained control
  * over how loading events are derived from the state.
  *
+ * @param input - Optional observable or config to initialize the context.
+ * @returns A mutable loading state context with reactive accessors.
+ *
  * @example
  * ```ts
  * // Create a context from a state observable
@@ -4390,9 +4416,6 @@ function distinctLoadingState(inputConfig) {
  * // Clean up
  * context.destroy();
  * ```
- *
- * @param input - optional observable or config to initialize the context
- * @returns a mutable loading state context with reactive accessors
  */ function loadingStateContext(input) {
     var _ref, _ref1;
     var _config = input && isObservable(input) ? {
@@ -4452,15 +4475,15 @@ function distinctLoadingState(inputConfig) {
  *
  * Returns true if the value is nullish or has zero length, regardless of loading status.
  *
+ * @param listLoadingState - The list loading state to check.
+ * @returns True if the value is empty or absent.
+ *
  * @example
  * ```ts
  * isListLoadingStateWithEmptyValue(successResult([])); // true
  * isListLoadingStateWithEmptyValue(successResult([1, 2])); // false
  * isListLoadingStateWithEmptyValue(beginLoading()); // true (no value)
  * ```
- *
- * @param listLoadingState - the list loading state to check
- * @returns true if the value is empty or absent
  */ function isListLoadingStateWithEmptyValue(listLoadingState) {
     var _listLoadingState_value;
     return Boolean(!((_listLoadingState_value = listLoadingState.value) === null || _listLoadingState_value === void 0 ? void 0 : _listLoadingState_value.length));
@@ -4468,14 +4491,14 @@ function distinctLoadingState(inputConfig) {
 /**
  * RxJS operator that maps each emitted {@link ListLoadingState} to a boolean indicating whether the list is empty.
  *
+ * @returns An operator that emits true when the list value is empty or absent.
+ *
  * @example
  * ```ts
  * of(successResult([])).pipe(
  *   mapIsListLoadingStateWithEmptyValue()
  * ).subscribe((isEmpty) => console.log(isEmpty)); // true
  * ```
- *
- * @returns an operator that emits true when the list value is empty or absent
  */ function mapIsListLoadingStateWithEmptyValue() {
     return map(isListLoadingStateWithEmptyValue);
 }
@@ -4484,16 +4507,16 @@ function distinctLoadingState(inputConfig) {
  *
  * Uses {@link loadingStateFromObs} internally and attaches the page number to each emitted state.
  *
+ * @param obs - The source observable to wrap.
+ * @param firstOnly - If true, only takes the first value.
+ * @param page - The page number to attach (defaults to 0)
+ * @returns An observable of page loading states.
+ *
  * @example
  * ```ts
  * const pageState$ = pageLoadingStateFromObs(fetchItems$, false, 2);
  * // emits: { loading: true, page: 2 }, then { value: items, loading: false, page: 2 }
  * ```
- *
- * @param obs - the source observable to wrap
- * @param firstOnly - if true, only takes the first value
- * @param page - the page number to attach (defaults to 0)
- * @returns an observable of page loading states
  */ function pageLoadingStateFromObs(obs, firstOnly) {
     var page = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : 0;
     return loadingStateFromObs(obs, firstOnly).pipe(map(function(x) {
@@ -4507,6 +4530,8 @@ function distinctLoadingState(inputConfig) {
  *
  * Combines {@link valueFromFinishedLoadingState} with a default of `[]`.
  *
+ * @returns An operator that emits the array value or an empty array.
+ *
  * @example
  * ```ts
  * of(successResult([1, 2, 3])).pipe(
@@ -4517,8 +4542,6 @@ function distinctLoadingState(inputConfig) {
  *   arrayValueFromFinishedLoadingState()
  * ).subscribe((items) => console.log(items)); // []
  * ```
- *
- * @returns an operator that emits the array value or an empty array
  */ function arrayValueFromFinishedLoadingState() {
     return function(obs) {
         return obs.pipe(valueFromFinishedLoadingState(function() {
@@ -4585,6 +4608,9 @@ function _type_of$2(obj) {
  * Extends {@link loadingStateContext} with list-aware behavior, including optional array length limiting
  * via {@link LimitArrayConfig} and empty-state detection streams.
  *
+ * @param input - Optional observable or config to initialize the context.
+ * @returns A mutable list loading state context.
+ *
  * @example
  * ```ts
  * const context = listLoadingStateContext<string>();
@@ -4602,9 +4628,6 @@ function _type_of$2(obj) {
  *
  * context.destroy();
  * ```
- *
- * @param input - optional observable or config to initialize the context
- * @returns a mutable list loading state context
  */ function listLoadingStateContext(input) {
     var limitArrayConfig = (typeof input === "undefined" ? "undefined" : _type_of$2(input)) === 'object' ? input : undefined;
     var loadingState = loadingStateContext(_object_spread_props$4(_object_spread$4({}, input), {
@@ -4746,7 +4769,7 @@ function _object_spread_props$3(target, source) {
             /**
      * Whether the current state has a non-null error.
      *
-     * @returns true if the current state contains an error
+     * @returns True if the current state contains an error.
      */ key: "hasError",
             value: function hasError() {
                 return isLoadingStateWithError(this._subject.value);
@@ -4774,7 +4797,7 @@ function _object_spread_props$3(target, source) {
             /**
      * Sets the loading flag and clears any existing error.
      *
-     * @param loading - whether loading is in progress (defaults to true)
+     * @param loading - Whether loading is in progress (defaults to true)
      */ key: "setLoading",
             value: function setLoading() {
                 var loading = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : true;
@@ -4788,8 +4811,8 @@ function _object_spread_props$3(target, source) {
             /**
      * Sets an error state with an optional loading flag.
      *
-     * @param error - the error to set
-     * @param loading - whether loading is still in progress (defaults to false)
+     * @param error - The error to set.
+     * @param loading - Whether loading is still in progress (defaults to false)
      */ key: "setError",
             value: function setError(error) {
                 var loading = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : false;
@@ -5189,10 +5212,9 @@ function itemAccumulator(itemIteration, inputMapItem) {
  * Automatically pages through an accumulator's iteration until the desired number of results
  * is reached or no more pages are available.
  *
- * @param config - configuration specifying the accumulator, result limit, and counting function
- * @returns promise resolving to the final page number and total results count
- *
- * @throws Rejects if the iteration encounters an error during loading
+ * @param config - Configuration specifying the accumulator, result limit, and counting function.
+ * @returns Promise resolving to the final page number and total results count.
+ * @throws {Error} Rejects if the iteration encounters a loading error.
  */ function itemAccumulatorNextPageUntilResultsCount(config) {
     var accumulator = config.accumulator, maxResultsLimit = config.maxResultsLimit, countResults = config.countResultsFunction;
     var getMaxResultsLimit = asGetter(maxResultsLimit);
@@ -5341,8 +5363,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
  * Designed for accumulators where each page returns an array of items. Concatenates all
  * page results into one flat array that grows as new pages are loaded.
  *
- * @param accumulator - accumulator whose page results are arrays to flatten
- * @returns observable emitting the flattened array of all accumulated items
+ * @param accumulator - Accumulator whose page results are arrays to flatten.
+ * @returns Observable emitting the flattened array of all accumulated items.
  */ function flattenAccumulatorResultItemArray(accumulator) {
     return accumulator.currentAllItemPairs$.pipe(scanBuildArray(function(allItems) {
         var pairs = allItems;
@@ -5369,8 +5391,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
  * The loading state reflects whether a page is currently being fetched, while the value
  * always contains the full flattened array of all items loaded so far.
  *
- * @param accumulator - page accumulator whose results are arrays to flatten
- * @returns observable of the combined loading state with all accumulated items
+ * @param accumulator - Page accumulator whose results are arrays to flatten.
+ * @returns Observable of the combined loading state with all accumulated items.
  */ function accumulatorFlattenPageListLoadingState(accumulator) {
     return combineLatest([
         accumulator.itemIteration.currentState$,
@@ -5392,8 +5414,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
  * Unlike {@link accumulatorFlattenPageListLoadingState}, this does not flatten arrays —
  * each accumulated value is included as-is.
  *
- * @param accumulator - page accumulator to observe
- * @returns observable of the combined loading state with all accumulated items
+ * @param accumulator - Page accumulator to observe.
+ * @returns Observable of the combined loading state with all accumulated items.
  */ function accumulatorCurrentPageListLoadingState(accumulator) {
     return combineLatest([
         accumulator.itemIteration.currentState$,
@@ -5411,8 +5433,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
 /**
  * Returns the latest loaded page number from the input accumulator's underlying iteration.
  *
- * @param pageItemAccumulator - accumulator to observe the current page from
- * @returns observable emitting the most recently loaded page number
+ * @param pageItemAccumulator - Accumulator to observe the current page from.
+ * @returns Observable emitting the most recently loaded page number.
  */ function pageItemAccumulatorCurrentPage(pageItemAccumulator) {
     return pageItemAccumulator.itemIteration.latestLoadedPage$;
 }
@@ -5423,9 +5445,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
  *
  * Control flow (next, hasNext, canLoadMore) is delegated directly to the underlying iteration.
  *
- * @param itemIterator - the source iteration to wrap
- * @param config - mapping configuration for transforming loading state values
- * @returns mapped iteration instance with transformed state observables
+ * @param itemIterator - The source iteration to wrap.
+ * @param config - Mapping configuration for transforming loading state values.
+ * @returns Mapped iteration instance with transformed state observables.
  */ function mapItemIteration(itemIterator, config) {
     var hasNext$ = itemIterator.hasNext$;
     var canLoadMore$ = itemIterator.canLoadMore$;
@@ -5512,9 +5534,9 @@ function _object_spread_props$2(target, source) {
  * and transforms its loading state values while preserving page-level operations
  * (nextPage, page load limits, latestLoadedPage).
  *
- * @param itemIteration - the source page iteration to wrap
- * @param config - mapping configuration for transforming loading state values
- * @returns mapped page iteration instance
+ * @param itemIteration - The source page iteration to wrap.
+ * @param config - Mapping configuration for transforming loading state values.
+ * @returns Mapped page iteration instance.
  */ function mappedPageItemIteration(itemIteration, config) {
     function nextPage(request) {
         return itemIteration.nextPage(request);
@@ -5699,8 +5721,8 @@ function _unsupported_iterable_to_array(o, minLen) {
             /**
      * Creates a new iteration instance with the given configuration.
      *
-     * @param config - filter and page limit configuration for this iteration session
-     * @returns new iteration instance ready to begin loading pages
+     * @param config - Filter and page limit configuration for this iteration session.
+     * @returns New iteration instance ready to begin loading pages.
      */ key: "instance",
             value: function instance(config) {
                 return new ItemPageIterationInstance(this, config);
@@ -5741,6 +5763,7 @@ function _unsupported_iterable_to_array(o, minLen) {
                 ];
             }), mergeMap(function(param) {
                 var _param = _sliced_to_array(param, 2), shouldLoadNextPage = _param[0], prevResult = _param[1];
+                var outputObs;
                 if (shouldLoadNextPage) {
                     var nextPageNumber = nextIteratorPageNumber(prevResult); // retry number if error occured
                     var page = filteredPage(nextPageNumber, _this._config);
@@ -5756,19 +5779,24 @@ function _unsupported_iterable_to_array(o, minLen) {
                         }).pipe(first());
                     }));
                     var stateObs = iteratorResultObs.pipe(first(), map(function(result) {
-                        if (result.error != null) {
-                            return {
+                        var mappedState;
+                        if (result.error == null) {
+                            mappedState = successPageResult(nextPageNumber, result);
+                        } else {
+                            mappedState = {
                                 loading: false,
                                 page: nextPageNumber,
                                 error: result.error,
                                 value: result
                             };
                         }
-                        return successPageResult(nextPageNumber, result);
+                        return mappedState;
                     }), startWithBeginLoading(page), shareReplay(1));
-                    return stateObs;
+                    outputObs = stateObs;
+                } else {
+                    outputObs = of(prevResult).pipe();
                 }
-                return of(prevResult).pipe();
+                return outputObs;
             }), map(function(inputState) {
                 var state;
                 if (inputState != null) {
@@ -6007,16 +6035,18 @@ function _unsupported_iterable_to_array(o, minLen) {
  * - `end` is not explicitly `false` and the result value is empty/null (via `hasValueOrNotEmpty`)
  * - Error results are never considered the end
  *
- * @param result - the page result to check
- * @returns `true` if this result indicates no more pages are available
+ * @param result - The page result to check.
+ * @returns `true` if this result indicates no more pages are available.
  */ function isItemPageIteratorResultEndResult(result) {
+    var isEnd;
     if (result.error != null) {
-        return false;
-    }
-    if (result.end != null) {
-        return result.end;
+        isEnd = false;
+    } else if (result.end == null) {
+        isEnd = !hasValueOrNotEmpty(result);
+    } else {
+        isEnd = result.end;
     }
-    return !hasValueOrNotEmpty(result);
+    return isEnd;
 }
 function itemPageIteratorShouldLoadNextPage(request, hasNextAndCanLoadMore, prevResult) {
     return hasNextAndCanLoadMore && // Must be able to load more
@@ -6031,6 +6061,8 @@ function mapItemPageLoadingStateFromResultPageLoadingState() {
 }
 function itemPageLoadingStateFromResultPageLoadingState(input) {
     var _input_value;
+    // TODO(breaking-change): refactor to build the result as an object literal so mapValue narrows V and hasNextPage can be assigned without the cast. See https://github.com/dereekb/dbx-components issue tracking for cleanup.
+    // TODO: Fix eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- cast widens mapValue's V|undefined inference to V and removes readonly so hasNextPage can be assigned; tsc reports both errors without it
     var result = mapLoadingStateResults(input, {
         mapValue: function mapValue(result) {
             return result.value;
@@ -6117,12 +6149,12 @@ function _type_of(obj) {
  *
  * Useful for deferring an action until all locks are released, with a safety timeout to avoid waiting indefinitely.
  *
- * @param config - configuration specifying the lock set, callback, timeout, and optional delay
- * @param config.lockSet - the lock set to monitor for the next unlock event
- * @param config.fn - optional callback to invoke when the lock set unlocks or the timeout is reached
- * @param config.timeout - maximum time in milliseconds to wait before timing out
- * @param config.delayTime - optional delay in milliseconds after unlock before invoking the callback
- * @returns subscription that can be unsubscribed to cancel the wait
+ * @param config - Configuration specifying the lock set, callback, timeout, and optional delay.
+ * @param config.lockSet - The lock set to monitor for the next unlock event.
+ * @param config.fn - Optional callback to invoke when the lock set unlocks or the timeout is reached.
+ * @param config.timeout - Maximum time in milliseconds to wait before timing out.
+ * @param config.delayTime - Optional delay in milliseconds after unlock before invoking the callback.
+ * @returns Subscription that can be unsubscribed to cancel the wait.
  *
  * @example
  * ```ts
@@ -6240,7 +6272,7 @@ function _type_of(obj) {
             /**
      * Locks for a specified number of seconds using the default time lock key.
      *
-     * @param seconds - duration in seconds
+     * @param seconds - Duration in seconds.
      */ key: "lockForSeconds",
             value: function lockForSeconds(seconds) {
                 this.lockForTime(seconds * 1000);
@@ -6250,8 +6282,8 @@ function _type_of(obj) {
             /**
      * Locks for a specified duration in milliseconds, automatically unlocking when the time elapses.
      *
-     * @param milliseconds - lock duration
-     * @param key - optional lock key, defaults to {@link DEFAULT_LOCK_SET_TIME_LOCK_KEY}
+     * @param milliseconds - Lock duration.
+     * @param key - Optional lock key, defaults to {@link DEFAULT_LOCK_SET_TIME_LOCK_KEY}
      */ key: "lockForTime",
             value: function lockForTime(milliseconds, key) {
                 this.addLock(key !== null && key !== void 0 ? key : DEFAULT_LOCK_SET_TIME_LOCK_KEY, of(false).pipe(delay(milliseconds), startWith(true)));
@@ -6262,9 +6294,9 @@ function _type_of(obj) {
      * Registers a lock observable under the given key. The lock is considered active when
      * the observable emits `true`. Empty observables are treated as unlocked.
      *
-     * @param key - identifier for this lock
-     * @param obs - observable that emits the lock state
-     * @returns function that removes this specific lock when called
+     * @param key - Identifier for this lock.
+     * @param obs - Observable that emits the lock state.
+     * @returns Function that removes this specific lock when called.
      *
      * @example
      * ```ts
@@ -6300,7 +6332,7 @@ function _type_of(obj) {
             /**
      * Removes the lock registered under the given key, if it exists.
      *
-     * @param key - identifier of the lock to remove
+     * @param key - Identifier of the lock to remove.
      */ key: "removeLock",
             value: function removeLock(key) {
                 if (this._locks.value.delete(key)) {
@@ -6312,9 +6344,9 @@ function _type_of(obj) {
             /**
      * Registers a callback for the next time this lock set becomes unlocked.
      *
-     * @param config - callback function or configuration object
-     * @param delayTime - optional delay in milliseconds after unlock before invoking the callback
-     * @returns subscription that can be unsubscribed to cancel the wait
+     * @param config - Callback function or configuration object.
+     * @param delayTime - Optional delay in milliseconds after unlock before invoking the callback.
+     * @returns Subscription that can be unsubscribed to cancel the wait.
      */ key: "onNextUnlock",
             value: function onNextUnlock(config, delayTime) {
                 return onLockSetNextUnlock(_object_spread({
@@ -6330,7 +6362,7 @@ function _type_of(obj) {
      * Establishes a parent-child relationship where this lock set's locked state is propagated
      * to the parent. When this lock set is locked, the parent will also reflect a locked state.
      *
-     * @param parent - parent lock set or observable of one; pass `undefined` to detach
+     * @param parent - Parent lock set or observable of one; pass `undefined` to detach.
      */ key: "setParentLockSet",
             value: function setParentLockSet(parent) {
                 var _this = this;
@@ -6349,9 +6381,9 @@ function _type_of(obj) {
             /**
      * Registers a child lock set so its locked state propagates upward to this lock set.
      *
-     * @param lockSet - child lock set to monitor
-     * @param key - optional lock key, auto-generated if not provided
-     * @returns function that removes the child lock relationship when called
+     * @param lockSet - Child lock set to monitor.
+     * @param key - Optional lock key, auto-generated if not provided.
+     * @returns Function that removes the child lock relationship when called.
      */ key: "addChildLockSet",
             value: function addChildLockSet(lockSet) {
                 var key = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : "".concat(LockSet.LOCK_SET_CHILD_INDEX_STEPPER++);
@@ -6372,8 +6404,8 @@ function _type_of(obj) {
      * After the unlock event (or timeout), the optional callback is invoked and then
      * {@link destroy} is called after a short delay.
      *
-     * @param config - optional callback or configuration for the unlock wait
-     * @param delayTime - optional delay in milliseconds after unlock before invoking the callback
+     * @param config - Optional callback or configuration for the unlock wait.
+     * @param delayTime - Optional delay in milliseconds after unlock before invoking the callback.
      */ key: "destroyOnNextUnlock",
             value: function destroyOnNextUnlock(config, delayTime) {
                 var _this = this;
@@ -6547,7 +6579,7 @@ function _define_property(obj, key, value) {
      *
      * If the loading state returns an error, the error is forwarded.
      *
-     * @param loadingStateObs - observable of the loading state to track as the work result
+     * @param loadingStateObs - Observable of the loading state to track as the work result.
      */ key: "startWorkingWithLoadingStateObservable",
             value: function startWorkingWithLoadingStateObservable(loadingStateObs) {
                 var _this = this;
@@ -6573,8 +6605,8 @@ function _define_property(obj, key, value) {
      *
      * It is used in conjunction with startWorking() and ideal for cases where multiple observables or promises are used.
      *
-     * @param loadingStateObs - promise or observable of the loading state to track for errors
-     * @returns a promise that resolves with the value from the loading state or rejects on error
+     * @param loadingStateObs - Promise or observable of the loading state to track for errors.
+     * @returns Resolves with the first non-loading value, or rejects when the loading state surfaces an error.
      */ key: "performTaskWithLoadingState",
             value: function performTaskWithLoadingState(loadingStateObs) {
                 var _this = this;
@@ -6593,7 +6625,8 @@ function _define_property(obj, key, value) {
      *
      * If an error is thrown, the error is forwarded to the reject function.
      *
-     * @param fn - synchronous function that returns the result value or throws an error
+     * @param fn - Synchronous function that returns the result value or throws an error.
+     * @throws Re-throws the error from `fn` after forwarding it to the reject function.
      */ key: "performTaskWithReturnValue",
             value: function performTaskWithReturnValue(fn) {
                 try {
@@ -6609,7 +6642,7 @@ function _define_property(obj, key, value) {
             /**
      * Begins working using a promise.
      *
-     * @param promise - the promise that represents the asynchronous work
+     * @param promise - Asynchronous work whose resolved value should be tracked as the work result.
      */ key: "startWorkingWithPromise",
             value: function startWorkingWithPromise(promise) {
                 this.startWorkingWithObservable(from(promise));
@@ -6619,7 +6652,7 @@ function _define_property(obj, key, value) {
             /**
      * Begins working using an observable.
      *
-     * @param workObs - the observable that represents the asynchronous work and emits the result
+     * @param workObs - The observable that represents the asynchronous work and emits the result.
      */ key: "startWorkingWithObservable",
             value: function startWorkingWithObservable(workObs) {
                 var _this = this;
@@ -6647,7 +6680,7 @@ function _define_property(obj, key, value) {
             /**
      * Sets success on the work.
      *
-     * @param result - the successful result value to pass to the delegate
+     * @param result - The successful result value to pass to the delegate.
      */ key: "success",
             value: function success(result) {
                 this._setComplete(successResult(result));
@@ -6658,7 +6691,7 @@ function _define_property(obj, key, value) {
             /**
      * Sets rejected on the work.
      *
-     * @param error - the error to pass to the delegate as the rejection reason
+     * @param error - The error to pass to the delegate as the rejection reason.
      */ key: "reject",
             value: function reject(error) {
                 this._setComplete(errorResult(error));
@@ -6708,6 +6741,11 @@ function _define_property(obj, key, value) {
  * If the work function returns an observable, it is automatically subscribed to. If it uses
  * the handler directly, the observable return is ignored.
  *
+ * @param config - Work function and delegate configuration.
+ * @param config.work - The work function to execute for each input value.
+ * @param config.delegate - Delegate that receives lifecycle callbacks (start, success, reject)
+ * @returns A factory function that creates WorkInstance for each input.
+ *
  * @example
  * ```ts
  * const factory = workFactory({
@@ -6719,38 +6757,36 @@ function _define_property(obj, key, value) {
  * // instance tracks the work lifecycle
  * ```
  *
- * @param config - work function and delegate configuration
- * @param config.work - the work function to execute for each input value
- * @param config.delegate - delegate that receives lifecycle callbacks (start, success, reject)
- * @returns a factory function that creates WorkInstance for each input
  * @__NO_SIDE_EFFECTS__
  */ function workFactory(param) {
     var work = param.work, delegate = param.delegate;
     return function(value) {
         var handler = new WorkInstance(value, delegate);
-        var fnResult;
+        var fnResult = undefined;
+        var result;
         try {
             fnResult = work(value, handler);
+            result = handler;
         } catch (e) {
             console.error('Work encountered an unexpected error.', e);
             handler.reject(e);
-            return;
         }
-        if (!handler.isComplete && fnResult && isObservable(fnResult)) {
+        if (result != null && !handler.isComplete && fnResult && isObservable(fnResult)) {
             if (handler.hasStarted) {
                 throw new Error('Work already marked as begun from returned result. Either return an observable or use the handler directly.');
             }
             handler.startWorkingWithObservable(fnResult);
         }
-        return handler;
+        return result;
     };
 }
 /**
  * Creates a {@link WorkFactory} that generates a new {@link WorkFactoryConfig} for each input,
  * enabling dynamic work and delegate selection per invocation.
  *
- * @param configFactory - factory that produces work configuration from the input value
- * @returns a work factory with per-invocation configuration
+ * @param configFactory - Factory that produces work configuration from the input value.
+ * @returns A work factory with per-invocation configuration.
+ *
  * @__NO_SIDE_EFFECTS__
  */ function workFactoryForConfigFactory(configFactory) {
     return function(value) {