@schlibs/pathlib

TypeScript library for bidirectional conversion between JSON-Path and JSON-Pointer formats.

Part of the schlibs dual-language library project - identical implementations in Python and TypeScript.

Installation

npm install @schlibs/pathlib

Usage

import {
  pointerToPath,
  pathToPointer,
  pathToPointers,
  PathNotFoundError,
  AmbiguousPathError,
} from '@schlibs/pathlib';

// JSON-Pointer → JSON-Path (no document required)
const path = pointerToPath('/store/book/0/title');
// Returns: "$.store.book[0].title"

// JSON-Path → JSON-Pointer (requires document)
const doc = {
  store: {
    book: [
      { title: 'Book 1', price: 8.95 },
      { title: 'Book 2', price: 12.99 }
    ]
  }
};

const pointer = pathToPointer('$.store.book[0].title', doc);
// Returns: "/store/book/0/title"

// With filter expressions
const pointer2 = pathToPointer('$.store.book[?(@.price > 10)].title', doc);
// Returns: "/store/book/1/title"

// Multiple results
const pointers = pathToPointers('$.store.book[*].title', doc);
// Returns: ["/store/book/0/title", "/store/book/1/title"]

Error Handling

import { PathNotFoundError, AmbiguousPathError } from '@schlibs/pathlib';

try {
  pathToPointer('$.nonexistent', doc);
} catch (error) {
  if (error instanceof PathNotFoundError) {
    console.log('Path not found in document');
  }
}

try {
  pathToPointer('$.store.book[*].title', doc);  // Multiple results
} catch (error) {
  if (error instanceof AmbiguousPathError) {
    console.log('Path resolves to multiple locations');
    // Use pathToPointers() instead
  }
}

API

pointerToPath(pointer: string): string

Convert a JSON-Pointer to a JSON-Path. This is a straightforward syntactic transformation that does not require a document.

Parameters:

• pointer: JSON-Pointer string (e.g., "/store/book/0/title")

Returns: JSON-Path string (e.g., "$.store.book[0].title")

pathToPointer(jsonpath: string, document: any): string

Convert a JSON-Path to a JSON-Pointer by resolving it against a document. Throws an error if the path resolves to zero or multiple results.

Parameters:

• jsonpath: JSON-Path string (e.g., "$.store.book[0].title")
• document: Document to resolve the path against

Returns: JSON-Pointer string (e.g., "/store/book/0/title")

Throws:

• PathNotFoundError: If the path resolves to zero results
• AmbiguousPathError: If the path resolves to multiple results

pathToPointers(jsonpath: string, document: any): string[]

Convert a JSON-Path to a list of JSON-Pointers. Handles paths that resolve to multiple results.

Parameters:

• jsonpath: JSON-Path string (e.g., "$.store.book[*].title")
• document: Document to resolve the path against

Returns: Array of JSON-Pointer strings

Why the Asymmetry?

JSON-Pointer → JSON-Path conversion is straightforward because JSON-Pointers are concrete paths that always point to exactly one location.

JSON-Path → JSON-Pointer conversion requires a document because:

• JSON-Paths can be queries (filters, wildcards) that need evaluation against actual data
• Without a document, we cannot determine which elements match a query
• Requiring a document ensures consistent behavior and validates path existence

Development

This package is BDD-tested with Cucumber to ensure identical behavior with the Python implementation.

# Run BDD tests
npm test

# Build
npm run build

# Test deployment
./test_deployment.sh

License

MIT