@dereekb/rxjs 13.0.7 → 13.2.0

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

@@ -19,9 +19,10 @@ export type IsEqualFunction<T = unknown> = IsCheckFunction<T>;
  */
 export type IsModifiedFunction<T = unknown> = IsCheckFunction<T>;
 /**
- * Creates an IsModifiedFunction from an IsEqualFunction, or from IsModifiedFunctionInput.
+ * Creates an {@link IsModifiedFunction} by inverting the result of an {@link IsEqualFunction}.
  *
- * @param isEqualFunction
+ * @param isEqualFunction - equality check function to invert
+ * @returns a function that returns true when the value has been modified
  */
 export declare function makeIsModifiedFunction<T>(isEqualFunction: IsEqualFunction<T>): IsModifiedFunction<T>;
 /**
@@ -44,18 +45,49 @@ export interface MakeIsModifiedFunctionObservableConfig<T = unknown> {
     readonly defaultFunction?: Maybe<IsModifiedFunction<T>>;
 }
 /**
- * Creates an Observable<IsModifiedFunction> from the input config.
+ * Creates an observable that emits an {@link IsModifiedFunction} derived from the config.
  *
- * @param config MakeIsModifiedFunctionObservableConfig.
- * @returns Observable<IsModifiedFunction<T>>
+ * Prefers `isModified` over `isEqual` (which is inverted), falling back to `defaultFunction`
+ * or a function that always returns true.
+ *
+ * @param config - configuration with isModified, isEqual, and/or defaultFunction
+ * @returns an observable of the resolved IsModifiedFunction
  */
 export declare function makeIsModifiedFunctionObservable<T>(config: MakeIsModifiedFunctionObservableConfig<T>): Observable<IsModifiedFunction<T>>;
+/**
+ * Creates a function that returns the value if the check function returns true, otherwise undefined.
+ *
+ * @param isCheckFunction - optional check function
+ * @param defaultValueOnMaybe - default result for null/undefined values
+ */
 export declare function makeReturnIfIsFunction<T>(isCheckFunction: Maybe<IsModifiedFunction<T>>, defaultValueOnMaybe?: boolean): (value: Maybe<T>) => Observable<Maybe<T>>;
+/**
+ * Returns the value wrapped in an observable if the check function passes, otherwise emits undefined.
+ *
+ * @param isCheckFunction - optional check function
+ * @param value - the value to check
+ * @param defaultValueOnMaybe - default result for null/undefined values
+ */
 export declare function returnIfIs<T>(isCheckFunction: Maybe<IsModifiedFunction<T>>, value: Maybe<T>, defaultValueOnMaybe?: boolean): Observable<Maybe<T>>;
+/**
+ * Creates a function that checks a value against the check function and returns an observable boolean.
+ *
+ * @param isCheckFunction - optional check function
+ * @param defaultValueOnMaybe - default result for null/undefined values
+ */
 export declare function makeCheckIsFunction<T>(isCheckFunction: Maybe<IsModifiedFunction<T>>, defaultValueOnMaybe?: boolean): (value: Maybe<T>) => Observable<boolean>;
