Introduction

This documentation covers the JMESPath Extensions project, which provides 400+ additional functions for JMESPath queries.

Project Components

This project includes multiple components:

This documentation primarily focuses on jpx, the CLI tool. For using the Rust library directly in your code, see the rustdoc documentation.

What is JMESPath?

JMESPath is a query language for JSON. It allows you to declaratively specify how to extract and transform elements from a JSON document.

Why JMESPath Extensions?

While standard JMESPath is powerful, it’s intentionally minimal with only 26 built-in functions. This project extends JMESPath with 400+ additional functions for:

• String manipulation: upper, lower, split, replace, camel_case, snake_case, and more
• Array operations: unique, chunk, flatten, group_by, zip, and more
• Object manipulation: pick, omit, deep_merge, flatten_keys, and more
• Math & statistics: round, sqrt, median, stddev, percentile, and more
• Date/time: now, format_date, parse_date, date_add, date_diff
• Hashing & encoding: md5, sha256, base64_encode, hex_encode
• Fuzzy matching: levenshtein, jaro_winkler, soundex
• And much more: geo functions, validation, regex, UUIDs, network utilities…

Features

• Rust Library: Use the functions in your Rust applications (docs.rs)
• Powerful CLI: Query JSON from files, stdin, or inline with jpx
• MCP Server: Use jpx with AI assistants like Claude
• Python Bindings: Use the same 400+ functions in Python
• Function Discovery: Built-in help for all functions
• Strict Mode: Use only standard JMESPath for portable queries

Quick Example

# Basic query
echo '{"users": [{"name": "alice"}, {"name": "bob"}]}' | jpx 'users[*].name'
# ["alice", "bob"]

# Using extension functions
echo '{"name": "hello world"}' | jpx 'upper(name)'
# "HELLO WORLD"

echo '{"items": [1, 2, 2, 3, 3, 3]}' | jpx 'unique(items)'
# [1, 2, 3]

echo '{"values": [10, 20, 30, 40, 50]}' | jpx 'median(values)'
# 30

Getting Started

Ready to dive in? Start with Installation to get jpx set up on your system.

Installation

Docker (Quickest)

Try jpx instantly without installing anything:

# Pull the image
docker pull ghcr.io/joshrotenberg/jpx

# Run a query
echo '{"name": "Alice", "age": 30}' | docker run -i ghcr.io/joshrotenberg/jpx 'name'
# "Alice"

# Fetch and transform data from an API
curl -s 'https://hacker-news.firebaseio.com/v0/item/1.json' | \
  docker run -i ghcr.io/joshrotenberg/jpx '{title: title, by: by, score: score}'
# {"by": "pg", "score": 57, "title": "Y Combinator"}

Available for linux/amd64 and linux/arm64.

Homebrew (macOS/Linux)

The easiest way to install jpx on macOS or Linux:

brew tap joshrotenberg/brew
brew install jpx

Pre-built Binaries

Download pre-built binaries for your platform from the GitHub Releases page.

Available platforms:

• macOS (Apple Silicon / arm64)
• macOS (Intel / x86_64)
• Linux (x86_64)
• Windows (x86_64)

Cargo (from crates.io)

If you have Rust installed:

cargo install jpx

From Source

Clone and build from source:

git clone https://github.com/joshrotenberg/jmespath-extensions
cd jmespath-extensions/jpx
cargo install --path .

Without MCP Server Support

MCP support is included by default. To build without it (smaller binary):

cargo install --path . --no-default-features

Verify Installation

Check that jpx is installed correctly:

jpx --version

You should see output like:

jpx 0.1.15

Shell Completions

Generate shell completions for your shell:

# Bash
jpx --completions bash > ~/.local/share/bash-completion/completions/jpx

# Zsh
jpx --completions zsh > ~/.zfunc/_jpx

# Fish
jpx --completions fish > ~/.config/fish/completions/jpx.fish

# PowerShell
jpx --completions powershell > jpx.ps1

Quick Start

jpx is a command-line JSON processor with 400+ built-in functions. Pipe JSON in, get transformed JSON out.

Five things to know to start using it:

1. Get a field

echo '{"name": "Alice", "city": "NYC"}' | jpx 'name'
# "Alice"

Nested fields use dots:

echo '{"user": {"name": "Alice"}}' | jpx 'user.name'
# "Alice"

2. Get all items from an array

Use [*] to get every element:

echo '[{"name": "Alice"}, {"name": "Bob"}]' | jpx '[*].name'
# ["Alice", "Bob"]

3. Filter an array

Use [?condition] to filter:

echo '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]' | jpx '[?age > `28`]'
# [{"name": "Alice", "age": 30}]

Note: literal values use backticks (`28`).

4. Call a function

jpx has 400+ functions. Pass data with @ (current value):

echo '[3, 1, 4, 1, 5]' | jpx 'sort(@)'
# [1, 1, 3, 4, 5]

echo '[3, 1, 4, 1, 5]' | jpx 'unique(@)'
# [3, 1, 4, 5]

echo '{"name": "hello"}' | jpx 'upper(name)'
# "HELLO"

5. Chain with pipes

Combine operations with |:

echo '[{"n": "Alice"}, {"n": "Bob"}, {"n": "Alice"}]' | jpx '[*].n | unique(@) | sort(@)'
# ["Alice", "Bob"]

That’s it. You can do a lot with just these five patterns.

Finding Functions

Don’t memorize 400 functions. Search for what you need:

jpx --search unique
jpx --describe unique

Next Steps

• Cookbook - Common tasks and recipes
• Basic Usage - More CLI options
• Function Reference - All functions by category
• Why jpx? - Compare jpx to Python, jq, and other tools

Basic Usage

Input Sources

jpx can read JSON from multiple sources:

Standard Input (stdin)

echo '{"name": "Alice"}' | jpx 'name'
# "Alice"

cat data.json | jpx 'users[*].name'
curl -s https://api.example.com/data | jpx 'results[0]'

File Input

jpx 'users[*].name' -f data.json
jpx --file users.json 'length(@)'

Null Input

Use -n to start with null (useful for functions that don’t need input):

jpx -n 'now()'
# 1705312200

jpx -n 'uuid()'
# "550e8400-e29b-41d4-a716-446655440000"

jpx -n 'range(`1`, `5`)'
# [1, 2, 3, 4]

Output Options

Pretty Printing (default)

By default, jpx pretty-prints JSON output with colors:

echo '{"a":1,"b":2}' | jpx '@'

Output:

{
  "a": 1,
  "b": 2
}

Compact Output

Use -c for single-line output:

echo '{"a":1,"b":2}' | jpx -c '@'

Output:

{"a":1,"b":2}

Raw Strings

Use -r to output strings without quotes:

echo '{"msg": "hello"}' | jpx -r 'msg'

Output:

hello

Output to File

Write results to a file:

jpx 'users[*].email' -f data.json -o emails.json
# (writes to emails.json)

Slurp Mode

Read multiple JSON objects into an array:

echo '{"a":1}
{"b":2}
{"c":3}' | jpx -s 'length(@)'

Output:

3

Expression as Positional Argument

The expression can be the first positional argument:

jpx 'users[*].name' -f data.json

Or use -e / --expression:

jpx -e 'users[*].name' -f data.json

Chaining Expressions

Three ways to chain transformations:

# 1. Pipes within a single expression (most common)
jpx 'users | [*].name | sort(@)' -f data.json

# 2. Multiple positional arguments
jpx 'users' '[*].name' 'sort(@)' -f data.json

# 3. Multiple -e flags
jpx -e 'users' -e '[*].name' -e 'sort(@)' -f data.json

All three are equivalent - each expression receives the output of the previous one.

Verbose Mode

See expression details and timing:

echo '{"x": 1}' | jpx -v 'x'

Output:

Input: object (1 keys)

[1] Expression: x
[1] Result: number (1)
[1] Time: 0.040ms

Total time: 0.214ms
1

Quiet Mode

Suppress errors and warnings:

jpx -q 'invalid[' -f data.json
# (no error output, exits with non-zero status)

Color Control

Control colorized output:

jpx --color=always 'name' -f data.json  # Force colors
jpx --color=never 'name' -f data.json   # No colors
jpx --color=auto 'name' -f data.json    # Auto-detect (default)

CLI Reference

Complete reference for all jpx command-line options.

Synopsis

jpx [OPTIONS] [EXPRESSIONS]...

Arguments

Options

Input/Output

Output Format

See Output Formats for detailed examples.

Modes

JSON Patch Operations

Data Analysis

Benchmarking

Function Discovery

Debugging

Interactive Mode

Other

Environment Variables

Environment variables are overridden by command-line flags.

Quick Examples

A few examples showing common flag combinations. For comprehensive examples, see:

• Basic Usage - getting started with queries
• Cookbook - task-oriented recipes
• Output Formats - tables, CSV, YAML
• Query Files - reusable query libraries

# Query a file, raw output for scripting
jpx -r 'config.api_key' -f settings.json

# Chain expressions, table output
jpx 'users' '[?active]' -t -f data.json

# Stream NDJSON, filter errors
cat logs.ndjson | jpx --stream '[?level == `"error"`]'

# Analyze structure before querying
jpx --paths --types -f data.json

# Find functions by keyword
jpx --search unique

# Run a named query from a library
jpx -Q queries.jpx:active-users -f data.json

Exit Codes

Cookbook

Common tasks and how to do them in jpx.

Extracting Data

Most JSON wrangling starts with pulling out the fields you care about.

Get a nested field

echo '{"user": {"profile": {"name": "Alice"}}}' | jpx 'user.profile.name'
# "Alice"

Get multiple fields

echo '{"id": 1, "name": "Alice", "email": "a@example.com", "age": 30}' | jpx '{id: id, name: name}'
# {"id": 1, "name": "Alice"}

Get a field from every object in an array

echo '[{"name": "Alice"}, {"name": "Bob"}]' | jpx '[*].name'
# ["Alice", "Bob"]

Get with a default value

echo '{"name": "Alice"}' | jpx 'get(@, `"email"`, `"no email"`)'
# "no email"

Filtering

Filter expressions ([?condition]) are one of JMESPath’s most powerful features. They let you select array elements that match criteria without writing loops.

Filter by a condition

echo '[{"status": "active"}, {"status": "inactive"}]' | jpx '[?status == `"active"`]'
# [{"status": "active"}]

Filter by multiple conditions

echo '[{"age": 25, "active": true}, {"age": 35, "active": true}, {"age": 30, "active": false}]' \
  | jpx '[?age > `30` && active]'
# [{"age": 35, "active": true}]

Filter by nested field

echo '[{"user": {"role": "admin"}}, {"user": {"role": "guest"}}]' | jpx '[?user.role == `"admin"`]'
# [{"user": {"role": "admin"}}]

Check if field exists

echo '[{"name": "Alice", "email": "a@b.com"}, {"name": "Bob"}]' | jpx '[?email]'
# [{"name": "Alice", "email": "a@b.com"}]

Transforming

Reshape data to match the structure you need - rename fields, compute new values, or convert between formats.

Rename fields

echo '{"firstName": "Alice", "lastName": "Smith"}' | jpx '{first: firstName, last: lastName}'
# {"first": "Alice", "last": "Smith"}

Add a computed field

echo '{"price": 100, "qty": 3}' | jpx '{price: price, qty: qty, total: multiply(price, qty)}'
# {"price": 100, "qty": 3, "total": 300}

Convert object keys to snake_case

echo '{"firstName": "Alice", "lastName": "Smith"}' | jpx 'snake_keys(@)'
# {"first_name": "Alice", "last_name": "Smith"}

Flatten nested structure

echo '{"user": {"name": "Alice", "address": {"city": "NYC"}}}' | jpx 'flatten(@)'
# {"user.name": "Alice", "user.address.city": "NYC"}

Arrays

Common operations on lists of items - sorting, deduplication, grouping, and slicing.

Sort

echo '[3, 1, 4, 1, 5]' | jpx 'sort(@)'
# [1, 1, 3, 4, 5]

Sort objects by field

echo '[{"name": "Bob", "age": 25}, {"name": "Alice", "age": 30}]' | jpx 'sort_by(@, &name)'
# [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]

Remove duplicates

echo '[1, 2, 2, 3, 3, 3]' | jpx 'unique(@)'
# [1, 2, 3]

First/last N items

echo '[1, 2, 3, 4, 5]' | jpx '[:3]'   # first 3
# [1, 2, 3]

echo '[1, 2, 3, 4, 5]' | jpx '[-2:]'  # last 2
# [4, 5]

Group by field

echo '[{"dept": "eng", "name": "Alice"}, {"dept": "eng", "name": "Bob"}, {"dept": "sales", "name": "Carol"}]' \
  | jpx 'group_by(@, `"dept"`)'
# {"eng": [{"dept": "eng", "name": "Alice"}, {"dept": "eng", "name": "Bob"}], "sales": [...]}

Chunk into batches

echo '[1, 2, 3, 4, 5, 6, 7]' | jpx 'chunk(@, `3`)'
# [[1, 2, 3], [4, 5, 6], [7]]

Aggregation

Reduce arrays to summary values - counts, sums, averages, and grouped statistics.

Count

echo '[1, 2, 3, 4, 5]' | jpx 'length(@)'
# 5

Sum, average, min, max

echo '[10, 20, 30]' | jpx 'sum(@)'
# 60

echo '[10, 20, 30]' | jpx 'avg(@)'
# 20

echo '[10, 20, 30]' | jpx 'min(@)'
# 10

Count by group

echo '[{"status": "active"}, {"status": "active"}, {"status": "inactive"}]' \
  | jpx 'group_by(@, `"status"`) | map_values(`"length(@)"`, @)'
# {"active": 2, "inactive": 1}

Strings

Text manipulation - case conversion, splitting, joining, and search/replace.

Upper/lower case

echo '"hello"' | jpx 'upper(@)'
# "HELLO"

Split and join

echo '"a,b,c"' | jpx 'split(@, `","`)'
# ["a", "b", "c"]

echo '["a", "b", "c"]' | jpx 'join(`", "`, @)'
# "a, b, c"

Replace

echo '"hello world"' | jpx 'replace(@, `"world"`, `"jpx"`)'
# "hello jpx"

Trim whitespace

echo '"  hello  "' | jpx 'trim(@)'
# "hello"

Dates

Working with timestamps - get current time, format for display, or calculate durations.

Current time

jpx -n 'now()'
# 1705312200 (Unix timestamp)

jpx -n 'format_date(now(), `"%Y-%m-%dT%H:%M:%SZ"`)'
# "2024-01-15T10:30:00Z"

Format a timestamp

jpx -n 'format_date(now(), `"%B %d, %Y"`)'
# "January 15, 2024"

# From a Unix timestamp
echo '1705312200' | jpx 'format_date(@, `"%Y-%m-%d"`)'
# "2024-01-15"

Add time to a timestamp

jpx -n 'date_add(now(), `7`, `"days"`) | format_date(@, `"%Y-%m-%d"`)'
# "2024-01-22" (7 days from now)

Working with Objects

Inspect and manipulate object structure - list keys, pick/omit fields, merge objects.

Get all keys

echo '{"a": 1, "b": 2, "c": 3}' | jpx 'keys(@)'
# ["a", "b", "c"]

Get all values

echo '{"a": 1, "b": 2, "c": 3}' | jpx 'values(@)'
# [1, 2, 3]

Pick specific keys

echo '{"a": 1, "b": 2, "c": 3}' | jpx 'pick(@, [`"a"`, `"c"`])'
# {"a": 1, "c": 3}

Omit specific keys

echo '{"a": 1, "b": 2, "c": 3}' | jpx 'omit(@, [`"b"`])'
# {"a": 1, "c": 3}

Merge objects

echo '{}' | jpx 'merge({a: `1`}, {b: `2`})'
# {"a": 1, "b": 2}

Cleaning Data

Real-world JSON is messy. These functions help you strip out nulls, empty strings, and other unwanted values.

Remove nulls

echo '{"a": 1, "b": null, "c": 3}' | jpx 'remove_nulls(@)'
# {"a": 1, "c": 3}

Remove empty strings

echo '{"a": "hello", "b": "", "c": "world"}' | jpx 'remove_empty_strings(@)'
# {"a": "hello", "c": "world"}

Compact (remove all empty values)

echo '{"a": 1, "b": null, "c": "", "d": [], "e": {}}' | jpx 'remove_empty(@)'
# {"a": 1}

Putting It Together

Chain these patterns together for real-world data processing tasks.

Extract, filter, transform, sort

echo '[
  {"name": "Alice", "dept": "eng", "salary": 100000},
  {"name": "Bob", "dept": "sales", "salary": 80000},
  {"name": "Carol", "dept": "eng", "salary": 120000}
]' | jpx '[?dept == `"eng"`] | sort_by(@, &salary) | [*].{name: name, salary: salary}'
# [{"name": "Alice", "salary": 100000}, {"name": "Carol", "salary": 120000}]

API response processing

curl -s 'https://api.github.com/users/octocat/repos' \
  | jpx '[?stargazers_count > `100`] | sort_by(@, &stargazers_count) | reverse(@) | [:5] | [*].{name: name, stars: stargazers_count}'

Log analysis

cat logs.json | jpx '[?level == `"error"`] | group_by(@, `"service"`) | map_values(`"length(@)"`, @)'
# {"api": 12, "worker": 3, "scheduler": 1}

Workflow Tips

jpx has built-in tools to help you build and reuse queries.

Explore data structure first

Before writing a query, see what you’re working with:

jpx --paths -f data.json

users (array)
users.0 (object)
users.0.name (string)
users.0.email (string)
users.0.role (string)

jpx --stats -f data.json

Type: object
Size: 2 keys
Depth: 3
Array fields:
  users: 150 items (object)
    Fields: name (100%), email (98%), role (100%), last_login (85%)

Find functions you need

Don’t memorize 400 functions - search for them:

jpx --search "date"

✓ Found 12 functions matching 'date':

  ▸ EXACT:
    date_add [datetime] - Add time to timestamp
    date_diff [datetime] - Difference between timestamps

  ▸ PREFIX:
    format_date [datetime] - Format timestamp as string
    parse_date [datetime] - Parse string to timestamp
    ...

jpx --describe format_date

format_date
===========
Category: datetime
Signature: number, string -> string
Description: Format a Unix timestamp as a string

Example:
  format_date(`1705312200`, '%Y-%m-%d') -> "2024-01-15"

Save queries to files

For complex or reusable queries, store them in a .jpx file:

-- queries.jpx

-- :name active-users
-- :description Get all active users with their email
users[?status == `"active"`].{name: name, email: email}

-- :name error-summary  
-- :description Count errors by service
[?level == `"error"`] | group_by(@, `"service"`) | map_values(`"length(@)"`, @)

Then run by name:

jpx -Q queries.jpx:active-users -f data.json

# List available queries
jpx -Q queries.jpx --list-queries

Available queries in queries.jpx:

  active-users
    Get all active users with their email

  error-summary
    Count errors by service

Debug complex expressions

When a query isn’t working, break it down:

jpx --explain 'users[?active].name | sort(@)'

Expression AST:
  Pipe
  ├─ Projection
  │  ├─ Field: users
  │  └─ Filter: active
  │     └─ Field: name
  └─ Function: sort
     └─ Current (@)

Benchmark performance

For queries you’ll run often, check how fast they are:

jpx --bench 1000 '[*].{id: id, name: upper(name)}' -f users.json

Benchmarking: [*].{id: id, name: upper(name)}
Iterations: 1000

  Mean:    0.234ms
  Median:  0.215ms
  p95:     0.312ms
  p99:     0.456ms

Throughput: 4,273 ops/sec

Output Formats

jpx supports multiple output formats beyond JSON, making it easy to integrate with other tools and workflows.

Available Formats

YAML Output

YAML is great for human-readable configuration files and nested data structures.

# Simple object
echo '{"name": "alice", "age": 30}' | jpx '@' --yaml

age: 30
name: alice

# Nested structures
echo '{"server": {"host": "localhost", "port": 8080}}' | jpx '@' -y

server:
  host: localhost
  port: 8080

# Arrays
echo '[{"name": "alice"}, {"name": "bob"}]' | jpx '@' --yaml

- name: alice
- name: bob

Use Cases

• Converting JSON configs to YAML for Kubernetes, Docker Compose, etc.
• Human-readable output for debugging
• Generating configuration files

# Extract and convert to YAML
jpx '[*].{name: name, role: role}' -f users.json --yaml > users.yaml

TOML Output

TOML is ideal for configuration files, especially in the Rust ecosystem.

# Simple object
echo '{"name": "myapp", "version": "1.0.0"}' | jpx '@' --toml

name = "myapp"
version = "1.0.0"

# Nested tables
echo '{"database": {"host": "localhost", "port": 5432}}' | jpx '@' --toml

[database]
host = "localhost"
port = 5432

Use Cases

• Generating Cargo.toml snippets
• Creating configuration files for Rust applications
• Converting JSON API responses to TOML configs

CSV Output

CSV format is perfect for tabular data that needs to go into spreadsheets or databases.

# Array of objects becomes a table
echo '[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]' | jpx '@' --csv

age,name
30,alice
25,bob

Nested Object Flattening

