🗣️ json-humanized

📢Transform any JSON / YAML / TOML into natural human language

Live Demo · Installation · Usage · API · Config

What it does

$ jh user.json

This JSON contains a structured object with 6 fields.
• Identifier: usr_8f3k2
• Name: "Alice Johnson"
• Email address: [email protected]
• Age: 28 years old
• Password: *** (hidden for security)
• Balance: $4.3K
• Created: March 15, 2024 at 10:30 AM

Works 100% offline (no API key needed) — or plug in Claude AI / OpenAI / Ollama for smarter descriptions.

Installation

npm install -g json-humanized

Or use without installing:

npx json-humanized data.json

Usage

CLI

# Basic — local engine (offline, instant)
jh data.json

# YAML and TOML also work
jh config.yaml
jh settings.toml

# AI-powered (Claude)
jh data.json --engine ai

# AI with OpenAI
jh data.json --engine ai --provider openai

# AI with local Ollama (no API key!)
jh data.json --engine ai --provider ollama

# Output formats
jh data.json --format markdown --output report.md
jh data.json --format story
jh data.json --format json

# Diff two files
jh v1.json --diff v2.json
jh v1.json --diff v2.json --format markdown

# Watch mode — re-runs on every save
jh data.json --watch

# Stdin
echo '{"name":"Alice","age":30}' | jh --stdin

# Custom Handlebars template
jh data.json --template ./report.hbs

# Limit JSON chars sent to AI (saves tokens)
jh huge.json --engine ai --max-chars 8000

# Cache management
jh --cache-stats
jh --cache-clear

# Init config/template files
jh --init-config      # creates .jh.config.json
jh --init-template    # creates template.hbs

All CLI flags

| Flag | Default | Description | |------|---------|-------------| | --engine <engine> | local | local or ai | | --provider <provider> | anthropic | anthropic, openai, ollama | | --format <format> | plain | plain, markdown, story, json | | --mode <mode> | structured | structured, prose, story | | --lang <lang> | English | Any language (AI only) | | --context <text> | — | Context hint for AI | | --api-key <key> | env var | API key override | | --max-chars <n> | 12000 | Max chars sent to AI | | --output <file> | stdout | Save output to file | | --template <file> | — | Handlebars .hbs template | | --diff <fileB> | — | Compare two files | | --watch | — | Re-run on file changes | | --config <file> | auto | Explicit config file path | | --cache / --no-cache | true | Enable/disable AI caching | | --cache-clear | — | Delete all cached responses | | --cache-stats | — | Show cache info | | --init-config | — | Generate sample config | | --init-template | — | Generate sample template | | --stdin | — | Read from stdin | | --silent | — | No spinner, no banner |

API

const { humanize, humanizeFile, humanizeString } = require('json-humanized');

// Parse a JS value
const text = await humanize({ name: 'Alice', age: 30 });

// From a file (JSON, YAML, or TOML)
const text = await humanizeFile('./users.yaml', { format: 'markdown' });

// From a raw string
const text = await humanizeString('{"key":"value"}');

// AI mode with caching
const text = await humanize(data, {
  engine:    'ai',
  aiProvider: 'anthropic',  // or 'openai' | 'ollama'
  format:    'plain',
  lang:      'Russian',
  cache:     true,
  cacheTTL:  3600,
});

Diff

const { diff } = require('json-humanized');

// Compare two objects
const result = await diff.diff(before, after);
// "Found 3 differences: …"

// Compare two files
const result = await diff.diffFiles('v1.json', 'v2.json', { format: 'markdown' });

TypeScript

Full types are included — no @types/ package needed:

import { humanize, humanizeFile, HumanizeOptions } from 'json-humanized';

const opts: HumanizeOptions = { engine: 'ai', aiProvider: 'ollama', format: 'markdown' };
const text = await humanizeFile('./data.json', opts);

Config file

Create .jh.config.json (or run jh --init-config) to set defaults:

{
  "engine":   "local",
  "format":   "plain",
  "lang":     "English",
  "maxChars": 12000,
  "cache":    true,
  "cacheTTL": 3600,

  "fieldLabels": {
    "user_id":      "User ID",
    "txn_ref":      "Transaction reference",
    "internal_*":   null
  },

  "fieldTypes": {
    "invoice_no": "id",
    "balance":    "money"
  },

  "hiddenFields": ["debug_*", "internal_hash"],

  "aiProvider":   "anthropic",
  "ollamaUrl":    "http://localhost:11434",
  "ollamaModel":  "llama3",
  "openaiModel":  "gpt-4o-mini"
}

Config is searched upward from the current directory (like ESLint / Prettier).

Custom templates

Create a Handlebars template (or run jh --init-template):

# {{filename}}
> Generated: {{timestamp}} · Engine: {{engine}}

{{humanized}}

---
*Type: {{stats.type}}, Keys: {{stats.keys}}*

Use it with:

jh data.json --template ./report.hbs

Available template variables: {{humanized}}, {{filename}}, {{engine}}, {{format}}, {{timestamp}}, {{stats.type}}, {{stats.keys}}, {{stats.items}}

AI Providers

| Provider | Env Variable | Install | |----------|-------------|---------| | anthropic (default) | ANTHROPIC_API_KEY | npm install @anthropic-ai/sdk | | openai | OPENAI_API_KEY | npm install openai | | ollama | none needed | Install Ollama |

Optional dependencies — install only what you use.

Caching

AI responses are cached by default in ~/.jh-cache/.

• Same JSON + same options → returns cached result instantly
• Cache TTL: 1 hour (configurable)
• Override: jh data.json --engine ai --no-cache
• Clear all: jh --cache-clear
• Custom dir: JH_CACHE_DIR=/tmp/my-cache jh data.json --engine ai

Diff

$ jh v1.json --diff v2.json

Found 3 differences:

➕ Added (1):
   + phone (phone): "555-0100"

✏  Changed (2):
   ~ name (name): "Alice" → "Alice Johnson"
   ~ balance (balance): $4.3K → $4.5K

# AI-powered diff (more natural language)
$ jh v1.json --diff v2.json --engine ai --lang Russian

Watch mode

$ jh data.json --watch

Watches the file and re-runs humanization on every save. Supports local and AI engines.

Supported file types

| Extension | Notes | |-----------|-------| | .json | Always available | | .yaml, .yml | Requires npm install js-yaml | | .toml | Requires npm install @iarna/toml |

Project structure

json-humanized/
├── bin/
│   └── cli.js                  # CLI entry point
├── src/
│   ├── index.js                # Public API
│   ├── humanizer.js            # Rule-based engine
│   ├── config.js               # Config file loader
│   ├── cache.js                # AI response cache
│   ├── diff.js                 # Diff engine
│   ├── watch.js                # File watcher
│   ├── parsers/
│   │   └── index.js            # JSON / YAML / TOML parser
│   ├── formatters/
│   │   ├── index.js            # plain, markdown, story, json
│   │   └── template.js         # Handlebars template renderer
│   └── strategies/
│       ├── ai.js               # AI provider router
│       ├── openai.js           # OpenAI provider
│       └── ollama.js           # Ollama provider
├── docs/
│   ├── DEMO.html               # Live browser demo
│   └── ARCHITECTURE.md
├── examples/
├── test/
├── index.d.ts                  # TypeScript types
└── .jh.config.json             # (optional) project config

Contributing

See CONTRIBUTING.md. Issues and PRs are welcome!

License

MIT © json-humanized contributors