High-performance JSON Pointer implementation
npm install json-type-cliJSON Type CLI is a powerful Node.js package for building command-line interface (CLI) utilities that implement the JSON Rx RPC protocol. It uses JSON as the primary data format and provides request/response communication pattern where each CLI interaction is a request that produces a response.
This package enables you to build type-safe CLI tools where:
- Each CLI command is a method with typed input/output schemas
- Input data forms the request payload (following JSON Rx RPC)
- Output data is the response payload
- Multiple input sources can be composed together
- Multiple output formats are supported (JSON, CBOR, MessagePack, etc.)
The library implements the JSON Rx RPC protocol, where each CLI interaction follows the request/response pattern. You define methods with typed schemas using the JSON Type system, and the CLI handles parsing, validation, method calling, and response formatting automatically.
``bash`
npm install json-type-cli
`typescript
import { createCli } from 'json-type-cli';
import { ObjectValue } from '@jsonjoy.com/json-type/lib/value/ObjectValue';
// Create a router with your methods
const router = ObjectValue.create()
.prop('greet',
t.Function(
t.Object(t.prop('name', t.str)), // Request schema
t.Object(t.prop('message', t.str)) // Response schema
).options({
title: 'Greet a person',
description: 'Returns a greeting message for the given name'
}),
async ({ name }) => ({
message: Hello, ${name}!
})
);
// Create and run CLI
const cli = createCli({
router,
version: 'v1.0.0',
cmd: 'my-cli'
});
cli.run();
`
Save this as my-cli.js and run:
`bash
node my-cli.js greet '{"name": "World"}'Output: {"message": "Hello, World!"}
node my-cli.js greet --str/name=Alice
JSON Rx RPC Protocol Implementation
This CLI tool implements the JSON Rx RPC protocol with the following characteristics:
$3
- Each CLI command is a method call in JSON Rx RPC terms
- The method name is the first positional argument:
- Request data is composed from multiple sources (see Input Sources)
- Response data is returned to STDOUT in the specified format$3
1. Request Composition: CLI parses arguments and builds request payload
2. Method Invocation: Calls the specified method with the request data
3. Response Generation: Method returns response payload
4. Response Encoding: Encodes response in the specified format (JSON, CBOR, etc.)This follows the JSON Rx RPC Request Complete message pattern where the client (CLI) sends a complete request and receives a complete response.
Building CLI Tools
$3
Methods are defined using the JSON Type system and added to a router:
typescript
import { createCli } from 'json-type-cli';
import { ObjectValue } from '@jsonjoy.com/json-type/lib/value/ObjectValue';const router = ObjectValue.create();
const { t } = router;
// Simple echo method
router.prop('echo',
t.Function(t.any, t.any).options({
title: 'Echo input',
description: 'Returns the input unchanged'
}),
async (input) => input
);
// Math operations
router.prop('math.add',
t.Function(
t.Object(
t.prop('a', t.num),
t.prop('b', t.num)
),
t.Object(t.prop('result', t.num))
).options({
title: 'Add two numbers',
description: 'Adds two numbers and returns the result'
}),
async ({ a, b }) => ({ result: a + b })
);
// File processing
router.prop('file.process',
t.Function(
t.Object(
t.prop('filename', t.str),
t.propOpt('encoding', t.str)
),
t.Object(
t.prop('size', t.num),
t.prop('content', t.str)
)
).options({
title: 'Process a file',
description: 'Reads and processes a file'
}),
async ({ filename, encoding = 'utf8' }) => {
const fs = require('fs');
const content = fs.readFileSync(filename, encoding);
return {
size: content.length,
content: content
};
}
);
`$3
For larger applications, organize routes into modules:
typescript
// routes/user.ts
export const defineUserRoutes = >(r: ObjectValue) => {
return r.extend((t, r) => [
r('user.create',
t.Function(
t.Object(
t.prop('name', t.str),
t.prop('email', t.str)
),
t.Object(
t.prop('id', t.str),
t.prop('name', t.str),
t.prop('email', t.str)
)
).options({
title: 'Create a user',
description: 'Creates a new user account'
}),
async ({ name, email }) => ({
id: generateId(),
name,
email
})
), r('user.get',
t.Function(
t.Object(t.prop('id', t.str)),
t.Object(
t.prop('id', t.str),
t.prop('name', t.str),
t.prop('email', t.str)
)
).options({
title: 'Get user by ID',
description: 'Retrieves user information by ID'
}),
async ({ id }) => getUserById(id)
)
]);
};
// main.ts
import { defineUserRoutes } from './routes/user';
const router = defineUserRoutes(ObjectValue.create());
const cli = createCli({ router });
`Input Sources (Request Composition)
The CLI composes request data from three sources in this priority order:
$3
Provide JSON directly as the second argument:
bash
my-cli greet '{"name": "Alice", "age": 30}'
my-cli math.add '{"a": 5, "b": 3}'
`$3
Pipe JSON data to the CLI:
bash
echo '{"name": "Bob"}' | my-cli greet
cat user.json | my-cli user.create
curl -s api.example.com/data.json | my-cli process.data
`$3
Use typed parameters to build the request object:
bash
String values
my-cli greet --str/name=Alice --str/title="Ms."Numeric values
my-cli math.add --num/a=10 --num/b=20Boolean values
my-cli user.update --bool/active=true --bool/verified=falseJSON values
my-cli config.set --json/settings='{"theme": "dark", "lang": "en"}'Nested paths using JSON Pointer (requires parent structure to exist)
my-cli user.update '{"profile": {}}' --str/profile/name="Alice" --num/profile/age=25To create nested structures, provide the base structure first
my-cli config.set '{"database": {}}' --str/database/host=localhost --num/database/port=5432
`$3
All sources can be combined. Command line options override STDIN data, which overrides the JSON parameter:
bash
echo '{"name": "Default", "age": 0}' | my-cli greet --str/name=Alice --num/age=30
Result: {"name": "Alice", "age": 30}
`Output Formats (Response Encoding)
$3
The CLI supports multiple output formats through codecs:
| Codec | Description | Use Case |
|-------|-------------|----------|
|
| Standard JSON (default) | Human-readable, web APIs |
| json2 | Pretty JSON (2 spaces) | Development, debugging |
| json4 | Pretty JSON (4 spaces) | Documentation, config files |
| cbor | CBOR binary format | Compact binary, IoT |
| msgpack | MessagePack binary | High performance, caching |
| ubjson | Universal Binary JSON | Cross-platform binary |
| text | Formatted text output | Human-readable reports |
| tree | Tree visualization | Debugging, data exploration |
| raw | Raw data output | Binary data, strings |$3
`bash
Default JSON output
my-cli user.get '{"id": "123"}'Pretty-printed JSON
my-cli user.get '{"id": "123"}' --format=json4Binary formats
my-cli data.export --format=cbor > data.cbor
my-cli data.export --format=msgpack > data.msgpackText visualization
my-cli config.get --format=tree
my-cli config.get --format=textDifferent input/output formats
cat data.cbor | my-cli process.data --format=cbor:json
echo '{"test": 123}' | my-cli echo --format=json:tree
`$3
Use the
or --out parameter to extract specific parts of the response:`bash
Extract specific field
my-cli user.get '{"id": "123"}' --out=/user/nameExtract nested data
my-cli api.fetch '{"url": "example.com"}' --out=/response/data/itemsCombine with format conversion
my-cli data.complex --out=/results/summary --format=json:text
`Command Line Parameters
All parameter paths use JSON Pointer syntax as defined in RFC 6901. JSON Pointers provide a standardized way to reference specific values within JSON documents using slash-separated paths.
When a path doesn't exist in the target object, the CLI automatically creates the necessary nested structure. For example,
will create the object {"database": {"host": "localhost"}} even if neither database nor host existed previously.$3
#### String Values (
--str or --s)
`bash
my-cli greet --str/name=Alice
my-cli config.set --s/database/host=localhost --s/database/name=mydb
`#### Numeric Values (
or --n)
`bash
my-cli math.add --num/a=10 --num/b=20
my-cli server.start --n/port=3000 --n/workers=4
`#### Boolean Values (
or --b)
`bash
my-cli user.update --bool/active=true
my-cli feature.toggle --b/enabled=false
`#### JSON Values (
or --j)
`bash
my-cli config.merge --json/settings='{"theme": "dark"}'
my-cli api.call --j/payload='[1,2,3]'
`#### Undefined Values (
)
`bash
my-cli optional.field --und/optionalParam
`$3
Read values from files with optional format and path extraction:
bash
Read JSON file
my-cli process.data --file/input=data.jsonRead with specific codec
my-cli import.data --f/data=data.cbor:cborExtract path from file
my-cli user.create --f/profile=user.json:json:/personalInfoChain: file -> codec -> path
my-cli complex.import --f/config=settings.msgpack:msgpack:/database/credentials
`$3
Execute commands and use their output as values:
bash
Use command output as string
my-cli log.write --cmd/message='(echo "Current time: $(date)"):text'Use command output as JSON
my-cli api.send --c/data='(curl -s api.example.com/data):json'Extract path from command output
my-cli process.status --c/info='(ps aux | grep node):json:/0/pid'
`$3
Control input and output encoding:
bash
Single format (for both input and output)
my-cli echo --format=cborSeparate input and output formats
my-cli convert --format=cbor:json
my-cli transform --fmt=json:tree
`$3
Explicitly control STDIN data mapping:
bash
Use all STDIN data
echo '{"name": "Alice"}' | my-cli greet --stdinMap STDIN to specific path
echo '{"users": [...]}' | my-cli process.users --in/data=/usersMap with path extraction
echo '{"response": {"users": [...]}}' | my-cli save.users --in/users=/response/users
`$3
Extract specific parts of the response:
bash
Extract single field
my-cli user.get '{"id": "123"}' --out=/nameExtract nested object
my-cli api.fetch --out=/response/dataUse with format conversion
my-cli complex.data --out=/results --format=json:tree
`$3
#### Help (
or --h)
`bash
my-cli --help # General help
my-cli method.name --help # Method-specific help
`#### Version (
or --v)
`bash
my-cli --version
`#### Execution Plan (
)
`bash
my-cli complex.operation --plan # Show what would be executed
`Advanced Features
$3
Get information about available methods and their schemas:
bash
List all methods
my-cli .typeGet method schema
my-cli .type --out=/methodName
my-cli .type --out=/user.create/req --format=tree
my-cli .type --out=/user.create/res --format=json4
`$3
The CLI supports binary data through various codecs:
bash
Process binary data
cat image.jpg | my-cli image.process --format=raw:jsonConvert between binary formats
cat data.cbor | my-cli convert --format=cbor:msgpack > data.msgpackEncode JSON as binary
my-cli data.export '{"large": "dataset"}' --format=json:cbor > export.cbor
`$3
Errors follow JSON Rx RPC error format and are sent to STDERR:
bash
my-cli invalid.method 2>errors.log
my-cli user.get '{"invalid": "data"}' 2>validation-errors.json
`Error objects include:
-
: Human-readable error description
- code: Stable error code for programmatic handling
- errno: Numeric error code
- errorId: Unique error identifier for logging
- meta: Additional error metadata (stack traces, etc.)$3
For high-performance scenarios:
`bash
Use binary formats for large data
my-cli large.dataset --format=msgpackUse raw format for simple string/binary output
my-cli get.file.content --format=rawStream processing with STDIN/STDOUT
cat large-file.json | my-cli process.stream --format=json:cbor | my-cli save.processed --format=cbor
`Complete Example
Here's a complete example building a file processing CLI:
typescript
import { createCli } from '@jsonjoy.com/json-type-cli';
import { ObjectValue } from '@jsonjoy.com/json-type/lib/value/ObjectValue';
import * as fs from 'fs';
import * as path from 'path';const router = ObjectValue.create();
const { t } = router;
// File operations
router
.prop('file.read',
t.Function(
t.Object(
t.prop('path', t.str),
t.propOpt('encoding', t.str)
),
t.Object(
t.prop('content', t.str),
t.prop('size', t.num)
)
).options({
title: 'Read file content',
description: 'Reads a file and returns its content and size'
}),
async ({ path: filePath, encoding = 'utf8' }) => {
const content = fs.readFileSync(filePath, encoding);
return {
content,
size: content.length
};
}
)
.prop('file.write',
t.Function(
t.Object(
t.prop('path', t.str),
t.prop('content', t.str),
t.propOpt('encoding', t.str)
),
t.Object(
t.prop('success', t.bool),
t.prop('bytesWritten', t.num)
)
).options({
title: 'Write file content',
description: 'Writes content to a file'
}),
async ({ path: filePath, content, encoding = 'utf8' }) => {
fs.writeFileSync(filePath, content, encoding);
return {
success: true,
bytesWritten: Buffer.from(content, encoding).length
};
}
)
.prop('file.list',
t.Function(
t.Object(
t.prop('directory', t.str),
t.propOpt('pattern', t.str)
),
t.Object(
t.prop('files', t.Array(t.str)),
t.prop('count', t.num)
)
).options({
title: 'List directory files',
description: 'Lists files in a directory, optionally filtered by pattern'
}),
async ({ directory, pattern }) => {
let files = fs.readdirSync(directory);
if (pattern) {
const regex = new RegExp(pattern);
files = files.filter(file => regex.test(file));
}
return {
files,
count: files.length
};
}
);
const cli = createCli({
router,
version: 'v1.0.0',
cmd: 'file-cli'
});
cli.run();
`Usage examples:
bash
Read a file
file-cli file.read --str/path=package.json --format=json4Write content from STDIN
echo "Hello World" | file-cli file.write --str/path=output.txt --in/contentList JavaScript files
file-cli file.list --str/directory=src --str/pattern='\\.js$' --out=/filesChain operations: read -> transform -> write
file-cli file.read --str/path=input.json |
file-cli transform.data |
file-cli file.write --str/path=output.json --in/content --format=json:raw
``This example demonstrates the full power of JSON Type CLI for building robust, type-safe command-line tools that implement the JSON Rx RPC protocol with rich input/output capabilities.