Intruduction

This will help to receive a specific property change updates in your program. This package will help to handle the registration of the interest and also communication of the changes.

Getting Started

Context

Lets assume that we are developping a travel portel and we want to disable the new reservations if the payment module is down. Instead of checeking everytime before presenting the page, we can register as observer with payment module. Based on last received status, we can decide on enable/disable the option

We can have multiple observers for receiving updates. We may also have the travel insurance module, which also needs payment service. We can register that also for the PaymentService Updates

This will have following classes to help with the same

Observer Observer that is interested in updates

Observable Observable, maintain observer registration and handles update communication

ObservableProperty Extends Observable and manages a single property

ObservableStatus Same as ObservableProperty, specialized for status

ObservableProperties Helps to manage multiple properties

Setup

Use standard NPM installation command to install @oprasad/observer from command prompt. Alternatively you can install oprasad, that will include this also. 

*
    npm install --save @oprasad/observer
*

Observer

Observer is the one who is interested in changes in other module/class. In this case it will be booking module. any class can implement IObserver interface to receive updates. The class will have to implement handleUpdate 

API

The Observer interface has following API to be implemented in subclasses

public handleUpdate(observable: Observable, property: string, value: any)

Handle the property change to value received from observable

import

IObserver has to be imported in the Observer calss
*
    import {IObserver} from 'oprasad/lib/observer/IObserver'
*

Implement

Implement IObserver interface in the observer class. Register with Observable(PaymentService in this case) for status change update
*
    class RegistrationService implements IObserver{
        constructor(){
            //register with payment service
            PaymentService.register(this);
            //any other initialization
        }
        public handleUpdate(observable: Observable, property: string, value: any) {
            console.log('Received ' + property + ' property change to ' + value + ' from ' + observable)
            //code required to enable/disable reservations
        }
    }
*

alternatively we can choose to have Observer variable inline implementation
*
    let allObserver = {} as IObserver;
    allObserver.handleUpdate = (observableReceived: Observable, property: string, value: any) => {
        console.log('Received ' + property + ' property change to ' + value + ' from ' + observable)
        //code required to enable/disable reservations
    }   
    
    //register with payment service
    PaymentService.register(allObserver);
*

Observable

Observable class will have all the mechanism for register observers and communication of updates. The PaymentService can extend the same to communicate updates

API

The Observable will have following API to be register observers and communicate

public register(observer : IObserver)

Register the observer for property updates

public unregister(observer : IObserver)

UnRegister the observer  

public communicate(property : string, value : any)

Inform the observers that property has changed to value

import

The class maintaining the observable property has to be imported in the Observable calss
*
    import {Observable} from '@oprasad/observer'
*

Usage

There are two ways to create Observable class.

extend Observable

Extend the Observable and implement the observer(PaymentService in this case) class
*
    class PaymentService extends Observable{
        //Paymentservice implementation
    }
*

Communicate

Whenever there is any change in the status, observer(PaymentService in this case) has to communicate to all the observers through communicate method
*
    class PaymentService extends Observable{
        status : string;
        public updateStatus(status : string) {
            this.status = status
            //any other code needed to handle status change
            this.communicate(this, 'Status', this.status);
        }

        //all otrher payment service code
    }
*

Observable as variable

If the observable is already extending for other base class, we can proceed as variable. The PaymentService can maintain the Observable variable and all the related methods has to be implemented to redirect to observable
*
    class PaymentService extends Observable{
        observable : Observable;
        status : string;
        constructor(){
            //initialize Observable
            observable = new Observable();
            //any other initialization like status etc
        }
        public register(observer){
            observable.register(observer);
        }
        public unregister(observer){
            observable.unregister(observer);
        }
        public updateStatus(status : string) {
            this.status = status
            //any other code needed to handle status change
            observable.communicate(this, 'Status' this.status);
        }

        //all otrher payment service code
    }
*

ObservableProperty

ObservableProperty will relieve you from maintaining the property(status in this case). This also gives additional functionality to register only for specific status instead of receiving all updates. This also can be used similar to Observer with following changes 

API

