ParcelNode

ParcelNodes are used via the asNode and asChildNodes updater functions.

asNode

import asNode from 'dataparcels/asNode';
import asNode from 'react-dataparcels/asNode';

asNode((node: ParcelNode) => ParcelNode)

The asNode function is a kind of parcel updater that primarily allows for setting meta. It will provide you with your Parcel's value wrapped in a ParcelNode, from which you can call .setMeta().

Your updater function must return a ParcelNode.

You can also call .update() if you'd like to add, remove or re-arrange child values, which does the same thing as asChildNodes described below.

.modifyUp(asNode(
    node => node.setMeta({cool: true})
))

asChildNodes

import asChildNodes from 'dataparcels/asChildNodes';
import asChildNodes from 'react-dataparcels/asChildNodes';

asChildNodes((nodes: any) => any

The asChildNodes function is a kind of parcel updater that allows for adding, removing and re-arranging child values.

It must be passed a function, whose first argument will be your Parcel’s value, but with all child values replaced with ParcelNode instances. You can move and remove these as you like. You can also insert non-ParcelNode values into the parent data shape to set new data. The function passed to asChildNodes() will also sometimes receive a ChangeRequest as a second parameter depending on what the asChildNodes() function is being passed into.

The function asChildNodes(updater) is equivalent to asNode(node => node.update(updater)).

let parcel = new Parcel({
    value: [1,2,3]
});

// reverse the parcel's children
let modifiedParcel = parcel.modifyDown(asChildNodes(
    shape => shape.slice().reverse() // clones and reverses the shape array
));

// new value is [3,2,1]

let parcel = new Parcel({
    value: {foo: 100}
});

// set a default value for a child
let modifiedParcel = parcel.modifyDown(asChildNodes(
    shape => ({bar: 200, ...shape})
));

ParcelNode

import ParcelNode from 'dataparcels/ParcelNode';
import ParcelNode from 'react-dataparcels/ParcelNode';

new ParcelNode(value?: any);

• value ?: any = undefined

  The value you want to put in the ParcelNode. This value will be changed immutably when change methods are called on the ParcelNode. The data type of the value will determine the type of ParcelNode that will be created, and will determine which methods you can use to change the value. Please read Parcel types for more info.

// creates a Parcel that contains a value of 123
let shape = new ParcelNode(123);

Properties

value

value: any

Returns the ParcelNode's value.

meta

meta: Object

Returns an object containing the ParcelNodes's meta data.

data

data: Object

Returns an object containing the ParcelNodes's data, which includes:

• value - The ParcelNodes's value
• meta - The ParcelNodes's meta object
• key - The ParcelNodes's key
• child - The ParcelNodes's child information, which includes any meta, key and child data related to the values children.

key

key: string

Returns the ParcelNode's key. Dataparcels automatically gives unique keys to all children of a parent parcel. See parcel keys for more info.

Methods

get()

get(key: string|number): ParcelNode // only on ParentParcels
get(key: string|number, notSetValue: any): ParcelNode // only on ParentParcels

Returns a ParcelNode containing the value associated with the provided key / index. If the key / index doesn't exist, a ParcelNode with a value of notSetValue will be returned. If notSetValue is not provided then a ParcelNode with a value of undefined will be returned.

let value = {
    abc: 123,
    def: 456
};
let node = new ParcelNode(value);
node.get('abc').value; // returns 123
node.get('xyz').value; // returns undefined
node.get('xyz', 789).value; // returns 789

get() with indexed values

When called on a Parcel with an indexed value, such as an array, this method can accept an index or a key.

• index (number) is used to get a value based off its position. It can also be negative, indicating an offset from the end of the sequence.
• key (string) is used to get a specific value by its unique key within the Parcel.

let value = ['abc', 'def', 'ghi'];
let node = new ParcelNode(value);
node.get(0).value; // returns 'abc'
node.get(-1).value; // returns 'ghi'
node.get('#a').value; // returns 'abc'

update()

// updates value - only to be used if shape doesn't change
update((value: any) => any): ParcelNode

// updates shape / meta
update(asNode((node: ParcelNode) => ParcelNode)): ParcelNode
update(asChildNodes(value: any) => any): ParcelNode

Calling update() with one argument will replace the current value in the ParcelNode with the result of the value updater provided to it. The value updater is passed the current value of the ParcelNode, from which you can return the intended replacement value.

Please be careful

This method is safe to use in most simple cases, but in some cases it should not be used:

• If the updater gives you a primitive value or childless value, you can return anything.
• If the updater gives you a value that has children, you can always return a primitive value or childless value.
• If the updater gives you a value that has children, you can return a value with children only if the shape hasn't changed.

To find out why, and what to do about it, please read about parcel updaters.

setMeta()

setMeta(partialMeta: Object): ParcelNode

Sets meta at the current parcel's location. Values on the partialMeta object are merged shallowly onto any existing meta. Read Parcel meta for more info.