@juulsgaard/signal-tools 18.0.0 → 18.0.2

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+import * as _angular_core from '@angular/core';
 import { Signal, Injector } from '@angular/core';
-import { BehaviorSubject, Subject, Subscribable } from 'rxjs';
+import * as rxjs from 'rxjs';
+import { BehaviorSubject, Subject, Subscribable, Observable, Observer, Unsubscribable } from 'rxjs';
 import { IValueLoadingState } from '@juulsgaard/rxjs-tools';
 
 /**
@@ -62,15 +64,16 @@ declare function subjectToSignal<T>(subject: BehaviorSubject<T>): Signal<T>;
  */
 declare function subjectToSignal<T>(subject: Subject<T>, initial: T): Signal<T>;
 
-/** @category Loading Signal */
-type LoadingSignal<T> = Signal<T | undefined> & {
+interface LoadingSignalProps {
     /** The current error state */
     readonly error: Signal<Error | undefined>;
     /** The current loading state */
     readonly loading: Signal<boolean>;
     /** Dispose the underlying request / action */
     readonly dispose: () => void;
-};
+}
+/** @category Loading Signal */
+type LoadingSignal<T> = Signal<T | undefined> & LoadingSignalProps;
 /**
  * Options for creating a LoadingSignal
  * @category Loading Signal
@@ -120,6 +123,86 @@ declare function toLoadingSignal<T>(observable: Subscribable<T>, options?: Loadi
  */
 declare function toLoadingSignal<T>(promise: Promise<T>, options?: LoadingSignalOptions): LoadingSignal<T>;
 
+/**
+ * A Map where the state and values are accessible as signals
+ * @category Signal Collections
+ */
+declare class SignalMap<TKey, TVal> implements ReadonlySignalMap<TKey, TVal> {
+    private readonly _map;
+    /** @inheritDoc */
+    readonly value: Signal<ReadonlyMap<TKey, TVal>>;
+    /** @inheritDoc */
+    readonly size: Signal<number>;
+    /** @inheritDoc */
+    readonly empty: Signal<boolean>;
+    constructor(values?: ReadonlyMap<TKey, TVal>);
+    [Symbol.iterator](): IterableIterator<[TKey, TVal]>;
+    private getCopy;
+    /**
+     * Remove all keys not in the whitelist
+     * @param whitelist - The keys to keep
+     */
+    filter(whitelist: ReadonlyArray<TKey> | ReadonlySet<TKey> | undefined): boolean;
+    /** Clear the collection */
+    clear(): boolean;
+    /**
+     * Add a value to the collection if the key is not in use
+     * @param key - The key to use
+     * @param value - The value to add
+     * @return added - Returns true if the value was added
+     */
+    add(key: TKey, value: TVal): boolean;
+    /**
+     * Add a value to the collection
+     * @param key - The key to use
+     * @param value - The value to add
+     * @return added - Returns true if the value was added or changed
+     */
+    set(key: TKey, value: TVal): boolean;
+    /**
+     * Remove a key from the collection
+     * @param key - The key to remove
+     * @return removed - True if an item was removed
+     */
+    delete(key: TKey): boolean;
+    /**
+     * Remove keys from the collection
+     * @param values - The keys to remove
+     * @return removed - True if items were removed
+     */
+    deleteRange(values: TKey[]): boolean;
+    /**
+     * Toggle a value in the map
+     * @param key - The key to toggle
+     * @param value - The value to insert if applicable
+     * @param state - A forced state (`true` = always add, `false` = always delete)
+     * @returns The applied change (`true` = item added, `false` = item removed, `undefined` = nothing changed)
+     */
+    toggle(key: TKey, value: TVal, state?: boolean): boolean | undefined;
+    /** Manually modify the inner collection */
+    modify(modify: (map: Map<TKey, TVal>) => void): void;
+    /** @inheritDoc */
+    has(key: TKey): Signal<boolean>;
+    /** @inheritDoc */
+    get(key: TKey): Signal<TVal | undefined>;
+}
+/**
+ * An immutable Map where the state and values are accessible as signals
+ * @category Signal Collections
+ */
+interface ReadonlySignalMap<TKey, TVal> extends Iterable<[TKey, TVal]> {
+    /** A signal emitting the number of items in the collection */
+    readonly size: Signal<number>;
+    /** A signal emitting true if the collection is empty */
+    readonly empty: Signal<boolean>;
+    /** A signal emitting the inner non-signal map */
+    readonly value: Signal<ReadonlyMap<TKey, TVal>>;
+    /** Create a signal emitting true if a key exists in the collection */
+    has(key: TKey): Signal<boolean>;
+    /** Create a signal emitting the value under a given key */
+    get(key: TKey): Signal<TVal | undefined>;
+}
+
 /**
  * A Set where the state and values are accessible as signals
  * @category Signal Collections
@@ -205,83 +288,502 @@ interface ReadonlySignalSet<T> extends Iterable<T> {
 }
 
 /**
- * A Map where the state and values are accessible as signals
+ * A signal FIFO queue
  * @category Signal Collections
  */
