caf_components/templateUtils

Functions to process template descriptions.

A parsed description has a type specType:

 { name: string, module: string | null, description=: string,
   env: Object, components=: Array.<specType>}

Merging template B into A starts at the top and uses the following rules:

  1. If we are merging the top component and A.name !== B.name, throw an error if overrideName is disabled, otherwise change A.name.

  2. To merge two components with the same name, if B.module === null then delete A. Otherwise, change A.module, merge the env properties, and finally, merge array B.components into A.components.

  3. To merge array B.components into A.components iterate on each element X of B.components applying the following ordering rules:

    1. If X.name matches any Y.name then merge with Y in place, and remember Y position in the array.
    2. if X.name does not match any component, and X.module !== null, insert X after the last remembered position. If none was remembered, X becomes the first element in the array. In both cases, remember the new X position.

Merge always clones first, leaving the original descriptions unmodified.

Source:

Methods

merge(template, deltaopt, overrideName) → {specType}

Source:

Patches a template description with a delta description.

Merge rules are described in a module-level comment in this file.

It does not modify the inputs, returning a cloned description with the merged results.

Parameters:
Name Type Attributes Description
template specType

A target parsed description.
delta specDeltaType <optional>

Description with changes to apply to template. A missing delta just clones template.
overrideName boolean

True if we allow changing the name of the top level component, false if names in template and delta should match.
Throws:

if invalid inputs, or overrideName is false and we have different names for the top component.

Type
Error
Returns:

A patched description.

Type
specType

(inner) mergeComponents(template, delta) → {Array.<specType>}

Source:

Merge two component arrays of matching components.

Parameters:
Name Type Description
template Array.<specType>
delta Array.<specDeltaType>
Returns:

result

Type
Array.<specType>

(inner) mergeEnv(template, delta) → {Object}

Source:

Merge two environments of matching components.

Parameters:
Name Type Description
template Object
delta Object
Returns:

result

Type
Object

(inner) mergeObj(template, delta, overrideName) → {specType}

Source:

Merge two descriptions with the same name.

Parameters:
Name Type Description
template specType
delta specDeltaType
overrideName boolean
Returns:

result

Type
specType

(inner) parseString(x) → {number|boolean|string|null|object}

Source:

Parses an string into an object or number or boolean or null... If we fail we just leave it as it was.

Parameters:
Name Type Description
x string

String to parse
Returns:

A parsed object.

Type
number | boolean | string | null | object

(inner) patchEnv(desc, f)

Source:

Patches every environment in a description.

Parameters:
Name Type Description
desc specType

A description to patch.
f function

A function to patch an environment.

(inner) patchOneEnv(prefix, f)

Source:

Returns a function that filters relevant values in an environment and applies a transform to them.

Parameters:
Name Type Description
prefix string

A matching prefix for selected values.
f function

A function that transforms matching values.

resolveEnv(desc)

Source:

Patches in place env values that link to environment properties.

We use the reserved process.env. prefix for values that come from the environment.

We can also provide default values using the string separator ||, and any characters after it will be parsed as JSON.

If parsing fails, we default to a simple string, avoiding the JSON requirement of quoting all strings. For example:

env: {"location" : "process.env.MY_LOCATION||Palo Alto"}

Parameters:
Name Type Description
desc specType

A description to be patched.
Source:

Patches in place links to the top level environment.

We use the prefix $._.env.. For example:

env: {"location" : "$._.env.location"}

Parameters:
Name Type Description
desc specType

A description to be patched.