@dereekb/rxjs 13.0.7 → 13.2.0

package/index.esm.js

@@ -9,18 +9,19 @@ function asObservable(valueOrObs) {
     }
 }
 /**
- * Switch map for an ObservableGetter that pipes through the value.
+ * RxJS operator that flattens an emitted {@link ObservableOrValue} into its unwrapped value via `switchMap`.
  *
- * @returns OperatorFunction<ObservableOrValue<T>, T>
+ * @returns an operator that unwraps ObservableOrValue emissions
  */ function valueFromObservableOrValue() {
     return switchMap(function(x) {
         return asObservable(x);
     });
 }
 /**
- * Switch map for an ObservableGetter that pipes through the Maybe value.
+ * RxJS operator that flattens an emitted Maybe<{@link ObservableOrValue}> into its unwrapped value,
+ * emitting `undefined` when the input is nullish.
  *
- * @returns OperatorFunction<Maybe<ObservableOrValue<T>>, Maybe<T>>
+ * @returns an operator that unwraps Maybe<ObservableOrValue> emissions
  */ function maybeValueFromObservableOrValue() {
     return switchMap(function(x) {
         return x != null ? asObservable(x) : of(undefined);
@@ -31,15 +32,18 @@ function asObservableFromGetter(input, args) {
     return asObservable(obs);
 }
 /**
- * Switch map for an ObservableOrValueGetter that pipes through the value.
+ * RxJS operator that flattens an emitted {@link ObservableOrValueGetter} into its resolved value via `switchMap`.
  *
- * @returns
+ * @returns an operator that unwraps getter emissions
  */ function valueFromObservableOrValueGetter() {
     return switchMap(function(x) {
         return asObservableFromGetter(x);
     });
 }
-function maybeValueFromObservableOrValueGetter() {
+/**
+ * RxJS operator that flattens an emitted Maybe<{@link ObservableOrValueGetter}> into its resolved value,
+ * emitting `undefined` when the input is nullish.
+ */ function maybeValueFromObservableOrValueGetter() {
     return switchMap(function(x) {
         return x != null ? asObservableFromGetter(x) : of(undefined);
     });
@@ -95,9 +99,10 @@ function _unsupported_iterable_to_array$b(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$b(o, minLen);
 }
 /**
- * Creates an IsModifiedFunction from an IsEqualFunction, or from IsModifiedFunctionInput.
+ * Creates an {@link IsModifiedFunction} by inverting the result of an {@link IsEqualFunction}.
  *
- * @param isEqualFunction
+ * @param isEqualFunction - equality check function to invert
+ * @returns a function that returns true when the value has been modified
  */ function makeIsModifiedFunction(isEqualFunction) {
     return function(value) {
         return isEqualFunction(value).pipe(map(function(x) {
@@ -106,10 +111,13 @@ function _unsupported_iterable_to_array$b(o, minLen) {
     };
 }
 /**
- * Creates an Observable<IsModifiedFunction> from the input config.
+ * Creates an observable that emits an {@link IsModifiedFunction} derived from the config.
  *
- * @param config MakeIsModifiedFunctionObservableConfig.
- * @returns Observable<IsModifiedFunction<T>>
+ * 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
  */ function makeIsModifiedFunctionObservable(config) {
     var isModified = config.isModified, isEqual = config.isEqual, defaultFunction = config.defaultFunction;
     return combineLatest([
@@ -124,29 +132,53 @@ function _unsupported_iterable_to_array$b(o, minLen) {
     }));
 }
 // MARK: IsCheck
-function makeReturnIfIsFunction(isCheckFunction, defaultValueOnMaybe) {
+/**
+ * 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
+ */ function makeReturnIfIsFunction(isCheckFunction, defaultValueOnMaybe) {
     return function(value) {
         return returnIfIs(isCheckFunction, value, defaultValueOnMaybe);
     };
 }
-function returnIfIs(isCheckFunction, value, defaultValueOnMaybe) {
+/**
+ * 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
+ */ function returnIfIs(isCheckFunction, value, defaultValueOnMaybe) {
     return checkIs(isCheckFunction, value, defaultValueOnMaybe).pipe(map(function(x) {
         return x ? value : undefined;
     }));
 }
-function makeCheckIsFunction(isCheckFunction, defaultValueOnMaybe) {
+/**
+ * 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
+ */ function makeCheckIsFunction(isCheckFunction, defaultValueOnMaybe) {
     return function(value) {
         return checkIs(isCheckFunction, value, defaultValueOnMaybe);
     };
 }
-function checkIs(isCheckFunction, value) {
+/**
+ * Evaluates a value against an optional check function, returning an observable boolean.
+ *
+ * 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)
+ */ 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);
     return is;
 }
 // MARK: Filter
 /**
- * Observable filter that filters maybe value that are defined.
+ * RxJS operator that filters out null and undefined values, only passing through defined values.
  */ function filterMaybe() {
     return filter(isMaybeSo);
 }
@@ -154,34 +186,36 @@ function checkIs(isCheckFunction, value) {
  * Equivalent to filterMaybe, but returns a strict MaybeSoStrict<T> value instead of the template type.
  */ var filterMaybeStrict = filterMaybe;
 /**
- * Observable filter that filters out MaybeNot values from the input array of maybe values
+ * RxJS operator that filters out null/undefined elements from an emitted array, keeping only defined values.
  */ function filterMaybeArray() {
     return map(filterMaybeArrayValues);
 }
 /**
- * Skips all initial maybe values, and then returns all values after the first non-null/undefined value is returned.
+ * RxJS operator that skips all leading null/undefined emissions, then passes all subsequent values through.
  */ function skipAllInitialMaybe() {
     return skipWhile(function(x) {
         return x == null;
     });
 }
 /**
- * Skips only the first maybe value, then returns all values afterwards.
+ * RxJS operator that skips only the first emission if it is null/undefined, then passes all subsequent values.
  */ function skipInitialMaybe() {
     return skipMaybes(1);
 }
 /**
- * Skips up to the given number of maybe values, and then returns all values after the first non-null/undefined value is returned.
+ * 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
  */ function skipMaybes(maxToSkip) {
     return skipWhile(function(x, i) {
         return x == null && i < maxToSkip;
     });
 }
 /**
- * Provides a switchMap that will emit the observable if the observable is defined, otherwise will return the default value.
+ * RxJS operator that switches to the emitted observable if defined, or emits the default value if null/undefined.
  *
- * @param defaultValue
- * @returns
+ * @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) {
@@ -207,7 +241,8 @@ function switchMapToDefault(defaultObs, useDefault) {
     });
 }
 /**
- * Provides a switchMap that retrieves and emits the value from the observable, unless the value is null/undefined/true in which case it emits the default value. If the value is false, null is emitted.
+ * RxJS operator that resolves an observable/getter config input into a value, applying defaults
+ * for `null`/`undefined`/`true` inputs and emitting `null` for `false`.
  */ function switchMapObject(config) {
     var defaultGetter = config.defaultGetter;
     return switchMap(function(inputConfig) {
@@ -239,9 +274,9 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
     });
 }
 /**
- * Combines both filterMaybe and switchMap to build a subscriber that emits values only from a concrete Observable, filtering out null/undefined Observables.
+ * RxJS operator that filters out null/undefined observables and then switches to the remaining ones.
  *
- * @returns
+ * Combines {@link filterMaybe} and `switchMap` to only subscribe to non-nullish observables.
  */ function switchMapFilterMaybe() {
     return function(source) {
         var subscriber = source.pipe(filterMaybe(), switchMap(function(x) {
@@ -251,9 +286,7 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
     };
 }
 /**
- * Converts a Maybe<Observable<Maybe<T>>> to an Observable<Maybe<T>> that emits null/undefined if the input observable is also null/undefined.
- *
- * @returns
+ * RxJS operator that switches to the emitted observable if defined, or emits `undefined` when the observable is nullish.
  */ function switchMapMaybe() {
     return function(source) {
         var subscriber = source.pipe(switchMap(function(x) {
@@ -263,18 +296,19 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
     };
 }
 /**
- * Performs the input map function on the input if it is not null/undefined.
+ * RxJS operator that applies a map function only when the emitted value is non-null/non-undefined.
  *
- * @param mapFn
- * @returns
+ * @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);
 }
 /**
- * Performs the input map function on the input if the decision returns true.
+ * RxJS operator that applies a map function only when the decision function returns true.
  *
- * @param mapFn
- * @returns
+ * @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;
@@ -319,9 +353,20 @@ function switchMapOnBoolean(switchOnValue, obs, otherwise) {
 }
 
 /**
- * Equivalent to distinctUntilChanged() using areEqualPOJOValues().
+ * RxJS operator that suppresses consecutive emissions when the emitted POJO values are deeply equal.
+ *
+ * Uses {@link areEqualPOJOValues} for comparison, so the emitted objects should be plain objects
+ * or compatible with deep value equality checks.
  *
- * The compared objects should only be POJOs or compatable with the areEqualPOJOValues() function.
+ * @returns operator that filters out consecutive duplicate POJO emissions
+ *
+ * @example
+ * ```ts
+ * of({ a: 1 }, { a: 1 }, { a: 2 }).pipe(
+ *   distinctUntilObjectValuesChanged()
+ * ).subscribe(console.log);
+ * // Output: { a: 1 }, { a: 2 }
+ * ```
  */ function distinctUntilObjectValuesChanged() {
     return distinctUntilChanged(function(a, b) {
         return areEqualPOJOValues(a, b);
@@ -396,7 +441,22 @@ function _unsupported_iterable_to_array$a(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$a(o, minLen);
 }
 /**
- * Destroyable object that wraps an Unsubscribable.
+ * Manages a single RxJS subscription with automatic cleanup on reassignment.
+ *
+ * When a new subscription is assigned, the previous one is automatically unsubscribed.
+ * Implements {@link Destroyable} for integration with lifecycle management patterns.
+ *
+ * @example
+ * ```ts
+ * const sub = new SubscriptionObject();
+ *
+ * // Assign a subscription — previous one is automatically unsubscribed
+ * sub.subscription = interval(1000).subscribe(console.log);
+ * sub.subscription = interval(500).subscribe(console.log); // first subscription is cleaned up
+ *
+ * // Clean up when done
+ * sub.destroy();
+ * ```
  */ var SubscriptionObject = /*#__PURE__*/ function() {
     function SubscriptionObject(sub) {
         _class_call_check$8(this, SubscriptionObject);
@@ -408,25 +468,35 @@ function _unsupported_iterable_to_array$a(o, minLen) {
     _create_class$7(SubscriptionObject, [
         {
             key: "hasSubscription",
-            get: function get() {
+            get: /**
+     * Whether a subscription is currently being managed.
+     */ function get() {
                 return Boolean(this._subscription);
             }
         },
         {
             key: "subscription",
-            set: function set(sub) {
+            set: /**
+     * Sets the managed subscription, unsubscribing from any previous one.
+     */ function set(sub) {
                 this.setSub(sub);
             }
         },
         {
-            key: "setSub",
+            /**
+     * Replaces the current subscription with the given one, unsubscribing from the previous.
+     *
+     * @param sub - new subscription to manage, or `undefined`/`void` to just unsubscribe
+     */ key: "setSub",
             value: function setSub(sub) {
                 this.unsub();
                 this._subscription = sub;
             }
         },
         {
-            key: "unsub",
+            /**
+     * Unsubscribes from the current subscription, if any.
+     */ key: "unsub",
             value: function unsub() {
                 if (this._subscription) {
                     this._subscription.unsubscribe();
@@ -435,7 +505,9 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             }
         },
         {
-            key: "destroy",
+            /**
+     * Unsubscribes from the current subscription and releases the reference.
+     */ key: "destroy",
             value: function destroy() {
                 this.unsub();
             }
@@ -444,9 +516,26 @@ function _unsupported_iterable_to_array$a(o, minLen) {
     return SubscriptionObject;
 }();
 /**
- * Destroyable object that wraps an array of subscriptions.
+ * Manages multiple RxJS subscriptions as a group, with bulk unsubscribe and cleanup.
+ *
+ * Useful when multiple independent subscriptions share a lifecycle. For subscriptions that
+ * should be merged into a single stream, consider using RxJS `merge(...)` instead.
+ *
+ * @example
+ * ```ts
+ * const subs = new MultiSubscriptionObject();
+ *
+ * subs.subscriptions = [
+ *   source1$.subscribe(console.log),
+ *   source2$.subscribe(console.log)
+ * ];
  *
- * NOTE: In some cases it might be better to use RXJS's merge(...[]) and subscribe to a single item.
+ * // Add more subscriptions later
+ * subs.addSubs(source3$.subscribe(console.log));
+ *
+ * // Clean up all at once
+ * subs.destroy();
+ * ```
  */ var MultiSubscriptionObject = /*#__PURE__*/ function() {
     function MultiSubscriptionObject(subs) {
         _class_call_check$8(this, MultiSubscriptionObject);
@@ -458,26 +547,38 @@ function _unsupported_iterable_to_array$a(o, minLen) {
     _create_class$7(MultiSubscriptionObject, [
         {
             key: "hasSubscription",
-            get: function get() {
+            get: /**
+     * Whether any subscriptions are currently being managed.
+     */ function get() {
                 var _this__subscriptions;
                 return Boolean((_this__subscriptions = this._subscriptions) === null || _this__subscriptions === void 0 ? void 0 : _this__subscriptions.length);
             }
         },
         {
             key: "subscriptions",
-            set: function set(subs) {
+            set: /**
+     * Replaces all managed subscriptions, unsubscribing from previous ones.
+     */ function set(subs) {
                 this.setSubs(subs);
             }
         },
         {
-            key: "setSubs",
+            /**
+     * Replaces all managed subscriptions with the given ones, unsubscribing from all previous.
+     *
+     * @param subs - new subscription(s) to manage
+     */ key: "setSubs",
             value: function setSubs(subs) {
                 this.unsub();
                 this._subscriptions = convertToArray(subs);
             }
         },
         {
-            key: "addSubs",
+            /**
+     * Adds subscription(s) to the managed set without affecting existing ones. Duplicate subscriptions are ignored.
+     *
+     * @param subs - subscription(s) to add
+     */ key: "addSubs",
             value: function addSubs(subs) {
                 var _this__subscriptions;
                 var nextSubscriptions = _to_consumable_array$5((_this__subscriptions = this._subscriptions) !== null && _this__subscriptions !== void 0 ? _this__subscriptions : []);
@@ -490,7 +591,9 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             }
         },
         {
-            key: "unsub",
+            /**
+     * Unsubscribes from all managed subscriptions and clears the list.
+     */ key: "unsub",
             value: function unsub() {
                 if (this._subscriptions) {
                     this._subscriptions.forEach(function(x) {
@@ -501,7 +604,9 @@ function _unsupported_iterable_to_array$a(o, minLen) {
             }
         },
         {
-            key: "destroy",
+            /**
+     * Unsubscribes from all managed subscriptions and releases references.
+     */ key: "destroy",
             value: function destroy() {
                 this.unsub();
             }
@@ -589,7 +694,27 @@ function _unsupported_iterable_to_array$9(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$9(o, minLen);
 }
 /**
- * A basic FilterSource implementation.
+ * Concrete implementation of {@link FilterSource} that manages reactive filter state with
+ * support for default values, initial values, and explicit overrides.
+ *
+ * Filter priority (highest to lowest):
+ * 1. Explicit filter set via {@link setFilter}
+ * 2. Initial filter set via {@link initWithFilter}
+ * 3. Default filter set via {@link setDefaultFilter}
+ *
+ * @example
+ * ```ts
+ * const source = new FilterSourceInstance<{ active: boolean }>();
+ *
+ * // Set a default filter
+ * source.setDefaultFilter(of({ active: false }));
+ *
+ * // Override with an explicit filter
+ * source.setFilter({ active: true });
+ *
+ * // Reset back to default
+ * source.resetFilter();
+ * ```
  */ var FilterSourceInstance = /*#__PURE__*/ function() {
     function FilterSourceInstance(config) {
         var _this = this;
@@ -601,8 +726,12 @@ function _unsupported_iterable_to_array$9(o, minLen) {
      * The initial filter can only pass through observables that always emit a value.
      */ _define_property$b(this, "_initialFilter", new BehaviorSubject(undefined));
         _define_property$b(this, "_defaultFilter", new BehaviorSubject(undefined));
-        _define_property$b(this, "defaultFilter$", this._defaultFilter.pipe(switchMapFilterMaybe()));
-        _define_property$b(this, "initialFilter$", combineLatest([
+        /**
+     * Observable of the default filter value, emitting when a default is set.
+     */ _define_property$b(this, "defaultFilter$", this._defaultFilter.pipe(switchMapFilterMaybe()));
+        /**
+     * Observable that emits the initial filter value, preferring the init filter over the default.
+     */ _define_property$b(this, "initialFilter$", combineLatest([
             this._initialFilter,
             this._defaultFilter
         ]).pipe(map(function(param) {
@@ -610,7 +739,8 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             return a !== null && a !== void 0 ? a : b;
         }), switchMapFilterMaybe(), distinctUntilChanged(), shareReplay(1)));
         /**
-     * filter$ uses the latest value from any filter.
+     * Observable of the active filter value, resolving to the explicit filter if set,
+     * otherwise falling back to the initial/default filter. Deduplicated by deep value equality.
      */ _define_property$b(this, "filter$", this._filter.pipe(switchMap(function(x) {
             return x != null ? of(x) : _this.initialFilter$;
         }), filterMaybe(), distinctUntilObjectValuesChanged(), shareReplay(1)));
@@ -627,20 +757,32 @@ function _unsupported_iterable_to_array$9(o, minLen) {
     }
     _create_class$6(FilterSourceInstance, [
         {
-            key: "initWithFilter",
+            /**
+     * Sets an initial filter observable that takes priority over the default filter.
+     *
+     * @param filterObs - observable providing the initial filter value
+     */ key: "initWithFilter",
             value: function initWithFilter(filterObs) {
                 this._initialFilter.next(filterObs);
                 this.initFilterTakesPriority();
             }
         },
         {
-            key: "setDefaultFilter",
+            /**
+     * 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
+     */ key: "setDefaultFilter",
             value: function setDefaultFilter(filter) {
                 this._defaultFilter.next(asObservable(filter));
             }
         },
         {
-            key: "setFilter",
+            /**
+     * Sets an explicit filter value that takes priority over the initial and default filters.
+     *
+     * @param filter - the filter value to set
+     */ key: "setFilter",
             value: function setFilter(filter) {
                 this._filter.next(filter);
             }
@@ -654,8 +796,14 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             }
         },
         {
-            // MARK: Accessors
-            key: "setInitialFilterTakesPriority",
+            /**
+     * Controls whether changes to the initial filter automatically reset the explicit filter.
+     *
+     * 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
+     */ key: "setInitialFilterTakesPriority",
             value: function setInitialFilterTakesPriority(initialFilterTakesPriority) {
                 this._initialFilterTakesPriority.next(initialFilterTakesPriority);
                 this.initFilterTakesPriority();
@@ -687,8 +835,9 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             }
         },
         {
-            // MARK: Cleanup
-            key: "destroy",
+            /**
+     * Completes all internal subjects and cleans up subscriptions.
+     */ key: "destroy",
             value: function destroy() {
                 this._initialFilterSub.destroy();
                 this._initialFilterTakesPriority.complete();
@@ -759,7 +908,22 @@ function _unsupported_iterable_to_array$8(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$8(o, minLen);
 }
 /**
- * Class used to keep track of filters keyed by a specific string identifier.
+ * Manages a collection of reactive filters keyed by string identifiers.
+ *
+ * Multiple filter observables can be registered under the same key and their emissions are merged.
+ * Supports default filters that are used when no explicit filter is set.
+ *
+ * @example
+ * ```ts
+ * const filterMap = new FilterMap<{ active: boolean }>();
+ *
+ * // Register a filter observable under a key
+ * filterMap.addFilterObs('users', of({ active: true }));
+ *
+ * // Subscribe to the filter for that key
+ * filterMap.filterForKey('users').subscribe(f => console.log(f));
+ * // Output: { active: true }
+ * ```
  */ var FilterMap = /*#__PURE__*/ function() {
     function FilterMap() {
         _class_call_check$6(this, FilterMap);
@@ -767,7 +931,14 @@ function _unsupported_iterable_to_array$8(o, minLen) {
     }
     _create_class$5(FilterMap, [
         {
-            key: "filterForKey",
+            /**
+     * Returns an observable of the filter value for the given key.
+     *
+     * 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
+     */ key: "filterForKey",
             value: function filterForKey(key) {
                 return this._map.pipe(map(function(x) {
                     return x.get(key);
@@ -777,25 +948,47 @@ function _unsupported_iterable_to_array$8(o, minLen) {
             }
         },
         {
-            key: "addDefaultFilterObs",
+            /**
+     * 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
+     */ key: "addDefaultFilterObs",
             value: function addDefaultFilterObs(key, obs) {
                 this._itemForKey(key).setDefaultFilterObs(obs);
             }
         },
         {
-            key: "addFilterObs",
+            /**
+     * 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
+     */ key: "addFilterObs",
             value: function addFilterObs(key, obs) {
                 this._itemForKey(key).addFilterObs(obs);
             }
         },
         {
-            key: "makeInstance",
+            /**
+     * 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
+     */ key: "makeInstance",
             value: function makeInstance(key) {
                 return new FilterMapKeyInstance(this, key);
             }
         },
         {
-            key: "instanceObsForKeyObs",
+            /**
+     * 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
+     */ key: "instanceObsForKeyObs",
             value: function instanceObsForKeyObs(keyObs) {
                 var _this = this;
                 return keyObs.pipe(distinctUntilChanged(), map(function(x) {
@@ -817,8 +1010,9 @@ function _unsupported_iterable_to_array$8(o, minLen) {
             }
         },
         {
-            // MARK: Cleanup
-            key: "destroy",
+            /**
+     * Destroys all filter items and completes the internal subject.
+     */ key: "destroy",
             value: function destroy() {
                 this._map.value.forEach(function(x) {
                     return x.destroy();
@@ -829,12 +1023,19 @@ function _unsupported_iterable_to_array$8(o, minLen) {
     ]);
     return FilterMap;
 }();
-var FilterMapKeyInstance = /*#__PURE__*/ function() {
+/**
+ * Bound instance of a {@link FilterMap} for a specific key.
+ *
+ * Implements both {@link FilterSource} (provides filter values) and {@link FilterSourceConnector}
+ * (accepts filter sources) for a single filter map entry.
+ */ var FilterMapKeyInstance = /*#__PURE__*/ function() {
     function FilterMapKeyInstance(dbxFilterMap, key) {
         _class_call_check$6(this, FilterMapKeyInstance);
         _define_property$a(this, "_dbxFilterMap", void 0);
         _define_property$a(this, "_key", void 0);
-        _define_property$a(this, "filter$", void 0);
+        /**
+     * Observable of the filter value for this instance's key.
+     */ _define_property$a(this, "filter$", void 0);
         this._dbxFilterMap = dbxFilterMap;
         this._key = key;
         this.filter$ = this._dbxFilterMap.filterForKey(this._key);
@@ -853,13 +1054,17 @@ var FilterMapKeyInstance = /*#__PURE__*/ function() {
             }
         },
         {
-            key: "initWithFilter",
+            /**
+     * Sets the default filter observable for this key.
+     */ key: "initWithFilter",
             value: function initWithFilter(filterObs) {
                 this.dbxFilterMap.addDefaultFilterObs(this.key, filterObs);
             }
         },
         {
-            key: "connectWithSource",
+            /**
+     * Connects a filter source, adding its filter observable to this key's merged filters.
+     */ key: "connectWithSource",
             value: function connectWithSource(filterSource) {
                 this.dbxFilterMap.addFilterObs(this.key, filterSource.filter$);
             }
@@ -960,7 +1165,31 @@ var FilterMapItem = /*#__PURE__*/ function() {
 } 
 ();
 
-function makeMapFilterWithPresetFn(fn) {
+/**
+ * Creates a mapping function that resolves preset references in filters.
+ *
+ * When a filter has a `preset` value, the provided function is called to expand the preset
+ * 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
+ *
+ * @example
+ * ```ts
+ * interface MyFilter extends FilterWithPreset {
+ *   active?: boolean;
+ * }
+ *
+ * const resolve = makeMapFilterWithPresetFn<MyFilter>((f) => {
+ *   if (f.preset === 'active') return { active: true };
+ *   return { active: false };
+ * });
+ *
+ * const result = resolve({ preset: 'active' });
+ * // result === { active: true }
+ * ```
+ */ function makeMapFilterWithPresetFn(fn) {
     return function(filter) {
         if (filter.preset) {
             var result = fn(filter);
@@ -971,7 +1200,12 @@ function makeMapFilterWithPresetFn(fn) {
         }
     };
 }
-function mapFilterWithPreset(fn) {
+/**
+ * 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
+ */ function mapFilterWithPreset(fn) {
     return map(makeMapFilterWithPresetFn(fn));
 }
 
@@ -1035,12 +1269,17 @@ function _is_native_reflect_construct$1() {
     })();
 }
 /**
- * Source that provides a filter observable.
+ * Abstract base class for providing reactive filter state.
+ *
+ * Implementations expose a `filter$` observable that emits the current filter value,
+ * and optionally support initialization from an external observable.
  */ var FilterSource = function FilterSource() {
     _class_call_check$5(this, FilterSource);
 };
 /**
- * A FilterSource that has a filter with a FilterPreset potentially available.
+ * A {@link FilterSource} whose filter type includes an optional preset reference.
+ *
+ * Useful for filter UIs that support both preset configurations and custom filter values.
  */ var PresetFilterSource = /*#__PURE__*/ function(FilterSource) {
     _inherits$1(PresetFilterSource, FilterSource);
     function PresetFilterSource() {
@@ -1050,7 +1289,9 @@ function _is_native_reflect_construct$1() {
     return PresetFilterSource;
 }(FilterSource);
 /**
- * A FilterSourceConnector connects with a Source for a function.
+ * Abstract connector that wires a {@link FilterSource} into a consuming component.
+ *
+ * Implementations define how to subscribe to a filter source and apply its values.
  */ var FilterSourceConnector = function FilterSourceConnector() {
     _class_call_check$5(this, FilterSourceConnector);
 } 
@@ -1185,10 +1426,11 @@ function _ts_generator$1(thisArg, body) {
     }
 }
 /**
- * Creates an observable from the input iteration that checks both the hasNext$ and canLoadMore$ states.
+ * 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
- * @returns
+ * @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) {
         if (canLoadMore) {
@@ -1199,15 +1441,16 @@ function _ts_generator$1(thisArg, body) {
     }), shareReplay(1));
 }
 /**
- * Automatically calls next up to the current maxPageLoadLimit configured on the iterator.
+ * Automatically pages through a {@link PageItemIteration} until its configured max page load limit is reached.
  *
- * If no maximum limit is defined, uses the defaultLimit. If default limit is not defined or null, this will result in an error.
+ * Falls back to the provided default limit if no max is configured on the iterator.
  *
- * The promise will reject with an error if an error is encountered.
+ * @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
  *
- * @param iterator
- * @param defaultLimit
- * @returns
+ * @throws {Error} If neither a max page load limit nor a default limit is defined
+ * @throws 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() {
@@ -1220,13 +1463,14 @@ function _ts_generator$1(thisArg, body) {
     });
 }
 /**
- * Automatically calls next on the PageItemIteration up to the target page, the number of total pages that should be loaded.
+ * Automatically pages through a {@link PageItemIteration} until the specified page number is reached,
+ * respecting the iteration's max page load limit.
  *
- * The promise will reject with an error if an error is encountered.
+ * @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
  *
- * @param iteration
- * @param page
- * @returns
+ * @throws Rejects if the iteration encounters a loading error
  */ function iteratorNextPageUntilPage(iteration, page) {
     var getPageLimit = asGetter(page);
     function checkPageLimit(page) {
@@ -1330,15 +1574,14 @@ function scanIntoArray() {
     }, []);
 }
 /**
- * Used to lazy build an array from two observables.
- *
- * The piped observable is for retrieving the seed value, and the accumulatorObs observable is used for
- * retrieving values going forward.
+ * Lazily builds an array from a seed observable and an accumulator observable.
  *
- * This is useful in cases where values are very large.
+ * The piped observable provides the seed state, while `accumulatorObs` provides values that
+ * are incrementally appended. Useful when loading large datasets where the initial page and
+ * subsequent pages come from different sources.
  *
- * @param param0
- * @returns
+ * @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;
@@ -1358,10 +1601,10 @@ function scanIntoArray() {
 }
 // MARK: MapForEach
 /**
- * Convenience function that calls forEachWithArray() and returns the original array.
+ * RxJS operator that executes a side-effect on each element of the emitted array, then passes the array through.
  *
- * @param forEach
- * @returns
+ * @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);
@@ -1370,7 +1613,14 @@ function scanIntoArray() {
     });
 }
 /**
- * Operator function that maps each value in the array independently using Observables, then combines the all results.
+ * RxJS operator that maps each element in an emitted array through an async observable function,
+ * then combines all results using `combineLatest`.
+ *
+ * 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
  */ 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) {
@@ -1388,9 +1638,21 @@ function scanIntoArray() {
 }
 
 /**
- * Emits a value when going from one matching value to a target value.
+ * RxJS operator that emits only when the stream transitions from a `from` value to a `to` value.
  *
- * The first value must be determined first before the second is raised.
+ * 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.
+ *
+ * @example
+ * ```ts
+ * // Emit when transitioning from true to false
+ * source$.pipe(
+ *   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) {
@@ -1447,19 +1709,23 @@ function scanIntoArray() {
 }
 
 /**
- * Returns the pipe if usePipe is true, otherwise returns the identity.
+ * 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
  */ function pipeIf(usePipe, pipe) {
     return usePipe ? pipe : identity;
 }
 /**
- * Maps the opposite value of the input boolean.
+ * RxJS operator that negates each emitted boolean value.
  */ function isNot() {
     return map(function(x) {
         return !x;
     });
 }
 /**
- * Emits a value when moving from a true value to a false value.
+ * RxJS operator that only emits when a boolean stream transitions from `true` to `false`.
  */ function onTrueToFalse() {
     return onMatchDelta({
         from: true,
@@ -1468,7 +1734,7 @@ function scanIntoArray() {
     });
 }
 /**
- * Emits a value when moving from a false value to a true value.
+ * RxJS operator that only emits when a boolean stream transitions from `false` to `true`.
  */ function onFalseToTrue() {
     return onMatchDelta({
         from: false,
@@ -1478,11 +1744,13 @@ function scanIntoArray() {
 }
 
 /**
- * Used to invert an ObservableDecisionFunction's result.
+ * Wraps an {@link ObservableDecisionFunction} to negate its boolean result.
  *
- * @param filterFn
- * @param invert whether or not to apply the inversion.
- * @returns
+ * 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
  */ function invertObservableDecision(decisionFn) {
     var invert = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : true;
     if (invert) {
@@ -1497,10 +1765,14 @@ function scanIntoArray() {
     }
 }
 /**
- * Operator function that uses SwitchMap and filters each of the input values using an ObservableDecisionFunction, and returns them as an array.
+ * RxJS operator that filters an emitted array by evaluating each item through an async {@link ObservableDecisionFunction}.
  *
- * @param observableDecisionFunction
- * @returns
+ * 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
  */ function filterItemsWithObservableDecision(observableDecisionFunction) {
     var throttle = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 20;
     var filterAndMap = filterAndMapFunction(function(x) {
@@ -1531,10 +1803,11 @@ function scanIntoArray() {
 }
 
 /**
- * Creates a new Expires object at the current time on emission that will expire in the set amount of time.
+ * RxJS operator that maps each emission to a new {@link Expires} object with an expiration
+ * time relative to the current moment.
  *
- * @param expiresIn
- * @returns
+ * @param expiresIn - duration in milliseconds until expiration
+ * @returns an operator that maps values to Expires objects
  */ function toExpiration(expiresIn) {
     return map(function() {
         var now = new Date();
@@ -1548,7 +1821,7 @@ function scanIntoArray() {
     });
 }
 /**
- * Filters further emissions once the input is expired.
+ * RxJS operator that filters out emissions whose {@link Expires} value has already expired.
  */ function skipExpired() {
     return filter(function(expires) {
         return !expirationDetails({
@@ -1557,7 +1830,9 @@ function scanIntoArray() {
     });
 }
 /**
- * Skips the input date or timenumber until expiration occurs.
+ * RxJS operator that skips emissions until the elapsed time since the emitted date/timestamp has exceeded `expiresIn`.
+ *
+ * @param expiresIn - duration in milliseconds
  */ function skipUntilExpiration(expiresIn) {
     return filter(function(x) {
         return expirationDetails({
@@ -1567,7 +1842,9 @@ function scanIntoArray() {
     });
 }
 /**
- * Skips the input date or timenumber after expiration occurs.
+ * RxJS operator that skips emissions after the elapsed time since the emitted date/timestamp has exceeded `expiresIn`.
+ *
+ * @param expiresIn - duration in milliseconds
  */ function skipAfterExpiration(expiresIn) {
     return filter(function(x) {
         return !expirationDetails({
@@ -1577,7 +1854,10 @@ function scanIntoArray() {
     });
 }
 /**
- * Skips emissions until time since the last emission from the watch observable has elapsed.
+ * 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
  */ function skipUntilTimeElapsedAfterLastEmission(watch, takeFor) {
     return function(observable) {
         return watch.pipe(switchMap(function() {
@@ -1592,7 +1872,11 @@ function scanIntoArray() {
     };
 }
 /**
- * Takes emissions until time since the last emission from the watch observable has elapsed.
+ * 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
  */ function takeAfterTimeElapsedSinceLastEmission(watch, skipFor) {
     return function(observable) {
         return watch.pipe(switchMap(function() {
@@ -1608,7 +1892,13 @@ function scanIntoArray() {
 }
 
 /**
- * Used to pass a default value incase an observable has not yet started emititng values.
+ * RxJS operator that emits a default value if the source does not emit within the specified timeout.
+ *
+ * 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
  */ function timeoutStartWith(defaultValue) {
     var first = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 0;
     return function(source) {
@@ -1620,7 +1910,13 @@ function scanIntoArray() {
         }));
     };
 }
-function tapAfterTimeout(timeoutDelay, useFn) {
+/**
+ * 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
+ */ function tapAfterTimeout(timeoutDelay, useFn) {
     return timeout({
         first: timeoutDelay,
         with: function _with() {
@@ -1628,7 +1924,13 @@ function tapAfterTimeout(timeoutDelay, useFn) {
         }
     });
 }
-function throwErrorAfterTimeout(timeoutDelay, error) {
+/**
+ * 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
+ */ function throwErrorAfterTimeout(timeoutDelay, error) {
     return timeout({
         first: timeoutDelay,
         with: function _with() {
@@ -1641,10 +1943,23 @@ function throwErrorAfterTimeout(timeoutDelay, error) {
 
 var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
 /**
- * Creates an observable that uses timer internally and maps values from the factory result.
+ * Creates an observable that emits values produced by a factory function on a timer interval.
  *
- * @param config
- * @returns
+ * Wraps `timer()` internally and maps each tick index through the factory. Optionally limits
+ * the total number of emissions.
+ *
+ * @example
+ * ```ts
+ * const countdown$ = factoryTimer({
+ *   factory: (i) => 10 - i,
+ *   interval: 1000,
+ *   limit: 11
+ * });
+ * // 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);
@@ -1659,29 +1974,33 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
 }
 
 /**
- * distinctUntilChanged() that reads the unique identifiers from the input values and compares them for uniqueness.
+ * `distinctUntilChanged` variant for arrays that only emits when the set of keys extracted from
+ * the array elements changes.
  *
- * @param readkey
+ * @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));
 }
 /**
- * Convenience function for distinctUntilChange() that compares the values using a readKey function.
+ * `distinctUntilChanged` variant for single objects that only emits when the extracted key changes.
  *
- * @param readKey
- * @returns
+ * @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));
 }
 
 /**
- * Cleans up the instance when a new value is pushed.
+ * RxJS operator that calls a destroy function on the previous value whenever a new value is emitted.
  *
- * Can be configured to wait until the previous value's destroy promise has resolved.
+ * Ensures proper cleanup of resources when switching between instances. When `wait` is true,
+ * delays emitting the new value until the previous destruction completes.
+ * On unsubscription, the last emitted instance is also destroyed.
  *
- * @param destroy
- * @param wait
- * @returns
+ * @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) {
@@ -1715,9 +2034,10 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
     };
 }
 /**
- * Convenience function for cleanup() on a Destroyable type.
+ * Convenience wrapper for {@link cleanup} that calls `destroy()` on each replaced {@link Destroyable} instance.
  *
- * @returns
+ * @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) {
         return x.destroy();
@@ -1725,9 +2045,17 @@ var DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
 }
 
 /**
- * Operator that returns true until the first item is emitted. Then returns false.
+ * RxJS operator that emits `true` immediately (loading), then `false` after the source emits its first value.
  *
- * @returns
+ * Only considers the first emission from the source. The result is shared via `shareReplay(1)`.
+ *
+ * @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() {
@@ -1751,15 +2079,23 @@ function tapLog(messageOrFunction) {
     return operator;
 }
 /**
- * Used to make a random delay for each observable value.
+ * RxJS operator that adds a random delay before each emission.
  *
- * @param maxOrArgs
- * @returns
+ * 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
  */ function randomDelay(maxOrArgs) {
     var makeRandomDelay = randomNumberFactory(maxOrArgs);
     return randomDelayWithRandomFunction(makeRandomDelay);
 }
-function randomDelayWithRandomFunction(makeRandomDelay) {
+/**
+ * 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
+ */ function randomDelayWithRandomFunction(makeRandomDelay) {
     var scheduler = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : asyncScheduler;
     return delayWhen(function() {
         return timer(makeRandomDelay(), scheduler);
@@ -1767,14 +2103,14 @@ function randomDelayWithRandomFunction(makeRandomDelay) {
 }
 
 /**
- * distinctUntilChanged() that compares id values.
+ * `distinctUntilChanged` variant that only emits when the model's `id` property changes.
  */ function distinctUntilModelIdChange() {
     return distinctUntilObjectKeyChange(function(x) {
         return x.id;
     });
 }
 /**
- * distinctUntilChanged() that compares key values.
+ * `distinctUntilChanged` variant that only emits when the model's `key` property changes.
  */ function distinctUntilModelKeyChange() {
     return distinctUntilObjectKeyChange(function(x) {
         return x.key;
@@ -1782,10 +2118,11 @@ function randomDelayWithRandomFunction(makeRandomDelay) {
 }
 
 /**
- * OperatorFunction that pipes the input from the object with a keys observable to produce the result of mapKeysIntersectionObjectToArray.
+ * 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
- * @returns
+ * @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) {
@@ -1794,9 +2131,9 @@ function randomDelayWithRandomFunction(makeRandomDelay) {
     });
 }
 /**
- * Operatorfunction using distinctUntilChanged to check that two maps have the same keys.
+ * `distinctUntilChanged` variant for `Map` instances that only emits when the set of map keys changes.
  *
- * @returns
+ * @returns an operator that filters out Maps with unchanged key sets
  */ function distinctUntilMapHasDifferentKeys() {
     return distinctUntilChanged(mapsHaveSameKeys);
 }
@@ -1849,7 +2186,11 @@ function _object_spread_props$7(target, source) {
     return target;
 }
 /**
- * Similar to count(), but counts emissions as they occur using scan.
+ * 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
  */ function scanCount() {
     var startAt = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : 0;
     return scan(function(count) {
@@ -1857,10 +2198,10 @@ function _object_spread_props$7(target, source) {
     }, startAt);
 }
 /**
- * Creates a factoryTimer for incrementing numbers.
+ * Creates a {@link factoryTimer} that emits incrementing numbers on an interval.
  *
- * @param config
- * @returns
+ * @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), {
@@ -1915,12 +2256,14 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$6(o, minLen);
 }
 /**
- * Merges both startWith and tapFirst to initialize a pipe.
+ * Combines `startWith` and {@link tapFirst} to initialize an observable pipe with a side-effect on the first emission.
  *
- * @param initial
- * @param tap
- * @param skipFirst
- * @returns
+ * 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
  */ function initialize(tap, initial, skipFirst) {
     return function(source) {
         var subscriber = source.pipe(startWith(initial), tapFirst(function(x) {
@@ -1930,11 +2273,11 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     };
 }
 /**
- * Taps once on the first element.
+ * Executes a side-effect on the first emission from the observable, then passes all values through.
  *
- * @param tap
- * @param skipFirst
- * @returns
+ * @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) {
@@ -1944,13 +2287,13 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     });
 }
 /**
- * Prevents an observable from emitting complete until it is unsubscribed from.
+ * Wraps an observable so that it never emits `complete` until it is unsubscribed.
  *
- * The subscription will never have complete() called as complete only gets called after it unsubscribes,
- * so use finalize() if additional cleanup is required.
+ * The subscription will never have `complete()` called since it only triggers after unsubscription.
+ * Use `finalize()` for additional cleanup.
  *
- * @param obs
- * @returns
+ * @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([
@@ -1964,12 +2307,18 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     }));
 }
 /**
- * Similar to from, but uses a Getter to keeps the Observable cold until it is subscribed to, then calls the promise or observable.
+ * Creates a cold observable that defers execution of the getter until subscription, then shares the result.
  *
- * The result value of the promise or the latest value of the observable is shared.
+ * Unlike `from()`, the promise/observable is not created until the first subscriber connects.
  *
- * @param getter
- * @returns
+ * @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());
@@ -1977,10 +2326,13 @@ function _unsupported_iterable_to_array$6(o, minLen) {
 }
 
 /**
- * Convenience function for building an OperatorFunction that uses filterUniqueFunction().
+ * RxJS operator that filters an array to unique items based on a key reader function.
  *
- * @param readKey
- * @param additionalKeys
+ * 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
  */ function filterUnique(readKey, additionalKeysInput) {
     var filterFn = filterUniqueFunction(readKey, additionalKeysInput);
     return map(function(x) {
@@ -1992,10 +2344,23 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  * Default amount of throttle in milliseconds used by AsyncPusher.
  */ var DEFAULT_ASYNC_PUSHER_THROTTLE = 200;
 /**
- * Creates an AsyncPusher.
+ * Creates an {@link AsyncPusher} — a callable function backed by a throttled {@link BehaviorSubject}.
  *
- * @param config
- * @returns
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const pusher = asyncPusher<string>({ throttle: 100 });
+ * const result$ = pusher('hello');
+ * // subsequent calls within 100ms are throttled
+ * pusher('world');
+ * // 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;
@@ -2037,12 +2402,12 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     return pusher;
 }
 /**
- * Creates a cache that returns an AsyncPusher.
+ * Creates a cached factory that lazily creates and returns an {@link AsyncPusher}.
  *
- * The CachedFactoryWithInput resunt can optionally be pass an observable to watch for the cleanup process.
+ * The factory optionally accepts a cleanup observable — when it completes, the pusher is destroyed.
  *
- * @param config
- * @returns
+ * @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);
@@ -2100,10 +2465,11 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$5(o, minLen);
 }
 /**
- * Creates a map function that maps the input Map to an Observable that returns values mapped from the map's values.
+ * Creates a function that takes a `Map` and combines the latest emissions from observables
+ * created from each map value.
  *
- * @param mapToObs
- * @returns
+ * @param mapToObs - function to transform each map value into an observable
+ * @returns a function that converts a Map to a combined observable of results
  */ function combineLatestFromMapValuesObsFn(mapToObs) {
     var combineArrayFn = combineLatestFromArrayObsFn(mapToObs);
     return function(latestMap) {
@@ -2113,13 +2479,37 @@ function _unsupported_iterable_to_array$5(o, minLen) {
         return combineArrayFn(mapValues);
     };
 }
-function combineLatestFromArrayObsFn(mapToObs) {
+/**
+ * Creates a function that takes an array of values, maps each to an observable, and combines their latest emissions.
+ *
+ * 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
+ */ function combineLatestFromArrayObsFn(mapToObs) {
     return function(latest) {
         var newObs = latest.map(mapToObs);
         return newObs.length ? combineLatest(newObs) : of([]);
     };
 }
-function combineLatestFromObject(objectMap) {
+/**
+ * Combines the latest values from an object of observables into a single observable of resolved values.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const result$ = combineLatestFromObject({
+ *   name: of('Alice'),
+ *   age: of(30)
+ * });
+ * // 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) {
         return asObservable(x[1]).pipe(map(function(value) {
@@ -2140,23 +2530,40 @@ function combineLatestFromObject(objectMap) {
 }
 // MARK: Keys Map
 /**
- * Convenience function for creating a map() operator function using keyValueMapFactory().
+ * RxJS operator that maps an array of items to a `Map<K, T>` using the provided key reader.
  *
- * @param read
- * @returns
+ * @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));
 }
 /**
- * Convenience function for creating a map() operator function using multiKeyValueMapFactory().
+ * 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
- * @returns
+ * @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));
 }
 
-function errorOnEmissionsInPeriod(config) {
+/**
+ * RxJS operator that throws an error (or switches to an alternative observable) when too many
+ * emissions occur within a rolling time period.
+ *
+ * Useful as a safety valve to detect infinite loops or runaway observables.
+ *
+ * @example
+ * ```ts
+ * source$.pipe(
+ *   errorOnEmissionsInPeriod({ maxEmissionsPerPeriod: 100, period: 1000 })
+ * ).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.';
     var errorFactory = inputErrorFactory ? inputErrorFactory : !switchToObs ? function() {
@@ -2187,22 +2594,39 @@ function errorOnEmissionsInPeriod(config) {
     };
 }
 
-function setContainsAllValuesFrom(valuesObs) {
+/**
+ * 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
+ */ function setContainsAllValuesFrom(valuesObs) {
     return combineLatestMapFrom(valuesObs, function(set, values) {
         return setContainsAllValues(set, values !== null && values !== void 0 ? values : []);
     });
 }
-function setContainsAnyValueFrom(valuesObs) {
+/**
+ * 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
+ */ function setContainsAnyValueFrom(valuesObs) {
     return combineLatestMapFrom(valuesObs, function(set, values) {
         return setContainsAnyValue(set, values !== null && values !== void 0 ? values : []);
     });
 }
-function setContainsNoValueFrom(valuesObs) {
+/**
+ * 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
+ */ function setContainsNoValueFrom(valuesObs) {
     return combineLatestMapFrom(valuesObs, function(set, values) {
         return setContainsNoneOfValue(set, values !== null && values !== void 0 ? values : []);
     });
 }
-function distinctUntilHasDifferentValues() {
+/**
+ * `distinctUntilChanged` variant for iterables that only emits when the contained values change.
+ */ function distinctUntilHasDifferentValues() {
     return distinctUntilChanged(hasSameValues);
 }
 function distinctUntilItemsHaveDifferentValues(readValues) {
@@ -2213,7 +2637,24 @@ function distinctUntilItemsValueChanges(readValues, isEqualComparator) {
 }
 
 /**
- * Uses a SearchStringFilterFunction to filter values.
+ * RxJS operator that filters an emitted array by a reactive search string.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const items$ = of(['apple', 'banana', 'cherry']);
+ * const search$ = new BehaviorSubject<string>('an');
+ *
+ * items$.pipe(
+ *   filterWithSearchString({ filter: (x) => x, search$ })
+ * ).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);
@@ -2229,15 +2670,33 @@ function distinctUntilItemsValueChanges(readValues, isEqualComparator) {
 }
 
 /**
- * Convenience function to subscribe to the input observable and use the first value.
+ * Subscribes to the observable, calls the provided function with the first emitted value,
+ * then automatically unsubscribes.
  *
- * @param useFn
+ * @param obs - the source observable
+ * @param useFn - function to call with the first value
  */ function useFirst(obs, useFn) {
     obs.pipe(first()).subscribe(useFn);
 }
 
 /**
- * Creates a switchMap operator that will emit the stream of events from the input LoadingContext as soon as a non-null LoadingContext is emitted.
+ * Creates a `switchMap` operator that subscribes to the {@link LoadingContext.stream$} of each emitted {@link LoadingContext},
+ * emitting `undefined` when the context is nullish.
+ *
+ * Useful for flattening an observable of optional loading contexts into a single stream of loading events.
+ *
+ * @example
+ * ```ts
+ * const context$ = new BehaviorSubject<Maybe<LoadingContext>>(myLoadingContext);
+ *
+ * const events$ = context$.pipe(
+ *   switchMapMaybeLoadingContextStream()
+ * );
+ * // 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);
@@ -2317,20 +2776,33 @@ function _unsupported_iterable_to_array$4(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
 }
 /**
- * Returns true if the two LoadingStates are considered equal, by comparing the loading, loadingProgress, error, and value properties.
+ * Compares two {@link LoadingState} instances for shallow equality across all key properties.
  *
- * @param a LoadingState a
- * @param b LoadingState b
- * @returns Returns true if the input LoadingStates are considered equal.
+ * @example
+ * ```ts
+ * const a = successResult('hello');
+ * const b = successResult('hello');
+ * isLoadingStateEqual(a, b); // true (same value reference is not required, but same primitive is)
+ *
+ * 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;
 }
 /**
- * Returns true if the input LoadingErrorPair has the same loading (truthy vs falsy) and error values as the other LoadingErrorPair.
+ * Compares the metadata (loading flag, loading progress, and error) of two {@link LoadingErrorPair} instances,
+ * using loose equality for loading and nullish-aware comparison for progress and error.
+ *
+ * Does not compare the `value` property — only structural metadata.
  *
- * @param a LoadingErrorPair a
- * @param b LoadingErrorPair b
- * @returns Returns true if the input's metadata is considered equivalent.
+ * @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);
 }
@@ -2353,10 +2825,21 @@ function _unsupported_iterable_to_array$4(o, minLen) {
      */ LoadingStateType["ERROR"] = "error";
 })(LoadingStateType || (LoadingStateType = {}));
 /**
- * Returns the LoadingStateType for the input LoadingState
+ * Determines the current {@link LoadingStateType} of a {@link LoadingState}.
  *
- * @param loadingState
- * @returns
+ * 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.
+ *
+ * @example
+ * ```ts
+ * loadingStateType(beginLoading()); // LoadingStateType.LOADING
+ * loadingStateType(successResult(42)); // LoadingStateType.SUCCESS
+ * 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;
@@ -2373,7 +2856,23 @@ function _unsupported_iterable_to_array$4(o, minLen) {
     }
     return type;
 }
-function isLoadingStateFinishedLoading(state) {
+/**
+ * Whether the given {@link LoadingState} has finished loading.
+ *
+ * Returns `true` when `loading` is explicitly `false`, or when `loading` is not `true`
+ * and either a value, error, or `null` value is present.
+ *
+ * @example
+ * ```ts
+ * isLoadingStateFinishedLoading(successResult('done')); // true
+ * isLoadingStateFinishedLoading(beginLoading()); // false
+ * 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) {
     if (state) {
         var loading = state.loading;
         if (loading === true) {
@@ -2386,7 +2885,16 @@ function isLoadingStateFinishedLoading(state) {
     }
 }
 /**
- * Returns a LoadingState that has no result and is not loading.
+ * Creates an idle {@link LoadingState} with `loading: false` and no value or error.
+ *
+ * Represents a state where no loading has been initiated yet.
+ *
+ * @example
+ * ```ts
+ * const state = idleLoadingState();
+ * // { loading: false }
+ * loadingStateType(state); // LoadingStateType.IDLE
+ * ```
  */ function idleLoadingState() {
     return {
         loading: false
@@ -2399,7 +2907,13 @@ function beginLoading(state) {
         loading: true
     };
 }
-function beginLoadingPage(page, 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`
+ */ function beginLoadingPage(page, state) {
     return state ? _object_spread_props$6(_object_spread$6({
         page: page
     }, state), {
@@ -2409,45 +2923,100 @@ function beginLoadingPage(page, state) {
         loading: true
     };
 }
-function successResult(value) {
+/**
+ * Creates a successful {@link LoadingState} with the given value and `loading: false`.
+ *
+ * @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,
         loading: false
     };
 }
-function successPageResult(page, value) {
+/**
+ * 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
+ */ function successPageResult(page, value) {
     return _object_spread_props$6(_object_spread$6({}, successResult(value)), {
         page: page
     });
 }
-function errorResult(error) {
+/**
+ * Creates a {@link LoadingState} representing an error with `loading: false`.
+ *
+ * Converts the input error to a {@link ReadableError} via {@link toReadableError}.
+ *
+ * @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),
         loading: false
     };
 }
-function errorPageResult(page, error) {
+/**
+ * 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
+ */ function errorPageResult(page, error) {
     return _object_spread_props$6(_object_spread$6({}, errorResult(error)), {
         page: page
     });
 }
 /**
- * Returns true if any of the input LoadingStates return true for isLoadingStateLoading().
+ * Whether any of the given {@link LoadingState} instances are currently loading.
  *
- * @param states
- * @returns
+ * @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);
 }
 /**
- * Returns true if all input LoadingStates return true for isLoadingStateLoading().
+ * Whether all given {@link LoadingState} instances have finished loading.
  *
- * @param states
- * @returns
+ * @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);
 }
-function isLoadingStateWithStateType(type) {
+/**
+ * Creates a predicate function that checks whether a {@link LoadingState} matches the given {@link LoadingStateType}.
+ *
+ * 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
+ */ function isLoadingStateWithStateType(type) {
     var defaultResult = type === LoadingStateType.IDLE ? true : false;
     return function(state) {
         if (state) {
@@ -2485,10 +3054,17 @@ function isLoadingStateWithStateType(type) {
  * @returns
  */ var isLoadingStateInErrorState = isLoadingStateWithStateType(LoadingStateType.ERROR);
 /**
- * Whether or not the input LoadingState has a non-undefined value.
+ * Type guard that checks whether a {@link LoadingState} has a non-undefined value, regardless of loading status.
  *
- * @param state
- * @returns
+ * @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) {
     if (state) {
         return state.value !== undefined;
@@ -2497,10 +3073,16 @@ function isLoadingStateWithStateType(type) {
     }
 }
 /**
- * Whether or not the input LoadingState has a non-null error defined. It may be loading.
+ * Type guard that checks whether a {@link LoadingState} has a non-null error, regardless of loading status.
  *
- * @param state
- * @returns
+ * @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) {
     if (state) {
         return state.error != null;
@@ -2509,10 +3091,10 @@ function isLoadingStateWithStateType(type) {
     }
 }
 /**
- * Whether or not the input LoadingState is not loading and has a non-null value.
+ * Type guard that checks whether a {@link LoadingState} has finished loading and has a defined value.
  *
- * @param state
- * @returns
+ * @param state - the loading state to check
+ * @returns true if finished loading with a non-undefined value
  */ function isLoadingStateFinishedLoadingWithDefinedValue(state) {
     if (state) {
         return isLoadingStateFinishedLoading(state) && state.value !== undefined;
@@ -2521,10 +3103,10 @@ function isLoadingStateWithStateType(type) {
     }
 }
 /**
- * Whether or not the input LoadingState is not loading and has an error defined.
+ * Type guard that checks whether a {@link LoadingState} has finished loading and has an error.
  *
- * @param state
- * @returns
+ * @param state - the loading state to check
+ * @returns true if finished loading with an error
  */ function isLoadingStateFinishedLoadingWithError(state) {
     if (state) {
         return isLoadingStateFinishedLoading(state) && state.error != null;
@@ -2533,12 +3115,26 @@ function isLoadingStateWithStateType(type) {
     }
 }
 /**
- * Returns true if the metadata from both input states are equivalent.
+ * Compares the metadata (page, loading, error) of two {@link PageLoadingState} instances for equivalence.
  *
- * The considered metadata is the page, loading, and error values.
+ * Does not compare values — only structural metadata.
+ *
+ * @example
+ * ```ts
+ * isPageLoadingStateMetadataEqual(
+ *   { page: 1, loading: true },
+ *   { page: 1, loading: true }
+ * ); // true
  *
- * @param a
- * @param b
+ * isPageLoadingStateMetadataEqual(
+ *   { page: 1 },
+ *   { 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);
 }
@@ -2595,7 +3191,13 @@ function mergeLoadingStates() {
     return result;
 }
 /**
- * Returns a new merged state to be loading or idle, and clears the current/error value. It will have a LoadingStateType of LOADING if loading is true.
+ * Returns a copy of the state with the value and error cleared, and `loading` set to the given flag.
+ *
+ * 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
  */ function mergeLoadingStateWithLoading(state) {
     var loading = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : true;
     return _object_spread_props$6(_object_spread$6({}, state), {
@@ -2605,7 +3207,11 @@ function mergeLoadingStates() {
     });
 }
 /**
- * Returns a new merged state with the input value. It will have a LoadingStateType of SUCCESS now.
+ * 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
  */ function mergeLoadingStateWithValue(state, value) {
     return _object_spread_props$6(_object_spread$6({}, state), {
         value: value !== null && value !== void 0 ? value : undefined,
@@ -2614,14 +3220,28 @@ function mergeLoadingStates() {
     });
 }
 /**
- * Returns a new merged state with the input error. It will have a LoadingStateType of ERROR now.
+ * 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
  */ function mergeLoadingStateWithError(state, error) {
     return _object_spread_props$6(_object_spread$6({}, state), {
         loading: false,
         error: error
     });
 }
-function mapMultipleLoadingStateResults(input, config) {
+/**
+ * Maps multiple {@link LoadingState} results into a single state using a value mapping or state mapping function.
+ *
+ * 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
+ *
+ * @throws {Error} When neither `mapValues` nor `mapState` is provided in the config.
+ */ function mapMultipleLoadingStateResults(input, config) {
     var mapValues = config.mapValues, mapState = config.mapState;
     var loading = isAnyLoadingStateInLoadingState(input);
     var error = input.map(function(x) {
@@ -2667,7 +3287,13 @@ function mapLoadingStateResults(input, config) {
     }
     return result;
 }
-function mapLoadingStateValueFunction(mapFn) {
+/**
+ * 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
+ */ function mapLoadingStateValueFunction(mapFn) {
     return function(state) {
         var result;
         if (state.value != null) {
@@ -3111,7 +3737,12 @@ function distinctLoadingState(inputConfig) {
     });
 }
 
-var DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION = function DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION(state, input) {
+/**
+ * Default function for converting a {@link LoadingState} into a {@link LoadingStateContextEvent}.
+ *
+ * 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.
+ */ 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;
     var loading = false;
@@ -3130,10 +3761,32 @@ var DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION = function DEFAULT_LOADING_E
     };
 };
 /**
- * Creates a new LoadingStateContext from the input.
- 
- * @param input LoadingStateContextInput
- * @returns LoadingStateContext
+ * Creates a new {@link MutableLoadingStateContext} that wraps an observable of {@link LoadingState} values
+ * and exposes reactive accessors for the loading flag, current value, errors, and state stream.
+ *
+ * Accepts either a raw observable or a {@link LoadingStateContextConfig} for fine-grained control
+ * over how loading events are derived from the state.
+ *
+ * @example
+ * ```ts
+ * // Create a context from a state observable
+ * const context = loadingStateContext(myLoadingState$);
+ *
+ * // Subscribe to the loading flag
+ * context.loading$.subscribe((loading) => console.log('Loading:', loading));
+ *
+ * // Access the value after loading completes
+ * context.value$.subscribe((value) => console.log('Value:', value));
+ *
+ * // Update the state observable later
+ * context.setStateObs(newLoadingState$);
+ *
+ * // 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) ? {
@@ -3189,22 +3842,51 @@ var DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION = function DEFAULT_LOADING_E
 }
 
 /**
- * Returns true if the loading state is not loading and is empty.
+ * Whether the {@link ListLoadingState} has no value or an empty array.
  *
- * @param listLoadingState
- * @returns
+ * Returns true if the value is nullish or has zero length, regardless of loading status.
+ *
+ * @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) {
     return Boolean(!listLoadingState.value || !listLoadingState.value.length);
 }
 /**
- * Convenience function that merges map() with isListLoadingStateWithEmptyValue()
+ * RxJS operator that maps each emitted {@link ListLoadingState} to a boolean indicating whether the list is empty.
  *
- * @returns
+ * @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);
 }
 /**
- * Wraps an observable output and maps the value to a PageLoadingState.
+ * Wraps an observable and converts its emissions into a {@link PageLoadingState} for the given page number.
+ *
+ * Uses {@link loadingStateFromObs} internally and attaches the page number to each emitted state.
+ *
+ * @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) {
@@ -3213,11 +3895,23 @@ var DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION = function DEFAULT_LOADING_E
     }));
 }
 /**
- * Returns the value once the LoadingState has finished loading, even if an error occured.
+ * RxJS operator that extracts the array value from a finished {@link ListLoadingState},
+ * defaulting to an empty array when no value is present.
  *
- * The value is defaulted to an empty array.
+ * Combines {@link valueFromFinishedLoadingState} with a default of `[]`.
  *
- * @returns Observable of the value
+ * @example
+ * ```ts
+ * of(successResult([1, 2, 3])).pipe(
+ *   arrayValueFromFinishedLoadingState()
+ * ).subscribe((items) => console.log(items)); // [1, 2, 3]
+ *
+ * of(successResult(null)).pipe(
+ *   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() {
@@ -3278,10 +3972,32 @@ function _type_of$2(obj) {
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
 /**
- * Creates a ListLoadingStateContext.
+ * Creates a {@link MutableListLoadingStateContext} that wraps a {@link ListLoadingState} observable
+ * and provides list-specific reactive accessors like `isEmpty$` and `list$`.
+ *
+ * Extends {@link loadingStateContext} with list-aware behavior, including optional array length limiting
+ * via {@link LimitArrayConfig} and empty-state detection streams.
+ *
+ * @example
+ * ```ts
+ * const context = listLoadingStateContext<string>();
+ *
+ * // Set a state observable
+ * context.setStateObs(of(successResult(['a', 'b', 'c'])));
  *
- * @param input Optional configuration for the ListLoadingStateContext.
- * @returns A ListLoadingStateContext.
+ * // Access the list (defaults to [] when undefined)
+ * context.list$.subscribe((list) => console.log(list));
+ * // => ['a', 'b', 'c']
+ *
+ * // Check if the list is empty
+ * context.isEmpty$.subscribe((empty) => console.log('Empty:', empty));
+ * // => false
+ *
+ * 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), {
@@ -3385,7 +4101,21 @@ function _object_spread_props$3(target, source) {
     return target;
 }
 /**
- * Simple LoadingContext implementation
+ * Simple imperative {@link LoadingContext} implementation backed by a {@link BehaviorSubject}.
+ *
+ * Provides methods to manually set loading, success, and error states. Useful in components
+ * or services that need to drive a loading indicator without a dedicated state observable.
+ *
+ * @example
+ * ```ts
+ * const context = new SimpleLoadingContext();
+ * // context starts in loading state by default
+ *
+ * context.setSuccess(); // marks loading as complete
+ * context.setError({ message: 'Something went wrong' }); // sets an error
+ * context.clearError(); // clears the error but preserves loading state
+ * context.destroy(); // completes the internal subject
+ * ```
  */ var SimpleLoadingContext = /*#__PURE__*/ function() {
     function SimpleLoadingContext() {
         var loading = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : true;
@@ -3398,19 +4128,25 @@ function _object_spread_props$3(target, source) {
     }
     _create_class$4(SimpleLoadingContext, [
         {
-            key: "destroy",
+            /**
+     * Completes the internal subject, ending the stream.
+     */ key: "destroy",
             value: function destroy() {
                 this._subject.complete();
             }
         },
         {
-            key: "hasError",
+            /**
+     * Whether the current state has a non-null error.
+     */ key: "hasError",
             value: function hasError() {
                 return isLoadingStateWithError(this._subject.value);
             }
         },
         {
-            key: "clearError",
+            /**
+     * Clears the current error while preserving other state.
+     */ key: "clearError",
             value: function clearError() {
                 this._subject.next(_object_spread_props$3(_object_spread$3({}, this._subject.value), {
                     error: undefined
@@ -3418,13 +4154,19 @@ function _object_spread_props$3(target, source) {
             }
         },
         {
-            key: "setSuccess",
+            /**
+     * Convenience method to mark loading as complete (sets loading to false).
+     */ key: "setSuccess",
             value: function setSuccess() {
                 this.setLoading(false);
             }
         },
         {
-            key: "setLoading",
+            /**
+     * Sets the loading flag and clears any existing error.
+     *
+     * @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;
                 // clears the current error
@@ -3434,7 +4176,12 @@ function _object_spread_props$3(target, source) {
             }
         },
         {
-            key: "setError",
+            /**
+     * 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)
+     */ key: "setError",
             value: function setError(error) {
                 var loading = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : false;
                 this._subject.next({
@@ -3534,7 +4281,31 @@ function _is_native_reflect_construct() {
     })();
 }
 /**
- * Utility object for maintaining a loading stream$. Is triggered into loading, then can be triggered again to see if elements have all completed loading or not.
+ * A {@link SimpleLoadingContext} that determines loading completion by checking whether
+ * all values returned by a check function are defined.
+ *
+ * Useful when loading depends on multiple values arriving asynchronously — call {@link check}
+ * to re-evaluate whether all required values are present.
+ *
+ * @example
+ * ```ts
+ * let valueA: string | undefined;
+ * let valueB: string | undefined;
+ *
+ * const context = new ValuesLoadingContext({
+ *   checkDone: () => [valueA, valueB]
+ * });
+ * // context.stream$ emits { loading: true }
+ *
+ * valueA = 'hello';
+ * context.check(); // still loading (valueB is undefined)
+ *
+ * valueB = 'world';
+ * context.check(); // loading complete (both defined)
+ * // context.stream$ emits { loading: false }
+ *
+ * context.destroy();
+ * ```
  */ var ValuesLoadingContext = /*#__PURE__*/ function(SimpleLoadingContext) {
     _inherits(ValuesLoadingContext, SimpleLoadingContext);
     function ValuesLoadingContext() {
@@ -3550,9 +4321,12 @@ function _is_native_reflect_construct() {
     _create_class$3(ValuesLoadingContext, [
         {
             /**
-     * Check the array for objects to see if loading is completed.
+     * Re-evaluates the check function to determine whether all values are loaded.
      *
-     * The loading state is always modified unless there is an error or no check function.
+     * Sets loading to `false` when every element in the check array is defined.
+     * Does nothing if the context currently has an error.
+     *
+     * @throws {Error} When no check function was provided in the constructor configuration.
      */ key: "check",
             value: function check() {
                 if (!this.hasError()) {
@@ -3803,13 +4577,13 @@ function itemAccumulator(itemIteration, inputMapItem) {
     return result;
 }
 /**
- * Automatically calls next on the accumulator's page item iteration up to the target number of results. Returns the total number of items loaded.
+ * Automatically pages through an accumulator's iteration until the desired number of results
+ * is reached or no more pages are available.
  *
- * The promise will reject with an error if an error is encountered.
+ * @param config - configuration specifying the accumulator, result limit, and counting function
+ * @returns promise resolving to the final page number and total results count
  *
- * @param iteration
- * @param maxResultsLimit
- * @returns
+ * @throws Rejects if the iteration encounters an error during loading
  */ function itemAccumulatorNextPageUntilResultsCount(config) {
     var accumulator = config.accumulator, maxResultsLimit = config.maxResultsLimit, countResults = config.countResultsFunction;
     var getMaxResultsLimit = asGetter(maxResultsLimit);
@@ -3960,10 +4734,13 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$1(o, minLen);
 }
 /**
- * Used for ItemAccumulators that have an array of results returned per page instead of a single item.
+ * Flattens paginated array results from an {@link ItemAccumulator} into a single growing array.
  *
- * @param accumulator
- * @returns
+ * 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
  */ function flattenAccumulatorResultItemArray(accumulator) {
     return accumulator.currentAllItemPairs$.pipe(scanBuildArray(function(allItems) {
         var pairs = allItems;
@@ -3984,7 +4761,14 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     }));
 }
 /**
- * A PageListLoadingState that captures all the values that have been loaded so far, flattens them as an array, and the current loading state of currentPageResult$.
+ * Combines a page accumulator's flattened array results with its current loading state
+ * into a single {@link PageListLoadingState} observable.
+ *
+ * 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
  */ function accumulatorFlattenPageListLoadingState(accumulator) {
     return combineLatest([
         accumulator.itemIteration.currentState$,
@@ -4000,7 +4784,14 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     }), shareReplay(1));
 }
 /**
- * A PageListLoadingState that captures all the values that have been loaded so far, and the current loading state of currentPageResult$.
+ * Combines a page accumulator's collected items with its current loading state
+ * into a single {@link PageListLoadingState} observable.
+ *
+ * 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
  */ function accumulatorCurrentPageListLoadingState(accumulator) {
     return combineLatest([
         accumulator.itemIteration.currentState$,
@@ -4016,20 +4807,23 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     }), shareReplay(1));
 }
 /**
- * Returns the latest loaded page number from the input PageItemAccumulator.
+ * Returns the latest loaded page number from the input accumulator's underlying iteration.
  *
- * @param pageItemAccumulator
- * @returns
+ * @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$;
 }
 
 /**
- * Creates a new MappedItemIteration instance given the input ItemIteration and config.
+ * Creates a {@link MappedItemIterationInstance} that wraps an existing iteration and transforms
+ * its loading state values through the provided mapping configuration.
  *
- * @param itemIteration
- * @param config
- * @returns
+ * 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
  */ function mapItemIteration(itemIterator, config) {
     var hasNext$ = itemIterator.hasNext$;
     var canLoadMore$ = itemIterator.canLoadMore$;
@@ -4112,11 +4906,13 @@ function _object_spread_props$2(target, source) {
     return target;
 }
 /**
- * Creates a new MappedItemIteration instance given the input ItemIteration and config.
+ * Creates a {@link MappedPageItemIterationInstance} that wraps a {@link PageItemIteration}
+ * and transforms its loading state values while preserving page-level operations
+ * (nextPage, page load limits, latestLoadedPage).
  *
- * @param itemIteration
- * @param config
- * @returns
+ * @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);
@@ -4244,12 +5040,24 @@ function _unsupported_iterable_to_array(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 }
-// MARK: Iterator
 /**
- * Default number of pages that can be loaded.
+ * Default maximum number of pages that can be loaded by an {@link ItemPageIterator}.
  */ var DEFAULT_ITEM_PAGE_ITERATOR_MAX = 100;
 /**
- * Used for generating new iterations.
+ * Factory for creating paginated iteration instances from a delegate and configuration.
+ *
+ * The iterator itself holds the delegate (data-loading logic) and optional global page limits.
+ * Call {@link instance} to create a new iteration session with a specific configuration.
+ *
+ * @example
+ * ```ts
+ * const iterator = new ItemPageIterator({
+ *   loadItemsForPage: (request) => fetchPage(request.page)
+ * });
+ *
+ * const instance = iterator.instance({ filter: 'active', maxPageLoadLimit: 10 });
+ * instance.next(); // loads first page
+ * ```
  */ var ItemPageIterator = /*#__PURE__*/ function() {
     function ItemPageIterator(delegate) {
         _class_call_check$2(this, ItemPageIterator);
@@ -4287,10 +5095,10 @@ function _unsupported_iterable_to_array(o, minLen) {
         },
         {
             /**
-     * Creates a new instance based on the input config.
+     * Creates a new iteration instance with the given configuration.
      *
-     * @param config
-     * @returns
+     * @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);
@@ -4300,7 +5108,11 @@ function _unsupported_iterable_to_array(o, minLen) {
     return ItemPageIterator;
 }();
 /**
- * Configured Iterator instance.
+ * Active iteration session created by an {@link ItemPageIterator}.
+ *
+ * Manages the lifecycle of paginated loading: triggering page loads via {@link next},
+ * tracking loading/success/error states, and exposing all results as reactive observables.
+ * Implements {@link PageItemIteration} for use with accumulators and other iteration utilities.
  */ var ItemPageIterationInstance = /*#__PURE__*/ function() {
     function ItemPageIterationInstance(iterator, config) {
         var _this = this;
@@ -4584,15 +5396,16 @@ function _unsupported_iterable_to_array(o, minLen) {
     ]);
     return ItemPageIterationInstance;
 }();
-// MARK: Utility
 /**
- * Is considered the "end" result if:
+ * Determines whether an {@link ItemPageIteratorResult} represents the end of iteration.
  *
- * - end is true
- * - end is not false and the result value is not empty/null. Uses hasValueOrNotEmpty internally to decide.
+ * End is detected when:
+ * - `end` is explicitly `true`
+ * - `end` is not explicitly `false` and the result value is empty/null (via `hasValueOrNotEmpty`)
+ * - Error results are never considered the end
  *
- * @param result
- * @returns
+ * @param result - the page result to check
+ * @returns `true` if this result indicates no more pages are available
  */ function isItemPageIteratorResultEndResult(result) {
     if (result.error != null) {
         return false;
@@ -4693,9 +5506,28 @@ function _type_of(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
-var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
 /**
- * Executes the input function when the lockSet is set unlocked, or the timeout is reached.
+ * Default lock key used by {@link LockSet.lockForTime} when no custom key is provided.
+ */ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
+/**
+ * Subscribes to the next unlock event of a {@link LockSet}, invoking the callback when it becomes unlocked or the timeout expires.
+ *
+ * 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
+ * @returns subscription that can be unsubscribed to cancel the wait
+ *
+ * @example
+ * ```ts
+ * const lockSet = new LockSet();
+ * lockSet.addLock('busy', of(true));
+ *
+ * const sub = onLockSetNextUnlock({
+ *   lockSet,
+ *   fn: (unlocked) => console.log('Unlocked:', unlocked),
+ *   timeout: 5000
+ * });
+ * ```
  */ function onLockSetNextUnlock(param) {
     var lockSet = param.lockSet, fn = param.fn, inputTimeout = param.timeout, delayTime = param.delayTime;
     var timeoutTime = inputTimeout !== null && inputTimeout !== void 0 ? inputTimeout : MS_IN_SECOND * 50;
@@ -4714,9 +5546,29 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
     });
 }
 /**
- * Used for preventing an action until all keys are removed.
+ * Observable-based locking mechanism that prevents actions until all registered locks are released.
+ *
+ * Each lock is identified by a {@link LockKey} and backed by an `Observable<boolean>`. The lock set
+ * is considered locked when any registered observable emits `true`. Empty or completed observables
+ * are treated as unlocked, so locks do not need to be explicitly removed.
+ *
+ * Supports hierarchical locking via parent/child relationships between lock sets.
+ *
+ * @example
+ * ```ts
+ * const lockSet = new LockSet();
  *
- * Added Observables do not need to be strictly removed; empty observables are counted as unlocked.
+ * // Add a lock that is currently active
+ * const removeLock = lockSet.addLock('saving', of(true));
+ *
+ * // Check locked state
+ * lockSet.isLocked$.subscribe(locked => console.log('Locked:', locked));
+ * // Output: Locked: true
+ *
+ * // Remove the lock
+ * removeLock();
+ * // Output: Locked: false
+ * ```
  */ var LockSet = /*#__PURE__*/ function() {
     function LockSet() {
         _class_call_check$1(this, LockSet);
@@ -4724,16 +5576,23 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
         _define_property$1(this, "_onDestroy", new Subject());
         _define_property$1(this, "_locks", new BehaviorSubject(new Map()));
         _define_property$1(this, "_parentSub", new SubscriptionObject());
-        _define_property$1(this, "locks$", this._locks.asObservable());
         /**
-     * isLocked$ is true if any observable is emitting true.
+     * Observable of the current lock map, emitting whenever locks are added or removed.
+     */ _define_property$1(this, "locks$", this._locks.asObservable());
+        /**
+     * Observable that emits `true` when any registered lock observable is emitting `true`.
+     * Emits `false` when all locks are released or the map is empty.
      */ _define_property$1(this, "isLocked$", this.locks$.pipe(switchMap(combineLatestFromMapValuesObsFn(function(x) {
             return x;
         })), map(reduceBooleansWithOrFn(false)), shareReplay(1)));
-        _define_property$1(this, "isUnlocked$", this.isLocked$.pipe(map(function(x) {
+        /**
+     * Observable that emits `true` when no locks are active. Inverse of {@link isLocked$}.
+     */ _define_property$1(this, "isUnlocked$", this.isLocked$.pipe(map(function(x) {
             return !x;
         })));
-        _define_property$1(this, "onDestroy$", this._onDestroy.pipe(shareReplay(1)));
+        /**
+     * Observable that emits when this lock set is destroyed. Useful for cleanup coordination.
+     */ _define_property$1(this, "onDestroy$", this._onDestroy.pipe(shareReplay(1)));
     }
     _create_class$1(LockSet, [
         {
@@ -4771,19 +5630,44 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
             }
         },
         {
-            key: "lockForSeconds",
+            /**
+     * Locks for a specified number of seconds using the default time lock key.
+     *
+     * @param seconds - duration in seconds
+     */ key: "lockForSeconds",
             value: function lockForSeconds(seconds) {
                 this.lockForTime(seconds * 1000);
             }
         },
         {
-            key: "lockForTime",
+            /**
+     * 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}
+     */ 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)));
             }
         },
         {
-            key: "addLock",
+            /**
+     * 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
+     *
+     * @example
+     * ```ts
+     * const lockSet = new LockSet();
+     * const remove = lockSet.addLock('saving', of(true));
+     *
+     * // Later, release the lock
+     * remove();
+     * ```
+     */ key: "addLock",
             value: function addLock(key, obs) {
                 var _this = this;
                 obs = obs.pipe(defaultIfEmpty(false) // empty observables count as unlocked.
@@ -4806,7 +5690,11 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
             }
         },
         {
-            key: "removeLock",
+            /**
+     * Removes the lock registered under the given key, if it exists.
+     *
+     * @param key - identifier of the lock to remove
+     */ key: "removeLock",
             value: function removeLock(key) {
                 if (this._locks.value.delete(key)) {
                     this._locks.next(this.locks);
@@ -4814,7 +5702,13 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
             }
         },
         {
-            key: "onNextUnlock",
+            /**
+     * 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
+     */ key: "onNextUnlock",
             value: function onNextUnlock(config, delayTime) {
                 return onLockSetNextUnlock(_object_spread({
                     lockSet: this,
@@ -4825,7 +5719,12 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
             }
         },
         {
-            key: "setParentLockSet",
+            /**
+     * 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
+     */ key: "setParentLockSet",
             value: function setParentLockSet(parent) {
                 var _this = this;
                 this._parentSub.subscription = preventComplete(asObservable(parent)).pipe(map(function(parentLockSet) {
@@ -4841,7 +5740,11 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
         },
         {
             /**
-     * Convenience function for watching a child lockset's locked state and propogating it upward.
+     * 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
      */ key: "addChildLockSet",
             value: function addChildLockSet(lockSet) {
                 var key = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : "".concat(LockSet.LOCK_SET_CHILD_INDEX_STEPPER++);
@@ -4856,7 +5759,15 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
             }
         },
         {
-            key: "destroyOnNextUnlock",
+            /**
+     * Schedules this lock set for destruction when it next becomes unlocked.
+     *
+     * 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
+     */ key: "destroyOnNextUnlock",
             value: function destroyOnNextUnlock(config, delayTime) {
                 var _this = this;
                 var fn;
@@ -4881,7 +5792,9 @@ var DEFAULT_LOCK_SET_TIME_LOCK_KEY = 'timelock';
             }
         },
         {
-            key: "destroy",
+            /**
+     * Completes all internal subjects, unsubscribes from the parent lock set, and marks this lock set as destroyed.
+     */ key: "destroy",
             value: function destroy() {
                 this._isDestroyed = true;
                 this._locks.complete();
@@ -4928,7 +5841,21 @@ function _define_property(obj, key, value) {
     return obj;
 }
 /**
- * Instance that tracks doing an arbitrary piece of asynchronous work that has an input value and an output value.
+ * Tracks the lifecycle of an asynchronous work unit from start through completion (success or error).
+ *
+ * Exposes reactive streams for monitoring progress (`hasStarted$`, `isComplete$`, `loadingState$`)
+ * and provides methods for starting work via observables, promises, or direct state management.
+ *
+ * @example
+ * ```ts
+ * const instance = new WorkInstance(inputValue, {
+ *   startWorking: () => console.log('started'),
+ *   success: (result) => console.log('done:', result),
+ *   reject: (err) => console.error('failed:', err)
+ * });
+ *
+ * instance.startWorkingWithObservable(of('result'));
+ * ```
  */ var WorkInstance = /*#__PURE__*/ function() {
     function WorkInstance(value, delegate) {
         var _this = this;
@@ -5162,7 +6089,24 @@ function _define_property(obj, key, value) {
 ();
 
 /**
- * Creates a function that handles the incoming value and creates a WorkContext.
+ * Creates a {@link WorkFactory} that executes the configured work function with a {@link WorkInstance} handler.
+ *
+ * If the work function returns an observable, it is automatically subscribed to. If it uses
+ * the handler directly, the observable return is ignored.
+ *
+ * @example
+ * ```ts
+ * const factory = workFactory({
+ *   work: (value: number) => of(`result: ${value}`),
+ *   delegate: { startWorking: () => {}, success: () => {}, reject: () => {} }
+ * });
+ *
+ * const instance = factory(42);
+ * // instance tracks the work lifecycle
+ * ```
+ *
+ * @param config - work function and delegate configuration
+ * @returns a factory function that creates WorkInstance for each input
  */ function workFactory(param) {
     var work = param.work, delegate = param.delegate;
     return function(value) {
@@ -5187,7 +6131,11 @@ function _define_property(obj, key, value) {
     };
 }
 /**
- * Creates a WorkFactory using the input WorkFactoryConfigFactory that generates new work configuration given the input.
+ * 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
  */ function workFactoryForConfigFactory(configFactory) {
     return function(value) {
         var config = configFactory(value);