docs_search/lib.rs
1//! docs-search: the client-side search index for docs sites
2//! (docs-core extension program, `SPEC.md` REQ-Q).
3//!
4//! A serialized index is a single binary blob: an FST term dictionary
5//! whose values are offsets into a postings area of (doc, tf) pair
6//! lists, a document-length table for BM25, and - behind the `vectors`
7//! feature - a quantized-vector section for cosine nearest-neighbor
8//! queries. The whole API is bytes-in/bytes-out, so the same artifact
9//! serves a native compiler writing it and a browser runtime (wasm32)
10//! querying it.
11//!
12//! ```
13//! use docs_search::{Index, IndexBuilder};
14//!
15//! let mut b = IndexBuilder::new();
16//! b.add_doc("the quick brown fox");
17//! b.add_doc("the lazy dog");
18//! let bytes = b.build().unwrap();
19//!
20//! let idx = Index::from_bytes(&bytes).unwrap();
21//! let hits = idx.query("fox", 10);
22//! assert_eq!(hits.len(), 1);
23//! assert_eq!(hits[0].doc, 0);
24//! ```
25//!
26//! # Scope (0.2, honest)
27//!
28//! In: boolean AND queries, full BM25 ranking over true term-frequency
29//! postings (the 0.1 unit-tf placeholder retired), deterministic
30//! serialization, total decoding, and - behind the `vectors` feature -
31//! fixed max-abs i8 quantization with an approximate-cosine query.
32//! Out: phrase queries, field weights, positional postings, and any
33//! learned-model codec (the quantization scheme is fixed arithmetic, not
34//! a model).
35//!
36//! # Layer
37//!
38//! L0 - leaf. Zero estate-internal dependencies; external floor is
39//! `fst` and `thiserror` (`roaring` left with the bitmap postings in
40//! 0.2; pair lists need nothing beyond the core).
41
42#![deny(missing_docs)]
43#![forbid(unsafe_code)]
44
45mod error;
46mod format;
47mod index;
48
49pub use error::IndexError;
50pub use index::{Hit, Index, IndexBuilder};
51
52/// The crate's version, for callers that report it.
53pub const VERSION: &str = env!("CARGO_PKG_VERSION");