@dereekb/rxjs 13.0.7 → 13.2.0

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

@@ -2,15 +2,16 @@ import { type OperatorFunction, type MonoTypeOperatorFunction } from 'rxjs';
 import { type MapKeysIntersectionObject } from '@dereekb/util';
 import { type ObservableOrValue } from './getter';
 /**
- * OperatorFunction that pipes the input from the object with a keys observable to produce the result of mapKeysIntersectionObjectToArray.
+ * RxJS operator that extracts values from a keyed object using a keys observable,
+ * returning only the values whose keys are present in both.
  *
- * @param keysObs
- * @returns
+ * @param keysObs - observable (or static value) of keys to intersect with
+ * @returns an operator that maps a keyed object to an array of matching values
  */
 export declare function mapKeysIntersectionToArray<T>(keysObs: ObservableOrValue<Iterable<string>>): OperatorFunction<MapKeysIntersectionObject<T>, T[]>;
 /**
- * Operatorfunction using distinctUntilChanged to check that two maps have the same keys.
+ * `distinctUntilChanged` variant for `Map` instances that only emits when the set of map keys changes.
  *
- * @returns
+ * @returns an operator that filters out Maps with unchanged key sets
  */
 export declare function distinctUntilMapHasDifferentKeys<I extends Map<K, V>, K, V>(): MonoTypeOperatorFunction<I>;

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

@@ -1,18 +1,38 @@
 import { type RandomNumberFactoryConfig, type RandomNumberFactory } from '@dereekb/util';
 import { type MonoTypeOperatorFunction, type SchedulerLike } from 'rxjs';
 /**
- * Used to log a message to the console.
+ * RxJS operator that logs each emission to the console as a side-effect.
  *
- * @param messageOrFunction
- * @returns
+ * Accepts either a static label or a function that produces log arguments from the emitted value.
+ *
+ * @example
+ * ```ts
+ * source$.pipe(
+ *   tapLog('Value:')
+ * ).subscribe();
+ * // logs "Value: <emitted value>" for each emission
+ * ```
+ *
+ * @param messageOrFunction - static label or function returning log arguments
+ * @param consoleLogFn - which console method to use (defaults to 'log')
+ * @returns a tap operator that logs emissions
  */
 export declare function tapLog<T = unknown>(message: string | number, consoleLogFn?: 'log' | 'warn' | 'error'): MonoTypeOperatorFunction<T>;
 export declare function tapLog<T = unknown>(messageFunction: (value: T) => unknown[], consoleLogFn?: 'log' | 'warn' | 'error'): MonoTypeOperatorFunction<T>;
 /**
- * Used to make a random delay for each observable value.
+ * RxJS operator that adds a random delay before each emission.
+ *
+ * Useful for simulating network latency or staggering requests.
  *
- * @param maxOrArgs
- * @returns
+ * @param maxOrArgs - maximum delay in ms, or a full random number config
+ * @returns an operator that delays each emission by a random amount
  */
 export declare function randomDelay<T = unknown>(maxOrArgs: number | RandomNumberFactoryConfig): MonoTypeOperatorFunction<T>;
+/**
+ * RxJS operator that adds a random delay using a custom random number generator.
+ *
+ * @param makeRandomDelay - factory that produces random delay values
+ * @param scheduler - the scheduler to use for the delay (defaults to asyncScheduler)
+ * @returns an operator that delays each emission
+ */
 export declare function randomDelayWithRandomFunction<T = unknown>(makeRandomDelay: RandomNumberFactory, scheduler?: SchedulerLike): MonoTypeOperatorFunction<T>;

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

@@ -1,9 +1,9 @@
 import { type ModelKeyRef, type UniqueModel } from '@dereekb/util';
 /**
- * distinctUntilChanged() that compares id values.
+ * `distinctUntilChanged` variant that only emits when the model's `id` property changes.
  */
 export declare function distinctUntilModelIdChange<T extends UniqueModel>(): import("rxjs").MonoTypeOperatorFunction<T>;
 /**
- * distinctUntilChanged() that compares key values.
+ * `distinctUntilChanged` variant that only emits when the model's `key` property changes.
  */
 export declare function distinctUntilModelKeyChange<T extends ModelKeyRef>(): import("rxjs").MonoTypeOperatorFunction<T>;

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

