cp-ast-json 0.1.3

Lossless JSON serialization boundary for cp-ast-core AST
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

//! Lossless JSON serialization for `cp-ast-core` AST documents.
//!
//! Provides full-snapshot JSON roundtrip that preserves arena structure,
//! tombstones, IDs, counters, and ordering through Rust → JS → Rust cycles.
//!
//! Use [`serialize_ast`] and [`deserialize_ast`] for complete documents, or
//! [`serialize_ast_compact`] when byte size matters. Editor integrations can
//! serialize actions with [`serialize_action`] / [`deserialize_action`] and
//! serialize UI projections with [`serialize_projection`].
//!
//! # Example
//!
//! ```
//! use cp_ast_core::operation::AstEngine;
//! use cp_ast_json::{deserialize_ast, serialize_ast};
//!
//! let engine = AstEngine::new();
//! let json = serialize_ast(&engine).expect("serialize");
//! let restored = deserialize_ast(&json).expect("deserialize");
//!
//! assert_eq!(restored.structure.root(), engine.structure.root());
//! ```
//!
//! # Schema Notes
//!
//! IDs are encoded as decimal strings so JavaScript callers do not lose integer
//! precision. The top-level JSON document is versioned with
//! [`dto::CURRENT_SCHEMA_VERSION`].

/// DTO types that define the stable JSON schema.
pub mod dto;
/// Error type returned by JSON conversion functions.
pub mod error;
mod from_dto;
mod to_dto;

mod action_dto;
mod projection_dto;
/// Compact share-link encoding helpers.
pub mod share_state;

pub use dto::AstDocumentEnvelope;
pub use error::ConversionError;

pub use action_dto::{deserialize_action, serialize_action};
pub use projection_dto::serialize_projection;
pub use share_state::{decode_share_state_json, deserialize_share_state, encode_share_state_json};

use cp_ast_core::operation::AstEngine;

/// Serialize an `AstEngine` to a JSON string.
///
/// Wraps in a versioned envelope with `schema_version`.
///
/// # Errors
/// Returns `ConversionError::Json` if JSON serialization fails.
pub fn serialize_ast(engine: &AstEngine) -> Result<String, ConversionError> {
    let envelope = to_dto::engine_to_envelope(engine);
    serde_json::to_string_pretty(&envelope).map_err(ConversionError::from)
}

/// Serialize an `AstEngine` to a compact JSON string.
///
/// This is intended for transport-oriented use cases such as share links.
///
/// # Errors
/// Returns `ConversionError::Json` if JSON serialization fails.
pub fn serialize_ast_compact(engine: &AstEngine) -> Result<String, ConversionError> {
    let envelope = to_dto::engine_to_envelope(engine);
    serde_json::to_string(&envelope).map_err(ConversionError::from)
}

/// Deserialize an `AstEngine` from a JSON string.
///
/// Validates schema version and arena consistency.
///
/// # Errors
/// Returns `ConversionError` if JSON is invalid, version unsupported,
/// or arena data is inconsistent.
pub fn deserialize_ast(json: &str) -> Result<AstEngine, ConversionError> {
    let envelope: AstDocumentEnvelope = serde_json::from_str(json)?;
    from_dto::envelope_to_engine(envelope)
}