-declare class SignalMap<TKey, TVal> implements ReadonlySignalMap<TKey, TVal> {
-    private readonly _map;
-    /** @inheritDoc */
-    readonly value: Signal<ReadonlyMap<TKey, TVal>>;
-    /** @inheritDoc */
-    readonly size: Signal<number>;
-    /** @inheritDoc */
+declare class SignalQueue<T> {
+    private readonly _items;
+    /** A signal emitting the items of the queue */
+    readonly items: Signal<T[]>;
+    /** A signal emitting the number of items in the queue */
+    readonly length: Signal<number>;
+    /** A signal emitting true if there are no items in the queue */
     readonly empty: Signal<boolean>;
-    constructor(values?: ReadonlyMap<TKey, TVal>);
-    [Symbol.iterator](): IterableIterator<[TKey, TVal]>;
-    private getCopy;
+    private _maxSize;
+    /** The max size of the queue */
+    get maxSize(): number | undefined;
+    constructor(options?: SignalQueueOptions);
     /**
-     * Remove all keys not in the whitelist
-     * @param whitelist - The keys to keep
+     * Signal returning the element at the front of the queue
      */
-    filter(whitelist: ReadonlyArray<TKey> | ReadonlySet<TKey> | undefined): boolean;
-    /** Clear the collection */
-    clear(): boolean;
+    readonly front: Signal<T | undefined>;
+    /** Signal returning the current front element and whether it was just added */
+    readonly frontDelta: Signal<SignalQueueDelta<T>>;
     /**
-     * Add a value to the collection if the key is not in use
-     * @param key - The key to use
-     * @param value - The value to add
-     * @return added - Returns true if the value was added
+     * Signal returning the element at the back of the queue
      */
-    add(key: TKey, value: TVal): boolean;
+    readonly back: Signal<T | undefined>;
+    /** Signal returning the current back element and whether it was just added */
+    readonly backDelta: Signal<SignalQueueDelta<T>>;
     /**
-     * Add a value to the collection
-     * @param key - The key to use
-     * @param value - The value to add
-     * @return added - Returns true if the value was added or changed
+     * Removes an item from the scheduler
+     * @param item
      */
-    set(key: TKey, value: TVal): boolean;
+    removeItem(item: T): boolean;
     /**
-     * Remove a key from the collection
-     * @param key - The key to remove
-     * @return removed - True if an item was removed
+     * Remove the front element from the queue and return it
      */
-    delete(key: TKey): boolean;
+    dequeue(): T | undefined;
     /**
-     * Remove keys from the collection
-     * @param values - The keys to remove
-     * @return removed - True if items were removed
+     * Remove the front x elements from the queue and return them
+     * @param count - The amount of elements to remove
      */
-    deleteRange(values: TKey[]): boolean;
+    dequeue(count: number): T[];
     /**
-     * Toggle a value in the map
-     * @param key - The key to toggle
-     * @param value - The value to insert if applicable
-     * @param state - A forced state (`true` = always add, `false` = always delete)
-     * @returns The applied change (`true` = item added, `false` = item removed, `undefined` = nothing changed)
+     * Remove the back element from the queue and return it
      */
-    toggle(key: TKey, value: TVal, state?: boolean): boolean | undefined;
-    /** Manually modify the inner collection */
-    modify(modify: (map: Map<TKey, TVal>) => void): void;
-    /** @inheritDoc */
-    has(key: TKey): Signal<boolean>;
-    /** @inheritDoc */
-    get(key: TKey): Signal<TVal | undefined>;
+    removeFromBack(): T | undefined;
+    /**
+     * Remove the back x elements from the queue and return it
+     * @param count - The amount of elements to remove
+     */
+    removeFromBack(count: number): T[];
+    /**
+     * Add item to the back of the queue
+     * @param item - Item to add
+     */
+    enqueue(item: T): void;
+    /**
+     * Add items to the back of the queue
+     * @param items - Items to add
+     */
+    enqueue(...items: T[]): void;
+    /**
+     * Add item to the front of the queue
+     * @param item - Item to add
+     */
+    addToFront(item: T): void;
+    /**
+     * Add items to the front of the queue
+     * @param items - Items to add
+     */
+    addToFront(...items: T[]): void;
+    /**
+     * Checks if the item exists in the queue
+     * @param item
+     */
+    contains(item: T): boolean;
+    /**
+     * Remove all elements from the set
+     */
+    clear(): void;
+    /**
+     * Change the max size of the queue
+     * @param size - The new max size
+     */
+    setMaxSize(size: number | undefined): void;
 }
 /**
- * An immutable Map where the state and values are accessible as signals
+ * Options for creating a Queue
  * @category Signal Collections
  */
-interface ReadonlySignalMap<TKey, TVal> extends Iterable<[TKey, TVal]> {
-    /** A signal emitting the number of items in the collection */
-    readonly size: Signal<number>;
-    /** A signal emitting true if the collection is empty */
+interface SignalQueueOptions {
+    size?: number | undefined;
+}
+/**
+ * Data indicating the change in state for a location in the Queue
+ * @category Signal Collections
+ */
+interface SignalQueueDelta<T> {
+    added: boolean;
+    item?: T;
+}
+
+/**
+ * A signal based FILO stack
+ * @category Signal Collections
+ */
+declare class SignalStack<T> {
+    private readonly _items;
+    /** A signal containing the items of the stack from bottom to top */
+    readonly items: Signal<T[]>;
+    /** A signal emitting the number of items in the stack */
+    readonly length: Signal<number>;
+    /** A signal emitting true if there are no items in the stack */
     readonly empty: Signal<boolean>;
-    /** A signal emitting the inner non-signal map */
-    readonly value: Signal<ReadonlyMap<TKey, TVal>>;
-    /** Create a signal emitting true if a key exists in the collection */
-    has(key: TKey): Signal<boolean>;
-    /** Create a signal emitting the value under a given key */
-    get(key: TKey): Signal<TVal | undefined>;
+    constructor();
+    /** Signal returning the element at the top of the stack */
+    readonly top: Signal<T | undefined>;
+    /** Signal returning the current top element and whether it was just added */
+    readonly topDelta: Signal<SignalStackDelta<T>>;
+    /** Signal returning the element at the bottom of the stack */
+    readonly bottom: Signal<T | undefined>;
+    /** Signal returning the current bottom element and whether it was just added */
+    readonly bottomDelta: Signal<SignalStackDelta<T>>;
+    /**
+     * Removes an item from the scheduler
+     * @param item
+     */
+    removeItem(item: T): boolean;
+    /**
+     * Remove the bottom element from the stack and return it
+     */
+    removeFromBottom(): T | undefined;
+    /**
+     * Remove the bottom x elements from the stack and return them
+     * @param count - The amount of elements to remove
+     */
+    removeFromBottom(count: number): T[];
+    /**
+     * Remove the top element from the stack and return it
+     */
+    pop(): T | undefined;
+    /**
+     * Remove the top x elements from the stack and return it
+     * @param count - The amount of elements to remove
+     */
+    pop(count: number): T[];
+    /**
+     * Add item to the top of the stack
+     * @param item - Item to add
+     */
+    push(item: T): void;
+    /**
+     * Add items to the top of the stack
+     * @param items - Items to add
+     */
+    push(...items: T[]): void;
+    /**
+     * Add item to the bottom of the stack
+     * @param item - Item to add
+     */
+    addToBottom(item: T): void;
+    /**
+     * Add items to the bottom of the stack
+     * @param items - Items to add
+     */
+    addToBottom(...items: T[]): void;
+    /**
+     * Checks if the item exists in the queue
+     * @param item
+     */
+    contains(item: T): boolean;
+    /**
+     * Remove all elements from the set
+     */
+    clear(): void;
+}
+/**
+ * Data indicating the change in state for a location in the Stack
+ * @category Signal Collections
+ */
+interface SignalStackDelta<T> {
+    item?: T;
+    added: boolean;
+}
+
+/**
+ * A class representing the state of a request
+ * @category RequestState
+ */
+declare abstract class IRequestState implements Subscribable<unknown> {
+    /** The underlying request */
+    abstract readonly request$: Observable<unknown>;
+    /** The result of the request */
+    abstract readonly result$: Observable<unknown>;
+    /** The result of the request, or undefined when unresolved */
+    abstract readonly result: Signal<unknown | undefined>;
+    /** Emits true when the request is running */
+    abstract readonly loading: Signal<boolean>;
+    /** Emits the error if one is thrown by the request. Otherwise undefined */
+    abstract readonly error: Signal<Error | undefined>;
+    /** Emits true if the request failed */
+    abstract readonly failed: Signal<boolean>;
+    /** Cancel a running request */
+    abstract cancel(): boolean;
+    /**
+     * Perform actions when the request finishes
+     * @param onValue - Action to perform on successful resolution
+     * @param onError - Action to perform on error
+     */
+    abstract then(onValue: (value: unknown) => void, onError?: (error: Error) => void): this;
+    /**
+     * Perform an action if the request fails
+     * @param onError
+     */
+    abstract catch(onError: (error: Error) => void): this;
+    /**
+     * Perform an action when the request finishes (Error or Success)
+     * @param onComplete
+     */
+    abstract finally(onComplete: (error?: Error) => void): this;
+    /**
+     * Subscribe to the underlying request Observable
+     * @param observer
+     */
+    subscribe(observer: Partial<Observer<unknown>>): Unsubscribable;
+}
+/**
+ * A class representing the state of a request with a known return type
+ * @category RequestState
+ */
+declare abstract class IValueRequestState<T> extends IRequestState implements Subscribable<T> {
+    abstract readonly request$: Observable<T>;
+    abstract readonly result$: Observable<T>;
+    abstract readonly result: Signal<T | undefined>;
+    subscribe(observer: Partial<Observer<T>>): Unsubscribable;
+    then(onValue: (value: T) => void, onError?: (error: Error) => void): this;
+    catch(onError: (error: Error) => void): this;
+    finally(onComplete: (error?: Error) => void): this;
+    /**
+     * Cancel a running request
+     * @param error - Optionally provide a custom error to throw when cancelling the request
+     */
+    abstract cancel(error?: string | Error | (() => Error)): boolean;
+}
+
+/**
+ * A manually populated RequestState
+ * @category RequestState
+ */
+declare class WritableRequestState<T> extends IValueRequestState<T> {
+    private readonly onCancel?;
+    private _completed;
+    get completed(): boolean;
+    private readonly _request$;
+    readonly request$: rxjs.Observable<T>;
+    private readonly _result$;
+    readonly result$: rxjs.Observable<T>;
+    private readonly _result;
+    readonly result: _angular_core.Signal<T | undefined>;
+    private readonly _loading;
+    readonly loading: _angular_core.Signal<boolean>;
+    private readonly _error;
+    readonly error: _angular_core.Signal<Error | undefined>;
+    readonly failed: _angular_core.Signal<boolean>;
+    private readonly _cancelled;
+    /** Emits true when the RequestState has been cancelled by a consumer, otherwise emits false */
+    readonly cancelled: _angular_core.Signal<boolean>;
+    private readonly _cancelled$;
+    /** Emits true when the RequestState has been cancelled by a consumer */
+    readonly cancelled$: rxjs.Observable<true>;
+    constructor(onCancel?: (() => void) | undefined);
+    /**
+     * Create a Readonly version of the RequestState
+     */
+    asReadonly(): IValueRequestState<T>;
+    /**
+     * Set the RequestState to an Error state
+     * @param error - The error for the RequestState
+     */
+    setError(error: unknown | Error): void;
+    /**
+     * Set the RequestState to a completed state with a given value
+     * @param value - The value to emit
+     */
+    setValue(value: T): void;
+    cancel(error?: string | Error | (() => Error)): boolean;
+}
+
+/**
+ * Create a RequestState from a request or Value
+ * @param data - The request or value
+ * @category RequestState
+ */
+declare function valueRequestState<T>(data: T | Promise<T> | Observable<T>): IValueRequestState<T>;
+/** @category RequestState */
+interface AltConstructors {
+    /**
+     * Create a writable RequestState
+     * @param onCancel - Optional cancellation handler
+     * @category RequestState
+     */
+    writable<T>(onCancel?: () => void): WritableRequestState<T>;
+    /**
+     * Create a RequestState emitting an error
+     * @param error - The error to emit
+     * @category RequestState
+     */
+    error(error: Error | (() => Error)): IRequestState;
+    /**
+     * Create a typed RequestState emitting an error
+     * @param error - The error to emit
+     * @category RequestState
+     */
+    error<T>(error: Error | (() => Error)): IValueRequestState<T>;
+    /**
+     * Create a RequestState which is always loading
+     * @category RequestState
+     */
+    loading(): IRequestState;
+    /**
+     * Create a typed RequestState which is always loading
+     * @category RequestState
+     */
+    loading<T>(): IValueRequestState<T>;
+    /**
+     * Create a RequestState that resolves after an amount of time
+     * @param duration - The loading duration in milliseconds
+     * @category RequestState
+     */
+    loading(duration: number): IRequestState;
+    /**
+     * Create a RequestState that resolves with a value after an amount of time
+     * @param duration - The loading duration in milliseconds
+     * @param value - The value to resolve with after the delay
+     * @category RequestState
+     */
+    loading<T>(duration: number, value: T): IValueRequestState<T>;
+    /**
+     * Create an empty RequestState
+     * @category RequestState
+     */
+    empty(): IRequestState;
+    /**
+     * Create a typed empty RequestState
+     * @category RequestState
+     */
+    empty<T>(): IValueRequestState<T>;
 }
+declare const requestState: typeof valueRequestState & AltConstructors;
+
+/**
+ * A RequestState representing a pending async action
+ * @category RequestState
+ */
+declare class AsyncRequestState<T> extends IValueRequestState<T> {
+    private readonly _request$;
+    readonly request$: Observable<T>;
+    private readonly _result$;
+    readonly result$: Observable<T>;
+    private readonly _result;
+    readonly result: _angular_core.Signal<T | undefined>;
+    private readonly _loading;
+    readonly loading: _angular_core.Signal<boolean>;
+    private readonly _error;
+    readonly error: _angular_core.Signal<Error | undefined>;
+    readonly failed: _angular_core.Signal<boolean>;
+    private readonly sub;
+    constructor(request: Promise<T> | Observable<T>);
+    cancel(error?: string | Error | (() => Error)): boolean;
+}
+
+/**
+ * An Empty RequestState
+ * @category RequestState
+ */
+declare class EmptyRequestState<T> extends IValueRequestState<T> {
+    readonly request$: rxjs.Observable<never>;
+    readonly result$: rxjs.Observable<never>;
+    readonly result: Signal<undefined>;
+    readonly loading: Signal<false>;
+    readonly error: Signal<undefined>;
+    readonly failed: Signal<false>;
+    cancel(): boolean;
+}
+
+/**
+ * A RequestState which always emits an error
+ * @category RequestState
+ */
+declare class ErrorRequestState<T> extends IValueRequestState<T> {
+    readonly request$: Observable<never>;
+    readonly result$: Observable<never>;
+    readonly result: Signal<undefined>;
+    readonly loading: Signal<boolean>;
+    readonly error: Signal<Error | undefined>;
+    readonly failed: Signal<boolean>;
+    constructor(getError: () => Error);
+    cancel(): boolean;
+}
+
+/**
+ * A RequestState which is perpetually loading
+ * @category RequestState
+ */
+declare class LoadingRequestState<T> extends IValueRequestState<T> {
+    private readonly _request$;
+    readonly request$: rxjs.Observable<T>;
+    readonly result$: rxjs.Observable<T>;
+    readonly result: Signal<undefined>;
+    private readonly _loading;
+    readonly loading: Signal<boolean>;
+    readonly error: Signal<undefined>;
+    readonly failed: Signal<false>;
+    cancel(): boolean;
+}
+
+/**
+ * A RequestState which always returns the same value immediately
+ * @category RequestState
+ */
+declare class StaticRequestState<T> extends IValueRequestState<T> {
+    private readonly value;
+    readonly request$: Observable<T>;
+    readonly result$: Observable<T>;
+    readonly result: Signal<T>;
+    readonly loading: Signal<false>;
+    readonly error: Signal<undefined>;
+    readonly failed: Signal<false>;
+    constructor(value: T);
+    cancel(): boolean;
+    then(next: (value: T) => void, _error?: (error: Error) => void): this;
+    catch(_onError: (error: Error) => void): this;
+    finally(onComplete: () => void): this;
+}
+
+/**
+ * A container which keeps track of a replaceable RequestState
+ * @category RequestState
+ */
+declare class RequestTracker {
+    private readonly _request;
+    /** The currently active RequestState */
+    readonly request: Signal<IRequestState>;
+    /** The currently active RequestState */
+    set current(req: IRequestState);
+    get current(): IRequestState;
+    /** Emits true if the current RequestState is loading */
+    readonly loading: Signal<boolean>;
+    /** Emits an error if the current RequestState is in an error state */
+    readonly error: Signal<Error | undefined>;
+    /** Emits true if the current RequestState has failed */
+    readonly failed: Signal<boolean>;
+    constructor(request?: IRequestState);
+    /**
+     * Set a new current RequestState
+     * @param state - The new RequestState
+     */
+    set(state: IRequestState): void;
+    /**
+     * Resets the Tracker to an Empty state
+     */
+    reset(): void;
+}
+/**
+ * A container which keeps track of a replaceable RequestState of a known return type
+ * @category RequestState
+ */
+declare class ValueRequestTracker<T> extends RequestTracker {
+    private readonly _valueRequest;
+    request: Signal<IValueRequestState<T>>;
+    set current(req: IValueRequestState<T>);
+    get current(): IValueRequestState<T>;
+    constructor(request?: IValueRequestState<T>);
+    set(req: IValueRequestState<T>): void;
+    reset(): void;
+}
+/**
+ * Create an empty and untyped RequestTracker
+ * @category RequestState
+ */
+declare function requestTracker(): RequestTracker;
+/**
+ * Create an empty RequestTracker with a known RequestState return type
+ * @category RequestState
+ */
+declare function requestTracker<T>(): ValueRequestTracker<T>;
+/**
+ * Create a typed RequestTracker from a types RequestState
+ * @param request - The initial RequestState
+ * @category RequestState
+ */
+declare function requestTracker<T>(request: IValueRequestState<T>): ValueRequestTracker<T>;
+/**
+ * Create an untyped RequestTracker from an untyped RequestState
+ * @param request - The initial RequestState
+ * @category RequestState
+ */
+declare function requestTracker(request: IRequestState): RequestTracker;
 
-export { type CreateLoadingSignalOptions, type LoadingSignal, type LoadingSignalOptions, type ReadonlySignalMap, type ReadonlySignalSet, SignalMap, SignalSet, debouncedSignal, debouncedThrottledSignal, loadingSignal, searchSignal, subjectToSignal, throttledSignal, toLoadingSignal };
+export { AsyncRequestState, type CreateLoadingSignalOptions, EmptyRequestState, ErrorRequestState, IRequestState, IValueRequestState, LoadingRequestState, type LoadingSignal, type LoadingSignalOptions, type ReadonlySignalMap, type ReadonlySignalSet, RequestTracker, SignalMap, SignalQueue, type SignalQueueDelta, type SignalQueueOptions, SignalSet, SignalStack, type SignalStackDelta, StaticRequestState, ValueRequestTracker, WritableRequestState, debouncedSignal, debouncedThrottledSignal, loadingSignal, requestState, requestTracker, searchSignal, subjectToSignal, throttledSignal, toLoadingSignal };