Nested objects are automatically flattened using dot notation:

echo '[
  {"name": "alice", "address": {"city": "NYC", "zip": "10001"}},
  {"name": "bob", "address": {"city": "LA", "zip": "90001"}}
]' | jpx '@' --csv

address.city,address.zip,name
NYC,10001,alice
LA,90001,bob

Arrays in Cells

Arrays are JSON-encoded within cells:

echo '[{"name": "alice", "tags": ["admin", "dev"]}]' | jpx '@' --csv

name,tags
alice,"[""admin"",""dev""]"

Single Objects

A single object is output as a single-row table:

echo '{"name": "alice", "role": "admin"}' | jpx '@' --csv

name,role
alice,admin

Array of Primitives

Arrays of primitives become single-column output (no header):

echo '[1, 2, 3, 4, 5]' | jpx '@' --csv

1
2
3
4
5

Use Cases

• Exporting data for Excel or Google Sheets
• Loading into databases
• Generating reports

# Export user emails for a mailing list
jpx '[*].{email: email, name: name}' -f users.json --csv > contacts.csv

TSV Output

TSV (tab-separated values) works the same as CSV but uses tabs instead of commas. This is useful for:

• Unix command-line tools that expect tab-separated input
• Pasting directly into spreadsheets
• Avoiding issues with commas in data

echo '[{"name": "alice", "city": "New York"}, {"name": "bob", "city": "Los Angeles"}]' | jpx '@' --tsv

city	name
New York	alice
Los Angeles	bob

Use Cases

# Pipe to awk for further processing
jpx '[*].{name: name, score: score}' -f data.json --tsv | awk -F'\t' '$2 > 90'

# Pipe to column for pretty printing
jpx '@' -f users.json --tsv | column -t -s $'\t'

Lines Output (JSONL)

The --lines flag outputs one JSON value per line, also known as JSON Lines (JSONL) or newline-delimited JSON (NDJSON).

echo '[1, 2, 3, "hello", {"key": "value"}]' | jpx '@' --lines

1
2
3
"hello"
{"key":"value"}

# Array of objects
echo '[{"id": 1}, {"id": 2}, {"id": 3}]' | jpx '@' -l

{"id":1}
{"id":2}
{"id":3}

Use Cases

• Streaming processing with tools like jq, grep, or awk
• Log file format
• Parallel processing (each line is independent)
• Piping to other JSON tools

# Process each line with another tool
jpx '[*]' -f events.json --lines | while read -r line; do
  echo "$line" | jpx '.timestamp'
done

# Filter with grep
jpx '@' -f logs.json --lines | grep '"level":"error"'

# Count items
jpx '[*]' -f data.json --lines | wc -l

Table Output

The --table flag renders arrays of objects as formatted tables, perfect for terminal display.

echo '[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]' | jpx '@' --table

┌───────┬─────┐
│ name  │ age │
├───────┼─────┤
│ alice │ 30  │
│ bob   │ 25  │
└───────┴─────┘

Table Styles

Use --table-style to choose different table formats:

# ASCII style (for older terminals)
echo '[{"name": "alice", "age": 30}]' | jpx '@' -t --table-style ascii

+-------+-----+
| name  | age |
+-------+-----+
| alice | 30  |
+-------+-----+

# Markdown style (for documentation)
echo '[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]' | jpx '@' -t --table-style markdown

| name  | age |
|-------|-----|
| alice | 30  |
| bob   | 25  |

Use Cases

• Quick data inspection in the terminal
• Generating markdown tables for documentation
• Human-readable output for reports

# Display users as a table
jpx '[*].{name: name, email: email, role: role}' -f users.json --table

# Generate markdown documentation
jpx '[*].{Function: name, Description: description}' -f functions.json -t --table-style markdown > docs/functions.md

Combining with Expressions

Output formats work with any JMESPath expression:

# Extract specific fields and output as YAML
echo '[{"name": "alice", "age": 30, "email": "alice@example.com"}]' | \
  jpx '[*].{name: name, email: email}' --yaml

- email: alice@example.com
  name: alice

# Filter and export as CSV
jpx '[?status == `active`].{id: id, name: name}' -f users.json --csv

# Aggregate and output as TOML
jpx '{total: length(@), active: length([?active])}' -f users.json --toml

active = 42
total = 100

Output to Files

All output formats work with the -o flag:

# Save as YAML
jpx '@' -f config.json --yaml -o config.yaml

# Save as CSV
jpx '[*].{name: name, email: email}' -f users.json --csv -o contacts.csv

# Save as TOML
jpx '@' -f settings.json --toml -o settings.toml

Format Selection Tips

Expression Syntax

JMESPath expression syntax reference.

Identifiers

Access object properties by name:

echo '{"name": "Alice", "age": 30}' | jpx 'name'
# "Alice"

Index Expressions

Access array elements by index (0-based):

echo '{"items": ["a", "b", "c"]}' | jpx 'items[0]'
# "a"

echo '{"items": ["a", "b", "c"]}' | jpx 'items[-1]'
# "c"

Slicing

Extract array slices with [start:stop:step]:

echo '[0, 1, 2, 3, 4, 5]' | jpx '[0:3]'
# [0, 1, 2]

echo '[0, 1, 2, 3, 4, 5]' | jpx '[::2]'
# [0, 2, 4]

echo '[0, 1, 2, 3, 4, 5]' | jpx '[::-1]'
# [5, 4, 3, 2, 1, 0]

Wildcard

Project all elements with *:

echo '{"users": [{"name": "Alice"}, {"name": "Bob"}]}' | jpx 'users[*].name'
# ["Alice", "Bob"]

Flatten

Flatten nested arrays with []:

echo '[[1, 2], [3, 4]]' | jpx '[]'
# [1, 2, 3, 4]

Filter Expressions

Filter arrays with [?expression]:

echo '[{"age": 25}, {"age": 17}, {"age": 30}]' | jpx '[?age > `18`]'
# [{"age": 25}, {"age": 30}]

echo '[{"name": "Alice", "active": true}, {"name": "Bob", "active": false}]' | jpx '[?active].name'
# ["Alice"]

Comparison Operators

Logical Operators

Pipe Expressions

Chain expressions with |:

echo '{"items": [3, 1, 2]}' | jpx 'items | sort(@) | reverse(@)'
# [3, 2, 1]

Multi-Select List

Create arrays from multiple expressions:

echo '{"a": 1, "b": 2, "c": 3}' | jpx '[a, b]'
# [1, 2]

Multi-Select Hash

Create objects from multiple expressions:

echo '{"first": "Alice", "last": "Smith", "age": 30}' | jpx '{name: first, surname: last}'
# {"name": "Alice", "surname": "Smith"}

Literal Values

Use backticks for literal values:

# Literal number
echo '{"items": [1, 2, 3]}' | jpx '[?@ > `1`]'

# Literal string
echo '{"items": ["a", "b"]}' | jpx 'contains(items, `"a"`)'

# Literal array
echo '{}' | jpx '`[1, 2, 3]`'

# Literal object
echo '{}' | jpx '`{"key": "value"}`'

Current Node

Reference the current node with @:

echo '[1, 2, 3, 4, 5]' | jpx '[?@ > `2`]'
# [3, 4, 5]

echo '"hello"' | jpx 'upper(@)'
# "HELLO"

Function Calls

Call functions with function_name(arg1, arg2, ...):

echo '{"items": [1, 2, 3]}' | jpx 'length(items)'
# 3

echo '{"name": "hello"}' | jpx 'upper(name)'
# "HELLO"

echo '{"a": [1, 2], "b": [3, 4]}' | jpx 'merge(a, b)'
# [1, 2, 3, 4]

Functions can take literal JSON values as arguments using backticks:

# Apply default values to an object
echo '{"name": "Alice"}' | jpx 'defaults(@, `{"role": "user", "active": true}`)'
# {"name": "Alice", "role": "user", "active": true}

# Build an object from key-value pairs
echo 'null' | jpx 'from_items(`[["a", 1], ["b", 2]]`)'
# {"a": 1, "b": 2}

Expression References

Use & for expression references (used with higher-order functions):

echo '[{"age": 30}, {"age": 20}]' | jpx 'sort_by(@, &age)'
# [{"age": 20}, {"age": 30}]

echo '[1, 2, 3]' | jpx 'map(&@ * `2`, @)'
# [2, 4, 6]

String Literals and Escaping

This guide covers how to properly write string literals, regex patterns, and special characters in JMESPath expressions. Understanding escaping is crucial for working with split(), replace(), regex functions, and any operation involving literal strings.

The Golden Rule

In JMESPath:

• Single quotes '...' = Identifiers (field names)
• Backticks with JSON `"..."` = String literals

# WRONG - 'hello' is an identifier (looks for a field named "hello")
echo '{"hello": "world"}' | jpx "'hello'"
# null (unless there's a field whose value equals the string "hello")

# RIGHT - `"hello"` is a string literal
echo '{"data": "hello"}' | jpx 'data == `"hello"`'
# true

String Literals Quick Reference

Special Characters

Newlines, Tabs, and Escapes

Inside backtick literals, use standard JSON escape sequences:

Example: Splitting by Newlines

# Split multi-line text into array
echo '"line1\nline2\nline3"' | jpx 'split(@, `"\n"`)'
# ["line1", "line2", "line3"]

Example: Working with Tabs

# Split TSV (tab-separated values)
echo '"name\tage\tcity"' | jpx 'split(@, `"\t"`)'
# ["name", "age", "city"]

Regex Patterns

Regex functions (regex_match, regex_extract, regex_replace, etc.) need their patterns as string literals.

Regex Quick Reference

Key insight: Backslash escapes in regex patterns need to be escaped for JSON, so \d becomes \\d inside the backtick literal.

Example: Extract Numbers

echo '"Order #12345"' | jpx 'regex_extract(@, `"\\d+"`)'
# "12345"

Example: Match Email Pattern

echo '"contact@example.com"' | jpx 'regex_match(@, `"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"`)'
# true

Example: Replace Whitespace

echo '"hello   world"' | jpx 'regex_replace(@, `"\\s+"`, `" "`)'
# "hello world"

Shell Escaping Layers

When running jpx from a shell, you have multiple escaping layers:

1. Shell interprets your command line
2. JMESPath parses the expression
3. JSON (inside backticks) parses the literal
4. Regex engine (for regex functions) interprets the pattern

Shell Quoting Strategies

Single quotes (recommended) - Shell doesn’t interpret anything:

# Best: Use single quotes around the entire expression
echo '{"text": "hello"}' | jpx 'regex_match(text, `"\\w+"`)'

Double quotes - Need to escape backticks and backslashes:

# Harder: Must escape backticks and double backslashes
echo '{"text": "hello"}' | jpx "regex_match(text, \`\"\\\\w+\"\`)"

Recommendation

Always use single quotes around your JMESPath expression when possible:

jpx 'your_expression_here'

This lets you write backticks and backslashes without shell interference.

Common Mistakes

Mistake 1: Using Single Quotes for Strings

# WRONG - 'hello' is an identifier
echo '{"x": "hello"}' | jpx "x == 'hello'"

# RIGHT - use backtick literal
echo '{"x": "hello"}' | jpx 'x == `"hello"`'

Mistake 2: Forgetting Quotes Inside Backticks

# WRONG - `hello` is not valid JSON
jpx '`hello`' --null-input

# RIGHT - strings need quotes inside backticks
jpx '`"hello"`' --null-input

Mistake 3: Over-escaping Regex Patterns

# WRONG - too many backslashes
echo '"abc123"' | jpx 'regex_extract(@, `"\\\\d+"`)'

# RIGHT - just escape once for JSON
echo '"abc123"' | jpx 'regex_extract(@, `"\\d+"`)'

Mistake 4: Confusing Identifier vs String

# This looks for field named "name" - CORRECT
echo '{"name": "Alice"}' | jpx 'name'
# "Alice"

# This compares against literal string - CORRECT
echo '{"name": "Alice"}' | jpx 'name == `"Alice"`'
# true

# This looks for field named by VALUE of 'name' field - WRONG (usually)
echo '{"name": "Alice"}' | jpx "'name'"
# null (looks for field "name" on string "Alice")

MCP Server Context

When using jpx through the MCP server (e.g., with Claude), there’s an additional JSON encoding layer. The MCP server handles this automatically, but be aware:

• Expressions are passed as JSON strings
• The server unescapes before evaluating
• When writing expressions in MCP tool calls, you typically don’t need extra escaping

Example MCP Tool Call

{
  "name": "jpx_query",
  "arguments": {
    "expression": "split(@, `\"\\n\"`)",
    "data": "line1\nline2\nline3"
  }
}

The MCP server handles the JSON string escaping, so \" becomes " and \\n becomes \n in the actual expression.

Debugging Tips

1. Use --null-input to test expressions without needing input data:

   jpx '`"test\\nstring"`' --null-input
   

2. Start simple - verify your literal works before using it in a function:

   # First, check the literal
   jpx '`"\\d+"`' --null-input
   # "\d+"
   
   # Then use it
   echo '"abc123"' | jpx 'regex_extract(@, `"\\d+"`)'
   

3. Check the AST for complex expressions:

   jpx --ast 'split(@, `"\n"`)'
   

Summary

Working with Files

jpx provides several ways to read input and write output, making it flexible for different workflows.

Reading Input

From stdin (default)

Pipe JSON directly to jpx:

echo '{"name": "alice"}' | jpx 'name'
# "alice"

cat data.json | jpx 'users[*].name'

curl -s https://api.example.com/data | jpx 'items[0]'

From a File

Use -f or --file to read from a file:

jpx -f data.json 'users[*].name'

jpx --file config.json 'settings.theme'

Null Input

Use -n or --null-input for expressions that don’t need input data:

jpx -n 'now()'
# "2024-01-15T10:30:00Z"

jpx -n 'uuid()'
# "550e8400-e29b-41d4-a716-446655440000"

jpx -n 'range(1, 5)'
# [1, 2, 3, 4]

Writing Output

To stdout (default)

Output goes to stdout with pretty-printing by default:

jpx -f data.json 'users[0]'
# {
#   "name": "alice",
#   "age": 30
# }

To a File

Use -o or --output to write to a file:

jpx -f data.json 'users[?active]' -o active-users.json

jpx -f input.json 'transform(@)' --output result.json

Compact Output

Use -c or --compact for single-line JSON (no pretty-printing):

jpx -c -f data.json 'users[0]'
# {"name":"alice","age":30}

Processing Multiple Files

Sequential Processing

Process files one at a time in a loop:

for f in *.json; do
  jpx -f "$f" 'metadata.title'
done

Combining Files with Slurp

Use -s or --slurp to combine multiple JSON values into an array:

cat file1.json file2.json file3.json | jpx -s 'length(@)'
# 3

cat *.json | jpx -s '[*].name'

Streaming JSON Lines (NDJSON)

Use --stream (or --each) for newline-delimited JSON:

# Process each line independently
cat events.ndjson | jpx --stream 'event_type'

# Filter and transform streaming data
cat logs.ndjson | jpx --stream '[?level == `error`].message'

Streaming mode uses constant memory regardless of file size.

Query Files

Store queries in files for reuse:

Plain Text Query Files

# query.txt contains: users[?active].{name: name, email: email}
jpx -Q query.txt -f data.json

Query Libraries (.jpx)

Create reusable query collections:

-- queries.jpx
-- :name active-users
-- :description Get all active users
users[?active]

-- :name user-emails
-- :description Extract just the email addresses
users[*].email

Run named queries:

jpx -Q queries.jpx:active-users -f data.json

# Or with --query flag
jpx -Q queries.jpx --query user-emails -f data.json

# List available queries
jpx -Q queries.jpx --list-queries

See Query Files for more details.

JSON Patch Operations

Generate Patches

Compare two files and generate a JSON Patch (RFC 6902):

jpx --diff original.json modified.json > changes.patch

Apply Patches

Apply a patch to a document:

jpx --patch changes.patch -f document.json -o updated.json

Merge Patches

Apply a JSON Merge Patch (RFC 7396):

jpx --merge updates.json -f document.json

Tips

Checking File Validity

Use --stats to quickly validate and analyze a JSON file:

jpx --stats -f data.json

Exploring File Structure

Use --paths to see all paths in a JSON document:

jpx --paths -f data.json

# With types
jpx --paths --types -f data.json

# With values
jpx --paths --values -f data.json

Benchmarking File Operations

Measure query performance on a file:

jpx --bench 1000 -f large-data.json 'complex[*].transformation'

Query Files

Query files let you store JMESPath expressions externally, making them reusable, version-controlled, and easier to maintain. jpx supports two formats:

1. Simple query files - A single expression in a plain text file
2. Query libraries (.jpx) - Multiple named queries in one file

Simple Query Files

The simplest approach: put your expression in a file and reference it with -Q:

# Create a query file
echo 'users[?active].{name: name, email: email}' > active-users.txt

# Use it
jpx -Q active-users.txt data.json

This is useful for:

• Long, complex expressions you don’t want to retype
• Sharing queries across scripts
• Version-controlling important queries

Query Libraries (.jpx)

For projects with multiple related queries, use a .jpx query library file. This format lets you define named queries with optional descriptions:

-- :name active-users
-- :desc Get all active users with their contact info
users[?active].{name: name, email: email}

-- :name admin-emails
-- :desc Extract just the admin email addresses  
users[?role == `admin`].email

-- :name user-stats
-- :desc Summary statistics about users
{
  total: length(users),
  active: length(users[?active]),
  admins: length(users[?role == `admin`])
}

File Format

• -- :name <name> starts a new query (required)
• -- :desc <description> adds a description (optional)
• -- other comment lines are ignored
• Everything else until the next -- :name is the query expression
• Multi-line expressions are supported

Using Query Libraries

There are two ways to run a query from a library:

# Colon syntax (concise)
jpx -Q queries.jpx:active-users data.json

# Separate flag (explicit)
jpx -Q queries.jpx --query active-users data.json

Both are equivalent. Use whichever feels more natural.

Listing Available Queries

See what queries are in a library:

jpx -Q queries.jpx --list-queries

Output:

Queries in queries.jpx:

  NAME          DESCRIPTION
  -----------   ----------------------------------------
  active-users  Get all active users with their contact info
  admin-emails  Extract just the admin email addresses
  user-stats    Summary statistics about users

Use: jpx -Q queries.jpx:<query-name> <input>

Validating Queries

Check that all queries in a library are syntactically valid:

jpx -Q queries.jpx --check

Output:

Validating queries.jpx...

  ✓ active-users
  ✓ admin-emails
  ✓ user-stats

All queries valid.

This is useful in CI pipelines to catch syntax errors before deployment.

Real-World Examples

NLP Analysis Library

Create reusable text processing pipelines:

-- :name clean-html
-- :desc Strip HTML tags and normalize whitespace
regex_replace(@, `<[^>]+>`, ` `) | collapse_whitespace(@)

-- :name extract-keywords
-- :desc Get top keywords from text (stemmed, no stopwords)
tokens(@) | remove_stopwords(@) | stems(@) | frequencies(@)

-- :name title-keywords
-- :desc Extract keywords from article titles
hits[*].title | join(` `, @) | tokens(@) | remove_stopwords(@) | stems(@) | frequencies(@)

-- :name reading-stats
-- :desc Get reading time and word count
{
  word_count: word_count(@),
  reading_time: reading_time(@),
  sentence_count: sentence_count(@)
}

Use it:

# Clean HTML from a field
jpx 'story_text' data.json | jpx -Q nlp.jpx:clean-html

# Analyze Hacker News titles
jpx -Q nlp.jpx:title-keywords hn_front.json

API Response Processing

Standardize how you extract data from APIs:

-- :name github-repos
-- :desc Extract repo summary from GitHub API response
[*].{
  name: name,
  stars: stargazers_count,
  language: language,
  description: description | default(@, `"No description"`)
}

-- :name github-issues
-- :desc Format GitHub issues for display  
[*].{
  number: number,
  title: title,
  state: state,
  author: user.login,
  labels: labels[*].name | join(`, `, @)
}

-- :name paginated-total
-- :desc Get total from paginated API response
{
  count: length(items),
  total: total_count,
  has_more: length(items) < total_count
}

Data Transformation Library

Common transformations for ETL pipelines:

-- :name flatten-nested
-- :desc Flatten nested user records for CSV export
[*].{
  id: id,
  name: profile.name,
  email: profile.email,
  city: profile.address.city,
  country: profile.address.country,
  created: metadata.created_at
}

-- :name aggregate-by-status
-- :desc Group and count records by status
group_by(@, &status) | map(&{ status: [0].status, count: length(@) }, @)

-- :name enrich-timestamps
-- :desc Add formatted date fields
[*] | map(&merge(@, {
  created_date: format_datetime(created_at, `%Y-%m-%d`),
  created_time: format_datetime(created_at, `%H:%M:%S`)
}), @)

Log Analysis Library

Queries for processing structured logs:

-- :name errors-only
-- :desc Filter to just error-level logs
[?level == `error` || level == `ERROR`]

-- :name errors-by-service
-- :desc Count errors grouped by service name
[?level == `error`] | group_by(@, &service) | map(&{ service: [0].service, count: length(@) }, @)

