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/// }
26/// ```
27///
28/// # Usage
29///
30/// ```ignore
31/// use hyperstack_sdk::HyperStack;
32/// use my_stack::PumpfunTokenEntity;
33///
34/// let hs = HyperStack::connect("wss://example.com").await?;
35/// let token = hs.get::<PumpfunTokenEntity>("mint_address").await;
36/// ```
37pub trait Entity: Sized + Send + Sync + 'static {
38    /// The data type this entity deserializes to.
39    ///
40    /// This is the struct containing all entity fields (id, info, trading, etc.).
41    type Data: Serialize + DeserializeOwned + Clone + Send + Sync + 'static;
42
43    /// Entity name (e.g., "PumpfunToken", "SettlementGame").
44    ///
45    /// This matches the entity name defined in the HyperStack spec.
46    const NAME: &'static str;
47
48    /// View path for single-entity state subscriptions.
49    ///
50    /// Returns a path like "EntityName/state" for subscribing to
51    /// a single entity's complete state by key.
52    fn state_view() -> &'static str;
53
54    /// View path for list subscriptions.
55    ///
56    /// Returns a path like "EntityName/list" for subscribing to
57    /// all entities of this type.
58    fn list_view() -> &'static str;
59}
60
61/// Optional trait for entities that support server-side filtering.
62///
63/// Implement this trait to enable filtered list queries.
64pub trait Filterable: Entity {
65    /// Filter configuration type for this entity.
66    type Filter: Default + Clone + Send + Sync;
67
68    /// Convert filter to query parameters.
69    fn filter_to_params(filter: &Self::Filter) -> std::collections::HashMap<String, String>;
70}
71
72/// Trait that maps a Data type back to its Entity type.
73///
74/// This enables type inference from return type instead of requiring turbofish syntax.
75///
76/// # Example
77///
78/// ```ignore
79/// // With EntityData implemented:
80/// let token: PumpfunToken = hs.get_data("mint").await?;
81///
82/// // Without EntityData (original API still works):
83/// let token = hs.get::<PumpfunTokenEntity>("mint").await;
84/// ```
85///
86/// The generated SDK code automatically implements this trait for each entity's data type.
87pub trait EntityData: Serialize + DeserializeOwned + Clone + Send + Sync + 'static {
88    /// The Entity type that produces this Data type.
89    type Entity: Entity<Data = Self>;
90}
hyperstack_sdk/entity.rs

hyperstack_sdk/
entity.rs
