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

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

- `translator-fluent` -- enables internationalization using [Fluent](https://projectfluent.org)
- `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

The remaining features are used internally by the other Perseus packages, and enabling them manually in your project will very likely wreak havoc unless you seriously know what you're doing!

- `tinker-plugins` -- makes tinker plugins be registered
- `server-side` -- enables various functions only used on the server-side (minimizes the client-side bundle)
- `standalone` -- makes Perseus able to be run as a standalone binary by changing some minor internal defaults

## Packages

This is the API documentation for the core `perseus` package, which underlies all Perseus apps. Note that Perseus mostly uses [the book](https://arctic-hen7.github.io/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/arctic-hen7/perseus/tree/main/examples).
*/

#![deny(missing_docs)]
// #![deny(missing_debug_implementations)] // TODO Pending sycamore-rs/sycamore#412
#![forbid(unsafe_code)]
#![recursion_limit = "256"] // TODO Do we need this anymore?

pub mod errors;
/// Utilities for working with plugins.
pub mod plugins;
/// Utilities for working with Perseus' state platform.
pub mod state;
/// Utilities for working with immutable and mutable stores. You can learn more about these in the book.
pub mod stores;

#[cfg(not(target_arch = "wasm32"))]
mod build;
#[cfg(all(feature = "client-helpers", target_arch = "wasm32"))]
mod client;
#[cfg(all(feature = "builder", not(target_arch = "wasm32")))]
mod engine;
mod error_pages;
#[cfg(not(target_arch = "wasm32"))]
mod export;
mod i18n;
mod init;
mod macros;
mod page_data;
mod router;
#[cfg(not(target_arch = "wasm32"))]
mod server;
#[cfg(target_arch = "wasm32")]
mod shell;
mod template;
mod translator;
mod utils;

// The rest of this file is devoted to module structuring
// Re-exports
#[cfg(not(target_arch = "wasm32"))]
pub use http;
#[cfg(not(target_arch = "wasm32"))]
pub use http::Request as HttpRequest;
pub use sycamore_futures::spawn_local_scoped;
/// All HTTP requests use empty bodies for simplicity of passing them around. They'll never need payloads (value in path requested).
#[cfg(not(target_arch = "wasm32"))]
pub type Request = HttpRequest<()>;
#[cfg(all(feature = "client-helpers", target_arch = "wasm32"))]
pub use client::{run_client, ClientReturn};
#[cfg(feature = "macros")]
pub use perseus_macro::{
    amalgamate_states, browser, browser_main, build_paths, build_state, engine, engine_main,
    global_build_state, head, main, main_export, make_rx, request_state, set_headers,
    should_revalidate, template, template_rx, test,
};
pub use sycamore::prelude::{DomNode, Html, HydrateNode, SsrNode};
pub use sycamore_router::{navigate, navigate_replace, Route}; // TODO Should we be exporting `Route` anymore?

// TODO Restructure everything here (needs to stay the same until v0.4.0 though)

// Items that should be available at the root (this should be nearly everything used in a typical Perseus app)
pub use crate::error_pages::ErrorPages;
pub use crate::errors::{ErrorCause, GenericErrorWithCause};
pub use crate::page_data::PageData;
pub use crate::plugins::{Plugin, PluginAction, Plugins};
#[cfg(target_arch = "wasm32")]
pub use crate::shell::checkpoint;
#[cfg(not(target_arch = "wasm32"))]
pub use crate::template::{HeadFn, States};
pub use crate::template::{RenderFnResult, RenderFnResultWithCause, Template};
#[cfg(not(target_arch = "wasm32"))]
pub use crate::utils::{cache_fallible_res, cache_res};
// Everything in the `init.rs` file should be available at the top-level for convenience
pub use crate::init::*;
/// Utilities for developing templates, particularly including return types for various rendering strategies.
pub mod templates {
    pub use crate::errors::{ErrorCause, GenericErrorWithCause};
    pub use crate::router::{RouterLoadState, RouterState};
    pub use crate::template::*;
}
/// Utilities for building an app.
#[cfg(all(feature = "builder", not(target_arch = "wasm32")))]
pub mod builder {
    pub use crate::engine::*;
}
/// A series of exports that should be unnecessary for nearly all uses of Perseus. These are used principally in developing alternative
/// engines.
pub mod internal {
    /// Internal utilities for working with internationalization.
    pub mod i18n {
        pub use crate::i18n::*;
        #[doc(hidden)]
        pub use crate::macros::DFLT_TRANSLATIONS_DIR;
        pub use crate::translator::*;
    }
    /// Internal utilities for working with the serving process. These will be useful for building integrations for hosting Perseus
    /// on different platforms.
    #[cfg(not(target_arch = "wasm32"))]
    pub mod serve {
        pub use crate::server::*;
    }
    /// Internal utilities for working with the Perseus router.
    pub mod router {
        pub use crate::router::*;
    }
    /// Internal utilities for working with error pages.
    pub mod error_pages {
        pub use crate::error_pages::*;
    }
    /// Internal utilities for working with the app shell.
    #[cfg(target_arch = "wasm32")]
    pub mod shell {
        pub use crate::shell::*;
    }
    /// Internal utilities for building apps at a very low level.
    #[cfg(not(target_arch = "wasm32"))]
    pub mod build {
        pub use crate::build::*;
    }
    /// Internal utilities for exporting apps at a very low level.
    #[cfg(not(target_arch = "wasm32"))]
    pub mod export {
        pub use crate::export::*;
    }
    #[cfg(target_arch = "wasm32")]
    pub use crate::utils::get_path_prefix_client;
    #[cfg(not(target_arch = "wasm32"))]
    pub use crate::utils::get_path_prefix_server;
    /// 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(target_arch = "wasm32")]
    pub mod log {
        pub use wasm_bindgen::JsValue;
        pub use web_sys::console::log_1 as log_js_value;
    }
}