vibe_ready/lib.rs
1//! Project foundations for vibe-coding applications.
2//!
3//! `vibe-ready` provides a small runtime layer for applications that need a
4//! ready-to-use engine, async task execution, scheduled work, structured
5//! logging, and a key-value store without assembling those pieces from scratch.
6//! Most applications start by building a [`VibeEngineConfig`], creating a
7//! [`VibeEngine`], and then using the engine for tasks, callbacks, and storage.
8//!
9//! # Examples
10//!
11//! ```no_run
12//! use vibe_ready::{VibeEngine, VibeEngineConfig, VibePlatformType, VibeResult};
13//!
14//! fn main() -> VibeResult<()> {
15//! let config = VibeEngineConfig::builder()
16//! .platform(VibePlatformType::MacOS)
17//! .app_name("demo-app")
18//! .namespace("examples")
19//! .build();
20//!
21//! let engine = VibeEngine::create(config)?;
22//! engine.store().set_str("status", "ready")?;
23//! engine.destroy_with_timeout(std::time::Duration::from_secs(2))?;
24//! Ok(())
25//! }
26//! ```
27
28pub(crate) mod api;
29pub(crate) mod log;
30pub(crate) mod net;
31pub mod platform;
32pub(crate) mod status;
33pub(crate) mod store;
34pub(crate) mod utils;
35
36/// Build-time capabilities available in the current crate build.
37pub use api::capabilities::VibeCapabilities;
38/// Connection state reported by the SDK runtime.
39pub use api::connection_status::VibeConnectionStatus;
40/// Main entry point for creating and driving a vibe-ready runtime.
41pub use api::engine::VibeEngine;
42/// Lifecycle state of a [`VibeEngine`].
43pub use api::engine::VibeEngineState;
44/// Application identity used to isolate SDK data on disk.
45pub use api::engine_config::VibeAppConfig;
46/// Backup behavior for SDK managed storage.
47pub use api::engine_config::VibeBackupStrategy;
48/// Configuration used to create a [`VibeEngine`].
49pub use api::engine_config::VibeEngineConfig;
50/// Builder for [`VibeEngineConfig`].
51pub use api::engine_config::VibeEngineConfigBuilder;
52/// Log backend selected for SDK log persistence.
53pub use api::engine_config::VibeLogBackend;
54/// Logging behavior used by the SDK.
55pub use api::engine_config::VibeLogConfig;
56/// Runtime sizing and queue capacity used by [`VibeEngine`].
57pub use api::engine_config::VibeRuntimeConfig;
58/// Store backend selected for SDK persistence.
59pub use api::engine_config::VibeStoreBackend;
60/// Storage behavior used by the SDK.
61pub use api::engine_config::VibeStoreConfig;
62/// Low-level context shared by engine services.
63pub use api::engine_context::VibeEngineContext;
64/// Error type returned by vibe-ready operations.
65pub use api::engine_error::VibeEngineError;
66/// Stable error code used by [`VibeError`].
67pub use api::engine_error::VibeEngineErrorCode as VibeErrorCode;
68/// High-level error category returned by [`VibeEngineError`].
69pub use api::engine_error::VibeErrorKind;
70/// Callback executor returned by [`VibeEngineExecutor::callback`].
71pub use api::engine_executor::VibeCallbackExecutor;
72/// Task executor used internally by [`VibeEngine`] and exposed for advanced integrations.
73pub use api::engine_executor::VibeEngineExecutor;
74/// Platform identifier used by [`VibeEngineConfig`].
75pub use api::platform_type::VibePlatformType;
76/// Cooperative cancellation token consumed by scheduled tasks.
77pub use api::scheduler::VibeCancellationToken;
78/// Handle returned by `VibeEngine::schedule_after` / `schedule_every` / `post_with_priority`.
79pub use api::scheduler::VibeTaskHandle;
80/// Snapshot of a scheduler-tracked task.
81pub use api::scheduler::VibeTaskInfo;
82/// Origin category of a scheduler-tracked task.
83pub use api::scheduler::VibeTaskKind;
84/// Diagnostic panel listing live scheduler tasks.
85pub use api::scheduler::VibeTaskPanel;
86/// Priority lane used by the task scheduler.
87pub use api::scheduler::VibeTaskPriority;
88/// Lifecycle state of a scheduler-tracked task.
89pub use api::scheduler::VibeTaskState;
90/// Log listener callback type.
91pub use log::log_def::LogListener as VibeLogListener;
92/// Log entry delivered to log listeners.
93pub use log::log_def::VibeLogInfo;
94/// Standard log field for error codes.
95pub use log::log_def::CODE_STR;
96/// Standard log field for descriptions.
97pub use log::log_def::DESC;
98/// Standard log field for return values.
99pub use log::log_def::RET_STR;
100/// Log severity used by the SDK.
101pub use log::log_level::LogLevel as VibeLogLevel;
102/// Low-level logger used by the engine log subsystem.
103pub use log::logger::VibeLogger;
104/// HTTP client foundation for outbound requests (requires `net-http`).
105#[cfg(feature = "net-http")]
106pub use net::VibeHttpClient;
107/// Builder for [`VibeHttpClient`] (requires `net-http`).
108#[cfg(feature = "net-http")]
109pub use net::VibeHttpClientBuilder;
110/// HTTP method used by [`VibeHttpClient`] (requires `net-http`).
111#[cfg(feature = "net-http")]
112pub use net::VibeHttpMethod;
113/// Configurable HTTP request (requires `net-http`).
114#[cfg(feature = "net-http")]
115pub use net::VibeHttpRequest;
116/// HTTP response (requires `net-http`).
117#[cfg(feature = "net-http")]
118pub use net::VibeHttpResponse;
119/// Retry and backoff policy for HTTP requests (requires `net-http`).
120#[cfg(feature = "net-http")]
121pub use net::VibeRetryPolicy;
122/// Runtime status manager exposed for advanced integrations.
123pub use status::status_manager::VibeStatusManager;
124/// Database client exposed for advanced integrations.
125pub use store::db::db_client::VibeDbClient;
126/// Database error category used by storage backends.
127pub use store::db::enums::db_error::DbError;
128/// Database error details exposed for advanced integrations.
129pub use store::db::enums::db_error::VibeDbErrorInfo;
130/// High-level value accepted by the SDK key-value store.
131pub use store::db::tables::key_val::VibeKvValue;
132/// Key-value row returned by advanced database APIs.
133pub use store::db::tables::key_val::VibeTableKeyVal;
134/// Bucket-scoped view of [`VibeKvStore`].
135pub use store::kv_store::VibeKvBucket;
136/// Change notification dispatched to KV listeners.
137pub use store::kv_store::VibeKvChange;
138/// Variant of [`VibeKvChange`] indicating whether a key was set or removed.
139pub use store::kv_store::VibeKvChangeKind;
140/// Cancellation handle returned by `VibeKvStore::on_change`.
141pub use store::kv_store::VibeKvListenerId;
142/// High-level key-value store facade.
143pub use store::kv_store::VibeKvStore;
144/// Buffered transaction handle used inside `VibeKvStore::transaction`.
145pub use store::kv_store::VibeKvTx;
146
147#[doc(hidden)]
148pub use log::logger_macro::on_log as __vibe_internal_log_on_log;
149
150// Re-export `serde_json` under a hidden alias so the exported `log_*!` (and JSON
151// helper) macros can reference it through `$crate` instead of the caller's crate
152// scope. Without this, every downstream crate would be forced to declare
153// `serde_json` as a direct dependency just to invoke the macros. This alias is an
154// internal implementation detail, not public API.
155#[doc(hidden)]
156pub use serde_json as __serde_json;
157
158/// Result alias used by vibe-ready public APIs.
159pub type VibeResult<T> = Result<T, VibeEngineError>;
160
161/// Short alias for [`VibeEngineError`].
162pub type VibeError = VibeEngineError;
163
164/// Common imports for applications using vibe-ready.
165pub mod prelude {
166 pub use crate::{
167 DbError, VibeAppConfig, VibeBackupStrategy, VibeCallbackExecutor, VibeCancellationToken,
168 VibeCapabilities, VibeConnectionStatus, VibeEngine, VibeEngineConfig,
169 VibeEngineConfigBuilder, VibeEngineContext, VibeEngineError, VibeEngineExecutor,
170 VibeEngineState, VibeError, VibeErrorCode, VibeErrorKind, VibeKvBucket, VibeKvChange,
171 VibeKvChangeKind, VibeKvListenerId, VibeKvStore, VibeKvTx, VibeKvValue, VibeLogBackend,
172 VibeLogConfig, VibeLogInfo, VibeLogLevel, VibeLogListener, VibeLogger, VibePlatformType,
173 VibeResult, VibeRuntimeConfig, VibeStoreBackend, VibeStoreConfig, VibeTableKeyVal,
174 VibeTaskHandle, VibeTaskInfo, VibeTaskKind, VibeTaskPanel, VibeTaskPriority, VibeTaskState,
175 };
176
177 #[cfg(feature = "net-http")]
178 pub use crate::{
179 VibeHttpClient, VibeHttpClientBuilder, VibeHttpMethod, VibeHttpRequest, VibeHttpResponse,
180 VibeRetryPolicy,
181 };
182}