jsonpath-plus/jsonpathفورك من JSONPath من 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>(انظر أيضًا [تراخيص تبعيات التطوير.](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).
***يرجى ملاحظة: هذا المشروع لا تتم صيانته بنشاط حاليًا. قد
نقبل طلبات سحب موثّقة جيدًا أو بعض التحديثات البسيطة، لكننا لا نسعى
إلى إجراء إصلاحات أو إضافة ميزات جديدة بأنفسنا.***
## الميزات
* **متوافق** مع مواصفة 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 الأخرى وفقًا لـ [json-querying-performance-testing](https://github.com/andykais/json-querying-performance-testing). يمكنك التحقق من هذه النتائج من خلال [تشغيل المشروع بنفسك](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 Module (للمتصفحات الحديثة):
```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/).
### الخصائص
تشمل الخصائص التي يمكن توفيرها على كائن الخيارات أو
طريقة التقييم (كوسيطة أولى):
- ***path*** (**مطلوب**) - تعبير JSONPath كسلسلة نصية (مُطبَّعة
أو غير مُطبَّعة) أو مصفوفة
- ***json*** (**مطلوب**) - كائن JSON المراد تقييمه (سواء كان من
نوع null أو boolean أو number أو string أو object أو array).
- ***autostart*** (**الافتراضي: true**) - إذا تم توفيره كـ `false`،
يمكن للمرء استدعاء طريقة `evaluate` يدويًا.
- ***flatten*** (**الافتراضي: false**) - ما إذا كانت المصفوفة المُرجَعة من النتائج
سيتم تسطيحها إلى مصفوفة أحادية البعد.
- ***resultType*** (**الافتراضي: "value"**) - يمكن أن يكون شكلًا غير حساس لحالة الأحرف من
"value" أو "path" أو "pointer" أو "parent" أو "parentProperty" لتحديد
ما إذا كان سيتم إرجاع النتائج كقيم للعناصر التي تم العثور عليها،
أو كمساراتها المطلقة، أو كـ [مؤشرات JSON](https://tools.ietf.org/html/rfc6901)
إلى المسارات المطلقة، أو ككائناتها الأصلية، أو كاسم خاصية
العنصر الأصلي. إذا تم تعيينه إلى "all"، سيتم إرجاع جميع هذه الأنواع على
كائن مع النوع كاسم مفتاح.
- ***sandbox*** (**الافتراضي: {}**) - خريطة مفتاح-قيمة للمتغيرات التي ستكون
متاحة لتقييمات الكود مثل تعبيرات التصفية. (لاحظ
أن المسار والقيمة الحاليين سيكونان متاحين أيضًا لتلك
التعبيرات؛ راجع قسم الصيغة للحصول على التفاصيل.)
- ***wrap*** (**الافتراضي: true**) - ما إذا كان سيتم تغليف النتائج
في مصفوفة أم لا. إذا تم تعيين `wrap` إلى `false`، ولم يتم العثور على نتائج،
سيتم إرجاع `undefined` (على عكس مصفوفة فارغة عندما
يتم تعيين `wrap` إلى true). إذا تم تعيين `wrap` إلى `false` وتم العثور على
نتيجة واحدة غير مصفوفية، ستكون تلك النتيجة هي العنصر الوحيد المُرجَع
(وليس داخل مصفوفة). ومع ذلك، سيتم إرجاع مصفوفة إذا تم العثور على
نتائج متعددة. لتجنب الغموض (في الحالة التي يكون فيها
من الضروري التمييز بين نتيجة فاشلة
وأخرى عبارة عن مصفوفة فارغة)، يُوصى بتبديل
الافتراضي إلى `false`.
- ***eval*** (**الافتراضي: "safe"**) - طريقة تقييم النص البرمجي.
`safe`: في المتصفح، سيستخدم محرك نصوص برمجية بسيط لا
يستخدم `eval` أو `Function` ويلبي سياسة أمان المحتوى. في NodeJS،
ليس له تأثير ويعادل native حيث أن النصوص البرمجية آمنة هناك.
`native`: يستخدم إمكانيات النصوص البرمجية الأصلية. أي `eval` أو
`Function` غير آمن في المتصفح و`vm.Script` في nodejs. `false`: تعطيل تعبيرات
تقييم JavaScript ورمي الاستثناءات عند محاولة استخدام هذه التعبيرات.
`callback [ (code, context) => value]`: تنفيذ مخصص يتم استدعاؤه
مع `code` و`context` كوسيطات لإرجاع القيمة المُقيَّمة.
`class`: فئة يتم إنشاؤها مع `code` كوسيطة للمُنشئ ويتم تقييم الكود
عن طريق استدعاء `runInNewContext` مع `context`.
``
- ***ignoreEvalErrors*** (**الافتراضي: false**) - تجاهل الأخطاء التي تتم مواجهتها أثناء
تقييم النص البرمجي.
- ***parent*** (**الافتراضي: null**) - في حالة إمكانية إجراء استعلام
لإرجاع العقدة الجذرية، يتيح هذا إرجاع العنصر الأصلي لتلك العقدة الجذرية
ضمن النتائج.
- ***parentProperty*** (**الافتراضي: null**) - في حالة إمكانية إجراء استعلام
لإرجاع العقدة الجذرية، يتيح هذا إرجاع `parentProperty`
لتلك العقدة الجذرية ضمن النتائج. قد يكون هذا اسم خاصية
نصيًا أو فهرس مصفوفة رقميًا.
- ***callback*** (**الافتراضي: (لا شيء)**) - إذا تم توفيره، سيتم استدعاء دالة استدعاء
فورًا عند استرجاع قيمة نقطة النهاية. ستكون الوسيطات الثلاث
الموفرة هي قيمة الحمولة (وفقًا لـ `resultType`)،
ونوع الحمولة (سواء كان "value" عاديًا أو اسم "property")،
وكائن حمولة كامل (مع جميع `resultType`s).
- ***otherTypeCallback*** (**الافتراضي: \<دالة ترمي خطأ**
**عند مواجهة @other()\>**) - في الغياب الحالي لدعم JSON
Schema، يمكن للمرء تحديد أنواع تتجاوز الأنواع المدمجة عن طريق
إضافة المعامل `@other()` في نهاية الاستعلام. إذا تمت مواجهة مثل هذا
المسار، سيتم استدعاء `otherTypeCallback` مع
قيمة العنصر، ومساره، والعنصر الأصلي، واسم خاصية العنصر الأصلي،
ويجب أن يُرجع قيمة منطقية تشير إلى ما إذا كانت القيمة الموفرة
تنتمي إلى النوع "other" أم لا (أو قد يتعامل مع التحويلات
ويُرجع false).
- ***customTypes*** (**الافتراضي: {}**) - خريطة مفتاح-قيمة لأسماء الأنواع إلى الدوال.
يتيح هذا إنشاء معاملات أنواع مخصصة يمكن استخدامها في الاستعلامات
(مثل `@myType()`). سيتم استدعاء الدالة مع قيمة العنصر،
ومساره، والعنصر الأصلي، واسم خاصية العنصر الأصلي. يجب أن تُرجع
قيمة منطقية تشير إلى ما إذا كانت القيمة الموفرة تطابق النوع المخصص. يمكن
أيضًا تعيينها إلى:
1. قيمة الاستيراد `jsonpath-plus/src/structuredCloningTypes.js` الذي يعرّف مسبقًا الأنواع التالية:
@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` الذي يعرّف مسبقًا الأنواع التالية:
@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](https://tools.ietf.org/html/rfc6901).
ستكون السلسلة في شكل مثل: `/aProperty/anotherProperty/0`
(مع تجريد أي أحرف داخلية `~` و`/` وفقًا لمواصفات JSON
Pointer). يتم تجريد تراكيب JSONPath الطرفية `~` و`^` ومعاملات
الأنواع مثل `@string()` بصمت.
## الصيغة من خلال الأمثلة
بالنظر إلى JSON التالي، المأخوذ من <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
}
}
}
```
والتمثيل 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>
```
يرجى ملاحظة أن أمثلة 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` (على الرغم من أن هذا غير موجود في المواصفات الأصلية)؛ لاحظ أن بعض المحارف الحرفية (`$` و `@`) تتطلب التهريب (escaping)، مع ذلك |
| `//author` | `$..author` | جميع المؤلفين | |
| `/store/*` | `$.store.*` | جميع الأشياء في المتجر، وهي كتبه (مصفوفة كتب) ودراجة حمراء (كائن دراجة). | |
| `/store//price` | `$.store..price` | سعر كل شيء في المتجر. | |
| `//book[3]` | `$..book[2]` | الكتاب الثالث (كائن كتاب) | |
| `//book[last()]` | `$..book[(@.length-1)]` <br> `$..book[-1:]` | الكتاب الأخير بالترتيب. | للوصول إلى خاصية بمحرف خاص، استخدم `[(@['...'])]` للمُرشِّح (هذه الميزة تحديدًا غير موجودة في المواصفات الأصلية) |
| `//book[position()<3]` | `$..book[0,1]` <br> `$..book[:2]` | أول كتابين | |
| `//book/*[self::category\|self::author]` أو `//book/(category,author)` في XPath 2.0 | `$..book[0][category,author]` | تصنيفات ومؤلفو جميع الكتب | |
| `//book[isbn]` | `$..book[?(@.isbn)]` | تصفية جميع الكتب التي تحتوي على رقم ISBN | للوصول إلى خاصية بمحرف خاص، استخدم `[?@['...']]` للمُرشِّح (هذه الميزة تحديدًا غير موجودة في المواصفات الأصلية) |
| `//book[price<10]` | `$..book[?(@.price<10)]` | تصفية جميع الكتب الأرخص من 10 | |
---
[Read more](https://github.com/jsonpath-plus/jsonpath)