@dereekb/rxjs 13.0.7 → 13.2.0

package/src/lib/iterator/iteration.next.d.ts

@@ -2,31 +2,34 @@ import { type Observable } from 'rxjs';
 import { type ItemIteration, type PageItemIteration } from './iteration';
 import { type Maybe, type GetterOrValue, type PageNumber } from '@dereekb/util';
 /**
- * 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
  */
 export declare function iterationHasNextAndCanLoadMore<V>(iteration: ItemIteration<V>): Observable<boolean>;
 /**
- * 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
  */
 export declare function iteratorNextPageUntilMaxPageLoadLimit(iterator: PageItemIteration, defaultLimit?: Maybe<number>): Promise<number>;
 /**
- * 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
  */
 export declare function iteratorNextPageUntilPage(iteration: PageItemIteration, page: GetterOrValue<number>): Promise<PageNumber>;

package/src/lib/iterator/iterator.page.d.ts

@@ -2,16 +2,20 @@ import { type PageLoadingState } from '../loading';
 import { type Destroyable, type Filter, type Maybe, type PageNumber, type Page } from '@dereekb/util';
 import { type Observable } from 'rxjs';
 import { type ItemIteratorNextRequest, type PageItemIteration } from './iteration';
+/**
+ * Configuration for limiting the number of pages that can be loaded by a page iterator.
+ */
 export interface ItemPageLimit {
     /**
-     * Maximum number of pages to load.
-     *
-     * This value should be defined in most cases.
-     *
-     * If not defined, the will be no ending iteration.
+     * Maximum number of pages to load. Should be defined in most cases to prevent
+     * unbounded iteration. If not defined, there is no limit.
      */
     readonly maxPageLoadLimit?: Maybe<number>;
 }
+/**
+ * Request object passed to the {@link ItemPageIteratorDelegate.loadItemsForPage} method,
+ * providing all context needed to load a specific page.
+ */
 export interface ItemPageIteratorRequest<V, F, C extends ItemPageIterationConfig<F> = ItemPageIterationConfig<F>> extends Page {
     /**
      * The base iterator config.
@@ -38,6 +42,10 @@ export interface ItemPageIteratorRequest<V, F, C extends ItemPageIterationConfig
      */
     readonly lastState$: Observable<Maybe<PageLoadingState<ItemPageIteratorResult<V>>>>;
 }
+/**
+ * Result returned by the delegate for a single page load, containing the loaded values
+ * and pagination status.
+ */
 export interface ItemPageIteratorResult<V> {
     /**
      * Error result.
@@ -56,6 +64,10 @@ export interface ItemPageIteratorResult<V> {
      */
     readonly end?: boolean;
 }
+/**
+ * Delegate responsible for loading items for a given page request.
+ * Implementations define the data-fetching logic for each page.
+ */
 export interface ItemPageIteratorDelegate<V, F, C extends ItemPageIterationConfig<F> = ItemPageIterationConfig<F>> {
     /**
      * Returns an observable of items given the input request.
@@ -64,14 +76,30 @@ export interface ItemPageIteratorDelegate<V, F, C extends ItemPageIterationConfi
      */
     loadItemsForPage(request: ItemPageIteratorRequest<V, F, C>): Observable<ItemPageIteratorResult<V>>;
 }
+/**
+ * Combined configuration for page iteration, including filter criteria and page limits.
+ */
 export interface ItemPageIterationConfig<F = unknown> extends Filter<F>, ItemPageLimit {
 }
 /**
- * Default number of pages that can be loaded.
+ * Default maximum number of pages that can be loaded by an {@link ItemPageIterator}.
  */
 export declare const 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
+ * ```
  */
 export declare class ItemPageIterator<V, F, C extends ItemPageIterationConfig<F> = ItemPageIterationConfig<F>> {
     private readonly _delegate;
@@ -83,13 +111,17 @@ export declare class ItemPageIterator<V, F, C extends ItemPageIterationConfig<F>
     getMaxPageLoadLimit(): Maybe<number>;
     setMaxPageLoadLimit(maxPageLoadLimit: Maybe<number>): void;
     /**
-     * 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
      */
     instance(config: C): ItemPageIterationInstance<V, F, C>;
 }
+/**
+ * Internal state snapshot of an {@link ItemPageIterationInstance}, tracking the current
+ * and historical loading states across page loads.
+ */
 export interface ItemPageIterationInstanceState<V> {
     /**
      * Used for tracking the start/end of a specific next call.
@@ -105,7 +137,11 @@ export interface ItemPageIterationInstanceState<V> {
     readonly lastSuccessful: Maybe<PageLoadingState<ItemPageIteratorResult<V>>>;
 }
 /**
- * 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.
  */
 export declare class ItemPageIterationInstance<V, F, C extends ItemPageIterationConfig<F> = ItemPageIterationConfig<F>> implements PageItemIteration<V, PageLoadingState<V>>, Destroyable {
     private readonly _iterator;
@@ -191,12 +227,14 @@ export declare class ItemPageIterationInstance<V, F, C extends ItemPageIteration
     destroy(): void;
 }
 /**
- * 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
  */
 export declare function isItemPageIteratorResultEndResult<V>(result: ItemPageIteratorResult<V>): boolean;

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

@@ -2,6 +2,22 @@ import { type OperatorFunction } from 'rxjs';
 import { type LoadingContext, type LoadingContextEvent } from './loading.context';
 import { type Maybe } from '@dereekb/util';
 /**
- * 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
  */
 export declare function switchMapMaybeLoadingContextStream(): OperatorFunction<Maybe<LoadingContext>, Maybe<LoadingContextEvent>>;

package/src/lib/loading/loading.context.simple.d.ts

@@ -2,16 +2,53 @@ import { type Destroyable, type ReadableError } from '@dereekb/util';
 import { type Observable } from 'rxjs';
 import { type LoadingContext, type LoadingContextEvent } from './loading.context';
 /**
- * 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
+ * ```
  */
 export declare class SimpleLoadingContext implements LoadingContext, Destroyable {
     private readonly _subject;
     readonly stream$: Observable<LoadingContextEvent>;
     constructor(loading?: boolean);
+    /**
+     * Completes the internal subject, ending the stream.
+     */
     destroy(): void;
+    /**
+     * Whether the current state has a non-null error.
+     */
     hasError(): boolean;
+    /**
+     * Clears the current error while preserving other state.
+     */
     clearError(): void;
+    /**
+     * Convenience method to mark loading as complete (sets loading to false).
+     */
     setSuccess(): void;
+    /**
+     * Sets the loading flag and clears any existing error.
+     *
+     * @param loading - whether loading is in progress (defaults to true)
+     */
     setLoading(loading?: boolean): void;
+    /**
+     * 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)
+     */
     setError(error: ReadableError, loading?: boolean): void;
 }

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

