jsonpath-plus/jsonpathUm fork do JSONPath de http://goessner.net/articles/JsonPath/
[](https://www.npmjs.com/package/jsonpath-plus)
[](badges/tests-badge.svg)
[](badges/coverage-badge.svg)
[](https://snyk.io/test/github/s3u/JSONPath)
<!--[](LICENSE-MIT.txt)-->
[](badges/licenses-badge.svg)
[](https://github.com/JSONPath-Plus/JSONPath/actions/workflows/node.js.yml)
<small>(veja também [licenças para dependências de desenvolvimento.](https://raw.githubusercontent.com/s3u/JSONPath/master/badges/licenses-badge-dev.svg?sanitize=true))</small>
# JSONPath Plus
Analise, transforme e extraia seletivamente dados de documentos JSON
(e objetos JavaScript).
`jsonpath-plus` expande a especificação original para adicionar alguns
operadores adicionais e torna explícitos alguns comportamentos que a
original não especificava.
Experimente a [demonstração no navegador](https://jsonpath-plus.github.io/JSONPath/demo/) ou
[Runkit (Node)](https://npm.runkit.com/jsonpath-plus).
***Observe: Este projeto não está sendo mantido ativamente no momento. Podemos
aceitar PRs bem documentados ou algumas atualizações simples, mas não estamos
buscando fazer correções ou adicionar novos recursos por conta própria.***
## Recursos
* **Compatível** com a especificação jsonpath original
* **Adições ou elaborações** convenientes não fornecidas na especificação original:
* `^` para obter o **pai** de um item correspondente
* `~` para obter **nomes de propriedades** de itens correspondentes (como array)
* **Seletores de tipo** para obter:
* Tipos JSON básicos: `@null()`, `@boolean()`, `@number()`, `@string()`, `@array()`, `@object()`
* `@integer()`
* O tipo composto `@scalar()` (que também aceita `undefined` e
números não finitos ao consultar objetos JavaScript, bem como todos os tipos básicos não-objeto/não-função)
* `@other()` utilizável em conjunto com um `otherTypeCallback` definido pelo usuário
* Tipos não-JSON que ainda podem ser usados ao consultar
objetos JavaScript não-JSON (`@undefined()`, `@function()`, `@nonFinite()`)
* **Seletores abreviados** `@path`/`@parent`/`@property`/`@parentProperty`/`@root` dentro de filtros
* **Escape**
* `` ` `` para escapar a sequência restante
* Sintaxe `@['...']`/`?@['...']` para escapar caracteres especiais dentro de
nomes de propriedades em filtros
* Documenta `$..` (**obtendo todos os componentes pais**)
* Formatos de exportação **ESM** e **UMD**
* Além dos valores consultados, **pode retornar várias meta-informações**
incluindo caminhos ou ponteiros para o valor, bem como o objeto
pai e o nome da propriedade pai (para permitir modificação).
* **Utilitários para converter** entre caminhos, arrays e ponteiros
* Opção para **prevenir avaliações** permitidas na especificação original ou fornecer
um **sandbox** para valores avaliados.
* Opção para **callback para lidar com resultados** conforme são obtidos.
## Benchmarking
`jsonpath-plus` é consistentemente performático com conjuntos de dados grandes e pequenos em comparação com outras bibliotecas de consulta json, de acordo com [json-querying-performance-testing](https://github.com/andykais/json-querying-performance-testing). Você pode verificar essas descobertas [executando o projeto você mesmo](https://github.com/andykais/json-querying-performance-testing#how-to-run) e adicionando mais casos de desempenho.
## Instalação
```shell
npm install jsonpath-plus
```
## Configuração
### Node.js
```js
const {JSONPath} = require('jsonpath-plus');
const result = JSONPath({path: '...', json});
```
### Navegador
Para uso no navegador, você pode incluir diretamente `dist/index-browser-umd.cjs`; nenhuma
mágica do Browserify é necessária:
```html
<script src="node_modules/jsonpath-plus/dist/index-browser-umd.cjs"></script>
<script>
const result = JSONPath.JSONPath({path: '...', json: {}});
</script>
```
### ESM (Navegadores modernos)
Você também pode usar importações de Módulo 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 (Bundlers)
Ou, se você estiver empacotando seu JavaScript (por exemplo, com Rollup), basta usar,
observando que [`mainFields`](https://github.com/rollup/plugins/tree/master/packages/node-resolve#mainfields)
deve incluir `browser` para builds de navegador (para Node, o padrão, que
verifica `module`, deve ser suficiente):
```js
import {JSONPath} from 'jsonpath-plus';
const result = JSONPath({path: '...', json});
```
## Uso
A assinatura completa disponível é:
```
const result = JSONPath([options,] path, json, callback, otherTypeCallback);
```
Os argumentos `path`, `json`, `callback` e `otherTypeCallback`
podem, em alternativa, ser expressos (juntamente com qualquer outra das
propriedades disponíveis) em `options`.
Note que `result` conterá todos os itens encontrados (opcionalmente
envolvidos num array), enquanto `callback` pode ser usado se
pretender realizar alguma operação à medida que cada item é descoberto, sendo
a função de callback executada 0 a N vezes dependendo
do número de itens independentes a encontrar no resultado.
Consulte a documentação abaixo para mais informações sobre os argumentos disponíveis do `JSONPath`.
Consulte também a [documentação da API](https://jsonpath-plus.github.io/JSONPath/docs/ts/).
### Propriedades
As propriedades que podem ser fornecidas no objeto de opções ou no
método evaluate (como primeiro argumento) incluem:
- ***path*** (**obrigatório**) - A expressão JSONPath como uma string
(normalizada ou não normalizada) ou array
- ***json*** (**obrigatório**) - O objeto JSON a avaliar (seja do tipo
null, boolean, number, string, object ou array).
- ***autostart*** (**predefinição: true**) - Se for fornecido como `false`,
pode-se chamar o método `evaluate` manualmente.
- ***flatten*** (**predefinição: false**) - Se o array de resultados devolvido
será achatado num array unidimensional.
- ***resultType*** (**predefinição: "value"**) - Pode ser uma forma insensível a maiúsculas/minúsculas de
"value", "path", "pointer", "parent" ou "parentProperty" para determinar
respetivamente se deve devolver os resultados como os valores dos itens encontrados,
como os seus caminhos absolutos, como [JSON Pointers](https://tools.ietf.org/html/rfc6901)
para os caminhos absolutos, como os seus objetos pai, ou como o nome da propriedade
do seu pai. Se definido como "all", todos estes tipos serão devolvidos num
objeto com o tipo como nome da chave.
- ***sandbox*** (**predefinição: {}**) - Mapa chave-valor de variáveis a estarem
disponíveis para avaliações de código, como expressões de filtragem. (Note
que o caminho e o valor atuais também estarão disponíveis para essas
expressões; consulte a secção Sintaxe para detalhes.)
- ***wrap*** (**predefinição: true**) - Se deve ou não envolver os resultados
num array. Se `wrap` estiver definido como `false`, e não forem encontrados resultados,
será devolvido `undefined` (em oposição a um array vazio quando
`wrap` está definido como true). Se `wrap` estiver definido como `false` e for encontrado um único
resultado não-array, esse resultado será o único item devolvido
(não dentro de um array). No entanto, um array continuará a ser devolvido se forem encontrados múltiplos
resultados. Para evitar ambiguidades (no caso em que
é necessário distinguir entre um resultado que é uma falha
e um que é um array vazio), recomenda-se alterar a
predefinição para `false`.
- ***eval*** (**predefinição: "safe"**) - Método de avaliação de scripts.
`safe`: No browser, usará um motor de scripting mínimo que não
usa `eval` ou `Function` e satisfaz a Content Security Policy. No NodeJS,
não tem efeito e é equivalente a native, pois o scripting é seguro aí.
`native`: usa as capacidades nativas de scripting. ou seja, `eval` ou
`Function` inseguros no browser e `vm.Script` no nodejs. `false`: Desativa expressões
de avaliação JavaScript e lança exceções quando essas expressões são tentadas.
`callback [ (code, context) => value]`: Uma implementação personalizada que é chamada
com `code` e `context` como argumentos para devolver o valor avaliado.
`class`: Uma classe que é criada com `code` como argumento do construtor e o código
é avaliado chamando `runInNewContext` com `context`.
``
- ***ignoreEvalErrors*** (**predefinição: false**) - Ignora erros encontrados durante
a avaliação de scripts.
- ***parent*** (**predefinição: null**) - No caso de uma consulta poder
ser feita para devolver o nó raiz, isto permite que o pai desse nó raiz
seja devolvido nos resultados.
- ***parentProperty*** (**predefinição: null**) - No caso de uma consulta
poder ser feita para devolver o nó raiz, isto permite que a `parentProperty`
desse nó raiz seja devolvida nos resultados. Pode ser um nome de propriedade
string ou um índice de array numérico.
- ***callback*** (**predefinição: (nenhum)**) - Se fornecido, um callback será
chamado imediatamente após a obtenção de um valor de ponto final. Os três argumentos
fornecidos serão o valor do payload (de acordo com `resultType`),
o tipo do payload (se é um "value" normal ou um nome de "property"),
e um objeto payload completo (com todos os `resultType`s).
- ***otherTypeCallback*** (**predefinição: \<Uma função que lança um erro**
**quando @other() é encontrado\>**) - Na ausência atual de suporte a JSON
Schema, pode-se determinar tipos além dos tipos incorporados
adicionando o operador `@other()` no final da consulta. Se tal
caminho for encontrado, o `otherTypeCallback` será invocado com o
valor do item, o seu caminho, o seu pai, e o nome da propriedade do seu pai,
e deve devolver um booleano indicando se o valor fornecido
pertence ao tipo "other" ou não (ou pode tratar transformações e
devolver false).
- ***customTypes*** (**predefinição: {}**) - Um mapa chave-valor de nomes de tipos para funções.
Isto permite criar operadores de tipo personalizados que podem ser usados em consultas
(por exemplo, `@myType()`). A função será invocada com o valor do item,
o seu caminho, o seu pai, e o nome da propriedade do seu pai. Deve devolver um
booleano indicando se o valor fornecido corresponde ao tipo personalizado. Pode
também ser definido como:
1. O valor do import `jsonpath-plus/src/structuredCloningTypes.js` que predefine os seguintes tipos:
@NaN(), @BigIntObject(), @Date(), @Set(), @Map(), @RegExp(),
@Blob(optionalMimeType), @File(optionalMimeType), @Boolean(), @Number(),
@String(), @Infinity(), @negativeInfinity(), @negativeZero(),
@DOMException(), @Error(), @EvalError(), @RangeError(), @ReferenceError(),
@SyntaxError(), @TypeError(), @URIError(), @AggregateError(),
@QuotaExceededError(), @WebTransportError(), @FileList, @ArrayBuffer(),
@DataView(), @ImageData(), @ImageBitmap(), @Int8Array(), @Uint8Array(),
@Uint8ClampedArray(), @Int16Array(), @Uint16Array(), @Int32Array(),
@Uint32Array(), @Float32Array(), @Float64Array(), @BigInt64Array(),
@BigUint64Array(), @Float16Array, @DOMMatrix(), @DOMMatrixReadOnly(),
@DOMPoint(), @DOMPointReadOnly(), @DOMRect, @DOMRectReadOnly(),
@DOMQuad(), @CryptoKey(), @AudioData(), @EncodedAudioChunk(),
@EncodedVideoChunk(), @VideoFrame(), @CropTarget,
@FileSystemDirectoryHandle(), @FileSystemFileHandle(),
@GPUCompilationInfo(), @GPUCompilationMessage(),
@GPUPipelineError(), @RTCCertificate(), @RTCEncodedAudioFrame(),
@RTCEncodedVideoFrame()
2. O valor do import `jsonpath-plus/src/javascriptTypes.js` que predefine os seguintes tipos:
@Generator(), @AsyncGenerator(), @GeneratorFunction(),
@AsyncGeneratorFunction(), @Iterable(), @AsyncIterable(), @Iterator()
### Métodos de instância
- ***evaluate(path, json, callback, otherTypeCallback)*** OU
***evaluate({path: \<path\>, json: \<json object\>, callback:***
***\<callback function\>, otherTypeCallback:***
***\<otherTypeCallback function\>})*** - Este método só é
necessário se a propriedade `autostart` estiver definida como `false`. Pode
ser usado para avaliações repetidas usando a mesma configuração.
Além das propriedades listadas, o último padrão de método pode
aceitar qualquer uma das outras propriedades de instância permitidas (exceto
`autostart`, que não teria relevância aqui).
### Propriedades e métodos de classe
- ***JSONPath.clearCache()*** - Limpa os caminhos analisados e os scripts compilados
em cache interna. O conteúdo da cache não é exposto; chame este método quando
a invalidação da cache for necessária.
- ***JSONPath.toPathArray(pathAsString)*** - Aceita um caminho normalizado ou
não normalizado como string e converte num array: por
exemplo, `['$', 'aProperty', 'anotherProperty']`.
- ***JSONPath.toPathString(pathAsArray)*** - Aceita um array de caminho e
converte numa string de caminho normalizada. A string estará numa forma
como: `$['aProperty']['anotherProperty][0]`. As construções terminais do JSONPath `~` e `^`
e operadores de tipo como `@string()` são silenciosamente removidos.
- ***JSONPath.toPointer(pathAsArray)*** - Aceita um array de caminho e
converte num [JSON Pointer](https://tools.ietf.org/html/rfc6901).
A string estará numa forma como: `/aProperty/anotherProperty/0`
(com quaisquer caracteres internos `~` e `/` escapados conforme a especificação
JSON Pointer). As construções terminais do JSONPath `~` e `^` e
operadores de tipo como `@string()` são silenciosamente removidos.
## Sintaxe através de exemplos
Dado o seguinte JSON, retirado 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
}
}
}
```
e a seguinte representação 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>
```
Observe que os exemplos de XPath abaixo não distinguem entre
recuperar elementos e seu conteúdo de texto (exceto quando útil para
comparações ou para evitar ambiguidade). Nota: para testar os exemplos de XPath
(incluindo os de 2.0), [esta demonstração](http://videlibri.sourceforge.net/cgi-bin/xidelcgi)
pode ser útil (definida como `xml` ou `xml-strict`).
| XPath | JSONPath | Result | Notas |
|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `/store/book/author` | `$.store.book[*].author` | Os autores de todos os livros na loja | Também pode ser representado sem o `$.` como `store.book[*].author` (embora isso não esteja presente na especificação original); note que alguns literais de caracteres (`$` e `@`) exigem escape, no entanto |
| `//author` | `$..author` | Todos os autores | |
| `/store/*` | `$.store.*` | Todas as coisas na loja, que são seus livros (um array de livros) e uma bicicleta vermelha (um objeto bicicleta). | |
| `/store//price` | `$.store..price` | O preço de tudo na loja. | |
| `//book[3]` | `$..book[2]` | O terceiro livro (objeto livro) | |
| `//book[last()]` | `$..book[(@.length-1)]` <br> `$..book[-1:]` | O último livro em ordem. | Para acessar uma propriedade com um caractere especial, utilize `[(@['...'])]` para o filtro (este recurso específico não está presente na especificação original) |
| `//book[position()<3]` | `$..book[0,1]` <br> `$..book[:2]` | Os dois primeiros livros | |
| `//book/*[self::category\|self::author]` ou `//book/(category,author)` em XPath 2.0 | `$..book[0][category,author]` | As categorias e autores de todos os livros | |
| `//book[isbn]` | `$..book[?(@.isbn)]` | Filtra todos os livros com um número ISBN | Para acessar uma propriedade com um caractere especial, utilize `[?@['...']]` para o filtro (este recurso específico não está presente na especificação original) |
| `//book[price<10]` | `$..book[?(@.price<10)]` | Filtra todos os livros mais baratos que 10 | |
| `//*[name() = 'price' and . != 8.95]` | `$..*[?(@property === 'price' && @ !== 8.95)]` | Obtém todos os valores de propriedade de objetos cuja propriedade é price e que não é igual a 8.95 | Com o `@` simples permitindo filtrar objetos por valor de propriedade (não necessariamente dentro de arrays), você pode adicionar `^` após a expressão para obter o objeto que possui as propriedades filtradas |
| `/` | `$` | A raiz do objeto JSON (ou seja, o próprio objeto inteiro) | Para obter um `$` literal (por si só ou em qualquer lugar no caminho), você deve usar o escape com crase |
| `//*/*\|//*/*/text()` | `$..*` | Todos os Elementos (e texto) abaixo da raiz em um documento XML. Todos os membros de uma estrutura JSON abaixo da raiz. | |
| `//*` | `$..` | Todos os Elementos em um documento XML. Todos os componentes pais de uma estrutura JSON, incluindo a raiz. | Este comportamento não foi especificado diretamente na especificação original |
---
[Read more](https://github.com/jsonpath-plus/jsonpath)