simple-bound/dist/types/binding.d.ts

A simple and customizable reactive data-binding library.

/**
 * Defines a role of a subscriber.
 *
 * 'master' -> updates all masters & all slaves.
 *
 * 'slave' -> does not update any subscriber.
 */
export declare type SubscriberRole = 'slave' | 'master';
/**
 * An internal interface for storing the subscribers
 */
export interface ISubscriber<T extends object = object> {
    /**
     * Stores a reference to subscribed object
     */
    obj: T;
    /**
     * Stores a key by which the subscribed property is get
     */
    prop: string | number;
    /**
     * The role of a subscriber
     *
     * 'master' -> updates all masters & all slaves (two-way bindings).
     *
     * 'slave' -> does not update any subscriber (one-way bindings).
     */
    role?: SubscriberRole;
}
/**
 * A type for a general Binding plugin function
 */
export declare type IBindingPlugin<T = any> = (value: T, action: {
    type: 'get' | 'set';
    subscribers: ISubscriber[];
}) => void;
/**
 * Responsible for binding objects' properties together, storing their values inside and updating subscribers.
 *
 * It helps to manipulate bindings on the lowest possible level.
 *
 * It only binds a SINGLE property at a time!
 *
 * @template T captures a type of property to bind. Once the class is initialied - only properties of types that extend T are allowed for binding.
 */
export default class Binding<T = any> {
    readonly twoWay: boolean;
    protected value: T;
    readonly plugins?: IBindingPlugin<T>[] | undefined;
    /**
     * Responsible for executing the plugins synchronyously,
     *
     * @param type describes the type of action to be transmitted to a plugin
     */
    private callPlugins;
    /**
     * Adds a subscriber to the list of subscribers.
     *
     * @param subscriber to add
     */
    protected bind(subscriber: ISubscriber): ISubscriber<object>;
    /**
     * Stores subscribers for further manipulations.
     */
    readonly subscribers: ISubscriber[];
    /**
     * Creates an instance of Binding.
     * @param twoWay defines if a binding should always be 2-way and ignore roles.
     * @param value initial value to assign to slave bindings.
     * @param [plugins] to call on events.
     */
    constructor(twoWay: boolean, value: T, plugins?: IBindingPlugin<T>[] | undefined);
    /**
     * A generic get function that is applied to subscribers.
     *
     * Can also be used to get the current binding value.
     */
    get(): T;
    /**
     * A generic set function that is applied to subscribers.
     *
     * Can also be used to set the current binding value.
     */
    set(newValue: T): void;
    /**
     * Asynchroniously notifies the subscribers about the value change.
     *
     * @param newValue is the value to set to subscribers' properties.
     */
    notify(newValue: T): Promise<{}>;
    /**
     * Binds an object prop and subscribes it to master-subscribers' changes
     *
     * @param obj is an object to take the value from.
     * @param prop key to get the value by.
     * @param role a role to give to the subscriber.
     */
    addSubscriber<B extends object>(obj: B, prop: Exclude<keyof B, symbol>, role?: SubscriberRole): any;
    /**
     * Binds an object prop as a master and subscribes it to master-subscribers' changes
     *
     * @param obj is an object to take the value from.
     * @param prop key to get the value by.
     */
    addMasterSubscriber<B extends object>(obj: B, prop: Exclude<keyof B, symbol>): any;
    /**
     * Binds an object prop as a slave and subscribes it to master-subscribers' changes
     *
     * @param obj is an object to take the value from.
     * @param prop key to get the value by.
     */
    addSlaveSubscriber<B extends object>(obj: B, prop: Exclude<keyof B, symbol>): any;
    /**
     * Unbinds an object's property and unsubscribes it from changes.
     *
     * @param obj is an object to find the value in.
     * @param prop key to get the value by.
     */
    removeSubscriber<B extends object>(obj: B, prop: Exclude<keyof B, symbol>): this;
    /**
     * Unbinds an object's property and unsubscribes it from changes.
     *
     * @param index an index to find the subscribber by.
     */
    removeSubscriber(index: number): this;
    /**
     * Clears all subscribers from the binding.
     */
    clearSubscribers(): this;
    /**
     * Global binding config. Changes affect all instances.
     */
    static readonly config: import("./config").IConfig;
    /**
     * Checks subscribers' objects for reference equality.
     */
    static readonly subscriptionsEqual: (src1: ISubscriber<object> | undefined, src2: ISubscriber<object> | undefined) => boolean;
}