🔧 JSONX - The Ultimate JSON Fixing and Manipulation Library

Comprehensive, intuitive, and powerful JSON helper library for TypeScript/JavaScript

JSONX is designed to be the most intuitive, powerful, and developer-friendly JSON fixing and manipulation library. It automatically repairs malformed JSON and provides a comprehensive set of tools for parsing, fixing, analyzing, searching, comparing, merging, converting, validating, and transforming JSON data.

✨ Features

• 🚀 Lightning Fast - Optimized for performance
• 🔒 Type Safe - Full TypeScript support with strict typing
• 🛠️ Auto-Fix - Automatically repair malformed JSON
• 📊 Deep Analysis - Comprehensive JSON structure analysis
• 🔍 Powerful Search - JSONPath and regex-based searching
• 🔄 Smart Merging - Intelligent merge strategies with conflict resolution
• 🌐 Multi-Format - Convert to YAML, XML, CSV, and more
• ✅ Validation - JSON Schema and custom validation rules
• 🎯 Chainable API - Fluent interface for complex operations
• 🧩 Zero Dependencies - No external dependencies for core functionality

📦 Installation

npm install @nomanbinhussein/jsonx

yarn add @nomanbinhussein/jsonx

pnpm add @nomanbinhussein/jsonx

🚀 Quick Start

Basic Usage

import JSONX from '@nomanbinhussein/jsonx';

// Parse with detailed error information
const result = JSONX.parse('{"name": "John", "age": 30}');
if (result.success) {
  console.log(result.data); // { name: "John", age: 30 }
} else {
  console.log(result.error.message);
}

// Auto-fix malformed JSON
const fixed = JSONX.fix(`{name: 'John', age: 30,}`);
console.log(fixed.data); // {"name": "John", "age": 30}

// Validate JSON data
const validation = JSONX.validate(data);
console.log(validation.valid, validation.errors);

Chainable Operations

import JSONX from '@nomanbinhussein/jsonx';

const result = new JSONX(`{"users": [{"name": "John"}, {"name": "Jane"}]}`)
  .parse()
  .validate()
  .transform(data => ({
    ...data,
    users: data.users.map(user => ({ ...user, id: Math.random() }))
  }))
  .merge({ timestamp: new Date().toISOString() })
  .get();

📖 API Reference

Static Methods (Quick Operations)

🔍 Parse & Fix

// Safe parsing with detailed errors
JSONX.parse(jsonString, options?)
JSONX.fix(malformedJson, options?)

// Examples
const result = JSONX.parse('{"invalid": json}');
const fixed = JSONX.fix(`{name: 'John', age: 30,}`);

✅ Validate & Analyze

// Validation and analysis
JSONX.validate(data, schema?)
JSONX.analyze(data, options?)

// Examples
const isValid = JSONX.validate(data);
const insights = JSONX.analyze(data);

🔄 Transform & Merge

// Data manipulation
JSONX.transform(data, transformer, options?)
JSONX.merge(obj1, obj2, strategy?)

// Examples
const transformed = JSONX.transform(data, x => x.users.filter(u => u.active));
const merged = JSONX.merge(config, userConfig);

🔍 Search & Compare

// Search and comparison
JSONX.search(data, query, options?)
JSONX.compare(obj1, obj2, options?)

// Examples
const users = JSONX.search(data, 'John');
const diff = JSONX.compare(original, modified);

🌐 Convert

// Format conversion
JSONX.convert(data, format, options?)

// Examples
const yaml = JSONX.convert(data, 'yaml');
const csv = JSONX.convert(arrayData, 'csv', { headers: true });

Instance Methods (Chainable API)

const jsonMan = new JSONX(initialData);

jsonMan
  .parse(jsonString)           // Parse JSON string
  .validate(schema)            // Validate against schema
  .transform(transformer)      // Transform data
  .merge(otherData)           // Merge with other data
  .search(query)              // Search within data
  .get();                     // Get final result

// Error handling
if (jsonMan.hasErrors()) {
  console.log(jsonMan.getErrors());
}

🎯 Use Cases

🔧 API Response Processing

import JSONX from '@nomanbinhussein/jsonx';

// Process potentially malformed API responses
const processApiResponse = (response: string) => {
  return new JSONX()
    .parse(response)
    .validate()
    .get();
};

📝 Configuration Management

// Merge user config with defaults
const config = JSONX.merge(defaultConfig, userConfig);

🔍 Data Analysis

// Analyze JSON structure
const analysis = JSONX.analyze(complexData);
console.log(`Depth: ${analysis.depth}`);
console.log(`Size: ${analysis.size}`);

🌐 Format Conversion

// Convert between formats
const yaml = JSONX.convert(jsonData, 'yaml');
const xml = JSONX.convert(jsonData, 'xml');

🚨 Error Handling

JSONX provides detailed error information:

const result = JSONX.parse('{"invalid": json}');

if (!result.success) {
  console.log(result.error.message);     // Detailed error message
  console.log(result.error.position);    // Line and column information
}

🔧 TypeScript Support

JSONX is built with TypeScript and provides full type safety:

import { JSONValue, JSONObject, ParseResult } from '@nomanbinhussein/jsonx';

// Type-safe operations
const result: ParseResult = JSONX.parse(jsonString);

🚀 Performance

JSONX is optimized for performance:

• Fast parsing with minimal overhead
• Memory efficient operations
• Lazy evaluation where possible
• Bundle size optimized (< 50KB)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/nomanHasan/jsonx.git
cd jsonx
npm install
npm run dev

Running Tests

npm test
npm run test:coverage

Building

npm run build

📄 License

MIT © Noman Hasan

🔗 Links

• GitHub
• NPM
• Issues