(ver también licencias para dependencias de desarrollo)

JSONPath Plus

Analiza, transforma y extrae selectivamente datos de documentos JSON (y objetos de JavaScript).

jsonpath-plus expande la especificación original para añadir algunos operadores adicionales y hace explícitos algunos comportamientos que la original no detallaba.

Prueba la demo en el navegador o Runkit (Node).

Nota: Este proyecto no se mantiene activamente en la actualidad. Podemos aceptar PRs bien documentados o algunas actualizaciones simples, pero no buscamos hacer correcciones ni añadir nuevas funciones por nuestra cuenta.

Características

• Conforme con la especificación original de jsonpath
• Adiciones o elaboraciones convenientes no proporcionadas en la especificación original:
  • ^ para obtener el padre de un elemento coincidente
  • ~ para obtener los nombres de propiedad de los elementos coincidentes (como array)
  • Selectores de tipo para obtener:
    • Tipos JSON básicos: @null(), @boolean(), @number(), @string(), @array(), @object()
    • @integer()
    • El tipo compuesto @scalar() (que también acepta undefined y números no finitos al consultar objetos de JavaScript, así como todos los tipos básicos no objeto/no función)
    • @other() utilizable junto con un definido por el usuario

Benchmarking

jsonpath-plus es consistentemente eficiente con conjuntos de datos tanto grandes como pequeños en comparación con otras librerías de consulta JSON según json-querying-performance-testing. Puedes verificar estos hallazgos ejecutando el proyecto tú mismo y añadiendo más casos de rendimiento.

Instalación```shell

npm install jsonpath-plus

## Configuración

### Node.js```js
const {JSONPath} = require('jsonpath-plus');

const result = JSONPath({path: '...', json});

Navegador

Para uso en navegador puedes incluir directamente dist/index-browser-umd.cjs; no es necesaria ninguna magia de Browserify:```html

### ESM (Navegadores modernos)

También puedes usar importaciones de módulos ES6 (para navegadores modernos):```html
<script type="module">

