surrealism_types/lib.rs
1//! # surrealism-types
2//!
3//! A language-agnostic serialization framework for WebAssembly (WASM) guest-host communication.
4//!
5//! ## Overview
6//!
7//! This crate provides the core types and traits for transferring data across WASM boundaries
8//! in a way that can be implemented by any language that compiles to WebAssembly. It defines:
9//!
10//! - A binary serialization protocol ([`Serializable`](serialize::Serializable))
11//! - Memory transfer abstractions ([`Transfer`](transfer::Transfer),
12//! [`AsyncTransfer`](transfer::AsyncTransfer))
13//! - Memory management interfaces ([`MemoryController`](controller::MemoryController),
14//! [`AsyncMemoryController`](controller::AsyncMemoryController))
15//! - Function argument marshalling ([`Args`](args::Args))
16//!
17//! ## Feature Flags
18//!
19//! - `host`: Enables async traits for host-side (runtime) implementations. Without this flag, all
20//! operations are synchronous, suitable for WASM guest modules.
21//!
22//! ## Dual-Mode Architecture
23//!
24//! The crate supports both synchronous (guest) and asynchronous (host) operations:
25//!
26//! - **Guest mode** (default): Synchronous traits for WASM module code
27//! - **Host mode** (`host` feature): Async traits for runtime/Wasmtime code
28//!
29//! This allows the same types to work efficiently on both sides of the WASM boundary.
30//!
31//! ## Example
32//!
33//! ```rust,ignore
34//! use surrealism_types::{Serializable, Transfer, MemoryController};
35//!
36//! // Guest side: Transfer a string to host
37//! fn send_string(s: String, controller: &mut dyn MemoryController) -> u32 {
38//! let ptr = s.transfer(controller).unwrap();
39//! *ptr
40//! }
41//!
42//! // Guest side: Receive a string from host
43//! fn receive_string(ptr: u32, controller: &mut dyn MemoryController) -> String {
44//! String::receive(ptr.into(), controller).unwrap()
45//! }
46//! ```
47/// Wrapper type for function arguments that implement [`surrealdb_types::SurrealValue`].
48pub mod arg;
49
50/// Traits for marshalling function arguments to and from [`surrealdb_types::Value`] vectors.
51pub mod args;
52
53/// Memory management abstractions for WASM linear memory allocation and deallocation.
54pub mod controller;
55
56/// Error handling utilities for adding context to errors.
57pub mod err;
58
59/// Core serialization traits and implementations for the binary wire format.
60pub mod serialize;
61
62/// Memory transfer traits for moving data across WASM boundaries.
63pub mod transfer;