ParcelHoc

ParcelHoc is a React higher order component. Its job is to provide a parcel as a prop, and to handle how the parcel binds to React props and lifecycle events.

It is recommended that you use ParcelHoc, rather than managing your own Parcel state.

import ParcelHoc from 'react-dataparcels/ParcelHoc';
ParcelHoc({
    name: string,
    valueFromProps: Function,
    shouldParcelUpdateFromProps?: Function,
    onChange?: Function,
    delayUntil?: Function,
    pipe?: Function
    // debugging options
    debugParcel?: boolean
});

Config

name

name: string

Sets the name of the prop that will contain the parcel.

Example

valueFromProps

valueFromProps: (props: Object) => any

The valueFromProps function will be called once when ParcelHoc mounts. It is passed props, and the returned value is used as the initial value of the ParcelHoc’s Parcel.

Example

shouldParcelUpdateFromProps

shouldParcelUpdateFromProps?: (prevProps: *, nextProps: *) => boolean // optional

The shouldParcelUpdateFromProps config option allows the ParcelHoc to replace its parcel’s contents based on received props.

If shouldParcelUpdateFromProps is set, it will be called every time props are received. It is passed three arguments:

  • prevProps is the previous set of props received.
  • nextProps is the next set of props received.
  • valueFromProps is the function passed to config.valueFromProps

When shouldParcelUpdateFromProps returns true, ParcelHoc will replace all of its parcels value with valueFromProps(nextProps), and it will delete all key and meta information from the parcel.

ParcelHoc({
    name: "exampleParcel",
    valueFromProps: (props) => props.data,
    shouldParcelUpdateFromProps: (prevProps, nextProps, valueFromProps) => valueFromProps(prevProps) !== valueFromProps(nextProps)
});
In future there will be more options to allow key and meta data to be retained.
Example

onChange

onChange?: (props: Object) => (value: any, changeRequest: ChangeRequest) => void // optional

The onChange function is called whenever ParcelHoc changes. It expects to be given a double barrel function. The first function will be passed props, and the next is passed the new value. It is only fired if the value actually changes.

onChange is often used to relay changes further up the React DOM heirarchy. This works in a very similar way to uncontrolled components in React.

Example

delayUntil

delayUntil?: (props: Object) => boolean // optional

You can delay the creation of the parcel by providing an delayUntil function. It will be called on mount and at every prop change until the parcel is created. It is passed props, and the Parcel will not be created until true is returned. A value of undefined will be passed down until the Parcel is created. Once the returned value is true, the Parcel will be created with the props at that time.

Example

pipe

pipe?: (props: Object) => (parcel: Parcel) => Parcel // optional

This function gives you the opportunity to modify the parcel before it reaches any other components.

The pipe function expects to be given a double barrel function. The first function will be passed props, and the next is passed the Parcel. The result of the pipe function will then be passed down as a prop.

debugParcel

debugParcel?: boolean = false // optional

For debugging purposes. When set to true this logs the ParcelHoc’s parcel each time it changes.

Child props

${name}

${name}: Parcel

ParceHoc’s child component will receive a Parcel as a prop, with the name of the prop specified by config.name.