ParcelShape

ParcelShape is a data container very similar to a Parcel but without the automatic data binding. All it does is contain data, no strings attached, and provide methods for you to alter its data.

These exist to be used with updater methods, such as Parcel.modifyDown, to provide a safe way to alter the shape of data in a Parcel. ParcelShape’s methods are a subset of Parcel’s methods.

import ParcelShape from 'dataparcels/ParcelShape';
import ParcelShape from 'react-dataparcels/ParcelShape';
new ParcelShape(value?: any);
  • value ?: any = undefined
    The value you want to put in the ParcelShape. This value will be changed immutably when change methods are called on the ParcelShape. The data type of the value will determine the type of ParcelShape 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 parcelShape = new ParcelShape(123);

Example Usage

ParcelShapes are used in a very similar way to Immutable.js Maps and Lists, by calling methods that return new and updated ParcelShapes.

This page is currently being written 🚧

Properties

value

value: any

Returns the ParcelShape’s value.

meta

meta: Object

Returns an object containing the ParcelShapes’s meta data.

data

data: Object

Returns an object containing the ParcelShape’s data, which includes:

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

key

key: string

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

Parent methods

get()

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

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

let value = {
    abc: 123,
    def: 456
};
let parcelShape = new ParcelShape(value);
parcelShape.get('abc').value; // returns 123
parcelShape.get('xyz').value; // returns undefined
parcelShape.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.
Dataparcels automatically gives unique keys to all elements of an indexed parcel. See parcel keys for more info.
let value = ['abc', 'def', 'ghi'];
let parcelShape = new ParcelShape(value);
parcelShape.get(0).value; // returns 'abc'
parcelShape.get(-1).value; // returns 'ghi'
parcelShape.get('#a').value; // returns 'abc'

getIn()

getIn(keyPath: Array<string|number>): ParcelShape // only on ParentParcels
getIn(keyPath: Array<string|number>, notSetValue: any): ParcelShape // only on ParentParcels

Returns a ParcelShape containing the value associated with the provided key path. If the key path doesn’t exist, a ParcelShape with a value of notSetValue will be returned. If notSetValue is not provided then a ParcelShape with a value of undefined will be returned.

let value = {
    a: {
        b: 123
    }
};
let parcelShape = new ParcelShape(value);
parcelShape.get(['a','b']).value; // returns 123
parcelShape.get(['a','z']).value; // returns undefined
parcelShape.get(['a','z'], 789).value; // returns 789

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.
Dataparcels automatically gives unique keys to all elements of an indexed parcel. See parcel keys for more info.

children()

children(): ParentType<ParcelShape> // only on ParentParcels

Returns all of the ParcelShape’s children as new ParcelShapes, contained within the original ParcelShape’s data structure.

let value = {
    abc: 123,
    def: 456
};

let parcelShape = new ParcelShape(value);
parcelShape.children();

// returns {
//    abc: ParcelShape, // contains a value of 123
//    def: ParcelShape // contains a value of 456
// }

toObject()

toObject(): {[key: string]: ParcelShape} // only on ParentParcels

Like children(), expect the returned data structure is cast to an object.

let value = {
    abc: 123,
    def: 456
};

let parcelShape = new ParcelShape(value);
parcelShape.toObject()

// returns {
//    abc: ParcelShape, // contains a value of 123
//    def: ParcelShape // contains a value of 456
// }

toArray()

toArray(): Array<ParcelShape> // only on ParentParcels

Like children(), expect the returned data structure is cast to an array.

let value = {
    abc: 123,
    def: 456
};

let parcelShape = new ParcelShape(value);
parcelShape.toArray();

// returns [
//    ParcelShape, // contains a value of 123
//    ParcelShape // contains a value of 456
// ]

has()

has(key: string|number): boolean // only on ParentParcels

Returns true if the ParcelShape has a child at the provided key or index, or false otherwise.

size()

size(): number // only on ParentParcels

Returns the number of children this ParcelShape has.

Set methods

set()

set(value: any): ParcelShape
set(key: string|number, value: any): ParcelShape // only on ParentParcels, will set a child

Calling set() with one argument will return a new ParcelShape where the original value is replaced with the value provided.

