diff --git a/Tether4.md b/Tether4.md index 490d518..b7ef075 100644 --- a/Tether4.md +++ b/Tether4.md @@ -12,10 +12,10 @@ For Output Plugs (publishing) NOW CHANNEL SENDERS, the topic will be constructed - agentRole/chanelName/optionalID For Input Plugs (subscribing) NOW CHANNEL RECEIVERS, the topic will be constructed as follows: -- agentRole/chanelName/# (matches "no ID" part and "ID part included") +- agentRole/chanelName/# (matches "no ID" part and "ID part(s) included") - agentRole/chanelName/optionalID (will only match when ID part is matched) -The main practical difference between a "topic" and a "Channel" (previously "plug") is simply that a Channel is expected to match ONLY ONE TYPE OF MESSAGE. So, a single MQTT Client may have multiple subscriptions, but we ensure that the correct messages are matched with the correct Channel when received, by applying our additional Tether Complaint Topic (TCT) matching pattern. +The main practical difference between a "topic" and a "Channel" (previously "plug") is simply that a Channel is expected to match ONLY ONE TYPE OF MESSAGE. So, a single MQTT Client may have multiple subscriptions, but we ensure that the correct messages are matched with the correct Channel when received, by applying our additional Tether Complaint Topic (TCT) matching pattern. The libraries (particularly typed languages such as TypeScript and Rust) should try to encourage (if not enforce) this practice. ## Cleaning up Unused "utilities" and the "explorer" will be removed. @@ -49,3 +49,18 @@ Apart from the terminology changes, the following are important to note: ## Rust changes Apart from the terminology changes, the following are important to note: - `agent.send` used to assume an already-encoded payload, while `.encode_and_send` did auto-encoding. Now, `.send` is the auto-encoding version and additional `.send_raw` and `.send_empty` functions are provided. It is VERY important that the new `.send` will actually (incorrectly!) accept already-encoded payloads, because `&[u8]` is ALSO `T: Serialize`! So applications using the new version must be carefully checked to ensure that things are not (double) encoded before sending! + +The term "OptionsBuilder" suffix has now been replaced with the much simpler "Builder", so we have simply: +- TetherAgentBuilder +- ChannelSenderBuilder +- ChannelReceiverBuilder + +Even better, the ChannelSenderBuilder/ChannelReceiver builder do not **have** to be used in all cases, since both ChannelSender and ChannelReceiver objects can be constructed via the Tether Agent object itself, i.e. + +- `tether_agent::create_sender` +- `tether_agent::create_receiver` + +All that needs to be provided, in the default cases, is the name and the type. For example: +- `tether_agent.create_sender::("numbersOnly")` creates a ChannelSender called "numbersOnly" which will automatically expect (require) u8 payloads + +The TypeScript library is now set up to mirror this as well (also, optional!). It means having to pass fewer arguments. diff --git a/examples/nodejs-ts/src/index.ts b/examples/nodejs-ts/src/index.ts index a83d726..df57021 100644 --- a/examples/nodejs-ts/src/index.ts +++ b/examples/nodejs-ts/src/index.ts @@ -17,15 +17,18 @@ logger.debug("Debug logging enabled; output could be verbose!"); const main = async () => { const agent = await TetherAgent.create("brain"); - const sender = new ChannelSender(agent, "randomValues"); + // Note the alternative syntax for doing the same thing, below: + // ... + // const sender = new ChannelSender(agent, "randomValues"); + const sender = agent.createSender("randomValues"); + sender.send({ value: Math.random(), timestamp: Date.now(), something: "one", }); - const genericReceiver = await ChannelReceiver.create( - agent, + const genericReceiver = await agent.createReceiver( "randomValuesStrictlyTyped" ); genericReceiver.on("message", (payload, topic) => { @@ -38,18 +41,14 @@ const main = async () => { ); }); - const typedReceiver = await ChannelReceiver.create( - agent, + const typedReceiver = await agent.createReceiver( "randomValuesStrictlyTyped" ); typedReceiver.on("message", (payload) => { logger.info("Our typed receiver got", payload, typeof payload); }); - const typedSender = new ChannelSender( - agent, - "randomValuesStrictlyTyped" - ); + const typedSender = agent.createSender("randomValuesStrictlyTyped"); // This will be rejected by TypeScript compiler: // typedSender.send({ // value: Math.random(), diff --git a/examples/react-ts/src/Tether/Receiver.tsx b/examples/react-ts/src/Tether/Receiver.tsx index 3694702..67f0d86 100644 --- a/examples/react-ts/src/Tether/Receiver.tsx +++ b/examples/react-ts/src/Tether/Receiver.tsx @@ -6,13 +6,15 @@ interface Props { } export const Receiver = (props: Props) => { + const { agent } = props; const [channel, setChannel] = useState | null>(null); const [lastMessage, setLastMessage] = useState(""); useEffect(() => { - ChannelReceiver.create(props.agent, "everything", { - overrideTopic: "#", - }) + agent + .createReceiver("everything", { + overrideTopic: "#", + }) .then((channel) => { setChannel(channel); channel.on("message", (payload, topic) => { @@ -24,7 +26,7 @@ export const Receiver = (props: Props) => { .catch((e) => { console.error("Error creating Channel Receiver:", e); }); - }, [props.agent]); + }, [agent]); return (
diff --git a/examples/react-ts/src/Tether/Sender.tsx b/examples/react-ts/src/Tether/Sender.tsx index 2f21e96..c3370c8 100644 --- a/examples/react-ts/src/Tether/Sender.tsx +++ b/examples/react-ts/src/Tether/Sender.tsx @@ -6,10 +6,12 @@ interface Props { } export const Sender = (props: Props) => { + const { agent } = props; + useEffect(() => { console.log("Sender useEffect"); - setChannel(new ChannelSender(props.agent, "sender")); - }, [props.agent]); + setChannel(new ChannelSender(agent, "sender")); + }, [agent]); const [useCustomTopic, setUseCustomTopic] = useState(false); const [customTopic, setTCustomTopic] = useState(""); @@ -32,7 +34,7 @@ export const Sender = (props: Props) => {