-- :name recent-errors
-- :desc Errors from the last hour with context
[?level == `error`] | sort_by(@, &timestamp) | reverse(@) | [:20].{
  time: timestamp,
  service: service,
  message: message,
  trace_id: trace_id
}

-- :name slow-requests
-- :desc Requests taking longer than 1 second
[?duration_ms > `1000`] | sort_by(@, &duration_ms) | reverse(@)

Best Practices

Naming Conventions

Use clear, descriptive names:

• active-users not au or query1
• errors-by-service not err-svc
• Use kebab-case for consistency

Add Descriptions

Always add -- :desc lines. They show up in --list-queries and help others (and future you) understand what each query does.

Organize by Domain

Group related queries into domain-specific libraries:

• nlp.jpx - Text processing pipelines
• api.jpx - API response transformations
• logs.jpx - Log analysis queries
• etl.jpx - Data transformation queries

Version Control

Query libraries are plain text files - perfect for git:

• Track changes to important queries
• Review query changes in PRs
• Share queries across your team

Validate in CI

Add query validation to your CI pipeline:

# .github/workflows/validate.yml
- name: Validate query libraries
  run: |
    for f in queries/*.jpx; do
      jpx -Q "$f" --check || exit 1
    done

CLI Reference

Colon Syntax

The colon syntax -Q file.jpx:query-name is shorthand for -Q file.jpx --query query-name.

Detection Logic

jpx automatically detects query libraries:

1. Files ending in .jpx are always treated as libraries
2. Files starting with -- :name are treated as libraries
3. Everything else is a simple single-query file

Migration from Simple Files

If you have many simple query files, consolidate them:

# Before: multiple files
queries/
  active-users.txt
  admin-emails.txt
  user-stats.txt

# After: one library
queries/users.jpx

Just add -- :name headers to combine them:

-- :name active-users
users[?active].{name: name, email: email}

-- :name admin-emails
users[?role == `admin`].email

-- :name user-stats
{total: length(users), active: length(users[?active])}

Strict Mode

Strict mode disables all extension functions, limiting jpx to only the 26 standard JMESPath functions. This is useful for writing portable queries that work with any JMESPath implementation.

Enabling Strict Mode

Use the --strict flag or set the JPX_STRICT=1 environment variable:

# Via flag
echo '{"name": "alice"}' | jpx --strict 'upper(name)'
# Error: Unknown function: upper

# Via environment variable
export JPX_STRICT=1
echo '{"items": [1, 2, 3]}' | jpx 'length(items)'
# 3

Standard JMESPath Functions

In strict mode, only these functions are available:

Use Cases

Portable Queries

If you’re writing queries that need to work across different JMESPath implementations (AWS CLI, Python jmespath, etc.), use strict mode to ensure compatibility:

# Test your query works with standard JMESPath
jpx --strict '[?status == `active`].name | sort(@)'

CI/CD Validation

Ensure queries in your codebase don’t accidentally use extensions:

# In your CI pipeline
jpx --strict -Q queries.jpx --check

Gradual Migration

When migrating from another JMESPath tool, start in strict mode and gradually adopt extensions as needed.

Checking if an Expression Uses Extensions

Use --explain to see what functions an expression uses:

jpx --explain 'users[*].name | unique(@) | sort(@)'

The unique function is an extension, while sort is standard.

MCP Server Strict Mode

The MCP server also supports strict mode. When configured with --strict, only standard JMESPath functions are available:

{
  "mcpServers": {
    "jpx-strict": {
      "command": "jpx-server",
      "args": ["--strict"]
    }
  }
}

Why jpx?

“I could just write Python or JavaScript for this - why use jpx?”

This is a fair question. Here’s why jpx is worth learning for JSON wrangling.

Almost No Syntax

JMESPath’s entire syntax fits on an index card:

That’s it. No for, if, def, import, class, let, const, =>, async, await…

You can learn the entire language in 10 minutes. The power comes from composing simple pieces, not memorizing syntax - the same insight that makes Lisp and shell pipelines compelling.

Compare to Python where “I want to extract some fields” requires knowing:

• Variable assignment
• Import statements
• List comprehensions (or for loops)
• Dictionary access
• String formatting
• File I/O

Zero Boilerplate

No imports. No script files. No virtual environments. Just pipe and go:

curl -s https://api.example.com/users | jpx 'users[*].name'

Compare to the Python equivalent:

import json
import sys

data = json.load(sys.stdin)
names = [user["name"] for user in data["users"]]
print(json.dumps(names))

That’s 5 lines (plus saving to a file, making it executable, etc.) vs. a single shell command.

Composable One-Liners

Shell pipelines are underrated. With jpx, you can do complex transformations in a single expression:

# Fetch, filter, transform, and sort in one line
curl -s https://api.github.com/users/octocat/repos \
  | jpx '[?stargazers_count > `100`] | sort_by(@, &stargazers_count) | reverse(@) | [*].{name: name, stars: stargazers_count}'

Or break it into multiple jpx calls when debugging:

curl -s https://api.github.com/users/octocat/repos \
  | jpx '[?stargazers_count > `100`]' \
  | jpx 'sort_by(@, &stargazers_count) | reverse(@) | [*].{name: name, stars: stargazers_count}'

Each step is independently testable. Add or remove transformations without rewriting a script.

Declarative vs Imperative

You describe what you want, not how to loop through it:

Imperative (Python):

result = []
for item in data["items"]:
    if item["active"]:
        result.append({"n": item["name"], "v": item["value"]})

Declarative (jpx):

jpx 'items[?active].{n: name, v: value}'

The jpx version is often more readable because it expresses intent directly.

The Learning Curve Comparison

Consistent Interface

Same syntax across:

• CLI (jpx 'query')
• MCP server (for AI assistants)
• Python bindings (jmespath_extensions.search('query', data))
• Rust library

Learn once, use everywhere.

No Runtime Dependencies

jpx is a single ~15MB binary. It works on any machine without Python, Node, or anything else installed.

• Great for CI/CD pipelines
• Works in minimal containers
• No “works on my machine” issues
• No dependency conflicts

Built for Exploration

When you’re exploring an unfamiliar API response, jpx helps you discover what’s there:

# Interactive REPL
jpx --repl

# See all paths in the data
jpx --paths -f data.json

# Search for functions
jpx --search "date"

# Get help on any function
jpx --describe format_date

# Find similar functions
jpx --similar levenshtein

Python requires knowing what to import before you start. jpx lets you explore first.

Safe for Automation

JMESPath expressions are pure functions with no side effects:

• No “oops I overwrote my file” moments
• No network calls from within queries
• No shell injection vulnerabilities
• Predictable, deterministic behavior

This makes jpx safe to use in scripts and automation.

When to Use What

jpx is for ad-hoc JSON exploration and transformation:

• “What’s in this API response?”
• “Extract these fields from 50 log files”
• “Quick data munging in a shell script”
• “Prototype a transformation before implementing it”

Use jpx when:

• Quick field extraction from JSON
• Ad-hoc API exploration
• Shell script data processing
• CI/CD pipeline JSON manipulation
• You need to explain the query to someone else

Use Python/JavaScript when:

• Complex business logic with many conditionals
• Stateful transformations
• Database operations
• Production ETL pipelines
• You need to integrate with other services

The sweet spot: use jpx for the JSON transformation step inside larger Python/JS applications:

import jmespath_extensions

# Complex Python logic here...
data = fetch_from_api()

# Let jpx handle the transformation
result = jmespath_extensions.search('items[?active].{id: id, name: upper(name)}', data)

# More Python logic...
save_to_database(result)

Coming from jq?

The key syntax differences:

jpx has more built-in functions (400+). jq is better for complex recursive transformations.

Summary

jpx trades generality for ergonomics. It can’t do everything Python can, but for its intended purpose - querying and transforming JSON - it’s faster to write, easier to read, and simpler to maintain.

The 10 minutes you spend learning JMESPath will save you hours of writing boilerplate data munging code.

MCP Server Overview

jpx can run as an MCP (Model Context Protocol) server, allowing AI assistants like Claude to use JMESPath for JSON querying and transformation.

What is MCP?

MCP is an open protocol that enables AI assistants to interact with external tools and data sources. By running jpx as an MCP server, you give Claude (and other MCP-compatible assistants) the ability to:

• Query JSON data using JMESPath expressions
• Transform and manipulate JSON structures
• Use all 400+ extension functions
• Explore available functions and their documentation

Why Use jpx with Claude?

When working with JSON data in Claude, jpx provides:

• Precise queries: Extract exactly the data you need
• Complex transformations: Reshape data structures on the fly
• Powerful functions: String manipulation, math, dates, hashing, and more
• Consistent results: Deterministic query execution

Available Tools

The MCP server exposes 25 tools organized by purpose:

Function Discovery Tools

Tools for finding and exploring available JMESPath functions:

Multi-Server Tool Discovery

Tools for semantic search across multiple MCP servers (see Discovery):

Data Analysis Tools

Tools for understanding JSON structure before querying:

Query Tools

Tools for evaluating JMESPath expressions:

JSON Utility Tools

Tools for JSON manipulation (RFC 6902/7396):

Typical Workflow for AI Agents

1. Analyze data: Use stats and paths to understand the JSON structure
2. Discover functions: Use search to find relevant functions, similar to explore alternatives
3. Build query: Use validate to check syntax before executing
4. Execute: Use evaluate or batch_evaluate to run queries
5. Transform: Use diff, patch, or merge for modifications

Getting Started

See Setup to configure jpx as an MCP server for Claude Desktop.

Setup with Claude Desktop

Configure jpx-server as an MCP server for Claude Desktop.

Prerequisites

1. Install jpx-server:

   cargo install jpx-server
   

   Or use Docker (no installation required).

2. Have Claude Desktop installed

Configuration

Docker (Recommended)

The simplest way to run jpx as an MCP server using the dedicated server image:

{
  "mcpServers": {
    "jpx": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/joshrotenberg/jpx-server"]
    }
  }
}

Available for linux/amd64 and linux/arm64.

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jpx": {
      "command": "jpx-server"
    }
  }
}

If jpx-server is not in your PATH, use the full path:

{
  "mcpServers": {
    "jpx": {
      "command": "/Users/yourname/.cargo/bin/jpx-server"
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "jpx": {
      "command": "C:\\path\\to\\jpx-server.exe"
    }
  }
}

Verify Setup

1. Restart Claude Desktop
2. Look for the jpx tools in Claude’s tool list
3. Try a simple query:

User: I have this JSON: {"users": [{"name": "alice"}, {"name": "bob"}]}
      Get all the names.

Claude: [Uses jpx.evaluate]
        Result: ["alice", "bob"]

Strict Mode

To use only standard JMESPath functions (no extensions):

{
  "mcpServers": {
    "jpx": {
      "command": "jpx-server",
      "args": ["--strict"]
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "jpx": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/joshrotenberg/jpx-server", "--strict"]
    }
  }
}

Troubleshooting

jpx-server not found

Make sure jpx-server is in your PATH, or use the full path in the config.

Tools not appearing

1. Check the config file syntax (must be valid JSON)
2. Restart Claude Desktop completely
3. Check Claude Desktop logs for errors

Permission errors on file access

The evaluate_file tool has security restrictions. It only allows access to files in safe directories (not system paths).

Available Tools

The jpx MCP server provides 26 tools organized into five categories.

Function Discovery

Tools for exploring the 400+ JMESPath extension functions.

search

Fuzzy search for functions by name, description, category, or signature.

{
  "query": "string manipulation",
  "limit": 10
}

similar

Find functions related to a specified function.

{
  "function": "upper",
  "limit": 5
}

Returns functions with similar purpose (e.g., lower, capitalize, title_case).

functions

List available functions, optionally filtered by category.

{
  "category": "string"
}

describe

Get detailed documentation for a specific function.

{
  "function": "pad_left"
}

Returns signature, description, parameters, return type, and examples.

categories

List all function categories with tool counts.

{}

Data Analysis

Tools for understanding JSON structure before writing queries.

stats

Analyze JSON structure and statistics.

{
  "json": {"users": [{"name": "Alice"}, {"name": "Bob"}]}
}

Returns type, size, depth, and field analysis.

paths

Extract all paths in a JSON document using dot notation.

{
  "json": {"user": {"profile": {"name": "Alice"}}}
}

Returns: ["user", "user.profile", "user.profile.name"]

keys

Extract object keys, optionally recursive with dot notation.

{
  "json": {"a": {"b": 1}},
  "recursive": true
}

Query Execution

Tools for running JMESPath expressions.

evaluate

Run a JMESPath expression against JSON input.

{
  "expression": "users[?age > `30`].name",
  "json": {"users": [{"name": "Alice", "age": 35}, {"name": "Bob", "age": 25}]}
}

Returns: ["Alice"]

evaluate_file

Query a JSON file directly from disk. Useful when the file is too large to pass inline or when you want to avoid serialization overhead.

{
  "expression": "length(items)",
  "path": "/path/to/data.json"
}

batch_evaluate

Run multiple expressions against the same input.

{
  "expressions": ["length(@)", "keys(@)", "@.name"],
  "json": {"name": "test", "value": 42}
}

validate

Check expression syntax without executing.

{
  "expression": "users[?active].name"
}

Returns validation status and any syntax errors.

JSON Utilities

Tools for JSON manipulation following RFC standards (RFC 6902 for JSON Patch, RFC 7396 for Merge Patch).

format

Pretty-print JSON with configurable indentation.

{
  "json": {"compact": true},
  "indent": 2
}

diff

Generate RFC 6902 JSON Patch between two documents.

{
  "source": {"a": 1},
  "target": {"a": 2, "b": 3}
}

Returns patch operations: [{"op": "replace", "path": "/a", "value": 2}, {"op": "add", "path": "/b", "value": 3}]

patch

Apply RFC 6902 JSON Patch operations.

{
  "json": {"a": 1},
  "operations": [{"op": "add", "path": "/b", "value": 2}]
}

merge

Apply RFC 7396 JSON Merge Patch.

{
  "json": {"a": 1, "b": 2},
  "patch": {"b": null, "c": 3}
}

Returns: {"a": 1, "c": 3} (null removes keys)

Multi-Server Discovery

Tools for semantic search across multiple MCP servers. See Multi-Server Discovery for full documentation.

register_discovery

Register an MCP server’s tools for BM25 indexing using the full discovery spec.

{
  "spec": {
    "server": {"name": "myserver", "version": "1.0.0"},
    "tools": [
      {"name": "tool_one", "description": "Does something useful", "category": "utils"}
    ]
  }
}

register_tools_simple

Quick registration without the full schema. Just provide server name and tools array.

{
  "server_name": "myserver",
  "tools": [
    {"name": "backup_db", "description": "Backup the database", "tags": ["database", "backup"]},
    {"name": "restore_db", "description": "Restore from backup", "tags": ["database", "restore"]}
  ]
}

query_tools

Semantic search across all registered tools.

{
  "query": "backup database",
  "top_k": 5
}

Returns ranked results with BM25 scores.

similar_tools

Find tools related to a specific tool.

{
  "tool_id": "myserver:tool_one",
  "top_k": 5
}

list_discovery_servers

List all registered servers with tool counts.

{}

list_discovery_categories

List tool categories across all registered servers.

{}

inspect_discovery_index

Get index statistics for debugging.

{}

Returns server count, tool count, term count, and average document length.

unregister_discovery

Remove a server from the registry.

{
  "server": "myserver"
}

get_discovery_schema

Get the JSON schema for registration.

{}

Multi-Server Tool Discovery

jpx provides BM25-based semantic search for discovering tools across multiple MCP servers. This enables natural language queries like “how do I backup a database?” instead of scanning flat tool lists.

The Problem

When an agent connects to multiple MCP servers, it has access to dozens or hundreds of tools. Finding the right tool for a task means:

• Scanning tool names hoping for a match
• Reading descriptions one by one
• Missing tools with different terminology (“backup” vs “snapshot” vs “export”)

The Solution: Registration + Search

jpx provides a discovery registry that indexes tools from any MCP server using BM25 (the algorithm behind search engines). The workflow:

1. Register: Agent registers each server’s tools with jpx
2. Search: Agent queries across all registered tools semantically
3. Discover: BM25 finds relevant tools even with different wording

Architecture

MCP servers don’t communicate with each other - they only respond to the agent. The agent orchestrates registration:

┌─────────┐     ┌─────────────┐     ┌─────────────┐
│  Agent  │────▶│     jpx     │     │  redisctl   │
│         │────▶│  (registry) │     │  (65 tools) │
│         │────▶│             │     └─────────────┘
│         │     └─────────────┘     ┌─────────────┐
│         │────────────────────────▶│ other-mcp   │
│         │                         │  (N tools)  │
└─────────┘                         └─────────────┘
     │
     │  1. Connect to all servers
     │  2. Get tool metadata from each
     │  3. Register with jpx
     │  4. Query jpx for tool discovery
     ▼

Discovery Tools

Registration

Search

Browse

Registration Schema

Register a server’s tools with register_discovery:

{
  "spec": {
    "server": {
      "name": "redisctl",
      "version": "0.1.0",
      "description": "Redis management tools"
    },
    "tools": [
      {
        "name": "enterprise_database_create",
        "description": "Create a new Redis Enterprise database with specified configuration",
        "category": "enterprise",
        "subcategory": "database",
        "tags": ["database", "create", "write"],
        "examples": ["Create a 500MB database named 'cache'"]
      },
      {
        "name": "enterprise_database_backup",
        "description": "Trigger a backup snapshot of a Redis Enterprise database",
        "category": "enterprise",
        "subcategory": "database",
        "tags": ["database", "backup", "snapshot", "read"]
      }
    ],
    "categories": {
      "enterprise": {
        "description": "Redis Enterprise on-premises tools",
        "tool_count": 30
      }
    }
  },
  "replace": false
}

Minimal Schema

Only server.name and tools[].name are required:

{
  "spec": {
    "server": { "name": "myserver" },
    "tools": [
      { "name": "tool_one" },
      { "name": "tool_two" }
    ]
  }
}

Full Schema

For best search results, include rich metadata:

• description: Natural language description (indexed for search)
• category / subcategory: For browsing and filtering
• tags: Keywords that improve search relevance
• examples: Usage examples (indexed for search)
• inputSchema: Parameter documentation

Searching

Semantic Search

// query_tools
{
  "query": "backup database",
  "top_k": 5
}

Returns ranked results with scores:

[
  {
    "tool_id": "redisctl:enterprise_database_backup",
    "server": "redisctl",
    "name": "enterprise_database_backup",
    "description": "Trigger a backup snapshot of a Redis Enterprise database",
    "score": 8.42,
    "category": "enterprise"
  },
  {
    "tool_id": "redisctl:enterprise_database_export",
    "server": "redisctl",
    "name": "enterprise_database_export",
    "description": "Export database data to RDB file",
    "score": 5.17,
    "category": "enterprise"
  }
]

Similar Tools

Find tools related to one you know:

// similar_tools
{
  "tool_id": "redisctl:enterprise_database_delete",
  "top_k": 5
}

Returns tools with similar descriptions/tags - useful for finding alternatives or related operations.

Agent Workflow

Manual Registration

At session start, register each server:

1. Get tool list from redisctl (agent already has this via MCP)
2. Call jpx.register_discovery with redisctl's tools
3. Repeat for other MCP servers
4. Use query_tools for semantic search

Automatic Registration (Recommended)

Add to your agent’s system prompt or CLAUDE.md:

## MCP Tool Discovery

At session start, if jpx and other MCP servers are available:

1. For each non-jpx MCP server, register its tools with jpx:
   - Extract tool name, description, and input schema
   - Call `mcp__jpx__register_discovery` with the server name and tool list

2. When searching for tools, use `mcp__jpx__query_tools` for semantic search
   instead of scanning the tool list manually.

3. Use `mcp__jpx__similar_tools` to find related tools when exploring options.

Example: Multi-Server Setup

With jpx + redisctl + github-mcp:

// Register redisctl (65 tools)
register_discovery({
  spec: {
    server: { name: "redisctl", version: "0.1.0" },
    tools: [
      { name: "enterprise_database_create", description: "...", category: "enterprise" },
      { name: "enterprise_database_backup", description: "...", category: "enterprise" },
      // ... 63 more tools
    ]
  }
})

// Register github-mcp (20 tools)
register_discovery({
  spec: {
    server: { name: "github", version: "1.0.0" },
    tools: [
      { name: "create_issue", description: "Create a GitHub issue", category: "issues" },
      { name: "list_pull_requests", description: "List PRs for a repo", category: "pulls" },
      // ... 18 more tools
    ]
  }
})

// Now search across both!
query_tools({ query: "create new resource", top_k: 10 })
// Returns: enterprise_database_create, create_issue, enterprise_crdb_create, ...

BM25 Scoring

The search uses BM25, a proven ranking algorithm that:

• Weights rare terms higher: “kubernetes” is more distinctive than “create”
• Handles term frequency saturation: Repeating a word doesn’t linearly increase relevance
• Normalizes by document length: Short and long descriptions scored fairly

This means “backup database” finds tools mentioning “snapshot”, “export”, “persist” if those terms appear in similar contexts across the corpus.

Session Scope

The registry is session-scoped (in-memory):

• Fresh index each agent session
• No persistence across sessions
• Cheap to rebuild from source

This is intentional - tool metadata changes, and re-registration ensures the index matches current reality.

Inspecting the Index

Debug with inspect_discovery_index:

{
  "server_count": 2,
  "tool_count": 85,
  "term_count": 342,
  "avg_doc_length": 12.4,
  "servers": ["redisctl", "github"]
}

List categories with list_discovery_categories:

{
  "enterprise": { "tool_count": 30, "servers": ["redisctl"] },
  "cloud": { "tool_count": 25, "servers": ["redisctl"] },
  "issues": { "tool_count": 8, "servers": ["github"] },
  "pulls": { "tool_count": 6, "servers": ["github"] }
}

MCP Examples

This page demonstrates common workflows using the jpx MCP server with Claude or other AI assistants.

Data Exploration

Understanding Unknown JSON

When you receive unfamiliar JSON data, start by exploring its structure:

User: I have this API response, can you help me understand it?

Claude: Let me analyze the structure first.

[Uses stats tool]
{
  "input": "{\"users\": [{\"id\": 1, \"profile\": {\"name\": \"Alice\", \"settings\": {\"theme\": \"dark\"}}}]}"
}

Result: Object with 1 key, depth 4, contains array of 1 object

[Uses paths tool]
{
  "input": "{\"users\": [{\"id\": 1, \"profile\": {\"name\": \"Alice\"}}]}",
  "include_types": true
}

Result:
  users: array
  users.0: object
  users.0.id: number
  users.0.profile: object
  users.0.profile.name: string

Finding the Right Function

When you need to transform data but aren’t sure which function to use:

User: I need to remove duplicate entries from an array

Claude: Let me search for relevant functions.

[Uses search tool]
{
  "query": "remove duplicates array unique"
}

Result: Found unique(), distinct(), dedupe() - all do similar things.

[Uses describe tool]
{
  "name": "unique"
}

Result: unique(array) - Returns array with duplicate elements removed, preserving order.

Query Building

Iterative Query Development

Build complex queries step by step:

User: Help me extract active premium users with their subscription dates

Claude: Let me build this query incrementally.

[Uses evaluate tool - Step 1: Filter active users]
{
  "expression": "users[?status == `active`]",
  "input": "{\"users\": [{\"name\": \"Alice\", \"status\": \"active\", \"plan\": \"premium\", \"since\": \"2024-01-15\"}, {\"name\": \"Bob\", \"status\": \"inactive\", \"plan\": \"free\", \"since\": \"2023-06-01\"}]}"
}

[Uses evaluate tool - Step 2: Add premium filter]
{
  "expression": "users[?status == `active` && plan == `premium`]",
  "input": "..."
}

[Uses evaluate tool - Step 3: Project fields]
{
  "expression": "users[?status == `active` && plan == `premium`].{name: name, member_since: since}",
  "input": "..."
}

Final query: users[?status == `active` && plan == `premium`].{name: name, member_since: since}

Validating Expressions

Check syntax before running on large datasets:

[Uses validate tool]
{
  "expression": "users[?active].name | sort(@"
}

Result: Invalid - unclosed parenthesis at position 27

[Uses validate tool]
{
  "expression": "users[?active].name | sort(@)"
}

Result: Valid expression

Batch Operations

Multiple Extractions

Extract several pieces of information at once:

[Uses batch_evaluate tool]
{
  "input": "{\"items\": [1, 2, 3, 4, 5], \"metadata\": {\"count\": 5, \"type\": \"numbers\"}}",
  "expressions": [
    "length(items)",
    "sum(items)",
    "avg(items)",
    "metadata.type"
  ]
}

Result:
  length(items): 5
  sum(items): 15
  avg(items): 3
  metadata.type: "numbers"

File Operations

Working with Large Files

Query files directly without loading into memory:

[Uses evaluate_file tool]
{
  "file_path": "/path/to/large-dataset.json",
  "expression": "records[?timestamp > `2024-01-01`] | length(@)"
}

Result: 15234 records match the filter

JSON Transformations

Generating Patches

Track changes between document versions:

[Uses diff tool]
{
  "source": "{\"version\": 1, \"config\": {\"debug\": true, \"timeout\": 30}}",
  "target": "{\"version\": 2, \"config\": {\"debug\": false, \"timeout\": 60, \"retries\": 3}}"
}

Result:
[
  {"op": "replace", "path": "/version", "value": 2},
  {"op": "replace", "path": "/config/debug", "value": false},
  {"op": "replace", "path": "/config/timeout", "value": 60},
  {"op": "add", "path": "/config/retries", "value": 3}
]

Applying Updates

Merge configuration updates:

[Uses merge tool]
{
  "input": "{\"database\": {\"host\": \"localhost\", \"port\": 5432}, \"cache\": {\"enabled\": true}}",
  "patch": "{\"database\": {\"host\": \"db.example.com\"}, \"cache\": null}"
}

Result:
{
  "database": {"host": "db.example.com", "port": 5432}
}

Note: Setting a key to null in merge patch removes it.

Function Discovery Workflows

Learning New Functions

Explore related functionality:

[Uses similar tool]
{
  "function": "snake_case"
}

Result:
  Same category: camel_case, kebab_case, pascal_case, title_case
  Similar signature: upper, lower, capitalize
  Related concepts: snake_keys, camel_keys (for object keys)

Category Exploration

See all functions in a category:

[Uses functions tool]
{
  "category": "datetime"
}

Result:
  now() - Current timestamp
  format_date(date, format) - Format date string
  parse_date(string, format) - Parse date from string
  date_add(date, amount, unit) - Add time to date
  date_diff(date1, date2, unit) - Difference between dates
  ...

Multi-Server Discovery

When working with multiple MCP servers, use discovery tools to find the right tool across all servers:

[Uses query_tools tool]
{
  "query": "send email notification",
  "top_k": 5
}

Result:
  1. notifications:send_email (score: 12.4)
  2. mailer:compose_message (score: 8.2)
  3. alerts:notify_user (score: 6.1)

See Multi-Server Discovery for more details on setting up cross-server tool search.

Function Overview

jpx provides 400+ functions organized into 31 categories.

Discovering Functions

List All Functions

jpx --list-functions

List by Category

jpx --list-category string
jpx --list-category math
jpx --list-category datetime

Get Function Details

jpx --describe upper

Categories

Function Syntax

Functions are called with parentheses:

function_name(arg1, arg2, ...)

Examples

# No arguments
echo '{}' | jpx 'now()'

# One argument
echo '{"name": "hello"}' | jpx 'upper(name)'

# Multiple arguments
echo '{"text": "hello world"}' | jpx 'split(text, ` `)'

# Literal arguments (use backticks)
echo '{}' | jpx 'range(`1`, `10`)'

Standard vs Extension Functions

Standard Functions (26)

These are part of the JMESPath specification and work in all implementations:

abs, avg, ceil, contains, ends_with, floor, join, keys, length, map, max, max_by, merge, min, min_by, not_null, reverse, sort, sort_by, starts_with, sum, to_array, to_number, to_string, type, values

Extension Functions (369)

These are jpx-specific and won’t work in other JMESPath implementations.

Strict Mode

Use --strict to disable extension functions:

# This works
jpx --strict 'length(items)' -f data.json

# This fails (upper is an extension)
jpx --strict 'upper(name)' -f data.json

Standard JMESPath Functions

These are the standard JMESPath functions as defined in the specification. They work in all JMESPath implementations.

Summary

Functions

abs

Returns the absolute value of a number

Signature: number -> number

Examples:

# Negative number
abs(`-5`) -> 5
# Positive number
abs(`5`) -> 5
# Zero
abs(`0`) -> 0

CLI Usage:

echo '{}' | jpx 'abs(`-5`)'

avg

Returns the average of an array of numbers

Signature: array[number] -> number

Examples:

# Simple average
avg([1, 2, 3]) -> 2
# Four numbers
avg([10, 20, 30, 40]) -> 25
# Single element
avg([5]) -> 5

CLI Usage:

echo '{}' | jpx 'avg([1, 2, 3])'

ceil

Returns the smallest integer greater than or equal to the number

Signature: number -> number

Examples:

# Round up decimal
ceil(`1.5`) -> 2
# Negative rounds toward zero
ceil(`-1.5`) -> -1
# Integer unchanged
ceil(`5`) -> 5

CLI Usage:

echo '{}' | jpx 'ceil(`1.5`)'

contains

Returns true if the subject contains the search value

Signature: array|string, any -> boolean

Examples:

# Array contains number
contains([1, 2, 3], `2`) -> true
# String contains substring
contains('hello', 'ell') -> true
# Not found
contains([1, 2, 3], `5`) -> false

CLI Usage:

echo '{}' | jpx 'contains([1, 2, 3], `2`)'

ends_with

Returns true if the subject ends with the suffix

Signature: string, string -> boolean

Examples:

# Ends with suffix
ends_with('hello', 'lo') -> true
# Does not end with
ends_with('hello', 'he') -> false
# File extension
ends_with('test.txt', '.txt') -> true

CLI Usage:

echo '{}' | jpx 'ends_with(`"hello"`, `"lo"`)'

floor

Returns the largest integer less than or equal to the number

Signature: number -> number

Examples:

# Round down decimal
floor(`1.9`) -> 1
# Negative rounds away from zero
floor(`-1.5`) -> -2
# Integer unchanged
floor(`5`) -> 5

CLI Usage:

echo '{}' | jpx 'floor(`1.9`)'

join

Returns array elements joined into a string with a separator

Signature: string, array[string] -> string

Examples:

# Join with comma
join(', ', ['a', 'b', 'c']) -> \"a, b, c\"
# Join date parts
join('-', ['2024', '01', '15']) -> \"2024-01-15\"
# Join without separator
join('', ['a', 'b', 'c']) -> \"abc\"

CLI Usage:

echo '{}' | jpx 'join(`", "`, ['a', `"b"`, 'c'])'

keys

Returns an array of keys from an object

Signature: object -> array[string]

Examples:

# Get object keys
keys({a: 1, b: 2}) -> [\"a\", \"b\"]
# Keys sorted alphabetically
keys({name: \"John\", age: 30}) -> [\"age\", \"name\"]
# Empty object
keys({}) -> []

CLI Usage:

echo '{}' | jpx 'keys({a: 1, b: 2})'

length

Returns the length of an array, object, or string

Signature: array|object|string -> number

Examples:

# Array length
length([1, 2, 3]) -> 3
# String length
length('hello') -> 5
# Object key count
length({a: 1, b: 2}) -> 2

CLI Usage:

echo '{}' | jpx 'length([1, 2, 3])'

map

Applies an expression to each element of an array

Signature: expression, array -> array

Examples:

# Extract field from objects
map(&a, [{a: 1}, {a: 2}]) -> [1, 2]
# Apply function
map(&length(@), ['a', 'bb', 'ccc']) -> [1, 2, 3]
# Identity mapping
map(&@, [1, 2, 3]) -> [1, 2, 3]

CLI Usage:

echo '{}' | jpx 'map(&a, [{a: 1}, {a: 2}])'

max

Returns the maximum value in an array

Signature: array[number]|array[string] -> number|string

Examples:

# Max of numbers
max([1, 3, 2]) -> 3
# Max of strings
max(['a', 'c', 'b']) -> 'c'
# Negative numbers
max([-5, -1, -10]) -> -1

CLI Usage:

echo '{}' | jpx 'max([1, 3, 2])'

max_by

Returns the element with maximum value by expression

Signature: array, expression -> any

Examples:

# Max by field
max_by([{a: 1}, {a: 2}], &a) -> {a: 2}
# Max by age
max_by([{name: 'a', age: 30}, {name: 'b', age: 25}], &age) -> {name: 'a', age: 30}
# Max by length
max_by(['aa', 'b', 'ccc'], &length(@)) -> 'ccc'

CLI Usage:

echo '{}' | jpx 'max_by([{a: 1}, {a: 2}], &a)'

merge

Merges objects into a single object

Signature: object... -> object

Examples:

# Merge two objects
merge({a: 1}, {b: 2}) -> {a: 1, b: 2}
# Later values override
merge({a: 1}, {a: 2}) -> {a: 2}
# Multiple objects
merge({a: 1}, {b: 2}, {c: 3}) -> {a: 1, b: 2, c: 3}

CLI Usage:

echo '{}' | jpx 'merge({a: 1}, {b: 2})'

min

Returns the minimum value in an array

Signature: array[number]|array[string] -> number|string

Examples:

# Min of numbers
min([1, 3, 2]) -> 1
# Min of strings
min(['a', 'c', 'b']) -> 'a'
# Negative numbers
min([-5, -1, -10]) -> -10

CLI Usage:

echo '{}' | jpx 'min([1, 3, 2])'

min_by

Returns the element with minimum value by expression

Signature: array, expression -> any

Examples:

# Min by field
min_by([{a: 1}, {a: 2}], &a) -> {a: 1}
# Min by age
min_by([{name: 'a', age: 30}, {name: 'b', age: 25}], &age) -> {name: 'b', age: 25}
# Min by length
min_by(['aa', 'b', 'ccc'], &length(@)) -> 'b'

CLI Usage:

echo '{}' | jpx 'min_by([{a: 1}, {a: 2}], &a)'

not_null

Returns the first non-null argument

Signature: any... -> any

Examples:

# Skip nulls
not_null(`null`, 'a', 'b') -> \"a\"
# First non-null
not_null('first', 'second') -> \"first\"
# Multiple nulls
not_null(`null`, `null`, `1`) -> 1

CLI Usage:

echo '{}' | jpx 'not_null(`null`, `"a"`, `"b"`)'

reverse

Reverses an array or string

Signature: array|string -> array|string

Examples:

# Reverse array
reverse([1, 2, 3]) -> [3, 2, 1]
# Reverse string
reverse('hello') -> 'olleh'
# Empty array
reverse([]) -> []

CLI Usage:

echo '{}' | jpx 'reverse([1, 2, 3])'

sort

Sorts an array of numbers or strings

Signature: array[number]|array[string] -> array

Examples:

# Sort numbers
sort([3, 1, 2]) -> [1, 2, 3]
# Sort strings
sort(['c', 'a', 'b']) -> ['a', 'b', 'c']
# Empty array
sort([]) -> []

CLI Usage:

echo '{}' | jpx 'sort([3, 1, 2])'

sort_by

Sorts an array by expression result

Signature: array, expression -> array

Examples:

# Sort by field
sort_by([{a: 2}, {a: 1}], &a) -> [{a: 1}, {a: 2}]
# Sort by length
sort_by(['bb', 'a', 'ccc'], &length(@)) -> ['a', 'bb', 'ccc']
# Sort by name
sort_by([{name: 'z'}, {name: 'a'}], &name) -> [{name: 'a'}, {name: 'z'}]

CLI Usage:

echo '{}' | jpx 'sort_by([{a: 2}, {a: 1}], &a)'

starts_with

Returns true if the subject starts with the prefix

Signature: string, string -> boolean

Examples:

# Starts with prefix
starts_with('hello', 'he') -> true
# Does not start with
starts_with('hello', 'lo') -> false
# URL protocol
starts_with('https://example.com', 'https') -> true

CLI Usage:

echo '{}' | jpx 'starts_with(`"hello"`, `"he"`)'

sum

Returns the sum of an array of numbers

Signature: array[number] -> number

Examples:

# Sum of numbers
sum([1, 2, 3]) -> 6
# With negative
sum([10, -5, 3]) -> 8
# Empty array
sum([]) -> 0

CLI Usage:

echo '{}' | jpx 'sum([1, 2, 3])'

to_array

Converts a value to an array

Signature: any -> array

Examples:

# String to array
to_array('hello') -> [\"hello\"]
# Array unchanged
to_array([1, 2]) -> [1, 2]
# Number to array
to_array(`5`) -> [5]

CLI Usage:

echo '{}' | jpx 'to_array(`"hello"`)'

to_number

Converts a value to a number

Signature: any -> number

Examples:

# String to number
to_number('42') -> 42
# String to float
to_number('3.14') -> 3.14
# Number unchanged
to_number(`5`) -> 5

CLI Usage:

echo '{}' | jpx 'to_number(`"42"`)'

to_string

Converts a value to a string

Signature: any -> string

Examples:

# Number to string
to_string(`42`) -> \"42\"
# Boolean to string
to_string(`true`) -> \"true\"
# String unchanged
to_string('hello') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'to_string(`42`)'

type

Returns the type of a value as a string

Signature: any -> string

Examples:

# String type
type('hello') -> \"string\"
# Number type
type(`42`) -> \"number\"
# Array type
type([1, 2]) -> \"array\"
# Object type
type({a: 1}) -> \"object\"

CLI Usage:

echo '{}' | jpx 'type(`"hello"`)'

values

Returns an array of values from an object

Signature: object -> array

Examples:

# Get object values
values({a: 1, b: 2}) -> [1, 2]
# String values
values({x: 'hello', y: 'world'}) -> ['hello', 'world']
# Empty object
values({}) -> []

CLI Usage:

echo '{}' | jpx 'values({a: 1, b: 2})'

String Functions

Functions for string manipulation: case conversion, splitting, joining, padding, and text processing.

Summary

Functions

abbreviate

Truncate string with ellipsis suffix

Signature: string, number, string? -> string

Examples:

# Default ellipsis
abbreviate('hello world', `8`) -> \"hello...\"
# No truncation needed
abbreviate('hello', `10`) -> \"hello\"
# Custom suffix
abbreviate('hello world', `8`, '>>') -> \"hello >>\"

CLI Usage:

echo '{}' | jpx 'abbreviate(`"hello world"`, `8`)'

camel_case

Convert to camelCase

Signature: string -> string

Examples:

# From snake_case
camel_case('hello_world') -> \"helloWorld\"
# From kebab-case
camel_case('hello-world') -> \"helloWorld\"
# From title case
camel_case('Hello World') -> \"helloWorld\"

CLI Usage:

echo '{}' | jpx 'camel_case(`"hello_world"`)'

capitalize

Capitalize the first character

Signature: string -> string

Examples:

# Basic capitalize
capitalize('hello') -> \"Hello\"
# Already uppercase
capitalize('HELLO') -> \"HELLO\"
# Empty string
capitalize('') -> \"\"

CLI Usage:

echo '{}' | jpx 'capitalize(`"hello"`)'

center

Center-pad string to given width

Signature: string, number, string? -> string

Examples:

# Center with spaces
center('hi', `6`) -> \"  hi  \"
# Center with dashes
center('hi', `6`, '-') -> \"--hi--\"
# Already wider
center('hello', `3`) -> \"hello\"

CLI Usage:

echo '{}' | jpx 'center(`"hi"`, `6`)'

concat

Concatenate strings

Signature: string... -> string

Examples:

# Multiple strings
concat('hello', ' ', 'world') -> \"hello world\"
# Two strings
concat('a', 'b') -> \"ab\"
# Single string
concat('only') -> \"only\"

CLI Usage:

echo '{}' | jpx 'concat(`"hello"`, `" "`, `"world"`)'

explode

Convert a string to an array of Unicode codepoints

Signature: string -> array

Examples:

# ASCII characters
explode('abc') -> [97, 98, 99]
# Unicode characters
explode('A☺') -> [65, 9786]
# Empty string
explode('') -> []

CLI Usage:

echo '{}' | jpx 'explode(`"abc"`)'

find_first

Find first occurrence of substring

Signature: string, string -> number | null

JEP: JEP-014

Examples:

# Find character
find_first('hello', 'l') -> 2
# Find substring
find_first('hello world', 'world') -> 6
# Not found
find_first('hello', 'x') -> null

CLI Usage:

echo '{}' | jpx 'find_first(`"hello"`, `"l"`)'

find_last

Find last occurrence of substring

Signature: string, string -> number | null

JEP: JEP-014

Examples:

# Find last character
find_last('hello', 'l') -> 3
# Find last substring
find_last('foo bar foo', 'foo') -> 8
# Not found
find_last('hello', 'x') -> null

CLI Usage:

echo '{}' | jpx 'find_last(`"hello"`, `"l"`)'

implode

Convert an array of Unicode codepoints to a string

Signature: array -> string

Examples:

# ASCII codepoints
implode([97, 98, 99]) -> \"abc\"
# Unicode codepoints
implode([65, 9786]) -> \"A☺\"
# Empty array
implode([]) -> \"\"

CLI Usage:

echo '{}' | jpx 'implode([97, 98, 99])'

indices

Find all indices of substring occurrences

Signature: string, string -> array

Examples:

# Multiple occurrences
indices('hello', 'l') -> [2, 3]
# Overlapping matches
indices('ababa', 'aba') -> [0, 2]
# No matches
indices('hello', 'x') -> []

CLI Usage:

echo '{}' | jpx 'indices(`"hello"`, `"l"`)'

inside

Check if search string is contained in string

Signature: string, string -> boolean

Examples:

# Found
inside('world', 'hello world') -> true
# Not found
inside('foo', 'hello world') -> false
# Empty string always matches
inside('', 'hello') -> true

CLI Usage:

echo '{}' | jpx 'inside(`"world"`, `"hello world"`)'

is_blank

Check if string is empty or whitespace-only

Signature: string -> boolean

Examples:

# Whitespace only
is_blank('   ') -> true
# Empty string
is_blank('') -> true
# Has content
is_blank('hello') -> false

CLI Usage:

echo '{}' | jpx 'is_blank(`"   "`)'

kebab_case

Convert to kebab-case

Signature: string -> string

Examples:

# From camelCase
kebab_case('helloWorld') -> \"hello-world\"
# From snake_case
kebab_case('hello_world') -> \"hello-world\"
# From title case
kebab_case('Hello World') -> \"hello-world\"

CLI Usage:

echo '{}' | jpx 'kebab_case(`"helloWorld"`)'

lower

Convert string to lowercase

Signature: string -> string

JEP: JEP-014

Examples:

# All uppercase
lower('HELLO') -> \"hello\"
# Mixed case
lower('Hello World') -> \"hello world\"
# Already lowercase
lower('hello') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'lower(`"HELLO"`)'

pascal_case

Convert to PascalCase (also known as UpperCamelCase)

Signature: string -> string

Examples:

# From snake_case
pascal_case('hello_world') -> "HelloWorld"
# From camelCase
pascal_case('helloWorld') -> "HelloWorld"
# From kebab-case
pascal_case('hello-world') -> "HelloWorld"
# Handles acronyms
pascal_case('xml_parser') -> "XmlParser"

CLI Usage:

echo '{}' | jpx 'pascal_case(`"hello_world"`)'

ltrimstr

Remove prefix from string if present

Signature: string, string -> string

Examples:

# Remove prefix
ltrimstr('foobar', 'foo') -> \"bar\"
# Prefix not found
ltrimstr('foobar', 'bar') -> \"foobar\"
# Empty prefix
ltrimstr('hello', '') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'ltrimstr(`"foobar"`, `"foo"`)'

mask

Mask string, keeping last N characters visible

Signature: string, number?, string? -> string

Examples:

# Credit card
mask('4111111111111111', `4`) -> \"************1111\"
# Mask all
mask('secret', `0`) -> \"******\"
# Custom mask char
mask('password', `4`, '#') -> \"####word\"

CLI Usage:

echo '{}' | jpx 'mask(`"4111111111111111"`, `4`)'

normalize_whitespace

Collapse multiple whitespace to single space

Signature: string -> string

Examples:

# Multiple spaces
normalize_whitespace('a  b  c') -> \"a b c\"
# Newlines to space
normalize_whitespace('a\\n\\nb') -> \"a b\"
# Already normalized
normalize_whitespace('hello') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'normalize_whitespace(`"a  b  c"`)'

pad_left

Pad string on the left to reach target length

Signature: string, number, string -> string

JEP: JEP-014

Examples:

# Zero-pad number
pad_left('5', `3`, '0') -> \"005\"
# Right-align text
pad_left('hi', `5`, ' ') -> \"   hi\"
# Already long enough
pad_left('hello', `3`, '0') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'pad_left(`"5"`, `3`, `"0"`)'

pad_right

Pad string on the right to reach target length

Signature: string, number, string -> string

JEP: JEP-014

Examples:

# Pad with zeros
pad_right('5', `3`, '0') -> \"500\"
# Left-align text
pad_right('hi', `5`, ' ') -> \"hi   \"
# Already long enough
pad_right('hello', `3`, '0') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'pad_right(`"5"`, `3`, `"0"`)'

redact

Redact regex pattern matches with replacement

Signature: string, string, string? -> string

Examples:

# Redact email
redact('email: test@example.com', '\\S+@\\S+', '[EMAIL]') -> \"email: [EMAIL]\"
# Redact phone
redact('call 555-1234', '\\d{3}-\\d{4}', '[PHONE]') -> \"call [PHONE]\"
# No matches
redact('no match', 'xyz', '[X]') -> \"no match\"

CLI Usage:

echo '{}' | jpx 'redact(`"email: test@example.com"`, `"\\S+@\\S+"`, `"[EMAIL]"`)'

repeat

Repeat a string n times

Signature: string, number -> string

Examples:

# Repeat 3 times
repeat('ab', `3`) -> \"ababab\"
# Create separator
repeat('-', `5`) -> \"-----\"
# Zero times
repeat('x', `0`) -> \"\"

CLI Usage:

echo '{}' | jpx 'repeat(`"ab"`, `3`)'

shouty_kebab_case

Convert to SHOUTY-KEBAB-CASE (also known as COBOL-CASE or SCREAMING-KEBAB-CASE)

Signature: string -> string

Examples:

# From camelCase
shouty_kebab_case('helloWorld') -> "HELLO-WORLD"
# From snake_case
shouty_kebab_case('hello_world') -> "HELLO-WORLD"
# From PascalCase
shouty_kebab_case('HelloWorld') -> "HELLO-WORLD"

CLI Usage:

echo '{}' | jpx 'shouty_kebab_case(`"helloWorld"`)'

shouty_snake_case

Convert to SHOUTY_SNAKE_CASE (also known as SCREAMING_SNAKE_CASE or CONSTANT_CASE)

Signature: string -> string

Examples:

# From camelCase
shouty_snake_case('helloWorld') -> "HELLO_WORLD"
# From kebab-case
shouty_snake_case('hello-world') -> "HELLO_WORLD"
# From PascalCase
shouty_snake_case('HelloWorld') -> "HELLO_WORLD"

CLI Usage:

echo '{}' | jpx 'shouty_snake_case(`"helloWorld"`)'

replace

Replace occurrences of a substring

Signature: string, string, string -> string

JEP: JEP-014

Examples:

# Replace all occurrences
replace('hello', 'l', 'L') -> \"heLLo\"
# No match
replace('hello', 'x', 'y') -> \"hello\"
# Replace all
replace('aaa', 'a', 'b') -> \"bbb\"

CLI Usage:

echo '{}' | jpx 'replace(`"hello"`, `"l"`, `"L"`)'

reverse_string

Reverse a string

Signature: string -> string

Examples:

# Reverse word
reverse_string('hello') -> \"olleh\"
# Two chars
reverse_string('ab') -> \"ba\"
# Empty string
reverse_string('') -> \"\"

CLI Usage:

echo '{}' | jpx 'reverse_string(`"hello"`)'

rtrimstr

Remove suffix from string if present

Signature: string, string -> string

Examples:

# Remove suffix
rtrimstr('foobar', 'bar') -> \"foo\"
# Remove file extension
rtrimstr('hello.txt', '.txt') -> \"hello\"
# Suffix not present
rtrimstr('hello', 'xyz') -> \"hello\"
# Only removes once
rtrimstr('barbar', 'bar') -> \"bar\"

CLI Usage:

echo '{}' | jpx 'rtrimstr(`"foobar"`, `"bar"`)'

shell_escape

Escape a string for safe use in shell commands (POSIX sh compatible, jq parity)

Signature: string -> string

Examples:

# Simple string unchanged
shell_escape('hello') -> \"hello\"
# Spaces get quoted
shell_escape('hello world') -> \"'hello world'\"
# Variables are escaped
shell_escape('$PATH') -> \"'$PATH'\"
# Single quotes escaped
shell_escape('it'\\''s') -> \"'it'\\\\''s'\"

CLI Usage:

echo '{}' | jpx 'shell_escape(`"hello"`)'

slice

Extract substring by start and end index

Signature: string, number, number -> string

Examples:

# Middle slice
slice('hello', `1`, `4`) -> \"ell\"
# From start
slice('hello', `0`, `2`) -> \"he\"
# To end
slice('hello', `3`, `5`) -> \"lo\"
# Two characters
slice('abcdef', `2`, `4`) -> \"cd\"

CLI Usage:

echo '{}' | jpx 'slice(`"hello"`, `1`, `4`)'

snake_case

Convert to snake_case

Signature: string -> string

Examples:

# From camelCase
snake_case('helloWorld') -> \"hello_world\"
# From PascalCase
snake_case('HelloWorld') -> \"hello_world\"
# From kebab-case
snake_case('hello-world') -> \"hello_world\"
# From UPPER_CASE
snake_case('HELLO_WORLD') -> \"hello_world\"

CLI Usage:

echo '{}' | jpx 'snake_case(`"helloWorld"`)'

split

Split string by delimiter

Signature: string, string -> array

JEP: JEP-014

Examples:

# Basic split
split('a,b,c', ',') -> [\"a\", \"b\", \"c\"]
# Split by space
split('hello world', ' ') -> [\"hello\", \"world\"]
# No delimiter found
split('no-delim', ',') -> [\"no-delim\"]
# Empty string
split('', ',') -> [\"\"]

CLI Usage:

echo '{}' | jpx 'split(`"a,b,c"`, `","`)'

sprintf

Printf-style string formatting

Signature: string, any... -> string

Examples:

# Float formatting
sprintf('Pi is %.2f', `3.14159`) -> \"Pi is 3.14\"
# String interpolation
sprintf('Hello %s', 'world') -> \"Hello world\"
# Integer formatting
sprintf('%d items', `42`) -> \"42 items\"
# Multiple args
sprintf('%s: %d', 'count', `5`) -> \"count: 5\"

CLI Usage:

echo '{}' | jpx 'sprintf(`"Pi is %.2f"`, `3.14159`)'

substr

Extract substring by start index and length

Signature: string, number, number -> string

Examples:

# From index 1, length 3
substr('hello', `1`, `3`) -> \"ell\"
# From start
substr('hello', `0`, `2`) -> \"he\"
# Middle portion
substr('abcdef', `2`, `2`) -> \"cd\"
# Single character
substr('hello', `4`, `1`) -> \"o\"

CLI Usage:

echo '{}' | jpx 'substr(`"hello"`, `1`, `3`)'

title

Convert to title case

Signature: string -> string

Examples:

# Basic title case
title('hello world') -> \"Hello World\"
# From uppercase
title('HELLO WORLD') -> \"Hello World\"
# Single word
title('hello') -> \"Hello\"
# Single letters
title('a b c') -> \"A B C\"

CLI Usage:

echo '{}' | jpx 'title(`"hello world"`)'

train_case

Convert to Train-Case (also known as HTTP-Header-Case)

Signature: string -> string

Examples:

# From camelCase
train_case('helloWorld') -> "Hello-World"
# From snake_case
train_case('hello_world') -> "Hello-World"
# From lowercase
train_case('content type') -> "Content-Type"

CLI Usage:

echo '{}' | jpx 'train_case(`"helloWorld"`)'

trim

Remove leading and trailing whitespace

Signature: string -> string

JEP: JEP-014

Examples:

# Remove both sides
trim('  hello  ') -> \"hello\"
# No whitespace
trim('hello') -> \"hello\"
# Only whitespace
trim('   ') -> \"\"
# Tabs and newlines
trim('\t\nhello\t\n') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'trim(`"  hello  "`)'

trim_left

Remove leading whitespace

Signature: string -> string

JEP: JEP-014

Examples:

# Remove leading spaces
trim_left('  hello') -> \"hello\"
# Trailing preserved
trim_left('hello  ') -> \"hello  \"
# Remove tabs
trim_left('\t\thello') -> \"hello\"
# No change needed
trim_left('hello') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'trim_left(`"  hello"`)'

trim_right

Remove trailing whitespace

Signature: string -> string

JEP: JEP-014

Examples:

# Remove trailing spaces
trim_right('hello  ') -> \"hello\"
# Leading preserved
trim_right('  hello') -> \"  hello\"
# Remove tabs
trim_right('hello\t\t') -> \"hello\"
# No change needed
trim_right('hello') -> \"hello\"

CLI Usage:

echo '{}' | jpx 'trim_right(`"hello  "`)'

upper

Convert string to uppercase

Signature: string -> string

JEP: JEP-014

Examples:

# Basic uppercase
upper('hello') -> \"HELLO\"
# Mixed case
upper('Hello World') -> \"HELLO WORLD\"
# Already uppercase
upper('HELLO') -> \"HELLO\"
# With numbers
upper('abc123') -> \"ABC123\"

CLI Usage:

echo '{}' | jpx 'upper(`"hello"`)'

wrap

Wrap text to specified width

Signature: string, number -> string

Examples:

# Wrap at word boundary
wrap('hello world', `5`) -> \"hello\\nworld\"
# Multiple wraps
wrap('a b c d e', `3`) -> \"a b\\nc d\\ne\"
# No wrap needed
wrap('short', `10`) -> \"short\"
# Longer text
wrap('one two three', `7`) -> \"one two\\nthree\"

CLI Usage:

echo '{}' | jpx 'wrap(`"hello world"`, `5`)'

Array Functions

Functions for working with arrays: chunking, filtering, transforming, and combining array data.

Summary

Functions

bsearch

Binary search in a sorted array, returns index or negative insertion point (jq parity)

Signature: array, any -> number

Examples:

# Found at index 2
bsearch([1, 3, 5, 7, 9], `5`) -> 2
# Not found, would insert at index 2
bsearch([1, 3, 5, 7, 9], `4`) -> -3
# Not found, would insert at index 0
bsearch([1, 3, 5, 7, 9], `0`) -> -1

CLI Usage:

echo '{}' | jpx 'bsearch([1, 3, 5, 7, 9], `5`)'

cartesian

Compute cartesian product of arrays (jq parity for N-way product)

Signature: array, array? -> array

Examples:

# Two-array product
cartesian([1, 2], [3, 4]) -> [[1, 3], [1, 4], [2, 3], [2, 4]]
# N-way product (jq style)
cartesian([[1, 2], [3, 4]]) -> [[1, 3], [1, 4], [2, 3], [2, 4]]
# Three-way product
cartesian([['a', 'b'], [1, 2], ['x', 'y']]) -> [['a', 1, 'x'], ['a', 1, 'y'], ...]
# Single array
cartesian([[1, 2]]) -> [[1], [2]]
# Empty array produces empty result
cartesian([[], [1, 2]]) -> []

CLI Usage:

echo '{}' | jpx 'cartesian([1, 2], [3, 4])'

chunk

Split array into chunks of size n

Signature: array, number -> array

Examples:

# Basic chunking
chunk([1, 2, 3, 4], `2`) -> [[1, 2], [3, 4]]
# Uneven chunks
chunk([1, 2, 3, 4, 5], `2`) -> [[1, 2], [3, 4], [5]]
# Empty array
chunk([], `2`) -> []

CLI Usage:

echo '{}' | jpx 'chunk([1, 2, 3, 4], `2`)'

compact

Remove null values from array

Signature: array -> array

Examples:

# Remove nulls
compact([1, null, 2, null]) -> [1, 2]
# All nulls
compact([null, null]) -> []
# No nulls
compact([1, 2, 3]) -> [1, 2, 3]

CLI Usage:

echo '{}' | jpx 'compact([1, null, 2, null])'

difference

Elements in first array not in second

Signature: array, array -> array

Examples:

# Remove matching elements
difference([1, 2, 3], [2]) -> [1, 3]
# No overlap
difference([1, 2, 3], [4, 5]) -> [1, 2, 3]
# All removed
difference([1, 2], [1, 2]) -> []

CLI Usage:

echo '{}' | jpx 'difference([1, 2, 3], [2])'

drop

Drop first n elements

Signature: array, number -> array

Examples:

# Drop first 2
drop([1, 2, 3, 4], `2`) -> [3, 4]
# Drop none
drop([1, 2, 3], `0`) -> [1, 2, 3]
# Drop more than length
drop([1, 2], `5`) -> []

CLI Usage:

echo '{}' | jpx 'drop([1, 2, 3, 4], `2`)'

find_index

Find index of value in array

Signature: array, any -> number | null

Examples:

# Find existing value
find_index([1, 2, 3], `2`) -> 1
# Find string
find_index(['a', 'b', 'c'], 'b') -> 1
# Value not found
find_index([1, 2, 3], `99`) -> null

CLI Usage:

echo '{}' | jpx 'find_index([1, 2, 3], `2`)'

first

Get first element of array

Signature: array -> any

Examples:

# Get first number
first([1, 2, 3]) -> 1
# Get first string
first(['a', 'b']) -> 'a'
# Empty array returns null
first([]) -> null

CLI Usage:

echo '{}' | jpx 'first([1, 2, 3])'

flatten

Flatten array one level deep

Signature: array -> array

Examples:

# Flatten nested arrays
flatten([[1, 2], [3]]) -> [1, 2, 3]
# Only one level deep
flatten([[1, [2]], [3]]) -> [1, [2], 3]
# Already flat
flatten([1, 2, 3]) -> [1, 2, 3]

CLI Usage:

echo '{}' | jpx 'flatten([[1, 2], [3]])'

flatten_deep

Recursively flatten nested arrays

Signature: array -> array

Examples:

# Deeply nested
flatten_deep([[1, [2]], [3]]) -> [1, 2, 3]
# Multiple levels
flatten_deep([[[1]], [[2]], [[3]]]) -> [1, 2, 3]
# Already flat
flatten_deep([1, 2, 3]) -> [1, 2, 3]

CLI Usage:

echo '{}' | jpx 'flatten_deep([[1, [2]], [3]])'

frequencies

Count occurrences of each value

Signature: array -> object

Examples:

# Count strings
frequencies(['a', 'b', 'a']) -> {a: 2, b: 1}
# Count numbers
frequencies([1, 2, 1, 1]) -> {1: 3, 2: 1}
# Empty array
frequencies([]) -> {}

CLI Usage:

echo '{}' | jpx 'frequencies(['a', `"b"`, 'a'])'

group_by

Group array elements by key

Signature: array, string -> object

Examples:

# Group by field
group_by([{t: 'a'}, {t: 'b'}, {t: 'a'}], 't') -> {a: [{t:'a'}, {t:'a'}], b: [{t:'b'}]}
# Group users by role
group_by(users, 'role') -> {admin: [...], user: [...]}
# Empty array returns empty object
group_by([], 'key') -> {}

CLI Usage:

echo '{}' | jpx 'group_by([{t: 'a'}, {t: 'b'}, {t: 'a'}], `"t"`)'

includes

Check if array contains value

Signature: array, any -> boolean

Examples:

# Value found
includes([1, 2, 3], `2`) -> true
# Value not found
includes([1, 2, 3], `99`) -> false
# String value
includes(['a', 'b'], 'a') -> true

CLI Usage:

echo '{}' | jpx 'includes([1, 2, 3], `2`)'

index_at

Get element at index (supports negative)

Signature: array, number -> any

Examples:

# First element
index_at([1, 2, 3], `0`) -> 1
# Last element (negative index)
index_at([1, 2, 3], `-1`) -> 3
# Out of bounds
index_at([1, 2, 3], `99`) -> null

CLI Usage:

echo '{}' | jpx 'index_at([1, 2, 3], `0`)'

index_by

Create lookup map from array using key field (last value wins for duplicates)

Signature: array, string -> object

Examples:

# Index by id field
index_by([{id: 1, name: "alice"}, {id: 2, name: "bob"}], "id") -> {"1": {id: 1, name: "alice"}, "2": {id: 2, name: "bob"}}
# Index by string key
index_by([{code: "US", name: "USA"}], "code") -> {"US": {code: "US", name: "USA"}}
# Last value wins for duplicates
index_by([{t: "a", v: 1}, {t: "a", v: 2}], "t") -> {"a": {t: "a", v: 2}}
# Empty array returns empty object
index_by([], "id") -> {}

CLI Usage:

echo '{}' | jpx 'index_by([{id: 1, name: "alice"}, {id: 2, name: "bob"}], "id")'

indices_array

Find all indices where a value appears in an array (jq parity)

Signature: array, any -> array

Examples:

# Find all occurrences
indices_array([1, 2, 3, 2, 4, 2], `2`) -> [1, 3, 5]
# String values
indices_array(['a', 'b', 'a', 'c'], `'a'`) -> [0, 2]
# Not found returns empty
indices_array([1, 2, 3], `5`) -> []

CLI Usage:

echo '{}' | jpx 'indices_array([1, 2, 3, 2, 4, 2], `2`)'

inside_array

Check if all elements of first array are contained in second array (inverse of contains, jq parity)

Signature: array, array -> boolean

Examples:

# Subset check
inside_array([1, 2], [1, 2, 3, 4]) -> true
# Not a subset
inside_array([1, 5], [1, 2, 3, 4]) -> false
# Empty is subset of any
inside_array([], [1, 2, 3]) -> true

CLI Usage:

echo '{}' | jpx 'inside_array([1, 2], [1, 2, 3, 4])'

intersection

Elements common to both arrays

Signature: array, array -> array

Examples:

# Common elements
intersection([1, 2], [2, 3]) -> [2]
# No overlap
intersection([1, 2], [3, 4]) -> []
# Identical arrays
intersection([1, 2, 3], [1, 2, 3]) -> [1, 2, 3]

CLI Usage:

echo '{}' | jpx 'intersection([1, 2], [2, 3])'

last

Get last element of array

Signature: array -> any

Examples:

# Get last number
last([1, 2, 3]) -> 3
# Get last string
last(['a', 'b']) -> 'b'
# Empty array returns null
last([]) -> null

CLI Usage:

echo '{}' | jpx 'last([1, 2, 3])'

pairwise

Return adjacent pairs from array

Signature: array -> array

Examples:

# Adjacent pairs
pairwise([1, 2, 3]) -> [[1, 2], [2, 3]]
# Single pair
pairwise([1, 2]) -> [[1, 2]]
# Too few elements
pairwise([1]) -> []

CLI Usage:

echo '{}' | jpx 'pairwise([1, 2, 3])'

range

Generate array of numbers

Signature: number, number -> array

Examples:

# Range 1 to 4
range(`1`, `5`) -> [1, 2, 3, 4]
# Range from zero
range(`0`, `3`) -> [0, 1, 2]
# Empty range
range(`5`, `5`) -> []

CLI Usage:

echo '{}' | jpx 'range(`1`, `5`)'

sliding_window

Create overlapping windows of size n (alias for window)

Signature: array, number -> array

Aliases: window

Examples:

# Size 2 windows
sliding_window([1, 2, 3, 4], `2`) -> [[1, 2], [2, 3], [3, 4]]
# Size 3 windows
sliding_window([1, 2, 3, 4], `3`) -> [[1, 2, 3], [2, 3, 4]]
# Window larger than array
sliding_window([1, 2], `3`) -> []

CLI Usage:

echo '{}' | jpx 'sliding_window([1, 2, 3, 4], `2`)'

take

Take first n elements

Signature: array, number -> array

Examples:

# Take first 2
take([1, 2, 3, 4], `2`) -> [1, 2]
# Take none
take([1, 2, 3], `0`) -> []
# Take more than length
take([1, 2], `5`) -> [1, 2]

CLI Usage:

echo '{}' | jpx 'take([1, 2, 3, 4], `2`)'

transpose

Transpose a 2D array (swap rows and columns)

Signature: array -> array

Examples:

# Swap rows/columns
transpose([[1, 2], [3, 4]]) -> [[1, 3], [2, 4]]
# 2x3 to 3x2
transpose([[1, 2, 3], [4, 5, 6]]) -> [[1, 4], [2, 5], [3, 6]]
# Empty array
transpose([]) -> []

CLI Usage:

echo '{}' | jpx 'transpose([[1, 2], [3, 4]])'

union

Unique elements from both arrays

Signature: array, array -> array

Examples:

# Combine with dedup
union([1, 2], [2, 3]) -> [1, 2, 3]
# No overlap
union([1, 2], [3, 4]) -> [1, 2, 3, 4]
# Empty first array
union([], [1, 2]) -> [1, 2]

CLI Usage:

echo '{}' | jpx 'union([1, 2], [2, 3])'

unique

Remove duplicate values

Signature: array -> array

Examples:

# Basic deduplication
unique([1, 2, 1, 3]) -> [1, 2, 3]
# String values
unique(['a', 'b', 'a']) -> ['a', 'b']
# Empty array
unique([]) -> []

CLI Usage:

echo '{}' | jpx 'unique([1, 2, 1, 3])'

zip

Zip two arrays together

Signature: array, array -> array

JEP: JEP-013

Examples:

# Basic zip
zip([1, 2], ['a', 'b']) -> [[1, 'a'], [2, 'b']]
# Unequal lengths (truncates)
zip([1, 2, 3], ['a', 'b']) -> [[1, 'a'], [2, 'b']]
# Empty arrays
zip([], []) -> []

CLI Usage:

echo '{}' | jpx 'zip([1, 2], ['a', 'b'])'

Object Functions

Functions for working with JSON objects: merging, filtering keys/values, and transformations.

Summary

Functions

camel_keys

Recursively convert all keys to camelCase

Signature: any -> any

Examples:

# Snake to camel
camel_keys({user_name: "alice"}) -> {userName: "alice"}
# Kebab to camel
camel_keys({"user-name": "bob"}) -> {userName: "bob"}
# Nested
camel_keys({user_info: {first_name: "x"}}) -> {userInfo: {firstName: "x"}}

CLI Usage:

echo '{}' | jpx 'camel_keys({user_name: "alice"})'

chunk_by_size

Split an array into chunks of approximately the specified byte size

Signature: array, number -> array

Examples:

# All fit in one chunk
chunk_by_size([{a:1}, {b:2}, {c:3}], `100`) -> [[{a:1}, {b:2}, {c:3}]]
# Split into chunks
chunk_by_size([{a:1}, {b:2}], `10`) -> [[{a:1}], [{b:2}]]

CLI Usage:

echo '{}' | jpx 'chunk_by_size([{a:1}, {b:2}, {c:3}], `100`)'

compact_deep

Recursively compact arrays, removing nulls at all levels

Signature: array -> array

Examples:

# Remove nulls from nested arrays
compact_deep([[1, null], [null, 2]]) -> [[1], [2]]
# Deep nesting
compact_deep([[1, null], [null, [2, null]]]) -> [[1], [[2]]]
# Simple array
compact_deep([1, null, 3]) -> [1, 3]

CLI Usage:

echo '{}' | jpx 'compact_deep([[1, null], [null, 2]])'

completeness

Calculate percentage of non-null fields (0-100)

Signature: object -> number

Examples:

# All fields filled
completeness({a: 1, b: 2, c: 3}) -> 100
# One of three filled
completeness({a: 1, b: null, c: null}) -> 33.33
# Nested null counted
completeness({a: 1, b: {c: null}}) -> 66.67
# Empty object is complete
completeness({}) -> 100

CLI Usage:

echo '{}' | jpx 'completeness({a: 1, b: 2, c: 3})'

data_quality_score

Analyze data quality and return score with detailed issues

Signature: any -> object

Examples:

# Perfect data
data_quality_score({a: 1, b: 'hello'}).score -> 100
# Issues detected
data_quality_score({a: null, b: ''}).issues -> [{path: 'a', issue: 'null'}, ...]
# Count null fields
data_quality_score(users).null_count -> 5
# Count type mismatches
data_quality_score(data).type_inconsistencies -> 2

CLI Usage:

echo '{}' | jpx 'data_quality_score({a: 1, b: 'hello'}).score'

deep_diff

Structural diff between two objects

Signature: object, object -> object

Examples:

# Changed value
deep_diff({a: 1}, {a: 2}) -> {added: {}, removed: {}, changed: {a: {from: 1, to: 2}}}
# Added and removed
deep_diff({a: 1}, {b: 2}) -> {added: {b: 2}, removed: {a: 1}, changed: {}}
# No differences
deep_diff({a: 1}, {a: 1}) -> {added: {}, removed: {}, changed: {}}
# New key added
deep_diff({}, {a: 1}) -> {added: {a: 1}, removed: {}, changed: {}}

CLI Usage:

echo '{}' | jpx 'deep_diff({a: 1}, {a: 2})'

deep_equals

Deep equality check for any two values

Signature: any, any -> boolean

Examples:

# Equal nested objects
deep_equals({a: {b: 1}}, {a: {b: 1}}) -> true
# Different values
deep_equals({a: 1}, {a: 2}) -> false
# Equal arrays
deep_equals([1, 2], [1, 2]) -> true
# Order matters
deep_equals([1, 2], [2, 1]) -> false

CLI Usage:

echo '{}' | jpx 'deep_equals({a: {b: 1}}, {a: {b: 1}})'

deep_merge

Recursively merge objects

Signature: object, object -> object

Examples:

# Merge nested objects
deep_merge({a: {b: 1}}, {a: {c: 2}}) -> {a: {b: 1, c: 2}}
# Merge flat objects
deep_merge({a: 1}, {b: 2}) -> {a: 1, b: 2}
# Later values override
deep_merge({a: 1}, {a: 2}) -> {a: 2}
# Merge with empty object
deep_merge({}, {a: 1}) -> {a: 1}

CLI Usage:

echo '{}' | jpx 'deep_merge({a: {b: 1}}, {a: {c: 2}})'

defaults

Assign default values for missing keys (shallow)

Signature: object, object -> object

Examples:

# Keep existing, add missing
defaults({a: 1}, {a: 2, b: 3}) -> {a: 1, b: 3}
# All defaults applied
defaults({}, {a: 1, b: 2}) -> {a: 1, b: 2}
# No defaults needed
defaults({a: 1, b: 2}, {}) -> {a: 1, b: 2}
# Different keys
defaults({x: 1}, {y: 2}) -> {x: 1, y: 2}

CLI Usage:

echo '{}' | jpx 'defaults({a: 1}, {a: 2, b: 3})'

defaults_deep

Recursively assign default values for missing keys

Signature: object, object -> object

Examples:

# Merge nested defaults
defaults_deep({a: {b: 1}}, {a: {c: 2}}) -> {a: {b: 1, c: 2}}
# Keep existing nested
defaults_deep({a: {b: 1}}, {a: {b: 2}}) -> {a: {b: 1}}
# Apply all nested defaults
defaults_deep({}, {a: {b: 1}}) -> {a: {b: 1}}
# Different structure
defaults_deep({x: 1}, {y: {z: 2}}) -> {x: 1, y: {z: 2}}

CLI Usage:

echo '{}' | jpx 'defaults_deep({a: {b: 1}}, {a: {c: 2}})'

delete_path

Delete value at JSON pointer path (immutable)

Signature: any, string -> any

Examples:

# Delete top-level key
delete_path({a: 1, b: 2}, '/b') -> {a: 1}
# Delete nested key
delete_path({a: {b: 1, c: 2}}, '/a/b') -> {a: {c: 2}}
# Delete array element
delete_path([1, 2, 3], '/1') -> [1, 3]
# Path not found
delete_path({a: 1}, '/x') -> {a: 1}

CLI Usage:

echo '{}' | jpx 'delete_path({a: 1, b: 2}, `"/b"`)'

estimate_size

Estimate the JSON serialization size in bytes

Signature: any -> number

Examples:

# String with quotes
estimate_size(`"hello"`) -> 7
# Simple object
estimate_size({a: 1}) -> 7
# Simple array
estimate_size([1, 2, 3]) -> 7

CLI Usage:

echo '{}' | jpx 'estimate_size(`"hello"`)'

flatten

Alias for flatten_keys - flatten nested object with dot notation keys

Signature: object -> object

Examples:

# Simple nested
flatten({a: {b: 1}}) -> {\"a.b\": 1}
# Deep nested
flatten({a: {b: {c: 1}}}) -> {\"a.b.c\": 1}
# Flat object
flatten({a: 1, b: 2}) -> {\"a\": 1, \"b\": 2}

CLI Usage:

echo '{}' | jpx 'flatten({a: {b: 1}})'

flatten_array

Flatten nested objects and arrays with dot notation keys (arrays use numeric indices)

Signature: any, string? -> object

Examples:

# Array with indices
flatten_array({a: [1, 2]}) -> {\"a.0\": 1, \"a.1\": 2}
# Nested object with array
flatten_array({a: {b: [1, 2]}}) -> {\"a.b.0\": 1, \"a.b.1\": 2}
# Array of objects
flatten_array([{a: 1}, {b: 2}]) -> {\"0.a\": 1, \"1.b\": 2}
# Custom separator
flatten_array({a: {b: 1}}, '/') -> {\"a/b\": 1}

CLI Usage:

echo '{}' | jpx 'flatten_array({a: [1, 2]})'

flatten_keys

Flatten nested object with dot notation keys

Signature: object -> object

Examples:

# Simple nested
flatten_keys({a: {b: 1}}) -> {\"a.b\": 1}
# Deep nested
flatten_keys({a: {b: {c: 1}}}) -> {\"a.b.c\": 1}
# Flat object
flatten_keys({a: 1, b: 2}) -> {\"a\": 1, \"b\": 2}
# Mixed nesting
flatten_keys({x: {y: 1}, z: 2}) -> {\"x.y\": 1, \"z\": 2}

CLI Usage:

echo '{}' | jpx 'flatten_keys({a: {b: 1}})'

from_items

Convert array of [key, value] pairs to object

Signature: array -> object

JEP: JEP-013

Examples:

# Single pair
from_items([['a', 1]]) -> {a: 1}
# Multiple pairs
from_items([['a', 1], ['b', 2]]) -> {a: 1, b: 2}
# Empty array
from_items([]) -> {}
# String value
from_items([['x', 'hello']]) -> {x: 'hello'}

CLI Usage:

echo '{}' | jpx 'from_items([['a', 1]])'

get

Get value at dot-separated path with optional default

Signature: any, string, any? -> any

Examples:

# Nested path
get({a: {b: 1}}, 'a.b') -> 1
# Top-level key
get({a: 1}, 'a') -> 1
# Missing with default
get({a: 1}, 'x', 'default') -> 'default'
# Deep path
get({a: {b: {c: 3}}}, 'a.b.c') -> 3

CLI Usage:

echo '{}' | jpx 'get({a: {b: 1}}, `"a.b"`)'

has

Check if dot-separated path exists

Signature: any, string -> boolean

Examples:

# Nested path exists
has({a: {b: 1}}, 'a.b') -> true
# Top-level exists
has({a: 1}, 'a') -> true
# Key missing
has({a: 1}, 'b') -> false
# Nested missing
has({a: {b: 1}}, 'a.c') -> false

CLI Usage:

echo '{}' | jpx 'has({a: {b: 1}}, `"a.b"`)'

has_same_shape

Check if two values have the same structure (ignoring actual values)

Signature: any, any -> boolean

Examples:

# Same keys, different values
has_same_shape({a: 1, b: 2}, {a: 99, b: 100}) -> true
# Different keys
has_same_shape({a: 1}, {a: 1, b: 2}) -> false
# Same length arrays
has_same_shape([1, 2], [3, 4]) -> true

CLI Usage:

echo '{}' | jpx 'has_same_shape({a: 1, b: 2}, {a: 99, b: 100})'

infer_schema

Infer a JSON Schema-like type description from a value

Signature: any -> object

Examples:

# Number type
infer_schema(`42`) -> {type: "number"}
# Object schema
infer_schema({name: "alice", age: 30}) -> {type: "object", properties: {name: {type: "string"}, age: {type: "number"}}}
# Array schema
infer_schema([1, 2, 3]) -> {type: "array", items: {type: "number"}}

CLI Usage:

echo '{}' | jpx 'infer_schema(`42`)'

invert

Swap keys and values

Signature: object -> object

Examples:

# Swap key and value
invert({a: 'x'}) -> {x: 'a'}
# Multiple pairs
invert({a: 'b', c: 'd'}) -> {b: 'a', d: 'c'}
# Empty object
invert({}) -> {}
# Real-world example
invert({name: 'id', value: 'data'}) -> {id: 'name', data: 'value'}

CLI Usage:

echo '{}' | jpx 'invert({a: 'x'})'

items

Convert object to array of [key, value] pairs

Signature: object -> array

JEP: JEP-013

Examples:

# Single key
items({a: 1}) -> [[\"a\", 1]]
# Multiple keys
items({a: 1, b: 2}) -> [[\"a\", 1], [\"b\", 2]]
# Empty object
items({}) -> []
# String value
items({x: 'hello'}) -> [[\"x\", \"hello\"]]

CLI Usage:

echo '{}' | jpx 'items({a: 1})'

kebab_keys

Recursively convert all keys to kebab-case

Signature: any -> any

Examples:

# Camel to kebab
kebab_keys({userName: "alice"}) -> {"user-name": "alice"}
# Snake to kebab
kebab_keys({user_name: "bob"}) -> {"user-name": "bob"}
# Nested
kebab_keys({userInfo: {firstName: "x"}}) -> {"user-info": {"first-name": "x"}}

CLI Usage:

echo '{}' | jpx 'kebab_keys({userName: "alice"})'

leaves

Get all leaf values (non-object, non-array)

Signature: any -> array

Examples:

# Mixed structure
leaves({a: 1, b: [2, 3]}) -> [1, 2, 3]
# Nested object
leaves({a: {b: 1}}) -> [1]
# Flat array
leaves([1, 2, 3]) -> [1, 2, 3]
# Flat object
leaves({a: 1, b: 2}) -> [1, 2]

CLI Usage:

echo '{}' | jpx 'leaves({a: 1, b: [2, 3]})'

pascal_keys

Recursively convert all keys to PascalCase

Signature: any -> any

Examples:

# Camel to pascal
pascal_keys({userName: "alice"}) -> {UserName: "alice"}
# Snake to pascal
pascal_keys({user_name: "bob"}) -> {UserName: "bob"}
# Nested
pascal_keys({userInfo: {firstName: "x"}}) -> {UserInfo: {FirstName: "x"}}

CLI Usage:

echo '{}' | jpx 'pascal_keys({user_name: "alice"})'

leaves_with_paths

Get all leaf values with their JSON pointer paths

Signature: any -> array

Examples:

# Single leaf
leaves_with_paths({a: 1}) -> [{path: \"/a\", value: 1}]
# Nested path
leaves_with_paths({a: {b: 1}}) -> [{path: \"/a/b\", value: 1}]
# Array indices
leaves_with_paths([1, 2]) -> [{path: \"/0\", value: 1}, {path: \"/1\", value: 2}]
# Empty object
leaves_with_paths({}) -> []

CLI Usage:

echo '{}' | jpx 'leaves_with_paths({a: 1})'

mask

Mask a string, showing only the last N characters

Signature: string, number? -> string

Examples:

# Credit card default
mask("4111111111111111") -> "************1111"
# Phone with 3 visible
mask("555-123-4567", `3`) -> "*********567"
# Short string masked
mask("abc") -> "***"

CLI Usage:

echo '{}' | jpx 'mask("4111111111111111")'

omit

Remove specific keys from object

Signature: object, array -> object

Examples:

# Remove one key
omit({a: 1, b: 2}, ['a']) -> {b: 2}
# Remove multiple keys
omit({a: 1, b: 2, c: 3}, ['a', 'c']) -> {b: 2}
# Key not present
omit({a: 1}, ['x']) -> {a: 1}
# Empty removal list
omit({a: 1, b: 2}, []) -> {a: 1, b: 2}

CLI Usage:

echo '{}' | jpx 'omit({a: 1, b: 2}, ['a'])'

paginate

Get a page of items from an array with metadata

Signature: array, number, number -> object

Examples:

# First page
paginate([1,2,3,4,5], `2`, `1`) -> {items: [1,2], page: 1, page_size: 2, total_items: 5, total_pages: 3, has_next: true, has_prev: false}
# Last page
paginate([1,2,3,4,5], `2`, `3`) -> {items: [5], page: 3, page_size: 2, total_items: 5, total_pages: 3, has_next: false, has_prev: true}

CLI Usage:

echo '{}' | jpx 'paginate([1,2,3,4,5], `2`, `1`)'

paths

List all JSON pointer paths in value

Signature: any -> array

Examples:

# Nested object
paths({a: {b: 1}}) -> [\"/a\", \"/a/b\"]
# Flat object
paths({a: 1, b: 2}) -> [\"/a\", \"/b\"]
# Array paths
paths([1, 2]) -> [\"/0\", \"/1\"]
# Empty object
paths({}) -> []

CLI Usage:

echo '{}' | jpx 'paths({a: {b: 1}})'

paths_to

Find all dot-notation paths to a key anywhere in structure

Signature: any, string -> array

Examples:

# Find paths to id
paths_to({a: {id: 1}, b: {id: 2}}, "id") -> ["a.id", "b.id"]
# Array paths
paths_to({users: [{id: 1}]}, "id") -> ["users.0.id"]
# Key not found
paths_to({a: 1}, "x") -> []

CLI Usage:

echo '{}' | jpx 'paths_to({a: {id: 1}, b: {id: 2}}, "id")'

pick

Select specific keys from object

Signature: object, array -> object

Examples:

# Pick one key
pick({a: 1, b: 2}, ['a']) -> {a: 1}
# Pick multiple keys
pick({a: 1, b: 2, c: 3}, ['a', 'c']) -> {a: 1, c: 3}
# Key not present
pick({a: 1}, ['x']) -> {}
# Empty pick list
pick({a: 1, b: 2}, []) -> {}

CLI Usage:

echo '{}' | jpx 'pick({a: 1, b: 2}, ['a'])'

pluck_deep

Find all values for a key anywhere in nested structure

Signature: any, string -> array

Examples:

# Find all ids
pluck_deep({users: [{id: 1}, {id: 2}], meta: {id: 99}}, "id") -> [1, 2, 99]
# Nested values
pluck_deep({a: {b: {c: 1}}, d: {c: 2}}, "c") -> [1, 2]
# Key not found
pluck_deep({a: 1}, "x") -> []

CLI Usage:

echo '{}' | jpx 'pluck_deep({users: [{id: 1}, {id: 2}], meta: {id: 99}}, "id")'

redact

Recursively replace values at specified keys with [REDACTED]

Signature: any, array -> any

Examples:

# Redact password
redact({name: "alice", password: "secret"}, ["password"]) -> {name: "alice", password: "[REDACTED]"}
# Nested redact
redact({user: {name: "bob", ssn: "123"}}, ["ssn"]) -> {user: {name: "bob", ssn: "[REDACTED]"}}
# Array of objects
redact([{token: "abc"}], ["token"]) -> [{token: "[REDACTED]"}]

CLI Usage:

echo '{}' | jpx 'redact({name: "alice", password: "secret"}, ["password"])'

redact_keys

Recursively redact keys matching a regex pattern

Signature: any, string -> any

Examples:

# Multiple patterns
redact_keys({password: "x", api_key: "y"}, "password|api_key") -> {password: "[REDACTED]", api_key: "[REDACTED]"}
# Wildcard pattern
redact_keys({secret_key: "a", secret_token: "b"}, "secret.*") -> {secret_key: "[REDACTED]", secret_token: "[REDACTED]"}

CLI Usage:

echo '{}' | jpx 'redact_keys({password: "x", api_key: "y"}, "password|api_key")'

remove_empty

Recursively remove nulls, empty strings, empty arrays, and empty objects

Signature: any -> any

Examples:

# Remove all empty values
remove_empty({a: \"\", b: [], c: {}, d: null, e: \"hello\"}) -> {e: \"hello\"}
# Nested cleanup
remove_empty({a: {b: \"\", c: 1}}) -> {a: {c: 1}}
# Array cleanup
remove_empty([\"\", \"hello\", [], null]) -> [\"hello\"]

CLI Usage:

echo '{}' | jpx 'remove_empty({a: \"\", b: [], c: {}, d: null, e: \"hello\"})'

remove_empty_strings

Recursively remove empty string values

Signature: any -> any

Examples:

# Remove empty strings
remove_empty_strings({name: \"alice\", bio: \"\"}) -> {name: \"alice\"}
# From arrays
remove_empty_strings([\"hello\", \"\", \"world\"]) -> [\"hello\", \"world\"]
# Nested
remove_empty_strings({a: {b: \"\", c: \"x\"}}) -> {a: {c: \"x\"}}

CLI Usage:

echo '{}' | jpx 'remove_empty_strings({name: \"alice\", bio: \"\"})'

remove_nulls

Recursively remove null values

Signature: any -> any

Examples:

# Remove nulls from object
remove_nulls({a: 1, b: null, c: 2}) -> {a: 1, c: 2}
# Nested nulls
remove_nulls({a: {b: null, c: 1}}) -> {a: {c: 1}}
# Remove from array
remove_nulls([1, null, 2]) -> [1, 2]

CLI Usage:

echo '{}' | jpx 'remove_nulls({a: 1, b: null, c: 2})'

rename_keys

Rename object keys

Signature: object, object -> object

Examples:

# Rename one key
rename_keys({a: 1}, {a: 'b'}) -> {b: 1}
# Rename multiple
rename_keys({a: 1, b: 2}, {a: 'x', b: 'y'}) -> {x: 1, y: 2}
# No matching key
rename_keys({a: 1}, {x: 'y'}) -> {a: 1}
# Real-world rename
rename_keys({old: 'value'}, {old: 'new'}) -> {new: 'value'}

CLI Usage:

echo '{}' | jpx 'rename_keys({a: 1}, {a: 'b'})'

set_path

Set value at JSON pointer path (immutable)

Signature: any, string, any -> any

Examples:

# Add new key
set_path({a: 1}, '/b', `2`) -> {a: 1, b: 2}
# Update existing
set_path({a: 1}, '/a', `2`) -> {a: 2}
# Set nested path
set_path({a: {}}, '/a/b', `1`) -> {a: {b: 1}}
# Update array element
set_path([1, 2], '/1', `5`) -> [1, 5]

CLI Usage:

echo '{}' | jpx 'set_path({a: 1}, `"/b"`, `2`)'

shouty_kebab_keys

Recursively convert all keys to SHOUTY-KEBAB-CASE

Signature: any -> any

Examples:

# Camel to shouty kebab
shouty_kebab_keys({userName: "alice"}) -> {"USER-NAME": "alice"}
# Snake to shouty kebab
shouty_kebab_keys({user_name: "bob"}) -> {"USER-NAME": "bob"}
# Nested
shouty_kebab_keys({userInfo: {firstName: "x"}}) -> {"USER-INFO": {"FIRST-NAME": "x"}}

CLI Usage:

echo '{}' | jpx 'shouty_kebab_keys({user_name: "alice"})'

shouty_snake_keys

Recursively convert all keys to SHOUTY_SNAKE_CASE

Signature: any -> any

Examples:

# Camel to shouty snake
shouty_snake_keys({userName: "alice"}) -> {USER_NAME: "alice"}
# Kebab to shouty snake
shouty_snake_keys({"user-name": "bob"}) -> {USER_NAME: "bob"}
# Nested
shouty_snake_keys({userInfo: {firstName: "x"}}) -> {USER_INFO: {FIRST_NAME: "x"}}

CLI Usage:

echo '{}' | jpx 'shouty_snake_keys({user_name: "alice"})'

snake_keys

Recursively convert all keys to snake_case

Signature: any -> any

Examples:

# Camel to snake
snake_keys({userName: "alice"}) -> {user_name: "alice"}
# Kebab to snake
snake_keys({"user-name": "bob"}) -> {user_name: "bob"}
# Nested
snake_keys({userInfo: {firstName: "x"}}) -> {user_info: {first_name: "x"}}

CLI Usage:

echo '{}' | jpx 'snake_keys({userName: "alice"})'

train_keys

Recursively convert all keys to Train-Case

Signature: any -> any

Examples:

# Camel to train
train_keys({userName: "alice"}) -> {"User-Name": "alice"}
# Snake to train
train_keys({user_name: "bob"}) -> {"User-Name": "bob"}
# Nested
train_keys({userInfo: {firstName: "x"}}) -> {"User-Info": {"First-Name": "x"}}

CLI Usage:

echo '{}' | jpx 'train_keys({user_name: "alice"})'

structural_diff

Compare two values and return their structural differences

Signature: any, any -> object

Examples:

# Changed value
structural_diff({a: 1}, {a: 2}) -> {changed: [{path: "a", from: 1, to: 2}], added: [], removed: []}
# Added key
structural_diff({a: 1}, {a: 1, b: 2}) -> {changed: [], added: [{path: "b", value: 2}], removed: []}
# Removed key
structural_diff({a: 1, b: 2}, {a: 1}) -> {changed: [], added: [], removed: [{path: "b", value: 2}]}

CLI Usage:

echo '{}' | jpx 'structural_diff({a: 1}, {a: 2})'

template

Expand a template string with values from an object using {{key}} syntax

Signature: object, string -> string

Examples:

# Simple substitution
template({name: "Alice"}, `"Hello, {{name}}!"`) -> "Hello, Alice!"
# Nested access
template({user: {name: "Bob"}}, `"Hi {{user.name}}"`) -> "Hi Bob"
# Default value
template({}, `"Hello {{name|World}}"`) -> "Hello World"

CLI Usage:

echo '{}' | jpx 'template({name: "Alice"}, `"Hello, {{name}}!"`)'

template_strict

Expand a template string, returning null if any variable is missing

Signature: object, string -> string | null

Examples:

# All vars present
template_strict({name: "Alice"}, `"Hello, {{name}}!"`) -> "Hello, Alice!"
# Missing variable
template_strict({}, `"Hello, {{name}}!"`) -> null

CLI Usage:

echo '{}' | jpx 'template_strict({name: "Alice"}, `"Hello, {{name}}!"`)'

truncate_to_size

Truncate an array to fit within approximately the specified byte size

Signature: array, number -> array

Examples:

# All fit
truncate_to_size([{a:1}, {b:2}, {c:3}], `100`) -> [{a:1}, {b:2}, {c:3}]
# Truncated
truncate_to_size([{a:1}, {b:2}, {c:3}], `15`) -> [{a:1}, {b:2}]

CLI Usage:

echo '{}' | jpx 'truncate_to_size([{a:1}, {b:2}, {c:3}], `100`)'

type_consistency

Check if array elements have consistent types

Signature: array -> object

Examples:

# Consistent numbers
type_consistency([1, 2, 3]).consistent -> true
# Mixed types
type_consistency([1, 'two', 3]).consistent -> false
# Object field mismatch
type_consistency([{a: 1}, {a: 'x'}]).inconsistencies -> [{field: 'a', ...}]
# Empty array is consistent
type_consistency([]).consistent -> true

CLI Usage:

echo '{}' | jpx 'type_consistency([1, 2, 3]).consistent'

unflatten

Alias for unflatten_keys - restore nested object from dot notation keys

Signature: object -> object

Examples:

# Simple nested
unflatten({\"a.b\": 1}) -> {a: {b: 1}}
# Deep nested
unflatten({\"a.b.c\": 1}) -> {a: {b: {c: 1}}}
# Flat keys
unflatten({\"a\": 1, \"b\": 2}) -> {a: 1, b: 2}

CLI Usage:

echo '{}' | jpx 'unflatten({\"a.b\": 1})'

unflatten_keys

Restore nested object from dot notation keys

Signature: object -> object

Examples:

# Simple nested
unflatten_keys({\"a.b\": 1}) -> {a: {b: 1}}
# Deep nested
unflatten_keys({\"a.b.c\": 1}) -> {a: {b: {c: 1}}}
# Flat keys
unflatten_keys({\"a\": 1, \"b\": 2}) -> {a: 1, b: 2}
# Mixed nesting
unflatten_keys({\"x.y\": 1, \"z\": 2}) -> {x: {y: 1}, z: 2}

CLI Usage:

echo '{}' | jpx 'unflatten_keys({\"a.b\": 1})'

with_entries

Transform object entries using an expression (jq parity)

Signature: object, string -> object

Examples:

# Transform keys and values
with_entries({a: 1, b: 2}, '[upper(@[0]), multiply(@[1], `2`)]') -> {A: 2, B: 4}
# Transform values only
with_entries({a: 1, b: 2}, '[@[0], add(@[1], `10`)]') -> {a: 11, b: 12}
# Filter entries
with_entries({a: 1, b: 2, c: 3}, 'if(@[1] > `1`, @, `null`)') -> {b: 2, c: 3}

CLI Usage:

echo '{}' | jpx 'with_entries({a: 1, b: 2}, `"[upper(@[0]), multiply(@[1], `2`)]"`)'

Math Functions

Mathematical and statistical functions: arithmetic, rounding, statistics, and number formatting.

Summary

Functions

abs_fn

Absolute value

Signature: number -> number

Examples:

# Negative to positive
abs_fn(`-5`) -> 5
# Already positive
abs_fn(`5`) -> 5
# Zero stays zero
abs_fn(`0`) -> 0
# Negative float
abs_fn(`-3.14`) -> 3.14

CLI Usage:

echo '{}' | jpx 'abs_fn(`-5`)'

add

Add two numbers

Signature: number, number -> number

Examples:

# Add integers
add(`2`, `3`) -> 5
# Add floats
add(`1.5`, `2.5`) -> 4.0
# With negative
add(`-5`, `3`) -> -2
# Add zero
add(`0`, `10`) -> 10

CLI Usage:

echo '{}' | jpx 'add(`2`, `3`)'

ceil_fn

Round up to nearest integer

Signature: number -> number

Examples:

# Round up fraction
ceil_fn(`3.2`) -> 4
# Round up high fraction
ceil_fn(`3.9`) -> 4
# Already integer
ceil_fn(`3.0`) -> 3
# Negative rounds toward zero
ceil_fn(`-3.2`) -> -3

CLI Usage:

echo '{}' | jpx 'ceil_fn(`3.2`)'

clamp

Clamp value to range

Signature: number, number, number -> number

Examples:

# Above max
clamp(`15`, `0`, `10`) -> 10
# Below min
clamp(`-5`, `0`, `10`) -> 0
# Within range
clamp(`5`, `0`, `10`) -> 5
# Custom range
clamp(`100`, `50`, `75`) -> 75

CLI Usage:

echo '{}' | jpx 'clamp(`15`, `0`, `10`)'

cos

Cosine function

Signature: number -> number

Examples:

# Cos of 0
cos(`0`) -> 1
# Cos of pi
cos(`3.14159`) -> -1
# Cos of pi/2
cos(`1.5708`) -> ~0
# Cos of 2*pi
cos(`6.28318`) -> 1

CLI Usage:

echo '{}' | jpx 'cos(`0`)'

covariance

Covariance between two arrays

Signature: array, array -> number

Examples:

# Perfect positive
covariance([1, 2, 3], [1, 2, 3]) -> 0.666...
# Perfect negative
covariance([1, 2, 3], [3, 2, 1]) -> -0.666...
# No correlation
covariance([1, 2, 3], [1, 1, 1]) -> 0
# From arrays
covariance(x_values, y_values) -> number

CLI Usage:

echo '{}' | jpx 'covariance([1, 2, 3], [1, 2, 3])'

cumulative_sum

Calculate running cumulative sum of a numeric array

Signature: array -> array

Examples:

# Running total
cumulative_sum([1, 2, 3, 4]) -> [1, 3, 6, 10]
# With negatives
cumulative_sum([10, -5, 3]) -> [10, 5, 8]
# Single element
cumulative_sum([100]) -> [100]

CLI Usage:

echo '{}' | jpx 'cumulative_sum([1, 2, 3, 4])'

divide

Divide first number by second

Signature: number, number -> number

Examples:

# Integer division
divide(`10`, `2`) -> 5
# Fractional result
divide(`7`, `2`) -> 3.5
# Repeating decimal
divide(`1`, `3`) -> 0.333...
# Negative dividend
divide(`-10`, `2`) -> -5

CLI Usage:

echo '{}' | jpx 'divide(`10`, `2`)'

ewma

Exponential weighted moving average

Signature: array, number -> array

Examples:

# Alpha 0.5
ewma([1, 2, 3, 4, 5], `0.5`) -> [1, 1.5, 2.25, ...]
# Smooth stock prices
ewma(prices, `0.3`) -> smoothed prices
# High alpha
ewma([10, 20, 30], `0.9`) -> fast response
# Low alpha
ewma([10, 20, 30], `0.1`) -> slow response

CLI Usage:

echo '{}' | jpx 'ewma([1, 2, 3, 4, 5], `0.5`)'

floor_fn

Round down to nearest integer

Signature: number -> number

Examples:

# Round down high fraction
floor_fn(`3.7`) -> 3
# Round down low fraction
floor_fn(`3.2`) -> 3
# Already integer
floor_fn(`3.0`) -> 3
# Negative rounds away from zero
floor_fn(`-3.2`) -> -4

CLI Usage:

echo '{}' | jpx 'floor_fn(`3.7`)'

format_number

Format number with separators and optional suffix

Signature: number, number?, string? -> string

Examples:

# With commas
format_number(`1234567`, `0`) -> \"1,234,567\"
# With decimals
format_number(`1234.56`, `2`) -> \"1,234.56\"
# Million
format_number(`1000000`, `0`) -> \"1,000,000\"
# Small number
format_number(`99.9`, `1`) -> \"99.9\"

CLI Usage:

echo '{}' | jpx 'format_number(`1234567`, `0`)'

log

Natural logarithm

Signature: number -> number

Examples:

# Log of e
log(`2.718`) -> ~1
# Log of 1
log(`1`) -> 0
# Log of 10
log(`10`) -> 2.302...
# Log of 100
log(`100`) -> 4.605...

CLI Usage:

echo '{}' | jpx 'log(`2.718`)'

median

Calculate median of array

Signature: array -> number

Examples:

# Odd count
median([1, 2, 3, 4, 5]) -> 3
# Even count
median([1, 2, 3, 4]) -> 2.5
# Middle value
median([10, 20, 30]) -> 20
# Single element
median([5]) -> 5

CLI Usage:

echo '{}' | jpx 'median([1, 2, 3, 4, 5])'

mod_fn

Modulo operation

Signature: number, number -> number

Examples:

# Remainder of 10/3
mod_fn(`10`, `3`) -> 1
# Evenly divisible
mod_fn(`15`, `5`) -> 0
# Odd check
mod_fn(`7`, `2`) -> 1
# Larger numbers
mod_fn(`100`, `7`) -> 2

CLI Usage:

echo '{}' | jpx 'mod_fn(`10`, `3`)'

mode

Find the most common value in an array

Signature: array -> any

Examples:

# Most frequent
mode([1, 2, 2, 3]) -> 2
# String mode
mode(['a', 'b', 'a', 'a']) -> 'a'
# Tie returns first
mode([1, 1, 2, 2, 3]) -> 1 or 2
# Single element
mode([5]) -> 5

CLI Usage:

echo '{}' | jpx 'mode([1, 2, 2, 3])'

moving_avg

Simple moving average with window size

Signature: array, number -> array

Examples:

# Window of 3
moving_avg([1, 2, 3, 4, 5], `3`) -> [null, null, 2, 3, 4]
# Window of 2
moving_avg([10, 20, 30, 40], `2`) -> [null, 15, 25, 35]
# 7-day moving avg
moving_avg(prices, `7`) -> weekly average
# Window of 1
moving_avg([1, 2, 3], `1`) -> [1, 2, 3]

CLI Usage:

echo '{}' | jpx 'moving_avg([1, 2, 3, 4, 5], `3`)'

multiply

Multiply two numbers

Signature: number, number -> number

Examples:

# Basic multiplication
multiply(`4`, `3`) -> 12
# With decimals
multiply(`2.5`, `4`) -> 10
# With negative
multiply(`-3`, `4`) -> -12
# Multiply by zero
multiply(`0`, `100`) -> 0

CLI Usage:

echo '{}' | jpx 'multiply(`4`, `3`)'

outliers_iqr

Find outliers using IQR method (values outside Q1-1.5IQR to Q3+1.5IQR)

Signature: array, number? -> array

Examples:

# Detect outlier
outliers_iqr([1, 2, 3, 4, 100]) -> [100]
# No outliers
outliers_iqr([1, 2, 3, 4, 5]) -> []
# Custom multiplier
outliers_iqr(values, `3.0`) -> extreme outliers only
# Find anomalies
outliers_iqr(measurements) -> anomalies

CLI Usage:

echo '{}' | jpx 'outliers_iqr([1, 2, 3, 4, 100])'

outliers_zscore

Find outliers using z-score method (values with |z-score| > threshold)

Signature: array, number? -> array

Examples:

# Detect outlier
outliers_zscore([1, 2, 3, 4, 100]) -> [100]
# No outliers
outliers_zscore([1, 2, 3, 4, 5]) -> []
# Custom threshold
outliers_zscore(values, `3.0`) -> extreme outliers only
# Lower threshold
outliers_zscore(measurements, `1.5`) -> more sensitive detection

CLI Usage:

echo '{}' | jpx 'outliers_zscore([1, 2, 3, 4, 100])'

percentile

Calculate percentile of array

Signature: array, number -> number

Examples:

# 50th percentile (median)
percentile([1, 2, 3, 4, 5], `50`) -> 3
# 25th percentile
percentile([1, 2, 3, 4, 5], `25`) -> 2
# 75th percentile
percentile([1, 2, 3, 4, 5], `75`) -> 4
# 90th percentile
percentile(scores, `90`) -> top 10% threshold

CLI Usage:

echo '{}' | jpx 'percentile([1, 2, 3, 4, 5], `50`)'

pow

Raise to power

Signature: number, number -> number

Examples:

# 2 cubed
pow(`2`, `3`) -> 8
# 10 squared
pow(`10`, `2`) -> 100
# 2^10
pow(`2`, `10`) -> 1024
# Square root via power
pow(`4`, `0.5`) -> 2

CLI Usage:

echo '{}' | jpx 'pow(`2`, `3`)'

quantile

Nth quantile (generalized percentile, q in [0,1])

Signature: array, number -> number

Examples:

# Median (0.5)
quantile([1, 2, 3, 4, 5], `0.5`) -> 3
# First quartile
quantile([1, 2, 3, 4, 5], `0.25`) -> 2
# Third quartile
quantile([1, 2, 3, 4, 5], `0.75`) -> 4
# 90th quantile
quantile(values, `0.9`) -> 90th quantile

CLI Usage:

echo '{}' | jpx 'quantile([1, 2, 3, 4, 5], `0.5`)'

quartiles

Calculate quartiles (Q1, Q2, Q3) and IQR of array

Signature: array -> object

Examples:

# Basic quartiles
quartiles([1, 2, 3, 4, 5]) -> {min: 1, q1: 2, q2: 3, q3: 4, max: 5, iqr: 2}
# Get IQR
quartiles([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).iqr -> 4.5
# Q2 equals median
quartiles(values).q2 == median(values) -> true
# Distribution analysis
quartiles(scores) -> full distribution stats

CLI Usage:

echo '{}' | jpx 'quartiles([1, 2, 3, 4, 5])'

rate_of_change

Calculate percentage change between consecutive values

Signature: array -> array

Examples:

# 10% growth
rate_of_change([100, 110, 121]) -> [10.0, 10.0]
# 50% decline
rate_of_change([100, 50, 25]) -> [-50.0, -50.0]
# Varying rate
rate_of_change([1, 2, 3]) -> [100.0, 50.0]

CLI Usage:

echo '{}' | jpx 'rate_of_change([100, 110, 121])'

round

Round to specified decimal places

Signature: number, number -> number

Examples:

# Two decimals
round(`3.14159`, `2`) -> 3.14
# Round to integer
round(`3.5`, `0`) -> 4
# Round up
round(`2.555`, `2`) -> 2.56
# One decimal
round(`123.456`, `1`) -> 123.5

CLI Usage:

echo '{}' | jpx 'round(`3.14159`, `2`)'

sin

Sine function

Signature: number -> number

Examples:

# Sin of 0
sin(`0`) -> 0
# Sin of pi/2
sin(`1.5708`) -> 1
# Sin of pi
sin(`3.14159`) -> ~0
# Sin of 2*pi
sin(`6.28318`) -> ~0

CLI Usage:

echo '{}' | jpx 'sin(`0`)'

sqrt

Square root

Signature: number -> number

Examples:

# Perfect square
sqrt(`16`) -> 4
# Irrational result
sqrt(`2`) -> 1.414...
# Larger number
sqrt(`100`) -> 10
# Zero
sqrt(`0`) -> 0

CLI Usage:

echo '{}' | jpx 'sqrt(`16`)'

standardize

Standardize array to mean=0, std=1 (z-score normalization)

Signature: array -> array

Examples:

# Basic z-scores
standardize([10, 20, 30]) -> [-1.22, 0, 1.22]
# Normalize values
standardize([1, 2, 3, 4, 5]) -> normalized
# Standardize scores
standardize(scores) -> z-scores
# Identical values
standardize([5, 5, 5]) -> [0, 0, 0]

CLI Usage:

echo '{}' | jpx 'standardize([10, 20, 30])'

stddev

Calculate standard deviation of array

Signature: array -> number

Examples:

# Basic stddev
stddev([1, 2, 3, 4, 5]) -> 1.414...
# No variation
stddev([10, 10, 10]) -> 0
# High variation
stddev([1, 100]) -> ~49.5
# Measure spread
stddev(values) -> spread measure

CLI Usage:

echo '{}' | jpx 'stddev([1, 2, 3, 4, 5])'

subtract

Subtract second number from first

Signature: number, number -> number

Examples:

# Basic subtraction
subtract(`5`, `3`) -> 2
# Negative result
subtract(`10`, `15`) -> -5
# With decimals
subtract(`3.5`, `1.5`) -> 2
# From zero
subtract(`0`, `5`) -> -5

CLI Usage:

echo '{}' | jpx 'subtract(`5`, `3`)'

tan

Tangent function

Signature: number -> number

Examples:

# Tan of 0
tan(`0`) -> 0
# Tan of pi/4
tan(`0.7854`) -> ~1
# Tan of pi
tan(`3.14159`) -> ~0
# Calculate tangent
tan(angle) -> ratio

CLI Usage:

echo '{}' | jpx 'tan(`0`)'

to_fixed

Format number with exact decimal places

Signature: number, number -> string

Examples:

# Two decimals
to_fixed(`3.14159`, `2`) -> \"3.14\"
# Pad with zeros
to_fixed(`5`, `2`) -> \"5.00\"
# Round to integer
to_fixed(`99.9`, `0`) -> \"100\"
# Extra precision
to_fixed(`1.5`, `3`) -> \"1.500\"

CLI Usage:

echo '{}' | jpx 'to_fixed(`3.14159`, `2`)'

trend

Detect trend direction in a numeric array (increasing, decreasing, or stable)

Signature: array -> string

Examples:

# Upward trend
trend([1, 2, 3, 4, 5]) -> "increasing"
# Downward trend
trend([5, 4, 3, 2, 1]) -> "decreasing"
# No change
trend([3, 3, 3, 3]) -> "stable"

CLI Usage:

echo '{}' | jpx 'trend([1, 2, 3, 4, 5])'

trend_slope

Calculate the linear regression slope of a numeric array

Signature: array -> number

Examples:

# Perfect linear increase
trend_slope([1, 2, 3, 4, 5]) -> 1.0
# Perfect linear decrease
trend_slope([5, 4, 3, 2, 1]) -> -1.0
# Noisy upward
trend_slope([1, 3, 2, 4]) -> ~0.7

CLI Usage:

echo '{}' | jpx 'trend_slope([1, 2, 3, 4, 5])'

variance

Calculate variance of array

Signature: array -> number

Examples:

# Basic variance
variance([1, 2, 3, 4, 5]) -> 2
# No variation
variance([10, 10, 10]) -> 0
# High variation
variance([1, 100]) -> 2450.25
# Squared spread
variance(values) -> spread^2

CLI Usage:

echo '{}' | jpx 'variance([1, 2, 3, 4, 5])'

Date/Time Functions

Functions for working with dates and times: parsing, formatting, arithmetic, and timezone handling.

Summary

Functions

business_days_between

Count business days (weekdays) between two timestamps

Signature: number, number -> number

Examples:

# Count weekdays
business_days_between(`1704067200`, `1705276800`) -> 10
# Between two timestamps
business_days_between(start_ts, end_ts) -> count
# One week = 5 days
business_days_between(`0`, `604800`) -> 5
# Same day
business_days_between(`0`, `0`) -> 0

CLI Usage:

echo '{}' | jpx 'business_days_between(`1704067200`, `1705276800`)'

date_add

Add time to timestamp

Signature: number, number, string -> number

Examples:

# Add 1 day
date_add(`0`, `1`, 'days') -> 86400
# Add 2 hours
date_add(`0`, `2`, 'hours') -> 7200
# Add 1 week
date_add(timestamp, `7`, 'days') -> next week
# Add 30 minutes
date_add(`0`, `30`, 'minutes') -> 1800

CLI Usage:

echo '{}' | jpx 'date_add(`0`, `1`, `"days"`)'

date_diff

Difference between timestamps

Signature: number, number, string -> number

Examples:

# Diff in days
date_diff(`86400`, `0`, 'days') -> 1
# Diff in hours
date_diff(`7200`, `0`, 'hours') -> 2
# Diff in minutes
date_diff(end_ts, start_ts, 'minutes') -> minutes
# Diff in weeks
date_diff(`604800`, `0`, 'weeks') -> 1

CLI Usage:

echo '{}' | jpx 'date_diff(`86400`, `0`, `"days"`)'

duration_since

Get detailed duration object from timestamp to now

Signature: number|string -> object

Examples:

# From timestamp
duration_since(`1702396800`) -> {days: 1, hours: 0, ...}
# From date string
duration_since('2023-01-01') -> {days: N, ...}
# Time since creation
duration_since(created_at) -> elapsed time
# One hour ago
duration_since(now() - 3600) -> {hours: 1, ...}

CLI Usage:

echo '{}' | jpx 'duration_since(`1702396800`)'

end_of_day

Get ISO 8601 string for end of day (23:59:59)

Signature: number|string -> string

Examples:

# From ISO string
end_of_day('2023-12-13T15:30:00Z') -> \"2023-12-13T23:59:59Z\"
# From timestamp
end_of_day(`1702483200`) -> end of that day
# From date only
end_of_day('2024-01-01') -> last second of day
# End of today
end_of_day(now()) -> today end

CLI Usage:

echo '{}' | jpx 'end_of_day(`"2023-12-13T15:30:00Z"`)'

epoch_ms

Current Unix timestamp in milliseconds (alias for now_ms)

Signature: -> number

Examples:

# Current time in ms
epoch_ms() -> 1702483200000
# Convert to seconds
epoch_ms() / `1000` -> seconds
# Calculate duration
epoch_ms() - start_ms -> elapsed

CLI Usage:

echo '{}' | jpx 'epoch_ms()'

format_date

Format timestamp to string

Signature: number, string -> string

Examples:

# ISO date format
format_date(`1705276800`, '%Y-%m-%d') -> \"2024-01-15\"
# Long date format
format_date(ts, '%B %d, %Y') -> \"January 15, 2024\"
# Time only
format_date(ts, '%H:%M:%S') -> \"10:30:00\"
# Full ISO 8601
format_date(ts, '%Y-%m-%dT%H:%M:%SZ') -> ISO string

CLI Usage:

echo '{}' | jpx 'format_date(`1705276800`, `"%Y-%m-%d"`)'

from_epoch

Convert Unix timestamp (seconds) to ISO 8601 string

Signature: number -> string

Examples:

# Convert seconds
from_epoch(`1702483200`) -> \"2023-12-13T16:00:00Z\"
# Unix epoch
from_epoch(`0`) -> \"1970-01-01T00:00:00Z\"
# Convert field
from_epoch(created_at) -> ISO string
# Current time
from_epoch(now()) -> current ISO

CLI Usage:

echo '{}' | jpx 'from_epoch(`1702483200`)'

from_epoch_ms

Convert Unix timestamp (milliseconds) to ISO 8601 string

Signature: number -> string

Examples:

# From milliseconds
from_epoch_ms(`1702483200000`) -> \"2023-12-13T16:00:00Z\"
# Unix epoch
from_epoch_ms(`0`) -> \"1970-01-01T00:00:00Z\"
# JS timestamp
from_epoch_ms(js_timestamp) -> ISO
# Current time
from_epoch_ms(epoch_ms()) -> current

CLI Usage:

echo '{}' | jpx 'from_epoch_ms(`1702483200000`)'

is_after

Check if first date is after second date (accepts timestamps or date strings)

Signature: number|string, number|string -> boolean

Examples:

# String comparison
is_after('2024-07-15', '2024-01-01') -> true
# Timestamp comparison
is_after(`1705276800`, `1704067200`) -> true
# Field comparison
is_after(end_date, start_date) -> true/false
# Same date
is_after('2024-01-01', '2024-01-01') -> false

CLI Usage:

echo '{}' | jpx 'is_after(`"2024-07-15"`, `"2024-01-01"`)'

is_before

Check if first date is before second date (accepts timestamps or date strings)

Signature: number|string, number|string -> boolean

Examples:

# String comparison
is_before('2024-01-01', '2024-07-15') -> true
# Timestamp comparison
is_before(`1704067200`, `1705276800`) -> true
# Field comparison
is_before(start_date, end_date) -> true/false
# Same date
is_before('2024-01-01', '2024-01-01') -> false

CLI Usage:

echo '{}' | jpx 'is_before(`"2024-01-01"`, `"2024-07-15"`)'

is_between

Check if date is between start and end (inclusive, accepts timestamps or date strings)

Signature: number|string, number|string, number|string -> boolean

Examples:

# Within range
is_between('2024-06-15', '2024-01-01', '2024-12-31') -> true
# Before range
is_between('2023-06-15', '2024-01-01', '2024-12-31') -> false
# Check event date
is_between(event_date, start, end) -> true/false
# Inclusive start
is_between('2024-01-01', '2024-01-01', '2024-12-31') -> true

CLI Usage:

echo '{}' | jpx 'is_between(`"2024-06-15"`, `"2024-01-01"`, `"2024-12-31"`)'

is_same_day

Check if two timestamps/dates are on the same day

Signature: number|string, number|string -> boolean

Examples:

# Same day, different time
is_same_day('2023-12-13T10:00:00Z', '2023-12-13T23:00:00Z') -> true
# Different days
is_same_day('2023-12-13', '2023-12-14') -> false
# Compare fields
is_same_day(created_at, updated_at) -> true/false
# Today check
is_same_day(now(), event_time) -> true/false

CLI Usage:

echo '{}' | jpx 'is_same_day(`"2023-12-13T10:00:00Z"`, `"2023-12-13T23:00:00Z"`)'

is_weekday

Check if timestamp falls on weekday (Monday-Friday)

Signature: number -> boolean

Examples:

# Monday is weekday
is_weekday(`1705276800`) -> true
# Check current day
is_weekday(now()) -> true/false
# Check event day
is_weekday(event_timestamp) -> true/false
# Saturday is not weekday
is_weekday(`1705104000`) -> false

CLI Usage:

echo '{}' | jpx 'is_weekday(`1705276800`)'

is_weekend

Check if timestamp falls on weekend (Saturday or Sunday)

Signature: number -> boolean

Examples:

# Saturday is weekend
is_weekend(`1705104000`) -> true
# Check current day
is_weekend(now()) -> true/false
# Monday is not weekend
is_weekend(`1705276800`) -> false
# Check event day
is_weekend(event_timestamp) -> true/false

CLI Usage:

echo '{}' | jpx 'is_weekend(`1705104000`)'

parse_date

Parse date string to timestamp

Signature: string, string? -> number

Examples:

# ISO date format
parse_date('2024-01-15', '%Y-%m-%d') -> 1705276800
# US date format
parse_date('01/15/2024', '%m/%d/%Y') -> timestamp
# Named month
parse_date('15-Jan-2024', '%d-%b-%Y') -> timestamp
# With time
parse_date('2024-01-15T10:30:00', '%Y-%m-%dT%H:%M:%S') -> timestamp

CLI Usage:

echo '{}' | jpx 'parse_date(`"2024-01-15"`, `"%Y-%m-%d"`)'

quarter

Get quarter of year (1-4) from timestamp

Signature: number -> number

Examples:

# April is Q2
quarter(`1713139200`) -> 2
# January is Q1
quarter(`1704067200`) -> 1
# July is Q3
quarter(`1719792000`) -> 3
# November is Q4
quarter(`1730419200`) -> 4

CLI Usage:

echo '{}' | jpx 'quarter(`1713139200`)'

relative_time

Human-readable relative time from timestamp

Signature: number -> string

Examples:

# One hour ago
relative_time(now() - 3600) -> \"1 hour ago\"
# One minute ago
relative_time(now() - 60) -> \"1 minute ago\"
# One day ago
relative_time(now() - 86400) -> \"1 day ago\"
# From field
relative_time(created_at) -> human readable

CLI Usage:

echo '{}' | jpx 'relative_time(now() - 3600)'

start_of_day

Get ISO 8601 string for start of day (00:00:00)

Signature: number|string -> string

Examples:

# From ISO string
start_of_day('2023-12-13T15:30:00Z') -> \"2023-12-13T00:00:00Z\"
# From timestamp
start_of_day(`1702483200`) -> start of that day
# Today start
start_of_day(now()) -> today midnight
# From date only
start_of_day('2024-01-15') -> midnight

CLI Usage:

echo '{}' | jpx 'start_of_day(`"2023-12-13T15:30:00Z"`)'

start_of_month

Get ISO 8601 string for start of month

Signature: number|string -> string

Examples:

# From ISO string
start_of_month('2023-12-13T15:30:00Z') -> \"2023-12-01T00:00:00Z\"
# Current month start
start_of_month(now()) -> first of month
# From timestamp
start_of_month(`1702483200`) -> month start
# March start
start_of_month('2024-03-15') -> \"2024-03-01T00:00:00Z\"

CLI Usage:

echo '{}' | jpx 'start_of_month(`"2023-12-13T15:30:00Z"`)'

start_of_week

Get ISO 8601 string for start of week (Monday 00:00:00)

Signature: number|string -> string

Examples:

# Wednesday to Monday
start_of_week('2023-12-13T15:30:00Z') -> \"2023-12-11T00:00:00Z\"
# Current week start
start_of_week(now()) -> this Monday
# From timestamp
start_of_week(`1702483200`) -> week start
# Monday stays Monday
start_of_week('2024-01-15') -> \"2024-01-15T00:00:00Z\"

CLI Usage:

echo '{}' | jpx 'start_of_week(`"2023-12-13T15:30:00Z"`)'

start_of_year

Get ISO 8601 string for start of year

Signature: number|string -> string

Examples:

# From ISO string
start_of_year('2023-12-13T15:30:00Z') -> \"2023-01-01T00:00:00Z\"
# Current year start
start_of_year(now()) -> Jan 1st
# From timestamp
start_of_year(`1702483200`) -> year start
# Mid-year to Jan 1
start_of_year('2024-06-15') -> \"2024-01-01T00:00:00Z\"

CLI Usage:

echo '{}' | jpx 'start_of_year(`"2023-12-13T15:30:00Z"`)'

time_ago

Human-readable time since date (accepts timestamps or date strings)

Signature: number|string -> string

Examples:

# From date string
time_ago('2020-01-01') -> \"4 years ago\"
# One hour ago
time_ago(now() - 3600) -> \"1 hour ago\"
# From field
time_ago(created_at) -> human readable
# Months ago
time_ago('2023-12-01') -> \"X months ago\"

CLI Usage:

echo '{}' | jpx 'time_ago(`"2020-01-01"`)'

timezone_convert

Convert timestamp between timezones (IANA timezone names)

Signature: string, string, string -> string

Examples:

# NY to London
timezone_convert('2024-01-15T10:00:00', 'America/New_York', 'Europe/London') -> \"2024-01-15T15:00:00\"
# UTC to Pacific
timezone_convert(time, 'UTC', 'America/Los_Angeles') -> PST time
# Tokyo to UTC
timezone_convert(time, 'Asia/Tokyo', 'UTC') -> UTC time
# Paris to Chicago
timezone_convert(time, 'Europe/Paris', 'America/Chicago') -> CST time

CLI Usage:

echo '{}' | jpx 'timezone_convert(`"2024-01-15T10:00:00"`, `"America/New_York"`, `"Europe/London"`)'

to_epoch

Convert date string or timestamp to Unix timestamp (seconds)

Signature: number|string -> number

Examples:

# From ISO string
to_epoch('2023-12-13T16:00:00Z') -> 1702483200
# From date only
to_epoch('2024-01-01') -> timestamp
# Convert field
to_epoch(date_field) -> seconds
# Unix epoch
to_epoch('1970-01-01T00:00:00Z') -> 0

CLI Usage:

echo '{}' | jpx 'to_epoch(`"2023-12-13T16:00:00Z"`)'

to_epoch_ms

Convert date string or timestamp to Unix timestamp (milliseconds)

Signature: number|string -> number

Examples:

# From ISO string
to_epoch_ms('2023-12-13T16:00:00Z') -> 1702483200000
# From date only
to_epoch_ms('2024-01-01') -> timestamp_ms
# Convert field
to_epoch_ms(date_field) -> milliseconds
# Unix epoch
to_epoch_ms('1970-01-01T00:00:00Z') -> 0

CLI Usage:

echo '{}' | jpx 'to_epoch_ms(`"2023-12-13T16:00:00Z"`)'

Duration Functions

Functions for working with time durations.

Summary

Functions

duration_hours

Convert seconds to hours

Signature: number -> number

Examples:

# 2 hours
duration_hours(`7200`) -> 2
# 1 hour
duration_hours(`3600`) -> 1
# 1.5 hours
duration_hours(`5400`) -> 1.5

CLI Usage:

echo '{}' | jpx 'duration_hours(`7200`)'

duration_minutes

Convert seconds to minutes

Signature: number -> number

Examples:

# 2 minutes
duration_minutes(`120`) -> 2
# 1 minute
duration_minutes(`60`) -> 1
# 1.5 minutes
duration_minutes(`90`) -> 1.5

CLI Usage:

echo '{}' | jpx 'duration_minutes(`120`)'

duration_seconds

Get seconds component

Signature: number -> number

Examples:

# 65 seconds mod 60
duration_seconds(`65`) -> 5
# Exact minutes
duration_seconds(`120`) -> 0
# 1 hour 1 min 1 sec
duration_seconds(`3661`) -> 1

CLI Usage:

echo '{}' | jpx 'duration_seconds(`65`)'

format_duration

Format seconds as duration string

Signature: number -> string

Examples:

# 1.5 hours
format_duration(`5400`) -> \"1h30m\"
# 1 hour 1 min 1 sec
format_duration(`3661`) -> \"1h1m1s\"
# 1 minute
format_duration(`60`) -> \"1m\"

CLI Usage:

echo '{}' | jpx 'format_duration(`5400`)'

parse_duration

Parse duration string to seconds

Signature: string -> number

Examples:

# 1.5 hours
parse_duration('1h30m') -> 5400
# 2 hours
parse_duration('2h') -> 7200
# 30 seconds
parse_duration('30s') -> 30

CLI Usage:

echo '{}' | jpx 'parse_duration(`"1h30m"`)'

Hash Functions

Cryptographic hash functions: MD5, SHA family, and other hash algorithms.

Summary

Functions

crc32

Calculate CRC32 checksum

Signature: string -> number

Examples:

# Simple string
crc32('hello') -> 907060870
# Empty string
crc32('') -> 0
# Data with space
crc32('test data') -> 2706273274

CLI Usage:

echo '{}' | jpx 'crc32(`"hello"`)'

hmac_md5

Calculate HMAC-MD5 signature

Signature: string, string -> string

Examples:

# With secret key
hmac_md5('hello', 'secret') -> \"e17e4e4a205c55782dce5b6ff41e6e19\"
# Different message
hmac_md5('message', 'key') -> \"a24c903c3a7e7b741ea77bd467b98bca\"

CLI Usage:

echo '{}' | jpx 'hmac_md5(`"hello"`, `"secret"`)'

hmac_sha1

Calculate HMAC-SHA1 signature

Signature: string, string -> string

Examples:

# With secret key
hmac_sha1('hello', 'secret') -> \"5112055c36b16a6693045d75a054332e4555b52f\"
# Different data
hmac_sha1('data', 'key') -> \"104152c5bfdca07bc633eebd46199f0255c9f49d\"

CLI Usage:

echo '{}' | jpx 'hmac_sha1(`"hello"`, `"secret"`)'

hmac_sha256

Calculate HMAC-SHA256 signature

Signature: string, string -> string

Examples:

# With secret key
hmac_sha256('hello', 'secret') -> \"88aab3ede8d3adf94d26ab90d3bafd4a2083070c3bcce9c014ee04a443847c0b\"
# Different data
hmac_sha256('data', 'key') -> \"5031fe3d989c6d1537a013fa6e739da23463fdaec3b70137d828e36ace221bd0\"

CLI Usage:

echo '{}' | jpx 'hmac_sha256(`"hello"`, `"secret"`)'