From 03165273edadd404a3b60b3e9c830d173e481deb Mon Sep 17 00:00:00 2001
From: djm <35852337+dmaccormack@users.noreply.github.com>
Date: Fri, 11 Nov 2022 10:15:18 -0500
Subject: [PATCH] doc: Add noEmptyComposite RunKit example to README

---
 README.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4d68914..7cae748 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,31 @@ let value = JsonURL.parse( "(Hello:Address Bar!!)",  { AQF: true });
 let string = JsonURL.stringify( value,  { AQF: true } );
 ```
 
-There are additional options available, but that's all you need to get started.
+### Options - noEmptyComposite
+
+The JSON→URL specification defines the empty composite value, `()`, because an
+empty array is indistinguishable from an empty object. This works well in
+practice, generally, but it can lead to counterintuitive results when parsing
+JSON→URL text into a language-native object and then stringifying it back
+into JSON→URL text; the input text doesn't "round-trip" back to
+itself as expected.
+
+The `noEmptyComposite` parse option causes the character sequence `()` to be
+parsed as an empty array, and the character sequence `(:)` to be parsed as an
+empty object. And the `noEmptyComposite` stringify option instructs
+`stringify` to generate those strings appropriately.
+
+[![RunKit: noEmptyComposite](https://img.shields.io/badge/RunKit-noEmptyComposite-ff69b4)][runkit3]
+
+```js
+let value = JsonURL.parse( "(Array:(true,false,(nested),()),Object:(nested:(:)))",  { AQF: true, noEmptyComposite: true });
+let string = JsonURL.stringify( value,  { AQF: true, noEmptyComposite: true });
+```
+
+### Options - More
+
+There are additional options available. The [typescript definition][dts] file
+is a good place to learn more.
 
 JSON→URL has no runtime dependencies.
 
@@ -100,6 +124,10 @@ set by default.
 
 [runkit2]: https://runkit.com/jsonurl/hello-aqf
 
+[runkit3]: https://runkit.com/jsonurl/noemptycomposite
+
+[dts]: https://github.com/jsonurl/jsonurl-js/blob/main/jsonurl.d.ts
+
 ## License
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fjsonurl%2Fjsonurl-js.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fjsonurl%2Fjsonurl-js?ref=badge_large)