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 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 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.