npm package: @gamedevmadeeasy/json-utils
Description: Extended utilities for JSON manipulation with cross-environment compatibility
Author: Your Name
Latest version: 1.0.1

# JSON Utilities

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/yourusername/json-utilities)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)

Extended utilities for JSON manipulation with cross-environment compatibility.

## Features

- Convert between JSON strings, JavaScript objects, and Map data structures
- Deep merge objects and Maps
- Flatten nested objects
- Schema validation
- Pretty printing
- Safe parsing with default values
- Cross-platform compatibility (Browser, Node.js)
- TypeScript support
- .NET implementation

## Installation

### Browser

```html
<script src="json-utilities.js"></script>
<script>
  // Access as JSONUtils
  const map = JSONUtils.objectify('{"key": "value"}');
</script>
```

### Node.js

```bash
npm install json-utilities
```

```javascript
const JSONUtils = require('json-utilities');
const map = JSONUtils.objectify('{"key": "value"}');
```

### TypeScript

```bash
npm install json-utilities
```

For TypeScript users, add the appropriate target library in your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "lib": ["es5", "dom"],
    "target": "es5"
  }
}
```

## API Reference

### Type Enum

```javascript
JSONUtils.Type.STRING  // "string"
JSONUtils.Type.OBJECT  // "object"
JSONUtils.Type.MAP     // "map"
JSONUtils.Type.JSON    // "json"
```

### Methods

#### `objectify(jsonString)`

Converts a JSON string into a Map of key-value pairs.

```javascript
const map = JSONUtils.objectify('{"name": "John", "age": 30}');
console.log(map.get('name')); // "John"
```

#### `convert(value, toType)`

Polymorphic converter between different JSON representations.

```javascript
// Convert string to object
const obj = JSONUtils.convert('{"name": "John"}', JSONUtils.Type.OBJECT);

// Convert object to string
const str = JSONUtils.convert({name: "John"}, JSONUtils.Type.STRING);

// Convert object to Map
const map = JSONUtils.convert({name: "John"}, JSONUtils.Type.MAP);
```

#### `deepMerge(target, source)`

Deeply merges two objects or Maps.

```javascript
const obj1 = { user: { name: "John", age: 30 } };
const obj2 = { user: { age: 31, city: "New York" } };
const result = JSONUtils.deepMerge(obj1, obj2);
// result: { user: { name: "John", age: 31, city: "New York" } }
```

#### `flatten(obj, separator)`

Flattens a nested object structure into a single-level object with path-based keys.

```javascript
const nested = { 
  user: { 
    name: "John", 
    address: { city: "New York", zip: 10001 } 
  } 
};
const flat = JSONUtils.flatten(nested);
// result: { 
//   "user.name": "John", 
//   "user.address.city": "New York", 
//   "user.address.zip": 10001 
// }
```

#### `validate(json, schema)`

Validates a JSON string or object against a schema.

```javascript
const schema = {
  required: ["name", "age"],
  properties: {
    name: { type: "string" },
    age: { type: "number" }
  }
};

const result = JSONUtils.validate('{"name": "John", "age": 30}', schema);
console.log(result.valid); // true
```

#### `prettyPrint(json, spaces)`

Pretty prints JSON with custom indentation.

```javascript
const formatted = JSONUtils.prettyPrint({ name: "John", age: 30 }, 4);
```

#### `safeParse(str, defaultValue)`

Safely parses JSON with a default value if parsing fails.

```javascript
const data = JSONUtils.safeParse('{"name": "John"}');
const invalid = JSONUtils.safeParse('invalid', { name: "Unknown" });
```

## TypeScript Support

TypeScript definitions are included:

```typescript
import * as JSONUtils from 'json-utilities';

const map: JSONUtils.StringKeyMap<any> = JSONUtils.objectify('{"key": "value"}');
const value: string = map.get('key') as string;
```

## .NET Implementation

A .NET implementation is available in the `JSONUtilities` namespace:

```csharp
using JSONUtilities;

var map = JSONUtils.Objectify("{\"name\": \"John\", \"age\": 30}");
Console.WriteLine(map["name"]); // "John"
```

## Compatibility

- Works in all modern browsers
- Works in Node.js
- TypeScript support with ES5 fallback
- .NET implementation for C# developers

## License

MIT