@@ -2,7 +2,11 @@ import { type IncrementingNumberFactoryConfig } from '@dereekb/util';
 import { type Observable, type OperatorFunction } from 'rxjs';
 import { type FactoryTimerConfig } from './factory';
 /**
- * Similar to count(), but counts emissions as they occur using scan.
+ * RxJS operator that counts emissions as they occur using `scan`, emitting the running count
+ * after each emission (unlike `count()` which only emits on completion).
+ *
+ * @param startAt - initial count value (defaults to 0)
+ * @returns an operator that emits the running emission count
  */
 export declare function scanCount(startAt?: number): OperatorFunction<unknown, number>;
 /**
@@ -11,9 +15,9 @@ export declare function scanCount(startAt?: number): OperatorFunction<unknown, n
 export interface IncrementingTimerConfig extends Omit<FactoryTimerConfig<number>, 'factory'>, IncrementingNumberFactoryConfig {
 }
 /**
- * Creates a factoryTimer for incrementing numbers.
+ * Creates a {@link factoryTimer} that emits incrementing numbers on an interval.
  *
- * @param config
- * @returns
+ * @param config - timer and incrementing number configuration
+ * @returns an observable of incrementing numbers
  */
 export declare function incrementingNumberTimer(config?: IncrementingTimerConfig): Observable<number>;

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

@@ -40,10 +40,23 @@ export interface AsyncPusherConfig<T> {
     cleanupObs?: Observable<unknown>;
 }
 /**
- * Creates an AsyncPusher.
+ * Creates an {@link AsyncPusher} — a callable function backed by a throttled {@link BehaviorSubject}.
  *
- * @param config
- * @returns
+ * Each call pushes a value onto the internal subject and returns the shared, throttled observable.
+ * Useful for debouncing repeated calls while sharing a single observable output.
+ *
+ * @example
+ * ```ts
+ * const pusher = asyncPusher<string>({ throttle: 100 });
+ * const result$ = pusher('hello');
+ * // subsequent calls within 100ms are throttled
+ * pusher('world');
+ * // clean up
+ * pusher.destroy();
+ * ```
+ *
+ * @param config - optional throttle, distinct, and pipe settings
+ * @returns an async pusher function
  */
 export declare function asyncPusher<T>(config?: AsyncPusherConfig<T>): AsyncPusher<T>;
 /**
@@ -51,11 +64,11 @@ export declare function asyncPusher<T>(config?: AsyncPusherConfig<T>): AsyncPush
  */
 export type AsyncPusherCache<T> = CachedFactoryWithInput<AsyncPusher<T>, Observable<unknown>>;
 /**
- * Creates a cache that returns an AsyncPusher.
+ * Creates a cached factory that lazily creates and returns an {@link AsyncPusher}.
  *
- * The CachedFactoryWithInput resunt can optionally be pass an observable to watch for the cleanup process.
+ * The factory optionally accepts a cleanup observable — when it completes, the pusher is destroyed.
  *
- * @param config
- * @returns
+ * @param config - optional config passed to the underlying async pusher
+ * @returns a cached factory that produces an async pusher
  */
 export declare function asyncPusherCache<T>(config?: AsyncPusherConfig<T>): AsyncPusherCache<T>;

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