import {
    JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';

const result = JSONPath({path: '...', json: {}});

</script>

ESM (Empaquetadores)

O si estás empaquetando tu JavaScript (p. ej., con Rollup), solo usa, ten en cuenta que mainFields debe incluir browser para las compilaciones del navegador (para Node, la opción predeterminada, que verifica module, debería ser suficiente):```js import {JSONPath} from 'jsonpath-plus';

const result = JSONPath({path: '...', json});

## Uso

La firma completa disponible es:```
const result = JSONPath([options,] path, json, callback, otherTypeCallback);

Los argumentos path, json, callback y otherTypeCallback pueden expresarse alternativamente (junto con cualquier otra de las propiedades disponibles) en options.

Tenga en cuenta que result contendrá todos los elementos encontrados (opcionalmente envueltos en un array) mientras que callback puede utilizarse si desea realizar alguna operación a medida que se descubre cada elemento, con la función de callback ejecutándose de 0 a N veces dependiendo del número de elementos independientes que se encuentren en el resultado. Consulte la documentación a continuación para más información sobre los argumentos disponibles de JSONPath.

Véase también la documentación de la API.

Propiedades

Las propiedades que se pueden suministrar en el objeto de opciones o en el método evaluate (como primer argumento) incluyen:

• path (obligatorio) - La expresión JSONPath como una cadena (normalizada o no normalizada) o array
• json (obligatorio) - El objeto JSON a evaluar (ya sea de tipo null, boolean, number, string, object o array).
• autostart (por defecto: true) - Si se suministra como false, se puede llamar manualmente al método evaluate.
• flatten (por defecto: false) - Si el array de resultados devuelto se aplanará a un array de una sola dimensión.
• resultType (por defecto: "value") - Puede ser una forma que no distinga entre mayúsculas y minúsculas de "value", "path", "pointer", "parent" o "parentProperty" para determinar respectivamente si devolver los resultados como los valores de los elementos encontrados, como sus rutas absolutas, como JSON Pointers a las rutas absolutas, como sus objetos padre, o como el nombre de la propiedad de su padre. Si se establece en "all", todos estos tipos se devolverán en un objeto con el tipo como nombre de clave.
• sandbox (por defecto: {}) - Mapa clave-valor de variables que estarán disponibles para evaluaciones de código, como expresiones de filtrado. (Tenga en cuenta que la ruta y el valor actuales también estarán disponibles para esas expresiones; consulte la sección Sintaxis para más detalles.)
• wrap (por defecto: true) - Indica si se envuelven o no los resultados en un array. Si wrap se establece en false y no se encuentran resultados, se devolverá undefined (en lugar de un array vacío cuando wrap se establece en true). Si se establece en y se encuentra un único resultado que no sea un array, ese resultado será el único elemento devuelto (no dentro de un array). No obstante, se seguirá devolviendo un array si se encuentran múltiples resultados. Para evitar ambigüedades (en el caso en que sea necesario distinguir entre un resultado que es un fallo y uno que es un array vacío), se recomienda cambiar el valor por defecto a .

Métodos de instancia

• evaluate(path, json, callback, otherTypeCallback) O evaluate({path: <path>, json: <json object>, callback: <callback function>, otherTypeCallback: <otherTypeCallback function>}) - Este método solo es necesario si la propiedad autostart está establecida en false. Se puede utilizar para evaluaciones repetidas usando la misma configuración. Además de las propiedades enumeradas, el último patrón de método puede aceptar cualquiera de las otras propiedades de instancia permitidas (excepto autostart, que no tendría relevancia aquí).

Propiedades y métodos de clase

• JSONPath.clearCache() - Limpia las rutas analizadas y los scripts compilados almacenados en caché internamente. El contenido de la caché no está expuesto; llame a este método cuando sea necesario invalidar la caché.
• JSONPath.toPathArray(pathAsString) - Acepta una ruta normalizada o no normalizada como cadena y la convierte en un array: por ejemplo, ['$', 'aProperty', 'anotherProperty'].
• JSONPath.toPathString(pathAsArray) - Acepta un array de ruta y lo convierte en una cadena de ruta normalizada. La cadena tendrá una forma como: $['aProperty']['anotherProperty][0]. Las construcciones terminales de JSONPath ~ y ^ y los operadores de tipo como @string() se eliminan silenciosamente.
• JSONPath.toPointer(pathAsArray) - Acepta un array de ruta y lo convierte en un JSON Pointer. La cadena tendrá una forma como: /aProperty/anotherProperty/0 (con cualquier carácter interno ~ y / escapado según la especificación de JSON Pointer). Las construcciones terminales de JSONPath ~ y ^ y los operadores de tipo como se eliminan silenciosamente.

Sintaxis a través de ejemplos

Dado el siguiente JSON, tomado de http://goessner.net/articles/JsonPath/:```json { "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } ], "bicycle": { "color": "red", "price": 19.95 } } }

y la siguiente representación XML:```xml
<store>
    <book>
        <category>reference</category>
        <author>Nigel Rees</author>
        <title>Sayings of the Century</title>
        <price>8.95</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Evelyn Waugh</author>
        <title>Sword of Honour</title>
        <price>12.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Herman Melville</author>
        <title>Moby Dick</title>
        <isbn>0-553-21311-3</isbn>
        <price>8.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>J. R. R. Tolkien</author>
        <title>The Lord of the Rings</title>
        <isbn>0-395-19395-8</isbn>
        <price>22.99</price>
    </book>
    <bicycle>
        <color>red</color>
        <price>19.95</price>
    </bicycle>
</store>

Tenga en cuenta que los ejemplos de XPath a continuación no distinguen entre recuperar elementos y su contenido de texto (excepto cuando es útil para comparaciones o para evitar ambigüedades). Nota: para probar los ejemplos de XPath (incluidos los de 2.0), esta demo puede ser útil (configúrelo en xml o xml-strict).| XPath | JSONPath | Resultado | Notas | |-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | /store/book/author | $.store.book[*].author | Los autores de todos los libros de la tienda | También puede representarse sin el $. como store.book[*].author (aunque esto no está presente en la especificación original); nótese que algunos literales de carácter ($ y @) requieren escape, sin embargo | | | | Todos los autores | | | | | Todas las cosas en la tienda, que son sus libros (un array de libros) y una bicicleta roja (un objeto bicicleta). | | | | | El precio de todo en la tienda. | | | | | El tercer libro (objeto libro) | | | | | El último libro en orden. | Para acceder a una propiedad con un carácter especial, utiliza para el filtro (esta característica en particular no está presente en la especificación original) | | | | Los dos primeros libros | | | o en XPath 2.0 | | Las categorías y autores de todos los libros | | | | | Filtrar todos los libros que tengan un número ISBN | Para acceder a una propiedad con un carácter especial, utiliza para el filtro (esta característica en particular no está presente en la especificación original) | | | | Filtrar todos los libros más baratos que 10 | | | | | Obtener todos los valores de propiedad de objetos cuya propiedad es price y que no sean iguales a 8.95 | Con el solo que permite filtrar objetos por valor de propiedad (no necesariamente dentro de arrays), puedes añadir después de la expresión para obtener el objeto que posee las propiedades filtradas | | | | La raíz del objeto JSON (es decir, el objeto completo en sí mismo) | Para obtener un literal (solo o en cualquier parte de la ruta), debes usar el escape de comilla invertida | | | | Todos los Elementos (y texto) debajo de la raíz en un documento XML. Todos los miembros de una estructura JSON debajo de la raíz. | | | | | Todos los Elementos en un documento XML. Todos los componentes padre de una estructura JSON incluyendo la raíz. | Este comportamiento no fue especificado directamente en la especificación original | | | | Padre de aquellos elementos específicos con un precio mayor que 19 (es decir, el valor de la tienda como padre de la bicicleta y el array de libros como padre de un libro individual) | El padre (caret) no está presente en la especificación original | | (en XPath 2.0) | | Los nombres de propiedad del subobjeto de la tienda («book» y «bicycle»). Útil con propiedades comodín. | El nombre de propiedad (tilde) no está presente en la especificación original | | (en XPath 2.0) | | Todos los libros excepto el que se encuentra en la ruta que apunta al primero | no está presente en la especificación original | | | | Obtiene todas las categorías de libros donde el objeto padre del libro tiene un hijo bicicleta cuyo color es rojo (es decir, todos los libros) | no está presente en la especificación original | | | | Obtiene todos los hijos de «book» excepto los de «category» | no está presente en la especificación original | | | | Obtiene todos los libros cuya propiedad (que, al estar dentro de un array, es el índice numérico) no sea 0 | no está presente en la especificación original | | | | Obtiene los nietos de la tienda cuya propiedad padre no es book (es decir, los hijos de la bicicleta, «color» y «price») | no está presente en la especificación original | | | | Obtiene los valores de propiedad de todas las instancias de libro donde la propiedad padre de estos valores (es decir, el índice del array que contiene el objeto padre del elemento libro) no sea 0 | no está presente en la especificación original | | | | Filtrar todos los libros cuyo precio sea igual al precio del tercer libro | no está presente en la especificación original | | (en XPath 2.0) | | Obtener los valores numéricos dentro del array de libros | , los otros tipos básicos (, ), otros tipos derivados de bajo nivel (, , ), el tipo añadido por JSONSchema, , el tipo compuesto (que también acepta y números no finitos para objetos JavaScript, así como todos los tipos básicos no objeto/no función), el tipo , para usarse junto con un callback definido por el usuario (ver ), y los siguientes tipos no JSON que pueden usarse no obstante con JSONPath al consultar objetos JavaScript no JSON (, , ) no están presentes en la especificación original | | (XPath 2.0) | | Todas las categorías de libros que coinciden con la expresión regular (terminan en 'TION' sin distinguir mayúsculas de minúsculas) | no está presente en la especificación original. | | (XPath 2.0) | | Todos los libros que tienen una propiedad que coincide con la expresión regular (terminan en 'TION' sin distinguir mayúsculas de minúsculas) | no está presente en la especificación original. Nota: Usa el selector de padre al final de la expresión para volver al objeto padre; sin el selector de padre, coincide con los dos valores de clave . | | | (e.g., to match a property literally named ) | Escapa toda la secuencia siguiente (para que se trate como un literal) | no está presente en la especificación original; para obtener una comilla invertida literal, usa una comilla invertida adicional para escapar |Cualquier variable adicional proporcionada como propiedades de la opción de objeto opcional "sandbox" también está disponible para evaluaciones (basadas en paréntesis).

Posibles fuentes de confusión para usuarios de XPath

1. En JSONPath, una expresión de filtro, además de que su @ sea una referencia a sus hijos, en realidad también selecciona los hijos inmediatos, mientras que en XPath, las condiciones de filtro no seleccionan los hijos sino que delimitan cuáles de sus nodos padres se obtendrán en el resultado.
2. En JSONPath, los índices de array son, como en JavaScript, basados en 0 (comienzan desde 0), mientras que en XPath son basados en 1.
3. En JSONPath, las pruebas de igualdad utilizan (como en JavaScript) múltiples signos igual, mientras que en XPath usan un solo signo igual.

Interfaz de línea de comandos

Se proporciona una interfaz básica de línea de comandos (CLI). Accede a ella usando npx jsonpath-plus <json-file> <jsonpath-query>.

Ideas

1. Soportar OR fuera de los filtros (como en XPath |) y agrupación.
2. ¿Crear sintaxis que funcione como los filtros de XPath para no seleccionar hijos?
3. Permitir una opción para el equivalente de parentNode (manteniendo toda la cadena de objetos parent-and-parentProperty hasta la raíz)

Desarrollo

Ejecutar las pruebas en Node:```shell npm test

Para pruebas en el navegador:

- Sirve los archivos js/html:```shell
npm run browser-test

• Visita http://localhost:8082/test/.

Seguridad

Consulta SECURITY.md para conocer las consideraciones de seguridad importantes y las instrucciones sobre cómo reportar vulnerabilidades.

Licencia

Licencia MIT.