@endevops/effect-codec-xml 0.0.1 → 0.1.0-beta.2

package/src/plain-value.ts

@@ -0,0 +1,312 @@
+// A plain value read from an element that carries more than character data.
+//
+// The parser reduces an element with no attributes and no children to its
+// character data, so a field like `Schema.String` is usually handed a bare
+// string. An element that also carries attributes does not reduce: it arrives
+// as a record holding the attributes, the `#text` character data, and any child
+// elements, because the value model has nowhere else to put them:
+//
+//   { "@lang": "en", "#text": "Dune" }
+//
+// Effect's `Schema.toCodecStringTree` derivation knows nothing about the `#text`
+// convention, so where a field wants a scalar it sees a record and fails with an
+// `InvalidType`. This module bridges the two. Walking the derived StringTree AST
+// beside the parsed value:
+//
+//   - a node that wants character data takes the `#text` key and discards the
+//     attributes, because an attribute is not part of the value the schema
+//     describes;
+//   - a node that wants character data but also finds a child element fails,
+//     because a plain value cannot hold one and silently dropping it would lose
+//     a field the document actually carried;
+//   - a node that describes a struct, array or record keeps its record and
+//     recurses, because `@`-prefixed fields and `#text` are ordinary field names
+//     to such a schema;
+//   - a union rewrites its record against each object member in turn, so a plain
+//     value nested under any branch is still read; a repeated field derives as a
+//     union of an array and `undefined`, so a record is also read through the
+//     first array node reachable behind a union;
+//   - an empty element under an array field reads as one empty object when the
+//     member is structural, because an empty array renders as a single empty
+//     element (see `renderRepeated`) and a member the schema requires must still
+//     read; a plain-value member reads as an empty array.
+//
+// The AST is the one `Schema.toCodecStringTree` produces for the source schema,
+// so it is the same shape the decoder is about to read; this pass only rewrites
+// the value, it does not derive a schema.
+
+import { Predicate, Result, SchemaAST } from 'effect';
+
+import type { XmlRecord, XmlValue } from './xml-value.ts';
+
+import { isAttributeKey, TEXT_KEY } from './conventions.ts';
+
+/**
+ * @description Whether an AST describes a structure - a struct, an array, or a union reachable to one - rather than a plain value. A node that describes a
+ * structure keeps a record as a record; a node that does not is where `#text` is read.
+ *
+ * @param ast - The derived StringTree AST to classify.
+ *
+ * @returns Whether the node is structural.
+ */
+const isStructural = (ast: SchemaAST.AST): boolean => {
+  if (SchemaAST.isSuspend(ast)) return isStructural(ast.thunk());
+  if (SchemaAST.isObjects(ast) || SchemaAST.isArrays(ast)) return true;
+  return SchemaAST.isUnion(ast) && ast.types.some(isStructural);
+};
+
+/**
+ * @description The AST a value is read against, with `Suspend` wrappers unwrapped so a recursive schema reaches its node.
+ *
+ * @param ast - The AST to unwrap.
+ *
+ * @returns The first node that is not a `Suspend`.
+ */
+const resolveNode = (ast: SchemaAST.AST): SchemaAST.AST => {
+  let node = ast;
+  while (SchemaAST.isSuspend(node)) node = node.thunk();
+  return node;
+};
+
+/**
+ * @description The AST a record value under one key is read against: the matching property signature, or the first index signature when the object is a record.
+ * `undefined` leaves the value alone, which is what an object with neither describes.
+ *
+ * @param node - The object node.
+ * @param key - The record key.
+ *
+ * @returns The AST for the value, or `undefined`.
+ */
+const fieldAst = (node: SchemaAST.Objects, key: string): SchemaAST.AST | undefined => {
+  const property = node.propertySignatures.find(candidate => candidate.name === key);
+  return property?.type ?? node.indexSignatures[0]?.type;
+};
+
+/**
+ * @description The AST one member of an array is read against: the tuple element at that index, or the array's rest element.
+ *
+ * @param node - The array node.
+ * @param index - The member's index.
+ *
+ * @returns The AST for the member, or `undefined`.
+ */
+const memberAst = (node: SchemaAST.Arrays, index: number): SchemaAST.AST | undefined => node.elements[index] ?? node.rest[0];
+
+/**
+ * @description The array node a value is read against. An optional repeated field derives as a union of an array and `undefined`, so an array node can sit behind
+ * a union rather than at the top; the first one reachable through the union's members is the one a repeated value belongs to.
+ *
+ * @param node - The resolved node to search.
+ *
+ * @returns The array node, or `undefined` when none is reachable.
+ */
+const arrayNode = (node: SchemaAST.AST): SchemaAST.Arrays | undefined => {
+  if (SchemaAST.isArrays(node)) return node;
+  if (SchemaAST.isUnion(node)) {
+    for (const member of node.types) {
+      const found = arrayNode(resolveNode(member));
+      if (found !== undefined) return found;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * @description Whether an array's member is a structure - a struct, an array, or a union reachable to one - rather than a plain value. An empty element under such
+ * an array reads as one empty object, because a structural member cannot be empty character data; a plain-value member reads as an empty array
+ * instead.
+ *
+ * @param node - The array node.
+ *
+ * @returns Whether the member is structural.
+ */
+const arrayMemberIsStructural = (node: SchemaAST.Arrays): boolean => {
+  const member = memberAst(node, 0);
+  return member !== undefined && isStructural(member);
+};
+
+/**
+ * @description The value an empty element under an array field reads as: one empty object when the member is structural, so a member the schema requires still
+ * reads, and an empty array otherwise.
+ *
+ * @param node - The array node.
+ *
+ * @returns The array to decode.
+ */
+const emptyArrayElement = (node: SchemaAST.Arrays): XmlValue => (arrayMemberIsStructural(node) ? [{}] : []);
+
+/**
+ * @description Whether a parsed element carries nothing at all: no character data, no attributes and no children. The parser reduces such an element to an empty
+ * string, and the codec reduces one whose only attributes were namespace declarations to an empty record. An array field reads either as one empty
+ * object or as an empty array, depending on whether its member is structural.
+ *
+ * @param value - The parsed value.
+ *
+ * @returns Whether the element is empty.
+ */
+const isEmptyElement = (value: XmlValue): boolean => value === '' || (Predicate.isReadonlyObject(value) && Object.keys(value).length === 0);
+
+/**
+ * @description The path of a field, for a failure message. The root has no name, so its fields are named on their own.
+ *
+ * @param parent - The parent's path.
+ * @param key - The field's key.
+ *
+ * @returns The field's path.
+ */
+const childPath = (parent: string, key: string): string => (parent === '' ? key : `${parent}.${key}`);
+
+/**
+ * @description Reads the character data of a record that wants a plain value, discarding the attributes around it. A record that also carries a child element is
+ * refused, because a plain value has nowhere to put one and dropping it would lose a field the document carried. A record with no `#text` at all is
+ * left for the decoder to refuse, which reports the attributes it found instead of a value.
+ *
+ * @param record - The record to read.
+ * @param path - The path of the value, for the failure message.
+ *
+ * @returns The `#text` value, or the message describing the child element that makes a plain value impossible.
+ */
+const readCharacterData = (record: XmlRecord, path: string): Result.Result<XmlValue, string> => {
+  if (!(TEXT_KEY in record)) return Result.succeed(record);
+
+  const child = Object.keys(record).find(key => key !== TEXT_KEY && !isAttributeKey(key));
+  if (child !== undefined) {
+    return Result.fail(
+      `the field "${path === '' ? 'root' : path}" wants a plain value, but the element also carries the child element "${child}"; only attributes are discarded alongside ${TEXT_KEY}`
+    );
+  }
+
+  return Result.succeed(record[TEXT_KEY]);
+};
+
+/**
+ * @description Folds the fields of a record against the object node that describes them, so each field is normalized by its own AST.
+ *
+ * @param record - The record to fold.
+ * @param node - The object node.
+ * @param path - The path of the record, for a failure message.
+ *
+ * @returns The folded record, or the first field's failure.
+ */
+const normalizeFields = (record: XmlRecord, node: SchemaAST.Objects, path: string): Result.Result<XmlValue, string> => {
+  const out: Record<string, XmlValue> = {};
+  for (const [key, child] of Object.entries(record)) {
+    const field = fieldAst(node, key);
+    if (field === undefined || child === undefined) {
+      out[key] = child;
+      continue;
+    }
+    const normalized = normalizePlainValue(child, field, childPath(path, key));
+    if (Result.isFailure(normalized)) return normalized;
+    out[key] = normalized.success;
+  }
+  return Result.succeed(out);
+};
+
+/**
+ * @description Folds every member of an array against the array node that describes them. A member that is an empty element - the parser reduces it to an empty
+ * string, or to an empty record once the codec drops the namespace declarations it carried - cannot be a structural member, so it is kept as one
+ * empty object. That is how the renderer writes an empty array, and how a repeated empty tag reads back as one empty object per element.
+ *
+ * @param value - The array to fold.
+ * @param node - The array node.
+ * @param path - The path of the array, for a failure message.
+ *
+ * @returns The folded array, or the first member's failure.
+ */
+const normalizeMembers = (value: ReadonlyArray<XmlValue>, node: SchemaAST.Arrays, path: string): Result.Result<XmlValue, string> => {
+  const out: Array<XmlValue> = [];
+  for (let index = 0; index < value.length; index++) {
+    const element = memberAst(node, index);
+    if (element === undefined) {
+      out.push(value[index]);
+      continue;
+    }
+    if (isEmptyElement(value[index]) && isStructural(element)) {
+      out.push({});
+      continue;
+    }
+    const normalized = normalizePlainValue(value[index], element, `${path}[${index}]`);
+    if (Result.isFailure(normalized)) return normalized;
+    out.push(normalized.success);
+  }
+  return Result.succeed(out);
+};
+
+/**
+ * @description Folds a record against every object member of a union, so a plain value nested under any branch is still read from its character data. Which branch
+ * the value belongs to is the decoder's job, so the first branch that folds the record cleanly wins; a branch that refuses the record - because a
+ * field it wants as a plain value also carries a child element - is skipped. When the union has no object member, or none of them folds the record,
+ * the record is left for the decoder to read as a plain value.
+ *
+ * @param record - The record to fold.
+ * @param node - The union node.
+ * @param path - The path of the record, for a failure message.
+ *
+ * @returns The folded value, the first object member's failure, or the record unchanged.
+ */
+const normalizeUnion = (record: XmlRecord, node: SchemaAST.Union, path: string): Result.Result<XmlValue, string> => {
+  let failure: Result.Result<XmlValue, string> | undefined;
+  let sawObject = false;
+  for (const member of node.types) {
+    const resolved = resolveNode(member);
+    if (!SchemaAST.isObjects(resolved)) continue;
+    sawObject = true;
+    const normalized = normalizeFields(record, resolved, path);
+    if (Result.isSuccess(normalized)) return normalized;
+    failure ??= normalized;
+  }
+  if (failure !== undefined) return failure;
+  return sawObject ? Result.succeed(record) : readCharacterData(record, path);
+};
+
+/**
+ * @description Folds a record against the node that describes it. An object node is folded field by field; a union folds against its object members so a plain
+ * value nested under any branch is read; anything else wants a plain value and reads the character data.
+ *
+ * @param record - The record to fold.
+ * @param node - The resolved node.
+ * @param path - The path of the record, for a failure message.
+ *
+ * @returns The folded value, or the failure that makes it impossible.
+ */
+const normalizeRecord = (record: XmlRecord, node: SchemaAST.AST, path: string): Result.Result<XmlValue, string> => {
+  if (SchemaAST.isObjects(node)) return normalizeFields(record, node, path);
+  if (SchemaAST.isUnion(node)) return normalizeUnion(record, node, path);
+  if (isStructural(node)) return Result.succeed(record);
+  return readCharacterData(record, path);
+};
+
+/**
+ * @description Folds a parsed value against the derived StringTree AST, so a plain value can be read from an element that carries attributes. An empty element
+ * under an array field reads as one empty object when the member is structural, and as an empty array otherwise.
+ *
+ * @param value - The value the parser produced, after namespaces were resolved.
+ * @param ast - The derived StringTree AST the decoder will read the value with.
+ * @param path - The path of this value, for a failure message.
+ *
+ * @returns The value to decode, or the message describing why a plain value could not be read.
+ */
+export const normalizePlainValue = (value: XmlValue, ast: SchemaAST.AST, path: string): Result.Result<XmlValue, string> => {
+  if (Predicate.isUndefined(value)) return Result.succeed(value);
+
+  const node = resolveNode(ast);
+  const arrays = arrayNode(node);
+
+  if (Predicate.isString(value)) {
+    // An empty element under an array field is how the renderer writes an empty array; a structural member still reads as one empty object.
+    if (arrays !== undefined && value === '') return Result.succeed(emptyArrayElement(arrays));
+    return Result.succeed(value);
+  }
+
+  if (Array.isArray(value)) {
+    return arrays !== undefined ? normalizeMembers(value, arrays, path) : Result.succeed(value);
+  }
+
+  if (!Predicate.isReadonlyObject(value)) return Result.succeed(value);
+
+  // The same empty element, after the codec dropped the namespace declarations it carried, arrives as an empty record.
+  if (arrays !== undefined && isEmptyElement(value)) return Result.succeed(emptyArrayElement(arrays));
+
+  return normalizeRecord(value as XmlRecord, node, path);
+};

package/src/render.ts

@@ -7,23 +7,23 @@
 // string.
 //
 // The walk itself is plain synchronous functions rather than a chain of
-// `yield*`es. Publicly `renderXml` is still an `Effect` — it suspends the walk so
+// `yield*`es. Publicly `renderXml` is still an `Effect`: it suspends the walk so
 // it runs lazily, and folds the one failure the walk can report into the typed
-// error channel — but inside a document there is no effect boundary per element
-// or per attribute. A 500-row report is thousands of elements, and a fiber step
-// for each of them was most of what the `render 500 rows` row measured. The
-// typed failure survives: the walk throws an {@link XmlRenderError} and
-// `renderXml` catches it into `Effect.fail`.
+// error channel, but inside a document there is no effect boundary per element
+// or per attribute. A 500-row report is thousands of elements, and one fiber
+// step per element dominated the `render 500 rows` benchmark. The typed failure
+// survives: the walk throws an {@link XmlRenderError} and `renderXml` catches
+// it into `Effect.fail`.
 //
 // Escaping is the part that scales with the size of the document rather than
 // with its structure, and it is written out here rather than delegated, for a
 // measured reason. The entity encoder that used to live beside this package
 // escaped by applying five sequential global replacements, one per character,
 // so a document with a single `&` in twenty thousand characters was scanned
-// five times over to change one byte -- which is what the `render 20k` rows in
-// `bench/codec.bench.ts` measure. The table below covers the same five
-// characters that encoder escaped, and the explicit expectations in
-// `test/render.spec.ts` pin the fast path.
+// five times over to change one byte. The `render 20k` rows in
+// `bench/codec.bench.ts` measure that five-pass cost. The table below covers
+// the same five characters that encoder escaped, and the explicit expectations
+// in `test/render.spec.ts` pin the fast path.
 
 import { Effect, Predicate, Result } from 'effect';
 
@@ -65,11 +65,12 @@ const TEXT_TABLE = buildTable({});
 const ATTRIBUTE_TABLE = buildTable(ATTRIBUTE_WHITESPACE);
 
 /**
- * @description The characters each table escapes, as a pattern rather than as a set of replacement passes. Finding the first one with a pattern is what makes
- * clean text cheap: V8 compiles a single character class into a scan that is several times faster than a JavaScript loop reading the same string a
- * code unit at a time, and clean text is most text. `render 20k of clean text` in `bench/codec.bench.ts` is the row that says so — a hand-written
- * loop over the same twenty thousand characters is roughly two and a half times slower. Neither pattern is global, so `exec` ignores `lastIndex` and
- * always starts at the beginning. One module-level instance of each is therefore safe to reuse, and nothing has to be reset between calls.
+ * @description The characters each table escapes, as a pattern rather than as a set of replacement passes. A single pattern finds the first character that needs
+ * replacing, which keeps clean text cheap: V8 compiles a single character class into a scan that is several times faster than a JavaScript loop
+ * reading the same string a code unit at a time, and clean text is most text. The `render 20k of clean text` benchmark in `bench/codec.bench.ts`
+ * measures that difference: a hand-written loop over the same twenty thousand characters is roughly two and a half times slower. Neither pattern is
+ * global, so `exec` ignores `lastIndex` and always starts at the beginning. One module-level instance of each is therefore safe to reuse, and nothing
+ * has to be reset between calls.
  */
 const TEXT_UNSAFE = /[<>&"']/;
 const ATTRIBUTE_UNSAFE = /[<>&"'\n\r\t]/;
@@ -171,9 +172,9 @@ interface ResolvedOptions {
 /**
  * @description Builds the name resolver for one render. Every element and every attribute name goes through here, and a document repeats names: a thousand
  * `<item>` elements, or the same `id` on every row. A validator that runs a regex per occurrence pays that cost a thousand times for one answer, so
- * the first result is remembered and the rest are lookups. It also keeps the mode and version in one place, which is what stops a caller from
- * resolving a name with different settings than the render it is part of. A cache miss calls {@link resolveNameSync}, which throws an
- * {@link XmlParseError} in `'error'` mode; {@link renderXml} catches it and reports it as an {@link XmlRenderError}.
+ * the first result is remembered and the rest are lookups. Keeping the mode and version in one place also stops a caller from resolving a name with
+ * different settings than the render it is part of. A cache miss calls {@link resolveNameSync}, which throws an {@link XmlParseError} in `'error'`
+ * mode; {@link renderXml} catches it and reports it as an {@link XmlRenderError}.
  *
  * @param options - Resolved render options.
  *
@@ -193,8 +194,7 @@ const makeNamer = (options: Omit<ResolvedOptions, 'namer' | 'lineAt'>): ((name:
 /**
  * @description A boolean option's value, with an absent one read as the default. The three boolean options are spelled through here rather than through a `??` of
  * their own, so the table below reads as a list of what each option _is_ instead of a list of nine separate decisions about what an omitted option
- * means — and so a reader looking for "which options are on by default" finds three words rather than three mixes of `?? true` and `?? false` to
- * read.
+ * means, and a reader looking for "which options are on by default" finds three words rather than three mixes of `?? true` and `?? false` to read.
  *
  * @param value - The option as the caller wrote it, or `undefined` when the caller left it out.
  * @param fallback - The value to use when the caller left it out.
@@ -265,10 +265,10 @@ export const escapeAttribute = (value: string): string => escape(value, ATTRIBUT
 
 /**
  * @description Replaces every character the table has an entry for, in one pass over the string. The pattern finds the first character that needs replacing, and a
- * string with none is handed straight back — which is the common case, and the one the pattern is there to make fast. From there the rest of the
- * string is copied in runs between the replacements rather than a character at a time, so the cost is one pattern scan, one copy, and one
- * concatenation per replacement, rather than a whole pass per character class. Only ASCII is looked up. XML carries every other character natively,
- * and a code unit above 127 has no entity an XML parser is required to know.
+ * string with none is handed straight back. That is the common case, and the pattern exists to keep it fast. From there the rest of the string is
+ * copied in runs between the replacements rather than a character at a time, so the cost is one pattern scan, one copy, and one concatenation per
+ * replacement, rather than a whole pass per character class. Only ASCII is looked up. XML carries every other character natively, and a code unit
+ * above 127 has no entity an XML parser is required to know.
  *
  * @param value - The text to escape.
  * @param pattern - Matches the first character that needs replacing.
@@ -302,7 +302,7 @@ const escape = (value: string, pattern: RegExp, table: ReadonlyArray<string | un
  * A record becomes an element:
  *
  * - `@`-prefixed keys become attributes, the reserved `#text` key becomes character data, and every other key becomes a child element.
- * - An array repeats its name — a document whose root value is an array wraps it in the root element and names each member `itemName`.
+ * - An array repeats its name. A document whose root value is an array wraps it in the root element and names each member `itemName`.
  * - A string is character data. The walk is synchronous, and what can go wrong is reported by throwing an {@link XmlRenderError}; {@link renderXml}
  *   folds that into the effect's typed error channel. A caller not already in an `Effect` runs it with `Effect.runSync`, which throws the failure it
  *   produced.
@@ -379,9 +379,9 @@ const render = (value: XmlValue, options: XmlRenderOptions): string => {
 };
 
 /**
- * @description Renders one named element and its subtree. The value an {@link XmlValue} holds decides which of the four shapes below it takes — a repeated run of
- * children, character data, an absent field, or a record — and each of those is written by a function of its own, so this one is the dispatch rather
- * than the document.
+ * @description Renders one named element and its subtree. The value an {@link XmlValue} holds decides which of the four shapes below it takes: a repeated run of
+ * children, character data, an absent field, or a record. Each of those is written by a function of its own, so this one is the dispatch rather than
+ * the document.
  *
  * @param out - The chunk buffer to append to.
  * @param name - The element name, not yet resolved.
@@ -397,8 +397,8 @@ const renderElement = (out: Array<string>, name: string, value: XmlValue, depth:
     return;
   }
 
-  // An element opens its own line rather than having its caller do it, which is
-  // what keeps a repeated run of children on separate lines. The root is the
+  // An element opens its own line rather than having its caller do it, so a
+  // repeated run of children stays on separate lines. The root is the
   // one element that has nothing in front of it.
   if (options.format && depth > 0) openLine(out, depth, options);
 
@@ -417,7 +417,7 @@ const renderElement = (out: Array<string>, name: string, value: XmlValue, depth:
 
 /**
  * @description Refuses to walk deeper than the render allows. A value can nest without end, and every one of those levels costs a stack frame here, so the cap is
- * checked on the way down rather than trusted to the caller.
+ * checked as the walk descends rather than trusted to the caller.
  *
  * @param depth - The depth about to be written.
  * @param options - Resolved render options.
@@ -459,8 +459,8 @@ const renderRepeated = (out: Array<string>, name: string, members: ReadonlyArray
 
 /**
  * @description Renders an element whose value is character data, or nothing. An empty string is character data that happens to be empty, and an element holding
- * none of it is the same element as one holding nothing at all — as is an `undefined` element, which is an absent one. The renderer is handed values
- * that never went through the schema — a caller building a document by hand — so the absent case is reachable, and an empty element is the honest
+ * none of it is the same element as one holding nothing at all, as is an `undefined` element, which is an absent one. The renderer is handed values
+ * that never went through the schema (a caller building a document by hand), so the absent case is reachable, and an empty element is the correct
  * rendering of both.
  *
  * @param out - The chunk buffer to append to.
@@ -538,9 +538,9 @@ interface Fields {
  * @description One pass over a record's keys, collecting all three roles at once: the attributes are rendered as they are found, the child names are set aside for
  * the pass that writes them, and the text key is left to {@link textOf}. A pass for the attributes, a pass for the children and an index for the text
  * instead walks the keys three times and allocates the key array twice, which on a document of a few thousand elements is thousands of allocations
- * for nothing. Sorting is off by default, and the default path is the one that matters, so the attributes are built as they are found and there is
+ * for nothing. Sorting is off by default, and the default path is the important one, so the attributes are built as they are found and there is
  * nothing to sort. When it is on, the attribute keys are collected instead and rendered afterwards in sorted order, which costs an array per element
- * and buys output that does not depend on the order the fields happened to be declared in.
+ * and gives output independent of the order the fields happened to be declared in.
  *
  * @param record - The element's value.
  * @param options - Resolved render options.
@@ -557,10 +557,10 @@ const collectFields = (record: XmlRecord, options: ResolvedOptions): Fields => {
     const key = keys[i] as string;
     const child = record[key];
 
-    // An absent field is not written at all, which is what keeps an unset
-    // optional attribute out of the document rather than in it as `a=""`, and
-    // an absent child out of it rather than in it as `<a/>`. The text key is
-    // read by `textOf` either way, so skipping it here costs nothing.
+    // An absent field is not written at all, so an unset optional attribute
+    // stays out of the document rather than appearing as `a=""`, and an absent
+    // child stays out rather than appearing as `<a/>`. The text key is read by
+    // `textOf` either way, so skipping it here costs nothing.
     if (child === undefined) continue;
 
     if (isAttributeKey(key)) {
@@ -647,9 +647,9 @@ const openLine = (out: Array<string>, depth: number, options: ResolvedOptions):
 
 /**
  * @description Writes an element with no content, in whichever of the two forms the options ask for. Every path that produces an element with nothing in it goes
- * through here, so the self-closing decision is made in exactly one place. That matters because "nothing in it" arrives four different ways — an
- * empty string, an absent value, an empty array, and a record whose fields are all absent — and four separate decisions are four chances for one of
- * them to write the long form by accident.
+ * through here, so the self-closing decision is made in exactly one place. That is important because "nothing in it" arrives four different ways: an
+ * empty string, an absent value, an empty array, and a record whose fields are all absent. Four separate decisions are four chances for one of them
+ * to write the long form by accident.
  *
  * @param out - The chunk buffer to append to.
  * @param tag - The element's name, already resolved.
@@ -690,8 +690,8 @@ const attributeText = (value: XmlValue): string => {
 };
 
 /**
- * @description Renders a leaf that is not a string as the character data an XML document can hold. A schema-derived value never reaches here —
- * `Schema.toCodecStringTree` has already turned every scalar into a string — so this is for values a caller built by hand. A value with no sensible
+ * @description Renders a leaf that is not a string as the character data an XML document can hold. A schema-derived value never reaches here, because
+ * `Schema.toCodecStringTree` has already turned every scalar into a string, so this is for values a caller built by hand. A value with no sensible
  * text form is rendered as nothing rather than as `[object Object]`, which would silently write a document that parses back to something else.
  *
  * @param value - The leaf to render.

package/src/xml-error.ts

@@ -6,38 +6,38 @@
  *
  * ## Why one error with a `reason`, and not one error per cause
  *
- * The causes would mean a class each, and a caller handling "any of these" would need `catchTags` with all of them. The causes are not independent
- * decisions a caller usually wants to make separately — they are all "this XML input was not acceptable", and the useful split is coarse: a bad
- * _configuration_ versus a bad _document_. So there is one error, and `reason` narrows to the specific cause. Recovery is a `catchReason` away:
+ * The causes would mean a class each, and a caller handling "any of these" would need `catchTags` with all of them. A caller does not usually want to
+ * decide between the causes separately. They are all "this XML input was not acceptable", and the useful split is coarse: a bad _configuration_
+ * versus a bad _document_. So there is one error, and `reason` narrows to the specific cause. Recovery is a `catchReason` away:
  *
  * @example
  *   ```typescript
  *   import { Effect } from 'effect';
- *   import { EntityDecoder, XmlError } from '@endevops/effect-xml-codec';
+ *   import { EntityDecoder, XmlError } from '@endevops/effect-codec-xml';
  *
  *   const limited = new EntityDecoder({ limit: { maxTotalExpansions: 2 } }).decode('&&&').pipe(
  *   Effect.catchReason('XmlError', 'ExpansionLimitExceeded', reason => Effect.succeed(`gave up after ${reason.actual}`)),
  *   );
  *   ```;
  *
- *   The message is kept alongside `reason` and is part of the schema, because the text is load-bearing: the
- *   `[EntityReplacer]` prefix in particular is documented as something callers match on, so it is reproduced exactly
- *   rather than reworded.
+ *   The message is kept alongside `reason` and is part of the schema, because callers depend on the text. The
+ *   `[EntityReplacer]` prefix in particular is documented as something callers match on, so the codec reproduces it exactly
+ *   rather than rewording it.
  */
 
 import { Schema } from 'effect';
 
 /**
  * @description The specific cause of an {@link XmlError}, as a tagged union. The `_tag` on each member is the discriminant `Effect.catchReason` matches on, and
- * the payload is what a handler needs in order to decide or to report. Every member is a case the decoder or the name validators actually raise —
- * there is no catch-all member, so an exhaustive `match` stays exhaustive as causes are added.
+ * the payload is what a handler needs in order to decide or to report. Every member is a case the decoder or the name validators actually raise.
+ * There is no catch-all member, so an exhaustive `match` stays exhaustive as causes are added.
  */
 export const XmlErrorReason = Schema.TaggedUnion({
   /**
    * @description A required argument was `null` or another non-value where the package requires a real one. Raised by the factories that take caller-supplied
-   * input — {@link EntityDecoder.make} among them — when they are handed `null` for an options object that has no meaningful default. It is a
-   * distinct case from the rest because the argument is not _wrong_, it is _absent_, and a caller who wrote `make(null)` meant something the type
-   * system does not allow: a decoder with every default is `make({})`, and saying so here is more useful than silently producing one.
+   * input, {@link EntityDecoder.make} among them, when they are handed `null` for an options object that has no meaningful default. It is a distinct
+   * case from the rest because the argument is not _wrong_, it is _absent_, and a caller who wrote `make(null)` meant something the type system does
+   * not allow. A decoder with every default is `make({})`, and saying so here is more useful than silently producing one.
    */
   MissingOptions: {
     /**
@@ -48,7 +48,7 @@ export const XmlErrorReason = Schema.TaggedUnion({
 
   /**
    * @description A name was checked against one of the five XML name productions and given a different one. Unreachable from TypeScript, where `Production` is a
-   * closed union — it is the guard for untyped JavaScript callers and for values that crossed a boundary as `unknown`.
+   * closed union. It is the guard for untyped JavaScript callers and for values that crossed a boundary as `unknown`.
    */
   InvalidProduction: {
     production: Schema.String,
@@ -78,7 +78,7 @@ export const XmlErrorReason = Schema.TaggedUnion({
    */
   EntityRejected: {
     /**
-     * @description Which registration was in progress. Both are runtime-injected, which is why they share a tier for limit accounting.
+     * @description Which registration was in progress. The runtime injects both, so they share a tier for limit accounting.
      */
     context: Schema.Literals(['external', 'input']),
     /**
@@ -93,7 +93,7 @@ export const XmlErrorReason = Schema.TaggedUnion({
    */
   ExpansionLimitExceeded: {
     /**
-     * @description The count that tripped the limit. Deliberately not reset on failure, so this is the real over-limit total rather than the ceiling.
+     * @description The count that tripped the limit. The counter is not reset on failure, so this is the real over-limit total rather than the ceiling.
      */
     actual: Schema.Number,
     /**
@@ -139,14 +139,14 @@ export const XmlErrorReason = Schema.TaggedUnion({
 export type XmlErrorReason = typeof XmlErrorReason.Type;
 
 /**
- * @description Every failure this package can report, in the `E` channel of the effects that can fail. Carries both a `reason` — the typed, matchable cause — and
+ * @description Every failure this package can report, in the `E` channel of the effects that can fail. Carries both a `reason`, the typed and matchable cause, and
  * a `message`, which is the human-readable form the package has always produced. Both are part of the schema, so an error survives a round-trip
  * through a serialised boundary without losing either.
  *
  * @example
  *   ```typescript
  *   import { Effect } from 'effect';
- *   import { EntityDecoder } from '@endevops/effect-xml-codec';
+ *   import { EntityDecoder } from '@endevops/effect-codec-xml';
  *
  *   const program = Effect.gen(function*() {
  *     const decoder = yield* EntityDecoder.make({});
@@ -162,7 +162,7 @@ export class XmlError extends Schema.TaggedError<XmlError>()('XmlError', {
 
   /**
    * @description Human-readable description. The `[EntityReplacer]` and `[EntityDecoder]` prefixes are reproduced verbatim from the original throw sites, because
-   * they are documented as load-bearing for anything matching on them.
+   * anything matching on them depends on them.
    */
   message: Schema.String,
 }) {}