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. 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. a config object optionally containing the following:

    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. 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. 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. mergeProps: whether or not props passed with toProps or asProps should be merged together.

    5. decorateProps: whether or not props which are functions should be decorated, so their arguments can be observed (default to true).

  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.