jsonpath-plus/jsonpathhttp://goessner.net/articles/JsonPath/ 에서 가져온 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>(개발 의존성에 대한 [라이선스](https://raw.githubusercontent.com/s3u/JSONPath/master/badges/licenses-badge-dev.svg?sanitize=true)도 참조하세요.)</small>
# JSONPath Plus
JSON 문서(및 JavaScript 객체)에서 데이터를 분석, 변환, 선택적으로 추출합니다.
`jsonpath-plus`는 원래 명세를 확장하여 몇 가지 추가 연산자를 제공하고, 원래 명세에서 명시하지 않았던 일부 동작을 명확히 합니다.
[브라우저 데모](https://jsonpath-plus.github.io/JSONPath/demo/) 또는 [Runkit (Node)](https://npm.runkit.com/jsonpath-plus)를 사용해 보세요.
***참고: 이 프로젝트는 현재 활발히 유지보수되고 있지 않습니다. 문서화가 잘 된 PR이나 간단한 업데이트는 수용할 수 있지만, 직접 수정하거나 새로운 기능을 추가할 계획은 없습니다.***
## 기능
* 원래 jsonpath 명세와 **호환**됩니다
* 원래 명세에서 제공하지 않는 편리한 **추가 또는 확장** 기능:
* 일치하는 항목의 **부모**를 가져오는 `^`
* 일치하는 항목의 **속성 이름**을 (배열로) 가져오는 `~`
* 다음을 얻기 위한 **타입 선택자**:
* 기본 JSON 타입: `@null()`, `@boolean()`, `@number()`, `@string()`, `@array()`, `@object()`
* `@integer()`
* 복합 타입 `@scalar()` (JavaScript 객체를 쿼리할 때 `undefined`와 비유한 숫자도 허용하며, 모든 기본 비객체/비함수 타입도 포함)
* 사용자 정의 `otherTypeCallback`과 함께 사용할 수 있는 `@other()`
* 비JSON JavaScript 객체를 쿼리할 때 사용할 수 있는 비JSON 타입 (`@undefined()`, `@function()`, `@nonFinite()`)
* 필터 내 **축약 선택자** `@path`/`@parent`/`@property`/`@parentProperty`/`@root`
* **이스케이프**
* 남은 시퀀스를 이스케이프하는 `` ` ``
* 필터 내 속성 이름의 특수 문자를 이스케이프하는 `@['...']`/`?@['...']` 구문
* `$..` (**모든 부모 구성 요소 가져오기**) 문서화
* **ESM** 및 **UMD** 내보내기 형식
* 쿼리된 값 외에도 값에 대한 경로나 포인터, 부모 객체 및 부모 속성 이름(수정을 허용하기 위해)을 포함한 **다양한 메타 정보를 반환**할 수 있습니다.
* 경로, 배열, 포인터 간 **변환 유틸리티**
* 원래 명세에서 허용된 **평가를 방지**하거나 평가된 값에 대한 **샌드박스**를 제공하는 옵션.
* 결과가 얻어질 때 **결과를 처리하는 콜백** 옵션.
## 벤치마킹
`jsonpath-plus`는 [json-querying-performance-testing](https://github.com/andykais/json-querying-performance-testing)에 따르면 다른 json 쿼리 라이브러리와 비교하여 크고 작은 데이터셋 모두에서 일관되게 성능이 우수합니다. [프로젝트를 직접 실행](https://github.com/andykais/json-querying-performance-testing#how-to-run)하고 더 많은 성능 사례를 추가하여 이러한 결과를 확인할 수 있습니다.
## 설치
```shell
npm install jsonpath-plus
```
## 설정
### Node.js
```js
const {JSONPath} = require('jsonpath-plus');
const result = JSONPath({path: '...', json});
```
### 브라우저
브라우저에서 사용하려면 `dist/index-browser-umd.cjs`를 직접 포함하면 됩니다.
Browserify 마법은 필요하지 않습니다:
```html
<script src="node_modules/jsonpath-plus/dist/index-browser-umd.cjs"></script>
<script>
const result = JSONPath.JSONPath({path: '...', json: {}});
</script>
```
### ESM (최신 브라우저)
최신 브라우저를 위한 ES6 모듈 임포트를 사용할 수도 있습니다:
```html
<script type="module">
import {
JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';
const result = JSONPath({path: '...', json: {}});
</script>
```
### ESM (번들러)
또는 JavaScript를 번들링하는 경우(예: Rollup 사용), 다음을 사용하면 되며,
[`mainFields`](https://github.com/rollup/plugins/tree/master/packages/node-resolve#mainfields)에
브라우저 빌드의 경우 `browser`가 포함되어야 한다는 점에 유의하세요(Node의 경우
`module`을 확인하는 기본값이면 충분합니다):
```js
import {JSONPath} from 'jsonpath-plus';
const result = JSONPath({path: '...', json});
```
## 사용법
사용 가능한 전체 시그니처는 다음과 같습니다:
```
const result = JSONPath([options,] path, json, callback, otherTypeCallback);
```
인수 `path`, `json`, `callback`, `otherTypeCallback`은
`options`에서 (사용 가능한 다른 속성들과 함께) 대안적으로
표현될 수 있습니다.
`result`는 발견된 모든 항목을 (선택적으로 배열로
감싸서) 포함하는 반면, `callback`은 각 항목이 발견될 때마다
어떤 작업을 수행하고자 할 때 사용할 수 있으며, 콜백 함수는
결과에서 발견되는 독립적인 항목의 수에 따라 0회에서 N회까지
실행됩니다. `JSONPath`의 사용 가능한 인수에 대한 자세한 내용은
아래 문서를 참조하십시오.
[API 문서](https://jsonpath-plus.github.io/JSONPath/docs/ts/)도 참조하십시오.
### 속성
options 객체 또는 evaluate 메서드(첫 번째 인수로서)에
제공될 수 있는 속성은 다음과 같습니다:
- ***path*** (**필수**) - (정규화되거나 정규화되지 않은) 문자열
또는 배열로서의 JSONPath 표현식
- ***json*** (**필수**) - 평가할 JSON 객체 (null, boolean, number,
string, object, array 타입 여부와 무관).
- ***autostart*** (**기본값: true**) - 이것이 `false`로 제공되면,
`evaluate` 메서드를 수동으로 호출할 수 있습니다.
- ***flatten*** (**기본값: false**) - 반환된 결과 배열이
1차원 배열로 평탄화될지 여부.
- ***resultType*** (**기본값: "value"**) - 대소문자를 구분하지 않는
형태의 "value", "path", "pointer", "parent", "parentProperty"로,
각각 발견된 항목의 값, 절대 경로, 절대 경로에 대한
[JSON Pointer](https://tools.ietf.org/html/rfc6901), 부모 객체,
또는 부모의 속성 이름으로 결과를 반환할지 결정합니다. "all"로
설정하면, 이 모든 타입이 타입을 키 이름으로 하는 객체에
반환됩니다.
- ***sandbox*** (**기본값: {}**) - 필터링 표현식과 같은 코드 평가에
사용할 수 있는 변수의 키-값 맵. (현재 경로와 값도 해당
표현식에서 사용할 수 있습니다; 자세한 내용은 구문 섹션을
참조하십시오.)
- ***wrap*** (**기본값: true**) - 결과를 배열로 감쌀지 여부.
`wrap`이 `false`로 설정되고 결과가 발견되지 않으면,
`undefined`가 반환됩니다 (`wrap`이 true일 때의 빈 배열과는
대조적). `wrap`이 `false`이고 단일 비배열 결과가 발견되면,
그 결과가 유일한 반환 항목이 됩니다 (배열 내에 있지 않음).
그러나 여러 결과가 발견되면 여전히 배열이 반환됩니다.
모호성을 피하기 위해 (결과가 실패인 경우와 빈 배열인 경우를
구분할 필요가 있는 경우), 기본값을 `false`로 전환하는 것이
권장됩니다.
- ***eval*** (**기본값: "safe"**) - 스크립트 평가 메서드.
`safe`: 브라우저에서는 `eval`이나 `Function`을 사용하지 않고
Content Security Policy를 충족하는 최소한의 스크립팅 엔진을
사용합니다. NodeJS에서는 효과가 없으며 스크립팅이 안전하므로
네이티브와 동일합니다.
`native`: 네이티브 스크립팅 기능을 사용합니다. 즉, 브라우저에서는
안전하지 않은 `eval` 또는 `Function`, nodejs에서는 `vm.Script`를
사용합니다. `false`: JavaScript 평가 표현식을 비활성화하고
이러한 표현식이 시도될 때 예외를 발생시킵니다.
`callback [ (code, context) => value]`: `code`와 `context`를
인수로 호출되어 평가된 값을 반환하는 사용자 정의 구현.
`class`: `code`를 생성자 인수로 생성되고 `context`와 함께
`runInNewContext`를 호출하여 코드가 평가되는 클래스.
``
- ***ignoreEvalErrors*** (**기본값: false**) - 스크립트 평가 중
발생한 오류를 무시합니다.
- ***parent*** (**기본값: null**) - 쿼리가 루트 노드를 반환하도록
만들어진 경우, 이는 해당 루트 노드의 부모가 결과 내에서
반환되도록 허용합니다.
- ***parentProperty*** (**기본값: null**) - 쿼리가 루트 노드를
반환하도록 만들어진 경우, 이는 해당 루트 노드의 `parentProperty`가
결과 내에서 반환되도록 허용합니다. 이는 문자열 속성 이름이나
숫자 배열 인덱스일 수 있습니다.
- ***callback*** (**기본값: (없음)**) - 제공되면, 종단점 값의
검색 시 즉시 콜백이 호출됩니다. 제공되는 세 인수는 페이로드의
값 (`resultType`에 따름), 페이로드의 타입 (일반 "value"인지
"property" 이름인지), 그리고 전체 페이로드 객체 (모든
`resultType` 포함)입니다.
- ***otherTypeCallback*** (**기본값: \<@other()가 발생했을 때**
**오류를 발생시키는 함수\>**) - 현재 JSON Schema 지원이 없는
상황에서, 쿼리 끝에 `@other()` 연산자를 추가하여 내장 타입
이외의 타입을 판별할 수 있습니다. 그러한 경로가 발생하면,
`otherTypeCallback`이 항목의 값, 경로, 부모, 부모의 속성 이름과
함께 호출되며, 제공된 값이 "other" 타입에 속하는지 여부를
나타내는 boolean을 반환해야 합니다 (또는 변환을 처리하고
false를 반환할 수도 있습니다).
- ***customTypes*** (**기본값: {}**) - 타입 이름에서 함수로의
키-값 맵. 이를 통해 쿼리에서 사용할 수 있는 사용자 정의 타입
연산자를 만들 수 있습니다 (예: `@myType()`). 함수는 항목의 값,
경로, 부모, 부모의 속성 이름과 함께 호출됩니다. 제공된 값이
사용자 정의 타입과 일치하는지 여부를 나타내는 boolean을
반환해야 합니다. 다음과 같이 설정할 수도 있습니다:
1. 다음 타입들을 미리 정의하는 `jsonpath-plus/src/structuredCloningTypes.js` import의 값:
@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. 다음 타입들을 미리 정의하는 `jsonpath-plus/src/javascriptTypes.js` import의 값:
@Generator(), @AsyncGenerator(), @GeneratorFunction(),
@AsyncGeneratorFunction(), @Iterable(), @AsyncIterable(), @Iterator()
### 인스턴스 메서드
- ***evaluate(path, json, callback, otherTypeCallback)*** 또는
***evaluate({path: \<path\>, json: \<json object\>, callback:***
***\<callback function\>, otherTypeCallback:***
***\<otherTypeCallback function\>})*** - 이 메서드는
`autostart` 속성이 `false`로 설정된 경우에만 필요합니다.
동일한 구성으로 반복 평가하는 데 사용할 수 있습니다.
나열된 속성 외에도, 후자의 메서드 패턴은 다른 허용된
인스턴스 속성들 중 어느 것이든 받아들일 수 있습니다
(여기서는 관련이 없는 `autostart`는 제외).
### 클래스 속성 및 메서드
- ***JSONPath.clearCache()*** - 내부적으로 캐시된 파싱된 경로와
컴파일된 스크립트를 지웁니다. 캐시 내용은 노출되지 않습니다;
캐시 무효화가 필요할 때 이 메서드를 호출하십시오.
- ***JSONPath.toPathArray(pathAsString)*** - 정규화되거나
정규화되지 않은 경로를 문자열로 받아 배열로 변환합니다:
예를 들어, `['$', 'aProperty', 'anotherProperty']`.
- ***JSONPath.toPathString(pathAsArray)*** - 경로 배열을 받아
정규화된 경로 문자열로 변환합니다. 문자열은 다음과 같은
형태가 됩니다: `$['aProperty']['anotherProperty][0]`. JSONPath
종단 구문 `~`와 `^` 그리고 `@string()`과 같은 타입 연산자는
조용히 제거됩니다.
- ***JSONPath.toPointer(pathAsArray)*** - 경로 배열을 받아
[JSON Pointer](https://tools.ietf.org/html/rfc6901)로
변환합니다. 문자열은 다음과 같은 형태가 됩니다:
`/aProperty/anotherProperty/0` (JSON Pointer 사양에 따라
내부 문자 `~`와 `/`는 이스케이프됨). JSONPath 종단 구문
`~`와 `^` 그리고 `@string()`과 같은 타입 연산자는 조용히
제거됩니다.
## 예제를 통한 구문
<http://goessner.net/articles/JsonPath/>에서 가져온 다음 JSON이
주어졌을 때:
```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
}
}
}
```
and the following XML representation:
```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>
```
아래 XPath 예제들은 요소와 그 텍스트 콘텐츠를 검색하는 것을 구분하지 않는다는 점에 유의하십시오(비교에 유용하거나 모호함을 방지하기 위해 필요한 경우는 제외). 참고: XPath 예제(2.0 예제 포함)를 테스트하려면 [이 데모](http://videlibri.sourceforge.net/cgi-bin/xidelcgi)가 도움이 될 수 있습니다(`xml` 또는 `xml-strict`로 설정).
| XPath | JSONPath | 결과 | 참고 |
|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `/store/book/author` | `$.store.book[*].author` | 상점에 있는 모든 책의 저자 | `$.` 없이 `store.book[*].author`로도 표현할 수 있다(원래 명세에는 없음). 다만 일부 문자 리터럴(`$`와 `@`)은 이스케이프가 필요하다는 점에 유의 |
| `//author` | `$..author` | 모든 저자 | |
| `/store/*` | `$.store.*` | 상점에 있는 모든 것, 즉 책들(book 배열)과 빨간 자전거(bicycle 객체). | |
| `/store//price` | `$.store..price` | 상점에 있는 모든 것의 가격. | |
| `//book[3]` | `$..book[2]` | 세 번째 책(book 객체) | |
| `//book[last()]` | `$..book[(@.length-1)]` <br> `$..book[-1:]` | 순서상 마지막 책. | 특수 문자가 있는 속성에 접근하려면 필터에 `[(@['...'])]`를 사용한다(이 특정 기능은 원래 명세에는 없음) |
| `//book[position()<3]` | `$..book[0,1]` <br> `$..book[:2]` | 처음 두 권의 책 | |
| `//book/*[self::category\|self::author]` 또는 XPath 2.0의 `//book/(category,author)` | `$..book[0][category,author]` | 모든 책의 카테고리와 저자 | |
| `//book[isbn]` | `$..book[?(@.isbn)]` | ISBN 번호가 있는 모든 책 필터링 | 특수 문자가 있는 속성에 접근하려면 필터에 `[?@['...']]`를 사용한다(이 특정 기능은 원래 명세에는 없음) |
| `//book[price<10]` | `$..book[?(@.price<10)]` | 가격이 10 미만인 모든 책 필터링 | |
| `//*[name() = 'price' and . != 8.95]` | `$..*[?(@property === 'price' && @ !== 8.95)]` | 속성이 price이고 8.95와 같지 않은 객체의 모든 속성 값 가져오기 | 단독 `@`를 사용하면 (반드시 배열 내에 있지 않더라도) 속성 값으로 객체를 필터링할 수 있으며, 표현식 뒤에 `^`를 추가하면 필터링된 속성을 가진 객체 자체를 얻을 수 있다 |
| `/` | `$` | JSON 객체의 루트(즉, 객체 전체 자체) | 리터럴 `$`(단독이든 경로 어디에서든)를 얻으려면 백틱 이스케이프를 사용해야 한다 |
| `//*/*\|//*/*/text()` | `$..*` | XML 문서에서 루트 아래의 모든 요소(및 텍스트). 루트 아래의 JSON 구조의 모든 멤버. | |
| `//*` | `$..` | XML 문서의 모든 요소. 루트를 포함한 JSON 구조의 모든 상위 구성 요소. | 이 동작은 원래 명세에 직접 명시되지 않았다 |
---
[Read more](https://github.com/jsonpath-plus/jsonpath)