Flow Types

parcels

• Fix all Flow errors as of v0.54.1
• Internal changes to keying and key conversion. For anyone who is
  • key is a string used to identify a child, on any parcel including elements in indexed parcels which are given auto geenrated keys. "abc" and "#a" are keys, 3 is not.
  • index is a number that says the position of an element in an indexed parcel. 3 is an index, "abc" and "#a" are not.
  • property is a string or a number that can be used by Javascript to access a value's child. "abc" and 3 are properties, "#a" on an indexed parcel is not.
• BREAKING CHANGE PartialParcelData type no longer exists and is not exported anymore
• Property type has been added to exports

parcels-react

• BREAKING CHANGE PartialParcelData type no longer exists and is not exported anymore
• Property type has been added to exports

parcels-plugin-form

• No change to API

Addresses #20 #52

ChangeRequest, Types, modifyChangeValue()

parcels

Change Requests

• Added ChangeRequests
  • All changes are now described as a change request, which contains an array of actions, information about the originator of the change, and optional metadata associated with the change. Parcel.dispatch() now accepts either an action, an array of actions, or a change request.
  • Potential big performance gains in future. We can now do caching so we can avoid hitting the reducer (slow) at every point where the changed data is required.
  • Clearer mental model (parcels never go up!)
  • Provides a place for change meta to exist
    • Note this can't really be used until #35 exposes it
  • Provides a place for origin identifying information to exist
  • Simplifies modifyChanges usage
• parcels now exports {ChangeRequest}
• BREAKING CHANGE Parcel.modifyChange() has changed. The previous setup was temporary. Now it accepts a function that receives two arguments: the parcel that modifyChange is being called on, and a changeRequest.
  • Instead of newParcelData(), use changeRequest.data()
  • Instead of actions, use changeRequest.actions()
  • Instead of continueChange(), use parcel.dispatch(changeRequest)
• Parcel.batch() now accepts an optional second argument changeRequest. If set, this change request's meta data and origin information will be used by the batcher.
• Added Parcel.modifyChangeValue(). It accepts a function that updates the value in the current change request.
• Add Parcel.setChangeRequestMeta() This sets meta on the change request (a separate concept to Parcel.meta()). You'll almost certainly use this inside a Parcel.batch()
• Added Action.isValueAction() and Action.isMetaAction()

Types

• Added runtime type checking to Parcel constructor and methods, errors will be thrown if given the wrong stuff

API changes

• BREAKING CHANGE Remove Parcel.equals() and use it only in PureParcel, because it was too opinionated in how it calculated equality to put on Parcel's api
• BREAKING CHANGE Remove Parcel.findAllMatching() and move it to the util directory
• BREAKING CHANGE Remove Parcel.addPreModifier(), this was added to make it easier to access a parcel directly from state from multiple pieces of code and make sure that it already had any necessary modifiers applied to it, but going forward it's better to get people to use the ParcelStateHock and it's modify method as a single point of access to a parcel. People who don't want to use that can easily make a method that gets their parcel from state and modifies it before using it.

Bug fixes

• Fix bug where Parcel.findAllMatching() would think globstars in a match string count as wildcards #43

Internal

• More tests added to increase coverage
• Begin fixing internal flow types

parcels-react

Change Requests

• parcels-react now exports {ChangeRequest}
• parcels-react now exports all of parcels types

Types

• BREAKING CHANGE ParcelStateHock no longer provides a default prop name. You must give one yourself. This is to encourage good naming conventions where the prop name relates to the value of the parcel (like "person", "address" etc), and not to the fact it is a parcel. Parcel props named "parcel" aren't great.
• Added runtime type checking to ParcelStateHock constructor and methods, errors will be thrown if given the wrong stuff
• parcels-react now exports parcels types

parcels-plugin-form

• No change to API

Addresses #46 #43 #35 #32 and #31

ValidModifier, ping(), hasDispatched(), meta()

parcels

• BREAKING CHANGE Parcel.meta(key: Key): * no longer exists, just call .meta() and look in the object
• BREAKING CHANGE Parcel.refresh() has been removed due to it's reliance on having to have previously created child parcels using get() in order for them to be refreshed.
• Parcel. ping() has been added. It dispatched the ping action which already existed, which changes no data but allows the top level parcels to receive data from the dispatcher.
• Parcel. hasDispatched(): boolean has been added. It returns a boolean stating whether a parcel at the current location has dispatched anything yet.
• Parcel. findAllMatching(match: string): Parcel[] has been added. It returns an array of all descendant parcels (and possibly itself) that match the match string provided. Note does not work with match strings containing a globstar.
• Parcel.getInternalLocationShareData() and Parcel.setInternalLocationShareData(partialData: Object) have been added. Not really intended for public use, but modifiers may sometimes need these to be able to share data with all parcel instances at the same location without triggering changes.
• Parcel.initialMeta(partialMeta: Object) is now chainable, meaning that two parcels at the same location can both call initialMeta() and the second call will work.

