@dereekb/rxjs 13.0.7 → 13.2.0

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

@@ -20,19 +20,32 @@ export interface LoadingErrorPair {
     readonly error?: Maybe<ReadableError>;
 }
 /**
- * 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
  */
 export declare function isLoadingStateEqual<T extends LoadingState>(a: T, b: T): boolean;
 /**
- * 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
  */
 export declare function isLoadingStateMetadataEqual(a: Partial<LoadingErrorPair>, b: Partial<LoadingErrorPair>): boolean;
 /**
@@ -115,39 +128,158 @@ export declare enum LoadingStateType {
     ERROR = "error"
 }
 /**
- * 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}
  */
 export declare function loadingStateType(loadingState: LoadingState): LoadingStateType;
+/**
+ * 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
+ */
 export declare function isLoadingStateFinishedLoading<L extends LoadingState>(state: Maybe<L>): boolean;
 /**
- * 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
+ * ```
  */
 export declare function idleLoadingState<T>(): LoadingState<T>;
+/**
+ * Creates a {@link LoadingState} with `loading: true`, optionally merged with additional state properties.
+ *
+ * @example
+ * ```ts
+ * const state = beginLoading();
+ * // { loading: true }
+ *
+ * const pageState = beginLoading({ page: 2 });
+ * // { page: 2, loading: true }
+ * ```
+ *
+ * @param state - optional partial state to merge with the loading flag
+ * @returns a loading state with `loading: true`
+ */
 export declare function beginLoading<T>(): LoadingState<T>;
 export declare function beginLoading<T>(state?: Partial<PageLoadingState<T>>): PageLoadingState<T>;
 export declare function beginLoading<T>(state?: Partial<LoadingState<T>>): LoadingState<T>;
+/**
+ * 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`
+ */
 export declare function beginLoadingPage<T>(page: PageNumber, state?: Partial<PageLoadingState<T>>): PageLoadingState<T>;
+/**
+ * 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
+ */
 export declare function successResult<T>(value: T): LoadingStateWithValue<T>;
+/**
+ * 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
+ */
 export declare function successPageResult<T>(page: PageNumber, value: T): PageLoadingState<T>;
+/**
+ * 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
+ */
 export declare function errorResult<T>(error?: Maybe<ErrorInput>): LoadingState<T>;
+/**
+ * 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
+ */
 export declare function errorPageResult<T>(page: PageNumber, error?: Maybe<ReadableError | ReadableDataError>): PageLoadingState<T>;
 /**
- * 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
  */
 export declare function isAnyLoadingStateInLoadingState(states: LoadingState[]): boolean;
 /**
- * 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
  */
 export declare function areAllLoadingStatesFinishedLoading(states: LoadingState[]): boolean;
