document: JSON as JavaScript has it, for C++

#include <webcpp/document.hpp>

#include <cstdint>
#include <iostream>
#include <string_view>

namespace wd = webcpp::document;

// JSON.parse, whose result holds the document or the error.
wd::result<wd::document> made =
    wd::parse(R"({"name":"Ada","born":1815,"langs":["Analytical"]})");
if (made.has_error()) {
    std::cout << "error: " << made.error().message() << '\n';
    return 1;
}
wd::document& doc = *made;

// doc.name ?? "nobody", and doc.born ?? 0.
std::cout << doc["name"].value_or(std::string_view("nobody")) << " was born in "
          << doc["born"].value_or(std::int64_t{0}) << '\n';

// doc.known = true; doc.langs.push("Note G"); each write returns its result.
if (!doc["known"].set(true) || !doc["langs"].push("Note G")) {
    std::cout << "error: the document is full\n";
    return 1;
}

// JSON.stringify(doc, null, 2).
std::cout << doc.stringify(2) << '\n';

Ada was born in 1815
{
  "name": "Ada",
  "born": 1815,
  "langs": [
    "Analytical",
    "Note G"
  ],
  "known": true
}

constexpr std::string_view text = R"({"user":"Ada","langs":["Analytical","Note G"]})";
wd::result<wd::document> made = wd::parse(text);
if (made.has_error()) {
    return false;
}
const std::span<const std::byte> image = made->image();
// A buffer of the program's, 16-aligned, large enough for the image.
alignas(16) std::array<std::byte, 8192> buffer{};
if (image.size() > buffer.size()) {
    return false;
}
std::ranges::copy(image, buffer.begin());
// Opened in place: the buffer becomes the document, with no parse.
wd::result<wd::basic_document<wd::default_traits, wd::external>> opened =
    wd::open(std::span<std::byte>(buffer.data(), image.size()));
if (opened.has_error()) {
    return false;
}
std::cout << "5. An image copied to another buffer and opened in place\n";
print_document(opened->stringify());
// A Boost.JSON value points into its memory resource, so its bytes cannot be copied: the
// only way to move it is to serialize it and parse it again.
print_boost(boost_text(made->stringify()));

5. An image copied to another buffer and opened in place
  document:   {"user":"Ada","langs":["Analytical","Note G"]}
  Boost.JSON: {"user":"Ada","langs":["Analytical","Note G"]}

/**
 NDJSON: each document ends at its line's newline, so a line may end in CRLF, a line may be empty,
 and the last line may lack its newline, which finish closes.
*/
bool read_ndjson() {
    std::cout << "NDJSON, taken with next():\n";
    wd::stream_options options;
    options.framing = wd::framing::lines;
    wd::stream_parser p(options);
    constexpr std::string_view text =
        "{\"id\":1,\"tags\":[\"a\",\"b\"]}\n"
        "{\"id\":2,\"note\":\"first\\nsecond\"}\r\n"
        "\n"
        "[3,4.5]\n"
        "null";
    if (!write_in_pieces(p, text, options.on_error)) {
        return false;
    }
    if (const wd::result<std::size_t> finished = p.finish(); finished.has_error()) {
        report_error(p, finished.error());
        return false;
    }
    take_ready(p, options.on_error);
    return true;
}

NDJSON, taken with next():
{"id":1,"tags":["a","b"]}
{"id":2,"note":"first\nsecond"}
[3,4.5]
null

// 0.1 + 0.2, computed by the program in the traits' own number type, then stored.
wd::result<wd::document> exact = wd::parse(R"({"a":0.1,"b":0.2})");
wd::result<wd::basic_document<wd::js_traits>> js =
    wd::parse<wd::js_traits>(R"({"a":0.1,"b":0.2})");
if (exact.has_error() || js.has_error()) {
    return 1;
}
using decimal = boost::decimal::decimal128_t;
const wd::result<decimal> a = (*exact)["a"].get<decimal>();
const wd::result<decimal> b = (*exact)["b"].get<decimal>();
const wd::result<double> x = (*js)["a"].get<double>();
const wd::result<double> y = (*js)["b"].get<double>();
if (!a || !b || !x || !y || !(*exact)["sum"].set(*a + *b) || !(*js)["sum"].set(*x + *y)) {
    return 1;
}
std::cout << exact->stringify() << '\n' << js->stringify() << '\n';

{"a":0.1,"b":0.2,"sum":0.3}
{"a":0.1,"b":0.2,"sum":0.30000000000000004}

// A sealed image with one byte changed is refused as damaged, by open and by from_image.
const auto found =
    std::ranges::search(bytes, std::as_bytes(std::span(std::string_view("Ada"))));
if (found.empty()) {
    return false;
}
found.front() = std::byte{'a'};
if (!refused("one byte changed", wd::open(bytes))) {
    return false;
}

one byte changed: damaged_document, a sealed image whose bytes do not match its seal

wd::result<wd::document> made = wd::parse("{}");
if (made.has_error()) {
    return false;
}
for (std::uint64_t i = 0; i < 1000; ++i) {
    if (!(*made)[std::to_string(i)].set(std::string(100, 'x'))) {
        return false;
    }
}
const std::uint64_t grown = made->image().size();
if (!made->root().set(wd::object{{"kept", true}}) || !made->shrink_to_fit()) {
    return false;
}
std::cout << "grown to " << grown << " bytes, shrunk to " << made->image().size() << ": "
          << made->stringify() << '\n';

// Blocks never move: a deep copy into a new document packs the content.
wd::result<wd::document> packed = wd::document::create();
if (packed.has_error() || !packed->root().set(*made)) {
    return false;
}
std::cout << "packed: " << packed->image().size() << " bytes\n";

grown to 524288 bytes, shrunk to 352864: {"kept":true}
packed: 4096 bytes

/** A pool of two blocks: the most the client leases at once. */
wd::image_pool pool_of_two() {
    return wd::image_pool::create(block_bytes, 2).value();
}

// make_mutable copies the image into a block of the writer's own when other holders exist, so the
// writer changes its copy and the others keep the document as it was. The library does not
// synchronise writers: a block with several writers, or a writer and readers of that same block,
// must wait for each other by the program's own means, such as a mutex. This writer changes only
// its copy, which no other holder reads.
void writer_task(wd::shared_document<> holder, std::string& out) {
    if (holder.make_mutable().has_error() || holder["name"].set("Lovelace").has_error()) {
        out = "error";
        return;
    }
    out = describe(holder);
}

writer: Lovelace was born in 1815
after the writer: Ada was born in 1815, use_count 1, 6 of 7 blocks free
last copy dropped: 7 of 7 blocks free

// by_key is the same object in key order, by UTF-16 code units, with bounds for ranges of keys.
// A JavaScript program sorts every key to get any of these; here the tree keeps them sorted.
wd::result<wd::document> catalog_made = wd::parse("{}");
if (catalog_made.has_error()) {
    return fail(catalog_made);
}
wd::document& catalog = *catalog_made;
wd::result<wd::object_ref> as_catalog = catalog.root().as_object();
if (as_catalog.has_error()) {
    return fail(as_catalog);
}
const wd::object_ref catalog_obj = *as_catalog;
const std::array<std::string_view, 13> names{
    "user_3", "admin",  "user_1", "guest",  "user_9", "user",   "user_2",
    "owner",  "user_7", "user_5", "user_4", "user_8", "user_6",
};
for (const std::string_view key : names) {
    const auto added = catalog_obj.insert(key, true);
    if (added.has_error()) {
        return fail(added);
    }
}
std::cout << "JavaScript order:";
for (const auto& member : catalog_obj) {
    std::cout << ' ' << member.first;
}
std::cout << '\n';
const auto keys = catalog_obj.by_key();
std::cout << "by_key order:";
for (const auto& member : keys) {
    std::cout << ' ' << member.first;
}
std::cout << '\n';

// The keys with the prefix "user_" lie from its first key up to the first key at or after
// "user`", the character after '_'.
const std::ranges::subrange users(keys.lower_bound("user_"), keys.lower_bound("user`"));
std::cout << "prefix user_: " << std::ranges::distance(users) << " keys, from "
          << users.begin()->first << " to " << std::ranges::prev(users.end())->first << '\n';

const auto [exact, exact_end] = keys.equal_range("user_5");
std::cout << "equal_range user_5: " << std::ranges::distance(exact, exact_end) << " member, "
          << exact->first << '\n';

std::cout << "lower_bound p: " << keys.lower_bound("p")->first << '\n';
const std::ranges::subrange between(keys.lower_bound("g"), keys.lower_bound("v"));
std::cout << "keys from g up to v: " << std::ranges::distance(between) << '\n';

JavaScript order: user_3 admin user_1 guest user_9 user user_2 owner user_7 user_5 user_4 user_8 user_6
by_key order: admin guest owner user user_1 user_2 user_3 user_4 user_5 user_6 user_7 user_8 user_9
prefix user_: 9 keys, from user_1 to user_9
equal_range user_5: 1 member, user_5
lower_bound p: user
keys from g up to v: 12

const doc = Document.parse('{"user":{"name":"Ada","age":36,"langs":["C"]},"n":null,"t":false}')
assert.equal(doc.get(['user', 'name']), 'Ada')
assert.equal(doc.get(['user', 'age']), 36)
assert.deepEqual(doc.get(['user', 'langs']), ['C'])
assert.equal(doc.get(['n']), null)
assert.equal(doc.get(['missing', 'deeper']), undefined)
assert.equal(doc.get(['user', 'langs', 0]), 'C')
doc.free()

const doc = Document.parse('{"user":{"name":"Ada"},"langs":[]}')
doc.set(['user', 'age'], 30)
doc.set(['user', 'tags'], { a: [1, 'two', null] })
doc.set(['pi'], 3.14159)
doc.set(['zero'], -0)
assert.equal(doc.get(['user', 'age']), 30)
doc.set([], [true])
assert.equal(doc.stringify(), '[true]')
doc.free()

const doc = Document.parse('{"langs":["C","Rust","Go"]}')
assert.equal(doc.push(['langs'], 'Note G'), 4)
assert.equal(doc.length(['langs']), 4)
assert.deepEqual(doc.splice(['langs'], 0, 1), ['C'])
assert.deepEqual(doc.splice(['langs'], -1, 1, 'JS', 'Lisp'), ['Note G'])
assert.equal(doc.stringify(), JSON.stringify({ langs: ['Rust', 'Go', 'JS', 'Lisp'] }))
doc.free()

const doc = Document.parse('{"obj":{"a":1},"arr":[1,2],"num":5,"str":"s"}')
assert.throws(() => doc.set(['missing', 'x'], 1), TypeError)
assert.throws(() => doc.push(['obj'], 1), TypeError)
assert.throws(() => doc.erase(['arr', 0]), TypeError)
assert.throws(() => doc.splice(['num'], 0, 1), TypeError)
assert.throws(() => doc.set(['f'], () => 1), TypeError)
assert.throws(() => doc.get(['arr', 1.5]), TypeError)
doc.free()

const text = '0.1234567890123456789012345678901234'
const doc = Document.parse(`{"price":${text},"small":1.50}`)
assert.equal(doc.getDecimal(['price']), text)
assert.equal(doc.get(['price']), Number(text))
assert.equal(doc.getDecimal(['small']), '1.5')
assert.equal(doc.get(['small']), 1.5)
doc.free()

const doc = Document.parse('{"users":{"user_2":{},"user_10":{},"admin":{},"user_1":{},' +
    '"user_":{},"user`":{}}}')
assert.deepEqual(doc.keysInRange(['users'], 'user_', 'user_￿'),
    ['user_', 'user_1', 'user_10', 'user_2'])
assert.deepEqual(doc.keysInRange(['users'], 'x', 'y'), [])
doc.free()

const doc = Document.parse('{"a":[1,2,3]}')
assert.equal(doc.byteLength, doc.image().byteLength)
assert.equal(doc.seal(), undefined)
const image = doc.image().slice()
assert.equal(Document.open(image).stringify(), '{"a":[1,2,3]}')
image[image.length - 1] ^= 0xff
assert.throws(() => Document.open(image), TypeError)
doc.free()

