This module implements the QueryAdapter interface to use the JMESPath query language as part of JM2MP projection documents.

This module only supports jmespath 0.16.x version (the canonical package). There is a community fork (with its own library @jmespath-community/jmespath), but its API is different enough that it is not considered compatible.

By design, JMESPath is a declarative query language with a formal specification and an official test suite. It is widely deployed (for instance, in the AWS CLI). It combines path access, projections, square-brackets segments, filtering, multi-selection expressions (for both, lists and maps), pipelines and a catalogue of built-in functions.

Examples of syntax:

• "foo.bar": inner property accessor.
• "users[0].name": inner property name of first user.
• "users[*].name": all names of every user.
• "users[?age > 18]": filter by predicates.
• "users[*].{n: name, a: age}": multi-select hash.
• "length(users)": built-in functions.
• "people | [0]": pipe (restarting its own context).

By compliance with JM2MP, the QueryAdapter created by createJmesPathAdapter maintains the expected behaviour:

• undefined --> null (native for JMESpath).
• null input --> null output without calling JMESpath external library.
• Expression with multiple resultsets --> array (as is).
• Expression with single result --> array (with single item). Aquí JMESPath DIFIERE del adaptador nativo / jsonpath-plus: no desempaquetamos. La razón es que en JMESPath la "aridad" de la expresión es una propiedad sintáctica (las proyecciones siempre devuelven listas, los accesos simples siempre devuelven escalares). Desempaquetar rompería esa propiedad y haría que el tipo de retorno dependa de los datos. Esta divergencia está documentada en la fallbackPolicy del adaptador para que el usuario sepa a qué atenerse.
• Invalid expression during validation --> ValidationError.
• Invalid expression during runtime --> EvaluationError.
• Expression cache: the canonical jmespath library do not publicly exposes its TreeInterpreter; because of that, jmespath.search(data, expr) parses again internally each query in every invocation; this QueryAdapter then uses its cache just for remember queries previously validated to avoid call compile from evaluate; it is not useful as a proper AST cache stricto sensu.

The jmespath library is dynamically loaded when constructing its corresponding QueryAdapter. If not previously installed, an AdapterError exception will be raised from createJmesPathAdapter with a clear message about it.