Compose props reactively for FrintJS Apps
npm install frint-props
> Compose reactive props for FrintJS Apps
- Guide
- Installation
- Concepts
- Usage
- Write your own functions
- API
- withDefaults
- withState
- withStore
- withObservable
- withHandlers
- compose
- map
- pipe
- shouldUpdate
---
With npm:
``
$ npm install --save rxjs frint-props
Via unpkg CDN:
`html
`
The package consists of multiple functions that enable you to compose your props as an RxJS Observable.
There are two kinds of functions:
1. That adds new props to the stream
1. That processes the props stream further (like RxJS operators)
And then there is compose function that accepts both kinds of functions as arguments, and returns a single function that you can use anywhere.
We can start small, and prepare a stream that only emits the props once, and it doesn't change over time:
`js
import { withDefaults } from 'frint-props';
const defaultProps = {
foo: 'foo value',
};
const props$ = withDefaults(defaultProps)();
`
Now that we have the Observable available as props$, we can subscribe to it as needed:
`js`
props$.subscribe(props => console.log(props));
But we have more real world use cases that require our props to change over time too. We can consider using withState for this example:
`js
import { withState } from 'frint-props';
const props$ = withState('counter', 'setCounter', 0)();
`
Now the props$ Observable will emit an object with these keys:
* counter (Integer): The counter valuesetCounter(n)
* (Function): Call this function to update counter value
You can compose multiple functions together to generate a combined stream of all props. For that, we can use the compose function:
`js
import { compose, withDefaults, withState } from 'frint-props';
const props$ = compose(
withDefaults({ foo: 'bar' }),
withState('counter', 'setCounter', 0),
withState('nane', 'setName', 'FrintJS')
)();
`
The props$ Observable will now emit with an object with these keys:
* foo (String)counter
* (Integer)setCounter(counter)
* (Function)name
* (String)setName(name)
* (String)
As you call functions like setCounter or setName, it will emit a new object with updated values for counter and name.
Besides adding just props, you may also need to process the stream further.
For example, you may want to control how often the Observable emits new values. We can use shouldUpdate function for this:
`js
import { compose, withDefaults, withState, shouldUpdate } from 'frint-props';
const props$ = compose(
withDefaults({ counter: 0 }),
withState('counter', 'setCounter', 0),
shouldUpdate((prevProps, nextProps) => {
return prevProps.counter !== nextProps.counter;
})
)();
`
The implementation of shouldUpdate above tells our props$ Observable to emit new values only if the counter value has changed. Otherwise nothing new is emitted.
The API of creating your own functions is pretty simple.
A basic function that is concerned about adding new props can be written like this:
`js`
function withFoo() {
return function () {
return {
foo: 'foo value here',
};
};
}
You can also return an Observable instead of a plain object:
`js
import { of } from 'rxjs/observable/of';
function withFoo() {
return function () {
return of({
foo: 'foo value here',
});
};
}
`
You would notice that instead of returning the Object/Observable directly from our function, we return another function which takes care of returning the final result.
This allows us to access additional arguments when composing props.
Imagine if we want to make the FrintJS app instance available to our functions:
`js
const app = new App();
const props$ = compose(
withFoo()
)(app);
`
The argument app can now be accessed inside our function like this:
`js`
withFoo() {
return function (app) {
return {
foo: 'foo value here',
};
};
}
The way some of our functions are designed in this repository, the returned functions expect to receive the same arguments as our observe higher-order component receives in frint-react, which are: app and parentProps$.
Besides just adding new props, functions can also take care of processing the stream further just like how RxJS operators work.
We can create a function that will check if there is any foo prop, and then capitalize it:
`js
import { map } from 'rxjs/operators/map';
function capitalizeFoo() {
return function () {
return map((props) => ({
...props,
foo: props.foo
? props.foo.toUpperCase()
: undefined,
}));
};
}
`
Can be composed together as follows:
`js
import { compose } from 'frint-props';
const props$ = compose(
withFoo(),
capitalizeFoo()
);
`
The props$ Observable will now emit { foo: 'FOO VALUE HERE' }.
---
All the functions return a function, when called, returns an Observable of props.
> withDefaults(defaultProps)
1. defaultProps: Default props to start the stream with
`js`
const props$ = withDefaults({ foo: 'foo value here' })();
> withState(valueName, setterName, initialValue)
1. valueName (String): Prop name for the valuesetterName
1. (String): Prop name for the setter functioninitialValue
1. (any): Initial value for the state
`js`
const props$ = withState('counter', 'setCounter', 0)();
> withStore(mapState, mapDispatch, options = {})
Works with frint-store or Redux store set in FrintJS App as a provider.
1. mapState (Function OR null): Maps state to propsmapDispatch
1. (Object): Action creators keyed by namesoptions
1. (Object) [optional]: Object with additional configurationoptions.providerName
1. (String): Defaults to store
1. (String): Defaults to null, otherwise name of any Child App
`jsstore
const app = new App(); // assuming it has a provider
const mapState = state => ({
foo: state.foo,
bar: state.bar
});
const mapDispatch = {
handleClick: () => ({
type: 'HANDLE_CLICK'
})
};
const props$ = withStore(mapState, mapDispatch)(app);
`
You can also pass null in place of mapState parameter if you don't want to subscribe to store updates.
`jsstore
const app = new App(); // assuming it has a provider
const mapDispatch = {
handleClick: () => ({
type: 'HANDLE_CLICK'
})
};
const props$ = withStore(null, mapDispatch)(app);
`
> withObservable(source$, ...mappers)
1. source$ (Observable OR function returning Observable)mapper
2. (Function): Returning props OR Observable of props
`js
import { of } from 'rxjs/observable/of';
const props$ = withObservable(
of({ foo: 'foo value here' }),
props => ({ foo: props.foo.toUpperCase() }),
props => ({ foo: ${props.foo}! })`
)();
Generated from a function:
`js
import { of } from 'rxjs/observable/of';
const props$ = withObservable(
() => of({ foo: 'foo value here' })
)();
`
> withHandlers(handlers)
This function can be only used via compose.
* handlers (Object): Functions keyed by prop name
`js`
const props$ = compose(
withHandlers({
handleClick: props => () => console.log('Clicked!')
})
)();
Other props are accessible too:
`js`
const props$ = compose(
withState('counter', 'setCounter', 0),
withHandlers({
increment: props => () => props.setCounter(props.counter + 1)
})
)();
Additional arguments can be accessed as follows:
`js`
const props$ = compose(
withHandlers({
handleClick: (props, arg1, arg2) => () => console.log('Clicked!')
})
)(arg1, arg2);
> compose(...functions)
Composes multiple functions into a combined single function, that can be called later.
`js`
const props$ = compose(
withDefaults({}),
withState('counter', 'setCounter', 0),
withState('name', 'setName', 'FrintJS'),
shouldUpdate((prevProps, nextProps) => true)
)();
> map(mapperFn)
1. mapperFn (Function): Function that accepts processed props, and returns new mapped props object
`js`
const props$ = compose(
withDefaults({ foo: 'foo value' }),
map(props => ({ foo: props.foo.toUpperCase() }))
)();
Will emit { foo: 'FOO VALUE' }.
> pipe(operator)
Pipes with any RxJS operator.
1. operator (Function): RxJS operator
`js
import { map } from 'rxjs/operators/map';
const props$ = compose(
withDefaults({ foo: 'foo value' }),
pipe(map(props => ({ foo: props.foo.toUpperCase() })))
)();
`
> shouldUpdate((prevProps, nextProps) => true)
Controls when to emit props.
1. Function`: receives previous and next props, and should return a Boolean deciding whether to update or not