feat: serialization of promises (#20)

Author: KATT

.rfcs/001-serialize-async.md

@@ -0,0 +1,32 @@
+## Serializing promises and other async generators
+
+### Finished JSON output
+
+```js
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, no-unused-vars
+const out = [
+	// <first line> is just a `[` that initializes the array pf the response
+	// <second line>
+	{
+		json: {
+			foo: "bar",
+			iterator: ["AsyncIterator", 1, "__tson"],
+			promise: ["Promise", 0, "__tson"],
+		},
+		nonce: "__tson",
+	},
+	// <second line>
+	// <second line of json>
+	[
+		// ------ this could be streamed ------
+		[1, ["chunk", "chunk from iterator"]],
+		[0, ["resolve", "result of promise"]],
+		[1, ["chunk", "another chunk from iterator"]],
+		[1, ["end"]],
+	],
+];
+```
+
+### Serializing
+
+> This is now implemented

CHANGELOG.md

@@ -1,11 +1,8 @@
-
-
 # [0.10.0](https://github.com/KATT/tupleson/compare/0.9.0...0.10.0) (2023-10-02)
 
-
 ### Features
 
-* use UUIDs for nonce ([#19](https://github.com/KATT/tupleson/issues/19)) ([e347640](https://github.com/KATT/tupleson/commit/e347640dd10bf6ecc6b93f99e3118f572da671b3))
+- use UUIDs for nonce ([#19](https://github.com/KATT/tupleson/issues/19)) ([e347640](https://github.com/KATT/tupleson/commit/e347640dd10bf6ecc6b93f99e3118f572da671b3))
 
 # [0.9.0](https://github.com/KATT/tupleson/compare/0.8.0...0.9.0) (2023-10-01)
 
@@ -72,4 +69,4 @@
 ### Features
 
 - initial version ([#1](https://github.com/KATT/tupleson/issues/1)) ([ccce25b](https://github.com/KATT/tupleson/commit/ccce25b6a039cf2e5c1a774c1ab022f0946ca8d5))
-- initialized repo ✨ ([c9e92a4](https://github.com/KATT/tupleson/commit/c9e92a42c97a8bc1ee3a9214f65626425c8598e3))
+- initialized repo ✨ ([c9e92a4](https://github.com/KATT/tupleson/commit/c9e92a42c97a8bc1ee3a9214f65626425c8598e3))

README.md

@@ -25,6 +25,8 @@
 
 ## Introduction
 
+> This package is still experimental (although it's pretty well tested) & is subject to big changes
+
 A hackable JSON serializer/deserializer that allows you to serialize/deserialize almost[^1] anything.
 
 Serialize exactly what you want; no more, no less.
@@ -104,9 +106,9 @@ type Obj = typeof obj;
 // -> type Obj = { foo: string; set: Set<number>; }
 ```
 
-### Extend with a custom serializer
+## Extend with a custom serializer
 
-#### [Temporal](https://www.npmjs.com/package/@js-temporal/polyfill)
+### [Temporal](https://www.npmjs.com/package/@js-temporal/polyfill)
 
 > See test reference in [`./src/extend/temporal.test.ts`](./src/extend/temporal.test.ts)
 
@@ -134,7 +136,7 @@ const tson = createTson({
 });
 ```
 
-#### [Decimal.js](https://github.com/MikeMcl/decimal.js)
+### [Decimal.js](https://github.com/MikeMcl/decimal.js)
 
 > See test reference in [`./src/extend/decimal.test.ts`](./src/extend/decimal.test.ts)
 
@@ -154,6 +156,8 @@ const tson = createTson({
 });
 ```
 
+---
+
 <!-- ## All contributors ✨
 
 <a href="https://github.com/KATT/tupleson/graphs/contributors">

cspell.json

@@ -14,18 +14,20 @@
 		"commitlint",
 		"contributorsrc",
 		"conventionalcommits",
+		"Iterarable",
+		"KATT",
 		"knip",
 		"lcov",
 		"markdownlintignore",
 		"npmpackagejsonlintrc",
 		"outro",
 		"packagejson",
 		"quickstart",
+		"stringifier",
+		"tson",
 		"tsup",
+		"tupleson",
 		"wontfix",
-		"tson",
-		"stringifier",
-		"KATT",
-		"tupleson"
+		"deferreds"
 	]
 }

src/async/asyncTypes.test.ts

@@ -0,0 +1,5 @@
+import { test } from "vitest";
+
+import "./asyncTypes.js";
+
+test.todo("check that it retains type");

src/async/asyncTypes.ts

@@ -0,0 +1,53 @@
+// eslint-disable-next-line eslint-comments/disable-enable-pair
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { TsonType } from "../types.js";
+import { TsonBranded, TsonTypeTesterCustom } from "../types.js";
+import { serialized } from "../types.js";
+
+export type TsonAsyncStringifierIterator<TValue> = AsyncIterable<string> & {
+	[serialized]: TValue;
+};
+
+export type TsonAsyncStringifier = <TValue>(
+	value: TValue,
+	space?: number,
+) => TsonAsyncStringifierIterator<TValue>;
+export type TsonAsyncIndex = TsonBranded<number, "AsyncRegistered">;
+export interface TsonTransformerSerializeDeserializeAsync<TValue> {
+	async: true;
+	/**
+	 * From JSON-serializable value
+	 */
+	deserialize: (
+		v: TsonAsyncIndex,
+		register: (index: TsonAsyncIndex) => Promise<TValue>,
+	) => TValue;
+
+	/**
+	 * The key to use when serialized
+	 */
+	key: string;
+	/**
+	 * JSON-serializable value
+	 */
+	serialize: (
+		v: TValue,
+		register: (thing: TValue) => TsonAsyncIndex,
+	) => TsonAsyncIndex;
+}
+
+export interface TsonAsyncType<TValue>
+	extends TsonTransformerSerializeDeserializeAsync<TValue>,
+		TsonTypeTesterCustom {}
+export interface TsonAsyncOptions {
+	/**
+	 * The nonce function every time we start serializing a new object
+	 * Should return a unique value every time it's called
+	 * @default `${crypto.randomUUID} if available, otherwise a random string generated by Math.random`
+	 */
+	nonce?: () => number | string;
+	/**
+	 * The list of types to use
+	 */
+	types: (TsonAsyncType<any> | TsonType<any, any> | TsonType<any, never>)[];
+}

src/async/createTsonAsync.ts

@@ -0,0 +1,8 @@
+import { TsonAsyncOptions } from "./asyncTypes.js";
+import { createTsonParseAsync } from "./deserializeAsync.js";
+import { createAsyncTsonStringify } from "./serializeAsync.js";
+
+export const createTsonAsync = (opts: TsonAsyncOptions) => ({
+	parse: createTsonParseAsync(opts),
+	stringify: createAsyncTsonStringify(opts),
+});