+/**
+ * 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
+ */
 export declare function isLoadingStateWithStateType(type: LoadingStateType): <L extends LoadingState>(state: Maybe<L>) => boolean;
 /**
  * Returns true if the input LoadingState passed to loadingStateType() returns IDLE.
@@ -182,48 +314,97 @@ export declare const isLoadingStateInSuccessState: <L extends LoadingState>(stat
  */
 export declare const isLoadingStateInErrorState: <L extends LoadingState>(state: Maybe<L>) => boolean;
 /**
- * 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
  */
 export declare function isLoadingStateWithDefinedValue<L extends LoadingState>(state: Maybe<L> | LoadingStateWithDefinedValue<LoadingStateValue<L>>): state is LoadingStateWithDefinedValue<LoadingStateValue<L>>;
 /**
- * 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
  */
 export declare function isLoadingStateWithError<L extends LoadingState>(state: Maybe<L> | LoadingState<LoadingStateValue<L>>): state is LoadingStateWithError<LoadingStateValue<L>>;
 /**
- * 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
  */
 export declare function isLoadingStateFinishedLoadingWithDefinedValue<L extends LoadingState>(state: Maybe<L> | LoadingStateWithDefinedValue<LoadingStateValue<L>>): state is LoadingStateWithDefinedValue<LoadingStateValue<L>>;
 /**
- * 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
  */
 export declare function isLoadingStateFinishedLoadingWithError<L extends LoadingState>(state: Maybe<L> | LoadingState<LoadingStateValue<L>>): state is LoadingStateWithError<LoadingStateValue<L>>;
 /**
- * Returns true if the metadata from both input states are equivalent.
+ * Compares the metadata (page, loading, error) of two {@link PageLoadingState} instances for equivalence.
+ *
+ * Does not compare values — only structural metadata.
  *
- * The considered metadata is the page, loading, and error values.
+ * @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
  */
 export declare function isPageLoadingStateMetadataEqual(a: Partial<PageLoadingState>, b: Partial<PageLoadingState>): boolean;
 /**
- * Merges the input LoadingStates.
+ * Merges multiple {@link LoadingState} instances into a single combined state.
+ *
+ * If any input is loading, returns a loading state. If any has an error (and is not still loading),
+ * returns the first error. When all are successful, merges the values using the optional merge function
+ * or `mergeObjects` by default.
  *
- * If one is unavailable, it is considered loading.
- * If one is loading, will return the loading state.
- * If one has an error and is not loading, will return the error with loading false.
+ * @example
+ * ```ts
+ * // Merge two successful states (values spread-merged)
+ * const merged = mergeLoadingStates(
+ *   successResult({ a: 1 }),
+ *   successResult({ b: 2 })
+ * );
+ * // { loading: false, value: { a: 1, b: 2 } }
+ *
+ * // Merge with a custom function
+ * const merged = mergeLoadingStates(
+ *   successResult({ x: 10 }),
+ *   successResult({ y: 20 }),
+ *   (a, b) => ({ sum: a.x + b.y })
+ * );
+ * // { loading: false, value: { sum: 30 } }
+ *
+ * // Any loading input makes the result loading
+ * const merged = mergeLoadingStates(beginLoading(), successResult({ a: 1 }));
+ * // { loading: true }
+ * ```
  */
 export declare function mergeLoadingStates<A extends object, B extends object>(a: LoadingState<A>, b: LoadingState<B>): LoadingState<A & B>;
 export declare function mergeLoadingStates<A extends object, B extends object, O>(a: LoadingState<A>, b: LoadingState<B>, mergeFn: (a: A, b: B) => O): LoadingState<O>;
@@ -235,15 +416,29 @@ export declare function mergeLoadingStates<A extends object, B extends object, C
 export declare function mergeLoadingStates<A extends object, B extends object, C extends object, D extends object, E extends object, O>(a: LoadingState<A>, b: LoadingState<B>, c: LoadingState<C>, d: LoadingState<D>, e: LoadingState<E>, mergeFn: (a: A, b: B, c: C, d: D, e: E) => O): LoadingState<O>;
 export declare function mergeLoadingStates<O>(...args: any[]): LoadingState<O>;
 /**
- * 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
  */
 export declare function mergeLoadingStateWithLoading<S extends LoadingState>(state: S, loading?: boolean): S;
 /**
- * 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
  */
 export declare function mergeLoadingStateWithValue<S extends LoadingState>(state: S, value: LoadingStateValue<S> | undefined): S;
 /**
- * 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
  */
 export declare function mergeLoadingStateWithError<S extends LoadingState = LoadingState>(state: S, error?: ReadableDataError): S;
 export type MapMultipleLoadingStateValuesFn<T, X> = (input: X[]) => T;
@@ -251,6 +446,17 @@ export interface MapMultipleLoadingStateResultsConfiguration<T, X, L extends Loa
     mapValues?: MapMultipleLoadingStateValuesFn<T, X>;
     mapState?: (input: L) => R;
 }
+/**
+ * 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.
+ */
 export declare function mapMultipleLoadingStateResults<T, X, L extends LoadingState<X>[], R extends LoadingState<T>>(input: L, config: MapMultipleLoadingStateResultsConfiguration<T, X, L, R>): Maybe<R>;
 export type MapLoadingStateFn<A, B, L extends LoadingState<A> = LoadingState<A>, O extends LoadingState<B> = LoadingState<B>> = (input: L, value?: B) => O;
 export type MapLoadingStateValuesFn<A, B, L extends LoadingState<A> = LoadingState<A>> = (input: A, state: L) => B;