+/**
+ * Evaluates a value against an optional check function, returning an observable boolean.
+ *
+ * Returns `of(true)` when no check function is provided.
+ *
+ * @param isCheckFunction - optional check function
+ * @param value - the value to check
+ * @param defaultValueOnMaybe - default result for null/undefined values (defaults to false)
+ */
 export declare function checkIs<T>(isCheckFunction: Maybe<IsModifiedFunction<T>>, value: Maybe<T>, defaultValueOnMaybe?: boolean): Observable<boolean>;
 /**
- * Observable filter that filters maybe value that are defined.
+ * RxJS operator that filters out null and undefined values, only passing through defined values.
  */
 export declare function filterMaybe<T>(): OperatorFunction<Maybe<T>, T>;
 /**
@@ -63,26 +95,28 @@ export declare function filterMaybe<T>(): OperatorFunction<Maybe<T>, T>;
  */
 export declare const filterMaybeStrict: <T>() => OperatorFunction<Maybe<T>, MaybeSoStrict<T>>;
 /**
- * Observable filter that filters out MaybeNot values from the input array of maybe values
+ * RxJS operator that filters out null/undefined elements from an emitted array, keeping only defined values.
  */
 export declare function filterMaybeArray<T>(): OperatorFunction<Maybe<T>[], T[]>;
 /**
- * Skips all initial maybe values, and then returns all values after the first non-null/undefined value is returned.
+ * RxJS operator that skips all leading null/undefined emissions, then passes all subsequent values through.
  */
 export declare function skipAllInitialMaybe<T>(): MonoTypeOperatorFunction<T>;
 /**
- * Skips only the first maybe value, then returns all values afterwards.
+ * RxJS operator that skips only the first emission if it is null/undefined, then passes all subsequent values.
  */
 export declare function skipInitialMaybe<T>(): MonoTypeOperatorFunction<T>;
 /**
- * Skips up to the given number of maybe values, and then returns all values after the first non-null/undefined value is returned.
+ * RxJS operator that skips up to `maxToSkip` null/undefined emissions, then passes all subsequent values.
+ *
+ * @param maxToSkip - maximum number of null/undefined emissions to skip
  */
 export declare function skipMaybes<T>(maxToSkip: number): MonoTypeOperatorFunction<T>;
 /**
- * Provides a switchMap that will emit the observable if the observable is defined, otherwise will return the default value.
+ * RxJS operator that switches to the emitted observable if defined, or emits the default value if null/undefined.
  *
- * @param defaultValue
- * @returns
+ * @param defaultValue - fallback value when the observable is nullish (defaults to undefined)
+ * @returns an operator that handles optional observables
  */
 export declare function switchMapMaybeDefault<T = unknown>(defaultValue?: Maybe<T>): OperatorFunction<Maybe<Observable<Maybe<T>>>, Maybe<T>>;
 /**
@@ -90,10 +124,12 @@ export declare function switchMapMaybeDefault<T = unknown>(defaultValue?: Maybe<
  */
 export type SwitchMapToDefaultFilterFunction<T> = ObservableDecisionFunction<Maybe<T>>;
 /**
- * Provides a switchMap that will emit the observable value if the observable is defined, otherwise will use the input default.
+ * RxJS operator that emits the source value if defined, or switches to the default observable/getter when
+ * the value is nullish (or when the custom `useDefault` decision function returns true).
  *
- * @param defaultValue
- * @returns
+ * @param defaultObs - default value/observable/getter to use as fallback
+ * @param useDefault - optional decision function to determine when to use the default
+ * @returns an operator that provides a default for nullish values
  */
 export declare function switchMapToDefault<T = unknown>(defaultObs: MaybeObservableOrValueGetter<T>): OperatorFunction<Maybe<T>, Maybe<T>>;
 export declare function switchMapToDefault<T = unknown>(defaultObs: ObservableOrValueGetter<T>): OperatorFunction<Maybe<T>, T>;
