@sanity/json-match

A modern, lightweight implementation of the JSONMatch path expression language made for low-level use in other libraries such as the Sanity App SDK.

Table of Contents

• Installation
• Core Concepts
  • What is JSONMatch?
  • Lazy evaluation
  • Handling undefined values
  • Special _key handling
  • Path manipulation
• JSONMatch Language Reference
• API Reference
  • jsonMatch(value, path, basePath?)
  • stringifyPath(path)
  • getIndexForKey(array, key)
  • getPathDepth(path)
  • joinPaths(base, path)
  • parsePath(input)
  • slicePath(path, start?, end?)
• LICENSE

Installation

npm install @sanity/json-match

Core Concepts

What is JSONMatch?

JSONMatch is a query language designed to select one or more sub-values within a JSON document.

Here's a quick example:

import {jsonMatch} from '@sanity/json-match'

const data = {
  users: [
    {name: 'Alice', _key: 'alice', age: 25, active: true},
    {name: 'Bob', _key: 'bob', age: 30, active: false},
    {name: 'Carol', _key: 'carol', age: 35, active: true},
  ],
}

// 1. Write a path expression
const expression = 'users[active == true]'

// 2. Evaluate expression against a value
const matches = jsonMatch(data, expression)

// `jsonMatch` returns a generator of matches
for (const match of matches) {
  console.log('Matched Value:', match.value)
  console.log('Path to Value:', match.path)
}

// Output:
//
// Matched Value: {name: 'Alice', _key: 'alice', age: 25, active: true}
// Path to Value: ['users', {_key: 'alice'}]
//
// Matched Value: {name: 'Carol', _key: 'carol', age: 35, active: true}
// Path to Value: ['users', {_key: 'carol'}]

To use JSONMatch you:

1. Write a path expression (e.g. users[active == true]) that describes where to search (e.g. users) and what constraints must be satisfied (e.g. [active == true]). To use a path expression, you…
2. Evaluate it against a JSON value. The evaluator then searches the document and returns all the matches that satisfy your expression.

For each match found, you get back a MatchEntry object:

// This object is yielded from `jsonMatch`
export interface MatchEntry {
  /**
   * The subvalue found within the given JSON value. This is
   * referentially equal to the nested value in the JSON object.
   */
  value: unknown
  /**
   * An array of keys and indices representing the location of the value within
   * the original value. Note that the evaluator will only yield paths that
   * address a single value.
   *
   * ```ts
   * const path: Path = ['users', 0, 'profile', { _key: 'email' }]
   * // Represents: users[0].profile[_key=="email"]
   * ```
   */
  path: SingleValuePath
}

export type IndexTuple = [number | '', number | ''] // array slice e.g. [1:3]
export type KeyedSegment = {_key: string} // key constraint e.g. [_key=="val"]

export type PathSegment = string | number | KeyedSegment | IndexTuple
export type Path = PathSegment[]

// `SingleValuePath`s don't include the index tuple since that can map to many values
export type SingleValuePath = Exclude<PathSegment, IndexTuple>[]

// the `jsonMatch` function returns a Generator of `MatchEntry`
export function jsonMatch(value, pathExpr): Generator<MatchEntry>

[!TIP] The Path format is a common representation in many other Sanity libraries making it easy to integrate with other Sanity tools.

This path type can be turned back into a string with stringifyPath if desired. See the path manipulation section for more path utilities.

Lazy evaluation

The jsonMatch function is lazy, meaning it returns a generator that yields matches one by one, only when you ask for them. It doesn't compute all possible matches upfront.

This design offers a significant performance advantage, especially when you're working with large datasets and only need the first few matches. For example, if you're looking for the first active item in an array of thousands of elements, jsonMatch will stop searching as soon as it finds it.

import {jsonMatch} from '@sanity/json-match'

// A large array where the match is halfway through
const data = {
  items: Array.from({length: 1000}, (_, i) => ({
    id: i,
    active: i === 500, // Only item at index 500 is active
  })),
}

// Find the first active item
const generator = jsonMatch(data, 'items[active == true]')

// .next().value gets the first match without iterating the whole array
const firstMatch = generator.next().value

console.log('Found:', firstMatch.value)
// Found: { id: 500, active: true }

This makes the library suitable for performance-critical tasks where you need to find a single value quickly.

Handling undefined values

jsonMatch yields matches for paths that resolve to undefined values, even when traversing through invalid intermediate values. This exhaustive path traversal behavior is designed to support both reading and writing operations in the Sanity ecosystem.

import {jsonMatch} from '@sanity/json-match'

const data = {
  user: {
    name: 'Alice',
    // Note: no 'email' property
  },
  posts: [
    {title: 'First Post'},
    // Note: no second post at index 1
  ],
  version: '1.0.0', // This is a string, not an object
}

// Accessing non-existent properties yields undefined with the path
const emailMatches = Array.from(jsonMatch(data, 'user.email'))
console.log(emailMatches)
// [{ value: undefined, path: ['user', 'email'] }]

