Utilities API Reference

Complete API reference for jsonpathx utility functions. Includes path manipulation, cache management, parent chain tracking, and helper functions.

PathUtils

Utilities for working with JSONPath expressions and JSON Pointers.

Import

import { PathUtils } from '@jsonpathx/jsonpathx';

Methods

toPointer(path: string | (string | number)[]): string

Convert JSONPath expression (or path array) to JSON Pointer (RFC 6901).

Parameters:

• path - JSONPath expression

Returns: JSON Pointer string

Example:

PathUtils.toPointer('$.store.books[0].title');
// Returns: '/store/books/0/title'

PathUtils.toPointer('$');
// Returns: ''

Throws: Error if path contains wildcards or filters

---

fromPointer(pointer: string): string

Convert JSON Pointer to JSONPath expression.

Parameters:

• pointer - JSON Pointer string

Returns: JSONPath expression

Example:

PathUtils.fromPointer('/store/books/0/title');
// Returns: '$.store.books[0].title'

PathUtils.fromPointer('');
// Returns: '$'

---

normalize(path: string): string

Normalize JSONPath to canonical bracket notation.

Parameters:

• path - JSONPath expression

Returns: Normalized path

Example:

PathUtils.normalize('$.user.name');
// Returns: "$['user']['name']"

PathUtils.normalize('$.items[0]');
// Returns: "$['items'][0]"

---

parse(path: string): PathComponent[]

Parse JSONPath into components.

Parameters:

• path - JSONPath expression

Returns: Array of path components

Types:

interface PathComponent {
  type: 'root' | 'property' | 'index' | 'wildcard' | 'slice' | 'filter' | 'recursive';
  value: string | number;
}

Example:

PathUtils.parse('$.store.books[0]');
// Returns:
// [
//   { type: 'root', value: '$' },
//   { type: 'property', value: 'store' },
//   { type: 'property', value: 'books' },
//   { type: 'index', value: 0 }
// ]

---

stringify(components: PathComponent[]): string

Build JSONPath from components.

Parameters:

• components - Array of path components

Returns: JSONPath expression

Example:

const components = [
  { type: 'root', value: '$' },
  { type: 'property', value: 'store' },
  { type: 'index', value: 0 }
];

PathUtils.stringify(components);
// Returns: '$.store[0]'

---

build(segments: (string | number)[]): string

Build JSONPath from array of segments.

Parameters:

• segments - Array of property names, indices, or wildcards

Returns: JSONPath expression

Example:

PathUtils.build(['store', 'books', 0, 'title']);
// Returns: '$.store.books[0].title'

PathUtils.build(['items', '*', 'price']);
// Returns: '$.items[*].price'

---

parent(path: string): string | null

Get parent path.

Parameters:

• path - JSONPath expression

Returns: Parent path or null if root

Example:

PathUtils.parent('$.store.books[0].title');
// Returns: '$.store.books[0]'

PathUtils.parent('$');
// Returns: null

---

append(basePath: string, ...segments: string[]): string

Append segments to path.

Parameters:

• basePath - Base JSONPath
• segments - Segments to append

Returns: Extended path

Example:

PathUtils.append('$.store', '.books', '[0]');
// Returns: '$.store.books[0]'

---

isValid(path: string): boolean

Check if path is valid JSONPath syntax.

Parameters:

• path - String to validate

Returns: true if valid

Example:

PathUtils.isValid('$.store.books');  // true
PathUtils.isValid('$.items[*]');     // true
PathUtils.isValid('store.books');    // false

---

isPointer(str: string): boolean

Check if string is valid JSON Pointer.

Parameters:

• str - String to validate

Returns: true if valid JSON Pointer

Example:

PathUtils.isPointer('/store/books');  // true
PathUtils.isPointer('');              // true
PathUtils.isPointer('$.store');       // false

---

equals(path1: string, path2: string): boolean

Compare two paths for equality.

Parameters:

• path1 - First path
• path2 - Second path

Returns: true if paths are equivalent

Example:

PathUtils.equals('$.store.books', "$['store']['books']");
// Returns: true

---

startsWith(path: string, prefix: string): boolean

Check if path starts with prefix.

Parameters:

• path - Path to check
• prefix - Prefix to match

Returns: true if path starts with prefix

Example:

PathUtils.startsWith('$.store.books[0]', '$.store');
// Returns: true

---

contains(path: string, segment: string | number): boolean

Check if path contains segment.

Parameters:

• path - Path to search
• segment - Segment to find

Returns: true if segment exists in path

Example:

PathUtils.contains('$.store.books[0]', 'books');
// Returns: true

---

Cache Management

Import

import { QueryCache, getGlobalCache, resetGlobalCache } from '@jsonpathx/jsonpathx';

QueryCache Class

LRU cache with TTL support.

Constructor

new QueryCache(options?: CacheOptions)

Options:

interface CacheOptions {
  maxSize?: number;  // Default: 100
  ttl?: number;      // Default: 60000 (1 minute)
}

Example:

const cache = new QueryCache({
  maxSize: 200,
  ttl: 120000
});

Methods

get(key: string): any | undefined

Get cached value.

Parameters:

• key - Cache key

Returns: Cached value or undefined

Example:

const value = cache.get('$.items[*]');

---

set(key: string, value: any): void

Store value in cache.

Parameters:

• key - Cache key
• value - Value to cache

Example:

cache.set('$.items[*]', resultData);

---

clear(key?: string): void

Clear cache entries.

Parameters:

• key - Optional specific key to clear

