Txsvc NPM | npm.io

TxSvc

A transactional state container for SPA applications

Who am I

TxSvc is a transactional state container for SPA applications like Angular & React. It relies on Typescript syntax for intercepting component calls and ZoneJS mechanism for tracking asynchronous activities. While using TxSvc inside Angular/React applications is simple you can also use TxSvc in any JavaScript application

Installation

$ npm install txsvc

Getting Started

First, define application state

interface AppState {
    counter: number
}

Then, define the store which manages a single aspect of the application state. In our case this is the counter field

class CounterStore {
    store = ServiceStore.create<AppState>("/", {
        counter: 0,
    });
    
    get state() {
        return this.store.getState();
    }
    
    @Transaction()
    inc() {
        this.store.update({
            counter: this.state.counter + 1,
        });
    }
    
    @Transaction()
    dec() {
        this.store.update({
            counter: this.state.counter - 1,
        });
    }
}

Then, create the backing appStore instance and register each store into it

const counterStore = new CounterStore();

const appStore = new AppStore<AppState>();
appStore.init([
    counterStore.store
]);

Inside your component you deal with a specific store instance (like, CounterStore) and forget about the backing appStore instance.

class ToolbarComponent {
    constructor(private counterStore: CounterStore){
    }
    
    onIncButtonClicked() {
        this.counterStore.inc();
    }
    
    onDecButtonClicked() {
        this.counterStore.dec();
    }
}

Other components can listen to the change event

class CounterComponent {
    constuctor(counterStore: CounterStore) {
        counterStore.subscribe(counter => {
            //
            //  Do something with the new counter
            //
        });
    }
}

The power of TxSvc resides inside the ability to compose actions from different stores

For example, we want to maintain a counter which counts the number of end user activities. Every time the user logs-in or logs-out we want to increment the activity counter

interface AppState {
    counters: CountersState,
    auth: AuthState,
}

interface AuthState {
    userName: string,
    roles: string[]
}

interface CountersState {
    activityCount: number;
}

class CountersStore {
    store = ServiceStore.create<AppState>("counters", {
        activityCount: 0,
    });
    
    get state() {
        return this.store.getState();
    }
    
    @Transaction()
    incActivity() {
        this.store.update({
            activityCount: this.state.activityCount + 1,
        });
    }
}

class AuthStore {
    store = ServiceStore.create<AuthState>("auth", {
        userName: null,
        roles: null,
    });
    
    @Transaction()
    login() {
        this.store.update({
            userName: "ori",
            roles: ["admin"]
        });
    }
    
    @Transaction()
    logout() {
        this.store.update({
            userName: null,
            roles: null
        });
    }
}

class RootStore {
    store = ServiceStore.create<AppState>("/", {
    });
    
    constructor(private countersStore: CountersStore, private authStore: AuthStore){
    }
    
    @Transaction()
    loginAndIncActivityCount() {
        this.authStore.login();
        this.countersStore.incActivity();
    }
}

const countersStore = new CountersStore();
const authStore = new AuthStore();
const rootStore = new RootStore();

const appStore = new AppStore<AppState>();
appStore.init([
    rootStore.store
    counterStore.store
    counterStore.store
]);

Only if both inc() and login() complete successfully then the backing appStore is updated and all subscribers are notified

TxSvc support asynchronous operations. Continuing with above example we can return a promise from an action and the transaction decorator will monitor the completeness of the action and only then will update the backing appStore

@Transaction(): Promise<void>
loginAndIncActivityCount() {
    return Promise.resolve()
        .then(()=>this.couterStore.inc())
        .then(()=>this.authStore.login());
}

Or, in case you are using async/await syntax

@Transaction(): Promise<void>
async loginAndIncActivityCount() {
    await this.couterStore.inc();
    await this.authStore.login();
}

Samples

Inside the repository you may find the samples directory which contains samples for both Angular1 and Angular2. Just run the following commands inside each directory sample