A better alternative to react context.
THIS REPO WILL NOT BE MAINTAINED ANY MORE. Because the Official Context API in React v16.3 is the better one.
Context is a very powerful feature in React, but it may get you into trouble sometimes.
See these issues for detail:
- Works well with
shouldComponentUpdate
andReact.PureComponent
- No namespace conflict
- Works well outside React Component
- Can communicate without parent-child relationship
import React, { Component, PropTypes } from "react";
import Wormhole from "react-wormhole-hoc";
const storeWormhole = new Wormhole({ content: "..." });
const fetchData = () =>
new Promise(resolve =>
setTimeout(() => resolve({ content: "awesome!!1" }), 1000)
);
@storeWormhole.hoc("myStore")
class DeepChild extends Component {
static propTypes = {
myStore: PropTypes.object
};
render() {
return <div>content: {this.props.myStore.content}</div>;
}
}
class NoUpdate extends Component {
shouldComponentUpdate() {
// no update
return false;
}
render() {
return <DeepChild />;
}
}
class App extends Component {
componentDidMount() {
fetchData("/fake/api").then(store => {
storeWormhole.set(store);
});
}
render() {
return <NoUpdate />;
}
}
For more usage, please check the ./example
directory, or clone this repo and run npm run example
to start live demo.
Create wormhole instance.
- initialValue (Any): Initial value.
(Wormhole): wormhole
instance.
Get current value. Will emit an get
event.
(Any): Value.
Set new value. Will emit an set
event. If the newValue
is different with the old value, it will also emit an change
event.
- newValue (Any)
Listen for a custom event on the current instance.
- event (String): Event type.
- handler (Function): Event handler.
(Function): off.
Listen for a custom event, but only once.
- event (String): Event type.
- handler (Function): Event handler.
(Function): off.
Remove event listener(s).
- event (String): Event type.
- handler (Function): Event handler.
Create React HOC.
- propName (String): Inject this value as
prop
.
(Function): A HOC creator function.
Basic usage:
import React, { Component, PropTypes } from "react";
import Wormhole from "react-wormhole-hoc";
const myWormhole = new Wormhole("awesome!!1");
class App extends Component {
static propTypes = {
myValue: PropTypes.string
};
render() {
return <h1>{this.props.myValue}</h1>;
}
}
const hoc = myWormhole.hoc("myValue");
export default hoc(App);
With transform-decorators-legacy babel plugin:
@myWormhole.hoc("myValue")
export default class App extends Component {
// the same with above...
}
Connect some wormholes to a HOC.
- mapProps (Object|Function): Define a key-value object to
props
. Avalue
should be awormhole
instance or a function. If avalue
is a type ofString
,Number
,Boolean
,Array
or a plain Object, it would be converted towormhole
instance. - options (Object): See below for detail.
- isPure (Boolean): Use
pureComponent
or not. Default value:true
. - withRef (Boolean): If true, stores a ref to the wrapped component instance and makes it available via
getWrappedInstance()
method. Default value:false
. - hoistMethods ([String]): Copies wrapped component instance methods to HOC instance. Make sure set
withRef: true
first. Default value:[]
.
Basic usage:
@Wormhole.connect({
hello: "hello",
/* or: */
// hello: new Wormhole('hello'),
world: "world"
})
class App extends Component {
static propTypes = {
hello: PropTypes.string,
world: PropTypes.string
};
render() {
const { hello, world } = this.props;
return (
<h1>
{hello} {world}
</h1>
);
}
}
With methods
:
@Wormhole.connect({
counter: 1,
increase(ev) {
ev.preventDefault();
this.counter.set(this.counter.get() + 1);
}
})
class App extends Component {
static propTypes = {
counter: PropTypes.number,
increase: PropTypes.func
};
render() {
const { counter, increase } = this.props;
return (
<div>
<p>{counter}</p>
<button onClick={increase} />
</div>
);
}
}
Makes the wormholes
available to the connect() calls in the component hierarchy below. It's useful when using server-side rendering. See below example for detail.
- wormholes (Object): A key/value object of
wormholes
. - children (ReactElement): The root of your component hierarchy.
import React from "react";
import ReactDOM from "react-dom";
import Wormhole, { Provider } from "react-wormhole-hoc";
import MyRootComponent from "./MyRootComponent";
@Wormhole.connect(wormholes => ({
// `wormholes` is provided by `<Provider>`.
page: wormholes.page
}))
class App extends Component {
static propTypes = {
page: PropTypes.object
};
render() {
const { page } = this.props;
return <div>{page}</div>;
}
}
const MyRootComponent = () => <App />;
const wormholes = {
page: {},
isFetching: false,
errorMessage: ""
};
ReactDOM.render(
<Provider wormholes={wormholes}>
<MyRootComponent />
</Provider>,
rootEl
);
(Function): A HOC creator function.
Using npm:
npm install --save react-wormhole-hoc
Using yarn:
yarn add react-wormhole-hoc
react-wormhole-hoc
has very few dependencies and most are managed by NPM automatically.
However the following peer dependencies must be specified by your project in order to avoid version conflicts:
react
,
react-addons-shallow-compare
, and
NPM will not automatically install these for you but it will show you a warning message with instructions on how to install them.
MIT © Cap32