@dereekb/rxjs 13.0.5 → 13.0.6

package/index.cjs.js

@@ -2753,9 +2753,25 @@ function _unsupported_iterable_to_array$3(o, minLen) {
 }
 // TODO(BREAKING_CHANGE): Fix all LoadingState types to use the LoadingStateValue inference typings
 /**
- * Wraps an observable output and maps the value to a LoadingState.
+ * Wraps an observable output and maps the value to a {@link LoadingState}.
+ *
+ * Emits a loading state immediately, then emits a success result when the observable emits a value,
+ * or an error result if the observable errors.
  *
  * If firstOnly is provided, it will only take the first value the observable returns.
+ *
+ * @example
+ * ```ts
+ * // Wrap a data fetch observable into a LoadingState
+ * readonly jsonContentState$ = loadingStateFromObs(this.jsonContent$);
+ *
+ * // Wrap an observable and only take the first emitted value
+ * readonly singleValueState$ = loadingStateFromObs(this.data$, true);
+ * ```
+ *
+ * @param obs - The source observable to wrap.
+ * @param firstOnly - If true, only takes the first value from the observable.
+ * @returns An observable that emits {@link LoadingState} values representing the loading lifecycle.
  */ function loadingStateFromObs(obs, firstOnly) {
     if (firstOnly) {
         obs = obs.pipe(rxjs.first());
@@ -2792,10 +2808,27 @@ function combineLoadingStates() {
     );
 }
 /**
- * Combines the status of all loading states. Only emits when the LoadingStateType of the result changes, or the loading state progress.
+ * Combines the status of all loading states into a single {@link LoadingState}<boolean>.
  *
- * @param sources
- * @returns
+ * Only emits when the {@link LoadingStateType} of the result changes, or the loading state progress changes.
+ * If any source has an error, the error is propagated. If any source is still loading, the result is loading.
+ * When all sources are successful, the result value is `true`.
+ *
+ * @example
+ * ```ts
+ * const success$ = of(successResult(1));
+ * const success2$ = of(successResult(2));
+ *
+ * // All success => emits { value: true }
+ * const status$ = combineLoadingStatesStatus([success$, success2$]);
+ *
+ * // One loading => emits loading state
+ * const loading$ = of(beginLoading());
+ * const status$ = combineLoadingStatesStatus([loading$, success$]);
+ * ```
+ *
+ * @param sources - An array of LoadingState observables to combine.
+ * @returns An observable emitting a {@link LoadingState}<boolean> representing the combined status.
  */ function combineLoadingStatesStatus(sources) {
     return rxjs.combineLatest(sources).pipe(rxjs.map(function(allLoadingStates) {
         var firstErrorState = allLoadingStates.find(function(x) {
@@ -2821,7 +2854,20 @@ function startWithBeginLoading(state) {
     return rxjs.startWith(beginLoading(state));
 }
 /**
- * Returns the current value from the LoadingState.
+ * Returns the current value from the {@link LoadingState}, including `undefined` when still loading or no value is set.
+ *
+ * Unlike {@link valueFromLoadingState}, this operator emits for every state change, regardless of whether the value is defined.
+ *
+ * @example
+ * ```ts
+ * // Expose the current (possibly undefined) value from a loading state
+ * const currentValue$: Observable<Maybe<T>> = state$.pipe(
+ *   currentValueFromLoadingState(),
+ *   shareReplay(1)
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that maps each {@link LoadingState} to its current value (or undefined).
  */ function currentValueFromLoadingState() {
     return function(obs) {
         return obs.pipe(rxjs.map(function(x) {
@@ -2830,9 +2876,21 @@ function startWithBeginLoading(state) {
     };
 }
 /**
- * Returns the current non-null value from the LoadingState.
+ * Returns the current non-null/non-undefined value from the {@link LoadingState}.
  *
- * Equivalent to currentValueFromLoadingState() and filterMaybe().
+ * Equivalent to piping {@link currentValueFromLoadingState} and `filterMaybeStrict()`.
+ * Only emits when the value is defined, filtering out loading and error states without values.
+ *
+ * @example
+ * ```ts
+ * // Only emit when the loading state has a defined value
+ * const value$ = state$.pipe(
+ *   valueFromLoadingState(),
+ *   // only emits non-null/non-undefined values
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that emits only defined values from the {@link LoadingState}.
  */ function valueFromLoadingState() {
     return function(obs) {
         return obs.pipe(rxjs.map(function(x) {
@@ -2841,7 +2899,20 @@ function startWithBeginLoading(state) {
     };
 }
 /**
- * Returns the error once the LoadingState has finished loading with an error.
+ * Returns the error once the {@link LoadingState} has finished loading with an error.
+ *
+ * Filters to only emit when the state contains an error, then extracts and emits the {@link ReadableError}.
+ *
+ * @example
+ * ```ts
+ * // React to errors from a loading state
+ * state$.pipe(
+ *   errorFromLoadingState(),
+ *   tap((error) => console.error('Loading failed:', error))
+ * ).subscribe();
+ * ```
+ *
+ * @returns An `OperatorFunction` that emits the {@link ReadableError} from error states.
  */ function errorFromLoadingState() {
     return function(obs) {
         return obs.pipe(rxjs.filter(isLoadingStateWithError), rxjs.map(function(x) {
@@ -2850,7 +2921,23 @@ function startWithBeginLoading(state) {
     };
 }
 /**
- * Throws an error if the LoadingState value has an error.
+ * Throws an error if the {@link LoadingState} value has an error.
+ *
+ * Passes through non-error states unchanged, but throws the error from any {@link LoadingStateWithError},
+ * converting the loading state error into an observable error that can be caught with `catchError`.
+ *
+ * @example
+ * ```ts
+ * // Convert a LoadingState observable to a Promise, throwing on error states
+ * const result = await firstValueFrom(
+ *   loadingState$.pipe(
+ *     throwErrorFromLoadingStateError(),
+ *     valueFromFinishedLoadingState()
+ *   )
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that passes through non-error states and throws on error states.
  */ function throwErrorFromLoadingStateError() {
     return function(obs) {
         return obs.pipe(rxjs.map(function(x) {
@@ -2990,12 +3077,30 @@ function distinctLoadingState(inputConfig) {
     };
 }
 /**
- * Creates a promise from a Observable that pipes loading states that resolves the value when the loading state has finished loading.
+ * Creates a Promise from an Observable of {@link LoadingState} that resolves when loading finishes.
  *
- * If the loading state returns an error, the error is thrown.
+ * Waits for the first finished loading state, then resolves with the value. If the finished state
+ * contains an error, the promise is rejected with that error.
  *
- * @param obs
- * @returns
+ * @example
+ * ```ts
+ * // Await a loading state observable as a promise
+ * const value = await promiseFromLoadingState(dataState$);
+ *
+ * // Use within a work instance to forward errors
+ * const result = await promiseFromLoadingState(
+ *   loadingStateObs.pipe(
+ *     filterMaybe(),
+ *     tap(() => this._setWorking(true))
+ *   )
+ * ).catch((e) => {
+ *   this.reject(e);
+ *   throw e;
+ * });
+ * ```
+ *
+ * @param obs - The observable emitting {@link LoadingState} values.
+ * @returns A Promise that resolves with the value or rejects with the error.
  */ function promiseFromLoadingState(obs) {
     return rxjs.firstValueFrom(obs.pipe(rxjs.filter(isLoadingStateFinishedLoading))).then(function(x) {
         var result;

package/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/index.esm.js

@@ -2751,9 +2751,25 @@ function _unsupported_iterable_to_array$3(o, minLen) {
 }
 // TODO(BREAKING_CHANGE): Fix all LoadingState types to use the LoadingStateValue inference typings
 /**
- * Wraps an observable output and maps the value to a LoadingState.
+ * Wraps an observable output and maps the value to a {@link LoadingState}.
+ *
+ * Emits a loading state immediately, then emits a success result when the observable emits a value,
+ * or an error result if the observable errors.
  *
  * If firstOnly is provided, it will only take the first value the observable returns.
+ *
+ * @example
+ * ```ts
+ * // Wrap a data fetch observable into a LoadingState
+ * readonly jsonContentState$ = loadingStateFromObs(this.jsonContent$);
+ *
+ * // Wrap an observable and only take the first emitted value
+ * readonly singleValueState$ = loadingStateFromObs(this.data$, true);
+ * ```
+ *
+ * @param obs - The source observable to wrap.
+ * @param firstOnly - If true, only takes the first value from the observable.
+ * @returns An observable that emits {@link LoadingState} values representing the loading lifecycle.
  */ function loadingStateFromObs(obs, firstOnly) {
     if (firstOnly) {
         obs = obs.pipe(first());
@@ -2790,10 +2806,27 @@ function combineLoadingStates() {
     );
 }
 /**
- * Combines the status of all loading states. Only emits when the LoadingStateType of the result changes, or the loading state progress.
+ * Combines the status of all loading states into a single {@link LoadingState}<boolean>.
  *
- * @param sources
- * @returns
+ * Only emits when the {@link LoadingStateType} of the result changes, or the loading state progress changes.
+ * If any source has an error, the error is propagated. If any source is still loading, the result is loading.
+ * When all sources are successful, the result value is `true`.
+ *
+ * @example
+ * ```ts
+ * const success$ = of(successResult(1));
+ * const success2$ = of(successResult(2));
+ *
+ * // All success => emits { value: true }
+ * const status$ = combineLoadingStatesStatus([success$, success2$]);
+ *
+ * // One loading => emits loading state
+ * const loading$ = of(beginLoading());
+ * const status$ = combineLoadingStatesStatus([loading$, success$]);
+ * ```
+ *
+ * @param sources - An array of LoadingState observables to combine.
+ * @returns An observable emitting a {@link LoadingState}<boolean> representing the combined status.
  */ function combineLoadingStatesStatus(sources) {
     return combineLatest(sources).pipe(map(function(allLoadingStates) {
         var firstErrorState = allLoadingStates.find(function(x) {
@@ -2819,7 +2852,20 @@ function startWithBeginLoading(state) {
     return startWith(beginLoading(state));
 }
 /**
- * Returns the current value from the LoadingState.
+ * Returns the current value from the {@link LoadingState}, including `undefined` when still loading or no value is set.
+ *
+ * Unlike {@link valueFromLoadingState}, this operator emits for every state change, regardless of whether the value is defined.
+ *
+ * @example
+ * ```ts
+ * // Expose the current (possibly undefined) value from a loading state
+ * const currentValue$: Observable<Maybe<T>> = state$.pipe(
+ *   currentValueFromLoadingState(),
+ *   shareReplay(1)
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that maps each {@link LoadingState} to its current value (or undefined).
  */ function currentValueFromLoadingState() {
     return function(obs) {
         return obs.pipe(map(function(x) {
@@ -2828,9 +2874,21 @@ function startWithBeginLoading(state) {
     };
 }
 /**
- * Returns the current non-null value from the LoadingState.
+ * Returns the current non-null/non-undefined value from the {@link LoadingState}.
  *
- * Equivalent to currentValueFromLoadingState() and filterMaybe().
+ * Equivalent to piping {@link currentValueFromLoadingState} and `filterMaybeStrict()`.
+ * Only emits when the value is defined, filtering out loading and error states without values.
+ *
+ * @example
+ * ```ts
+ * // Only emit when the loading state has a defined value
+ * const value$ = state$.pipe(
+ *   valueFromLoadingState(),
+ *   // only emits non-null/non-undefined values
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that emits only defined values from the {@link LoadingState}.
  */ function valueFromLoadingState() {
     return function(obs) {
         return obs.pipe(map(function(x) {
@@ -2839,7 +2897,20 @@ function startWithBeginLoading(state) {
     };
 }
 /**
- * Returns the error once the LoadingState has finished loading with an error.
+ * Returns the error once the {@link LoadingState} has finished loading with an error.
+ *
+ * Filters to only emit when the state contains an error, then extracts and emits the {@link ReadableError}.
+ *
+ * @example
+ * ```ts
+ * // React to errors from a loading state
+ * state$.pipe(
+ *   errorFromLoadingState(),
+ *   tap((error) => console.error('Loading failed:', error))
+ * ).subscribe();
+ * ```
+ *
+ * @returns An `OperatorFunction` that emits the {@link ReadableError} from error states.
  */ function errorFromLoadingState() {
     return function(obs) {
         return obs.pipe(filter(isLoadingStateWithError), map(function(x) {
@@ -2848,7 +2919,23 @@ function startWithBeginLoading(state) {
     };
 }
 /**
- * Throws an error if the LoadingState value has an error.
+ * Throws an error if the {@link LoadingState} value has an error.
+ *
+ * Passes through non-error states unchanged, but throws the error from any {@link LoadingStateWithError},
+ * converting the loading state error into an observable error that can be caught with `catchError`.
+ *
+ * @example
+ * ```ts
+ * // Convert a LoadingState observable to a Promise, throwing on error states
+ * const result = await firstValueFrom(
+ *   loadingState$.pipe(
+ *     throwErrorFromLoadingStateError(),
+ *     valueFromFinishedLoadingState()
+ *   )
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that passes through non-error states and throws on error states.
  */ function throwErrorFromLoadingStateError() {
     return function(obs) {
         return obs.pipe(map(function(x) {
@@ -2988,12 +3075,30 @@ function distinctLoadingState(inputConfig) {
     };
 }
 /**
- * Creates a promise from a Observable that pipes loading states that resolves the value when the loading state has finished loading.
+ * Creates a Promise from an Observable of {@link LoadingState} that resolves when loading finishes.
  *
- * If the loading state returns an error, the error is thrown.
+ * Waits for the first finished loading state, then resolves with the value. If the finished state
+ * contains an error, the promise is rejected with that error.
  *
- * @param obs
- * @returns
+ * @example
+ * ```ts
+ * // Await a loading state observable as a promise
+ * const value = await promiseFromLoadingState(dataState$);
+ *
+ * // Use within a work instance to forward errors
+ * const result = await promiseFromLoadingState(
+ *   loadingStateObs.pipe(
+ *     filterMaybe(),
+ *     tap(() => this._setWorking(true))
+ *   )
+ * ).catch((e) => {
+ *   this.reject(e);
+ *   throw e;
+ * });
+ * ```
+ *
+ * @param obs - The observable emitting {@link LoadingState} values.
+ * @returns A Promise that resolves with the value or rejects with the error.
  */ function promiseFromLoadingState(obs) {
     return firstValueFrom(obs.pipe(filter(isLoadingStateFinishedLoading))).then(function(x) {
         var result;

package/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dereekb/rxjs",
-  "version": "13.0.5",
+  "version": "13.0.6",
   "peerDependencies": {
     "rxjs": "^7.8.0",
-    "@dereekb/util": "13.0.5"
+    "@dereekb/util": "13.0.6"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/loading/loading.state.rxjs.d.ts

@@ -2,13 +2,54 @@ import { type Maybe, type ReadableError, type EqualityComparatorFunction, type G
 import { type MonoTypeOperatorFunction, type OperatorFunction, type Observable, type ObservableInputTuple } from 'rxjs';
 import { type LoadingState, type PageLoadingState, type MapLoadingStateResultsConfiguration, type LoadingStateValue, LoadingStateType, type LoadingStateWithValueType, type LoadingStateWithDefinedValue, type LoadingStateWithError } from './loading.state';
 /**
- * Wraps an observable output and maps the value to a LoadingState.
+ * Wraps an observable output and maps the value to a {@link LoadingState}.
+ *
+ * Emits a loading state immediately, then emits a success result when the observable emits a value,
+ * or an error result if the observable errors.
  *
  * If firstOnly is provided, it will only take the first value the observable returns.
+ *
+ * @example
+ * ```ts
+ * // Wrap a data fetch observable into a LoadingState
+ * readonly jsonContentState$ = loadingStateFromObs(this.jsonContent$);
+ *
+ * // Wrap an observable and only take the first emitted value
+ * readonly singleValueState$ = loadingStateFromObs(this.data$, true);
+ * ```
+ *
+ * @param obs - The source observable to wrap.
+ * @param firstOnly - If true, only takes the first value from the observable.
+ * @returns An observable that emits {@link LoadingState} values representing the loading lifecycle.
  */
 export declare function loadingStateFromObs<T>(obs: Observable<T>, firstOnly?: boolean): Observable<LoadingState<T>>;
 /**
- * Convenience function for creating a pipe that merges the multiple loading states into one.
+ * Convenience function for creating a pipe that merges multiple loading states into one.
+ *
+ * Combines two or more {@link LoadingState} observables using `combineLatest` and merges their values.
+ * If any input is still loading, the combined state is loading. If any input has an error, the error is propagated.
+ * An optional merge function can be provided to customize how the values are combined; otherwise, values are spread-merged.
+ *
+ * @example
+ * ```ts
+ * // Merge two loading states into one combined state using object spread
+ * const combined$ = combineLoadingStates(
+ *   of(successResult({ a: true })),
+ *   of(successResult({ b: true }))
+ * );
+ * // => emits LoadingState<{ a: true } & { b: true }>
+ *
+ * // Merge with a custom merge function
+ * const combined$ = combineLoadingStates(
+ *   of(successResult({ a: 1 })),
+ *   of(successResult({ b: 2 })),
+ *   (a, b) => ({ sum: a.a + b.b })
+ * );
+ * // => emits LoadingState<{ sum: number }> with value { sum: 3 }
+ * ```
+ *
+ * @param args - Two or more LoadingState observables, with an optional merge function as the last argument.
+ * @returns An observable emitting the merged {@link LoadingState}.
  */
 export declare function combineLoadingStates<A, B>(obsA: Observable<LoadingState<A>>, obsB: Observable<LoadingState<B>>): Observable<LoadingState<A & B>>;
 export declare function combineLoadingStates<A extends object, B extends object, O>(obsA: Observable<LoadingState<A>>, obsB: Observable<LoadingState<B>>, mergeFn: (a: A, b: B) => O): Observable<LoadingState<O>>;
@@ -20,82 +61,289 @@ export declare function combineLoadingStates<A extends object, B extends object,
 export declare function combineLoadingStates<A extends object, B extends object, C extends object, D extends object, E extends object, O>(obsA: Observable<LoadingState<A>>, obsB: Observable<LoadingState<B>>, obsC: Observable<LoadingState<C>>, obsD: Observable<LoadingState<D>>, obsE: Observable<LoadingState<E>>, mergeFn: (a: A, b: B, c: C, d: D, e: E) => O): Observable<LoadingState<O>>;
 export declare function combineLoadingStates<O>(...args: any[]): Observable<LoadingState<O>>;
 /**
- * Combines the status of all loading states. Only emits when the LoadingStateType of the result changes, or the loading state progress.
+ * Combines the status of all loading states into a single {@link LoadingState}<boolean>.
+ *
+ * Only emits when the {@link LoadingStateType} of the result changes, or the loading state progress changes.
+ * If any source has an error, the error is propagated. If any source is still loading, the result is loading.
+ * When all sources are successful, the result value is `true`.
+ *
+ * @example
+ * ```ts
+ * const success$ = of(successResult(1));
+ * const success2$ = of(successResult(2));
  *
- * @param sources
- * @returns
+ * // All success => emits { value: true }
+ * const status$ = combineLoadingStatesStatus([success$, success2$]);
+ *
+ * // One loading => emits loading state
+ * const loading$ = of(beginLoading());
+ * const status$ = combineLoadingStatesStatus([loading$, success$]);
+ * ```
+ *
+ * @param sources - An array of LoadingState observables to combine.
+ * @returns An observable emitting a {@link LoadingState}<boolean> representing the combined status.
  */
 export declare function combineLoadingStatesStatus<A extends readonly LoadingState<any>[]>(sources: readonly [...ObservableInputTuple<A>]): Observable<LoadingState<boolean>>;
 /**
- * Merges startWith() with beginLoading().
+ * Merges `startWith()` with `beginLoading()` into a single typed operator.
+ *
+ * Preferred over using both individually, as typing information can get lost when chaining them separately.
+ * An optional partial state can be provided to include additional metadata (e.g., page info) in the initial loading state.
  *
- * Preferred over using both individually, as typing information can get lost.
+ * @example
+ * ```ts
+ * // Emit a loading state immediately before the source observable emits
+ * readonly resultsState$ = this.fetchValues().pipe(
+ *   map((values) => successResult(values)),
+ *   startWithBeginLoading(),
+ *   shareReplay(1)
+ * );
  *
- * @returns
+ * // Use inside a switchMap to re-emit loading on each new search
+ * readonly searchResultsState$ = this.searchText$.pipe(
+ *   switchMap((text) =>
+ *     this.search(text).pipe(
+ *       startWithBeginLoading()
+ *     )
+ *   ),
+ *   shareReplay(1)
+ * );
+ * ```
+ *
+ * @param state - Optional partial loading state to include in the initial emission.
+ * @returns A `MonoTypeOperatorFunction` that prepends a loading state to the observable.
  */
 export declare function startWithBeginLoading<L extends LoadingState>(): MonoTypeOperatorFunction<L>;
 export declare function startWithBeginLoading<L extends LoadingState>(state?: Partial<LoadingState>): MonoTypeOperatorFunction<L>;
 export declare function startWithBeginLoading<L extends PageLoadingState>(state?: Partial<PageLoadingState>): MonoTypeOperatorFunction<L>;
 /**
- * Returns the current value from the LoadingState.
+ * Returns the current value from the {@link LoadingState}, including `undefined` when still loading or no value is set.
+ *
+ * Unlike {@link valueFromLoadingState}, this operator emits for every state change, regardless of whether the value is defined.
+ *
+ * @example
+ * ```ts
+ * // Expose the current (possibly undefined) value from a loading state
+ * const currentValue$: Observable<Maybe<T>> = state$.pipe(
+ *   currentValueFromLoadingState(),
+ *   shareReplay(1)
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that maps each {@link LoadingState} to its current value (or undefined).
  */
 export declare function currentValueFromLoadingState<L extends LoadingState>(): OperatorFunction<L, Maybe<LoadingStateValue<L>>>;
 /**
- * Returns the current non-null value from the LoadingState.
+ * Returns the current non-null/non-undefined value from the {@link LoadingState}.
  *
- * Equivalent to currentValueFromLoadingState() and filterMaybe().
+ * Equivalent to piping {@link currentValueFromLoadingState} and `filterMaybeStrict()`.
+ * Only emits when the value is defined, filtering out loading and error states without values.
+ *
+ * @example
+ * ```ts
+ * // Only emit when the loading state has a defined value
+ * const value$ = state$.pipe(
+ *   valueFromLoadingState(),
+ *   // only emits non-null/non-undefined values
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that emits only defined values from the {@link LoadingState}.
  */
 export declare function valueFromLoadingState<L extends LoadingStateWithDefinedValue>(): OperatorFunction<L, MaybeSoStrict<LoadingStateValue<L>>>;
 /**
- * Returns the error once the LoadingState has finished loading with an error.
+ * Returns the error once the {@link LoadingState} has finished loading with an error.
+ *
+ * Filters to only emit when the state contains an error, then extracts and emits the {@link ReadableError}.
+ *
+ * @example
+ * ```ts
+ * // React to errors from a loading state
+ * state$.pipe(
+ *   errorFromLoadingState(),
+ *   tap((error) => console.error('Loading failed:', error))
+ * ).subscribe();
+ * ```
+ *
+ * @returns An `OperatorFunction` that emits the {@link ReadableError} from error states.
  */
 export declare function errorFromLoadingState<L extends LoadingState>(): OperatorFunction<L, ReadableError>;
 /**
- * Throws an error if the LoadingState value has an error.
+ * Throws an error if the {@link LoadingState} value has an error.
+ *
+ * Passes through non-error states unchanged, but throws the error from any {@link LoadingStateWithError},
+ * converting the loading state error into an observable error that can be caught with `catchError`.
+ *
+ * @example
+ * ```ts
+ * // Convert a LoadingState observable to a Promise, throwing on error states
+ * const result = await firstValueFrom(
+ *   loadingState$.pipe(
+ *     throwErrorFromLoadingStateError(),
+ *     valueFromFinishedLoadingState()
+ *   )
+ * );
+ * ```
+ *
+ * @returns An `OperatorFunction` that passes through non-error states and throws on error states.
  */
 export declare function throwErrorFromLoadingStateError<L extends LoadingState>(): OperatorFunction<L, L>;
 /**
- * Returns the value once the LoadingState has finished loading, even if an error occured or there is no value.
+ * Returns the value once the {@link LoadingState} has finished loading, even if an error occurred or there is no value.
+ *
+ * Filters to only emit when loading is complete, then maps to the value. A default value (or getter) can be
+ * provided to use when the finished state has no value (e.g., due to an error).
  *
- * Can optionally specify a default value to use instead.
+ * @example
+ * ```ts
+ * // Wait for loading to complete and emit the value
+ * const value$ = state$.pipe(
+ *   valueFromFinishedLoadingState(),
+ *   shareReplay(1)
+ * );
+ *
+ * // Provide a default value for error/empty states
+ * const items$ = itemsState$.pipe(
+ *   valueFromFinishedLoadingState(() => []),
+ *   shareReplay(1)
+ * );
+ * ```
+ *
+ * @param defaultValue - Optional default value or getter to use when the finished state has no value.
+ * @returns An `OperatorFunction` that emits the value (or default) once loading is finished.
  */
 export declare function valueFromFinishedLoadingState<L extends LoadingState>(defaultValue: GetterOrValue<LoadingStateValue<L>>): OperatorFunction<L, LoadingStateValue<L>>;
 export declare function valueFromFinishedLoadingState<L extends LoadingState>(defaultValue?: Maybe<GetterOrValue<LoadingStateValue<L>>>): OperatorFunction<L, Maybe<LoadingStateValue<L>>>;
 export declare function valueFromFinishedLoadingState<L extends LoadingStateWithDefinedValue>(): OperatorFunction<L, LoadingStateValue<L>>;
 /**
- * Executes a function when the piped LoadingState has the configured state.
+ * Executes a side-effect function when the piped {@link LoadingState} matches the given {@link LoadingStateType}.
+ *
+ * This is a tap-style operator that does not modify the stream, but calls `fn` when the state matches the specified type.
+ *
+ * @example
+ * ```ts
+ * // Log whenever the state transitions to an error
+ * state$.pipe(
+ *   tapOnLoadingStateType((state) => console.error('Error:', state.error), LoadingStateType.ERROR)
+ * ).subscribe();
  *
- * @param fn
+ * // Trigger an action when loading begins
+ * state$.pipe(
+ *   tapOnLoadingStateType(() => showSpinner(), LoadingStateType.LOADING)
+ * ).subscribe();
+ * ```
+ *
+ * @param fn - The side-effect function to call when the state matches.
+ * @param type - The {@link LoadingStateType} to match against.
+ * @returns A `MonoTypeOperatorFunction` that taps on matching states.
  */
 export declare function tapOnLoadingStateType<L extends LoadingState>(fn: (state: L) => void, type: LoadingStateType): MonoTypeOperatorFunction<L>;
 export declare function tapOnLoadingStateType<L extends LoadingState>(fn: (state: L) => void, type: LoadingStateType): MonoTypeOperatorFunction<L>;
 export declare function tapOnLoadingStateType<L extends PageLoadingState>(fn: (state: L) => void, type: LoadingStateType): MonoTypeOperatorFunction<L>;
 /**
- * Executes a function when the input state has a successful value.
+ * Executes a side-effect function when the input {@link LoadingState} has a successful value.
+ *
+ * This is a convenience wrapper around {@link tapOnLoadingStateType} with {@link LoadingStateType.SUCCESS}.
+ *
+ * @example
+ * ```ts
+ * // Log the successful value
+ * state$.pipe(
+ *   tapOnLoadingStateSuccess((state) => console.log('Loaded:', state.value))
+ * ).subscribe();
+ * ```
  *
- * @param fn
+ * @param fn - The side-effect function to call on success states.
+ * @returns A `MonoTypeOperatorFunction` that taps on successful states.
  */
 export declare function tapOnLoadingStateSuccess<L extends LoadingState>(fn: (state: L) => void): MonoTypeOperatorFunction<L>;
 export declare function tapOnLoadingStateSuccess<L extends LoadingState>(fn: (state: L) => void): MonoTypeOperatorFunction<L>;
 export declare function tapOnLoadingStateSuccess<L extends PageLoadingState>(fn: (state: L) => void): MonoTypeOperatorFunction<L>;
 /**
- * Convenience function for using mapLoadingStateResults with an Observable.
+ * Convenience function for using {@link mapLoadingStateResults} with an Observable.
+ *
+ * Maps the value within a {@link LoadingState} using the provided configuration, preserving the loading/error state metadata.
+ *
+ * @example
+ * ```ts
+ * // Map a SystemState<T> loading state to just its data property
+ * readonly dataState$: Observable<LoadingState<T>> = this.systemStateLoadingState$.pipe(
+ *   mapLoadingState({ mapValue: (x: SystemState<T>) => x.data }),
+ *   shareReplay(1)
+ * );
+ * ```
+ *
+ * @param config - Configuration for mapping the loading state value.
+ * @returns An `OperatorFunction` that maps the value within the loading state.
  */
 export declare function mapLoadingState<A, B, L extends LoadingState<A> = LoadingState<A>, O extends LoadingState<B> = LoadingState<B>>(config: MapLoadingStateResultsConfiguration<A, B, L, O>): OperatorFunction<L, O>;
 export declare function mapLoadingState<A, B, L extends PageLoadingState<A> = PageLoadingState<A>, O extends PageLoadingState<B> = PageLoadingState<B>>(config: MapLoadingStateResultsConfiguration<A, B, L, O>): OperatorFunction<L, O>;
 export declare function mapLoadingState<A, B, L extends Partial<PageLoadingState<A>> = Partial<PageLoadingState<A>>, O extends Partial<PageLoadingState<B>> = Partial<PageLoadingState<B>>>(config: MapLoadingStateResultsConfiguration<A, B, L, O>): OperatorFunction<L, O>;
 /**
- * Convenience function for catching the loading state's error from one value to another using an arbitrary operator.
+ * Maps the value within a {@link LoadingState} using an arbitrary RxJS operator.
+ *
+ * When the state has a defined value, the value is extracted, passed through the provided operator,
+ * and the result is wrapped back into the loading state. If the operator does not emit immediately,
+ * a temporary loading state (with no value) is emitted while waiting.
+ *
+ * Error and loading states are passed through without invoking the operator.
+ *
+ * @example
+ * ```ts
+ * // Filter loading state values using a search string operator
+ * readonly state$: Observable<ListLoadingState<DocValue>> = this._values.pipe(
+ *   switchMap((x) => of(successResult(x)).pipe(startWithBeginLoading())),
+ *   mapLoadingStateValueWithOperator(
+ *     filterWithSearchString({
+ *       filter: (a) => a.name,
+ *       search$: this.search$
+ *     })
+ *   )
+ * );
+ *
+ * // Transform values using switchMap inside the operator
+ * readonly groupsState$ = this.itemsState$.pipe(
+ *   mapLoadingStateValueWithOperator(
+ *     switchMap((items) => this.viewDelegate$.pipe(
+ *       switchMap((delegate) => asObservable(delegate.groupBy(items)))
+ *     ))
+ *   ),
+ *   shareReplay(1)
+ * );
+ * ```
+ *
+ * @param operator - The RxJS operator to apply to the loading state's value.
+ * @param mapOnUndefined - If true, also applies the operator when the value is undefined (but loading is finished and no error).
+ * @returns An `OperatorFunction` that transforms the value within the loading state.
  */
 export declare function mapLoadingStateValueWithOperator<L extends LoadingState, O>(operator: OperatorFunction<LoadingStateValue<L>, O>, mapOnUndefined?: boolean): OperatorFunction<L, LoadingStateWithValueType<L, O>>;
 export declare function mapLoadingStateValueWithOperator<L extends PageLoadingState, O>(operator: OperatorFunction<LoadingStateValue<L>, O>, mapOnUndefined?: boolean): OperatorFunction<L, LoadingStateWithValueType<L, O>>;
 export declare function mapLoadingStateValueWithOperator<L extends Partial<PageLoadingState>, O>(operator: OperatorFunction<LoadingStateValue<L>, O>, mapOnUndefined?: boolean): OperatorFunction<L, LoadingStateWithValueType<L, O>>;
 /**
- * Convenience function for catching an LoadingStateWithError and returning a new LoadingState.
+ * Catches a {@link LoadingStateWithError} and transforms it into a new {@link LoadingState} using the provided operator.
+ *
+ * Non-error states are passed through unchanged. When an error state is encountered, it is passed through the
+ * operator to produce a replacement state. If the operator does not emit immediately, a temporary loading state is emitted.
+ *
+ * @example
+ * ```ts
+ * // On error, return an empty list instead of propagating the error
+ * readonly notificationItemsLoadingState$ = this.store.notificationItemsLoadingState$.pipe(
+ *   catchLoadingStateErrorWithOperator<LoadingState<NotificationItem<any>[]>>(
+ *     map(() => successResult([]))
+ *   )
+ * );
+ * ```
+ *
+ * @param operator - The RxJS operator to apply to the error loading state.
+ * @returns A `MonoTypeOperatorFunction` that catches and transforms error states.
  */
 export declare function catchLoadingStateErrorWithOperator<L extends LoadingState>(operator: OperatorFunction<L & LoadingStateWithError, L>): MonoTypeOperatorFunction<L>;
 export declare function catchLoadingStateErrorWithOperator<L extends PageLoadingState>(operator: OperatorFunction<L & LoadingStateWithError, L>): MonoTypeOperatorFunction<L>;
 export declare function catchLoadingStateErrorWithOperator<L extends Partial<PageLoadingState>>(operator: OperatorFunction<L & LoadingStateWithError, L>): MonoTypeOperatorFunction<L>;
+/**
+ * Config for {@link distinctLoadingState}.
+ */
 export interface DistinctLoadingStateConfig<L extends LoadingState> {
     /**
      * Whether or not to pass the retained value when the next LoadingState's value (the value being considered by this DecisionFunction) is null/undefined.
@@ -117,23 +365,60 @@ export interface DistinctLoadingStateConfig<L extends LoadingState> {
     metadataComparator?: EqualityComparatorFunction<Maybe<Partial<L>>>;
 }
 /**
- * A special distinctUntilChanged-like operator for LoadingState and PageLoadingState.
+ * A special `distinctUntilChanged`-like operator for {@link LoadingState} and {@link PageLoadingState}.
+ *
+ * Retains the previous value and only emits when the value or loading state metadata actually changes,
+ * as determined by the provided value comparator. This prevents unnecessary re-emissions when a loading
+ * state re-emits with an equivalent value.
+ *
+ * Accepts either a simple {@link EqualityComparatorFunction} for comparing values, or a full
+ * {@link DistinctLoadingStateConfig} for more fine-grained control over comparison behavior.
  *
- * It saves the previous value and passes it through whenever the LoadingState changes.
+ * @example
+ * ```ts
+ * // Filter out duplicate loading states using key-based comparison
+ * const distinct$ = values$.pipe(
+ *   distinctLoadingState(objectKeysEqualityComparatorFunction((x) => x))
+ * );
  *
- * @param operator
- * @param mapOnUndefined
- * @returns
+ * // Full config with custom comparator
+ * const distinct$ = values$.pipe(
+ *   distinctLoadingState({
+ *     valueComparator: (a, b) => a?.id === b?.id,
+ *   })
+ * );
+ * ```
+ *
+ * @param config - Either a value comparator function or a full {@link DistinctLoadingStateConfig}.
+ * @returns A `MonoTypeOperatorFunction` that filters out duplicate loading states.
  */
 export declare function distinctLoadingState<L extends LoadingState>(config: EqualityComparatorFunction<Maybe<LoadingStateValue<L>>> | DistinctLoadingStateConfig<L>): MonoTypeOperatorFunction<L>;
 export declare function distinctLoadingState<L extends PageLoadingState>(config: EqualityComparatorFunction<Maybe<LoadingStateValue<L>>> | DistinctLoadingStateConfig<L>): MonoTypeOperatorFunction<L>;
 export declare function distinctLoadingState<L extends Partial<PageLoadingState>>(config: EqualityComparatorFunction<Maybe<LoadingStateValue<L>>> | DistinctLoadingStateConfig<L>): MonoTypeOperatorFunction<L>;
 /**
- * Creates a promise from a Observable that pipes loading states that resolves the value when the loading state has finished loading.
+ * Creates a Promise from an Observable of {@link LoadingState} that resolves when loading finishes.
+ *
+ * Waits for the first finished loading state, then resolves with the value. If the finished state
+ * contains an error, the promise is rejected with that error.
+ *
+ * @example
+ * ```ts
+ * // Await a loading state observable as a promise
+ * const value = await promiseFromLoadingState(dataState$);
  *
- * If the loading state returns an error, the error is thrown.
+ * // Use within a work instance to forward errors
+ * const result = await promiseFromLoadingState(
+ *   loadingStateObs.pipe(
+ *     filterMaybe(),
+ *     tap(() => this._setWorking(true))
+ *   )
+ * ).catch((e) => {
+ *   this.reject(e);
+ *   throw e;
+ * });
+ * ```
  *
- * @param obs
- * @returns
+ * @param obs - The observable emitting {@link LoadingState} values.
+ * @returns A Promise that resolves with the value or rejects with the error.
  */
 export declare function promiseFromLoadingState<T>(obs: Observable<LoadingState<T>>): Promise<T>;