Metadata-Version: 2.4
Name: starddb
Version: 1.0.1
Summary: A lightweight JSON document database with field-level operation queuing and concurrency support
Author: 
License-Expression: MIT
Project-URL: Homepage, https://github.com/lucidityai/stardb
Project-URL: Repository, https://github.com/lucidityai/stardb
Keywords: json,database,document-db,queue,concurrency,lightweight,embedded
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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`, `push`
- `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
- `add_field(key_path, value)` — Add a new field to a nested dict at runtime. `key_path` is a dot-separated string (`"players.new_guy"`) or list of keys. Dict values are automatically crawled into `StarDDBField` instances. Raises `KeyError` if the path doesn't exist or the key already exists.

**`push` operation:**
```python
# Append a value to a list field
hook["scores"].update("push", 30)
```

**`add_field` examples:**
```python
# Add a primitive or list field
db.add_field("players.new_guy", 0)
db.add_field("players.new_guy.inventory", [])

# Add a nested dict (crawled automatically)
db.add_field("players.new_guy", {"coins": 0, "level": 1})
hook["players"]["new_guy"]["coins"].update("add", 5)

# Use a list of keys to avoid dot ambiguity
db.add_field(["some.weird.key", "nested"], 42)
```
