leptos_store/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 web-mech
3
4//! # leptos-store
5//!
6//! Enterprise-grade, type-enforced state management for Leptos.
7//!
8//! This crate provides a structured, SSR-safe state management architecture
9//! inspired by Vuex and Pinia, translated into idiomatic Rust for Leptos.
10//!
11//! ## Core Concepts
12//!
13//! Each store is a **domain module** composed of:
14//!
15//! 1. **State** - Read-only externally, reactive data container
16//! 2. **Getters** - Derived, read-only computed values
17//! 3. **Mutators** - Pure, synchronous state mutations
18//! 4. **Actions** - Synchronous orchestration with side effects
19//! 5. **Async Actions** - Asynchronous orchestration
20//!
21//! ## Mutation Rules
22//!
23//! | Layer | Can Write State | Async | Side Effects |
24//! |-------|-----------------|-------|--------------|
25//! | Components | ❌ | ❌ | ❌ |
26//! | Getters | ❌ | ❌ | ❌ |
27//! | Mutators | ✅ | ❌ | ❌ |
28//! | Actions | ❌ | ❌ | ✅ |
29//! | Async Actions | ❌ | ✅ | ✅ |
30//!
31//! **Only mutators may write state.**
32//!
33//! ## Feature Flags
34//!
35//! | Feature | Default | Description |
36//! |---------|---------|-------------|
37//! | `ssr` | ✅ Yes | Server-side rendering support |
38//! | `hydrate` | ❌ No | SSR hydration with automatic state serialization |
39//! | `csr` | ❌ No | Client-side rendering only |
40//!
41//! ### Choosing Features
42//!
43//! - **CSR only (SPA)**: Use `features = ["csr"]`
44//! - **SSR without hydration**: Use default features (`ssr`)
45//! - **Full SSR with hydration**: Use `ssr` on server, `hydrate` on client
46//!
47//! ### Why is `hydrate` opt-in?
48//!
49//! The `hydrate` feature adds:
50//! - `serde` and `serde_json` for state serialization
51//! - `web-sys` and `wasm-bindgen` for DOM access
52//! - Approximately 50KB to your WASM bundle
53//!
54//! If you don't need state transfer from server to client, you can skip this overhead.
55//!
56//! ## Available Macros
57//!
58//! | Macro | Purpose | Feature |
59//! |-------|---------|---------|
60//! | `define_state!` | Define state structs with default values | - |
61//! | `define_hydratable_state!` | Define state with serde derives | `hydrate` |
62//! | `define_action!` | Define synchronous action structs | - |
63//! | `define_async_action!` | Define async action structs with error types | - |
64//! | `impl_store!` | Implement Store trait for an existing type | - |
65//! | `impl_hydratable_store!` | Implement HydratableStore trait | `hydrate` |
66//! | `store!` | Complete store definition in one macro | - |
67//!
68//! See the [`macros`] module for detailed documentation and examples.
69//!
70//! ## Hydration Support
71//!
72//! When building full SSR applications where state needs to transfer from
73//! server to client, enable the `hydrate` feature:
74//!
75//! ```toml
76//! [dependencies]
77//! leptos-store = { version = "0.1", default-features = false }
78//!
79//! [features]
80//! ssr = ["leptos-store/ssr"]
81//! hydrate = ["leptos-store/hydrate"]
82//! ```
83//!
84//! This enables:
85//! - `HydratableStore` trait for state serialization
86//! - `provide_hydrated_store()` for server-side state embedding
87//! - `use_hydrated_store()` for client-side state recovery
88//!
89//! See the `hydration` module (requires `hydrate` feature) for implementation details.
90//!
91//! ## Example
92//!
93//! ```rust
94//! use leptos::prelude::*;
95//! use leptos_store::prelude::*;
96//!
97//! // Define your state
98//! #[derive(Clone, Debug, Default)]
99//! pub struct CounterState {
100//! pub count: i32,
101//! }
102//!
103//! // Define your store
104//! #[derive(Clone)]
105//! pub struct CounterStore {
106//! state: RwSignal<CounterState>,
107//! }
108//!
109//! impl Store for CounterStore {
110//! type State = CounterState;
111//!
112//! fn state(&self) -> ReadSignal<Self::State> {
113//! self.state.read_only()
114//! }
115//! }
116//!
117//! // Define mutators
118//! impl CounterStore {
119//! pub fn increment(&self) {
120//! self.state.update(|s| s.count += 1);
121//! }
122//!
123//! pub fn decrement(&self) {
124//! self.state.update(|s| s.count -= 1);
125//! }
126//! }
127//! ```
128
129// Enable doc_cfg for docs.rs to show feature requirements
130#![cfg_attr(docsrs, feature(doc_cfg))]
131#![warn(missing_docs)]
132#![warn(clippy::all)]
133#![deny(unsafe_code)]
134
135pub mod r#async;
136pub mod context;
137pub mod macros;
138pub mod store;
139
140#[cfg(feature = "hydrate")]
141pub mod hydration;
142
143pub mod prelude;
144
145pub use prelude::*;