parcels-react

• No changes

parcels-plugin-form

• BREAKING CHANGE ValidModifier now accepts a function that returns an object, instead of just an object.

Before

validators: {
    "name": [isRequired],
    "email": [isRequired, isEmail]
}

After

validators: (parcel) => ({
    "name": [isRequired],
    "email": [isRequired, isEmail]
})

• ValidModifier can now cope with falsey items being passed into its config, so you can now conditionally add validation depending on the value of the parcel:

validators: (parcel) => ({
    "name": [isRequired],
    "email": [isRequired, isEmail],
    "cool": parcel.value().isCool() && [isRequired],
    "something": [isRequired, parcel.value().isCool() && isAmazing],
})

• Internally validator now works much better. On submit it iterates over the keys passed to it, ping()s each parcels that it hasn't received an action from yet so it contains up-to-date data, then calls all the validators.

Based off #43

New matcher, sync ping

parcels

• Replaced minimatch with own matcher. It can match:
  • Root ^
  • By key abc
  • Grandchild by key abc.def
  • By key with wildcard abc.*
  • By key with partial wildcard abc.d*
  • By type *:Parent
  • By not type *:!Parent
  • By multiple type *:Parent|Element
  • By globstar **hello or **.abc
  • Keys with non word characters (e.g. "abc.:%") abc%.%:%%
• Parcels also has a new key escaping scheme. Previously Parcels would not work with objects that contained colons or some other characters in a value's keys. Now it works with all characters. Match strings like the ones above should have all non-word characters escaped with a preceding %, so if you want to write a match string that matches a name that contains anything other than alphanumeric characters and underscores, then you'll have to escape the special characters in the match string.

Example

{
    ['abc']: 123, // match this with "abc"
    ['underscore_name']: 456, // match this with "underscore_name"
    ['hyphenated-name']: 789, // match this with "hyphenated%-name"
    ['weird%name*with:!)what!?']: 123, // match this with "weird%%name%*with%:%!%)what%!%?",
    ['foo']: {
        ['bar']: 789 // match this with "foo.bar"
    },
    ['foo.bar']: 456, // match this with "foo%.bar"
    ['foo%.bar']: 456 // match this with "foo%%%.bar"
}

• Rename noop action to ping
• parcelsand parcels-react now export Action class and ActionCreators
• No breaking changes

parcels-react

• PureParcel now ignores debounce whenever a ping (previously noop) action is present
• parcelsand parcels-react now export Action class and ActionCreators
• No breaking changes

parcels-plugin-form

• No change

ParcelPure debounce, debug render, form tweaks

parcels

• Added Parcel({debugRender: true}) option to allow ParcelPure to paint re-rendered parcels different colours so you can see which ones are being re-rendered
• No breaking changes

parcels-react

• ParcelPure can paint re-rendered parcels different colours so you can see which ones are being re-rendered when given a parcel with debugRender: true
• Add debounce to ParcelPure

parcels-plugin-form

• Allow SubmitModifier to store last captured errors on meta.errors
• Added onError function to SubmitModifier config and to ParcelsPluginForm
• No breaking changes

ParcelStateHock and more

parcels

• Let parcel keying work with Immutable.js Records by using unmutable !isIndexed() rather than isKeyed()
• No breaking changes

parcels-react

• Added ParcelStateHock, a higher order component that stores and provides a parcel to the components beneath it
• No breaking changes

parcels-plugin-form

• Fix bug in dirty modifier where original value was compared against root parcel value, not child parcel value
• No breaking changes

parcels-docs

• Fix broken examples link in docs

Cool Times

• Added Parcel.initialMeta(initialMeta: Object) => Parcel
• Added Parcel.isTopLevel() and concept of a TopLevel type
• Added Parcel.refresh() to force all children parcels to return their current values back up to the caller
• Parcel.modify() can now accept multiple arguments
  • Addresses #22
  • Parcel.modify(modifier) -> Parcel.modify(...modifier[])
• Added new package parcels-plugin-form contianing modifiers to make form behaviour with parcels
  • Addresses #23
• Action buffers can now be nested
• Changed id() algorithm to make more sense, now contains less special cases
• Perf gains by thunking calls to the reducer and upgrading unmutable
• Fixed bug where ids of modifiers would have their type code appended multiple times