Example:

// Clear all
cache.clear();

// Clear specific
cache.clear('$.items[*]');

---

getStats(): CacheStats

Get cache statistics.

Returns:

interface CacheStats {
  size: number;       // Current entries
  hits: number;       // Cache hits
  misses: number;     // Cache misses
  hitRate: number;    // Hit rate (0-1)
  maxSize: number;    // Configured max
  ttl: number;        // Configured TTL
}

Example:

const stats = cache.getStats();
console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);

---

Global Cache Functions

getGlobalCache(): QueryCache

Get the global cache instance.

Returns: Global QueryCache instance

Example:

const cache = getGlobalCache();
const stats = cache.getStats();

---

resetGlobalCache(): void

Reset global cache to default settings.

Example:

resetGlobalCache();
// Global cache is now reset

---

Parent Chain Tracking

Import

import {
  ParentChainTracker,
  buildParentChain,
  navigateUp
} from '@jsonpathx/jsonpathx';

ParentChainTracker Class

Tracks parent relationships in query results.

Constructor

new ParentChainTracker()

Example:

const tracker = new ParentChainTracker();

Methods

track(result: AllTypesResult, index: number): void

Track parent chain for result.

Parameters:

• result - Query result with parents
• index - Result index

Example:

tracker.track(queryResult, 0);

---

getChain(index: number): unknown[]

Get parent chain for tracked result.

Parameters:

• index - Result index

Returns: Array of parent objects (root to immediate parent)

Example:

const chain = tracker.getChain(0);
// [rootObj, level1Obj, level2Obj, immediateParent]

---

Helper Functions

buildParentChain(result: AllTypesResult, index: number): unknown[]

Build parent chain from query result.

Parameters:

• result - Query result with parents
• index - Result index

Returns: Array of parent objects

Example:

const result = await JSONPath.query('$..value', data, {
  resultType: 'all'
});

const chain = buildParentChain(result, 0);
// Returns: [root, parent1, parent2, ...]

---

navigateUp(chain: unknown[], levels: number): unknown | null

Navigate up parent chain.

Parameters:

• chain - Parent chain array
• levels - Number of levels to go up

Returns: Parent at specified level or null

Example:

const immediateParent = navigateUp(chain, 1);
const grandparent = navigateUp(chain, 2);
const root = navigateUp(chain, chain.length);

---

Engine Management

init() is a no-op for the JS engine and is kept for API compatibility.

Sandbox Utilities

Import

import {
  validateSandbox,
  createSafeSandbox,
  resolveSandbox,
  getFunctionNames
} from '@jsonpathx/jsonpathx';

Functions

validateSandbox(sandbox: Sandbox): void

Validate sandbox object.

Parameters:

• sandbox - Sandbox object to validate

Throws: Error if sandbox is invalid

Example:

const sandbox = {
  myFunc: (x) => x > 10
};

validateSandbox(sandbox);  // OK

// Invalid sandbox
validateSandbox({ constructor: () => {} });  // Throws

---

createSafeSandbox(sandbox: Sandbox): Sandbox

Create safe copy of sandbox.

Parameters:

• sandbox - Original sandbox

Returns: Safe sandbox copy

Example:

const userSandbox = {
  filter: (x) => x.active
};

const safeSandbox = createSafeSandbox(userSandbox);
// Safe to use in queries

---

resolveSandbox(sandbox: Sandbox, functionName: string): Function | undefined

Resolve function from sandbox.

Parameters:

• sandbox - Sandbox object
• functionName - Function name

Returns: Function or undefined

Example:

const func = resolveSandbox(sandbox, 'myFunc');
if (func) {
  const result = func(item);
}

---

getFunctionNames(sandbox: Sandbox): string[]

Get all function names from sandbox.

Parameters:

• sandbox - Sandbox object

Returns: Array of function names

Example:

const names = getFunctionNames(sandbox);
console.log('Available functions:', names);
// ['isExpensive', 'inStock', 'validate']

---

Result Formatter

Import

import { ResultFormatter } from '@jsonpathx/jsonpathx';

ResultFormatter Class

Format query results or payloads.

Static Methods

format(result: unknown, options: QueryOptions): unknown

Format query results based on options.

Parameters:

• result - Result array or payloads
• options - Query options

Returns: Formatted result

Example:

const formatted = ResultFormatter.format(resultPayloads, {
  resultType: 'value',
  flatten: true
});

---

formatValues(values: unknown[], options: QueryOptions): unknown[]

Format value array.

Parameters:

• values - Value array
• options - Query options

Returns: Formatted values

Example:

const formatted = ResultFormatter.formatValues(values, {
  flatten: true
});

---

Type Guards

Utility type guards for TypeScript.

Import

import { isAllTypesResult } from '@jsonpathx/jsonpathx';

Functions

isAllTypesResult(result: unknown): result is AllTypesResult

Check if result is AllTypesResult.

Example:

if (isAllTypesResult(result)) {
  console.log(result.values);
  console.log(result.paths);
  console.log(result.parents);
}

---

See Also

• Path Utilities Guide - Path utility usage
• Caching Guide - Cache configuration
• Parent Selector Guide - Parent tracking
• Types Reference - TypeScript types

fromPointerArray(pointer: string): (string | number)[]

Convert JSON Pointer to a path array.

Parameters:

• pointer - JSON Pointer string

Returns: Path array

Example:

const array = PathUtils.fromPointerArray('/store/books/0/title');
// Returns: ['$', 'store', 'books', 0, 'title']

---