@@ -102,61 +138,59 @@ export interface SwitchMapObjectConfig<T> {
     defaultGetter?: GetterOrValue<Maybe<T>>;
 }
 /**
- * Provides a switchMap that retrieves and emits the value from the observable, unless the value is null/undefined/true in which case it emits the default value. If the value is false, null is emitted.
+ * RxJS operator that resolves an observable/getter config input into a value, applying defaults
+ * for `null`/`undefined`/`true` inputs and emitting `null` for `false`.
  */
 export declare function switchMapObject<T extends object>(config: SwitchMapObjectConfig<T>): OperatorFunction<Maybe<ObservableOrValueGetter<Maybe<T | boolean>>>, Maybe<T>>;
 /**
- * Provides a switchMap that will emit from the input observable if the value is true, otherwise emits the otherwise value or empty.
- *
- * @param defaultValue
- * @returns
+ * RxJS operator that emits from the given observable/getter when the source boolean is `true`,
+ * otherwise emits from the `otherwise` source or `EMPTY`.
  */
 export declare function switchMapWhileTrue<T = unknown>(obs: ObservableOrValueGetter<T>): OperatorFunction<boolean, T>;
 export declare function switchMapWhileTrue<T = unknown>(obs: MaybeObservableOrValueGetter<T>): OperatorFunction<boolean, T>;
 export declare function switchMapWhileTrue<T = unknown>(obs: ObservableOrValueGetter<T>, otherwise: ObservableOrValueGetter<T>): OperatorFunction<boolean, T>;
 export declare function switchMapWhileTrue<T = unknown>(obs: MaybeObservableOrValueGetter<T>, otherwise?: MaybeObservableOrValueGetter<T>): OperatorFunction<boolean, Maybe<T>>;
 /**
- * Provides a switchMap that will emit from the input observable if the value is false, otherwise emits the otherwise value or empty.
- *
- * @param defaultValue
- * @returns
+ * RxJS operator that emits from the given observable/getter when the source boolean is `false`,
+ * otherwise emits from the `otherwise` source or `EMPTY`.
  */
 export declare function switchMapWhileFalse<T = unknown>(obs: ObservableOrValueGetter<T>): OperatorFunction<boolean, T>;
 export declare function switchMapWhileFalse<T = unknown>(obs: MaybeObservableOrValueGetter<T>): OperatorFunction<boolean, T>;
 export declare function switchMapWhileFalse<T = unknown>(obs: ObservableOrValueGetter<T>, otherwise: ObservableOrValueGetter<T>): OperatorFunction<boolean, T>;
 export declare function switchMapWhileFalse<T = unknown>(obs: MaybeObservableOrValueGetter<T>, otherwise?: MaybeObservableOrValueGetter<T>): OperatorFunction<boolean, Maybe<T>>;
 /**
- * Provides a switchMap that will emit from the input observable if the value matches the switchOnValue, otherwise emits the otherwise value or empty.
+ * RxJS operator that emits from `obs` when the source boolean matches `switchOnValue`,
+ * otherwise emits from `otherwise` or `EMPTY`.
  *
- * @param defaultValue
- * @returns
+ * @param switchOnValue - the boolean value that triggers emitting from `obs`
+ * @param obs - observable/getter to emit from when matched
+ * @param otherwise - optional observable/getter for the non-matching case
  */
 export declare function switchMapOnBoolean<T = unknown>(switchOnValue: boolean, obs: MaybeObservableOrValueGetter<T>): OperatorFunction<boolean, T>;
 export declare function switchMapOnBoolean<T = unknown>(switchOnValue: boolean, obs: MaybeObservableOrValueGetter<T>, otherwise?: MaybeObservableOrValueGetter<T>): OperatorFunction<boolean, Maybe<T>>;
 /**
- * Combines both filterMaybe and switchMap to build a subscriber that emits values only from a concrete Observable, filtering out null/undefined Observables.
+ * RxJS operator that filters out null/undefined observables and then switches to the remaining ones.
  *
- * @returns
+ * Combines {@link filterMaybe} and `switchMap` to only subscribe to non-nullish observables.
  */
 export declare function switchMapFilterMaybe<T = unknown>(): OperatorFunction<Maybe<Observable<Maybe<T>>>, T>;
 /**
- * Converts a Maybe<Observable<Maybe<T>>> to an Observable<Maybe<T>> that emits null/undefined if the input observable is also null/undefined.
- *
- * @returns
+ * RxJS operator that switches to the emitted observable if defined, or emits `undefined` when the observable is nullish.
  */
 export declare function switchMapMaybe<T = unknown>(): OperatorFunction<Maybe<Observable<Maybe<T>>>, Maybe<T>>;
 /**
- * Performs the input map function on the input if it is not null/undefined.
+ * RxJS operator that applies a map function only when the emitted value is non-null/non-undefined.
  *
- * @param mapFn
- * @returns
+ * @param mapFn - function to transform defined values
+ * @returns an operator that maps defined values and passes through undefined
  */
 export declare function mapMaybe<A, B>(mapFn: MapFunction<A, Maybe<B>>): OperatorFunction<Maybe<A>, Maybe<B>>;
 /**
- * Performs the input map function on the input if the decision returns true.
+ * RxJS operator that applies a map function only when the decision function returns true.
  *
- * @param mapFn
- * @returns
+ * @param mapFn - function to transform the value
+ * @param decision - predicate that determines whether to apply the map
+ * @returns an operator that conditionally maps values
  */
 export declare function mapIf<A, B>(mapFn: MapFunction<Maybe<A>, Maybe<B>>, decision: DecisionFunction<Maybe<A>>): OperatorFunction<Maybe<A>, Maybe<B>>;
 /**

package/src/lib/subscription.d.ts

@@ -1,29 +1,106 @@
 import { type Unsubscribable } from 'rxjs';
 import { type ArrayOrValue, type Destroyable, type Maybe } from '@dereekb/util';
 /**
- * Destroyable object that wraps an Unsubscribable.
+ * Manages a single RxJS subscription with automatic cleanup on reassignment.
+ *
+ * When a new subscription is assigned, the previous one is automatically unsubscribed.
+ * Implements {@link Destroyable} for integration with lifecycle management patterns.
+ *
+ * @example
+ * ```ts
+ * const sub = new SubscriptionObject();
+ *
+ * // Assign a subscription — previous one is automatically unsubscribed
+ * sub.subscription = interval(1000).subscribe(console.log);
+ * sub.subscription = interval(500).subscribe(console.log); // first subscription is cleaned up
+ *
+ * // Clean up when done
+ * sub.destroy();
+ * ```
  */
 export declare class SubscriptionObject<T extends Unsubscribable = Unsubscribable> implements Destroyable {
     private _subscription?;
+    /**
+     * @param sub - optional initial subscription to manage
+     */
     constructor(sub?: Maybe<T>);
+    /**
+     * Whether a subscription is currently being managed.
+     */
     get hasSubscription(): boolean;
+    /**
+     * Sets the managed subscription, unsubscribing from any previous one.
+     */
     set subscription(sub: Maybe<T | void>);
+    /**
+     * Replaces the current subscription with the given one, unsubscribing from the previous.
+     *
+     * @param sub - new subscription to manage, or `undefined`/`void` to just unsubscribe
+     */
     setSub(sub: Maybe<T | void>): void;
+    /**
+     * Unsubscribes from the current subscription, if any.
+     */
     unsub(): void;
+    /**
+     * Unsubscribes from the current subscription and releases the reference.
+     */
     destroy(): void;
 }
 /**
- * Destroyable object that wraps an array of subscriptions.
+ * Manages multiple RxJS subscriptions as a group, with bulk unsubscribe and cleanup.
+ *
+ * Useful when multiple independent subscriptions share a lifecycle. For subscriptions that
+ * should be merged into a single stream, consider using RxJS `merge(...)` instead.
+ *
+ * @example
+ * ```ts
+ * const subs = new MultiSubscriptionObject();
+ *
+ * subs.subscriptions = [
+ *   source1$.subscribe(console.log),
+ *   source2$.subscribe(console.log)
+ * ];
+ *
+ * // Add more subscriptions later
+ * subs.addSubs(source3$.subscribe(console.log));
  *
- * NOTE: In some cases it might be better to use RXJS's merge(...[]) and subscribe to a single item.
+ * // Clean up all at once
+ * subs.destroy();
+ * ```
  */
 export declare class MultiSubscriptionObject<T extends Unsubscribable = Unsubscribable> implements Destroyable {
     private _subscriptions?;
+    /**
+     * @param subs - optional initial subscription(s) to manage
+     */
     constructor(subs?: ArrayOrValue<T>);
+    /**
+     * Whether any subscriptions are currently being managed.
+     */
     get hasSubscription(): boolean;
+    /**
+     * Replaces all managed subscriptions, unsubscribing from previous ones.
+     */
     set subscriptions(subs: ArrayOrValue<T>);
+    /**
+     * Replaces all managed subscriptions with the given ones, unsubscribing from all previous.
+     *
+     * @param subs - new subscription(s) to manage
+     */
     setSubs(subs: ArrayOrValue<T>): void;
+    /**
+     * Adds subscription(s) to the managed set without affecting existing ones. Duplicate subscriptions are ignored.
+     *
+     * @param subs - subscription(s) to add
+     */
     addSubs(subs: ArrayOrValue<T>): void;
+    /**
+     * Unsubscribes from all managed subscriptions and clears the list.
+     */
     unsub(): void;
+    /**
+     * Unsubscribes from all managed subscriptions and releases references.
+     */
     destroy(): void;
 }

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

