JSONPath Plus

Анализируйте, преобразуйте и выборочно извлекайте данные из документов JSON (и объектов JavaScript).

jsonpath-plus расширяет исходную спецификацию, добавляя некоторые дополнительные операторы и делая явными некоторые поведения, которые не были описаны в оригинале.

Попробуйте демонстрацию в браузере или Runkit (Node).

Обратите внимание: этот проект в настоящее время не поддерживается активно. Мы можем принять хорошо задокументированные PR или некоторые простые обновления, но не ищем возможности исправлять ошибки или добавлять новые функции самостоятельно.

Особенности

• Соответствие оригинальной спецификации jsonpath.
• Удобные дополнения или уточнения, не представленные в исходной спецификации:
  • ^ для получения родителя соответствующего элемента.
  • ~ для получения имен свойств соответствующих элементов (в виде массива).
  • Селекторы типов для получения:
    • Базовых типов JSON: @null(), @boolean(), @number(), @string(), @array(), @object().
    • @integer().
    • Составного типа @scalar() (который также принимает undefined и неконечные числа при запросе объектов JavaScript, а также всех основных типов, отличных от объекта/функции).
    • @other(), который можно использовать вместе с определяемым пользователем otherTypeCallback.
    • Не-JSON типов, которые тем не менее можно использовать при запросах к объектам JavaScript, отличным от JSON (@undefined(), @function(), @nonFinite()).
  • @path/@parent/@property/@parentProperty/@root сокращенные селекторы в фильтрах.
  • Экранирование:
    • ` для экранирования оставшейся последовательности.
    • @['...']/?@['...'] синтаксис для экранирования специальных символов в именах свойств в фильтрах.
  • Документы $.. (получение всех родительских компонентов).
• Форматы экспорта ESM и UMD.
• В дополнение к запрашиваемым значениям можно возвращать различную метаинформацию, включая пути или указатели на значение, а также родительский объект и имя родительского свойства (чтобы разрешить изменение).
• Утилиты для преобразования между путями, массивами и указателями.
• Возможность предотвратить оценки, разрешенные в исходной спецификации, или предоставить песочницу для оцененных значений.
• Вариант для обратного вызова для обработки результатов по мере их получения.

Бенчмаркинг

jsonpath-plus стабильно работает как с большими, так и с малыми наборами данных по сравнению с другими библиотеками запросов JSON согласно... ## Установка

npm install jsonpath-plus

Настройка

Node.js

const {JSONPath} = require('jsonpath-plus');

const result = JSONPath({путь: '...', json});

Браузер

Для использования в браузере вы можете напрямую включить dist/index-browser-umd.cjs; магия Browserify не требуется:

<!-- Polyfill, рекомендованный Babel для элементов, не охваченных старыми браузерами в dist -->
<script src="node_modules/core-js-bundle/minified.js"></script>

<script src="node_modules/jsonpath-plus/dist/index-browser-umd.cjs"></script>

<script>

const result = JSONPath.JSONPath({путь: '...', json: {}});

</script>

ESM (современные браузеры)

Вы также можете использовать импорт модуля ES6 (для современных браузеров):

<script type="module">

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

const result = JSONPath({путь: '...', json: {}});

</script>

ESM (сборщики)

Или если вы собираете свой JavaScript (например, с помощью Rollup), просто используйте, отмечая, что mainFields должен включать browser для сборок браузера (для Node по умолчанию, который проверяет module, должно быть нормально):

import {JSONPath} from 'jsonpath-plus';

const result = JSONPath({путь: '...', json});

Использование

Доступна полная сигнатура:

const result = JSONPath([options,] путь, json, callback, otherTypeCallback);

Аргументы путь, json, callback и otherTypeCallback могут быть выражены альтернативно (вместе с любыми другими доступными свойствами) в options.

Обратите внимание, что result будет содержать все найденные элементы (необязательно заключённые в массив), тогда как callback можно использовать, если вы хотите выполнить некоторую операцию при обнаружении каждого элемента, причём функция обратного вызова выполняется от 0 до N раз в зависимости от количества независимых элементов, которые должны быть найдены в результате. Подробнее об аргументах JSONPath см. в документации ниже.

См. также документацию API.

Свойства

Свойства, которые можно предоставить в объекте параметров или методе оценки (в качестве первого аргумента), включают:

• путь (обязательно) — выражение JSONPath в виде (нормализованной или ненормализованной) строки или массива;

• json (обязательно) — объект JSON для оценки (нулевого, логического, числового, строкового, объектного или массивного типа).

• autostart (по умолчанию: true) — если это указано как false, можно вызвать метод evaluate вручную.

• flatten (по умолчанию: false) — будет ли возвращённый массив результатов сглажен до одномерного массива.

• resultType (по умолчанию: "value") — может быть регистронезависимой формой «value», «path», «pointer», «parent» или «parentProperty», чтобы определить соответственно, следует ли возвращать результаты как значения найденных элементов, как их абсолютные пути, как JSON Pointers к абсолютным путям, как их родительские объекты или как имя свойства их родителя. Если установлено значение «all», все эти типы будут возвращены в объекте с типом в качестве имени ключа.

• sandbox (по умолчанию: {}) — карта переменных ключ-значение, которая будет доступна для оценок кода, таких как фильтрующие выражения. (Обратите внимание, что текущий путь и значение также будут доступны для этих выражений; подробности см. в разделе «Синтаксис».)

• wrap (по умолчанию: true) — следует ли заключать результаты в массив. Если wrap установлено на false и результаты не найдены, будет возвращено undefined (в отличие от пустого массива, когда wrap установлен на true). Если wrap установлено на false и найден один результат, не являющийся массивом, этот результат будет единственным возвращаемым элементом (не внутри массива). Массив всё равно будет возвращён, если найдено несколько результатов. Найдено, однако. Чтобы избежать двусмысленности (в случае, когда необходимо различать результат, который является ошибкой, и пустой массив), рекомендуется установить значение по умолчанию в false.

• preventEval (default: false) — хотя выражения оценки JavaScript разрешены по умолчанию, из соображений безопасности (например, если вы работаете с ненадёжным пользовательским вводом) можно установить для этого параметра значение true, чтобы вызывать исключения при попытке использовать эти выражения.

• parent (default: null) — если запрос может быть выполнен так, чтобы вернуть корневой узел, этот параметр позволяет вернуть родителя этого корневого узла в результатах.

• parentProperty (default: null) — если запрос может быть выполнен так, чтобы вернуть корневой узел, этот параметр позволяет возвратить parentProperty этого корневого узла в результатах.

• callback (default: (none)) — если предоставлен, обратный вызов будет вызываться сразу после получения значения конечной точки. Будут предоставлены три аргумента: значение полезной нагрузки (согласно resultType), тип полезной нагрузки (является ли это обычным «значением» или именем «свойства») и полный объект полезной нагрузки (со всеми resultTypes).

• otherTypeCallback (default: <функция, которая выдаёт ошибку, когда @other() встречается>) — в настоящее время при отсутствии поддержки JSON Schema можно определить типы, выходящие за рамки встроенных типов, добавив оператор @other() в конце запроса. Если такой путь будет обнаружен, otherTypeCallback будет вызван со значением элемента, его пути, его родителя и имени свойства его родителя, и он должен возвращать логическое значение, указывающее, принадлежит ли предоставленное значение к типу «другой» (или он может обрабатывать преобразования и возвращать false).

Методы экземпляра

• evaluate(path, json, callback, otherTypeCallback) ИЛИ evaluate({path: <путь>, json: <объект json>, callback: <обратный вызов функции>, otherTypeCallback: <обратная функция otherTypeCallback>}) — этот метод необходим только в том случае, если для свойства autostart установлено значение false. Его можно использовать для повторных оценок с использованием той же конфигурации. Помимо перечисленных свойств, последний шаблон метода может принимать любой из других разрешённых свойств экземпляра (за исключением autostart, которое здесь не имеет значения).

Свойства и методы класса

• JSONPath.cache — предоставляет объект кэша для тех, кто хочет сохранить и повторно использовать его для оптимизации.

• JSONPath.toPathArray(pathAsString) — принимает нормализованный или ненормализованный путь в виде строки и преобразует его в массив: например, ['$', 'aProperty', 'anotherProperty'].

• JSONPath.toPathString(pathAsArray) — принимает массив путей и преобразует в нормализованную строку пути. Строка будет иметь вид: $['aProperty']['anotherProperty][0]. Конструкции терминала JSONPath ~ и ^ и операторы типов, такие как @string(), молча удаляются.

• JSONPath.toPointer(pathAsArray) — принимает массив путей и преобразует в JSON Pointer. Строка будет выглядеть следующим образом: /aProperty/anotherProperty/0 (с любыми внутренними символами ~ и /, экранированными в соответствии со спецификацией JSON Pointer). Конструкции терминала JSONPath ~ и ^ и операторы типов, такие как @string(), молча удаляются.

Синтаксис на примерах

Учитывая следующий JSON, взятый из http://goessner.net/articles/JsonPath/:

{
"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
    }
  ]
}
}
``` specific items with a price greater than 19 (i.e., the store value as the parent of the bicycle and the book array as parent of an individual book) | Parent (caret) not present in the original spec
/store/*/name() (in XPath 2.0)  | $.store.*~ | The property names of the store sub-object ("book" and "bicycle"). Useful with wildcard properties. | Property name (tilde) is not present in the original spec
/store/book\[not(. is /store/book\[1\])\] (in XPath 2.0) | $.store.book\[?(@path !== "$\[\'store\']\[\'book\']\[0]")] | All books besides that at the path pointing to the first | @path not present in the original spec
//book\[parent::\*/bicycle/color = "red"]/category | $..book\[?(@parent.bicycle && @parent.bicycle.color === "red")].category | Grabs all categories of books where the parent object of the book has a bicycle child whose color is red (i.e., all the books) | @parent is not present in the original spec
//book/*\[name() != 'category']     | $..book.*\[?(@property !== "category")] | Grabs all children of "book" except for "category" ones  | @property is not present in the original spec
//book\[position() != 1]    | $..book\[?(@property !== 0)] | Grabs all books whose property (which, being that we are reaching inside an array, is the numeric index) is not 0 | @property is not present in the original spec
/store/\*/\*\[name(parent::*) != 'book'] | $.store.*\[?(@parentProperty !== "book")] | Grabs the grandchildren of store whose parent property is not book (i.e., bicycle's children, "color" and "price") | @parentProperty is not present in the original spec
//book\[count(preceding-sibling::\*) != 0]/\*/text() | $..book.*\[?(@parentProperty !== 0)]  | Get the property values of all book instances whereby the parent property of these values (i.e., the array index holding the book item parent object) is not 0 | @parentProperty is not present in the original spec
//book\[price = /store/book\[3]/price] | $..book\[?(@.price === @root.store.book\[2].price)] | Filter all books whose price equals the price of the third book | @root is not present in the original spec
//book/../\*\[. instance of element(\*, xs:decimal)\] (in XPath 2.0) | $..book..\*@number() | Get the numeric values within the book array | @number(), the other basic types (@boolean(), @string()), other low-level derived types (@null(), @object(), @array()), the JSONSchema-added type, @integer(), the compound type @scalar() (which also accepts `undefined` and non-finite numbers for JavaScript objects as well as all of the basic non-object/non-function types), the type, @other(), to be used in conjunction with a user-defined callback (see `otherTypeCallback`) and the following non-JSON types that can nevertheless be used with JSONPath when querying non-JSON JavaScript objects (@undefined(), @function(), @nonFinite()) are not present in the original spec
//book/*[name() = 'category' and matches(., 'tion$')] (XPath 2.0) | $..book.*\[?(@property === "category" && @.match(/TION$/i))] | All categories of books which match the regex (end in 'TION' case insensitive)  | @property is not present in the original spec.
//book/*[matches(name(), 'bn$')]/parent::* (XPath 2.0) | $..book.*\[?(@property.match(/bn$/i))]^ | All books which have a property matching the regex (end in 'TION' case insensitive)  | @property is not present in the original spec. Note: Uses the parent selector \^ at the end of the expression to return to the parent object; without the parent selector, it matches the two `isbn` key values.