hyperstack_sdk/
entity.rs

1//! Entity trait for typed HyperStack entities.
2//!
3//! The `Entity` trait is implemented by generated code for each entity type,
4//! providing type-safe access to HyperStack views.
5
6use serde::{de::DeserializeOwned, Serialize};
7
8/// Marker trait for HyperStack entities.
9///
10/// This trait is implemented by generated code (via `hyperstack sdk create rust`)
11/// for each entity type defined in a HyperStack spec.
12///
13/// # Example (Generated Code)
14///
15/// ```ignore
16/// pub struct PumpfunTokenEntity;
17///
18/// impl Entity for PumpfunTokenEntity {
19///     type Data = PumpfunToken;
20///     
21///     const NAME: &'static str = "PumpfunToken";
22///     
23///     fn state_view() -> &'static str { "PumpfunToken/state" }
24///     fn list_view() -> &'static str { "PumpfunToken/list" }
25///     fn kv_view() -> &'static str { "PumpfunToken/kv" }
26/// }
27/// ```
28///
29/// # Usage
30///
31/// ```ignore
32/// use hyperstack_sdk::HyperStack;
33/// use my_stack::PumpfunTokenEntity;
34///
35/// let hs = HyperStack::connect("wss://example.com").await?;
36/// let token = hs.get::<PumpfunTokenEntity>("mint_address").await;
37/// ```
38pub trait Entity: Sized + Send + Sync + 'static {
39    /// The data type this entity deserializes to.
40    ///
41    /// This is the struct containing all entity fields (id, info, trading, etc.).
42    type Data: Serialize + DeserializeOwned + Clone + Send + Sync + 'static;
43
44    /// Entity name (e.g., "PumpfunToken", "SettlementGame").
45    ///
46    /// This matches the entity name defined in the HyperStack spec.
47    const NAME: &'static str;
48
49    /// View path for single-entity state subscriptions.
50    ///
51    /// Returns a path like "EntityName/state" for subscribing to
52    /// a single entity's complete state by key.
53    fn state_view() -> &'static str;
54
55    /// View path for list subscriptions.
56    ///
57    /// Returns a path like "EntityName/list" for subscribing to
58    /// all entities of this type.
59    fn list_view() -> &'static str;
60
61    /// View path for key-value lookups.
62    ///
63    /// Returns a path like "EntityName/kv" for subscribing to
64    /// specific entities by key with efficient updates.
65    fn kv_view() -> &'static str;
66}
67
68/// Optional trait for entities that support server-side filtering.
69///
70/// Implement this trait to enable filtered list queries.
71pub trait Filterable: Entity {
72    /// Filter configuration type for this entity.
73    type Filter: Default + Clone + Send + Sync;
74
75    /// Convert filter to query parameters.
76    fn filter_to_params(filter: &Self::Filter) -> std::collections::HashMap<String, String>;
77}
hyperstack_sdk/entity.rs

hyperstack_sdk/
entity.rs