The ObservableProperty will extend [Observable](#observable) and have following additional API for property specific registrations

public register(observer : IObserver, value ?: any)

Register the observer for specific property value. Observer will be informed only when property value changes to this value
If the value is not defined, observer will be informed every time the property changes

public unregister(observer : IObserver, value ?: any)

UnRegister the observer 

public setProperty(value : any)

set the property value to the input value. THis will automatically trigger the communication to observers based on registration

public getProperty() : any

returns current value of the property

import

The class maintaining the observable property has to be imported in the ObservableProperty calss
*
    import {ObservableProperty} from '@oprasad/observer'
*

Usage

ObservableProperty constructor will take property name and optional initial value as inputs. This will help to store the property name to communicate to the observers. Observers will be informed only if there is a change in status
*
    class PaymentService extends ObservableProperty{
        constructor(){
            //initialize ObservableProperty with initial value of status as Active
            super('Status', 'Active');

            //any other initialization like status etc
        }
        //all otrher payment service code
    }
*

Property Updates

ObservableProperty has set and get methods for the class to update/access the property. When ever the property modified through setProperty method, all the observers will be communicated based on their registration
*
        public updateStatus(status : string) {
            //any other code needed to handle status change
            super.setProperty(status);
        }
*

Observer registration

Observer can register to all the updates similar to Observable. Apart from that ObservableProperty provides option to register for a specific value
*
    let activeObserver = {} as IObserver;
    activeObserver.handleUpdate = (observableReceived: Observable, property: string, value: any) => {
        console.log('Received ' + property + ' property change to ' + value + ' from ' + observable)
        //code required to enable reservations
    }   
    //register with payment service
    PaymentService.register(activeObserver, 'Active');

    let downObserver = {} as IObserver;
    downObserver.handleUpdate = (observableReceived: Observable, property: string, value: any) => {
        console.log('Received ' + property + ' property change to ' + value + ' from ' + observable)
        //code required to disable reservations
    }        
    //register with payment service
    PaymentService.register(downObserver, 'Down');
*

ObservableStatus

This is just a specific extension of ObservableProperty. Most of the times, we will have status as observable property. So this gives some convinience methods

API

The ObservableProperty will extend [ObservableProperty](#observableproperty) and have following additional API for property specific registrations 

public setStatus(value : string)

set the status to the input value. THis will automatically trigger the communication to observers based on registration

public getStatus() : strring

returns current status 

import

The class maintaining the status has to be imported in the ObservableStatus calss
*
    import {ObservableStatus} from '@oprasad/observer'
*

Usage

ObservableStatus can be instantiated with out property name. Use setStatus and getStatus methods instead of corresponding Property methods
*
    class PaymentService extends ObservableStatus{
        constructor(){
            //initialize ObservableStatus with initial value of status as Active
            super('Active');

            //any other initialization like status etc
        }
        public updateStatus(status : string) {
            //any other code needed to handle status change
            super.setStatus(status);
        }
        //all otrher payment service code
    }
*

ObservableProperties

ObservableProperty will help to track only one property. What if we want to observe multiple properties. Lets assume that PaymentService uses some dynamic service charges. The registration service will be interested in both the status and also service charges.

One way to handle multiple properties is to have multiple ObservableProperties and have methods to manage them. Alternatively, ObservableProperties will help to maintain multiple properties and communicate to Observers according to their registration. This also gives additional functionality to register only for specific property and Property value instead of receiving all updates. This also can be used similar to Observer with following changes 

API

The ObservableProperty will extend [Observable](#observable) and have following additional API for property  and value specific registrations 

public register(observer : IObserver, property ?: string, value ?: any)

Register the observer for specific property and value. Observer will be informed only when the specific property value changes to this value. 

If the value is not defined, observer will be informed every time the specific property changes

If the property is not defined, observer will be informed of any property changes   

public unregister(observer : IObserver, property ?: string, value ?: any)

UnRegister the observer 

public addProperty(property : string, value : any){

Add a new property with initial value for monitoring

public removeProperty(property : string)

remove property from monitoring

public setProperty(property : string, value : any)

set the property value to the input value. THis will automatically trigger the communication to observers based on registration

public getProperty(property : string) : any

returns current value of the property

Usage

import

ObservableProperties has to be imported in the Observable class(PaymentService in this case)
*
    import {ObservableProperties} from '@oprasad/observer'
    class PaymentService extends ObservableProperties{
        //all other payment service code
    }
*

Adding the property to be observed

ObservableProperties has an interface to add and remove the properties to be onserved. The Observable class have to add the property before any registration for thgat property.
*
    class PaymentService extends ObservableProperties{
        constructor(){
            //initialize ObservableProperties 
            super();

            //add Status and ServiceCharges
            super.addProperty('Status', 'Active')'
            super.addProperty('ServiceCharges', '2%')'

            //any other initialization like status etc
        }
        //all other payment service code
    }
*

Property Updates

ObservableProperties has set and get methods for the class to update/access the property. The setProperty method takes both property name and value as inputs. When ever the property modified through setProperty method, all the observers will be communicated based on their registration
*
        public updateStatus(status : string) {
            //any other code needed to handle status change
            super.setProperty('Status', status);
        }
*

Observer registration

Observer can register to all the updates similar to Observable. Apart from that ObservableProperty provides option to register for a specific property and value
*
    let observer = {} as IObserver;
    observer.handleUpdate = (observableReceived: Observable, property: string, value: any) => {
        console.log('Received ' + property + ' property change to ' + value + ' from ' + observable)
        //code required to handle property change
    }   

    //register with payment service for all updates
    PaymentService.register(observer);

    //register with payment service for all status changes
    PaymentService.register(observer, 'Status');

    //register with payment service for only status changes to 'Active'
    PaymentService.register(observer, 'Status', 'Active');
*

Support

If you have any issues/suggesitions/feedback, please send a mail to [email protected]