bestjsonformatter 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suraj Krishnan Rajan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,39 +1,163 @@
-# Best JSON Formatter for agents
+# Best JSON Formatter CLI
 
-Private, deterministic JSON tools for MCP clients, coding agents, CI, and the
-terminal. Documents are processed inside the local Node.js process. The package
-does not make network requests or collect analytics.
+[![npm](https://img.shields.io/npm/v/bestjsonformatter)](https://www.npmjs.com/package/bestjsonformatter)
+[![CI](https://github.com/skrcode/bestjsonformatter-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/skrcode/bestjsonformatter-cli/actions/workflows/ci.yml)
+[![skills.sh](https://skills.sh/b/skrcode/bestjsonformatter-cli)](https://skills.sh/skrcode/bestjsonformatter-cli)
 
-## MCP
+Fast, local JSON formatting and correctness checks without lossy
+`JSON.parse()`/`JSON.stringify()` round trips.
 
-Add a stdio server with this command:
+```bash
+npx -y bestjsonformatter@latest check response.json
+npx -y bestjsonformatter@latest format response.json --write
+```
+
+Best JSON Formatter preserves duplicate object properties, integers beyond JavaScript's safe
+range, decimal and exponent spelling, string escape spelling, and property order. It performs no
+network requests, collects no analytics, and requires no MCP server or account.
+
+## Install
+
+Use it without installing:
+
+```bash
+npx -y bestjsonformatter@latest check package.json
+```
+
+Or install the short `bjf` command:
+
+```bash
+npm install --global bestjsonformatter
+bjf check package.json
+```
+
+Node.js 20 or newer is required.
+
+## Check JSON
+
+`check` validates syntax and finds duplicate keys and numbers that ordinary JavaScript parsing may
+round, overflow, underflow, or rewrite:
+
+```bash
+bjf check response.json
+bjf check response.json --json
+bjf check response.json --schema response.schema.json
+```
+
+Exit codes are stable for CI and coding agents:
+
+| Code | Meaning |
+| ---: | --- |
+| `0` | Valid JSON with no selected correctness findings |
+| `1` | Invalid JSON, correctness findings, schema errors, or formatting differences |
+| `2` | Invalid command, inaccessible file, or internal failure |
+
+## Format JSON
+
+```bash
+bjf format response.json
+bjf format response.json --check
+bjf format response.json --write
+bjf format response.json --indent minified
+bjf format response.json --indent tab
+bjf format response.json --sort
+```
 
-```text
-npx -y bestjsonformatter mcp
+Ordinary formatting changes whitespace only. `--sort` explicitly reorders object properties while
+preserving array order and exact scalar tokens. `--write` uses a same-directory temporary file and
+atomic rename.
+
+Multiple files are supported when checking or writing:
+
+```bash
+bjf format package.json fixtures/*.json --check
+bjf format package.json fixtures/*.json --write
+bjf check fixtures/*.json --json
+```
+
+## Repair, query, compare, convert, and use schemas
+
+```bash
+bjf repair broken.json
+bjf repair broken.json --write
+bjf duplicates response.json
+bjf precision response.json
+bjf compare before.json after.json
+bjf query '$.items[*].id' response.json
+bjf to-yaml response.json
+bjf to-csv records.json
+bjf to-xml response.json
+bjf schema-infer response.json
+bjf schema-validate response.json schema.json
+bjf schema-sample schema.json
 ```
 
-The server exposes formatting, validation, repair, duplicate-key and
-number-precision analysis, structural comparison, JSONPath, YAML/CSV/XML
-conversion, and Draft 2020-12 JSON Schema tools.
+Repair output is a proposal unless `--write` is explicitly supplied. Use `-o output.ext` to write
+conversion or repair output to a separate file.
+
+## Coding agents
+
+Agents can call the CLI directly through their normal shell, so JSON never has to be copied into an
+MCP tool argument or model context.
 
-## CLI
+Install the agent skill:
 
 ```bash
-printf '%s' '{"id":9007199254740993}' | npx bestjsonformatter format --indent 2
-npx bestjsonformatter validate response.json
-npx bestjsonformatter duplicates response.json
-npx bestjsonformatter precision response.json
-npx bestjsonformatter compare before.json after.json
-npx bestjsonformatter query '$.items[*].id' response.json
+npx skills add skrcode/bestjsonformatter-cli
+```
+
+The skill teaches Codex, Claude Code, Cursor, GitHub Copilot, and other compatible agents to run
+compact checks first and request explicit authorization before `--write`.
+
+## Library
+
+The same engine is available as an ESM library:
+
+```ts
+import { checkJson, formatLosslessJson } from "bestjsonformatter";
+
+const checked = checkJson(source);
+const formatted = formatLosslessJson(source, 2).formatted;
 ```
 
-Run `npx bestjsonformatter --help` for every command.
+Heavy repair, diff, query, conversion, and schema dependencies are loaded only when their
+operations are requested. Formatting, validation, and correctness checks stay on the small local
+hot path.
+
+## Performance and correctness
+
+In the repository's reproducible five-run benchmark, Best JSON Formatter is the fastest formatter
+that passes every exact-token check.
+
+| Fresh-process median | 155 B | 105 KB | 1.07 MB | 5.35 MB | Fully lossless |
+| --- | ---: | ---: | ---: | ---: | :---: |
+| Best JSON Formatter 0.2.0 | **54 ms** | **76 ms** | **143 ms** | **473 ms** | Yes |
+| Biome 2.5.6 | 58 ms | 88 ms | 280 ms | 1,150 ms | No |
+| Prettier 3.9.6 | 120 ms | 234 ms | 955 ms | 3,926 ms | No |
+| jsonc-parser 3.3.1 | 63 ms | 825 ms | >15,000 ms | >15,000 ms | Yes |
+| jq 1.8.2 | 5 ms | 14 ms | 105 ms | 500 ms | No |
 
-## Correctness
+The comparison uses identical stdin payloads and complete fresh CLI processes. jq is faster on
+small and one-megabyte inputs but discards duplicate keys and rewrites number and escape spelling.
+Results are bounded to the recorded machine, versions, inputs, and command boundaries—not a
+universal speed claim. See [the complete method, raw samples, Python and native Node
+results](docs/BENCHMARKS.md).
+
+## Privacy
+
+Documents are read and processed inside the local Node.js process. The package contains no
+telemetry client, post-install script, network request, account system, or hosted document API.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run benchmark
+```
 
-Unlike a `JSON.parse()` and `JSON.stringify()` round trip, formatting preserves
-duplicate object properties, integers beyond JavaScript's safe range, exponent
-notation, and original escape spelling. Repair output is always a proposal for
-review rather than an automatic source-file mutation.
+Every formatting change must preserve the exact-token fixtures. Performance changes must record
+the complete journey, competitor versions, raw samples, median, p95, correctness, and timeouts.
 
-Website and documentation: <https://bestjsonformatter.org/agents>
+MIT licensed. The browser tool is available at
+[bestjsonformatter.org](https://bestjsonformatter.org).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,429 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { once } from "node:events";
+import { readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+const help = `Best JSON Formatter — fast, local, lossless JSON tools
+
+Usage:
+  bjf format [file ...] [--indent minified|2|3|4|tab] [--sort] [--write|--check]
+  bjf check [file ...] [--schema schema.json] [--json]
+  bjf validate [file ...] [--json]
+  bjf repair [file|-] [--write|-o output.json]
+  bjf duplicates [file|-]
+  bjf precision [file|-]
+  bjf compare <original.json> <changed.json>
+  bjf query <jsonpath> [file|-]
+  bjf to-yaml|to-csv|to-xml [file|-] [-o output]
+  bjf schema-infer [file|-]
+  bjf schema-validate <document.json> <schema.json>
+  bjf schema-sample [schema.json|-]
+
+Use "-" or pipe stdin for document input. Formatting changes whitespace only:
+duplicate keys, large integers, number notation, string escapes, and key order
+remain exact unless --sort or repair is explicitly requested.
+
+Options:
+  -w, --write       Write the result back atomically
+  -c, --check       Exit 1 when formatting differs
+  -o, --output      Write to a separate file
+      --json        Emit machine-readable check or validation results
+  -q, --quiet       Suppress successful human-readable status
+  -h, --help        Show help
+  -v, --version     Show the installed version`;
+function parseIndent(value) {
+    if (value === "minified" || value === "0")
+        return 0;
+    if (value === "tab")
+        return "tab";
+    if (value === "2" || value === "3" || value === "4")
+        return Number(value);
+    throw new TypeError("--indent must be minified, 2, 3, 4, or tab.");
+}
+function parseArguments(args) {
+    const options = {
+        indent: 2,
+        sort: false,
+        write: false,
+        check: false,
+        json: false,
+        quiet: false,
+    };
+    const operands = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--") {
+            operands.push(...args.slice(index + 1));
+            break;
+        }
+        if (!argument.startsWith("-") || argument === "-") {
+            operands.push(argument);
+            continue;
+        }
+        const [name, inlineValue] = argument.split("=", 2);
+        const value = () => {
+            if (inlineValue !== undefined)
+                return inlineValue;
+            const next = args[index + 1];
+            if (next === undefined)
+                throw new TypeError(`${name} requires a value.`);
+            index += 1;
+            return next;
+        };
+        switch (name) {
+            case "--indent":
+                options.indent = parseIndent(value());
+                break;
+            case "--output":
+            case "-o":
+                options.output = value();
+                break;
+            case "--schema":
+                options.schema = value();
+                break;
+            case "--sort":
+                options.sort = true;
+                break;
+            case "--write":
+            case "-w":
+                options.write = true;
+                break;
+            case "--check":
+            case "-c":
+                options.check = true;
+                break;
+            case "--json":
+                options.json = true;
+                break;
+            case "--quiet":
+            case "-q":
+                options.quiet = true;
+                break;
+            default:
+                throw new TypeError(`Unknown option: ${name}`);
+        }
+    }
+    return { options, operands };
+}
+async function installedVersion() {
+    const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function readDocument(path) {
+    if (path !== "-")
+        return readFile(path, "utf8");
+    if (process.stdin.isTTY)
+        throw new TypeError("Provide a file path or pipe JSON through stdin.");
+    return readStdin();
+}
+async function writeStdout(value) {
+    if (!process.stdout.write(value))
+        await once(process.stdout, "drain");
+}
+function withFinalNewline(value) {
+    return `${value.replace(/\n*$/, "")}\n`;
+}
+async function writeAtomically(path, value) {
+    const temporaryPath = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    let mode;
+    try {
+        mode = (await stat(path)).mode;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    try {
+        await writeFile(temporaryPath, value, mode === undefined ? undefined : { mode });
+        await rename(temporaryPath, path);
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+function displayPath(path) {
+    return path === "-" ? "<stdin>" : path;
+}
+function setFailure() {
+    process.exitCode = 1;
+}
+function syntaxFailure(path, error) {
+    if (error &&
+        typeof error === "object" &&
+        "line" in error &&
+        "column" in error &&
+        "message" in error) {
+        const line = String(error.line);
+        const column = String(error.column);
+        process.stderr.write(`${displayPath(path)}:${line}:${column} ${String(error.message)}\n`);
+    }
+    else {
+        const message = error instanceof Error ? error.message : "Invalid JSON.";
+        process.stderr.write(`${displayPath(path)}: ${message}\n`);
+    }
+    setFailure();
+}
+async function formatCommand(files, options) {
+    const paths = files.length ? files : ["-"];
+    if (options.write && options.check)
+        throw new TypeError("--write and --check cannot be combined.");
+    if (options.output && (options.write || options.check || paths.length !== 1)) {
+        throw new TypeError("--output requires one input and cannot be combined with --write or --check.");
+    }
+    if (paths.length > 1 && !options.write && !options.check) {
+        throw new TypeError("Multiple format inputs require --write or --check.");
+    }
+    if ((options.write || options.check) && paths.includes("-")) {
+        throw new TypeError("--write and --check require file paths, not stdin.");
+    }
+    const { JsonSyntaxError, formatLosslessJson } = await import("./lib/lossless-json.js");
+    for (const path of paths) {
+        const input = await readDocument(path);
+        try {
+            let output;
+            if (options.sort) {
+                const { runTool } = await import("./lib/json-tools.js");
+                const result = await runTool({
+                    operation: "sort",
+                    input,
+                    indent: options.indent,
+                    includeEdits: false,
+                });
+                if (!result.ok) {
+                    syntaxFailure(path, result);
+                    continue;
+                }
+                output = result.value;
+            }
+            else {
+                output = formatLosslessJson(input, options.indent).formatted;
+            }
+            const rendered = withFinalNewline(output);
+            if (options.check) {
+                if (input !== rendered) {
+                    process.stderr.write(`${path}: formatting differs\n`);
+                    setFailure();
+                }
+                else if (!options.quiet) {
+                    process.stdout.write(`${path}: formatted\n`);
+                }
+            }
+            else if (options.write) {
+                if (input !== rendered)
+                    await writeAtomically(path, rendered);
+                if (!options.quiet)
+                    process.stdout.write(`${path}: ${input === rendered ? "unchanged" : "formatted"}\n`);
+            }
+            else if (options.output) {
+                await writeAtomically(options.output, rendered);
+            }
+            else {
+                await writeStdout(rendered);
+            }
+        }
+        catch (error) {
+            if (error instanceof JsonSyntaxError)
+                syntaxFailure(path, error);
+            else
+                throw error;
+        }
+    }
+}
+async function validateCommand(files, options) {
+    const paths = files.length ? files : ["-"];
+    const { JsonSyntaxError, parseLosslessJson } = await import("./lib/lossless-json.js");
+    const results = [];
+    for (const path of paths) {
+        const input = await readDocument(path);
+        try {
+            const parsed = parseLosslessJson(input);
+            results.push({ path: displayPath(path), valid: true, metadata: parsed.metadata });
+            if (!options.json && !options.quiet)
+                process.stdout.write(`${displayPath(path)}: valid JSON\n`);
+        }
+        catch (error) {
+            setFailure();
+            if (error instanceof JsonSyntaxError) {
+                results.push({
+                    path: displayPath(path),
+                    valid: false,
+                    message: error.message,
+                    line: error.line,
+                    column: error.column,
+                    offset: error.offset,
+                });
+                if (!options.json)
+                    syntaxFailure(path, error);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    if (options.json) {
+        await writeStdout(`${JSON.stringify(paths.length === 1 ? results[0] : results, null, 2)}\n`);
+    }
+}
+async function checkCommand(files, options) {
+    const paths = files.length ? files : ["-"];
+    const { checkJson } = await import("./lib/json-check.js");
+    const schemaInput = options.schema ? await readFile(options.schema, "utf8") : undefined;
+    const results = [];
+    for (const path of paths) {
+        const input = await readDocument(path);
+        const result = checkJson(input);
+        const schemaErrors = [];
+        if (result.valid && schemaInput !== undefined) {
+            const { validateJsonSchema } = await import("./lib/json-schema.js");
+            const schemaResult = await validateJsonSchema(input, schemaInput);
+            schemaErrors.push(...schemaResult.errors);
+        }
+        const clean = result.valid && result.clean && schemaErrors.length === 0;
+        if (!clean)
+            setFailure();
+        results.push({
+            path: displayPath(path),
+            ...result,
+            ...(schemaInput === undefined
+                ? {}
+                : { schemaValid: schemaErrors.length === 0, schemaErrors }),
+        });
+        if (options.json)
+            continue;
+        if (!result.valid) {
+            process.stderr.write(`${displayPath(path)}:${result.line}:${result.column} ${result.message}\n`);
+            continue;
+        }
+        for (const issue of result.issues) {
+            const location = issue.locations[0];
+            process.stderr.write(`${displayPath(path)}:${location.line}:${location.column} ${issue.severity} ${issue.code} ${issue.path}: ${issue.message}\n`);
+        }
+        for (const error of schemaErrors) {
+            process.stderr.write(`${displayPath(path)}: error schema: ${error}\n`);
+        }
+        if (clean && !options.quiet) {
+            process.stdout.write(`${displayPath(path)}: valid, lossless-safe JSON\n`);
+        }
+    }
+    if (options.json) {
+        await writeStdout(`${JSON.stringify(paths.length === 1 ? results[0] : results, null, 2)}\n`);
+    }
+}
+async function executeToolCommand(command, operands, options) {
+    const { runTool } = await import("./lib/json-tools.js");
+    let operation;
+    let inputPath = operands[0] ?? "-";
+    let secondaryInput;
+    let query;
+    switch (command) {
+        case "repair":
+            operation = "repair";
+            break;
+        case "duplicates":
+            operation = "duplicates";
+            break;
+        case "precision":
+            operation = "precision";
+            break;
+        case "compare":
+            if (operands.length !== 2)
+                throw new TypeError("compare requires two JSON files.");
+            operation = "compare";
+            inputPath = operands[0];
+            secondaryInput = await readDocument(operands[1]);
+            break;
+        case "query":
+            if (!operands[0])
+                throw new TypeError("query requires a JSONPath expression.");
+            operation = "jsonpath";
+            query = operands[0];
+            inputPath = operands[1] ?? "-";
+            break;
+        case "to-yaml":
+        case "to-csv":
+        case "to-xml":
+            operation = command.slice(3);
+            break;
+        case "schema-infer":
+            operation = "schema";
+            break;
+        case "schema-validate":
+            if (operands.length !== 2) {
+                throw new TypeError("schema-validate requires a JSON file and a schema file.");
+            }
+            operation = "schema_validate";
+            inputPath = operands[0];
+            secondaryInput = await readDocument(operands[1]);
+            break;
+        case "schema-sample":
+            operation = "schema_sample";
+            break;
+        default:
+            throw new TypeError(`Unknown command: ${command}`);
+    }
+    if (options.write && command !== "repair") {
+        throw new TypeError("--write is supported by format and repair.");
+    }
+    if (options.output && options.write)
+        throw new TypeError("--output and --write cannot be combined.");
+    if (options.write && inputPath === "-")
+        throw new TypeError("--write requires a file path.");
+    const input = await readDocument(inputPath);
+    const result = await runTool({
+        operation,
+        input,
+        secondaryInput,
+        query,
+        indent: options.indent,
+        includeEdits: false,
+    });
+    if (!result.ok) {
+        syntaxFailure(inputPath, result);
+        return;
+    }
+    const rendered = withFinalNewline(result.value);
+    if (options.write) {
+        await writeAtomically(inputPath, rendered);
+        if (!options.quiet)
+            process.stdout.write(`${inputPath}: repaired\n`);
+    }
+    else if (options.output) {
+        await writeAtomically(options.output, rendered);
+    }
+    else {
+        await writeStdout(rendered);
+    }
+}
+async function main(args) {
+    const first = args[0];
+    if (!first || first === "help" || first === "--help" || first === "-h") {
+        process.stdout.write(`${help}\n`);
+        return;
+    }
+    if (first === "--version" || first === "-v" || first === "version") {
+        process.stdout.write(`${await installedVersion()}\n`);
+        return;
+    }
+    const { options, operands } = parseArguments(args.slice(1));
+    if (first === "format")
+        await formatCommand(operands, options);
+    else if (first === "validate")
+        await validateCommand(operands, options);
+    else if (first === "check")
+        await checkCommand(operands, options);
+    else
+        await executeToolCommand(first, operands, options);
+}
+main(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : "The command failed.";
+    process.stderr.write(`bestjsonformatter: ${message}\n`);
+    process.exitCode = 2;
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { checkJson, type JsonCheckIssue, type JsonCheckResult, type JsonIssueLocation, } from "./lib/json-check.js";
+export { parseJson, runTool, type TextEdit, type ToolFailure, type ToolOperation, type ToolRequest, type ToolResponse, type ToolResult, } from "./lib/json-tools.js";
+export { canonicalJsonNumber, formatLosslessJson, type JsonNode, type JsonParseMetadata, JsonSyntaxError, jsonNodeToNative, type LosslessFormatResult, LosslessNumber, type LosslessParseResult, type LosslessTreeResult, parseLosslessJson, serializeJsonNode, stringifyNativeLosslessly, } from "./lib/lossless-json.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { checkJson, } from "./lib/json-check.js";
+export { parseJson, runTool, } from "./lib/json-tools.js";
+export { canonicalJsonNumber, formatLosslessJson, JsonSyntaxError, jsonNodeToNative, LosslessNumber, parseLosslessJson, serializeJsonNode, stringifyNativeLosslessly, } from "./lib/lossless-json.js";

package/dist/lib/json-check.d.ts

@@ -0,0 +1,32 @@
+import { type JsonParseMetadata } from "./lossless-json.js";
+export type JsonIssueLocation = {
+    line: number;
+    column: number;
+    offset: number;
+};
+export type JsonCheckIssue = {
+    code: "duplicate-key" | "unsafe-number" | "number-overflow" | "number-underflow" | "number-spelling";
+    severity: "error" | "warning";
+    path: string;
+    message: string;
+    token?: string;
+    locations: JsonIssueLocation[];
+};
+type JsonCheckSuccess = {
+    valid: true;
+    clean: boolean;
+    issues: JsonCheckIssue[];
+    metadata: JsonParseMetadata;
+};
+type JsonCheckFailure = {
+    valid: false;
+    clean: false;
+    issues: [];
+    message: string;
+    line: number;
+    column: number;
+    offset: number;
+};
+export type JsonCheckResult = JsonCheckSuccess | JsonCheckFailure;
+export declare function checkJson(input: string): JsonCheckResult;
+export {};