@@ -259,9 +465,34 @@ export interface MapLoadingStateResultsConfiguration<A, B, L extends LoadingStat
     mapValue?: MapLoadingStateValuesFn<A, B, L>;
     mapState?: MapLoadingStateFn<A, B, L, O>;
 }
+/**
+ * Maps the value of a single {@link LoadingState} to a new type using the provided configuration.
+ *
+ * Preserves the loading/error metadata while transforming the value via `mapValue` or the entire
+ * state via `mapState`. When `alwaysMapValue` is true, maps even when the value is null/undefined.
+ *
+ * @example
+ * ```ts
+ * const result = mapLoadingStateResults(successResult(0), {
+ *   mapValue: (v) => `Value: ${v}`
+ * });
+ * // { value: 'Value: 0', loading: false }
+ * ```
+ *
+ * @param input - the loading state to transform
+ * @param config - mapping configuration
+ * @returns the transformed loading state
+ */
 export declare function mapLoadingStateResults<A, B, L extends LoadingState<A> = LoadingState<A>, O extends LoadingState<B> = LoadingState<B>>(input: L, config: MapLoadingStateResultsConfiguration<A, B, L, O>): O;
 export declare function mapLoadingStateResults<A, B, L extends PageLoadingState<A> = PageLoadingState<A>, O extends PageLoadingState<B> = PageLoadingState<B>>(input: L, config: MapLoadingStateResultsConfiguration<A, B, L, O>): O;
 export declare function mapLoadingStateResults<A, B, L extends Partial<PageLoadingState<A>> = Partial<PageLoadingState<A>>, O extends Partial<PageLoadingState<B>> = Partial<PageLoadingState<B>>>(input: L, config: MapLoadingStateResultsConfiguration<A, B, L, O>): O;
 export type MapLoadingStateValueFunction<O, I, L extends LoadingState<I> = LoadingState<I>> = MapFunction<L, Maybe<O>>;
 export type MapLoadingStateValueMapFunction<O, I, L extends LoadingState<I> = LoadingState<I>> = (item: I, state: L) => Maybe<O>;
+/**
+ * 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
+ */
 export declare function mapLoadingStateValueFunction<O, I, L extends LoadingState<I> = LoadingState<I>>(mapFn: MapLoadingStateValueMapFunction<O, I, L>): MapLoadingStateValueFunction<O, I, L>;

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

@@ -2,27 +2,68 @@ import { type PageNumber } from '@dereekb/util';
 import { type Observable, type OperatorFunction } from 'rxjs';
 import { type LoadingStateValue, type ListLoadingState, type PageLoadingState } from './loading.state';
 /**
- * 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
  */
 export declare function isListLoadingStateWithEmptyValue<T>(listLoadingState: ListLoadingState<T>): boolean;
 /**
- * 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
  */
 export declare function mapIsListLoadingStateWithEmptyValue<T>(): OperatorFunction<ListLoadingState<T>, boolean>;
 /**
- * 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
  */
 export declare function pageLoadingStateFromObs<T>(obs: Observable<T>, firstOnly?: boolean, page?: PageNumber): Observable<PageLoadingState<T>>;
 /**
- * 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.
+ *
+ * Combines {@link valueFromFinishedLoadingState} with a default of `[]`.
+ *
+ * @example
+ * ```ts
+ * of(successResult([1, 2, 3])).pipe(
+ *   arrayValueFromFinishedLoadingState()
+ * ).subscribe((items) => console.log(items)); // [1, 2, 3]
  *
- * The value is defaulted to an empty array.
+ * of(successResult(null)).pipe(
+ *   arrayValueFromFinishedLoadingState()
+ * ).subscribe((items) => console.log(items)); // []
+ * ```
  *
- * @returns Observable of the value
+ * @returns an operator that emits the array value or an empty array
  */
 export declare function arrayValueFromFinishedLoadingState<L extends ListLoadingState>(): OperatorFunction<L, LoadingStateValue<L>>;