starddb 1.0.0

A lightweight JSON document database with field-level operation queuing and concurrency support

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

pip install starddb

Quick Start

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