starddb 1.0.1

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, 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:

# Append a value to a list field
hook["scores"].update("push", 30)

add_field examples:

# 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)