react-wormhole-hoc
A better alternative to react context.
Motivations
Context is a very powerful feature in React, but it may get you into trouble sometimes.
See these issues for detail:
- https://medium.com/@mweststrate/how-to-safely-use-react-context-b7e343eff076
- https://github.com/facebook/react/issues/2517
Features
- Works well with
shouldComponentUpdate
andReact.PureComponent
- No namespace conflict
- Works well outside React Component
- Can communicate without parent-child relationship
Quick Start
;; const storeWormhole = content: '...' const fetchData = ; @storeWormhole static propTypes = myStore: PropTypesobject ; { return <div> content: thispropsmyStorecontent </div> ; } { // no update return false; } { return <DeepChild /> ; } { ; } { return <NoUpdate /> ; }
For more usage, please check the ./example
directory, or clone this repo and run npm run example
to start live demo.
API
constructor(initialValue)
Create wormhole instance.
Arguments
- initialValue (Any): Initial value.
Return
(Wormhole): wormhole
instance.
get()
Get current value. Will emit an get
event.
Return
(Any): Value.
set(newValue)
Set new value. Will emit an set
event. If the newValue
is different with the old value, it will also emit an change
event.
Arguments
- newValue (Any)
on(event, handler)
Listen for a custom event on the current instance.
Arguments
- event (String): Event type.
- handler (Function): Event handler.
Return
(Function): off.
once(event, handler)
Listen for a custom event, but only once.
Arguments
- event (String): Event type.
- handler (Function): Event handler.
Return
(Function): off.
off([event, handler])
Remove event listener(s).
Arguments
- event (String): Event type.
- handler (Function): Event handler.
hoc(propName)
Create React HOC.
Arguments
- propName (String): Inject this value as
prop
.
Return
(Function): A HOC creator function.
Example
Basic usage:
;; const myWormhole = 'awesome!!1'; static propTypes = myValue: PropTypesstring ; { return <h1>thispropsmyValue</h1> ; } const hoc = myWormhole;App;
With transform-decorators-legacy babel plugin:
@myWormhole // the same with above...
static connect(mapProps[, options])
Connect some wormholes to a HOC.
Arguments
- 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.
Available options:
- 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:[]
.
Example
Basic usage:
@Wormhole static propTypes = hello: PropTypesstring world: PropTypesstring ; { const hello world = thisprops; return <h1>hello world</h1> ; }
With methods
:
@Wormhole static propTypes = counter: PropTypesnumber increase: PropTypesfunc ; { const counter increase = thisprops; return <div> <p>counter</p> <button onClick=increase /> </div> ; }
<Provider wormholes />
static 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.
Props
- wormholes (Object): A key/value object of
wormholes
. - children (ReactElement): The root of your component hierarchy.
Example
;;;; @Wormhole static propTypes = page: PropTypesobject ; { const page = thisprops; return <div>page</div> ; } const MyRootComponent = <App />; const wormholes = page: {} isFetching: false errorMessage: ''; ReactDOM;
Return
(Function): A HOC creator function.
Installing
Using npm:
npm install --save react-wormhole-hoc
Using yarn:
yarn add react-wormhole-hoc
Dependencies
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.
Related Projects
License
MIT © Cap32