chore: add comments to example (#38)

examples/async/src/client.ts

@@ -6,13 +6,14 @@ import type { ResponseShape } from "./server.js";
 import { mapIterable, readableStreamToAsyncIterable } from "./iteratorUtils.js";
 import { tsonOptions } from "./shared.js";
 
+// create the async parser
 const tsonParseAsync = createTsonParseAsync(tsonOptions);
 
 async function main() {
-	// do a streamed fetch request
 	const port = 3000;
 	await waitPort({ port });
 
+	// <request to server - boring, you can skip this>
 	const response = await fetch(`http://localhost:${port}`);
 
 	if (!response.body) {
@@ -26,28 +27,35 @@ async function main() {
 		readableStreamToAsyncIterable(response.body),
 		(v) => textDecoder.decode(v),
 	);
+	// </request to server>
 
 	// ✨ ✨ ✨ ✨  parse the response body stream  ✨ ✨ ✨ ✨ ✨
 	const output = await tsonParseAsync<ResponseShape>(stringIterator);
 
-	// we can now use the output as a normal object
+	// .... we can now use the output as a normal object 🤯🤯
 	console.log({ output });
 
+	console.log("[output.promise] Promise result:", await output.promise);
+
+	// Iterate over the async iterators
 	const printBigInts = async () => {
 		for await (const value of output.bigints) {
-			console.log(`Received bigint:`, value);
+			console.log(`[output.bigints] Received bigint:`, value);
 		}
 	};
 
+	// Iterate over the async iterators
 	const printNumbers = async () => {
 		for await (const value of output.numbers) {
-			console.log(`Received number:`, value);
+			console.log(`[output.numbers] Received number:`, value);
 		}
 	};
 
 	await Promise.all([printBigInts(), printNumbers()]);
 
-	console.log("✅ Output ended");
+	console.log(
+		`✅ Output ended - visit http://localhost:${port} to see the raw server output`,
+	);
 }
 
 main().catch((err) => {

examples/async/src/server.ts

@@ -9,19 +9,24 @@ const randomNumber = (min: number, max: number) => {
 	return Math.floor(Math.random() * (max - min + 1) + min);
 };
 
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * This function returns the object we will be sending to the client.
+ */
 export function getResponseShape() {
 	async function* bigintGenerator() {
 		const iterate = new Array(10).fill(0).map((_, i) => BigInt(i));
 		for (const number of iterate) {
-			await new Promise((resolve) => setTimeout(resolve, randomNumber(1, 400)));
+			await wait(randomNumber(1, 400));
 			yield number;
 		}
 	}
 
 	async function* numberGenerator() {
 		const iterate = new Array(10).fill(0).map((_, i) => i);
 		for (const number of iterate) {
-			await new Promise((resolve) => setTimeout(resolve, randomNumber(1, 400)));
+			await wait(randomNumber(1, 400));
 			yield number;
 		}
 	}
@@ -30,7 +35,6 @@ export function getResponseShape() {
 		bigints: bigintGenerator(),
 		foo: "bar",
 		numbers: numberGenerator(),
-		// promise: Promise.resolve(42),
 		promise: new Promise<number>((resolve) =>
 			setTimeout(() => {
 				resolve(42);
@@ -53,6 +57,7 @@ async function handleRequest(
 
 	const obj = getResponseShape();
 
+	// Stream the response to the client
 	for await (const chunk of tsonStringifyAsync(obj)) {
 		res.write(chunk);
 	}

examples/async/src/shared.ts

@@ -5,6 +5,17 @@ import {
 	tsonPromise,
 } from "tupleson";
 
+/**
+ * Shared tupleSON options for the server and client.
+ */
 export const tsonOptions: TsonAsyncOptions = {
-	types: [tsonPromise, tsonAsyncIterator, tsonBigint],
+	// We need to specify the types we want to allow serialization of
+	types: [
+		// Allow serialization of promises
+		tsonPromise,
+		// Allow serialization of async iterators
+		tsonAsyncIterator,
+		// Allow serialization of bigints
+		tsonBigint,
+	],
 };