loxe v0.5.0
Loxe
Flux architecture incorporates FRP library implementation. Observable is awesome!
- The main purpose is mapping the Observables to props of the component
- Design with a focus on ES6-7.
- Using the Higher-order Components with decorator instead of Mixin.
- To follow the ES Observable Proposal to the
Subject
. - Wherever possible, declarative statements should be.
Installation
Recommend for use browserify, or other CommonJS/ES6 modules resolver.
Use browserify
To install the loxe
by NPM.
npm install --save loxe
// CommonJS
var Loxe = require('loxe');
// ES6 modules (babel)
import Loxe from 'loxe';
# Loxe depends on React. If you want to separate `react` as other bundle.
browserify index.js -x react -o bundle.js
browserify -r react -o libs.js
Use <script src="loxe.js">
loxe.js
built with browserify-shim. To run the Loxe window.React
is required.
<script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.13.3/react.js"></script>
<script src="loxe.js"></script>
Usage
Flux comparison example
Minimal Example
Domain
that manages the Store
and Action
. Each feature of Flux provides to Component
, using the Context feature of the React.
Loxe uses javascript-decorators for the component. TypeScript or Babel with --stage 1
option, use recommended. (As a function Root = provideContext(Root);
you might also use)
import { Domain, Store, Action, Subject } from 'loxe';
class AppDomain extends Domain {
getObservables() {
// Object returns that will provide to components, through `@provideObservables`.
return {
items$ : this.getStore(AppStore).items$,
count$ : this.getStore(AppStore).items$.map(a => a.length)
};
}
}
class AppAction extends Action {
addItem(item) {
// `.publish()` is like a dispatch of the Flux.
// By event name published here, you can subscribe from the Store.
this.publish('ADD_ITEM', item);
}
}
class AppStore extends Store {
constructor() {
super();
// init data storage property
this._items = [];
// create Observable that keep latest value. (like `Rx.BehaviorSubject`)
this.items$ = Subject.property(this._items);
// `.plugStream$` is Observable, and `{event: string, payload: any}`
// will be published from the `Action` will be aggregated.
// `.subscribeEvent(event, observer)` subscribe to Observable
// that from plugStream filtered by events.
this.subscribeEvent('ADD_ITEM', (item) => {
this._items.push(item);
this.items$.next(this._items);
});
}
}
// Becoming a root Component, `@provideContext` Decorator is required.
// It connects components Tree Root and Flux.
@provideContext()
class Root extends React.Component {
render() {
return <Child />;
}
}
// @provideAction: Inject Action instance to the component props.
// @provideObservables: Value of the Observable will be provided
// from the domain mapped to the props.
@provideAction([AppAction])
@provideObservables(observables => ({
items : observables.items$
}))
class Child extends React.Component {
addItem() {
this.props.AppAction.addItems({data: Date.now()});
}
render() {
return (
<div>
<button onClick={this.addItem.bind(this)}>add item</button>
<ul>
{this.props.items.map(item => <li>{item.data}</li>)}
</ul>
</div>
);
}
}
const appDomain = new AppDomain();
appDomain.registerAction(new AppAction());
appDomain.registerStore(new AppStore());
appDomain.mountRootComponent(Root, document.getElementById('app'));
Choose FRP library
At first, you MUST sets the FRP (Functional Reactive Programming) library, used internally by the Subject
.
import Rx from 'rx-lite';
import rxCombineTemplate from 'rx.observable.combinetemplate';
import { Subject } from 'loxe';
Subject.setBuilder(new Subject.RxBuilder(Rx));
Subject.setCombineTemplate(rxCombineTemplate);
Supported Reactive-Extensions/RxJS and rpominov/kefir.
import Kefir from 'kefir';
import kefirCombineTemplate from 'kefir.combinetemplate';
import { Subject } from 'loxe';
Subject.setBuilder(new Subject.KefirBuilder(Kefir));
Subject.setCombineTemplate(kefirCombineTemplate);
This is a transitional period for the future within fixed on either side.
API Reference
Action
Is the Action
of the flux. Implements the API from component to use imperative.
eventStream$: Subject
All events will be published through this stream. During the initialization phase of the Domain
, is connected with the Store#plugStream$
.
publish(event: string, payload: any)
Publish event data. It's a this.eventStream$.next({event, payload})
an equivalent process.
do(event: string, payload: any)
Alias of publish()
.
Domain
Domain
that manages the Store
and Action
. Each feature of Flux provides to Component
, using the context of the React.
registerAction(action: Action)
Register Action
instance.
registerStore(store: Store)
Register Store
instance.
mountRootComponent(root: Component, container: Element)
Mount root component at node, and connect domain contexts as props. root
Component should applied @provideContext
decorator.
getObservables(): object
This method called '@provideObservables'. You need to maintain their own when returning this object is not cached, so consistently reuses.
getObservables() {
if (!this.observables$) {
this.observables$ = {
items$ : this.getStore(Store).items$,
count$ : this.getStore(Store).items$.map(a => a.length)
};
}
return this.observables$;
}
Store
Is the Store
of the flux. Store
some Observable publishes the Domain
.
plugStream$: Subject
plugStream$
is Observable, and {event: string, payload: any}
will be published from the Action
will be aggregated.
Without subscribing to it directly, usually using either of the following methods.
getEvent(event: string): Observable
subscribe(target: Observable, callback: Function)
subscribeEvent(event: string, callback: Function)
These methods generate an Observable filtered in any event from the plugStream$
or, to subscribe to it. Look at the following example.
// example
constructor() {
super();
// You want to combine multiple events useful 'getEvent()'.
let foo$ = this.getEvent('foo');
let bar$ = this.getEvent('bar');
this.subscribe(foo$.merge(bar$), v => console.log(v));
// 'subscribeEvent()' useful if you only subscribe to one type of event.
this.subscribeEvent('baz', v => console.log(v));
}
Subject
Creates an object with both Observable and Observer roles. That object behave like Rx.BehaviorSubject
, Bacon.Bus
, and Kefir.Bus
(deprecated).
Objects that are generated by subject can be used on the function of next()
. Useful when combining multiple event streams, controlling the UI.
componentWillMount() {
this.clickStream$ = Subject.stream();
this.clickStream$.subscribe(e => {
console.log(e); // -> [SyntheticEvent]
});
}
render() {
return <button onClick={this.clickStream$}>click me</button>;
}
Subject.setBuilder(builder: Rxbuilder|KefirBuilder)
Set instance of Subject.RxBuilder
or Subject.KefirBuilder
. Select FRP library you want to use.
Subject.setCombineTemplate(combineTemplate: Function)
Set function of rx.observable.combinetemplate or kefir.combinetemplate. Use when mapping the Observables to prop of the component.
Subject.stream(): Subject
To create standard Subject
object. Value issued only after starting to subscribe.
let stream$ = Subject.stream();
stream$.next(100);
stream$.subscribe(v => console.log(`Log: ${v}`));
stream$.next(200);
// => Log: 200
Subject.property(): Subject
To create Subject
object that keeps latest value. Latest value is issued immediately when started to subscribe.
let property$ = Subject.property();
property$.next(100);
property$.subscribe(v => console.log(`Log: ${v}`));
property$.next(200);
// => Log: 100
// => Log: 200
next(value: any)
A common interface with the subject. Notifies the subject of a new element in the sequence.
throw(error: Error)
A common interface with the subject. Notifies the subject that an error has occurred.
return()
A common interface with the subject. Notifies the subject of the end of the sequence.
Providers
Providers are implemented as decorators. But also support to normally functional use.
// decorators
@provideXyz()
class MyComponent extends React.Component { }
// normally function
class MyComponent extends React.Component { }
MyComponent = provideXyz(MyComponent);
@provideContext()
@provideContext
provides getAction()
and getObservables()
from props.domain
in the context of the React.Component.
These methods are used in the @provideAction
or @provideObservables
, component tree and Store
and the Action
is associated.
@provideActions(Actions: Action[])
Inject Action instance to the component props.
@provideActions([FooAction, BarAction])
class MyComponent extends React.Component {
doFoo() {
this.props.FooAction.foo();
}
doBar() {
this.props.BarAction.bar();
}
}
@provideObservables
Value of the Observable will be provided from the Domain
mapped to the this.props
.
@provideObservables(observables => ({
items : observables.items$,
count : observables.items$.map(items => items.length),
navigate : {
current : observables.page$,
prev : observables.page$.map(v => v-1),
next : observables.page$.map(v => v+1)
}
}))
class MyComponent extends React.Component {
render() {
return (
<ul>
{this.props.items.map(item => <li>{item.name}</li>)}
</ul>
<p>count: {this.props.count}</p>
<p>current: {this.props.navigate.current}</p>
<p>prev: {this.props.navigate.prev}</p>
<p>next: {this.props.navigate.next}</p>
);
}
}
@provideSideEffect()
Components that use this Decorator is to control the adverse effects of global available props
@provideSideEffect()
class MyComponent extends React.Component {
static handleSideEffect(propsList) {
let someOneVisible = propsList.some(props => props.isVisible);
let htmlElement = document.body.parentNode;
if (someOneVisible) {
htmlElement.classList.add('is-some-one-visible');
} else {
htmlElement.classList.remove('is-some-one-visible');
}
}
}
Tests
npm install
npm test
Contributing
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature
- Commit your changes:
git commit -am 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request :D
License
MIT
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago