plexus_client/decode.rs
1//! The macro-free typed path: a transport's wire items, typed by hand.
2//!
3//! A generated client builds its streams with [`MethodStream::call`] and
4//! [`call_one`](crate::call_one). These are the same decoding for a caller
5//! holding a raw [`ItemStream`] — a test, a tool that reads a stream the
6//! macro did not generate a client for — with the item type spelled at the
7//! call site:
8//!
9//! ```
10//! use futures::TryStreamExt;
11//! use plexus_client::{decode, MemoryTransport, MethodRef, Transport};
12//!
13//! #[derive(serde::Serialize, serde::Deserialize, Debug, PartialEq)]
14//! struct Tick { n: u32 }
15//!
16//! const COUNT: MethodRef = MethodRef::new("demo", "count");
17//! let t = MemoryTransport::new().script_events(COUNT, &[Tick { n: 1 }, Tick { n: 2 }]);
18//!
19//! let ticks: Vec<Tick> = futures::executor::block_on(
20//! decode::<Tick>(t.call(COUNT, serde_json::json!({}))).try_collect(),
21//! )
22//! .unwrap();
23//! assert_eq!(ticks, vec![Tick { n: 1 }, Tick { n: 2 }]);
24//! ```
25//!
26//! The decoding table is [`method_stream`](crate::method_stream)'s.
27
28use serde::de::DeserializeOwned;
29
30use crate::envelope::RawItem;
31use crate::method_stream::{plain, untagged, MethodStream, WithProgress};
32use crate::transport::{ItemStream, RawItemStream};
33
34/// A transport's [`StreamItem`](crate::StreamItem)s as a typed call reads
35/// them ([`RawItem`]s), each content the `Value` it carries.
36fn raw(items: ItemStream<'_>) -> RawItemStream<'_> {
37 use futures_util::StreamExt;
38 Box::pin(items.map(|item| item.map(RawItem::from)))
39}
40
41/// [`decode`] on a typed call's items (PERF.115-36): each data item's
42/// content decoded straight from the wire's JSON into `I`, never into a
43/// `Value` first — what a generated client reads, on
44/// [`Transport::call_raw`](crate::Transport::call_raw)'s items. A decode
45/// error says what [`decode`] says of the same content.
46pub fn decode_raw<'a, I>(items: RawItemStream<'a>) -> MethodStream<'a, I>
47where
48 I: DeserializeOwned,
49{
50 untagged(items, plain::<I>())
51}
52
53/// A plain-`T` method's items: each data frame's `content` decodes as `I`;
54/// progress frames are dropped. The stream's aggregate is `I` itself
55/// ([`MethodStream::events`] yields the items).
56pub fn decode<'a, I>(items: ItemStream<'a>) -> MethodStream<'a, I>
57where
58 I: DeserializeOwned,
59{
60 untagged(raw(items), plain::<I>())
61}
62
63/// [`decode`], opted in to progress: items as `Frame::Item(i)`, progress
64/// frames decoded as `P` and yielded as `Frame::Progress(p)`, in arrival
65/// order.
66pub fn decode_with_progress<'a, I, P>(items: ItemStream<'a>) -> WithProgress<'a, I, P>
67where
68 I: DeserializeOwned,
69 P: DeserializeOwned,
70{
71 MethodStream::<'a, I, P, I>::new(raw(items), plain::<I>(), |i| i).with_progress()
72}
73
74/// A Result method's items: each data frame's `content` is `{"ok": t}` or
75/// `{"err": e}` ([`wire_result`](crate::wire_result)) and decodes as `Ok(t)`
76/// / `Err(e)`. An `Err` is data — the activation saying no — so it does not
77/// end the stream.
78pub fn decode_result<'a, T, E>(items: ItemStream<'a>) -> MethodStream<'a, Result<T, E>>
79where
80 T: DeserializeOwned,
81 E: DeserializeOwned,
82{
83 untagged(raw(items), crate::wire_result::from_content::<T, E>)
84}