ParcelBoundaryHoc

ParcelBoundaryHoc is a React higher order component. It’s job is to control the flow of parcel changes. It is the higher order component version of a ParcelBoundary.

Each ParcelBoundaryHoc is given a name, and expects that it will be given Parcel as a prop of the same name.

ParcelBoundaryHocs have an internal action buffer that can hold onto changes as they exit the boundary. These are normally released immediately, but also allow for debouncing changes, or putting a hold on all changes so they can be released later or cancelled.

Unlike ParcelBoundary, it cannot use pure rendering.

import {ParcelBoundaryHoc} from 'react-dataparcels';
ParcelBoundaryHoc({
    name: string | (props: *) => string,
    debounce?: number | (props: *) => number,
    hold?: boolean | (props: *) => boolean,
    originalParcelProp?: string | (props: *) => string,
    // debugging options
    debugBuffer?: boolean,
    debugParcel?: boolean
});
ParcelBoundaryHoc is also available as a React component, ParcelBoundary.

Config

name

name: string | (props: *) => string

The name of the prop that will contain a parcel.

The parcel is allowed to be undefined, in which case the ParcelBoundaryHoc will have no effect.

originalParcelProp

originalParcelProp?: string | (props: *) => string // optional

If set, ParcelBoundaryHoc will pass down the original parcel as a prop to its children. The name of the prop is specified by originalParcelProp.

debounce

debounce?: number | (props: *) => number // optional

If set, debounce will debounce any changes that occur inside the ParcelBoundaryHoc. The number indicates the number of milliseconds to debounce.

This can be used to increase rendering performance for parcels that change value many times in rapid succession, such as text inputs.

Debouncing explained

When the parcel in the ParcelBoundaryHoc sends a change, the ParcelBoundaryHoc will catch it and prevent it from being propagated out of the boundary. The parcel on the inside of the ParcelBoundaryHoc will still update as normal.

The ParcelBoundaryHoc waits until no new changes have occured for debounce number of milliseconds. It then releases all the changes it has buffered, all together in a single change request.

Debouncing can be good for rendering performance because parcels outside the ParcelBoundaryHoc don’t needlessly update every time a small change occurs (e.g. each time the user presses a key).

hold

hold?: boolean | (props: *) => boolean // optional

When hold is true, all changes made to the parcel inside the ParcelBoundaryHoc are prevented from being propagated out of the boundary. The parcel beneath will continue to update as normal. You can then call the release() action to release all the buffered changes at once, or the cancel() action to cancel all the buffered changes. This can be useful for building UIs that have a submit action.

debugBuffer

debugBuffer?: boolean = false // optional

Wehn debugBuffer is true, ParcelBoundaryHoc will log out changes relating to its internal action buffer.

debugParcel

debugParcel?: boolean = false // optional

Wehn debugParcel is true, ParcelBoundaryHoc will log out changes to its current parcel state.

Child props

${name}

${name}: Parcel

ParcelBoundaryHoc’s child component will receive a Parcel as a prop, with the name of the prop specified by config.name. This parcel is on the “inside” of the parcel boundary, and is able to update independently of the parcel that was passed into the ParcelBoundaryHoc.

If ParcelBoundaryHoc doesn’t receive a parcel as a prop at the name indicated by config.name, then this child prop will not exist.

${name}Actions

${name}Actions: {release: () => void, cancel: () => void}

ParcelBoundaryHoc’s child component will receive a set of actions that can be used to control the ParcelBoundaryHoc’s action buffer.

If ParcelBoundaryHoc doesn’t receive a parcel as a prop at the name indicated by config.name, then this child prop will not exist.

${name}Buffered

${name}Buffered: boolean

ParcelBoundaryHoc’s child component will receive a boolean that indicates if the ParcelBoundaryHoc currently contains changes that it hasn’t yet released.

If ParcelBoundaryHoc doesn’t receive a parcel as a prop at the name indicated by config.name, then this child prop will not exist.

${originalParcelProp}

${originalParcelProp}: Parcel

If config.originalParcelProp exists, ParcelBoundaryHoc’s child component will receive the original Parcel that was passed into the ParcelBoundaryHoc.