@@ -1,38 +1,46 @@
 import { type Getter, type Maybe } from '@dereekb/util';
 import { type Observable, type MonoTypeOperatorFunction } from 'rxjs';
 /**
- * Merges both startWith and tapFirst to initialize a pipe.
+ * Combines `startWith` and {@link tapFirst} to initialize an observable pipe with a side-effect on the first emission.
  *
- * @param initial
- * @param tap
- * @param skipFirst
- * @returns
+ * Emits the `initial` value first, then taps on the first emitted value to run the provided callback.
+ *
+ * @param tap - side-effect function called with the first value
+ * @param initial - optional starting value emitted before the source
+ * @param skipFirst - if true, skips tapping the initial value
+ * @returns an operator that initializes the pipe with a tap
  */
 export declare function initialize<T>(tap: (value: Maybe<T>) => void, initial?: Maybe<T>, skipFirst?: boolean): MonoTypeOperatorFunction<T>;
 /**
- * Taps once on the first element.
+ * Executes a side-effect on the first emission from the observable, then passes all values through.
  *
- * @param tap
- * @param skipFirst
- * @returns
+ * @param tap - the side-effect function to call once
+ * @param skipFirst - if true, skips the very first emission before tapping
+ * @returns an operator that taps the first value
  */
 export declare function tapFirst<T>(tap: (value: T) => void, skipFirst?: boolean): MonoTypeOperatorFunction<T>;
 /**
- * Prevents an observable from emitting complete until it is unsubscribed from.
+ * Wraps an observable so that it never emits `complete` until it is unsubscribed.
  *
- * The subscription will never have complete() called as complete only gets called after it unsubscribes,
- * so use finalize() if additional cleanup is required.
+ * The subscription will never have `complete()` called since it only triggers after unsubscription.
+ * Use `finalize()` for additional cleanup.
  *
- * @param obs
- * @returns
+ * @param obs - the source observable to wrap
+ * @returns an observable that only completes on unsubscription
  */
 export declare function preventComplete<T>(obs: Observable<T>): Observable<T>;
 /**
- * Similar to from, but uses a Getter to keeps the Observable cold until it is subscribed to, then calls the promise or observable.
+ * Creates a cold observable that defers execution of the getter until subscription, then shares the result.
+ *
+ * Unlike `from()`, the promise/observable is not created until the first subscriber connects.
  *
- * The result value of the promise or the latest value of the observable is shared.
+ * @example
+ * ```ts
+ * const data$ = lazyFrom(() => fetch('/api/data').then(r => r.json()));
+ * // The fetch is not called until data$ is subscribed to
+ * ```
  *
- * @param getter
- * @returns
+ * @param getter - factory that returns a Promise or Observable
+ * @returns a shared observable that defers execution until subscription
  */
 export declare function lazyFrom<T>(getter: Getter<Promise<T> | Observable<T>>): Observable<T>;

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

@@ -36,4 +36,21 @@ export interface ErrorOnEmissionsInPeriodConfig<T> {
      */
     readonly errorMessage?: string;
 }
+/**
+ * RxJS operator that throws an error (or switches to an alternative observable) when too many
+ * emissions occur within a rolling time period.
+ *
+ * Useful as a safety valve to detect infinite loops or runaway observables.
+ *
+ * @example
+ * ```ts
+ * source$.pipe(
+ *   errorOnEmissionsInPeriod({ maxEmissionsPerPeriod: 100, period: 1000 })
+ * ).subscribe();
+ * // throws if more than 100 emissions occur within 1 second
+ * ```
+ *
+ * @param config - period duration, max emissions, and error/fallback handling
+ * @returns an operator that monitors emission frequency
+ */
 export declare function errorOnEmissionsInPeriod<T>(config: ErrorOnEmissionsInPeriodConfig<T>): MonoTypeOperatorFunction<T>;

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

@@ -1,29 +1,57 @@
 import { type Observable, type OperatorFunction } from 'rxjs';
 import { type PrimativeKey, type ReadKeyFunction, type ReadMultipleKeysFunction } from '@dereekb/util';
 /**
- * Creates a map function that maps the input Map to an Observable that returns values mapped from the map's values.
+ * Creates a function that takes a `Map` and combines the latest emissions from observables
+ * created from each map value.
  *
- * @param mapToObs
- * @returns
+ * @param mapToObs - function to transform each map value into an observable
+ * @returns a function that converts a Map to a combined observable of results
  */
 export declare function combineLatestFromMapValuesObsFn<T, O>(mapToObs: (value: T) => Observable<O>): (map: Map<unknown, T>) => Observable<O[]>;
+/**
+ * Creates a function that takes an array of values, maps each to an observable, and combines their latest emissions.
+ *
+ * Returns `of([])` for empty arrays.
+ *
+ * @param mapToObs - function to transform each value into an observable
+ * @returns a function that converts an array to a combined observable
+ */
 export declare function combineLatestFromArrayObsFn<T, O>(mapToObs: (value: T) => Observable<O>): (values: T[]) => Observable<O[]>;
 export type ObservableObjectMap = object;
 export type ObservableObjectMapResult<T extends ObservableObjectMap> = {
     [K in keyof T]: T[K] extends Observable<infer O> ? O : T[K];
 };
