nope/lib/module/Interface.nopeObservebale.ts

/**
 * @author Martin Karkowski
 * @email m.karkowski@zema.de
 * @create date 2020-10-12 17:25:21
 * @modify date 2020-10-12 17:26:53
 * @desc [description]
 */

import { BehaviorSubject, CompletionObserver, ErrorObserver, NextObserver, Observable, Subscription } from "rxjs";

/** Definition of a Callback, used in the Observables */
export type waitForCallback<T> = (content?: T | null, sender?: string, timeStamp?: number | null, ...data) => boolean | Promise<boolean>;

/** Options used to describe a Wait-For statement on an Observable */
export interface nopeWaitForOptions {
    /**
     * Flag to enable / disable testing the first available value.
     */
    testFirst?: boolean;
    /**
     * The mode used for the subscription
     */
    subscriptionMode?: 'immediate' | 'sync';
    /**
     * Type of the Trigger used.
     */
    triggerMode?: Array<'sub' | 'super' | 'direct'>;
}

/** Definition of an Observer */
export interface nopeObserver<T> extends Subscription {
    /**
     * Options used to describe a Subscription with some additional parameters
     */
    options: nopeSubscriptionOptions
    /**
     * Function used to pause the Subscription. This will prevent receiving updates.
     * Only affects unpause / active subscriptions.
     */
    pause(): void;
    /**
     * Function used to unpause the Subscription. Only affects paused subscriptions. 
     * After calling this Function => The Callback will receive updates again.
     */
    unpause(): void;
}

/** Options used for determine the updates, which should be received. */
export interface nopeSubscriptionOptions {
    /**
     * Type of the Trigger used.
     */
    mode: Array<'sub' | 'super' | 'direct'>
}

/**
 * Defintion of a partial observer
 */
export interface NopePartialObserver<T> {
    /**
     * Function, which will be called during an update
     */
    next?: observableCallback<T>,
    /**
     * Function, which will be called if an error has to be
     * propagated on the channel.
     */
    error?: (error: any) => void,
    /**
     * Functon that will be called on completition.
     */
    complete?: () => void,
}


export declare type PartialObserver<T> = (NextObserver<T> | ErrorObserver<T> | CompletionObserver<T>);

export type observableCallback<T> = (content: T | null, sender: string, timeStamp: number | null, ...data) => void;

export type pipe<T, K> = (scope: { [index: string]: any }, observable: Observable<T>) => Observable<K>

/**
 * Interface of an nope Observable.
 */
export interface INopeObservable<T, S = T, G = T> {

    /**
     * The original Observable. Implemented by an Behaviour Subject.
     * See here: https://www.learnrxjs.io/learn-rxjs/subjects/behaviorsubject
     * for more details.
     */
    observable: BehaviorSubject<G>;

    /**
     * An id of the Observable.
     */
    readonly id: string;

    /**
     * Accessor to the currently stored value.
     */
    _value: T;

    /**
     * options.
     */
    options: any;

    /**
     * Function to specify a Setter
     */
    setter: ((value: S | null, sender: string | null, timeStamp: number | null, ...data) => {
        data: T | null,
        valid: boolean,
    }) | null;

    /**
     * Function to specify a Getter
     */
    getter: ((value: T | null) => G | null) | null;

    /**
     * Function to 
     * @param value 
     * @param sender 
     * @param timeStamp 
     * @param data 
     */
    setContent(value: S | null, sender?: string | null, timeStamp?: number | null, ...data): void

    /**
     * Function to Force an Update.
     * @param sender Sender, which initiated the Update
     * @param timestamp The Timestamp of the Updaet
     * @param data Additional Args. 
     */
    forcePublish(sender?: string | null, timestamp?: number | null, ...data);

    /**
     * A Set containing the Subscriptions
     */
    _subscriptions: Set<() => void>;

    /**
     * Flag to Disable Publishing
     */
    disablePublishing: boolean;

    /**
     * Function, used to dispose the observable.
     * Every item will be unsubscribed.
     */
    dispose(): void

    /**
     * Function to extract the Content.
     * If a Getter is provided, the Getter will be used
     * to Transform the item.
     */
    getContent(): G | null;

    /**
     * A Function to subscribe to updates of the Observable.
     * @param observer The Observer. Could be a Function or a Partial Observer.
     * @param mode The Mode of the Subscription
     * @param options Additional Options.
     */
    subscribe(observer: NopePartialObserver<G> | observableCallback<G>,
        mode?: 'immediate' | 'sync',
        options?: nopeSubscriptionOptions): nopeObserver<G>

    /**
     * Create an enhanced Subscription of the Observable. Use the Pipes, to 
     * Define what should be subscribed.
     * @param next The Next Function, used to transmit changes
     * @param options The Options, used to determine the Enhancements.
     */
    enhancedSubscription<K>(next: (data: K) => void, options?: {
        scope?: { [index: string]: any },
        pipe?: pipe<T | G, K>
    }): Subscription

    /**
     * Creates a Subscription for the value of the Observable. After one Update the Value will be deleted 
     * @param func Function which is called when new Datas are pushed
     * @param mode Mode of the Subscription
     * @param options Additional Options
     */
    once(func: observableCallback<G>, mode?: 'sync' | 'immediate', options?: nopeSubscriptionOptions): nopeObserver<G>

    /**
     * Async Function to Wait for an Update
     * @param mode Mode of the Subscription
     * @param options Additional Options for the Wait Function.
     */
    waitFor(testCallback: waitForCallback<G>, options?: nopeWaitForOptions): Promise<G>

    /**
     * Async Function to Wait for an Update
     * @param mode Mode of the Subscription
     * @param options Additional Options for the Wait Function.
     */
    waitForUpdate(mode?: 'sync' | 'immediate', options?: nopeSubscriptionOptions): Promise<G>

    /**
     * Flag, showing if there exists any subscription this particular observer.
     */
    readonly hasSubscriptions: boolean;
}