@dereekb/rxjs 13.0.7 → 13.2.0

package/src/lib/lock.d.ts

@@ -1,19 +1,40 @@
 import { type ObservableOrValue } from './rxjs/getter';
 import { type Subscription, type Observable } from 'rxjs';
 import { type Destroyable, type Maybe } from '@dereekb/util';
+/**
+ * Key used to identify a specific lock within a {@link LockSet}.
+ */
 export type LockKey = string;
 /**
- * Called when the lock set becomes unlocked, or the unlock times out.
+ * Callback invoked when a {@link LockSet} becomes unlocked or the wait times out.
+ *
+ * @param unlocked - `true` if the lock set unlocked normally, `false` if the timeout was reached
  */
 export type OnLockSetUnlockedFunction = (unlocked: boolean) => void;
+/**
+ * Function returned by {@link LockSet.addLock} that removes the associated lock when called.
+ */
 export type RemoveLockFunction = () => void;
+/**
+ * Configuration for {@link onLockSetNextUnlock} that specifies how to wait for a {@link LockSet} to unlock.
+ */
 export interface OnLockSetUnlockedConfig {
+    /** The lock set to monitor for the next unlock event. */
     readonly lockSet: LockSet;
+    /** Optional callback to invoke when the lock set unlocks or the timeout is reached. */
     readonly fn?: Maybe<OnLockSetUnlockedFunction>;
+    /** Maximum time in milliseconds to wait for unlock before timing out. Defaults to 50 seconds. */
     readonly timeout?: Maybe<number>;
+    /** Optional delay in milliseconds after the unlock is detected before invoking the callback. */
     readonly delayTime?: Maybe<number>;
 }
+/**
+ * Configuration for {@link LockSet.destroyOnNextUnlock}, excluding the lock set reference.
+ */
 export type DestroyOnNextUnlockConfig = Omit<OnLockSetUnlockedConfig, 'lockSet'>;
+/**
+ * Configuration for {@link LockSet.setLocked} that controls the locked state and optional auto-unlock duration.
+ */
 export interface SetLockedConfig {
     /**
      * Whether or not to lock the config.
@@ -26,15 +47,55 @@ export interface SetLockedConfig {
      */
     readonly duration?: number;
 }