@@ -2,36 +2,69 @@ import { type Observable } from 'rxjs';
 import { type FactoryWithRequiredInput, type Maybe } from '@dereekb/util';
 import { WorkInstance, type WorkInstanceDelegate } from './work.instance';
 /**
- * A function that handles the incoming value to do work and creates a WorkContext.
+ * A function that accepts an input value, performs asynchronous work, and returns a {@link WorkInstance}
+ * to track progress and results.
  */
 export type WorkFactory<T, O> = FactoryWithRequiredInput<Maybe<WorkInstance<T, O>>, T>;
 /**
- * Performs the work.
- *
- * Can either return an observable that will use the handler, or can use the handler itself.
+ * Union type for work that can either return an observable result directly or interact with
+ * the {@link WorkInstance} handler to manage the work lifecycle manually.
  */
 export type Work<T = unknown, O = unknown> = WorkUsingObservable<T, O> | WorkUsingContext<T, O>;
 /**
- * Performs the work using the value and returns an observable.
+ * Work implementation that returns an observable of the result, allowing the framework
+ * to manage subscription and lifecycle.
  */
 export type WorkUsingObservable<T = unknown, O = unknown> = (value: T) => Observable<O>;
 /**
- * Performs the work that uses the context handler to handle the event.
+ * Work implementation that manages its own lifecycle by calling methods on the
+ * {@link WorkInstance} handler directly (e.g. `startWorking()`, `success()`, `reject()`).
  */
 export type WorkUsingContext<T = unknown, O = unknown> = (value: T, instance: WorkInstance<T, O>) => void;
 /**
- * Config for workFactory().
+ * Configuration for {@link workFactory}.
  */
 export interface WorkFactoryConfig<T, O> {
+    /**
+     * The work function to execute.
+     */
     readonly work: Work<T, O>;
+    /**
+     * Delegate that receives lifecycle callbacks (start, success, reject).
+     */
     readonly delegate: WorkInstanceDelegate<O>;
 }
 /**
- * Creates a function that handles the incoming value and creates a WorkContext.
+ * Creates a {@link WorkFactory} that executes the configured work function with a {@link WorkInstance} handler.
+ *
+ * If the work function returns an observable, it is automatically subscribed to. If it uses
+ * the handler directly, the observable return is ignored.
+ *
+ * @example
+ * ```ts
+ * const factory = workFactory({
+ *   work: (value: number) => of(`result: ${value}`),
+ *   delegate: { startWorking: () => {}, success: () => {}, reject: () => {} }
+ * });
+ *
+ * const instance = factory(42);
+ * // instance tracks the work lifecycle
+ * ```
+ *
+ * @param config - work function and delegate configuration
+ * @returns a factory function that creates WorkInstance for each input
  */
 export declare function workFactory<T, O>({ work, delegate }: WorkFactoryConfig<T, O>): WorkFactory<T, O>;