+/**
+ * Combines the latest values from an object of observables into a single observable of resolved values.
+ *
+ * Each key in the input object maps to an observable (or static value). The result observable
+ * emits an object with the same keys, where each value is the latest emission from its source.
+ *
+ * @example
+ * ```ts
+ * const result$ = combineLatestFromObject({
+ *   name: of('Alice'),
+ *   age: of(30)
+ * });
+ * // emits { name: 'Alice', age: 30 }
+ * ```
+ *
+ * @param objectMap - an object whose values are observables or static values
+ * @returns an observable that emits the resolved object
+ */
 export declare function combineLatestFromObject<T extends ObservableObjectMap>(objectMap: T): Observable<ObservableObjectMapResult<T>>;
 /**
- * Convenience function for creating a map() operator function using keyValueMapFactory().
+ * RxJS operator that maps an array of items to a `Map<K, T>` using the provided key reader.
  *
- * @param read
- * @returns
+ * @param read - function to extract the key from each item
+ * @returns an operator that converts an array into a keyed Map
  */
 export declare function keyValueMap<T, K extends PrimativeKey = PrimativeKey>(read: ReadKeyFunction<T, K>): OperatorFunction<T[], Map<K, T>>;
 /**
- * Convenience function for creating a map() operator function using multiKeyValueMapFactory().
+ * RxJS operator that maps an array of items to a `Map<K, T>` using a multi-key reader,
+ * allowing each item to appear under multiple keys.
  *
- * @param read
- * @returns
+ * @param read - function to extract multiple keys from each item
+ * @returns an operator that converts an array into a multi-keyed Map
  */
 export declare function multiKeyValueMap<T, K extends PrimativeKey = PrimativeKey>(read: ReadMultipleKeysFunction<T, K>): OperatorFunction<T[], Map<K, T>>;

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

@@ -1,9 +1,12 @@
 import { type FilterUniqueFunctionAdditionalKeysInput, type PrimativeKey, type ReadKeyFunction } from '@dereekb/util';
 import { type MonoTypeOperatorFunction } from 'rxjs';
 /**
- * Convenience function for building an OperatorFunction that uses filterUniqueFunction().
+ * RxJS operator that filters an array to unique items based on a key reader function.
  *
- * @param readKey
- * @param additionalKeys
+ * Uses {@link filterUniqueFunction} to deduplicate emitted arrays by extracting a key from each item.
+ *
+ * @param readKey - function to extract the unique key from each item
+ * @param additionalKeysInput - optional additional keys to include in the unique set
+ * @returns an operator that emits deduplicated arrays
  */
 export declare function filterUnique<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>, additionalKeysInput?: FilterUniqueFunctionAdditionalKeysInput<T, K>): MonoTypeOperatorFunction<T[]>;

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

@@ -1,10 +1,44 @@
 import { type Maybe, type PrimativeKey, type ReadValueFunction, type EqualityComparatorFunction } from '@dereekb/util';
 import { type MonoTypeOperatorFunction, type Observable, type OperatorFunction } from 'rxjs';
+/**
+ * RxJS operator that checks whether the emitted `Set` contains all values from the given observable.
+ *
+ * @param valuesObs - observable of values to check against
+ * @returns an operator that emits true if all values are contained in the set
+ */
 export declare function setContainsAllValuesFrom<T>(valuesObs: Observable<Maybe<Iterable<T>>>): OperatorFunction<Set<T>, boolean>;
+/**
+ * RxJS operator that checks whether the emitted `Set` contains any value from the given observable.
+ *
+ * @param valuesObs - observable of values to check against
+ * @returns an operator that emits true if any value is contained in the set
+ */
 export declare function setContainsAnyValueFrom<T>(valuesObs: Observable<Maybe<Iterable<T>>>): OperatorFunction<Set<T>, boolean>;
+/**
+ * RxJS operator that checks whether the emitted `Set` contains none of the values from the given observable.
+ *
+ * @param valuesObs - observable of values to check against
+ * @returns an operator that emits true if no values are contained in the set
+ */
 export declare function setContainsNoValueFrom<T>(valuesObs: Observable<Maybe<Iterable<T>>>): OperatorFunction<Set<T>, boolean>;
+/**
+ * `distinctUntilChanged` variant for iterables that only emits when the contained values change.
+ */
 export declare function distinctUntilHasDifferentValues<I extends Iterable<K>, K extends PrimativeKey>(): MonoTypeOperatorFunction<I>;
