Links

withEffects

Used to enhance a plain component, wrapping it in a WithEffects component which handles side-effects internally. It is a curried higher-order component.

Packages

withEffects is provided by our React, Inferno or Preact packages - refract-*, refract-inferno-*, refract-preact-*.

Signature

withEffects = (
aperture,
config: { handler?, errorHandler?, Context?, mergeProps?, decorateProps? }
) => BaseComponent => {
return WrappedComponent
}

Arguments

  1. 1.
    aperture (function): a function which observes data sources within your app, passes this data through any necessary logic flows, and outputs a stream of effect values in response.
    Signature: (component, initialProps, initialContext?) => { return effectStream }.
    • The component is an object which lets you observe your React, Inferno or Preact component: see Observing React
    • The initialProps are all props passed into the WrappedComponent.
    • The initialContext is the initial context value of the provided Context (see above, React >= 16.6.0 only)
    • Within the body of the function, you observe the event source you choose, pipe the events through your stream library of choice, and return a single stream of effects.
  2. 2.
    a config object optionally containing the following:
    1. 1.
      handler (function): an optional function which causes side-effects in response to effect values.
      Signature: (initialProps, initialContext?) => (effect) => { /* handle effect here */ }
      • The initialProps are all props passed into the WrappedComponent.
      • The initialContext is the initial context value of the provided Context (see below, React >= 16.6.0 only)
      • The effect is each value emitted by your aperture.
      • Within the body of the function, you cause any side-effect you wish.
    2. 2.
      errorHandler (function): an optional function for catching any unexpected errors thrown within your aperture. Typically used for logging errors.
      Signature: (initialProps, initialContext?) => (error) => { /* handle error here */ }
      • The initialProps are all props passed into the WrappedComponent.
      • The initialContext is the initial context value of the provided Context (see below, React >= 16.6.0 only)
      • The error is each value emitted by your aperture.
      • Within the body of the function, you cause any side-effect you wish.
    3. 3.
      Context (ReactContext): a React Context object. Its initial value will be passed to handler, errorHandler and aperture (React 16.6.0 and above only).
    4. 4.
      mergeProps: whether or not props passed with toProps or asProps should be merged together.
    5. 5.
      decorateProps: whether or not props which are functions should be decorated, so their arguments can be observed (default to true).
  3. 3.
    BaseComponent (React component): any react component.

Returns

WrappedComponent (React component): a new component which contains your side-effect logic, and which will render your component as per usual.

Example

import { withEffects } from 'refract-rxjs'
const BaseComponent = ({ username, onChange }) => (
<input value={username} onChange={onChange} />
)
const aperture = component => {
return component.observe('username').pipe(
debounce(2000),
map(username => ({
type: 'localstorage',
name: 'username',
value: username
}))
)
}
const handler = initialProps => effect => {
switch (effect.type) {
case 'localstorage':
localstorage.setItem(effect.name, effect.value)
return
}
}
const WrappedComponent = withEffects(aperture, { handler })(BaseComponent)

Tips

  • Take a look at our recipe for dependency injection into your Refract components.
  • withEffects is curried so that you can re-use a bound handler (and errorHandler) with multiple different apertures.