natural-lenses/datum-plan

This module is (when required) or exports as default (when imported) a Function accepting a datum plan specification and returning a structure with the same names composed of Lenses. The plan specification can be provided either directly as a plan or as a Function that receives as its first argument a DSL object providing relevantly named values.

The terminal value (or VALUE in the DSL) indicates where descent into spec terminates. Otherwise, specification descent continues, though differently through Arrays and other Objects.

Descent through an Array expects either 0 or 1 elements in the Array: if one entry is given, it is the "item spec" for items in the Array; if no element is given, the Array has no "item spec." The item spec — if one is given — is passed to certain IndexableMixin methods attached to the Lens that retrieves the equivalent slot in a subject.

Descent through an Object produces Lenses for each own-property of the spec Object, attaching them to the Lens which would retrieve the instant Object spec. Spec Objects can have a special own-property with the key given by [others], which specifies A) that this Object behaves at in a dictionary-like manner for any non-explicit properties, and B) the datum plan spec for each non-explicit entry's value (if something other than value is provided). The DSL near-equivalent of using [others] is NAMED_VALUES.

To allow specification of any property in an Object of a datum plan spec, the special key [raw] can be used to provide an additional Object whose own-properties are just like the properties for the Object containing the [raw] key, except none of the keys of this secondary object are treated as special -- not [raw], nor [others], nor any other key matching the "special key" pattern (double parentheses containing only lowercase letters).

The resulting datum plan will be structured vaguely like spec (or the result of calling spec) and constructed to access a value of similar structure to spec.

If options.planGroup is given, the constructed datum plan can be instrumented with JavaScript proxies to detect and report cases where undefined properties of lenses within the datum plan are accessed. This is done by including the options.planGroup value within the comma-separated value in the DATUM_PLAN_GUARDS environment variable.

Source:

src/datum_plan.js, line 695

See:

DatumPlan_Dsl
Datum Plans tutorial

Properties:

Name	Type	Description
`others`	string	Used as a key in an Object to indicate dictionary-like behavior
`raw`	string	Used as a key in an Object to provide additional properties for the host object, none of which are treated specially
`value`	string	Used as a "tip" indicator for where generation of nested Lenses ends

Parameters:

Name Type Attributes Description

spec

Array | Object | string | DatumPlan_DslCallback

An object specifying the datum plan to be generated, or a DatumPlan_DslCallback to return such an object

opts

Object

Properties

Name	Type	Attributes	Description
`planGroup`	string	<optional>	String name to associate with all lenses in this plan; should not contain any commas
`methodsVersion`	string	<optional>	(since 2.3.0) The major.minor version of the Lens methods to use; this avoids changes to deconfliction of declared datum plan properties with later-introduced Lens method names

Returns:

A Lens with Lens properties which may, in turn, have Lens properties; mixin methods may be added to some of these lenses

Type: Lens

Methods

fromPOD(spec, optsopt) → {Lens}

Generate a datum plan from Plain Ol' Data (POD)

Source:

src/datum_plan.js, line 775

Since:

2.1.0

See:

module:natural-lenses/datum-plan

If an initial state POD value is available, this function simplifies generating a datum plan to access the value. One example application would be in a Redux store, where the initial state could be passed to this function and the resulting datum plan used to create selectors and reducers.

Several aspects of the abstract structure of the target value as it evolves over time cannot be inferred from spec and some information in spec may be ambiguous in terms of generating a datum plan. These difficulties can be addressed by passing an Array (or a DSL-consuming Function returning an Array) in opts.tweaks. Idiomatic usage is to pass a DatumPlan_TweaksBuilderCallback, which can use the basic datum plan DSL values (from DatumPlan_Dsl) plus lens and access to build functions that make altered clones of spec which resolve these lacunae and ambiguities.