npm package: @nomanbinhussein/jsonx
Description: Comprehensive JSON Helper Library - Parse, Fix, Analyze, Search, Compare, Merge, Convert and more
Author: Noman Hasan
Latest version: 1.0.0

# 🔧 JSONX - The Ultimate JSON Fixing and Manipulation Library

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

[![npm version](https://badge.fury.io/js/@nomanbinhussein/jsonx.svg)](https://badge.fury.io/js/@nomanbinhussein/jsonx)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
npm install @nomanbinhussein/jsonx
```

```bash
yarn add @nomanbinhussein/jsonx
```

```bash
pnpm add @nomanbinhussein/jsonx
```

## 🚀 Quick Start

### Basic Usage

```typescript
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

```typescript
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

```typescript
// 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

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

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

#### 🔄 Transform & Merge

```typescript
// 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

```typescript
// 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

```typescript
// 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)

```typescript
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

```typescript
import JSONX from '@nomanbinhussein/jsonx';

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

### 📝 Configuration Management

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

### 🔍 Data Analysis

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

### 🌐 Format Conversion

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

## 🚨 Error Handling

JSONX provides detailed error information:

```typescript
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:

```typescript
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](CONTRIBUTING.md) for details.

### Development Setup

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

### Running Tests

```bash
npm test
npm run test:coverage
```

### Building

```bash
npm run build
```

## 📄 License

MIT © [Noman Hasan](https://github.com/nomanHasan)

## 🔗 Links

- [GitHub](https://github.com/nomanHasan/jsonx)
- [NPM](https://www.npmjs.com/package/@nomanbinhussein/jsonx)
- [Issues](https://github.com/nomanHasan/jsonx/issues)

---

<div align="center">
  <strong>Built with ❤️ for developers who work with JSON</strong>
</div>