jsonpath-plus/jsonpathEin Fork von JSONPath von 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>(siehe auch [Lizenzen für Entwicklungsabhängigkeiten.](https://raw.githubusercontent.com/s3u/JSONPath/master/badges/licenses-badge-dev.svg?sanitize=true))</small>
# JSONPath Plus
Analysiere, transformiere und extrahiere selektiv Daten aus JSON-Dokumenten (und JavaScript-Objekten).
`jsonpath-plus` erweitert die ursprüngliche Spezifikation um einige zusätzliche Operatoren und macht einige Verhaltensweisen explizit, die das Original nicht ausdrücklich festgelegt hat.
Probiere die [Browser-Demo](https://jsonpath-plus.github.io/JSONPath/demo/) oder [Runkit (Node)](https://npm.runkit.com/jsonpath-plus) aus.
***Bitte beachte: Dieses Projekt wird derzeit nicht aktiv gepflegt. Wir akzeptieren möglicherweise gut dokumentierte PRs oder einige einfache Aktualisierungen, sind aber nicht bestrebt, selbst Fehlerbehebungen vorzunehmen oder neue Funktionen hinzuzufügen.***
## Funktionen
* **Konform** mit der ursprünglichen jsonpath-Spezifikation
* Praktische **Ergänzungen oder Erläuterungen**, die in der ursprünglichen Spezifikation nicht enthalten sind:
* `^` zum Erfassen des **Elternelements** eines übereinstimmenden Elements
* `~` zum Erfassen von **Eigenschaftsnamen** übereinstimmender Elemente (als Array)
* **Typselektoren** zum Abrufen von:
* Grundlegenden JSON-Typen: `@null()`, `@boolean()`, `@number()`, `@string()`, `@array()`, `@object()`
* `@integer()`
* Dem zusammengesetzten Typ `@scalar()` (der auch `undefined` und nicht-finite Zahlen akzeptiert, wenn JavaScript-Objekte abgefragt werden, sowie alle grundlegenden Nicht-Objekt-/Nicht-Funktions-Typen)
* `@other()`, verwendbar in Verbindung mit einem benutzerdefinierten `otherTypeCallback`
* Nicht-JSON-Typen, die dennoch bei der Abfrage von Nicht-JSON-JavaScript-Objekten verwendet werden können (`@undefined()`, `@function()`, `@nonFinite()`)
* `@path`/`@parent`/`@property`/`@parentProperty`/`@root` **Kurzselektoren** innerhalb von Filtern
* **Escaping**
* `` ` `` zum Escapen der verbleibenden Sequenz
* `@['...']`/`?@['...']`-Syntax zum Escapen von Sonderzeichen innerhalb von Eigenschaftsnamen in Filtern
* Dokumentiert `$..` (**Abrufen aller übergeordneten Komponenten**)
* **ESM**- und **UMD**-Exportformate
* Zusätzlich zu abgefragten Werten **können verschiedene Metainformationen zurückgegeben werden**, einschließlich Pfaden oder Zeigern auf den Wert sowie des übergeordneten Objekts und des Namens der übergeordneten Eigenschaft (um Änderungen zu ermöglichen).
* **Dienstprogramme zur Konvertierung** zwischen Pfaden, Arrays und Zeigern
* Option zum **Verhindern von Auswertungen**, die in der ursprünglichen Spezifikation erlaubt sind, oder zum Bereitstellen einer **Sandbox** für ausgewertete Werte.
* Option für einen **Callback zur Verarbeitung von Ergebnissen**, sobald sie erhalten werden.
## Benchmarking
`jsonpath-plus` ist im Vergleich zu anderen JSON-Abfragebibliotheken laut [json-querying-performance-testing](https://github.com/andykais/json-querying-performance-testing) sowohl bei großen als auch bei kleinen Datensätzen durchgängig leistungsfähig. Du kannst diese Ergebnisse überprüfen, indem du [das Projekt selbst ausführst](https://github.com/andykais/json-querying-performance-testing#how-to-run) und weitere Performance-Fälle hinzufügst.
## Installation
```shell
npm install jsonpath-plus
```
## Einrichtung
### Node.js
```js
const {JSONPath} = require('jsonpath-plus');
const result = JSONPath({path: '...', json});
```
### Browser
Für die Nutzung im Browser kannst du direkt `dist/index-browser-umd.cjs` einbinden; es ist keine
Browserify-Magie notwendig:
```html
<script src="node_modules/jsonpath-plus/dist/index-browser-umd.cjs"></script>
<script>
const result = JSONPath.JSONPath({path: '...', json: {}});
</script>
```
### ESM (Moderne Browser)
Sie können auch ES6-Modul-Importe verwenden (für moderne Browser):
```html
<script type="module">
import {
JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';
const result = JSONPath({path: '...', json: {}});
</script>
```
### ESM (Bundler)
Oder wenn Sie Ihr JavaScript bündeln (z. B. mit Rollup), verwenden Sie einfach
Folgendes, wobei zu beachten ist, dass [`mainFields`](https://github.com/rollup/plugins/tree/master/packages/node-resolve#mainfields)
`browser` für Browser-Builds enthalten sollte (für Node sollte der Standard,
der `module` prüft, in Ordnung sein):
```js
import {JSONPath} from 'jsonpath-plus';
const result = JSONPath({path: '...', json});
```
## Verwendung
Die vollständige verfügbare Signatur ist:
```
const result = JSONPath([options,] path, json, callback, otherTypeCallback);
```
Die Argumente `path`, `json`, `callback` und `otherTypeCallback`
können alternativ (zusammen mit allen anderen der
verfügbaren Eigenschaften) in `options` angegeben werden.
Beachten Sie, dass `result` alle gefundenen Elemente enthält (optional
in ein Array verpackt), während `callback` verwendet werden kann, wenn Sie
eine Operation ausführen möchten, sobald jedes Element entdeckt wird, wobei
die Callback-Funktion 0 bis N Mal ausgeführt wird, abhängig
von der Anzahl der unabhängigen Elemente, die im Ergebnis gefunden werden.
Weitere Informationen zu den verfügbaren Argumenten von `JSONPath` finden Sie in der Dokumentation unten.
Siehe auch die [API-Dokumentation](https://jsonpath-plus.github.io/JSONPath/docs/ts/).
### Eigenschaften
Die Eigenschaften, die im Optionsobjekt oder in der
evaluate-Methode (als erstes Argument) angegeben werden können, umfassen:
- ***path*** (**erforderlich**) - Der JSONPath-Ausdruck als (normalisierter
oder unnormalisierter) String oder Array
- ***json*** (**erforderlich**) - Das JSON-Objekt, das ausgewertet werden soll (sei es vom
Typ null, boolean, number, string, object oder array).
- ***autostart*** (**Standard: true**) - Wenn dies als `false` angegeben wird,
kann man die `evaluate`-Methode manuell aufrufen.
- ***flatten*** (**Standard: false**) - Ob das zurückgegebene Array von Ergebnissen
auf ein eindimensionales Array reduziert wird.
- ***resultType*** (**Standard: "value"**) - Kann eine Form (ohne Beachtung der Groß-/Kleinschreibung) von
"value", "path", "pointer", "parent" oder "parentProperty" sein, um festzulegen,
ob Ergebnisse als die Werte der gefundenen Elemente,
als deren absolute Pfade, als [JSON Pointers](https://tools.ietf.org/html/rfc6901)
zu den absoluten Pfaden, als deren übergeordnete Objekte oder als der
Eigenschaftsname des übergeordneten Objekts zurückgegeben werden. Wenn auf "all" gesetzt, werden alle diese Typen
in einem Objekt mit dem Typ als Schlüsselname zurückgegeben.
- ***sandbox*** (**Standard: {}**) - Key-Value-Map von Variablen, die
für Code-Auswertungen wie Filterausdrücke verfügbar sein sollen. (Beachten Sie,
dass der aktuelle Pfad und Wert auch für diese
Ausdrücke verfügbar sein werden; siehe den Abschnitt Syntax für Details.)
- ***wrap*** (**Standard: true**) - Ob die Ergebnisse
in ein Array verpackt werden sollen oder nicht. Wenn `wrap` auf `false` gesetzt ist und keine Ergebnisse gefunden werden,
wird `undefined` zurückgegeben (im Gegensatz zu einem leeren Array, wenn
`wrap` auf true gesetzt ist). Wenn `wrap` auf `false` gesetzt ist und ein einzelnes
Nicht-Array-Ergebnis gefunden wird, wird dieses Ergebnis das einzige zurückgegebene Element sein
(nicht innerhalb eines Arrays). Ein Array wird jedoch weiterhin zurückgegeben, wenn mehrere
Ergebnisse gefunden werden. Um Mehrdeutigkeiten zu vermeiden (in dem Fall, in dem
es notwendig ist, zwischen einem Ergebnis, das ein Fehler ist,
und einem, das ein leeres Array ist, zu unterscheiden), wird empfohlen, den
Standard auf `false` umzustellen.
- ***eval*** (**Standard: "safe"**) - Skript-Auswertungsmethode.
`safe`: Im Browser wird eine minimale Skript-Engine verwendet, die weder
`eval` noch `Function` nutzt und die Content Security Policy erfüllt. In NodeJS
hat es keine Wirkung und entspricht native, da Skripting dort sicher ist.
`native`: verwendet die nativen Skript-Fähigkeiten. D.h. unsicheres `eval` oder
`Function` im Browser und `vm.Script` in nodejs. `false`: Deaktiviert JavaScript-
Auswertungsausdrücke und wirft Ausnahmen, wenn diese Ausdrücke versucht werden.
`callback [ (code, context) => value]`: Eine benutzerdefinierte Implementierung, die
mit `code` und `context` als Argumente aufgerufen wird, um den ausgewerteten Wert zurückzugeben.
`class`: Eine Klasse, die mit `code` als Konstruktorargument erstellt wird und deren Code
durch Aufruf von `runInNewContext` mit `context` ausgewertet wird.
``
- ***ignoreEvalErrors*** (**Standard: false**) - Ignoriert Fehler, die während
der Skript-Auswertung auftreten.
- ***parent*** (**Standard: null**) - Für den Fall, dass eine Abfrage
den Wurzelknoten zurückgeben könnte, ermöglicht dies, dass das übergeordnete Element dieses Wurzelknotens
in den Ergebnissen zurückgegeben wird.
- ***parentProperty*** (**Standard: null**) - Für den Fall, dass eine Abfrage
den Wurzelknoten zurückgeben könnte, ermöglicht dies, dass die `parentProperty`
dieses Wurzelknotens in den Ergebnissen zurückgegeben wird. Dies kann ein String-
Eigenschaftsname oder ein numerischer Array-Index sein.
- ***callback*** (**Standard: (keine)**) - Wenn angegeben, wird ein Callback
sofort beim Abrufen eines Endpunktwerts aufgerufen. Die drei übergebenen Argumente
sind der Wert der Nutzlast (gemäß `resultType`),
der Typ der Nutzlast (ob es sich um einen normalen "value" oder einen "property"-
Namen handelt) und ein vollständiges Nutzlastobjekt (mit allen `resultType`s).
- ***otherTypeCallback*** (**Standard: \<Eine Funktion, die einen Fehler wirft,**
**wenn @other() angetroffen wird\>**) - In der derzeitigen Abwesenheit von JSON
Schema-Unterstützung kann man Typen jenseits der eingebauten Typen bestimmen, indem
man den Operator `@other()` am Ende seiner Abfrage hinzufügt. Wenn ein solcher
Pfad angetroffen wird, wird der `otherTypeCallback` mit dem
Wert des Elements, seinem Pfad, seinem übergeordneten Element und dem Eigenschaftsnamen seines übergeordneten Elements aufgerufen,
und er sollte einen booleschen Wert zurückgeben, der angibt, ob der übergebene Wert
zum "other"-Typ gehört oder nicht (oder er kann Transformationen handhaben und
false zurückgeben).
- ***customTypes*** (**Standard: {}**) - Eine Key-Value-Map von Typnamen zu Funktionen.
Dies ermöglicht die Erstellung benutzerdefinierter Typoperatoren, die in Abfragen
verwendet werden können (z. B. `@myType()`). Die Funktion wird mit dem Wert des Elements,
seinem Pfad, seinem übergeordneten Element und dem Eigenschaftsnamen seines übergeordneten Elements aufgerufen. Sie sollte einen
booleschen Wert zurückgeben, der angibt, ob der übergebene Wert zum benutzerdefinierten Typ passt. Kann
auch gesetzt werden auf:
1. Den Wert des Imports `jsonpath-plus/src/structuredCloningTypes.js`, der die folgenden Typen vordefiniert:
@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. Den Wert des Imports `jsonpath-plus/src/javascriptTypes.js`, der die folgenden Typen vordefiniert:
@Generator(), @AsyncGenerator(), @GeneratorFunction(),
@AsyncGeneratorFunction(), @Iterable(), @AsyncIterable(), @Iterator()
### Instanzmethoden
- ***evaluate(path, json, callback, otherTypeCallback)*** ODER
***evaluate({path: \<path\>, json: \<json object\>, callback:***
***\<callback function\>, otherTypeCallback:***
***\<otherTypeCallback function\>})*** - Diese Methode ist nur
notwendig, wenn die `autostart`-Eigenschaft auf `false` gesetzt ist. Sie
kann für wiederholte Auswertungen mit derselben Konfiguration verwendet werden.
Neben den aufgeführten Eigenschaften kann das letztere Methodenmuster
jede der anderen erlaubten Instanzeigenschaften akzeptieren (außer
`autostart`, das hier keine Relevanz hätte).
### Klassen-Eigenschaften und -Methoden
- ***JSONPath.clearCache()*** - Löscht die intern zwischengespeicherten geparsten Pfade und
kompilierten Skripte. Der Cache-Inhalt wird nicht offengelegt; rufen Sie diese Methode auf, wenn
eine Cache-Invalidierung erforderlich ist.
- ***JSONPath.toPathArray(pathAsString)*** - Akzeptiert einen normalisierten oder
unnormalisierten Pfad als String und konvertiert ihn in ein Array: zum
Beispiel `['$', 'aProperty', 'anotherProperty']`.
- ***JSONPath.toPathString(pathAsArray)*** - Akzeptiert ein Pfad-Array und
konvertiert es in einen normalisierten Pfad-String. Der String wird in einer Form
wie: `$['aProperty']['anotherProperty][0]` vorliegen. Die JSONPath-Terminal-
Konstruktionen `~` und `^` und Typoperatoren wie `@string()` werden
stillschweigend entfernt.
- ***JSONPath.toPointer(pathAsArray)*** - Akzeptiert ein Pfad-Array und
konvertiert es in einen [JSON Pointer](https://tools.ietf.org/html/rfc6901).
Der String wird in einer Form wie: `/aProperty/anotherProperty/0`
vorliegen (wobei alle internen `~`- und `/`-Zeichen gemäß der JSON
Pointer-Spezifikation escaped werden). Die JSONPath-Terminal-Konstruktionen `~` und `^` und
Typoperatoren wie `@string()` werden stillschweigend entfernt.
## Syntax anhand von Beispielen
Angesichts des folgenden JSON, entnommen von <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
}
}
}
```
und die folgende XML-Darstellung:
```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>
```
Bitte beachten Sie, dass die folgenden XPath-Beispiele nicht zwischen
dem Abrufen von Elementen und ihrem Textinhalt unterscheiden (außer wo es
für Vergleiche nützlich ist oder um Mehrdeutigkeit zu vermeiden). Hinweis: Um die XPath-Beispiele
(einschließlich der 2.0-Beispiele) zu testen, kann [diese Demo](http://videlibri.sourceforge.net/cgi-bin/xidelcgi)
hilfreich sein (auf `xml` oder `xml-strict` gesetzt).
| XPath | JSONPath | Ergebnis | Hinweise |
|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `/store/book/author` | `$.store.book[*].author` | Die Autoren aller Bücher im Store | Kann auch ohne das `$.` als `store.book[*].author` dargestellt werden (obwohl dies nicht in der ursprünglichen Spezifikation vorhanden ist); beachten Sie, dass einige Zeichenliterale (`$` und `@`) jedoch escapt werden müssen |
| `//author` | `$..author` | Alle Autoren | |
| `/store/*` | `$.store.*` | Alle Dinge im Store, das sind seine Bücher (ein Buch-Array) und ein rotes Fahrrad (ein Fahrrad-Objekt). | |
| `/store//price` | `$.store..price` | Der Preis von allem im Store. | |
| `//book[3]` | `$..book[2]` | Das dritte Buch (Buch-Objekt) | |
| `//book[last()]` | `$..book[(@.length-1)]` <br> `$..book[-1:]` | Das letzte Buch in der Reihenfolge. | Um auf eine Eigenschaft mit einem Sonderzeichen zuzugreifen, verwenden Sie `[(@['...'])]` für den Filter (dieses spezielle Feature ist nicht in der ursprünglichen Spezifikation vorhanden) |
| `//book[position()<3]` | `$..book[0,1]` <br> `$..book[:2]` | Die ersten beiden Bücher | |
| `//book/*[self::category\|self::author]` oder `//book/(category,author)` in XPath 2.0 | `$..book[0][category,author]` | Die Kategorien und Autoren aller Bücher | |
| `//book[isbn]` | `$..book[?(@.isbn)]` | Alle Bücher mit einer ISBN-Nummer filtern | Um auf eine Eigenschaft mit einem Sonderzeichen zuzugreifen, verwenden Sie `[?@['...']]` für den Filter (dieses spezielle Feature ist nicht in der ursprünglichen Spezifikation vorhanden) |
| `//book[price<10]` | `$..book[?(@.price<10)]` | Alle Bücher filtern, die günstiger als 10 sind | |
| `//*[name() = 'price' and . != 8.95]` | `$..*[?(@property === 'price' && @ !== 8.95)]` | Alle Eigenschaftswerte von Objekten abrufen, deren Eigenschaft price ist und die nicht gleich 8.95 ist | Mit dem bloßen `@`, das das Filtern von Objekten nach Eigenschaftswert ermöglicht (nicht unbedingt innerhalb von Arrays), können Sie `^` nach dem Ausdruck hinzufügen, um das Objekt zu erhalten, das die gefilterten Eigenschaften besitzt |
| `/` | `$` | Die Wurzel des JSON-Objekts (d. h. das gesamte Objekt selbst) | Um ein literales `$` zu erhalten (allein oder irgendwo im Pfad), müssen Sie den Backtick-Escape verwenden |
| `//*/*\|//*/*/text()` | `$..*` | Alle Elemente (und Text) unterhalb der Wurzel in einem XML-Dokument. Alle Mitglieder einer JSON-Struktur unterhalb der Wurzel. | |
---
[Read more](https://github.com/jsonpath-plus/jsonpath)