// Accessing out-of-bounds array indices also yields undefined
const missingPostMatches = Array.from(jsonMatch(data, 'posts[1].title'))
console.log(missingPostMatches)
// [{ value: undefined, path: ['posts', 1, 'title'] }]

// Even traversing through non-objects continues until path is exhausted
const invalidTraversal = Array.from(jsonMatch(data, 'version.major.patch'))
console.log(invalidTraversal)
// [{ value: undefined, path: ['version', 'major', 'patch'] }]
// Note: continues evaluating even though 'version' is a string

// Arrays with mixed types yield undefined for non-objects
const mixedArray = {
  items: ['string', {name: 'Alice'}, null, 42],
}
const mixedResults = Array.from(jsonMatch(mixedArray, 'items.name'))
console.log(mixedResults)
// [
//   { value: undefined, path: ['items', 0, 'name'] },  // string has no 'name'
//   { value: 'Alice', path: ['items', 1, 'name'] },    // object has 'name'
//   { value: undefined, path: ['items', 2, 'name'] },  // null has no 'name'
//   { value: undefined, path: ['items', 3, 'name'] }   // number has no 'name'
// ]

// This allows downstream systems to know where values can be set
const pathsForSetting = Array.from(jsonMatch(data, 'user.profile.settings.theme')).map(
  (m) => m.path,
)
console.log(pathsForSetting)
// [['user', 'profile', 'settings', 'theme']] - full path even if intermediate values don't exist!

Why this matters:

• For reading: You can distinguish between non-existent paths and paths that exist but contain undefined
• For writing: You get the exact path information needed to set values at locations that don't currently exist, even through multiple levels of missing intermediate values
• For consistency: The same path expression works for both reading existing values and determining where new values can be written
• For completeness: Arrays with mixed types (objects, primitives, null) yield results for all elements, with undefined for non-objects

How exhaustive traversal works:

1. Property access (obj.prop): Always yields a result, even if obj is not an object
2. Array indexing (arr[0]): Always yields a result, even if arr is not an array or index is out of bounds
3. Deep paths (a.b.c.d): Continues evaluating the entire path even if intermediate segments are invalid
4. Array iteration (arr.prop): Applies property access to every array element, yielding undefined for non-objects

[!NOTE]
This exhaustive behavior only applies to property access and array indexing. Constraint-based filtering (like [active == true]) will still skip items that don't match the constraint, and existence checks (like [email?]) will not match undefined values.

Special _key handling

In Sanity documents, it's good practice to add a unique _key property to objects inside an array. This gives each object a stable identifier that doesn't change even if the array is reordered.

jsonMatch has special first-class support for _keys to improve both path resilience and performance.

1. When a matched object has a _key, the returned path will use the key instead of the array index. This creates a path that remains valid even if other items are added, removed, or reordered.
2. When you filter an array by _key (e.g., items[_key == "b"]), this library creates and caches a lookup of indexes so subsequent evaluations of the same path expression will be cheap. See getIndexForKey for more info.

[!WARNING] For these optimizations to work reliably, _key values are assumed to be unique within any given array. If an array contains objects with duplicate _keys, the behavior is undefined, as the evaluator will typically match only the first object it finds.

Path manipulation

This library ships with some helper functions to help modify and normalize paths. These utilities allow you to programmatically construct, deconstruct, and analyze paths in a consistent way, regardless of their original format (string, array, or AST).

Here are a few common use cases:

import {joinPaths, slicePath, getPathDepth, stringifyPath, type Path} from '@sanity/json-match'

// Path utilities work with path strings...
const originalPath = 'users[0].posts[_key=="abc"].title'
const parentFromString = slicePath(originalPath, 0, -1)
// -> users[0].posts[_key=="abc"]

// ...and Path arrays.
const originalPathArray: Path = ['users', 0, 'posts', {_key: 'abc'}, 'title']
const parentFromArray = slicePath(originalPathArray, 0, -1)
// -> users[0].posts[_key=="abc"]

// `joinPaths` also accepts both formats.
const newPath = joinPaths(parentFromArray, 'lastModified')
// -> users[0].posts[_key=="abc"].lastModified

// You can convert a Path array to its string equivalent with `stringifyPath`.
const pathString = stringifyPath(originalPathArray)
// -> users[0].posts[_key=="abc"].title
console.log(pathString === originalPath) // true

// Get the depth (number of segments) of a path.
const depth = getPathDepth(originalPath)
// -> 5

JSONMatch Language Reference

See our official documentation for JSONMatch.

import {jsonMatch} from '@sanity/json-match'

// In this reference we will use the following example JSON object to extract data from:
const data = {
  name: 'fred',
  friends: [
    {name: 'mork', age: 40, favoriteColor: 'red'},
    {name: 'mindy', age: 32, favoriteColor: 'blue'},
    {name: 'franklin', favoriteColor: 'yellow'},
    {name: 'bob', favoriteColor: 'green'},
    {name: 'alice', favoriteColor: 'blue'},
  ],
  roles: ['admin', 'owner'],
  contactInfo: {
    streetAddress: '42 Mountain Road',
    state: {
      shortName: 'WY',
      longName: 'Wyoming',
    },
  },
}

