kora_doc/
lib.rs

1//! # kora-doc
2//!
3//! Document layer that turns Kora from a key-value cache engine into a
4//! JSON-native document database. Documents are stored in a compact binary
5//! packed format, queried via a WHERE expression parser, and indexed through
6//! four secondary index types (hash, sorted, array, unique).
7//!
8//! ## Architecture
9//!
10//! A JSON document passes through a pipeline of transformations before it
11//! reaches storage:
12//!
13//! 1. **Decomposition** ([`decompose`]) -- a JSON object is recursively walked,
14//!    each leaf field is assigned a numeric [`FieldId`](registry::FieldId) via
15//!    the [`IdRegistry`](registry::IdRegistry), string values are
16//!    dictionary-encoded when their field cardinality is low, and the result is
17//!    assembled into a [`PackedDoc`](packed::PackedDoc).
18//!
19//! 2. **Packed encoding** ([`packed`]) -- fields are stored in a flat binary
20//!    buffer with an offset table sorted by field ID, enabling O(log F)
21//!    single-field reads via binary search.
22//!
23//! 3. **Recomposition** ([`recompose`]) -- the inverse of decomposition,
24//!    rebuilding a `serde_json::Value` from packed bytes, dictionary lookups,
25//!    and registry path resolution. Supports full reconstruction or
26//!    field-level projection.
27//!
28//! ## Key Modules
29//!
30//! | Module | Purpose |
31//! |---|---|
32//! | [`packed`] | Binary packed document format and builder |
33//! | [`registry`] | Integer-keyed ID mapping for collections, fields, and docs |
34//! | [`dictionary`] | Dictionary encoding for low-cardinality string values |
35//! | [`decompose`] | JSON to packed document conversion |
36//! | [`recompose`] | Packed document to JSON reconstruction |
37//! | [`engine`] | Collection CRUD, index maintenance, and query execution |
38//! | [`expr`] | WHERE clause recursive-descent parser |
39//! | [`index`] | Hash, sorted, array, and unique secondary indexes |
40//! | [`collection`] | Collection metadata and configuration |
41//! | [`key`] | Binary key encoding for storage and index records |
42
43#![warn(clippy::all)]
44#![warn(missing_docs)]
45
46pub mod collection;
47pub mod decompose;
48pub mod dictionary;
49pub mod engine;
50pub mod expr;
51pub mod index;
52pub mod key;
53pub mod packed;
54pub mod recompose;
55pub mod registry;
56
57pub use collection::{Collection, CollectionConfig, CollectionError, CompressionProfile};
58pub use decompose::{DecomposeError, Decomposer};
59pub use dictionary::{DictionaryError, StoredValue, ValueDictionary, ValueDictionaryConfig};
60pub use engine::{
61    CollectionInfo, DictionaryFieldInfo, DictionaryInfo, DocEngine, DocError, DocMutation,
62    InsertResult, SetResult, StorageInfo,
63};
64pub use expr::{Expr, ExprError, ExprValue};
65pub use index::{hash32, CollectionIndexes, IndexConfig, IndexError, IndexType};
66pub use key::{
67    decode_cdc_event_key, decode_cold_doc_key, decode_collection_key, decode_compound_index_key,
68    decode_doc_key, decode_hashed_bucket_key, decode_sorted_index_key, encode_cdc_event_key,
69    encode_cold_doc_key, encode_collection_key, encode_compound_index_key, encode_doc_key,
70    encode_hashed_bucket_key, encode_sorted_index_key, KeyDecodeError, KeyTag,
71};
72pub use packed::{FieldValue, PackedDoc, PackedDocBuilder, PackedDocError, PackedDocIter};
73pub use recompose::{RecomposeError, Recomposer};
74pub use registry::{
75    CollectionId, DocId, FieldId, IdRegistry, RegistryError, RegistrySegment, RegistrySegmentRef,
76};
kora_doc/lib.rs

kora_doc/
lib.rs
