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 [`fs-transaction`](fs_transaction), a layer *down*:
35//! it knows nothing about documents, so it is a dependency of this crate rather
36//! than a consumer of it. [`fs`] re-exports its port.
37//!
38//! [`ReadStorage`]: prov_graph::fs::ReadStorage
39//! [`IdIndex`]: prov_graph::index::IdIndex
40
41// `edit` synthesizes a metadata block for a document that has none, and picks
42// the archetype by format feature — so at least one backend must be compiled
43// in here for the same reason it must be in `prov-graph`.
44#[cfg(not(any(
45 feature = "yaml",
46 feature = "json",
47 feature = "toml",
48 feature = "fig-lang"
49)))]
50compile_error!(
51 "prov-store needs at least one metadata-format feature enabled: \
52 `yaml` (the default), `json`, `toml`, or `fig-lang`. \
53 You have disabled the default feature without selecting a replacement."
54);
55
56pub mod edit;
57pub mod fs;
58pub mod index;
59
60pub use edit::MetaEditor;
61pub use fs::{Capabilities, Durability, InMemoryFs, Storage, SyncGuarantee};
62pub use index::{FileIndex, InMemoryIndex, IndexStore, Rebase};