<h1 align="center">
  <br>
  <a><img src="./assets/json_icon.png" alt="EasyJSON" width="200"></a>
  <br>
  JsonIO
  <br>
</h1>

<h4 align="center">🚀 Seamless JSON Handling in Python 🐍</h4>

<p align="center">
  <a href="https://github.com/itzAyrun/JsonIO">
    <img alt="Created At" src="https://img.shields.io/github/created-at/itzAyrun/JsonIO?logo=github">
  </a>
  <a href="https://github.com/itzAyrun/EasyJSON">
    <img alt="Last Commit" src="https://img.shields.io/github/last-commit/itzAyrun/JsonIO?logo=git">
  </a>
  <a href="./LICENSE">
    <img alt="MIT License" src="https://img.shields.io/github/license/itzAyrun/JsonIO?logo=securityscorecard">
  </a>
</p>

<p align="center">
  <a href="#overview">Overview</a> •
  <a href="#features">Features</a> •
  <a href="#installation">Installation</a> •
  <a href="#documentation">Documentation</a> •
  <a href="#usage">Usage</a> •
  <a href="#contributions">Contributions</a> •
  <a href="#license">License</a>
</p>

## Overview

**JsonIO** is a high-level API for handling JSON serialization and deserialization in Python using the [orjson](https://github.com/ijl/orjson) library. It provides a simple and efficient way to work with JSON data, including support for custom types.

## Features

- **Fast Serialization**: Built on `orjson`, offering high-performance JSON serialization.

- **Custom Serialization**: Easily extendable to handle non-standard data types with a custom encoder.

- **Convenient File Operations**: Load and save JSON data directly from/to files.

## Installation

You can install the module via pip:

```bash
pip install ayrun-jsonio
```

## Documentation

The documentation website is still **under development**.

## Usage

### Basic Functions

The module provides the following main functions:

- `loads(data: Union[str, bytes]) -> Any`: Deserialize a JSON string or bytes into a Python object.

- `load(filepath: Union[str, Path]) -> Any`: Read a JSON file and return the corresponding Python object.

- `dumps(obj: Any, *, option: Optional[int] = None, default: Optional[Callable[[Any], Any]] = None) -> str`: Serialize a Python object into a JSON string.

- `dump(obj: Any, filepath: Union[str, Path], *, option: Optional[int] = None, default: Optional[Callable[[Any], Any]] = None) -> None`: Serialize a Python object and write it to a JSON file.

### Example Usage

```python
import uuid
from datetime import datetime
from decimal import Decimal

import jsonio

# Sample data
data = {
    "name": "Alice",
    "age": 30,
    "balance": Decimal("1234.56"),  # Decimal support
    "tags": {"json", "python"},       # Set support
    "uuid": uuid.uuid4(),             # UUID support
    "timestamp": datetime.now()        # Datetime support
}

# Serialize to JSON string
json_str = jsonio.dumps(data, default=my_custom_encoder)
print(json_str)

# Deserialize from JSON string
loaded_data = jsonio.loads(json_str)
print(loaded_data)

# Save to a file
jsonio.dump(data, "data.json", default=my_custom_encoder)

# Load from a file
file_data = jsonio.load("data.json")
print(file_data)
```

## Contributions

Contributions are welcome! Please feel free to submit a pull request or open an issue if you encounter any problems or have suggestions for improvements.

## License

This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
