JSON Model-to-Model Projection (JM2MP) Documentation

JSON Model-to-Model Projection (JM2MP) Documentation

Module

jm2mp/adapters/registry

This module declares the QueryAdapter interface to implement by any external query language as part of JM2MP projection documents, which needs to be registered using an instance of the AdapterRegistry class.

This module serves as a central registry for query language external adapters (like JMESPath or JSONPath, to name a few). After an external adapters is registered, its offered syntax can be used as part of any JM2MP projection module through the $get template command.

To standardize any potential adapters, an asynchronous execution mechanism has been chosen.

The evaluate function will always return a Promise<any>. This way, adapters that are internally synchronous can simply return Promise.resolve(value) implicitly, since they are declared as async. This unifies the interface and avoids ambiguities in the evaluator.

The fact is that, for now, the JSONata@2.x library is the only asynchronous one. However, it is expected that in the future, as asynchronous programming in JavaScript becomes more popular, the number of external libraries that benefit from this design will grow.

Source

Classes

AdapterRegistry

Type Definitions

Properties

  • evaluate EvaluateFunction

    It evaluates the expression on the provided input.

    It must be always async.

    Every adapter must guarantee satisfaction of (uniform contract):

    • If input is null, returns null without invoking the underlying library.
    • If the expression returns no result or undefined, it returns null.
    • If the expression returns a single scalar, it returns that scalar not wrapped in an array.
    • If the expression returns multiple matches, it returns an array wrapping all maches.
    • Library errors are wrapped in EvaluationError or ValidationError, as appropriate.

    The cache parameter is a Map provided by the system to store compiled expressions during the current evaluation.

    The env parameter is the complete language environment. The native adapter needs it to resolve $ or @ or %alias; the rest of adapters ignore it.

  • fallbackPolicy FallbackPolicyObject

    Human-readable documentation of the adapter's behavior.

    Required fields: missing, multipleMatches, typeError, and nullInput.

EvaluateFunction()

typedef {(path: any, input: any, cache: Map<string, any>, env: object) => Promise} EvaluateFunction

Properties

  • evaluate EvaluateFunction

    It evaluates the expression on the provided input.

    It must be always async.

    Every adapter must guarantee satisfaction of (uniform contract):

    • If input is null, returns null without invoking the underlying library.
    • If the expression returns no result or undefined, it returns null.
    • If the expression returns a single scalar, it returns that scalar not wrapped in an array.
    • If the expression returns multiple matches, it returns an array wrapping all maches.
    • Library errors are wrapped in EvaluationError or ValidationError, as appropriate.

    The cache parameter is a Map provided by the system to store compiled expressions during the current evaluation.

    The env parameter is the complete language environment. The native adapter needs it to resolve $ or @ or %alias; the rest of adapters ignore it.

  • fallbackPolicy FallbackPolicyObject

    Human-readable documentation of the adapter's behavior.

    Required fields: missing, multipleMatches, typeError, and nullInput.

Source

FallbackPolicyObject

FallbackPolicyObject A descriptive object with human-readable documentation of the adapter's behavior.

Type

  • object

Properties

  • missing string

    How a missing value from each query is returned.

  • singleMatch string

    How a single matched value from each query is returned.

  • multipleMatches string

    How multiple matched values from each query are returned.

  • typeError string

    How type errors from each query are catched and maybe raised.

  • nullInput string

    How a null input (execution environment) is treated.

  • timeout string

    Is there any timeout to configure? Currenctly only affects to JSONata@2.x adapter, due its async internal implementation.

Source

QueryAdapter

Interface (contract) that every query language adapter must implement.

Type

  • object

Properties

  • name string

    Unique syntax identifier.

    It is used in the $syntax clause of the get templante command.

  • description string

    Shrot description for documenting purposes.

  • validate ValidateFunction

    It validates (tests) the path expression.

  • evaluate EvaluateFunction

    It evaluates (runs) the path expression.

Source

Properties

  • validate ValidateFunction

    It validates a $path expression statically (template command get).

    It throws a ValidationError if it is invalid.

    It is asynchronous to accommodate adapters whose parser is asynchronous.

ValidateFunction()

typedef {(path: any) => Promise} ValidateFunction

Properties

  • validate ValidateFunction

    It validates a $path expression statically (template command get).

    It throws a ValidationError if it is invalid.

    It is asynchronous to accommodate adapters whose parser is asynchronous.

Source