const doc = Document.parse('{"a":1}')
const before = doc.capacity
assert.ok(before >= doc.byteLength)
assert.equal(doc.reserve(before * 4), undefined)
assert.ok(doc.capacity >= before * 4)
assert.equal(doc.stringify(), '{"a":1}')
doc.free()

const doc = Document.parse(text)
doc.set(['user', 'age'], 36)
const bytes = doc.image().slice()
doc.free()

worker.postMessage({ image: bytes.buffer }, [bytes.buffer])

self.onmessage = ({ data }) => {
    const doc = Document.open(new Uint8Array(data.image))
    self.postMessage({
        name: doc.get(['user', 'name']),
        age: doc.get(['user', 'age']),
        langs: doc.get(['user', 'langs']),
        price: doc.getDecimal(['price']),
        text: doc.stringify(),
    })
    doc.free()
}

const free = pool.available
const doc = Document.parse('{"user":{"name":"Ada","langs":["C","Note G"]},"price":1.50}')
const address = doc.image().byteOffset
say(`page: parsed into one block of the pool, use count ${doc.useCount}`)

const workers = Array.from({ length: 4 }, start)
const adopted = await Promise.all(workers.map(worker =>
    worker.send({ command: 'adopt', connection: connection(), token: doc.share() })))

const commands = {
    async adopt({ connection, token }) {
        await join(connection)
        doc = SharedDocument.adopt(token)
        return describe()
    },
    // The document made this worker's own, a copy in a block of its own, then changed.
    write({ name }) {
        doc.makeMutable()
        doc.set(['user', 'name'], name)
        return describe()
    },
    free() {
        doc.free()
        return {}
    },
}

const doc = Document.parse(text)
const token = doc.share()
SharedDocument.drop(token)
assert.equal(doc.useCount, 1)
assert.throws(() => SharedDocument.adopt(token), TypeError)
assert.throws(() => SharedDocument.drop(token), TypeError)

cross-origin isolated: true
page: parsed into one block of the pool, use count 1
worker 1: reads Ada and C, Note G, at the page's address: true, in a SharedArrayBuffer: true
worker 2: reads Ada and C, Note G, at the page's address: true, in a SharedArrayBuffer: true
worker 3: reads Ada and C, Note G, at the page's address: true, in a SharedArrayBuffer: true
worker 4: reads Ada and C, Note G, at the page's address: true, in a SharedArrayBuffer: true
page: use count 5, blocks in use 1
worker 4: makeMutable, then set: reads Grace, at the page's address: false
page: reads Ada, use count 4, blocks in use 2
page: every worker freed its reference, use count 1
page: freed, every block back in the pool: true

for await (const doc of StreamParser.from(chunked(encoder.encode(lines), size), { framing: 'lines' })) {
    assert.ok(doc instanceof Document)
    out.push(doc.toJSON())
}

const parser = new StreamParser({ framing: 'lines' })
parser.write(encoder.encode('{"a":'))
assert.equal(parser.read(), undefined)
parser.write(encoder.encode('1}\n'))
assert.deepEqual(parser.read().toJSON(), { a: 1 })
assert.equal(parser.read(), undefined)
parser.finish()

/** Prints a JavaScript expression and the value it reads, `undefined` when nothing is there. */
void show(std::string_view expression, const wd::const_value& v) {
    std::cout << expression << " -> " << (v.is_undefined() ? "undefined" : v.stringify()) << '\n';
}

wd::result<wd::document> made = wd::parse(R"({"list":[10,20],"o":{"3":"three"},"z":-0})");
if (made.has_error()) {
    return false;
}
wd::document& doc = *made;
show("doc.list['0']", doc["list"]["0"]);  // JavaScript: 10, an index written as a key
show("doc.o[3]", doc["o"][3]);            // JavaScript: "three", a key written as an index
show("doc.z", doc["z"]);                  // -0 is 0, as JSON.stringify writes it
say(R"(JSON.parse('"\ud800"') refused)", wd::parse(R"("\ud800")").error() == wd::errc::syntax);

doc.list['0'] -> undefined
doc.o[3] -> undefined
doc.z -> 0
JSON.parse('"\ud800"') refused -> true

constexpr std::string_view text = R"({"user":{"name":"Ada","tags":["math"]},"n":3})";
wd::result<wd::document> made = wd::parse(text);
if (made.has_error()) {
    return false;
}
wd::document& doc = *made;
wd::value user = doc["user"];

show("user.name", user["name"]);
show("user.nick", user["nick"]);        // a missing member: set creates it
show("doc.n.x.y", doc["n"]["x"]["y"]);  // nothing: JavaScript throws a TypeError here
show("user.tags[0]", user["tags"][0]);
show("user.tags.at(-1)", user["tags"].at(-1));

user.name -> "Ada"
user.nick -> undefined
doc.n.x.y -> undefined
user.tags[0] -> "math"
user.tags.at(-1) -> "math"

say("typeof user.name === 'string'", user["name"].is_string());
say("'tags' in user", user.contains("tags"));
if (const wd::result<std::uint64_t> length = user["name"].length()) {
    say("user.name.length", *length);
}
say("doc.n ?? 0", doc["n"].value_or(std::int64_t{0}));
say("user.nick ?? 'none'", user["nick"].value_or(std::string_view("none")));
say("Number.isInteger(doc.n)", doc["n"].is_integer());

typeof user.name === 'string' -> true
'tags' in user -> true
user.name.length -> 3
doc.n ?? 0 -> 3
user.nick ?? 'none' -> none
Number.isInteger(doc.n) -> true

// user.nick = "Countess"; user.age = 36; user.tags.push("poetry"); user.home = {...};
if (!user["nick"].set("Countess") || !user["age"].set(36) || !user["tags"].push("poetry") ||
    !user["home"].set(wd::object{{"city", "London"}, {"rooms", wd::array{1, 2}}})) {
    return false;
}
show("user", user);

// delete user.age; user.nick = undefined, which erases it; Object.assign(user, {...}).
const wd::result<bool> erased = user.erase("age");
if (!erased || !user["nick"].set(wd::undefined)) {
    return false;
}
say("delete user.age", *erased);
wd::result<wd::document> defaults = wd::parse(R"({"lang":"en","name":"Lovelace"})");
if (defaults.has_error() || !user.assign_from(defaults->root())) {
    return false;
}
show("user", user);

user -> {"name":"Ada","tags":["math","poetry"],"nick":"Countess","age":36,"home":{"city":"London","rooms":[1,2]}}
delete user.age -> true
user -> {"name":"Lovelace","tags":["math","poetry"],"home":{"city":"London","rooms":[1,2]},"lang":"en"}

// doc.copy = doc.user shares one object in JavaScript; here it is a copy of the subtree.
if (!doc["copy"].set(user) || !doc["copy"]["name"].set("Byron")) {
    return false;
}
show("user.name", user["name"]);
show("copy.name", doc["copy"]["name"]);

user.name -> "Lovelace"
copy.name -> "Byron"

// for (const [key, value] of Object.entries(user))
for (auto [key, value] : user.entries()) {
    std::cout << key << ": " << value.stringify() << '\n';
}
// for (const tag of user.tags)
for (const wd::const_value tag : user["tags"]) {
    std::cout << "tag " << tag.stringify() << '\n';
}

name: "Lovelace"
tags: ["math","poetry"]
home: {"city":"London","rooms":[1,2]}
lang: "en"
tag "math"
tag "poetry"

constexpr std::string_view text =
    "[0.1000000000000000000000000000000001,18446744073709551615,4611686018427387904,"
    "1e21,1.50,1E-7,1.0,-0]";
parsed("default_traits", wd::parse(text));
parsed("js_traits     ", wd::parse<wd::js_traits>(text));

default_traits: [0.1000000000000000000000000000000001,18446744073709551615,4611686018427387904,1e+21,1.5,1e-7,1,0]
js_traits     : [0.1,18446744073709552000,4611686018427388000,1e+21,1.5,1e-7,1,0]

constexpr std::string_view forty_digits = "1234567890123456789012345678901234567890";
parsed("40 digits, default_traits", wd::parse(forty_digits));
parsed("40 digits, js_traits     ", wd::parse<wd::js_traits>(forty_digits));
parsed("1e999, default_traits    ", wd::parse("1e999"));
parsed("1e999, js_traits         ", wd::parse<wd::js_traits>("1e999"));

40 digits, default_traits: a number or index out of range
40 digits, js_traits     : 1.2345678901234568e+39
1e999, default_traits    : 1e+999
1e999, js_traits         : null

wd::result<wd::document> made =
    wd::parse(R"({"small":300,"big":18446744073709551615,"half":0.5,"huge":1e30})");
if (made.has_error()) {
    return 1;
}
const wd::document& doc = *made;
read("small as int64_t", doc["small"].get<std::int64_t>());
read("small as int8_t", doc["small"].get<std::int8_t>());
read("big as uint64_t", doc["big"].get<std::uint64_t>());
read("big as int64_t", doc["big"].get<std::int64_t>());
read("half as int64_t", doc["half"].get<std::int64_t>());
std::cout << "Number.isInteger(huge): " << std::boolalpha << doc["huge"].is_integer() << '\n';

small as int64_t: 300
small as int8_t: a number or index out of range
big as uint64_t: 18446744073709551615
big as int64_t: a number or index out of range
half as int64_t: a number or index out of range
Number.isInteger(huge): true

// 0.1 + 0.2, computed by the program in the traits' own number type, then stored.
wd::result<wd::document> exact = wd::parse(R"({"a":0.1,"b":0.2})");
wd::result<wd::basic_document<wd::js_traits>> js =
    wd::parse<wd::js_traits>(R"({"a":0.1,"b":0.2})");
if (exact.has_error() || js.has_error()) {
    return 1;
}
using decimal = boost::decimal::decimal128_t;
const wd::result<decimal> a = (*exact)["a"].get<decimal>();
const wd::result<decimal> b = (*exact)["b"].get<decimal>();
const wd::result<double> x = (*js)["a"].get<double>();
const wd::result<double> y = (*js)["b"].get<double>();
if (!a || !b || !x || !y || !(*exact)["sum"].set(*a + *b) || !(*js)["sum"].set(*x + *y)) {
    return 1;
}
std::cout << exact->stringify() << '\n' << js->stringify() << '\n';

{"a":0.1,"b":0.2,"sum":0.3}
{"a":0.1,"b":0.2,"sum":0.30000000000000004}

constexpr std::string_view text = R"(["é😀","tab\there \"q\" \u0001"])";
wd::result<wd::document> utf8 = wd::parse(text);
wd::result<wd::basic_document<wd::js_traits>> utf16 = wd::parse<wd::js_traits>(text);
if (utf8.has_error() || utf16.has_error()) {
    return false;
}
// "é😀".length is 3 in UTF-16 code units, whatever the stored encoding.
read("UTF-8 length ", (*utf8)[0].length());
read("UTF-16 length", (*utf16)[0].length());
read("UTF-8 as std::string_view", (*utf8)[0].get<std::string_view>());
read("UTF-8 as std::u16string_view", (*utf8)[0].get<std::u16string_view>());
read("UTF-16 as std::u16string_view", (*utf16)[0].get<std::u16string_view>());
read("UTF-16 as std::string", (*utf16)[0].get<std::string>());
std::cout << "both write: " << utf8->stringify() << ' ' << utf16->stringify() << '\n';

// A lone surrogate: kept by UTF-16 and written as JSON.stringify writes it; refused by UTF-8.
constexpr std::array<char16_t, 1> lone{0xD800};
const std::u16string_view surrogate(lone.data(), lone.size());
print("UTF-16 set", (*utf16)[2].set(surrogate));
print("UTF-8 set ", (*utf8)[2].set(surrogate));
std::cout << "UTF-16 writes: " << (*utf16)[2].stringify() << '\n';

UTF-8 length : 3
UTF-16 length: 3
UTF-8 as std::string_view: é😀
UTF-8 as std::u16string_view: a value of another kind
UTF-16 as std::u16string_view: 3 code units
UTF-16 as std::string: é😀
both write: ["é😀","tab\there \"q\" \u0001"] ["é😀","tab\there \"q\" \u0001"]
UTF-16 set: ok
UTF-8 set : a value of another kind
UTF-16 writes: "\ud800"