@@ -74,15 +74,43 @@ export interface LoadingStateContextConfig<T = unknown, S extends LoadingState<T
     readonly loadingEventForLoadingPair?: Maybe<(state: S, config: LoadingEventForLoadingPairConfigInput) => E>;
 }
 export type LoadingEventForLoadingPairConfigInput = Pick<LoadingStateContextConfig, 'showLoadingOnUndefinedValue'>;
+/**
+ * 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.
+ */
 export declare const DEFAULT_LOADING_EVENT_FOR_LOADING_PAIR_FUNCTION: <T = unknown, S extends LoadingState<T> = LoadingState<T>, E extends LoadingStateContextEvent = LoadingContextEvent & S>(state: S, input: LoadingEventForLoadingPairConfigInput) => LoadingStateContextEvent<T>;
 /**
  * Input for loadingStateContext()
  */
 export type LoadingStateContextInput<T = unknown, S extends LoadingState<T> = LoadingState<T>, E extends LoadingStateContextEvent = LoadingContextEvent & S> = LoadingStateContextConfig<T, S, E> | LoadingStateContextConfig<T, S, E>['obs'];
 /**
- * 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
  */
 export declare function loadingStateContext<T = unknown, S extends LoadingState<T> = LoadingState<T>, E extends LoadingStateContextEvent = LoadingContextEvent & S>(input?: LoadingStateContextInput<T, S, E>): MutableLoadingStateContext<T, S, E>;

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

@@ -49,9 +49,31 @@ export type ListLoadingStateContextConfig<L, S extends ListLoadingState<L> = Lis
  */
 export type ListLoadingStateContextInput<L, S extends ListLoadingState<L> = ListLoadingState<L>> = Omit<LoadingStateContextInput<L[], S>, 'loadingEventForLoadingPair'> | ListLoadingStateContextConfig<L, S>;
 /**
- * Creates a ListLoadingStateContext.
+ * Creates a {@link MutableListLoadingStateContext} that wraps a {@link ListLoadingState} observable
+ * and provides list-specific reactive accessors like `isEmpty$` and `list$`.
  *
- * @param input Optional configuration for the ListLoadingStateContext.
- * @returns A ListLoadingStateContext.
+ * 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'])));
+ *
+ * // 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
  */
 export declare function listLoadingStateContext<L, S extends ListLoadingState<L> = ListLoadingState<L>>(input?: ListLoadingStateContextInput<L, S>): MutableListLoadingStateContext<L, S>;

package/src/lib/loading/loading.context.value.d.ts

@@ -1,19 +1,59 @@
 import { SimpleLoadingContext } from './loading.context.simple';
+/**
+ * Function that returns an array of values to check for completion.
+ * If any element is `undefined`, the check considers loading to still be in progress.
+ */
 export type LoadingContextCheckCompletionFunction = () => unknown[];
+/**
+ * Configuration for {@link ValuesLoadingContext}.
+ */
 export interface LoadingContextConfiguration {
+    /**
+     * Initial loading state. Defaults to `true`.
+     */
     loading?: boolean;
+    /**
+     * Function that returns values to check for loading completion.
+     */
     checkDone?: LoadingContextCheckCompletionFunction;
 }
 /**
- * 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();
+ * ```
  */
 export declare class ValuesLoadingContext extends SimpleLoadingContext {
     private _checkDone?;
     constructor({ checkDone, loading }?: LoadingContextConfiguration);
     /**
-     * Check the array for objects to see if loading is completed.
+     * Re-evaluates the check function to determine whether all values are loaded.
+     *
+     * Sets loading to `false` when every element in the check array is defined.
+     * Does nothing if the context currently has an error.
      *
-     * The loading state is always modified unless there is an error or no check function.
+     * @throws {Error} When no check function was provided in the constructor configuration.
      */
     check(): void;
 }