Metadata-Version: 2.4
Name: starddb
Version: 1.0.0
Summary: A lightweight JSON document database with field-level operation queuing and concurrency support
Author: 
License: MIT
Project-URL: Homepage, https://github.com/obama/stardb
Project-URL: Repository, https://github.com/obama/stardb
Keywords: json,database,document-db,queue,concurrency,lightweight,embedded
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: filelock>=3.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# StarDDB (Star Document-database)

> "Shoot for the moon. Even if you miss, you'll land among the stars." - Norman Vincent Peale

StarDDB is a simple to use, lightweight (single file implementation) DB for efficient JSON-like storage management.

## Features

- Concurrency support via field-level operation queuing
- Easy-to-use API
- Automatic background persistence
- Nested document support
- Thread-safe (Python) / Event-loop safe (Node.js)

## Installation

```bash
pip install starddb
```

## Quick Start

```python
from stardb import StarDDBField, StarDDB

# Create a field and queue operations
field = StarDDBField(0)
field.update("set", 1)
field.update("mult", 5)
field.update("div", 0.5)
field.flush()
print(field.value)  # 10.0

# Use with a database file
db = StarDDB("data.json", save_time=5)
hook = db.db()
hook["health"].update("sub", 30)
hook["mana"].update("mult", 2)
db.close()
```

## API

### StarDDBField(value, max_queue_size=10000)

- `value` — Initial value (any JSON-serializable type)
- `max_queue_size` — Maximum queued operations (default: 10000)

**Methods:**
- `update(method, value)` — Queue an operation. Methods: `set`, `add`, `sub`, `mult`, `div`
- `flush()` — Block until all queued operations are processed

### StarDDB(database, save_time, database_hook=None, safe_root=None)

- `database` — Path to the JSON database file
- `save_time` — Seconds between automatic saves
- `database_hook` — Optional pre-loaded dict (skips file read)
- `safe_root` — Optional root directory to restrict path traversal

**Methods:**
- `db()` — Get the database hook (dict of StarDDBField instances)
- `flush()` — Block until all field operations are processed
- `close()` — Flush, save, and stop the background save thread