let parcelShape = new ParcelShape(123);
parcelShape.set(456);
// returns a new ParcelShape containing 456

On ParentParcels this method can also be called with a key, which returns a new ParcelShape with the the child value at that key set to value.

let parcelShape = new ParcelShape({
    value: {
        abc: 123,
        def: 789
    }
});
parcelShape.set('abc', 456);
// returns a new ParcelShape containing {abc: 456, def: 789}

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.
Dataparcels automatically gives unique keys to all elements of an indexed parcel. See parcel keys for more info.

setIn()

setIn(keyPath: Array<string|number>, value: any): ParcelShape // only on ParentParcels

Calling setIn() will return a new ParcelShape where the value at the provided keyPath has been set to value.

let value = {
    a: {
        b: 123,
        c: 789
    }
};
let parcelShape = new ParcelShape(value);
parcelShape.set(['a','b'], 456);
// returns a new ParcelShape containing {a: {b: 456, c: 789}}

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.
Dataparcels automatically gives unique keys to all elements of an indexed parcel. See parcel keys for more info.

delete()

delete(): ParcelShape
delete(key: string|number): ParcelShape // only on ParentParcels, will delete a child

deleteIn()

deleteIn(keyPath: Array<string|number>): ParcelShape // only on ParentParcels

update()

update(updater: Function): ParcelShape
update(key: string|number, updater: Function): ParcelShape // only on ParentParcels, will set a child

updateShape()

updateShape(updater: Function): ParcelShape
updateShape(key: string|number, updater: Function): ParcelShape // only on ParentParcels, will set a child

updateIn()

updateIn(keyPath: Array<string|number>, updater: Function): ParcelShape // only on ParentParcels

updateShapeIn()

updateShapeIn(keyPath: Array<string|number>, updater: Function): ParcelShape // only on ParentParcels

Indexed & element change methods

insertAfter()

insertAfter(value: *): ParcelShape // only on ElementParcels, will insert after self
insertAfter(key: string|number, value: *): ParcelShape // only on IndexedParcels, will insert after child

insertBefore()

insertBefore(value: *): ParcelShape // only on ElementParcels, will insert before self
insertBefore(key: string|number, value: *): ParcelShape // only on IndexedParcels, will insert before child

move()

move(key: string|number): ParcelShape // only on ElementParcels, will move with sibling
move(keyA: string|number, keyB: string|number): ParcelShape // only on IndexedParcels, will move children

push()

push(...values: Array<*>): ParcelShape // only on IndexedParcels

pop()

pop(): ParcelShape // only on IndexedParcels

shift()

shift(): ParcelShape // only on IndexedParcels

swap()

swap(key: string|number): ParcelShape // only on ElementParcels, will swap with sibling
swap(keyA: string|number, keyB: string|number): ParcelShape // only on IndexedParcels, will swap children

swapNext()

swapNext(): ParcelShape // only on ElementParcels, will swap with next sibling
swapNext(key: string|number): ParcelShape // only on IndexedParcels, will swap child with next child

swapPrev()

swapPrev(): ParcelShape // only on ElementParcels, will swap with previous sibling
swapPrev(key: string|number): ParcelShape // only on IndexedParcels, will swap child with previous child 

unshift()

unshift(...values: Array<*>): ParcelShape // only on IndexedParcels

Type methods

isChild()

isChild(): boolean

Returns true if the ParcelShape is a child parcel. Read Parcel types for more info.

When a ParcelShape is a child parcel, it allows the use of child methods.

isElement()

isElement(): boolean

Returns true if the ParcelShape is an element parcel. Read Parcel types for more info.

When a ParcelShape is an element parcel, it allows the use of element methods.

isIndexed()

isIndexed(): boolean

Returns true if the ParcelShape is an indexed parcel. Read Parcel types for more info.

When a ParcelShape is an indexed parcel, it allows the use of indexed methods.

isParent()

isParent(): boolean

Returns true if the ParcelShape is a parent parcel. Read Parcel types for more info.

When a ParcelShape is a parent parcel, it allows the use of parent methods.

isTopLevel()

isTopLevel(): boolean

Returns true if the ParcelShape is a top level parcel. Read Parcel types for more info.

Debug methods

toConsole()

toConsole(): void

Outputs the ParcelShape’s data to the console.