constexpr std::string_view text = R"({"at":"2026-10-12T03:04:05.678Z","day":"2026-10-12"})";
wd::parse_options revive;
revive.revive_dates = true;
wd::result<wd::document> plain = wd::parse(text);
wd::result<wd::document> revived = wd::parse(text, revive);
if (plain.has_error() || revived.has_error()) {
    return false;
}
std::cout << "is_date: " << std::boolalpha << (*plain)["at"].is_date() << ' '
          << (*revived)["at"].is_date() << ' ' << (*revived)["day"].is_date() << '\n';
// A string in Date.prototype.toJSON's format reads as a date, revived or not.
const wd::result<wd::date_ms> at = (*plain)["at"].get<wd::date_ms>();
std::cout << "ms since the epoch: " << (at ? at->time_since_epoch().count() : 0) << '\n';

const wd::date_ms last{std::chrono::milliseconds{8'640'000'000'000'000}};
print("set the last date", (*plain)["last"].set(last));
print("set one ms later ", (*plain)["later"].set(last + std::chrono::milliseconds{1}));
print("written", plain);

is_date: false true false
ms since the epoch: 1791774245678
set the last date: ok
set one ms later : a number or index out of range
written: {"at":"2026-10-12T03:04:05.678Z","day":"2026-10-12","last":"+275760-09-13T00:00:00.000Z"}

const std::array<std::byte, 4> raw{
    std::byte{0xde},
    std::byte{0xad},
    std::byte{0xbe},
    std::byte{0xef},
};
const std::span<const std::byte> view(raw);
wd::result<wd::document> base64 = wd::document::create();
wd::result<wd::basic_document<canonical_traits>> base64url =
    wd::basic_document<canonical_traits>::create();
wd::result<wd::basic_document<wd::js_traits>> js = wd::basic_document<wd::js_traits>::create();
if (base64.has_error() || base64url.has_error() || js.has_error() ||
    !base64->root().set(view) || !base64url->root().set(view) || !js->root().set(view)) {
    return false;
}
print("base64          ", base64);
print("base64url       ", base64url);
print("javascript_bytes", js);

// revive_bytes turns text of the bytes policy back into bytes.
wd::parse_options revive;
revive.revive_bytes = true;
wd::result<wd::document> revived = wd::parse(R"({"key":"3q2+7w=="})", revive);
if (revived.has_error()) {
    return false;
}
const wd::result<std::vector<std::byte>> key = (*revived)["key"].get<std::vector<std::byte>>();
std::cout << "revived: " << std::boolalpha << (*revived)["key"].is_bytes() << ", "
          << (key ? key->size() : 0) << " bytes\n";

base64          : "3q2+7w=="
base64url       : "3q2-7w"
javascript_bytes: {"0":222,"1":173,"2":190,"3":239}
revived: true, 4 bytes

constexpr std::string_view text = R"({"b":1,"2":2,"a":3,"1":4,"01":5})";
print("javascript_order", wd::parse(text));
print("insertion_order ", wd::parse<insertion_traits>(text));
print("sorted          ", wd::parse<canonical_traits>(text));

// An index key erased and created again goes back among the indices; any other key, last.
wd::result<wd::document> made = wd::parse(text);
if (made.has_error() || !made->root().erase("b") || !(*made)["b"].set(6) ||
    !made->root().erase("1") || !(*made)["1"].set(7)) {
    return false;
}
print("erased, created ", made);

javascript_order: {"1":4,"2":2,"b":1,"a":3,"01":5}
insertion_order : {"b":1,"2":2,"a":3,"1":4,"01":5}
sorted          : {"01":5,"1":4,"2":2,"a":3,"b":1}
erased, created : {"1":7,"2":2,"a":3,"01":5,"b":6}

if (!a.set(wd::array{1, 2, 3, 4, 5})) {
    return 1;
}
log("a.splice(-2, 1)", a.splice(-2, 1), a);
log("a.splice(10, 0, 'end')", a.splice(10, 0, "end"), a);
log("a.splice(1, -5)", a.splice(1, -5), a);
log("a.splice(3)", a.splice(3), a);

a.splice(-2, 1) -> [4], a = [1,2,3,5]
a.splice(10, 0, 'end') -> [], a = [1,2,3,5,"end"]
a.splice(1, -5) -> [], a = [1,2,3,5,"end"]
a.splice(3) -> [5,"end"], a = [1,2,3]

log("a.length = 1", a.set_length(1), a);
log("a.length = 3", a.set_length(3), a);
log("a[5] = 6", a[5].set(6), a);
log("a.pop()", a.pop(), a);
log("a.pop()", a.pop(), a);  // JavaScript: undefined, the element of a hole

a.length = 1 -> undefined, a = [1]
a.length = 3 -> undefined, a = [1,null,null]
a[5] = 6 -> undefined, a = [1,null,null,null,null,6]
a.pop() -> 6, a = [1,null,null,null,null]
a.pop() -> null, a = [1,null,null,null]

if (!a.set(wd::array{})) {
    return 1;
}
log("a.pop()", a.pop(), a);  // a document that holds undefined
// JavaScript inserts the array itself, a cycle; a document inserts a copy of it.
if (!a.set(wd::array{1, 2})) {
    return 1;
}
log("a.splice(0, 1, a)", a.splice(0, 1, a), a);
log("a[0].push({})", a[0].push(wd::object{}), a);  // the copy, not a

a.pop() -> undefined, a = []
a.splice(0, 1, a) -> [1], a = [[1,2],2]
a[0].push({}) -> 3, a = [[1,2,{}],2]

// An object is a sorted map: insert and try_emplace answer the member and whether it was
// inserted, and insert_or_assign assigns to it as JavaScript's o[key] = v does.
wd::result<wd::document> made = wd::parse("{}");
if (made.has_error()) {
    return fail(made);
}
wd::document& doc = *made;
wd::result<wd::object_ref> as_object = doc.root().as_object();
if (as_object.has_error()) {
    return fail(as_object);
}
const wd::object_ref obj = *as_object;

const auto name = obj.insert("name", "Ada");
if (name.has_error()) {
    return fail(name);
}
std::cout << "insert name: " << name->second << '\n';

// A key that is there keeps its value.
const auto again = obj.insert("name", "Grace");
if (again.has_error()) {
    return fail(again);
}
std::cout << "insert name again: " << again->second
          << ", name = " << doc["name"].value_or(std::string_view("nobody")) << '\n';

const auto assigned = obj.insert_or_assign("name", "Augusta Ada");
if (assigned.has_error()) {
    return fail(assigned);
}
std::cout << "insert_or_assign name: " << assigned->second
          << ", name = " << doc["name"].value_or(std::string_view("nobody")) << '\n';

const auto born = obj.try_emplace("born", 1815);
if (born.has_error()) {
    return fail(born);
}
std::cout << "try_emplace born: " << born->second << '\n';

// find answers the member's iterator, or the end; contains answers whether the key is there.
const wd::object_ref::iterator found = obj.find("born");
std::cout << "find born: " << found->second.value_or(std::int64_t{0}) << '\n';
const wd::object_ref::iterator missing = obj.find("nope");
std::cout << "contains born: " << obj.contains("born")
          << ", find nope is end: " << (missing == obj.end()) << '\n';

const auto erased = obj.erase("born");
if (erased.has_error()) {
    return fail(erased);
}
std::cout << "erase born: " << *erased << ", contains born: " << obj.contains("born") << '\n';

// A new key comes last, and so does a key erased and inserted again: the members iterate in
// JavaScript's order, which is the order they were added in.
const auto langs = obj.insert("langs", wd::array{"Analytical", "Note G"});
if (langs.has_error()) {
    return fail(langs);
}
const auto known = obj.insert("known", true);
if (known.has_error()) {
    return fail(known);
}
const auto born_again = obj.insert("born", 1815);
if (born_again.has_error()) {
    return fail(born_again);
}
for (const auto& [key, handle] : obj) {
    std::cout << key << " = " << handle.stringify() << '\n';
}

insert name: true
insert name again: false, name = Ada
insert_or_assign name: false, name = Augusta Ada
try_emplace born: true
find born: 1815
contains born: true, find nope is end: true
erase born: 1, contains born: false
name = "Augusta Ada"
langs = ["Analytical","Note G"]
known = true
born = 1815

// An array is a vector: push_back, emplace_back, insert, erase and resize change it as
// std::vector does, and at checks the index.
wd::result<wd::document> list_made = wd::parse("[1,2,3]");
if (list_made.has_error()) {
    return fail(list_made);
}
wd::document& list_doc = *list_made;
wd::result<wd::array_ref> as_array = list_doc.root().as_array();
if (as_array.has_error()) {
    return fail(as_array);
}
const wd::array_ref list = *as_array;

const auto pushed = list.push_back(4);
if (pushed.has_error()) {
    return fail(pushed);
}
step("push_back(4)", list_doc);

const auto emplaced = list.emplace_back(5);
if (emplaced.has_error()) {
    return fail(emplaced);
}
step("emplace_back(5)", list_doc);

const auto placed = list.insert(std::ranges::next(list.begin(), 1), 9);
if (placed.has_error()) {
    return fail(placed);
}
step("insert(begin + 1, 9)", list_doc);

// erase answers the iterator of the element after the one it removed.
const wd::array_ref::iterator after = list.erase(std::ranges::next(list.begin(), 1));
step("erase(begin + 1)", list_doc);
const wd::value next_element = *after;
std::cout << "erase returns the element after: " << next_element.value_or(std::int64_t{0})
          << '\n';

const auto shrunk = list.resize(3);
if (shrunk.has_error()) {
    return fail(shrunk);
}
step("resize(3)", list_doc);
std::cout << "front " << list.front().value_or(std::int64_t{0}) << ", back "
          << list.back().value_or(std::int64_t{0}) << '\n';

const wd::result<wd::value> third = list.at(2);
if (third.has_error()) {
    return fail(third);
}
std::cout << "at(2) = " << third->value_or(std::int64_t{0}) << '\n';
// An index past the end is an error value, not an undefined element.
const wd::result<wd::value> beyond = list.at(10);
std::cout << "at(10) is errc::range: "
          << (beyond.has_error() && beyond.error() == wd::errc::range) << '\n';

const auto grown = list.resize(5);
if (grown.has_error()) {
    return fail(grown);
}
step("resize(5)", list_doc);

push_back(4) -> [1,2,3,4]
emplace_back(5) -> [1,2,3,4,5]
insert(begin + 1, 9) -> [1,9,2,3,4,5]
erase(begin + 1) -> [1,2,3,4,5]
erase returns the element after: 2
resize(3) -> [1,2,3]
front 1, back 3
at(2) = 3
at(10) is errc::range: true
resize(5) -> [1,2,3,null,null]

// An object and an array are ranges: the standard algorithms and the views over them read
// their members, as they read a vector.
wd::result<wd::document> shop_made = wd::document::create();
if (shop_made.has_error()) {
    return fail(shop_made);
}
wd::document& shop = *shop_made;
const auto shop_set = shop.root().set(wd::object{
    {"prices", wd::array{3, 8, 12, 5, 20}},
    {"stock", wd::object{{"apple", 4}, {"pear", 0}, {"plum", 7}}},
});
if (shop_set.has_error()) {
    return fail(shop_set);
}
wd::result<wd::array_ref> as_prices = shop["prices"].as_array();
if (as_prices.has_error()) {
    return fail(as_prices);
}
const wd::array_ref prices = *as_prices;
wd::result<wd::object_ref> as_stock = shop["stock"].as_object();
if (as_stock.has_error()) {
    return fail(as_stock);
}
const wd::object_ref stock = *as_stock;

const auto above_five = [](const wd::value& v) { return v.value_or(std::int64_t{0}) > 5; };
const auto doubled_value = [](const wd::value& v) { return 2 * v.value_or(std::int64_t{0}); };
std::cout << "prices above 5: " << std::ranges::count_if(prices, above_five) << '\n';
std::cout << "prices above 5, doubled:";
// The view is built and iterated in one statement: a filter view has no const iteration.
for (const std::int64_t twice :
     prices | std::views::filter(above_five) | std::views::transform(doubled_value)) {
    std::cout << ' ' << twice;
}
std::cout << '\n';

const auto empty = std::ranges::find_if(
    stock, [](const auto& member) { return member.second.value_or(std::int64_t{0}) == 0; });
std::cout << "first out of stock: " << empty->first << '\n';

prices above 5: 3
prices above 5, doubled: 16 24 40
first out of stock: pear

// by_key is the same object in key order, by UTF-16 code units, with bounds for ranges of keys.
// A JavaScript program sorts every key to get any of these; here the tree keeps them sorted.
wd::result<wd::document> catalog_made = wd::parse("{}");
if (catalog_made.has_error()) {
    return fail(catalog_made);
}
wd::document& catalog = *catalog_made;
wd::result<wd::object_ref> as_catalog = catalog.root().as_object();
if (as_catalog.has_error()) {
    return fail(as_catalog);
}
const wd::object_ref catalog_obj = *as_catalog;
const std::array<std::string_view, 13> names{
    "user_3", "admin",  "user_1", "guest",  "user_9", "user",   "user_2",
    "owner",  "user_7", "user_5", "user_4", "user_8", "user_6",
};
for (const std::string_view key : names) {
    const auto added = catalog_obj.insert(key, true);
    if (added.has_error()) {
        return fail(added);
    }
}
std::cout << "JavaScript order:";
for (const auto& member : catalog_obj) {
    std::cout << ' ' << member.first;
}
std::cout << '\n';
const auto keys = catalog_obj.by_key();
std::cout << "by_key order:";
for (const auto& member : keys) {
    std::cout << ' ' << member.first;
}
std::cout << '\n';

// The keys with the prefix "user_" lie from its first key up to the first key at or after
// "user`", the character after '_'.
const std::ranges::subrange users(keys.lower_bound("user_"), keys.lower_bound("user`"));
std::cout << "prefix user_: " << std::ranges::distance(users) << " keys, from "
          << users.begin()->first << " to " << std::ranges::prev(users.end())->first << '\n';

const auto [exact, exact_end] = keys.equal_range("user_5");
std::cout << "equal_range user_5: " << std::ranges::distance(exact, exact_end) << " member, "
          << exact->first << '\n';

std::cout << "lower_bound p: " << keys.lower_bound("p")->first << '\n';
const std::ranges::subrange between(keys.lower_bound("g"), keys.lower_bound("v"));
std::cout << "keys from g up to v: " << std::ranges::distance(between) << '\n';

JavaScript order: user_3 admin user_1 guest user_9 user user_2 owner user_7 user_5 user_4 user_8 user_6
by_key order: admin guest owner user user_1 user_2 user_3 user_4 user_5 user_6 user_7 user_8 user_9
prefix user_: 9 keys, from user_1 to user_9
equal_range user_5: 1 member, user_5
lower_bound p: user
keys from g up to v: 12

// The same bytes as stringify, in pieces of at most 8 bytes, to a sink that prints each.
const wd::result<void> written =
    wd::stringify_to(*made, [](std::string_view piece) { std::cout << piece << '|'; }, 0, 8);
if (written.has_error()) {
    return 1;
}
std::cout << '\n';

// A sink that returns a failure stops the writing, and stringify_to returns that failure.
std::string kept;
const wd::result<void> stopped = wd::stringify_to(
    *made,
    [&kept](std::string_view piece) -> wd::result<void> {
        if (!kept.empty()) {
            return wd::errc::capacity;
        }
        kept = piece;
        return {};
    },
    0, 8);
std::cout << kept << " then " << stopped.error().message() << '\n';

{"name":|"Ada","t|ags":["m|ath"],"n|":1500}|
{"name": then no room left

wd::parser p;
// The text {"name":"Ada","tags":["math"],"n":1.5e3}, split inside a string and a number.
for (const std::string_view chunk :
     {R"({"name":"Ad)", R"(a","tags":["ma)", R"(th"],"n":1.)", R"(5e3})"}) {
    if (const wd::result<void> written = p.write(chunk); written.has_error()) {
        std::cout << "error: " << written.error().message() << '\n';
        return 1;
    }
}
wd::result<wd::document> made = p.finish();
if (made.has_error()) {
    std::cout << "error: " << made.error().message() << '\n';
    return 1;
}
std::cout << made->stringify() << '\n';

{"name":"Ada","tags":["math"],"n":1500}

p.reset();
report("write [1,2", p.write("[1,2"), p);
report("write ,]", p.write(",]"), p);  // the error, at the byte where it was found
std::cout << "cause: " << p.cause().message() << '\n';
report("write 3]", p.write("3]"), p);  // a failed parser stays failed
p.reset();
report("write [1]", p.write("[1]"), p);
const wd::result<wd::document> one = p.finish();
std::cout << "finish: " << (one.has_value() ? one->stringify() : one.error().message()) << '\n';
report("write [2]", p.write("[2]"), p);  // a finished parser takes no more text

wd::parse_options limits;
limits.max_depth = 2;
limits.max_bytes = 8;
wd::parser limited(limits);
report("write [[1],", limited.write("[[1],"), limited);
report("write [2]]", limited.write("[2]]"), limited);  // 9 bytes in all
std::cout << "[[[1]]]: " << wd::parse("[[[1]]]", limits).error().message() << '\n';

write [1,2: ok
write ,]: malformed JSON text at 5
cause: syntax error
write 3]: malformed JSON text at 5
write [1]: ok
finish: [1]
write [2]: malformed JSON text at 3
write [[1],: ok
write [2]]: no room left at 5
[[[1]]]: no room left

/**
 A TCP connection on the loopback address: the server's end, written to, and the client's end,
 read from.
*/
struct link {
    link(asio::io_context& io, tcp::acceptor& acceptor) : server(io), client(io) {
        client.connect(acceptor.local_endpoint());
        acceptor.accept(server);
    }

    tcp::socket server;
    tcp::socket client;
};

/**
 Writes `text` to the server's end in pieces of 1, 3, 7, 2 and 13 bytes in turn. After each piece
 the context is drained until the client's parser has consumed it, so the pieces arrive one at a
 time; then the write side is shut down, which the client reads as eof.
*/
bool send_in_pieces(asio::io_context& io, tcp::socket& server, std::string_view text,
                    const wd::stream_parser& parser) {
    constexpr std::array<std::size_t, 5> sizes{1, 3, 7, 2, 13};
    std::uint64_t sent = 0;
    for (std::size_t turn = 0; !text.empty(); ++turn) {
        const std::string_view piece = text.substr(0, sizes[turn % sizes.size()]);
        text.remove_prefix(piece.size());
        asio::write(server, asio::buffer(piece.data(), piece.size()));
        sent += piece.size();
        if (!drain_until(io, [&parser, sent] { return parser.offset() == sent; })) {
            return false;
        }
    }
    server.shutdown(tcp::socket::shutdown_send);
    return true;
}

/**
 Reads the client's documents until eof, awaiting each read in turn. The parser's finish delivers
 its last document before the eof.
*/
asio::awaitable<void> read_in_coroutine(tcp::socket& client, wd::stream_parser& parser) {
    std::string storage;
    const auto buffer = asio::dynamic_buffer(storage);
    for (;;) {
        auto [ec, made] = co_await wd::async_read_document(client, buffer, parser,
                                                           asio::as_tuple(asio::use_awaitable));
        if (ec == asio::error::eof) {
            std::cout << "eof\n";
            co_return;
        }
        if (ec) {
            std::cout << "error: " << ec.message() << '\n';
            co_return;
        }
        std::cout << made.stringify() << '\n';
    }
}

/** Sends NDJSON over a link and reads it in a coroutine, one document printed per line. */
bool ndjson_in_coroutine(asio::io_context& io, tcp::acceptor& acceptor) {
    std::cout << "NDJSON, read in a coroutine:\n";
    link c(io, acceptor);
    wd::stream_options options;
    options.framing = wd::framing::lines;
    wd::stream_parser parser(options);
    constexpr std::string_view text =
        "{\"id\":1,\"tags\":[\"a\",\"b\"]}\n"
        "{\"id\":2,\"ok\":false}\r\n"
        "\n"
        "[3,null]\n"
        "\"last\"";
    bool done = false;
    asio::co_spawn(io, read_in_coroutine(c.client, parser),
                   [&done](const std::exception_ptr&) { done = true; });
    return send_in_pieces(io, c.server, text, parser) && drain_until(io, [&done] { return done; });
}

NDJSON, read in a coroutine:
{"id":1,"tags":["a","b"]}
{"id":2,"ok":false}
[3,null]
"last"
eof

/**
 Reads documents with a callback, each read started after the one before it completes. The next
 read is posted rather than called, so no read is started from inside its own callback.
*/
class callback_reader {
public:
    callback_reader(tcp::socket& client, wd::stream_parser& parser, bool& done)
        : client_(client), parser_(parser), done_(done), buffer_(asio::dynamic_buffer(storage_)) {}

    /** Starts the read of the next document. */
    void start() {
        wd::async_read_document(client_, buffer_, parser_,
                                [this](boost::system::error_code ec, const wd::document& made) {
                                    if (ec == asio::error::eof) {
                                        std::cout << "eof\n";
                                        done_ = true;
                                        return;
                                    }
                                    if (ec) {
                                        std::cout << "error: " << ec.message() << '\n';
                                        done_ = true;
                                        return;
                                    }
                                    std::cout << made.stringify() << '\n';
                                    asio::post(client_.get_executor(), [this] { start(); });
                                });
    }

private:
    tcp::socket& client_;
    wd::stream_parser& parser_;
    bool& done_;
    std::string storage_;
    asio::dynamic_string_buffer<char, std::char_traits<char>, std::allocator<char>> buffer_;
};

/** Sends concatenated JSON over a link and reads it with a callback. */
bool concatenated_with_callback(asio::io_context& io, tcp::acceptor& acceptor) {
    std::cout << "concatenated JSON, read with a callback:\n";
    link c(io, acceptor);
    wd::stream_parser parser;
    constexpr std::string_view text =
        "{\"a\":1}    {\"b\":[true,null]}\n"
        "[1][2]\n"
        "{\n  \"c\": \"x\"\n}\n"
        "42";
    bool done = false;
    callback_reader reader(c.client, parser, done);
    reader.start();
    return send_in_pieces(io, c.server, text, parser) && drain_until(io, [&done] { return done; });
}

concatenated JSON, read with a callback:
{"a":1}
{"b":[true,null]}
[1]
[2]
{"c":"x"}
42
eof

/**
 Writes `bytes` to the socket; false when the write failed, after printing the error.
*/
asio::awaitable<bool> send_bytes(tcp::socket& socket, std::string_view bytes) {
    auto [ec, sent] = co_await asio::async_write(socket, asio::buffer(bytes.data(), bytes.size()),
                                                 asio::as_tuple(asio::use_awaitable));
    if (ec) {
        std::cout << "server: " << ec.message() << '\n';
        co_return false;
    }
    co_return true;
}

/**
 Answers the client's GET: the response header, written by Beast, and the NDJSON body in pieces of
 2, 5, 3 and 11 bytes; the write side is then shut down, which ends the body for the client, since
 the response has no Content-Length.
*/
asio::awaitable<void> serve(tcp::socket& socket) {
    constexpr std::string_view body =
        "{\"id\":1,\"name\":\"ada\"}\n"
        "{\"id\":2,\"tags\":[\"a\",\"b\"]}\n"
        "[3,null]\n"
        "\"last\"";

    beast::multi_buffer buffer;
    http::request<http::empty_body> request;
    auto [read_ec, read_bytes] =
        co_await http::async_read(socket, buffer, request, asio::as_tuple(asio::use_awaitable));
    if (read_ec) {
        std::cout << "server: " << read_ec.message() << '\n';
        co_return;
    }

    // Without a Content-Length the body ends with the connection, so the connection is not kept.
    http::response<http::empty_body> response{http::status::ok, request.version()};
    response.set(http::field::content_type, "application/x-ndjson");
    response.keep_alive(false);
    std::ostringstream header;
    header << response;

    // The header and the body's first piece leave in one write, so the client's first read can take
    // both: the bytes past the header are then in the client's buffer when Beast returns.
    constexpr std::array<std::size_t, 4> sizes{2, 5, 3, 11};
    std::string_view rest = body;
    std::string first = header.str();
    const std::string_view head_piece = rest.substr(0, sizes[0]);
    rest.remove_prefix(head_piece.size());
    first.append(head_piece);
    if (!co_await send_bytes(socket, first)) {
        co_return;
    }
    for (std::size_t turn = 1; !rest.empty(); ++turn) {
        const std::string_view piece = rest.substr(0, sizes[turn % sizes.size()]);
        rest.remove_prefix(piece.size());
        if (!co_await send_bytes(socket, piece)) {
            co_return;
        }
    }
    socket.shutdown(tcp::socket::shutdown_send);
}

beast::multi_buffer buffer;
http::response_parser<http::empty_body> header;
auto [header_ec, header_bytes] = co_await http::async_read_header(
    socket, buffer, header, asio::as_tuple(asio::use_awaitable));
if (header_ec) {
    std::cout << "client: " << header_ec.message() << '\n';
    co_return;
}
const http::response<http::empty_body>& response = header.get();
std::cout << "status " << response.result_int() << ' ' << response.reason() << '\n';
std::cout << "content type " << response[http::field::content_type] << '\n';

// The buffer may already hold the first bytes of the body: whatever Beast read past the header
// stays in it. The reader writes those bytes into the parser before it reads the socket again,
// so the first document is parsed from them, and nothing is copied out of the buffer.
wd::stream_options options;
options.framing = wd::framing::lines;
wd::stream_parser documents(options);
for (;;) {
    auto [ec, made] = co_await wd::async_read_document(socket, buffer, documents,
                                                       asio::as_tuple(asio::use_awaitable));
    if (ec == asio::error::eof) {
        std::cout << "eof\n";
        co_return;
    }
    if (ec) {
        std::cout << "error: " << ec.message() << '\n';
        co_return;
    }
    std::cout << made.stringify() << '\n';
}

status 200 OK
content type application/x-ndjson
{"id":1,"name":"ada"}
{"id":2,"tags":["a","b"]}
[3,null]
"last"
eof

// Sends the text in pieces of 1, 3, 7, 2 and 13 bytes in turn, then shuts the sending side of the
// connection, which is the end of the stream for the reader.
cobalt::task<void> send(tcp::socket& socket, std::string_view text) {
    constexpr std::array<std::size_t, 5> sizes{1, 3, 7, 2, 13};
    for (std::size_t turn = 0; !text.empty(); ++turn) {
        const std::size_t size = std::min(sizes[turn % sizes.size()], text.size());
        co_await asio::async_write(socket, asio::buffer(text.data(), size), cobalt::use_op);
        text.remove_prefix(size);
    }
    socket.shutdown(tcp::socket::shutdown_send);
}

// Reads the documents one at a time and prints each with its number; the end of the stream is
// eof, which is not an error, and a failure of the stream is printed and ends the reader.
cobalt::task<void> read(tcp::socket& socket) {
    wd::stream_options options;
    options.framing = wd::framing::lines;
    wd::stream_parser parser(options);
    std::string storage;
    const auto buffer = asio::dynamic_buffer(storage);
    std::size_t count = 0;
    for (;;) {
        auto next = co_await cobalt::as_result(
            wd::async_read_document(socket, buffer, parser, cobalt::use_op));
        if (next.has_error()) {
            if (next.error() == asio::error::eof) {
                break;
            }
            std::cout << "error: " << next.error().message() << '\n';
            co_return;
        }
        ++count;
        std::cout << count << ' ' << next->stringify() << '\n';
    }
    std::cout << "eof after " << count << " documents\n";
}

// The connection is made before the coroutines start: the listening socket holds it until accept.
cobalt::main co_main(int /*argc*/, char** /*argv*/) {
    const auto executor = cobalt::this_thread::get_executor();
    tcp::acceptor acceptor(executor, tcp::endpoint(asio::ip::address_v4::loopback(), 0));
    tcp::socket writer(executor);
    tcp::socket reader(executor);
    reader.connect(acceptor.local_endpoint());
    acceptor.accept(writer);
    co_await cobalt::join(send(writer, ndjson), read(reader));
    co_return 0;
}

1 {"name":"Ada","tags":["math"],"n":1500}
2 [1,2.5,null,true,"x"]
3 "plain text"
4 {"z":1,"a":2}
5 {"last":true}
eof after 5 documents

/** The bytes of the stream, as the host sends them. */
struct chunk {
    std::string text;
};

/** The end of the stream, which the parser closes. */
struct end_of_stream {};

/** A document the parser completed, moved to the consumer: its image stays where it is. */
struct parsed {
    wd::document value;
};

/** A line the parser dropped, and the line it was on. */
struct rejected {
    std::string reason;
    std::uint64_t line = 0;
};

using message = std::variant<chunk, end_of_stream, parsed, rejected>;

/** Parses the stream, and sends each document, or each line it drops, to the consumer. */
class parser final : public xactor::actor_logic<message> {
public:
    explicit parser(xactor::actor_ref consumer) : consumer_(consumer), stream_(lines_skipping()) {}

    /** The callback the parser hands each document to, and each dropped line's error. */
    auto hand(xactor::turn<message>& turn) {
        return
            [this, &turn](wd::result<wd::document>&& made) { return relay(turn, std::move(made)); };
    }

    xactor::result<void> handle(xactor::turn<message>& turn,
                                const xactor::envelope<message>& cause) override {
        if (const auto* bytes = std::get_if<chunk>(&cause.payload)) {
            const xactor::result<std::size_t> written = stream_.write(bytes->text, hand(turn));
            return as_void(written);
        }
        if (std::holds_alternative<end_of_stream>(cause.payload)) {
            const xactor::result<std::size_t> finished = stream_.finish(hand(turn));
            return as_void(finished);
        }
        return {};
    }

private:
    /** Sends a completed document, or the reason a line was dropped, to the consumer. */
    xactor::result<void> relay(xactor::turn<message>& turn, wd::result<wd::document>&& made) {
        if (made.has_value()) {
            return turn.send(consumer_, parsed{.value = std::move(*made)});
        }
        return turn.send(consumer_,
                         rejected{.reason = made.error().message(), .line = stream_.error_line()});
    }

    /** Keeps the failure of a call of the parser; the documents it completed went on already. */
    static xactor::result<void> as_void(const xactor::result<std::size_t>& counted) {
        if (!counted.has_value()) {
            return {boost::system::in_place_error, counted.error()};
        }
        return {};
    }

    xactor::actor_ref consumer_;
    wd::stream_parser stream_;
};

/** Prints each document with stringify, and each line the parser dropped. */
class consumer final : public xactor::actor_logic<message> {
public:
    xactor::result<void> handle([[maybe_unused]] xactor::turn<message>& turn,
                                const xactor::envelope<message>& cause) override {
        if (const auto* got = std::get_if<parsed>(&cause.payload)) {
            std::cout << got->value.stringify() << '\n';
        }
        if (const auto* dropped = std::get_if<rejected>(&cause.payload)) {
            std::cout << "line " << dropped->line << " dropped: " << dropped->reason << '\n';
        }
        return {};
    }
};

xactor::scheduler<message> system(xactor::budgets{.fuel = 100});
const xactor::result<xactor::actor_ref> printing = xactor::create_actor<consumer>(system);
if (!printing.has_value()) {
    return 1;
}
const xactor::result<xactor::actor_ref> reading =
    xactor::create_actor<parser>(system, *printing);
if (!reading.has_value()) {
    return 1;
}

// Two documents and a line that is not JSON, in chunks cut inside a string, a number and a
// line; a third document with an exponent, and a last one with no newline after it.
const std::array<std::string_view, 7> pieces{
    R"({"name":"Ad)",
    R"(a","born":181)",
    "5}\n{\"name\":\"Gr",
    R"(ace","langs":["COB)",
    "OL\"]}\nnot j",
    "son\n{\"name\":\"Alan\",\"n\":1.5",
    "e3}\n{\"name\":\"Edsger\"}",
};

xactor::fifo_driver<message> driver(system);
std::uint64_t delivery = 0;
for (const std::string_view piece : pieces) {
    const xactor::correlation_id execution{.value = ++delivery};
    if (!system.deliver(*reading, chunk{.text = std::string(piece)}, execution).has_value()) {
        return 1;
    }
    if (!driver.run_until_idle(nullptr).has_value()) {
        return 1;
    }
}
const xactor::correlation_id execution{.value = ++delivery};
if (!system.deliver(*reading, end_of_stream{}, execution).has_value()) {
    return 1;
}
if (!driver.run_until_idle(nullptr).has_value()) {
    return 1;
}

{"name":"Ada","born":1815}
{"name":"Grace","langs":["COBOL"]}
line 3 dropped: malformed JSON text
{"name":"Alan","n":1500}
{"name":"Edsger"}

/**
 A parser of a stream of documents that JavaScript writes to and that calls JavaScript back: the
 callback `on_document` is given each document as the text `stringify` writes, and `on_error` the
 line and the message of an error.

 The framing `lines` is NDJSON, whose bad line is dropped and reported while the stream goes
 on; any other name is a concatenated stream, whose first error ends it.
*/
class json_stream {
public:
    json_stream(const std::string& framing, emscripten::val on_document, emscripten::val on_error)
        : on_document_(std::move(on_document)),
          on_error_(std::move(on_error)),
          parser_(options_of(framing)) {}

    /** Takes a chunk of the stream, and calls back for each document it completes. */
    void write(const std::string& chunk) {
        const wd::result<std::size_t> written =
            parser_.write(chunk, [this](auto made) { deliver(std::move(made)); });
        if (written.has_error()) {
            report(written.error());
        }
    }

    /** Ends the stream, which closes a last line with no newline and a number at the end. */
    void finish() {
        const wd::result<std::size_t> finished =
            parser_.finish([this](auto made) { deliver(std::move(made)); });
        if (finished.has_error()) {
            report(finished.error());
        }
    }

private:
    static wd::stream_options options_of(std::string_view framing) {
        wd::stream_options options;
        if (framing == "lines") {
            options.framing = wd::framing::lines;
            options.on_error = wd::on_error::skip;
        }
        return options;
    }

    /** What the parser gives for each document it completes, or for each line it drops. */
    void deliver(wd::result<wd::document> made) {
        if (made.has_error()) {
            report(made.error());
            return;
        }
        on_document_(made->stringify());
    }

    void report(const boost::system::error_code& error) {
        on_error_(static_cast<unsigned>(parser_.error_line()), error.message());
    }

    emscripten::val on_document_;
    emscripten::val on_error_;
    wd::stream_parser parser_;
};

EMSCRIPTEN_BINDINGS(document_stream_js) {
    emscripten::class_<json_stream>("JsonStream")
        .constructor<const std::string&, emscripten::val, emscripten::val>()
        .function("write", &json_stream::write)
        .function("finish", &json_stream::finish);
}

// Sends a text to a C++ stream in chunks of the given size and prints what each chunk completes.
// The text is encoded first, so that a chunk may end inside a character, as a socket's may.
function send(framing, text, size) {
    let chunk = 0
    const stream = new module.JsonStream(framing,
        document => lines.push(`  chunk ${chunk}: ${document}`),
        (line, message) => lines.push(`  chunk ${chunk}: line ${line} dropped, ${message}`))
    const bytes = encoder.encode(text)
    lines.push(`${framing}, in chunks of ${size} bytes:`)
    for (let at = 0; at < bytes.length; at += size) {
        chunk += 1
        stream.write(bytes.subarray(at, at + size))
    }
    chunk += 1
    stream.finish()
    stream.delete()
}

send('lines', '{"id":1,"tags":["a","b"]}\n{"id":2,"name":"Zoé"}\n{"bad":}\n[3,4.5]\n"last"', 9)
send('concatenated', '{"a":1}    {"b":[2,3]}[4]"five" 6', 4)

lines, in chunks of 9 bytes:
  chunk 3: {"id":1,"tags":["a","b"]}
  chunk 6: {"id":2,"name":"Zoé"}
  chunk 7: line 3 dropped, malformed JSON text
  chunk 8: [3,4.5]
  chunk 9: "last"
concatenated, in chunks of 4 bytes:
  chunk 2: {"a":1}
  chunk 6: {"b":[2,3]}
  chunk 7: [4]
  chunk 8: "five"
  chunk 10: 6

/** A callback that prints what it receives and where. */
constexpr auto print = [](const wd::const_value& v, wd::path_view where) {
    std::cout << "  " << where.to_string() << ": " << v.stringify() << '\n';
};

constexpr std::string_view text =
    R"({"meta":{"page":1},"items":[{"id":"a","qty":2},{"id":"b","qty":3}],"done":true})";
wd::parser p;
std::int64_t total = 0;
const wd::result<void> taken =
    p.on("$.items[*]", [&total](const wd::const_value& item, wd::path_view where) {
        print(item, where);
        total += item["qty"].value_or(std::int64_t{0});
    });
const wd::result<void> kept = p.observe("$.meta", print);
if (taken.has_error() || kept.has_error() || p.write(text).has_error()) {
    return 1;
}
std::cout << "total " << total << '\n';
finished(p);

  $['meta']: {"page":1}
  $['items'][0]: {"id":"a","qty":2}
  $['items'][1]: {"id":"b","qty":3}
total 5
finish: {"meta":{"page":1},"items":[],"done":true}

wd::parser rows;
if (rows.on("$.rows[*][1]", print).has_error() ||
    rows.observe("$.rows[*]", print).has_error() ||
    rows.write(R"({"rows":[[1,2,3],[4,5,6]]})").has_error()) {
    return 1;
}
finished(rows);

  $['rows'][0][1]: 2
  $['rows'][0]: [1,3]
  $['rows'][1][1]: 5
  $['rows'][1]: [4,6]
finish: {"rows":[[1,3],[4,6]]}

wd::parser whole;
if (whole.on("$", print).has_error() || whole.write("[1,2]").has_error()) {
    return 1;
}
finished(whole);  // the root was taken
whole.reset();    // the selectors stay
if (whole.write("12").has_error()) {
    return 1;
}
std::cout << "12 written\n";  // a number at the top ends only with the text
finished(whole);

  $: [1,2]
finish: undefined
12 written
  $: 12
finish: undefined

wd::parser strict;
const wd::result<void> subscribed =
    strict.on("$[*]", [](const wd::const_value& v, wd::path_view) -> wd::result<void> {
        if (!v.is_number()) {
            return wd::errc::type;
        }
        return {};
    });
if (subscribed.has_error()) {
    return 1;
}
std::cout << "write: " << strict.write(R"([1,"two",3])").error().message() << '\n';
finished(strict);  // a failed parser stays failed until reset

write: a value of another kind
finish: a value of another kind

wd::parser stream;
std::uint64_t count = 0;
if (stream.on("$[*]", [&count](const wd::const_value&, wd::path_view) { ++count; })
        .has_error() ||
    stream.write("[").has_error()) {
    return 1;
}
for (std::uint64_t i = 0; i < 100'000; ++i) {
    const std::string element =
        std::string(i == 0 ? "" : ",") + R"({"id":)" + std::to_string(i) + "}";
    if (stream.write(element).has_error()) {
        return 1;
    }
}
if (stream.write("]").has_error()) {
    return 1;
}
const wd::result<wd::document> streamed = stream.finish();
if (streamed.has_error()) {
    return 1;
}
std::cout << count << " delivered, " << streamed->stringify()
          << " left, image under 64 KiB: " << std::boolalpha
          << (streamed->image().size() < 65'536) << '\n';

100000 delivered, [] left, image under 64 KiB: true

wd::result<wd::document> made = wd::parse(R"({"user":"Ada","langs":["Analytical","Note G"]})");
if (made.has_error()) {
    return false;
}
const std::span<const std::byte> image = made->image();
std::cout << image.size() << " bytes, sha-256 " << digest_of(image) << "...\n";

// An owned copy, at another address, which grows as any owned document does.
wd::result<wd::document> copy = wd::from_image(image);
if (copy.has_error() || !(*copy)["user"].set("Lovelace")) {
    return false;
}
std::cout << copy->stringify() << '\n' << made->stringify() << '\n';

4096 bytes, sha-256 ed85084394e7bf7f...
{"user":"Lovelace","langs":["Analytical","Note G"]}
{"user":"Ada","langs":["Analytical","Note G"]}

std::cout << "16 zero bytes: " << wd::from_image(std::array<std::byte, 16>{}).error().message()
          << '\n';
std::cout << "other traits: " << wd::from_image<wd::js_traits>(image).error().message() << '\n';

16 zero bytes: not a document's image
other traits: an image of another format, layout, byte order or traits

// An image written with default_traits is no image of js_traits: the layout tag differs.
if (!refused("js_traits", wd::from_image<wd::js_traits>(image))) {
    return false;
}
// The format version is the header's field at offset 8; another version is not read.
std::span<std::byte> bytes = copy_into(storage, image);
set_field(bytes, offsetof(wd::image_header, version), std::uint32_t{2});
if (!refused("format version 2", wd::open(bytes))) {
    return false;
}
// Bytes that are not an image, and are longer than a header, have no magic.
constexpr std::string_view text =
    "this text is not an image, and it is longer than the 64 bytes of a header";
if (!refused("garbage", wd::from_image(std::as_bytes(std::span(text))))) {
    return false;
}
// Memory that was never written reads as zeros, which are no magic either.
alignas(16) std::array<std::byte, 256> zeros{};
if (!refused("zeroed memory", wd::open(zeros))) {
    return false;
}
// open reads the image in place, so its buffer must be 16-aligned: this one starts 8 bytes in.
bytes = copy_into(std::span<std::byte>(storage).subspan(8), image);
if (!refused("misaligned buffer", wd::open(bytes))) {
    return false;
}
// Cut short, an image that is not sealed is no image at all.
bytes = copy_into(storage, image);
if (!refused("truncated, unsealed", wd::open(bytes.first(bytes.size() - 16)))) {
    return false;
}
// A header that states a size larger than the bytes it is given is refused before it is read.
bytes = copy_into(storage, image);
set_field(bytes, offsetof(wd::image_header, size), std::uint64_t{image.size() + 4096});
if (!refused("size", wd::open(bytes.first(image.size())))) {
    return false;
}
// A header that names a container outside the heap is refused before anything is read there.
bytes = copy_into(storage, image);
set_field(bytes, offsetof(wd::image_header, container), std::uint64_t{image.size()});
return refused("container offset", wd::open(bytes));
// Cut short, a sealed image is a torn write: damaged, not merely no image.
std::span<std::byte> bytes = copy_into(storage, made->image());
if (!refused("truncated, sealed", wd::open(bytes.first(bytes.size() - 16)))) {
    return false;
}

js_traits: incompatible_document, an image of another format, layout, byte order or traits
format version 2: incompatible_document, an image of another format, layout, byte order or traits
garbage: not_a_document, not a document's image
zeroed memory: not_a_document, not a document's image
misaligned buffer: not_a_document, not a document's image
truncated, unsealed: not_a_document, not a document's image
size: not_a_document, not a document's image
container offset: not_a_document, not a document's image
truncated, sealed: damaged_document, a sealed image whose bytes do not match its seal

// A buffer the program owns, such as a browser's memory, 16-aligned.
alignas(16) std::array<std::byte, 8192> buffer{};
using external_document = wd::basic_document<wd::default_traits, wd::external>;
wd::result<external_document> formatted = wd::format(buffer);
if (formatted.has_error() || !formatted->root().set(wd::array{})) {
    return false;
}
wd::basic_value<wd::default_traits, wd::external> list = formatted->root();
std::uint64_t pushed = 0;
wd::result<std::uint64_t> length = list.push("an element of the list");
for (; length.has_value(); length = list.push("an element of the list")) {
    ++pushed;
}
const std::string before = formatted->stringify();
std::cout << pushed << " pushed, then: " << length.error().message() << '\n';
// A failed operation changes nothing of the content.
std::cout << "unchanged: " << std::boolalpha
          << (list.splice(0, 1, wd::array{1, 2, 3}).error() == wd::errc::capacity) << ' '
          << (formatted->stringify() == before) << '\n';

// The buffer holds the image, which another document opens in place.
wd::result<external_document> opened = wd::open(buffer);
if (opened.has_error()) {
    return false;
}
std::cout << "opened in place: " << opened->root().size() << " elements\n";

31 pushed, then: no room left
unchanged: true true
opened in place: 31 elements

// The batch's size is known, so the image is reserved once, before the insertions: they then
// move nothing. Without the reservation, the same insertions grow the image.
constexpr std::int64_t batch = 10'000;
constexpr std::uint64_t bytes_per_member = 256;

wd::result<wd::document> plain_made = wd::parse("{}");
if (plain_made.has_error()) {
    return fail(plain_made);
}
wd::document& plain = *plain_made;
wd::result<wd::object_ref> as_plain = plain.root().as_object();
if (as_plain.has_error()) {
    return fail(as_plain);
}
const std::uint64_t plain_before = plain.capacity();
for (std::int64_t i = 0; i < batch; ++i) {
    const auto added = as_plain->insert("k" + std::to_string(i), i);
    if (added.has_error()) {
        return fail(added);
    }
}
std::cout << "without reserve, " << batch
          << " insertions grew the image: " << (plain.capacity() != plain_before) << '\n';

wd::result<wd::document> reserved_made = wd::parse("{}");
if (reserved_made.has_error()) {
    return fail(reserved_made);
}
wd::document& reserved = *reserved_made;
wd::result<wd::object_ref> as_reserved = reserved.root().as_object();
if (as_reserved.has_error()) {
    return fail(as_reserved);
}
const std::uint64_t reserved_before = reserved.capacity();
const auto reservation = reserved.reserve(static_cast<std::uint64_t>(batch) * bytes_per_member);
if (reservation.has_error()) {
    return fail(reservation);
}
const std::uint64_t reserved_capacity = reserved.capacity();
std::cout << "reserve grew the image: " << (reserved_capacity != reserved_before) << '\n';
for (std::int64_t i = 0; i < batch; ++i) {
    const auto added = as_reserved->insert("k" + std::to_string(i), i);
    if (added.has_error()) {
        return fail(added);
    }
}
std::cout << "after the reserve, " << batch
          << " insertions grew it: " << (reserved.capacity() != reserved_capacity) << '\n';

without reserve, 10000 insertions grew the image: true
reserve grew the image: true
after the reserve, 10000 insertions grew it: false

wd::result<wd::document> made = wd::parse("{}");
if (made.has_error()) {
    return false;
}
for (std::uint64_t i = 0; i < 1000; ++i) {
    if (!(*made)[std::to_string(i)].set(std::string(100, 'x'))) {
        return false;
    }
}
const std::uint64_t grown = made->image().size();
if (!made->root().set(wd::object{{"kept", true}}) || !made->shrink_to_fit()) {
    return false;
}
std::cout << "grown to " << grown << " bytes, shrunk to " << made->image().size() << ": "
          << made->stringify() << '\n';

// Blocks never move: a deep copy into a new document packs the content.
wd::result<wd::document> packed = wd::document::create();
if (packed.has_error() || !packed->root().set(*made)) {
    return false;
}
std::cout << "packed: " << packed->image().size() << " bytes\n";

grown to 524288 bytes, shrunk to 352864: {"kept":true}
packed: 4096 bytes

/** A pool of two blocks: the most the client leases at once. */
wd::image_pool pool_of_two() {
    return wd::image_pool::create(block_bytes, 2).value();
}

/**
 A document parsed from JSON text and shrunk to its size, so that its image holds what the document
 needs and no more.
*/
wd::document document_of(std::string_view text) {
    wd::document made = wd::parse_or_throw(text);
    // A shrink that fails leaves the document as valid as it was, only larger.
    static_cast<void>(made.shrink_to_fit());
    return made;
}

/** The documents the server sends, in order. */
std::vector<wd::document> documents() {
    std::vector<wd::document> sent;
    sent.push_back(document_of(ada));
    sent.push_back(document_of(grace));
    sent.push_back(document_of(alan));
    return sent;
}

/**
 Prints a document as the client holds it: its text, whether its image is sealed, and the blocks the
 pool has free while the image's block is leased.
*/
void print_held(const wd::leased_document<>& image, const wd::image_pool& pool) {
    std::cout << image.get().stringify() << ": " << (image.sealed() ? "sealed" : "not sealed")
              << ", blocks available: " << pool.available() << '\n';
}

/** Sends each document's image, awaiting each write, then shuts the write side down. */
asio::awaitable<void> send_in_coroutine(tcp::socket& server, std::vector<wd::document>& sent) {
    for (wd::document& document : sent) {
        auto [ec] =
            co_await wd::async_write_image(server, document, asio::as_tuple(asio::use_awaitable));
        if (ec) {
            std::cout << "error: " << ec.message() << '\n';
            co_return;
        }
    }
    server.shutdown(tcp::socket::shutdown_send);
}

/**
 Receives images until eof, awaiting each read in turn. Each image is printed while its block is
 leased, and the block goes back when the loop's iteration ends.
*/
asio::awaitable<void> receive_in_coroutine(tcp::socket& client, wd::image_pool& pool, bool& done) {
    for (;;) {
        auto [ec, image] =
            co_await wd::async_read_image(client, pool, asio::as_tuple(asio::use_awaitable));
        if (ec == asio::error::eof) {
            std::cout << "eof, blocks available: " << pool.available() << '\n';
            done = true;
            co_return;
        }
        if (ec) {
            std::cout << "error: " << ec.message() << '\n';
            done = true;
            co_return;
        }
        print_held(image, pool);
    }
}

/** Sends the documents over a link and receives them in a coroutine. */
bool images_in_coroutine(asio::io_context& io, tcp::acceptor& acceptor,
                         std::vector<wd::document>& sent) {
    std::cout << "images, received in a coroutine:\n";
    link c(io, acceptor);
    wd::image_pool pool = pool_of_two();
    bool done = false;
    asio::co_spawn(io, send_in_coroutine(c.server, sent), asio::detached);
    asio::co_spawn(io, receive_in_coroutine(c.client, pool, done), asio::detached);
    return drain_until(io, [&done] { return done; });
}

images, received in a coroutine:
{"name":"Ada","born":1815,"langs":["Analytical"]}: sealed, blocks available: 1
{"name":"Grace","langs":["COBOL"]}: sealed, blocks available: 1
{"name":"Alan","n":1500}: sealed, blocks available: 1
eof, blocks available: 2

/**
 Sends each document's image with async_write_image, the next one started after the last one
 completed, then shuts the write side down. The next write is posted, not called, so that no write
 starts inside the callback of the one before it.
*/
class callback_sender {
public:
    callback_sender(tcp::socket& server, std::vector<wd::document>& sent)
        : server_(server), sent_(sent) {}

    /** Starts the first write. */
    void start() { send_next(); }

private:
    void send_next() {
        if (next_ == sent_.size()) {
            server_.shutdown(tcp::socket::shutdown_send);
            return;
        }
        wd::async_write_image(server_, sent_[next_], [this](boost::system::error_code ec) {
            if (ec) {
                std::cout << "error: " << ec.message() << '\n';
                return;
            }
            ++next_;
            asio::post(server_.get_executor(), [this] { send_next(); });
        });
    }

    tcp::socket& server_;
    std::vector<wd::document>& sent_;
    std::size_t next_ = 0;
};

/**
 Receives images with async_read_image, the next read started after the last one completed, until
 eof. The image is printed inside its callback, where its block is leased; the block goes back when
 the callback returns.
*/
class callback_receiver {
public:
    callback_receiver(tcp::socket& client, wd::image_pool& pool, bool& done)
        : client_(client), pool_(pool), done_(done) {}

    /** Starts the first read. */
    void start() { read_next(); }

private:
    void read_next() {
        wd::async_read_image(
            client_, pool_, [this](boost::system::error_code ec, wd::leased_document<> image) {
                if (ec == asio::error::eof) {
                    std::cout << "eof, blocks available: " << pool_.available() << '\n';
                    done_ = true;
                    return;
                }
                if (ec) {
                    std::cout << "error: " << ec.message() << '\n';
                    done_ = true;
                    return;
                }
                print_held(image, pool_);
                asio::post(client_.get_executor(), [this] { read_next(); });
            });
    }

    tcp::socket& client_;
    wd::image_pool& pool_;
    bool& done_;
};

/** Sends the documents over a link and receives them with a callback. */
bool images_with_callback(asio::io_context& io, tcp::acceptor& acceptor,
                          std::vector<wd::document>& sent) {
    std::cout << "images, received with a callback:\n";
    link c(io, acceptor);
    wd::image_pool pool = pool_of_two();
    bool done = false;
    callback_sender sender(c.server, sent);
    callback_receiver receiver(c.client, pool, done);
    sender.start();
    receiver.start();
    return drain_until(io, [&done] { return done; });
}

images, received with a callback:
{"name":"Ada","born":1815,"langs":["Analytical"]}: sealed, blocks available: 1
{"name":"Grace","langs":["COBOL"]}: sealed, blocks available: 1
{"name":"Alan","n":1500}: sealed, blocks available: 1
eof, blocks available: 2

/**
 Sends the three images in one gather write with async_write_images, then receives them in a
 coroutine, as the first exchange does.

 Tip: the write reads the images in place and completes with the bytes it wrote, so the documents
 stay unchanged until it completes.
*/
bool images_in_one_write(asio::io_context& io, tcp::acceptor& acceptor,
                         std::vector<wd::document>& sent) {
    std::cout << "images, sent in one write:\n";
    link c(io, acceptor);
    wd::image_pool pool = pool_of_two();
    bool done = false;
    wd::async_write_images(c.server, sent, [&c](boost::system::error_code ec, std::size_t bytes) {
        if (ec) {
            std::cout << "error: " << ec.message() << '\n';
        } else {
            std::cout << "written: " << bytes << " bytes\n";
        }
        c.server.shutdown(tcp::socket::shutdown_send);
    });
    asio::co_spawn(io, receive_in_coroutine(c.client, pool, done), asio::detached);
    return drain_until(io, [&done] { return done; });
}

images, sent in one write:
written: 4176 bytes
{"name":"Ada","born":1815,"langs":["Analytical"]}: sealed, blocks available: 1
{"name":"Grace","langs":["COBOL"]}: sealed, blocks available: 1
{"name":"Alan","n":1500}: sealed, blocks available: 1
eof, blocks available: 2

// A sealed image with one byte changed is refused as damaged, by open and by from_image.
const auto found =
    std::ranges::search(bytes, std::as_bytes(std::span(std::string_view("Ada"))));
if (found.empty()) {
    return false;
}
found.front() = std::byte{'a'};
if (!refused("one byte changed", wd::open(bytes))) {
    return false;
}

one byte changed: damaged_document, a sealed image whose bytes do not match its seal

// verify::none skips the seal: the caller trusts the source, and the changed byte reads as is.
wd::result<wd::document> trusted =
    wd::from_image(bytes, wd::default_max_bytes, wd::verify::none);
if (trusted.has_error()) {
    return false;
}
std::cout << "verify::none, accepted: " << trusted->stringify() << '\n';

verify::none, accepted: {"user":"ada","langs":["Analytical","Note G"]}

// An old sealed image left in memory, which a later use wrote over in part, is refused as
// damaged: the seal shows that the bytes changed since the image was written.
bytes = copy_into(storage, made->image());
std::ranges::fill(bytes.subspan(2048, 64), std::byte{0xAA});
if (!refused("reused memory", wd::open(bytes))) {
    return false;
}

// An intact sealed image opens in place, and is still sealed.
bytes = copy_into(storage, made->image());
wd::result<wd::basic_document<wd::default_traits, wd::external>> opened = wd::open(bytes);
if (opened.has_error()) {
    return false;
}
std::cout << "opened, sealed " << std::boolalpha << opened->sealed() << ": "
          << opened->stringify() << '\n';

reused memory: damaged_document, a sealed image whose bytes do not match its seal
opened, sealed true: {"user":"Ada","langs":["Analytical","Note G"]}

// A queue for one producer and one consumer: a push wakes the consumer, and close tells it that
// nothing more comes.
template <class T>
class queue {
public:
    void push(T value) {
        {
            const std::scoped_lock lock(mutex_);
            items_.push_back(std::move(value));
        }
        ready_.notify_one();
    }

    void close() {
        {
            const std::scoped_lock lock(mutex_);
            closed_ = true;
        }
        ready_.notify_all();
    }

    // The oldest value, waiting while the queue is open; nothing once it is closed and empty.
    std::optional<T> pop() {
        std::unique_lock lock(mutex_);
        ready_.wait(lock, [this] { return closed_ || !items_.empty(); });
        if (items_.empty()) {
            return std::nullopt;
        }
        T value = std::move(items_.front());
        items_.pop_front();
        return value;
    }

private:
    std::mutex mutex_;
    std::condition_variable ready_;
    std::deque<T> items_;
    bool closed_ = false;
};

// What the producer sends: a document, and the address of its image before the push. Moving a
// document moves its handle and never the bytes of its image, so the consumer finds them there.
struct parcel {
    wd::document doc;
    const std::byte* image = nullptr;
};

// What the consumer keeps: the documents in arrival order, how many of them still have their image
// where the producer left it, and how many texts failed to parse.
struct exchanged {
    std::vector<wd::document> documents;
    std::size_t same_image = 0;
    std::size_t failed = 0;
};

// The producer parses each text and pushes the document; the consumer keeps each one it receives.
// The two threads write different members of the result, and main reads it after both are joined.
exchanged through_a_queue(std::array<std::string_view, 3> texts) {
    queue<parcel> arrivals;
    exchanged result;
    std::thread consumer([&arrivals, &result] {
        while (std::optional<parcel> next = arrivals.pop()) {
            if (next->doc.image().data() == next->image) {
                ++result.same_image;
            }
            result.documents.push_back(std::move(next->doc));
        }
    });
    std::thread producer([&arrivals, &result, texts] {
        for (const std::string_view text : texts) {
            wd::result<wd::document> parsed = wd::parse(text);
            if (parsed.has_error()) {
                ++result.failed;
                continue;
            }
            const std::byte* image = parsed->image().data();
            arrivals.push(parcel{.doc = std::move(*parsed), .image = image});
        }
        arrivals.close();
    });
    producer.join();
    consumer.join();
    return result;
}

queue: 3 received, 3 with the image the producer sent, 0 failed to parse
{"id":1,"name":"Ada"}
[1,2,3]
{"id":3,"tags":["queue","thread"]}

// The name and birth year of a shared document, read through a const reference: a reader never
// writes.
std::string describe(const wd::shared_document<>& doc) {
    return std::string(doc["name"].value_or(std::string_view("nobody"))) + " was born in " +
           std::to_string(doc["born"].value_or(std::int64_t{0}));
}

// A reader holds its copy until it returns, then drops it in its own thread.
void reader_task(const wd::shared_document<>& holder, std::string& out) {
    out = describe(holder);
}

// The image is copied into a block of the pool; the document it makes holds the one reference.
wd::result<wd::shared_document<>> stored =
    wd::shared_document<>::from_image(pool, parsed->image());
if (stored.has_error()) {
    std::cout << "error: " << stored.error().message() << '\n';
    return 1;
}
wd::shared_document<> shared = std::move(*stored);
std::cout << "stored: use_count " << shared.use_count() << ", " << pool.available() << " of "
          << pool.blocks() << " blocks free\n";

// Each reader gets its copy here, before any thread starts, so the count printed is exact.
constexpr std::size_t reader_count = 4;
std::vector<wd::shared_document<>> copies(reader_count, shared);
std::cout << "with " << reader_count << " readers: use_count " << shared.use_count() << '\n';

std::array<std::string, reader_count> read{};
std::vector<std::thread> readers;
readers.reserve(reader_count);
for (std::size_t i = 0; i < reader_count; ++i) {
    readers.emplace_back(reader_task, std::move(copies[i]), std::ref(read[i]));
}
for (std::thread& reader : readers) {
    reader.join();
}
std::cout << "after the readers: use_count " << shared.use_count() << ", " << pool.available()
          << " of " << pool.blocks() << " blocks free\n";
for (std::size_t i = 0; i < reader_count; ++i) {
    std::cout << "reader " << i << ": " << read[i] << '\n';
}

pool: 7 blocks of 2048 bytes
stored: use_count 1, 6 of 7 blocks free
with 4 readers: use_count 5
after the readers: use_count 1, 6 of 7 blocks free
reader 0: Ada was born in 1815
reader 1: Ada was born in 1815
reader 2: Ada was born in 1815
reader 3: Ada was born in 1815

// make_mutable copies the image into a block of the writer's own when other holders exist, so the
// writer changes its copy and the others keep the document as it was. The library does not
// synchronise writers: a block with several writers, or a writer and readers of that same block,
// must wait for each other by the program's own means, such as a mutex. This writer changes only
// its copy, which no other holder reads.
void writer_task(wd::shared_document<> holder, std::string& out) {
    if (holder.make_mutable().has_error() || holder["name"].set("Lovelace").has_error()) {
        out = "error";
        return;
    }
    out = describe(holder);
}

// The writer takes its reference before its thread starts; its change leaves the shared
// document, which main still reads, as it was.
wd::shared_document<> writer_copy = shared;
std::string written;
std::thread writer(writer_task, std::move(writer_copy), std::ref(written));
writer.join();
std::cout << "writer: " << written << '\n';
std::cout << "after the writer: " << describe(shared) << ", use_count " << shared.use_count()
          << ", " << pool.available() << " of " << pool.blocks() << " blocks free\n";

// The last copy gives its block back to the pool, zeroed.
shared = wd::shared_document<>();
std::cout << "last copy dropped: " << pool.available() << " of " << pool.blocks()
          << " blocks free\n";

writer: Lovelace was born in 1815
after the writer: Ada was born in 1815, use_count 1, 6 of 7 blocks free
last copy dropped: 7 of 7 blocks free

// The room of each block's image, and the blocks of the pool: 8 blocks of 4096 bytes, the size of
// a parsed document's image.
constexpr std::size_t block_bytes = 4096;
constexpr std::size_t blocks = 8;

// The queue holds every offset at once, the end of the stream included.
constexpr std::size_t queue_messages = 8;

// The end of the stream: no document's image is at offset 0.
constexpr std::uint64_t end_of_stream = 0;

// The document a JSON text makes: parsed, its image copied into a block of the pool, then sealed.
wd::result<wd::shared_document<>> sealed_from_text(wd::shared_pool pool, std::string_view text) {
    wd::result<wd::document> parsed = wd::parse(text);
    if (parsed.has_error()) {
        return parsed.error();
    }
    wd::result<wd::shared_document<>> made =
        wd::shared_document<>::from_image(pool, parsed->image());
    if (made.has_error()) {
        return made.error();
    }
    if (made->seal().has_error()) {
        return wd::errc::type;
    }
    return made;
}

// Releases a document's reference and sends its offset, the document now the consumer's.
void hand_over(bip::message_queue& queue, wd::shared_document<>& doc) {
    const std::uint64_t offset = doc.release();
    queue.send(&offset, sizeof offset, 0);
}

// The producer: it makes the documents, hands each over and runs the consumer, which prints them.
int produce(const char* program) {
    const names run = names_for(std::to_string(bip::ipcdetail::get_current_process_id()));
    remove_names(run);
    const remover cleanup(run);

    const wd::result<std::size_t> size = wd::shared_pool::region_bytes(block_bytes, blocks);
    if (size.has_error()) {
        std::cout << "error: " << size.error().message() << '\n';
        return 1;
    }
    bip::shared_memory_object memory(bip::create_only, run.segment.c_str(), bip::read_write);
    memory.truncate(static_cast<bip::offset_t>(*size));
    const bip::mapped_region mapped(memory, bip::read_write);
    const std::span<std::byte> bytes(static_cast<std::byte*>(mapped.get_address()),
                                     mapped.get_size());
    const wd::result<wd::shared_pool> formatted = wd::shared_pool::format(bytes, block_bytes);
    if (formatted.has_error()) {
        std::cout << "error: " << formatted.error().message() << '\n';
        return 1;
    }
    const wd::shared_pool pool = *formatted;
    bip::message_queue queue(bip::create_only, run.queue.c_str(), queue_messages,
                             sizeof(std::uint64_t));

    // Three documents parsed or built in place, and a fourth whose sealed image is then damaged.
    wd::result<wd::shared_document<>> ada =
        sealed_from_text(pool, R"({"name":"Ada","born":1815,"langs":["Analytical"]})");
    wd::result<wd::shared_document<>> grace =
        sealed_from_text(pool, R"({"name":"Grace","langs":["COBOL"]})");
    wd::result<wd::shared_document<>> alan = wd::shared_document<>::create(pool);
    wd::result<wd::shared_document<>> edsger = sealed_from_text(pool, R"({"name":"Edsger"})");
    if (ada.has_error() || grace.has_error() || alan.has_error() || edsger.has_error()) {
        std::cout << "error: a document could not be made\n";
        return 1;
    }
    if (alan->root().set(wd::object{{"name", "Alan"}, {"n", 1500}}).has_error() ||
        alan->seal().has_error()) {
        std::cout << "error: a document could not be made\n";
        return 1;
    }

    // One byte of the sealed image changes after the seal; any change breaks a seal.
    constexpr std::size_t damaged_byte = 100;
    pool.region()[edsger->offset() + damaged_byte] ^= std::byte{0xff};

    hand_over(queue, *ada);
    hand_over(queue, *grace);
    hand_over(queue, *alan);
    hand_over(queue, *edsger);
    queue.send(&end_of_stream, sizeof end_of_stream, 0);

    std::cout << "available before the consumer: " << pool.available() << '\n' << std::flush;

    // The consumer is this program run again, as Boost.Interprocess's own tests run theirs; the
    // parent waits for it, so its output comes before the parent's last line.
    const std::string command =
        "\"" + std::string(program) + "\" consumer " + run.segment + " " + run.queue;
    // NOLINTNEXTLINE(bugprone-command-processor,cert-env33-c)
    if (std::system(command.c_str()) != 0) {
        std::cout << "error: the consumer failed\n";
        return 1;
    }
    std::cout << "available after the consumer: " << pool.available() << '\n';
    return 0;
}

// The consumer: it adopts each offset the producer sends, prints the document and drops it, so
// that its block returns to the pool; an offset the seal refuses is dropped by the pool, unread.
int consume(const char* segment, const char* queue_name) {
    const bip::shared_memory_object memory(bip::open_only, segment, bip::read_write);
    const bip::mapped_region mapped(memory, bip::read_write);
    const std::span<std::byte> bytes(static_cast<std::byte*>(mapped.get_address()),
                                     mapped.get_size());
    const wd::result<wd::shared_pool> attached = wd::shared_pool::attach(bytes);
    if (attached.has_error()) {
        std::cout << "error: " << attached.error().message() << '\n';
        return 1;
    }
    const wd::shared_pool pool = *attached;
    bip::message_queue queue(bip::open_only, queue_name);

    for (;;) {
        std::uint64_t offset = 0;
        std::size_t received = 0;
        unsigned int priority = 0;
        queue.receive(&offset, sizeof offset, received, priority);
        if (offset == end_of_stream) {
            return 0;
        }

        wd::result<wd::shared_document<>> adopted = wd::shared_document<>::adopt(pool, offset);
        if (adopted.has_value()) {
            std::cout << adopted->get().stringify() << ": use count " << adopted->use_count()
                      << '\n';
        } else {
            std::cout << "refused: " << adopted.error().message() << '\n';
            // A refused reference stays counted until it is given back: the pool drops it by its
            // offset, without reading the image, and the block returns to the pool.
            if (const wd::result<void> dropped = pool.drop(offset); dropped.has_error()) {
                std::cout << "error: " << dropped.error().message() << '\n';
                return 1;
            }
        }
    }
}

available before the consumer: 4
{"name":"Ada","born":1815,"langs":["Analytical"]}: use count 1
{"name":"Grace","langs":["COBOL"]}: use count 1
{"name":"Alan","n":1500}: use count 1
refused: a sealed image whose bytes do not match its seal
available after the consumer: 8

constexpr std::string_view text = R"({"b":1,"2":2,"a":3,"1":4})";
wd::result<wd::document> made = wd::parse(text);
if (made.has_error()) {
    return false;
}
std::cout << "1. Key order\n";
print_document(made->stringify());
print_boost(boost_text(text));

1. Key order
  document:   {"1":4,"2":2,"b":1,"a":3}
  Boost.JSON: {"b":1,"2":2,"a":3,"1":4}

constexpr std::string_view text = R"({"b":1,"2":2,"b":3,"1":4})";
wd::result<wd::document> made = wd::parse(text);
if (made.has_error()) {
    return false;
}
std::cout << "6. Repeated keys\n";
print_document(made->stringify());
print_boost(boost_text(text));

6. Repeated keys
  document:   {"1":4,"2":2,"b":3}
  Boost.JSON: {"b":3,"2":2,"1":4}

constexpr std::string_view text = R"({"a":1,"b":2,"c":3,"d":4})";
wd::result<wd::document> made = wd::parse(text);
if (made.has_error() || !made->root().erase("a")) {
    return false;
}
std::cout << "2. Erase keeps the order of the other members\n";
print_document(made->stringify());

// Boost.JSON's erase copies the last member into the gap, so d comes before b and c.
boost::system::error_code ec;
json::value v = json::parse(text, ec);
json::object* object = v.if_object();
if (ec || object == nullptr) {
    return false;
}
object->erase("a");
print_boost(json::serialize(v));

2. Erase keeps the order of the other members
  document:   {"b":2,"c":3,"d":4}
  Boost.JSON: {"d":4,"b":2,"c":3}

constexpr std::string_view text =
    R"([0.1000000000000000000000000000000001,12345678901234567890123])";
wd::result<wd::document> made = wd::parse(text);
if (made.has_error()) {
    return false;
}
// The digits are the ones read; 23 of them are written in JavaScript's exponent form.
std::cout << "3. Exact numbers\n";
print_document(made->stringify());
print_boost(boost_text(text));

3. Exact numbers
  document:   [0.1000000000000000000000000000000001,1.2345678901234567890123e+22]
  Boost.JSON: [1E-1,1.2345678901234568E22]

wd::result<wd::document> made = wd::parse("[1,2,3,4]");
if (made.has_error()) {
    return false;
}
wd::value a = made->root();
const wd::result<std::uint64_t> length = a.unshift(0);
// splice removes two elements from index 1, returns them, and inserts "x" in their place.
const wd::result<wd::document> removed = a.splice(1, 2, "x");
if (length.has_error() || removed.has_error()) {
    return false;
}
std::cout << "4. Array methods\n";
print_document("unshift(0) -> " + std::to_string(*length) + "; splice(1, 2, \"x\") removes " +
               removed->stringify() + "; a = " + a.stringify());

// Boost.JSON's array has insert and erase, which make the same edit but return no removed
// values.
json::array arr{1, 2, 3, 4};
arr.insert(arr.begin(), 0);
arr.erase(arr.begin() + 1, arr.begin() + 3);
arr.insert(arr.begin() + 1, json::value("x"));
print_boost(
    "no splice or unshift; insert and erase make the edit, without the removed "
    "values: a = " +
    json::serialize(arr));

4. Array methods
  document:   unshift(0) -> 5; splice(1, 2, "x") removes [1,2]; a = [0,"x",3,4]
  Boost.JSON: no splice or unshift; insert and erase make the edit, without the removed values: a = [0,"x",3,4]

constexpr std::string_view text = R"({"user":"Ada","langs":["Analytical","Note G"]})";
wd::result<wd::document> made = wd::parse(text);
if (made.has_error()) {
    return false;
}
const std::span<const std::byte> image = made->image();
// A buffer of the program's, 16-aligned, large enough for the image.
alignas(16) std::array<std::byte, 8192> buffer{};
if (image.size() > buffer.size()) {
    return false;
}
std::ranges::copy(image, buffer.begin());
// Opened in place: the buffer becomes the document, with no parse.
wd::result<wd::basic_document<wd::default_traits, wd::external>> opened =
    wd::open(std::span<std::byte>(buffer.data(), image.size()));
if (opened.has_error()) {
    return false;
}
std::cout << "5. An image copied to another buffer and opened in place\n";
print_document(opened->stringify());
// A Boost.JSON value points into its memory resource, so its bytes cannot be copied: the
// only way to move it is to serialize it and parse it again.
print_boost(boost_text(made->stringify()));