perseus 0.4.2

A lightning-fast frontend web dev platform with full support for SSR and SSG.
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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

#![doc = include_str!("../README.proj.md")]
/*!
## Features

- `translator-fluent` --- enables internationalization using [Fluent](https://projectfluent.org)
- `macros` (default) --- adds support for macros that will make your life much easier
- `dflt_engine` (default) --- adds support for the default engine-side mechanics (you would only not want this in extremely niche use-cases)
- `client_helpers` (default) --- adds useful helpers for managing the browser-side
- `hydrate` --- enables Sycamore's *experimental* hydration system (if you experience odd issues, try disabling this)
- `preload-wasm-on-redirect` --- *experimentally* preloads the Wasm bundle for locale redirections (this only partially works right now)
- `idb-freezing` --- enables utilities for freezing your app's state to IndexedDB in the browser (see the book)
- `live-reload` (default) --- enables reloading the browser automatically when you make changes to your app
- `hsr` (default) --- enables *hot state reloading*, which reloads the state of your app right before you made code changes in development, allowing you to pick up where you left off

## Packages

This is the API documentation for the core `perseus` package, which underlies all Perseus apps. Note that Perseus mostly uses [the book](https://framesurge.sh/perseus/en-US) for
documentation, and this should mostly be used as a secondary reference source. You can also find full usage examples [here](https://github.com/framesurge/perseus/tree/main/examples).
*/

#![deny(missing_docs)]
#![deny(missing_debug_implementations)]
#![recursion_limit = "256"] // TODO Do we need this anymore?

/// Utilities for working with the engine-side, particularly with regards to
/// setting up the entrypoint for your app's build/export/server processes.
#[cfg(engine)]
pub mod engine;
/// Utilities surrounding `ErrorViews` and their management.
pub mod error_views;
pub mod errors;
/// Utilities for internationalization, the process of making your app available
/// in multiple languages.
pub mod i18n;
/// Utilities for working with plugins.
pub mod plugins;
/// Utilities for working with the router. Note that you should only have to use
/// these when waiting for a page transition in normal use-cases.
pub mod router;
/// Utilities for working with the server. These are fairly low-level, and
/// are intended for use by those developing new server integrations.
#[cfg(engine)]
pub mod server;
/// Utilities for working with Perseus' state platform.
pub mod state;
/// Utilities for working with immutable and mutable stores. See
/// [`stores::ImmutableStore`] and [`stores::MutableStore`] for details.
pub mod stores;
/// Utilities for working with templates and state generation. This is by far
/// the module you'll probably access the most.
pub mod template;
/// General utilities that may be useful while building Perseus apps.
pub mod utils;

/// Utilities for initializing the Perseus client.
#[cfg(all(feature = "client-helpers", any(client, doc)))]
pub mod client;
mod init;
mod page_data;
/// Utilities for working with typed paths.
pub mod path;
/// The core of the Perseus browser-side system. This is used on the engine-side
/// as well for rendering.
pub mod reactor;
mod translator;
/// The core of the Perseus state generation system.
#[cfg(engine)]
pub mod turbine;

// The rest of this file is devoted to module structuring
// Re-exports
#[cfg(engine)]
pub use http;
#[cfg(engine)]
pub use http::Request as HttpRequest;

/// All HTTP requests use empty bodies for simplicity of passing them around.
/// They'll never need payloads (value in path requested).
///
/// **Warning:** on the browser-side, this is defined as `()`.
#[cfg(engine)]
pub type Request = HttpRequest<()>;
/// All HTTP requests use empty bodies for simplicity of passing them around.
/// They'll never need payloads (value in path requested).
///
/// **Warning:** on the browser-side, this is defined as `()`.
#[cfg(client)]
pub type Request = ();

#[cfg(feature = "macros")]
pub use perseus_macro::*;

/// Internal utilities for lower-level work.
#[cfg(engine)]
pub mod internal {
    pub use crate::page_data::*;
}
/// Internal utilities for logging. These are just re-exports so that users
/// don't have to have `web_sys` and `wasm_bindgen` to use `web_log!`.
#[cfg(any(client, doc))]
#[doc(hidden)]
pub mod log {
    pub use wasm_bindgen::JsValue;
    pub use web_sys::console::log_1 as log_js_value;
}

/// An alias for `DomNode`, `HydrateNode`, or `SsrNode`, depending on the
/// `hydrate` feature flag and compilation target.
///
/// You **should not** use this in your return types (e.g.
/// `View<PerseusNodeType>`), there you should use a `G: Html` generic.
/// This is intended for `lazy_static!`s and the like, for capsules. See
/// the book and capsule examples for further details.
#[cfg(engine)]
pub type PerseusNodeType = sycamore::web::SsrNode;
/// An alias for `DomNode`, `HydrateNode`, or `SsrNode`, depending on the
/// `hydrate` feature flag and compilation target.
///
/// You **should not** use this in your return types (e.g.
/// `View<PerseusNodeType>`), there you should use a `G: Html` generic.
/// This is intended for `lazy_static!`s and the like, for capsules. See
/// the book and capsule examples for further details.
#[cfg(all(client, not(feature = "hydrate")))]
pub type PerseusNodeType = sycamore::web::DomNode;
/// An alias for `DomNode`, `HydrateNode`, or `SsrNode`, depending on the
/// `hydrate` feature flag and compilation target.
///
/// You **should not** use this in your return types (e.g.
/// `View<PerseusNodeType>`), there you should use a `G: Html` generic.
/// This is intended for `lazy_static!`s and the like, for capsules. See
/// the book and capsule examples for further details.
#[cfg(all(client, feature = "hydrate"))]
pub type PerseusNodeType = sycamore::web::HydrateNode;

/// A series of imports needed by most Perseus apps, in some form. This should
/// be used in conjunction with the Sycamore prelude.
pub mod prelude {
    pub use crate::error_views::ErrorViews;
    // Target-gating doesn't matter, because the prelude is intended to be used all
    // at once
    #[cfg(engine)]
    pub use crate::errors::{BlamedError, ErrorBlame};
    pub use crate::init::*;
    pub use crate::reactor::Reactor;
    pub use crate::state::{BuildPaths, RxResult, RxResultRx, SerdeInfallible, StateGeneratorInfo};
    pub use crate::template::{Capsule, Template};
    pub use sycamore::web::Html;
    pub use sycamore_router::{navigate, navigate_replace};

    #[cfg(engine)]
    pub use crate::utils::{cache_fallible_res, cache_res};
    pub use crate::web_log;
    #[cfg(any(feature = "translator-fluent", feature = "translator-lightweight"))]
    pub use crate::{link, t};
    pub use crate::{PerseusNodeType, Request};
    #[cfg(feature = "macros")]
    pub use perseus_macro::*;
    pub use sycamore_futures::spawn_local_scoped;

    #[cfg(any(client, doc))]
    pub use crate::utils::checkpoint;
}