Metadata-Version: 2.3
Name: jsdfile
Version: 0.1.0
Summary: High-performance JSON serialization and deserialization library with efficient binary storage format. JSDFile combines msgspec speed with LZ4 compression for applications that need to store and retrieve JSON data rapidly while minimizing storage requirements.
License: MIT
Keywords: json,database,serialization,deserialization,compression,performance,msgspec,lz4,binary,file-format,data-storage,msgpack,high-performance,fast-json,io,persistence
Author: Alaamer
Author-email: ahmedmuhamed12@gmail.com
Maintainer: Alaamer
Maintainer-email: ahmedmuhamed239@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Object Brokering
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: System :: Filesystems
Classifier: Typing :: Typed
Requires-Dist: lz4 (>=4.4.4,<5.0.0)
Requires-Dist: msgspec (>=0.19.0,<0.20.0)
Project-URL: Documentation, https://github.com/alaamer12/jsdfile
Project-URL: Homepage, https://github.com/alaamer12/jsdfile
Project-URL: Repository, https://github.com/alaamer12/jsdfile
Project-URL: Source Code, https://github.com/alaamer12/jsdfile
Description-Content-Type: text/markdown

# 🚀 JSD (JSON Database)
> The next-generation JSON storage format for Python

<div >

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Format](https://img.shields.io/badge/format-JSD4-orange.svg)](BENCHMARK.md)

</div>

---

## 🌟 Overview

JSD revolutionizes JSON storage by combining cutting-edge compression techniques with lightning-fast serialization. Built for performance-critical applications, JSD delivers unmatched read speeds and exceptional storage efficiency.

### ✨ Key Features

- 🏃‍♂️ **Blazing Fast Reads**: Up to 5x faster than traditional JSON libraries
- 💾 **Superior Compression**: Up to 70% reduction in storage footprint
- 🧠 **Memory Efficient**: Optimized memory utilization during operations
- 🛠️ **Modern Architecture**: Leverages cutting-edge Python technologies
- 📊 **Rich Analytics**: Comprehensive benchmarking and visualization suite

## 🚀 Quick Start

### Installation

```bash
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt
```

### Basic Usage

## 🏗️ Architecture

JSD employs a sophisticated multi-layer architecture:

1. **Binary Serialization** 🔄
   - Powered by `msgspec` for maximum performance
   - Custom-optimized binary format
   - Intelligent type handling

2. **Compression Layer** 📦
   - LZ4 frame compression
   - Adaptive compression levels
   - Optimized for both speed and size

3. **Storage Format** 💾
   - Custom binary format with magic bytes
   - Fixed-size header for fast seeking
   - Versioned format support

## 📈 Performance

JSD delivers exceptional performance metrics:

| Operation   | vs orjson   | vs msgspec  | File Size Reduction |
|-------------|-------------|-------------|---------------------|
| Read (10k)  | 4.5x faster | 4.2x faster | 71% smaller         |
| Write (10k) | 1.1x faster | 1.0x faster | 71% smaller         |

*For detailed benchmarks, see [BENCHMARK.md](BENCHMARK.md)*

## 🛠️ Development Tools

### Included Utilities

- 📊 **Benchmark Suite**: Comprehensive performance testing
- 📈 **Visualization Tools**: Advanced performance analytics
- 🔧 **Data Generators**: Sophisticated test data creation
- 🧪 **Test Suite**: Extensive unit and integration tests

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create your feature branch
3. 💻 Commit your changes
4. 🚀 Push to the branch
5. 🎉 Open a Pull Request

## 📜 License

MIT License - see [LICENSE](LICENSE) for details

## 🙏 Acknowledgments

- [LZ4](https://github.com/lz4/lz4) - Exceptional compression library
- [msgspec](https://github.com/jcrist/msgspec) - Ultra-fast serialization
- [Python](https://python.org) - The foundation of it all

---

<div>

**[Benchmarks](BENCHMARK.md)**

Made with ❤️ by Alaamer

</div>