+/**
+ * A factory that produces a fresh {@link WorkFactoryConfig} for each input value, allowing
+ * per-invocation customization of work and delegate.
+ */
 export type WorkFactoryConfigFactory<T, O> = FactoryWithRequiredInput<WorkFactoryConfig<T, O>, T>;
 /**
- * Creates a WorkFactory using the input WorkFactoryConfigFactory that generates new work configuration given the input.
+ * Creates a {@link WorkFactory} that generates a new {@link WorkFactoryConfig} for each input,
+ * enabling dynamic work and delegate selection per invocation.
+ *
+ * @param configFactory - factory that produces work configuration from the input value
+ * @returns a work factory with per-invocation configuration
  */
 export declare function workFactoryForConfigFactory<T, O>(configFactory: WorkFactoryConfigFactory<T, O>): WorkFactory<T, O>;

package/src/lib/work/work.instance.d.ts

@@ -2,15 +2,39 @@ import { type Maybe, type Destroyable, type ErrorInput } from '@dereekb/util';
 import { type Observable } from 'rxjs';
 import { type LoadingState } from '../loading';
 /**
- * Delegate for WorkInstance
+ * Delegate that receives lifecycle callbacks from a {@link WorkInstance} as work progresses
+ * through its start, success, and rejection phases.
  */
 export interface WorkInstanceDelegate<O = unknown> {
+    /**
+     * Called when work begins.
+     */
     startWorking(): void;
+    /**
+     * Called when work completes successfully.
+     */
     success(result?: Maybe<O>): void;
+    /**
+     * Called when work fails.
+     */
     reject(error?: Maybe<unknown>): void;
 }
 /**
- * Instance that tracks doing an arbitrary piece of asynchronous work that has an input value and an output value.
+ * Tracks the lifecycle of an asynchronous work unit from start through completion (success or error).
+ *
+ * Exposes reactive streams for monitoring progress (`hasStarted$`, `isComplete$`, `loadingState$`)
+ * and provides methods for starting work via observables, promises, or direct state management.
+ *
+ * @example
+ * ```ts
+ * const instance = new WorkInstance(inputValue, {
+ *   startWorking: () => console.log('started'),
+ *   success: (result) => console.log('done:', result),
+ *   reject: (err) => console.error('failed:', err)
+ * });
+ *
+ * instance.startWorkingWithObservable(of('result'));
+ * ```
  */
 export declare class WorkInstance<I = unknown, O = unknown> implements Destroyable {
     private readonly _value;