prov_store/lib.rs
1//! # prov-store
2//!
3//! The write surface over a [prov](https://docs.rs/prov) workspace: the half of
4//! each storage port that changes something.
5//!
6//! ## What this crate is for
7//!
8//! [`prov_graph`] is the read core — it declares [`ReadStorage`] and
9//! [`IdIndex`], and every traversal in it is generic over exactly those two.
10//! This crate declares their other halves — [`Storage`] and [`IndexStore`] —
11//! plus the metadata [`editor`](edit) that rewrites a document's frontmatter in
12//! place.
13//!
14//! The two live in separate crates so that the read core's guarantee is
15//! structural rather than editorial. A consumer that must not modify a
16//! workspace — a language server, a static renderer, a browser viewer — depends
17//! on `prov-graph` alone and *cannot* write, because the vocabulary for writing
18//! is not in its dependency graph at all. Not a feature flag it might have left
19//! on, not a convention review has to police: the functions do not exist.
20//!
21//! ## The shape of it
22//!
23//! - [`fs`] — [`Storage`], the write half of the filesystem port, and the
24//! durability vocabulary a backend answers with ([`Capabilities`],
25//! [`Durability`], [`SyncGuarantee`]). Also [`InMemoryFs`], a writable
26//! in-process backend for tests and sandboxes.
27//! - [`edit`] — format-preserving, comment-preserving edits to a document's
28//! embedded metadata, whatever carries it.
29//! - [`index`] — [`IndexStore`], the [`Rebase`] seam a pending change set
30//! answers through, and the two concrete registries ([`InMemoryIndex`] and
31//! the registry-document-backed [`FileIndex`]).
32//!
33//! The crash-atomic staging that drives these — the change set and its
34//! write-ahead journal — is `prov-transaction`, a layer up.
35//!
36//! [`ReadStorage`]: prov_graph::fs::ReadStorage
37//! [`IdIndex`]: prov_graph::index::IdIndex
38
39// `edit` synthesizes a metadata block for a document that has none, and picks
40// the archetype by format feature — so at least one backend must be compiled
41// in here for the same reason it must be in `prov-graph`.
42#[cfg(not(any(
43 feature = "yaml",
44 feature = "json",
45 feature = "toml",
46 feature = "fig-lang"
47)))]
48compile_error!(
49 "prov-store needs at least one metadata-format feature enabled: \
50 `yaml` (the default), `json`, `toml`, or `fig-lang`. \
51 You have disabled the default feature without selecting a replacement."
52);
53
54pub mod edit;
55pub mod fs;
56pub mod index;
57
58pub use edit::MetaEditor;
59pub use fs::{Capabilities, Durability, InMemoryFs, Storage, SyncGuarantee};
60pub use index::{FileIndex, InMemoryIndex, IndexStore, Rebase};