ORJSONLexicon

Ultra-high performance persistence adapter using orjson for native serialization.

Overview

The ORJSONLexicon class is an implementation of the Lexicon interface. It optimizes data storage by leveraging orjson, providing faster serialization of datetime objects and UUIDs compared to standard JSON libraries.

Key Feature: Uses binary mode (wb/rb) to maximize I/O throughput with orjson.dumps and orjson.loads.

Initialization

init(storage_path: str = "codex_data.json")

Initializes the storage path and ensures the JSON structure is ready for use.

Core Persistence Methods

These internal methods handle the low-level communication with the file system.

Method	Description
`_read_data()`	Loads the graph structure using `orjson.loads`. Returns a dictionary.
`_write_data(data: Dict)`	Saves data with `OPT_INDENT_2` for readability and `OPT_UTC_Z` for ISO standards.
`_initialize_storage()`	Creates a default `{"entries": {}, "relations": []}` structure if the file is missing.

Entry Management

save(entry: Entry) -> None

Persists an Entry object. Automatically updates the updated_at timestamp and maps attributes to the storage schema.

get_by_id(entry_id: str) -> Optional[Entry]

Retrieves a single entry by its unique identifier. Returns None if not found.

delete(entry_id: str) -> bool

Removes an entry and all associated relations (cascade delete). Returns True if successful.

Relation Management

Handles the connections between different entries in the graph.

save_relation(relation: Relation)

Records a connection between two entries. Checks for existing duplicates before appending.

get_in_relations(entry_id: str) -> List[Relation]

Returns a list of relations where the specified ID is the destination.