diff --git a/docs/docs/guides/jsonpath-functions.md b/docs/docs/guides/jsonpath-functions.md index 7d83bab..49af94e 100644 --- a/docs/docs/guides/jsonpath-functions.md +++ b/docs/docs/guides/jsonpath-functions.md @@ -1,11 +1,75 @@ # JSONPath Functions -TODO: +## Standard functions -## `match()` +These are the standard, built-in function available to JSONPath [filters](./jsonpath-syntax.md#filters). You can also create your own [function extensions](#function-extensions). -TODO: +### `count()` + +```typescript +count(nodes: JSONPathNodeList): number +``` + +Return the number of nodes in a node list. Usually, `count()` will be given a [filter query](./jsonpath-syntax.md#filter-queries) as its argument, and a call to `count()` must be part of a comparison expression. + +```text title="Example query" +$.users[?count(@.*) > 2] +``` + +### `length()` + +```typescript +length(value: JSONValue): number | undefined +``` + +Return the length of a string or array, or the number of items in an object. Usually, `length()` will be given a [filter query](./jsonpath-syntax.md#filter-queries) as its argument, and a call to `length()` must be part of a comparison expression. + +```text title="Example query" +$.users[?length(@) > 2] +``` + +### `match()` + +```typescript +match(value: string, pattern: string): boolean +``` + +Return `true` if _value_ is a full match to the regular expression _pattern_, or `false` otherwise. + +```text title="Example query" +$.users[?match(@.name, '[Ss].*')] +``` + +### `search()` + +```typescript +search(value: string, pattern: string): boolean +``` + +Return `true` if _value_ contains _pattern_, or `false` otherwise. + +```text title="Example query" +$.users[?search(@.name, '[Aa]')] +``` + +### `value()` + +```typescript +value(nodes: JSONPathNodeList): JSONValue | undefined +``` + +Return the value associated with the first node in _nodes_, if _nodes_ has exactly one [`JSONPathNode`](../api/classes/jsonpath.JSONPathNode.md). Usually, `value()` will be called with a [filter query](./jsonpath-syntax.md#filter-queries) as its argument. + +:::info +[Filter queries](./jsonpath-syntax.md#filter-queries) that can result in at most one node are known as "singular queries", and all singular queries will be implicitly replaced with their value as required, without the use of `value()`. `value()` is useful when you need the value from a query that can, theoretically, return multiple nodes. +::: + +## Well-typedness + +The JSONPath specification defines a [type system for function expressions](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20#name-type-system-for-function-ex), and rules for how those types can be used within an expression. JSON P3 will throw a [JSONPathTypeError](../api/classes/jsonpath.JSONPathTypeError.md) as query compile time if it contains expressions that are not deemed to be well-typed. + +Please see [Section 2.4.3](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20#name-well-typedness-of-function-) _Well-Typedness of Function Expressions_. -## `search()` +## Function extensions TODO: diff --git a/docs/docs/guides/jsonpath-syntax.md b/docs/docs/guides/jsonpath-syntax.md index 039f41c..542f5ca 100644 --- a/docs/docs/guides/jsonpath-syntax.md +++ b/docs/docs/guides/jsonpath-syntax.md @@ -141,6 +141,19 @@ Selectively include child nodes from the current selection using filters of the - an existence test on the result of a JSONPath query, - or the truthiness of some function calls, depending on the function's return type. +```text +$.users[?@.admin] +``` + +```json title="Example output" +[ + { "name": "John", "score": 86, "admin": true }, + { "name": "Sally", "score": 84, "admin": false } +] +``` + +### Filter queries + Inside a filter expression, `@` is the _current node identifier_, starting a new JSONPath query with the current node at the root. ```text @@ -177,7 +190,7 @@ $.users[?@.score > 85 && @.score < 100].name ["John"] ``` -### Functions +### Filter functions Filter expressions can include calls to predefined functions. For example, the [`match()`](./jsonpath-functions.md#match) function matches nodes against a regular expression, if that node is a string value. @@ -215,7 +228,7 @@ $.users[0, ?@.name == 'Sally', 'foo'].score ### Recursive descent -The recursive descent segment (`..[]`) selects all nodes, recursively, beneath the current selection in the JSON document tree. There mst be at least one selector. In this example we use shorthand notation for a property name (`score`), but a bracketed selector list is OK too. +The recursive descent segment (`..[]`) visits all nodes, recursively, beneath the current selection in the JSON document tree. There mst be at least one selector. In this example we use shorthand notation for a property name (`score`), but a bracketed selector list is OK too. ```text $..score diff --git a/docs/docs/intro.mdx b/docs/docs/intro.mdx index 2c6328f..3661939 100644 --- a/docs/docs/intro.mdx +++ b/docs/docs/intro.mdx @@ -9,13 +9,15 @@ import TabItem from "@theme/TabItem"; JSON P3 implements JSONPath following the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20) specification, JSON Pointer described by [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901), and JSON Patch described by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). -**JSONPath** is a mini language for selecting values from JSON-like data. A JSONPath query has the potential to return multiple values from a data structure, along with their locations. This implementation is non-evaluating and read-only. We strictly follow the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20). +**[JSONPath](./quick-start.md#jsonpath)** is a mini language for selecting values from JSON-like data. A JSONPath query has the potential to return multiple values from a data structure, along with their locations. This implementation is non-evaluating and read-only. We strictly follow the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20). -**JSON Pointer** is a syntax for targeting a single value in JSON-like data. JSON Pointers can be _resolved_ against data to retrieve the value, or used as part of a JSON Patch operation. +**[JSON Pointer](./quick-start.md#json-pointer)** is a syntax for targeting a single value in JSON-like data. JSON Pointers can be _resolved_ against data to retrieve the value, or used as part of a JSON Patch operation. -**JSON Patch** is a standard for describing update operations to perform on JSON-like data. You can _apply_ a patch to _add_, _remove_, _replace_, _copy_ and _move_ values within a JSON document. +**[JSON Patch](./quick-start.md#json-patch)** is a standard for describing update operations to perform on JSON-like data. You can _apply_ a patch to _add_, _remove_, _replace_, _copy_ and _move_ values within a JSON document. +:::info We use the term _JSON-like data_ to describe arbitrary, possibly nested, JavaScript arrays and objects, plus primitive strings, numbers, booleans and `null`, as you might expect from `JSON.parse()`. When traversing JSON-like data, we only resolve an object's direct properties, and the `length` property of arrays and strings is ignored. +::: ## Install