function evaluate(expression) {
  const matches = jsonMatch(data, expression)
  const values = Array.from(matches).map((match) => match.value)
  console.log(values)
}

// Given the example document, these expressions can be evaluated
evaluate('name') // [ 'fred' ]
evaluate('friends[*].name') // [ 'mork', 'mindy', 'franklin', 'bob', 'alice' ]
evaluate('friends[age > 35].name') // [ 'mork' ]
evaluate('friends[age > 30, favoriteColor == "blue"].name') // [ 'mork', 'mindy', 'alice' ]
evaluate('friends[age?].age') // [ 40, 32 ]
evaluate('friends[0].name') // [ 'mork' ]
evaluate('friends[1:3].name') // [ 'mindy', 'franklin' ]
evaluate('friends[0, 2:3].name') // [ 'mork', 'franklin' ]
evaluate('contactInfo.state.shortName') // [ 'WY' ]
evaluate('contactInfo.state[shortName, longName]') // [ 'WY', 'Wyoming' ]
evaluate('friends.age[@ > 35]') // [ 40 ]
evaluate('roles') // [ [ 'admin', 'owner' ] ]
evaluate('roles[*]') // [ 'admin', 'owner' ]
evaluate('roles[0]') // [ 'admin' ]
evaluate('roles[-1]') // [ 'owner' ]
evaluate('contactInfo..shortName') // [ 'WY' ]
evaluate('[contactInfo.state.shortName, roles]') // [ 'WY', [ 'admin', 'owner' ] ]

API Reference

jsonMatch(value, path, basePath?)

The main function for evaluating JSONMatch expressions.

import {jsonMatch} from '@sanity/json-match'

const data = {users: [{name: 'Alice', age: 25}]}

// Basic usage
const matches = Array.from(jsonMatch(data, 'users[*].name'))

// With base path (useful for nested evaluation)
const nestedMatches = Array.from(jsonMatch(data.users, '[*].name', ['users']))

stringifyPath(path)

Convert various path formats to their string representation.

This function can handle JSONMatch AST nodes, Path arrays, and string expressions. It's useful for normalizing different path formats into a consistent string format.

import {parsePath, stringifyPath} from '@sanity/json-match'

// Convert AST back to string
const ast = parsePath('users[age > 21].name')
const str = stringifyPath(ast) // "users[age>21].name"

// Convert Path array to string
const pathArr = ['users', 0, {_key: 'profile'}, 'email']
const pathStr = stringifyPath(pathArr) // "users[0][_key==\"profile\"].email"

// String expressions are returned unchanged
const existing = 'items[*].name'
const result = stringifyPath(existing) // "items[*].name" (same string)

// Useful for normalizing expressions
const normalized = stringifyPath(parsePath('  users  [  age  >  21  ] . name  '))
console.log(normalized) // "users[age>21].name"

getIndexForKey(array, key)

Efficiently find the array index for objects with _key properties (Sanity's keyed arrays).

import {getIndexForKey} from '@sanity/json-match'

const keyedArray = [
  {_key: 'item1', name: 'First'},
  {_key: 'item2', name: 'Second'},
  {_key: 'item3', name: 'Third'},
]

const index = getIndexForKey(keyedArray, 'item2') // 1
console.log(keyedArray[index]) // { _key: 'item2', name: 'Second' }

// Performance: First call builds cache, subsequent calls are O(1)
const index2 = getIndexForKey(keyedArray, 'item3') // Fast lookup

getPathDepth(path)

Calculates the number of segments in a path.

import {getPathDepth} from '@sanity/json-match'

getPathDepth('user.profile.email') // 3
getPathDepth('items[0].name') // 3
getPathDepth(['users', {_key: 'alice'}]) // 2

joinPaths(base, path)

Joins two path segments into a single path string.

import {joinPaths} from '@sanity/json-match'

// Adding properties
joinPaths('user', 'profile') // 'user.profile'

// Chaining operations
let path = 'data'
path = joinPaths(path, 'users') // 'data.users'
path = joinPaths(path, '[0]') // 'data.users[0]'

parsePath(input)

Parse various path formats into a standardized AST.

import {parsePath} from '@sanity/json-match'

// String expressions
parsePath('user.profile.email')

// Path arrays
parsePath(['users', 0, {_key: 'profile'}, 'email'])

// Already parsed AST (returns unchanged)
const ast = parsePath('items[*]')
parsePath(ast) === ast // true

slicePath(path, start?, end?)

Extracts a section of a path, similar to Array.prototype.slice.

import {slicePath} from '@sanity/json-match'

slicePath('a.b.c.d.e', 1, 4) // 'b.c.d'

// Get parent path
slicePath('user.profile.email', 0, -1) // 'user.profile'

// Get last segment
slicePath('items[0].name', -1) // 'name'

LICENSE

MIT License - see LICENSE file for details.