+/**
+ * `distinctUntilChanged` variant that extracts iterable values from the emitted item and only emits
+ * when the set of extracted values changes.
+ *
+ * @param readValues - function to extract the iterable of values to compare
+ */
 export declare function distinctUntilItemsHaveDifferentValues<I, V extends Iterable<PrimativeKey>>(readValues: ReadValueFunction<I, V>): MonoTypeOperatorFunction<I>;
 export declare function distinctUntilItemsHaveDifferentValues<I, V extends Iterable<PrimativeKey>>(readValues: ReadValueFunction<I, V>): MonoTypeOperatorFunction<Maybe<I>>;
+/**
+ * `distinctUntilChanged` variant that extracts values from the emitted item and compares them
+ * using a custom equality comparator.
+ *
+ * @param readValues - function to extract the value to compare
+ * @param isEqualComparator - custom equality function for the extracted values
+ */
 export declare function distinctUntilItemsValueChanges<I, V>(readValues: ReadValueFunction<I, V>, isEqualComparator: EqualityComparatorFunction<V>): MonoTypeOperatorFunction<I>;
 export declare function distinctUntilItemsValueChanges<I, V>(readValues: ReadValueFunction<I, V>, isEqualComparator: EqualityComparatorFunction<V>): MonoTypeOperatorFunction<Maybe<I>>;

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

@@ -8,6 +8,23 @@ export interface SearchStringFilterConfig<T> {
     readonly search$: Observable<Maybe<string>>;
 }
 /**
- * Uses a SearchStringFilterFunction to filter values.
+ * RxJS operator that filters an emitted array by a reactive search string.
+ *
+ * Combines the source array with the `search$` observable and applies the configured
+ * search string filter function. When the search is null/undefined, all items pass through.
+ *
+ * @example
+ * ```ts
+ * const items$ = of(['apple', 'banana', 'cherry']);
+ * const search$ = new BehaviorSubject<string>('an');
+ *
+ * items$.pipe(
+ *   filterWithSearchString({ filter: (x) => x, search$ })
+ * ).subscribe(console.log);
+ * // ['banana']
+ * ```
+ *
+ * @param config - search filter configuration with filter function and search$ observable
+ * @returns an operator that filters arrays by search string
  */
 export declare function filterWithSearchString<T>(config: SearchStringFilterConfig<T>): MonoTypeOperatorFunction<T[]>;

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

@@ -1,8 +1,28 @@
 import { type MonoTypeOperatorFunction } from 'rxjs';
 import { type Getter, type GetterOrValue } from '@dereekb/util';
 /**
- * Used to pass a default value incase an observable has not yet started emititng values.
+ * RxJS operator that emits a default value if the source does not emit within the specified timeout.
+ *
+ * After the timeout, the default value is prepended and the source continues normally.
+ *
+ * @param defaultValue - value or getter to use as the default
+ * @param first - timeout in ms before emitting the default (defaults to 0)
+ * @returns an operator that provides a fallback on slow emissions
  */
 export declare function timeoutStartWith<T>(defaultValue: GetterOrValue<T>, first?: number): MonoTypeOperatorFunction<T>;
+/**
+ * RxJS operator that executes a side-effect function if the source does not emit within the given timeout.
+ *
+ * @param timeoutDelay - timeout in ms before triggering the side-effect
+ * @param useFn - side-effect function to call on timeout
+ * @returns an operator that taps after timeout
+ */
 export declare function tapAfterTimeout<T>(timeoutDelay: number, useFn: () => void): MonoTypeOperatorFunction<T>;
+/**
+ * RxJS operator that throws an error if the source does not emit within the given timeout.
+ *
+ * @param timeoutDelay - timeout in ms before throwing
+ * @param error - getter that produces the error to throw
+ * @returns an operator that throws on timeout
+ */
 export declare function throwErrorAfterTimeout<T>(timeoutDelay: number, error: Getter<unknown>): MonoTypeOperatorFunction<T>;

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

@@ -1,7 +1,9 @@
 import { type Observable } from 'rxjs';
 /**
- * Convenience function to subscribe to the input observable and use the first value.
+ * Subscribes to the observable, calls the provided function with the first emitted value,
+ * then automatically unsubscribes.
  *
- * @param useFn
+ * @param obs - the source observable
+ * @param useFn - function to call with the first value
  */
 export declare function useFirst<T>(obs: Observable<T>, useFn: (value: T) => void): void;