UJSONLexicon
High-speed persistence adapter using ujson for flat-file serialization.
Class Overview
The UJSONLexicon class is an implementation of the Lexicon port.
It leverages the ujson library to handle large-scale JSON operations with significantly
lower latency than the standard library, making it ideal for graph-based flat-file storage.
UJSONLexicon → Lexicon
Initialization
__init__(storage_path: str = "codex_data.json")
Sets the path for the JSON database and ensures the file exists with a valid structure.
| Parameter | Type | Description |
|---|---|---|
storage_path |
string | The file path where data is persisted. Defaults to codex_data.json. |
Core Persistence
save(entry: Entry) -> None
Serializes an Entry object into the JSON store. Updates updated_at automatically.
delete(entry_id: str) -> bool
Removes an entry and performs manual referential integrity by cleaning up all associated relations.
Entry Retrieval
Methods designed to query the entry registry efficiently.
get_by_id(entry_id: str) -> Optional[Entry]
Retrieves a single entry by its unique identifier.
get_by_tag(tag: str) -> List[Entry]
Filters and returns all entries containing the specified tag.
get_by_date_range(start: datetime, end: datetime) -> List[Entry]
Returns entries created within the specified datetime window.
Relation Management
Handles the graph edges between different entries.
save_relation(relation: Relation)
Persists a link between two entries if it doesn't already exist.
get_out_relations(entry_id: str) -> List[Relation]
Retrieves all relations where the given ID is the from_id (source).
delete_relation(from_id, to_id, connection_type) -> bool
Removes a specific edge from the graph. Returns True if a deletion occurred.
Private Utilities
Internal methods for data mapping and file I/O.
_read_data(): Handles file opening andujson.load()with error recovery._write_data(data): Executesujson.dump()with optimized indentation._map_to_entry(dict): Converts raw JSON dictionaries back intoEntrydataclasses.