+/**
+ * Default lock key used by {@link LockSet.lockForTime} when no custom key is provided.
+ */
 export declare const DEFAULT_LOCK_SET_TIME_LOCK_KEY = "timelock";
 /**
- * Executes the input function when the lockSet is set unlocked, or the timeout is reached.
+ * Subscribes to the next unlock event of a {@link LockSet}, invoking the callback when it becomes unlocked or the timeout expires.
+ *
+ * Useful for deferring an action until all locks are released, with a safety timeout to avoid waiting indefinitely.
+ *
+ * @param config - configuration specifying the lock set, callback, timeout, and optional delay
+ * @returns subscription that can be unsubscribed to cancel the wait
+ *
+ * @example
+ * ```ts
+ * const lockSet = new LockSet();
+ * lockSet.addLock('busy', of(true));
+ *
+ * const sub = onLockSetNextUnlock({
+ *   lockSet,
+ *   fn: (unlocked) => console.log('Unlocked:', unlocked),
+ *   timeout: 5000
+ * });
+ * ```
  */
 export declare function onLockSetNextUnlock({ lockSet, fn, timeout: inputTimeout, delayTime }: OnLockSetUnlockedConfig): Subscription;
 /**
- * Used for preventing an action until all keys are removed.
+ * Observable-based locking mechanism that prevents actions until all registered locks are released.
+ *
+ * Each lock is identified by a {@link LockKey} and backed by an `Observable<boolean>`. The lock set
+ * is considered locked when any registered observable emits `true`. Empty or completed observables
+ * are treated as unlocked, so locks do not need to be explicitly removed.
+ *
+ * Supports hierarchical locking via parent/child relationships between lock sets.
  *
- * Added Observables do not need to be strictly removed; empty observables are counted as unlocked.
+ * @example
+ * ```ts
+ * const lockSet = new LockSet();
+ *
+ * // Add a lock that is currently active
+ * const removeLock = lockSet.addLock('saving', of(true));
+ *
+ * // Check locked state
+ * lockSet.isLocked$.subscribe(locked => console.log('Locked:', locked));
+ * // Output: Locked: true
+ *
+ * // Remove the lock
+ * removeLock();
+ * // Output: Locked: false
+ * ```
  */
 export declare class LockSet implements Destroyable {
     private static LOCK_SET_CHILD_INDEX_STEPPER;
@@ -42,28 +103,110 @@ export declare class LockSet implements Destroyable {
     private readonly _onDestroy;
     private readonly _locks;
     private readonly _parentSub;
+    /**
+     * Observable of the current lock map, emitting whenever locks are added or removed.
+     */
     readonly locks$: Observable<Map<string, Observable<boolean>>>;
     /**
-     * isLocked$ is true if any observable is emitting true.
+     * Observable that emits `true` when any registered lock observable is emitting `true`.
+     * Emits `false` when all locks are released or the map is empty.
      */
     readonly isLocked$: Observable<boolean>;
+    /**
+     * Observable that emits `true` when no locks are active. Inverse of {@link isLocked$}.
+     */
     readonly isUnlocked$: Observable<boolean>;
+    /**
+     * Observable that emits when this lock set is destroyed. Useful for cleanup coordination.
+     */
     readonly onDestroy$: Observable<void>;
     private get locks();
+    /**
+     * Sets the locked state for a given key, optionally with an auto-unlock duration.
+     *
+     * When locked with a duration, the lock automatically releases after the specified time.
+     * When unlocked, the lock is removed from the set.
+     *
+     * @param key - identifier for this lock
+     * @param config - locked state or configuration object
+     * @param duration - optional auto-unlock duration in milliseconds (only used with boolean config)
+     */
     setLocked(key: LockKey, config: SetLockedConfig): void;
     setLocked(key: LockKey, config: boolean, duration?: number): void;
+    /**
+     * Locks for a specified number of seconds using the default time lock key.
+     *
+     * @param seconds - duration in seconds
+     */
     lockForSeconds(seconds: number): void;
+    /**
+     * Locks for a specified duration in milliseconds, automatically unlocking when the time elapses.
+     *
+     * @param milliseconds - lock duration
+     * @param key - optional lock key, defaults to {@link DEFAULT_LOCK_SET_TIME_LOCK_KEY}
+     */
     lockForTime(milliseconds: number, key?: LockKey): void;
+    /**
+     * Registers a lock observable under the given key. The lock is considered active when
+     * the observable emits `true`. Empty observables are treated as unlocked.
+     *
+     * @param key - identifier for this lock
+     * @param obs - observable that emits the lock state
+     * @returns function that removes this specific lock when called
+     *
+     * @example
+     * ```ts
+     * const lockSet = new LockSet();
+     * const remove = lockSet.addLock('saving', of(true));
+     *
+     * // Later, release the lock
+     * remove();
+     * ```
+     */
     addLock(key: LockKey, obs: Observable<boolean>): RemoveLockFunction;
     private _removeObsForKey;
+    /**
+     * Removes the lock registered under the given key, if it exists.
+     *
+     * @param key - identifier of the lock to remove
+     */
     removeLock(key: LockKey): void;
+    /**
+     * Registers a callback for the next time this lock set becomes unlocked.
+     *
+     * @param config - callback function or configuration object
+     * @param delayTime - optional delay in milliseconds after unlock before invoking the callback
+     * @returns subscription that can be unsubscribed to cancel the wait
+     */
     onNextUnlock(config: OnLockSetUnlockedFunction | Omit<OnLockSetUnlockedConfig, 'lockSet'>, delayTime?: number): Subscription;
+    /**
+     * Establishes a parent-child relationship where this lock set's locked state is propagated
+     * to the parent. When this lock set is locked, the parent will also reflect a locked state.
+     *
+     * @param parent - parent lock set or observable of one; pass `undefined` to detach
+     */
     setParentLockSet(parent: ObservableOrValue<Maybe<LockSet>>): void;
     /**
-     * Convenience function for watching a child lockset's locked state and propogating it upward.
+     * Registers a child lock set so its locked state propagates upward to this lock set.
+     *
+     * @param lockSet - child lock set to monitor
+     * @param key - optional lock key, auto-generated if not provided
+     * @returns function that removes the child lock relationship when called
      */
     addChildLockSet(lockSet: LockSet, key?: LockKey): RemoveLockFunction;
     get isDestroyed(): boolean;
+    /**
+     * Schedules this lock set for destruction when it next becomes unlocked.
+     *
+     * After the unlock event (or timeout), the optional callback is invoked and then
+     * {@link destroy} is called after a short delay.
+     *
+     * @param config - optional callback or configuration for the unlock wait
+     * @param delayTime - optional delay in milliseconds after unlock before invoking the callback
+     */
     destroyOnNextUnlock(config?: Maybe<DestroyOnNextUnlockConfig['fn'] | DestroyOnNextUnlockConfig>, delayTime?: number): void;
+    /**
+     * Completes all internal subjects, unsubscribes from the parent lock set, and marks this lock set as destroyed.
+     */
     destroy(): void;
 }

package/src/lib/object.d.ts

@@ -1,14 +1,38 @@
 import { type MonoTypeOperatorFunction, type Observable } from 'rxjs';
 /**
- * Equivalent to distinctUntilChanged() using areEqualPOJOValues().
+ * RxJS operator that suppresses consecutive emissions when the emitted POJO values are deeply equal.
  *
- * The compared objects should only be POJOs or compatable with the areEqualPOJOValues() function.
+ * Uses {@link areEqualPOJOValues} for comparison, so the emitted objects should be plain objects
+ * or compatible with deep value equality checks.
+ *
+ * @returns operator that filters out consecutive duplicate POJO emissions
+ *
+ * @example
+ * ```ts
+ * of({ a: 1 }, { a: 1 }, { a: 2 }).pipe(
+ *   distinctUntilObjectValuesChanged()
+ * ).subscribe(console.log);
+ * // Output: { a: 1 }, { a: 2 }
+ * ```
  */
 export declare function distinctUntilObjectValuesChanged<T>(): MonoTypeOperatorFunction<T>;
 /**
- * Observable filter that filters the input if the object is unchanged/equal to the input.
+ * RxJS operator that filters out emissions that are deeply equal to a reference value.
+ *
+ * Accepts either a static reference value or an observable of reference values. When given an observable,
+ * each emission is compared against the latest reference value. Uses {@link areEqualPOJOValues} for comparison.
+ *
+ * @param input - static reference value or observable of reference values to compare against
+ * @returns operator that only passes through values that differ from the reference
  *
- * The compared objects should only be POJOs or compatable with the areEqualPOJOValues() function.
+ * @example
+ * ```ts
+ * const ref = { status: 'active' };
+ * of({ status: 'active' }, { status: 'inactive' }).pipe(
+ *   filterIfObjectValuesUnchanged(ref)
+ * ).subscribe(console.log);
+ * // Output: { status: 'inactive' }
+ * ```
  */
 export declare function filterIfObjectValuesUnchanged<F>(inputFilter: F): MonoTypeOperatorFunction<F>;
 export declare function filterIfObjectValuesUnchanged<F>(obs: Observable<F>): MonoTypeOperatorFunction<F>;

package/src/lib/rxjs/array.d.ts

@@ -1,14 +1,34 @@
 import { type MonoTypeOperatorFunction, type Observable, type OperatorFunction, type ObservableInput } from 'rxjs';
 import { type Maybe, type ArrayOrValue, type MapFunction } from '@dereekb/util';
+/**
+ * `distinctUntilChanged` variant that only emits when the array length changes.
+ *
+ * Optionally accepts an accessor function to extract the array from a complex value.
+ *
+ * @param getArray - optional function to extract the array from the emitted value
+ * @returns an operator that filters emissions with unchanged array lengths
+ */
 export declare function distinctUntilArrayLengthChanges<A>(getArray: (value: A) => unknown[]): MonoTypeOperatorFunction<A>;
 export declare function distinctUntilArrayLengthChanges<T>(): MonoTypeOperatorFunction<T[]>;
 export interface ScanIntoArrayConfig {
     readonly immutable?: boolean;
 }
 /**
- * Scans values from the observable into an array.
+ * Accumulates emitted values into a growing array using `scan`.
+ *
+ * Each emission adds to the accumulated array. When `immutable` is true (default),
+ * a new array is created on each emission via `concat`. When false, the array is mutated in place.
  *
- * Can configure whether or not the accumulator array is immutable or not.
+ * @example
+ * ```ts
+ * of(1, 2, 3).pipe(
+ *   scanIntoArray()
+ * ).subscribe(console.log);
+ * // [1], [1, 2], [1, 2, 3]
+ * ```
+ *
+ * @param config - optional immutability setting
+ * @returns an operator that accumulates values into an array
  */
 export declare function scanIntoArray<T>(config?: ScanIntoArrayConfig): OperatorFunction<Maybe<ArrayOrValue<T>>, T[]>;
 export declare function scanIntoArray<T>(config?: ScanIntoArrayConfig): OperatorFunction<Maybe<T>, T[]>;
@@ -29,22 +49,21 @@ export interface ScanBuildArrayConfig<T> {
 }
 export type ScanBuildArrayConfigFn<S, T> = (seedState: S) => ScanBuildArrayConfig<T>;
 /**
- * Used to lazy build an array from two observables.
- *
- * The piped observable is for retrieving the seed value, and the accumulatorObs observable is used for
- * retrieving values going forward.
+ * Lazily builds an array from a seed observable and an accumulator observable.
  *
- * This is useful in cases where values are very large.
+ * The piped observable provides the seed state, while `accumulatorObs` provides values that
+ * are incrementally appended. Useful when loading large datasets where the initial page and
+ * subsequent pages come from different sources.
  *
- * @param param0
- * @returns
+ * @param init - function that receives the seed state and returns the accumulator config
+ * @returns an operator that emits the growing array
  */
 export declare function scanBuildArray<S, T>(init: ScanBuildArrayConfigFn<S, T>): OperatorFunction<S, T[]>;
 /**
- * Convenience function that calls forEachWithArray() and returns the original array.
+ * RxJS operator that executes a side-effect on each element of the emitted array, then passes the array through.
  *
- * @param forEach
- * @returns
+ * @param forEach - callback to run for each element, or null/undefined to pass through unchanged
+ * @returns an operator that taps each element in emitted arrays
  */
 export declare function mapForEach<T>(forEach: Maybe<(value: T) => void>): MonoTypeOperatorFunction<T[]>;
 export interface MapEachAsyncConfig {
@@ -54,6 +73,13 @@ export interface MapEachAsyncConfig {
     readonly onlyFirst?: boolean;
 }
 /**
- * Operator function that maps each value in the array independently using Observables, then combines the all results.
+ * RxJS operator that maps each element in an emitted array through an async observable function,
+ * then combines all results using `combineLatest`.
+ *
+ * Emits `[]` for empty arrays. When `onlyFirst` is true, takes only the first combined emission.
+ *
+ * @param mapFunction - function that maps each item to an ObservableInput
+ * @param config - optional config (e.g., `onlyFirst`)
+ * @returns an operator that async-maps each array element
  */
 export declare function mapEachAsync<I, O>(mapFunction: MapFunction<I, ObservableInput<O>>, config?: MapEachAsyncConfig): OperatorFunction<I[], O[]>;

package/src/lib/rxjs/boolean.d.ts

@@ -1,17 +1,21 @@
 import { type OperatorFunction, type MonoTypeOperatorFunction } from 'rxjs';
 /**
- * Returns the pipe if usePipe is true, otherwise returns the identity.
+ * Conditionally applies an operator. Returns the given pipe when `usePipe` is true, otherwise returns identity (pass-through).
+ *
+ * @param usePipe - whether to apply the pipe
+ * @param pipe - the operator to conditionally apply
+ * @returns the pipe or identity operator
  */
 export declare function pipeIf<A>(usePipe: boolean, pipe: OperatorFunction<A, A>): OperatorFunction<A, A>;
 /**
- * Maps the opposite value of the input boolean.
+ * RxJS operator that negates each emitted boolean value.
  */
 export declare function isNot(): MonoTypeOperatorFunction<boolean>;
 /**
- * Emits a value when moving from a true value to a false value.
+ * RxJS operator that only emits when a boolean stream transitions from `true` to `false`.
  */
 export declare function onTrueToFalse(): MonoTypeOperatorFunction<boolean>;
 /**
- * Emits a value when moving from a false value to a true value.
+ * RxJS operator that only emits when a boolean stream transitions from `false` to `true`.
  */
 export declare function onFalseToTrue(): MonoTypeOperatorFunction<boolean>;

package/src/lib/rxjs/decision.d.ts

@@ -5,17 +5,23 @@ import { type MonoTypeOperatorFunction, type Observable } from 'rxjs';
  */
 export type ObservableDecisionFunction<T> = (value: T) => Observable<boolean>;
 /**
- * Used to invert an ObservableDecisionFunction's result.
+ * Wraps an {@link ObservableDecisionFunction} to negate its boolean result.
  *
- * @param filterFn
- * @param invert whether or not to apply the inversion.
- * @returns
+ * When `invert` is false, returns the original function unchanged.
+ *
+ * @param decisionFn - the decision function to invert
+ * @param invert - whether to apply the inversion (defaults to true)
+ * @returns the inverted (or original) decision function
  */
 export declare function invertObservableDecision<F extends ObservableDecisionFunction<any>>(decisionFn: F, invert?: boolean): F;
 /**
- * Operator function that uses SwitchMap and filters each of the input values using an ObservableDecisionFunction, and returns them as an array.
+ * RxJS operator that filters an emitted array by evaluating each item through an async {@link ObservableDecisionFunction}.
+ *
+ * Items where the decision returns true are kept; others are removed. Results are throttled
+ * to prevent excessive re-emissions.
  *
- * @param observableDecisionFunction
- * @returns
+ * @param observableDecisionFunction - async predicate to evaluate each item
+ * @param throttle - throttle duration in ms (defaults to 20)
+ * @returns an operator that async-filters array elements
  */
 export declare function filterItemsWithObservableDecision<T>(observableDecisionFunction: ObservableDecisionFunction<T>, throttle?: Milliseconds): MonoTypeOperatorFunction<T[]>;

package/src/lib/rxjs/delta.d.ts

@@ -25,8 +25,20 @@ export interface OnMatchDeltaConfig<T> {
     requireConsecutive?: boolean;
 }
 /**
- * Emits a value when going from one matching value to a target value.
+ * RxJS operator that emits only when the stream transitions from a `from` value to a `to` value.
  *
- * The first value must be determined first before the second is raised.
+ * The `from` value must be seen first; only then is the `to` value emitted. When `requireConsecutive`
+ * is true, the two values must be adjacent emissions.
+ *
+ * @example
+ * ```ts
+ * // Emit when transitioning from true to false
+ * source$.pipe(
+ *   onMatchDelta({ from: true, to: false, requireConsecutive: true })
+ * ).subscribe((val) => console.log('Transitioned to false'));
+ * ```
+ *
+ * @param config - from/to values, optional comparator, and consecutive requirement
+ * @returns an operator that emits on value transitions
  */
 export declare function onMatchDelta<T>(config: OnMatchDeltaConfig<T>): MonoTypeOperatorFunction<T>;

package/src/lib/rxjs/expires.d.ts

@@ -1,29 +1,41 @@
 import { type Milliseconds, type DateOrUnixDateTimeMillisecondsNumber, type Expires } from '@dereekb/util';
 import { type MonoTypeOperatorFunction, type Observable, type OperatorFunction } from 'rxjs';
 /**
- * Creates a new Expires object at the current time on emission that will expire in the set amount of time.
+ * RxJS operator that maps each emission to a new {@link Expires} object with an expiration
+ * time relative to the current moment.
  *
- * @param expiresIn
- * @returns
+ * @param expiresIn - duration in milliseconds until expiration
+ * @returns an operator that maps values to Expires objects
  */
 export declare function toExpiration<T>(expiresIn: number): OperatorFunction<T, Expires>;
 /**
- * Filters further emissions once the input is expired.
+ * RxJS operator that filters out emissions whose {@link Expires} value has already expired.
  */
 export declare function skipExpired<T extends Expires>(): MonoTypeOperatorFunction<T>;
 /**
- * Skips the input date or timenumber until expiration occurs.
+ * RxJS operator that skips emissions until the elapsed time since the emitted date/timestamp has exceeded `expiresIn`.
+ *
+ * @param expiresIn - duration in milliseconds
  */
 export declare function skipUntilExpiration(expiresIn?: number): MonoTypeOperatorFunction<DateOrUnixDateTimeMillisecondsNumber>;
 /**
- * Skips the input date or timenumber after expiration occurs.
+ * RxJS operator that skips emissions after the elapsed time since the emitted date/timestamp has exceeded `expiresIn`.
+ *
+ * @param expiresIn - duration in milliseconds
  */
 export declare function skipAfterExpiration(expiresIn?: number): MonoTypeOperatorFunction<DateOrUnixDateTimeMillisecondsNumber>;
 /**
- * Skips emissions until time since the last emission from the watch observable has elapsed.
+ * RxJS operator that only takes emissions from the source within a time window after each emission from a watch observable.
+ *
+ * @param watch - observable whose emissions reset the time window
+ * @param takeFor - duration in milliseconds of each time window
  */
 export declare function skipUntilTimeElapsedAfterLastEmission<T>(watch: Observable<unknown>, takeFor: Milliseconds): MonoTypeOperatorFunction<T>;
 /**
- * Takes emissions until time since the last emission from the watch observable has elapsed.
+ * RxJS operator that skips emissions from the source for a duration after each emission from a watch observable,
+ * then passes values through once the time has elapsed.
+ *
+ * @param watch - observable whose emissions reset the skip window
+ * @param skipFor - duration in milliseconds to skip after each watch emission
  */
 export declare function takeAfterTimeElapsedSinceLastEmission<T>(watch: Observable<unknown>, skipFor: Milliseconds): MonoTypeOperatorFunction<T>;

package/src/lib/rxjs/factory.d.ts

@@ -23,9 +23,22 @@ export interface FactoryTimerConfig<T> {
 }
 export declare const DEFAULT_FACTORY_TIMER_INTERVAL = 1000;
 /**
- * Creates an observable that uses timer internally and maps values from the factory result.
+ * Creates an observable that emits values produced by a factory function on a timer interval.
  *
- * @param config
- * @returns
+ * Wraps `timer()` internally and maps each tick index through the factory. Optionally limits
+ * the total number of emissions.
+ *
+ * @example
+ * ```ts
+ * const countdown$ = factoryTimer({
+ *   factory: (i) => 10 - i,
+ *   interval: 1000,
+ *   limit: 11
+ * });
+ * // emits 10, 9, 8, ... 0
+ * ```
+ *
+ * @param config - timer configuration including factory, interval, wait, and limit
+ * @returns an observable of factory-produced values
  */
 export declare function factoryTimer<T>(config: FactoryTimerConfig<T>): Observable<T>;

package/src/lib/rxjs/getter.d.ts

@@ -6,20 +6,21 @@ import { type Observable, type OperatorFunction, type Subscription, type Observe
 export type ObservableOrValue<T> = T | Observable<T>;
 export type MaybeObservableOrValue<T> = Maybe<ObservableOrValue<Maybe<T>>>;
 /**
- * Wraps the input value as an observable, if it is not an observable.
+ * Wraps a value as an observable using `of()`, or returns it directly if it is already an observable.
  */
 export declare function asObservable<T>(valueOrObs: ObservableOrValue<T>): Observable<T>;
 export declare function asObservable<T>(valueOrObs: Maybe<ObservableOrValue<T>>): Observable<Maybe<T>>;
 /**
- * Switch map for an ObservableGetter that pipes through the value.
+ * RxJS operator that flattens an emitted {@link ObservableOrValue} into its unwrapped value via `switchMap`.
  *
- * @returns OperatorFunction<ObservableOrValue<T>, T>
+ * @returns an operator that unwraps ObservableOrValue emissions
  */
 export declare function valueFromObservableOrValue<T>(): OperatorFunction<ObservableOrValue<T>, T>;
 /**
- * Switch map for an ObservableGetter that pipes through the Maybe value.
+ * RxJS operator that flattens an emitted Maybe<{@link ObservableOrValue}> into its unwrapped value,
+ * emitting `undefined` when the input is nullish.
  *
- * @returns OperatorFunction<Maybe<ObservableOrValue<T>>, Maybe<T>>
+ * @returns an operator that unwraps Maybe<ObservableOrValue> emissions
  */
 export declare function maybeValueFromObservableOrValue<T>(): OperatorFunction<MaybeObservableOrValue<T>, Maybe<T>>;
 /**
@@ -29,22 +30,35 @@ export type ObservableOrValueGetter<T> = GetterOrValue<ObservableOrValue<T>>;
 export type ObservableOrValueFactoryWithInput<T extends GetterDistinctValue, A> = GetterOrValueWithInput<ObservableOrValue<T>, A>;
 export type ObservableFactoryWithRequiredInput<T extends GetterDistinctValue, A> = FactoryWithRequiredInput<ObservableOrValue<T>, A>;
 export type MaybeObservableOrValueGetter<T> = Maybe<ObservableOrValueGetter<Maybe<T>>>;
+/**
+ * Resolves an {@link ObservableOrValueGetter} into an Observable by first evaluating the getter,
+ * then wrapping the result with {@link asObservable} if needed.
+ *
+ * @param input - a getter or value that produces an observable or value
+ * @param args - optional arguments passed to the getter
+ * @returns an observable of the resolved value
+ */
 export declare function asObservableFromGetter<T>(input: ObservableOrValueGetter<T>): Observable<T>;
 export declare function asObservableFromGetter<T>(this: unknown, input: ObservableOrValueGetter<T>): Observable<T>;
 export declare function asObservableFromGetter<T extends GetterDistinctValue, A>(this: unknown, input: ObservableFactoryWithRequiredInput<T, A>, args: A): Observable<T>;
 export declare function asObservableFromGetter<T extends GetterDistinctValue, A>(this: unknown, input: ObservableOrValueFactoryWithInput<T, A>, args?: A): Observable<T>;
 /**
- * Switch map for an ObservableOrValueGetter that pipes through the value.
+ * RxJS operator that flattens an emitted {@link ObservableOrValueGetter} into its resolved value via `switchMap`.
  *
- * @returns
+ * @returns an operator that unwraps getter emissions
  */
 export declare function valueFromObservableOrValueGetter<T>(): OperatorFunction<ObservableOrValueGetter<T>, T>;
+/**
+ * RxJS operator that flattens an emitted Maybe<{@link ObservableOrValueGetter}> into its resolved value,
+ * emitting `undefined` when the input is nullish.
+ */
 export declare function maybeValueFromObservableOrValueGetter<T>(): OperatorFunction<MaybeObservableOrValueGetter<T>, Maybe<T>>;
 /**
- * Convenience function for subscribing to a ObservableOrValue<T> value as an observable.
+ * Subscribes to an {@link ObservableOrValue} and calls the observer/next function with each emitted value.
  *
- * @param input
- * @param next
+ * @param input - the observable or value to subscribe to
+ * @param observer - callback or partial observer
+ * @returns the subscription
  */
 export declare function useAsObservable<T>(input: ObservableOrValue<T>, next: (value: T) => void): Subscription;
 export declare function useAsObservable<T>(input: ObservableOrValue<T>, observer: Partial<Observer<T>>): Subscription;

package/src/lib/rxjs/key.d.ts

@@ -1,15 +1,17 @@
 import { type PrimativeKey, type ReadKeyFunction, type ReadMultipleKeysFunction } from '@dereekb/util';
 import { type MonoTypeOperatorFunction } from 'rxjs';
 /**
- * distinctUntilChanged() that reads the unique identifiers from the input values and compares them for uniqueness.
+ * `distinctUntilChanged` variant for arrays that only emits when the set of keys extracted from
+ * the array elements changes.
  *
- * @param readkey
+ * @param readKey - function to extract one or more keys from each element
+ * @returns an operator that filters out arrays with unchanged key sets
  */
 export declare function distinctUntilKeysChange<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>): MonoTypeOperatorFunction<T[]>;
 /**
- * Convenience function for distinctUntilChange() that compares the values using a readKey function.
+ * `distinctUntilChanged` variant for single objects that only emits when the extracted key changes.
  *
- * @param readKey
- * @returns
+ * @param readKey - function to extract a key from the emitted object
+ * @returns an operator that filters out emissions with unchanged keys
  */
 export declare function distinctUntilObjectKeyChange<T>(readKey: ReadKeyFunction<T>): MonoTypeOperatorFunction<T>;

package/src/lib/rxjs/lifecycle.d.ts

@@ -1,18 +1,21 @@
 import { type Destroyable, type PromiseOrValue } from '@dereekb/util';
 import { type MonoTypeOperatorFunction } from 'rxjs';
 /**
- * Cleans up the instance when a new value is pushed.
+ * RxJS operator that calls a destroy function on the previous value whenever a new value is emitted.
  *
- * Can be configured to wait until the previous value's destroy promise has resolved.
+ * Ensures proper cleanup of resources when switching between instances. When `wait` is true,
+ * delays emitting the new value until the previous destruction completes.
+ * On unsubscription, the last emitted instance is also destroyed.
  *
- * @param destroy
- * @param wait
- * @returns
+ * @param destroy - function to clean up each replaced instance
+ * @param wait - whether to wait for the previous destroy to complete before emitting
+ * @returns an operator that manages instance lifecycle
  */
 export declare function cleanup<T>(destroy: (instance: T) => PromiseOrValue<void>, wait?: boolean): MonoTypeOperatorFunction<T>;
 /**
- * Convenience function for cleanup() on a Destroyable type.
+ * Convenience wrapper for {@link cleanup} that calls `destroy()` on each replaced {@link Destroyable} instance.
  *
- * @returns
+ * @param wait - whether to wait for the previous destroy to complete before emitting
+ * @returns an operator that manages Destroyable lifecycle
  */
 export declare function cleanupDestroyable<T extends Destroyable>(wait?: boolean): MonoTypeOperatorFunction<T>;

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

@@ -1,7 +1,15 @@
 import { type OperatorFunction } from 'rxjs';
 /**
- * Operator that returns true until the first item is emitted. Then returns false.
+ * RxJS operator that emits `true` immediately (loading), then `false` after the source emits its first value.
  *
- * @returns
+ * Only considers the first emission from the source. The result is shared via `shareReplay(1)`.
+ *
+ * @example
+ * ```ts
+ * const loading$ = dataFetch$.pipe(isLoading());
+ * // emits true initially, then false once dataFetch$ emits
+ * ```
+ *
+ * @returns an operator that tracks whether the first value has been emitted
  */
 export declare function isLoading<T>(): OperatorFunction<T, boolean>;