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 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).
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 and constructed to access a value of similar shape 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:
- 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 |
<optional> |
Properties
|
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:
- Since:
- 2.1.0
- See:
If a intial 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.
Parameters:
| Name | Type | Attributes | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
spec |
Array | Object | string | An object specifying the datum plan to be generated |
||||||||||||||||
opts |
Object |
<optional> |
Properties
|
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