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

package/dist/entities/entity-decoder.d.ts

@@ -7,8 +7,8 @@ import { Effect } from "effect";
  */
 export type EntityHookAction = 'allow' | 'block' | 'throw';
 /**
- * @description A function-valued entity replacement: the `val` of the legacy `{ regex, val }` form when it is not a string. This decoder cannot use one — a
- * function has no meaning without the regex it was meant to be matched against — so such an entry is dropped at registration rather than expanded.
+ * @description A function-valued entity replacement: the `val` of the legacy `{ regex, val }` form when it is not a string. This decoder cannot use one. A
+ * function has no meaning without the regex it was meant to be matched against, so such an entry is dropped at registration rather than expanded.
  */
 export type EntityValFn = (match: string, captured: string, ...rest: Array<unknown>) => string;
 /**
@@ -41,15 +41,15 @@ export declare const ENTITY_ACTION: Readonly<{
 /**
  * @description Which entity categories count toward the expansion limits.
  *
- * - `'external'` — only input/runtime + persistent external entities. The default, and the only one that ignores the built-in XML entities.
- * - `'base'` — only the built-in XML entities, the caller's `namedEntities`, and numeric references.
- * - `'all'` — every entity regardless of tier.
- * - `Array<'external' | 'base'>` — an explicit combination. An empty array is honoured literally: nothing counts, so the limits can never trip.
+ * - `'external'`: only input/runtime + persistent external entities. The default, and the only one that ignores the built-in XML entities.
+ * - `'base'`: only the built-in XML entities, the caller's `namedEntities`, and numeric references.
+ * - `'all'`: every entity regardless of tier.
+ * - `Array<'external' | 'base'>`: an explicit combination. An empty array is honoured literally: nothing counts, so the limits can never trip.
  */
 export type ApplyLimitsTo = 'external' | 'base' | 'all' | Array<'external' | 'base'>;
 /**
  * @description Ceilings on what a single document's entity references may cost. Both are cumulative across {@link EntityDecoder.decode} calls until
- * {@link EntityDecoder.reset}, and both default to `0`, meaning unlimited. `0` — and any negative or non-numeric value — is unlimited, because the
+ * {@link EntityDecoder.reset}, and both default to `0`, meaning unlimited. `0`, and any negative or non-numeric value, is unlimited, because the
  * runtime tests `> 0` rather than truthiness of the configured number.
  */
 export interface EntityDecoderLimitOptions {
@@ -68,8 +68,8 @@ export interface EntityDecoderLimitOptions {
    */
   maxExpandedLength?: number;
   /**
-   * @description Which tiers count against both limits. Defaults to `'external'`, which is what keeps the built-in entities — including every numeric reference —
-   * from being able to trip a limit on a document the caller already trusts.
+   * @description Which tiers count against both limits. Defaults to `'external'`, which keeps the built-in entities, including every numeric reference, from being
+   * able to trip a limit on a document the caller already trusts.
    *
    * @default 'external'
    */
@@ -81,15 +81,15 @@ export interface EntityDecoderLimitOptions {
  */
 export interface EntityDecoderNCROptions {
   /**
-   * @description The XML version whose codepoint restrictions apply. `1.0` prohibits the C0 controls U+0001–U+001F other than tab, newline and carriage return;
+   * @description The XML version whose codepoint restrictions apply. `1.0` prohibits the C0 controls U+0001 to U+001F other than tab, newline and carriage return;
    * `1.1` does not, since it permits them when written as references. Any value other than `1.1` is read as `1.0`.
    *
    * @default 1.0
    */
   xmlVersion?: 1.0 | 1.1;
   /**
-   * @description The base action for every numeric reference. Codepoint ranges that carry a minimum — surrogates always, the XML 1.0 C0 controls under `1.0`, and
-   * null under `nullNCR` — take the stricter of the two, so this is a floor and not an override.
+   * @description The base action for every numeric reference. Codepoint ranges that carry a minimum (surrogates always, the XML 1.0 C0 controls under `1.0`, and
+   * null under `nullNCR`) take the stricter of the two, so this is a floor and not an override.
    *
    * @default 'allow'
    */
@@ -107,10 +107,10 @@ export interface EntityDecoderNCROptions {
 export interface EntityDecoderOptions {
   /**
    * @description Extra named entities merged into the `base` map alongside the five XML predefined ones. A string value is used directly; a `{ regex, val }` or `{
-   * regx, val }` envelope is unwrapped to its `val`. Anything else — a number, `null`, a function, an envelope whose `val` is a function — is
-   * dropped, leaving the name unresolvable rather than failing the construction. Upstream's documentation says a value containing `&` is skipped
-   * here, to prevent recursive expansion. It is not: the code stores the value unchanged, and only {@link EntityDecoder.addExternalEntity} checks for
-   * `&`. Preserved as-is; see the note on the class.
+   * regx, val }` envelope is unwrapped to its `val`. Anything else (a number, `null`, a function, an envelope whose `val` is a function) is dropped,
+   * leaving the name unresolvable rather than failing the construction. Upstream's documentation says a value containing `&` is skipped here, to
+   * prevent recursive expansion. It is not: the code stores the value unchanged, and only {@link EntityDecoder.addExternalEntity} checks for `&`.
+   * Preserved as-is; see the note on the class.
    *
    * @default null
    */
@@ -120,7 +120,7 @@ export interface EntityDecoderOptions {
   }> | null;
   /**
    * @description Called once on the finished string. Receives `(resolved, original)` and must return a string; return `original` to reject the expansion outright,
-   * or a sanitised form of `resolved` to clean it. It is _not_ called for a string that never reaches the scanning loop — an empty string, a
+   * or a sanitised form of `resolved` to clean it. It is _not_ called for a string that never reaches the scanning loop: an empty string, a
    * non-string, or any string with no `&` in it. A caller relying on `postCheck` to sanitise therefore has to know that a string with no ampersand is
    * never inspected.
    *
@@ -128,8 +128,8 @@ export interface EntityDecoderOptions {
    */
   postCheck?: ((resolved: string, original: string) => string) | null;
   /**
-   * @description Whether numeric references expand at all. Turning it off leaves every one of them in the output verbatim — _except_ the codepoints that carry a
-   * minimum action of `remove` or stricter, which are still handled, because that classification runs first and is what makes the option safe to rely
+   * @description Whether numeric references expand at all. Turning it off leaves every one of them in the output verbatim, _except_ the codepoints that carry a
+   * minimum action of `remove` or stricter, which are still handled, because that classification runs first. This is why the option is safe to rely
    * on.
    *
    * @default true
@@ -144,7 +144,7 @@ export interface EntityDecoderOptions {
   /**
    * @description Names to delete outright, matched the same way as {@link EntityDecoderOptions.leave}. A removed reference is charged to the `external` tier even
    * when the name is a built-in one, so a document full of removed built-ins can trip an `applyLimitsTo: 'external'` limit it would not otherwise be
-   * subject to. Preserved as-is; the only in-code comment claims the charge is for unknown references, which is not what distinguishes them.
+   * subject to. Preserved as-is; the only in-code comment claims the charge is for unknown references, which does not distinguish them.
    *
    * @default [ ]
    */
@@ -167,7 +167,7 @@ export interface EntityDecoderOptions {
   onExternalEntity?: EntityRegistrationHook | null;
   /**
    * @description Called once per entity as it is registered through {@link EntityDecoder.addInputEntities}. Same contract as
-   * {@link EntityDecoderOptions.onExternalEntity}, and unlike it the hook is not the only filter — see the class note on name validation.
+   * {@link EntityDecoderOptions.onExternalEntity}, and unlike it the hook is not the only filter. See the class note on name validation.
    *
    * @default null
    */
@@ -178,25 +178,25 @@ export interface EntityDecoderOptions {
  *
  * ### Entity lookup priority
  *
- * 1. **input / runtime** — injected per document through {@link EntityDecoder.addInputEntities}
- * 2. **persistent external** — set through {@link EntityDecoder.setExternalEntities} and {@link EntityDecoder.addExternalEntity}, surviving
+ * 1. **input / runtime**: injected per document through {@link EntityDecoder.addInputEntities}
+ * 2. **persistent external**: set through {@link EntityDecoder.setExternalEntities} and {@link EntityDecoder.addExternalEntity}, surviving
  *    {@link EntityDecoder.reset}
- * 3. **base** — the five XML predefined entities plus the constructor's `namedEntities` Both input and external resolve as the `external` tier for limit
+ * 3. **base**: the five XML predefined entities plus the constructor's `namedEntities` Both input and external resolve as the `external` tier for limit
  *    purposes, because both are injected at runtime. Numeric references (`&#NNN;`, `&#xHH;`) resolve directly through `String.fromCodePoint` and are
  *    always `base` tier: they cannot recurse, so a limit that counted them would only punish a document that spells its characters out.
  *
  * ### Upstream behaviour preserved
  *
- * Several quirks of the original are kept deliberately, because a consumer's output already depends on them:
+ * Several quirks of the original are kept intentionally, because a consumer's output already depends on them:
  *
  * - A value containing `&` is **not** filtered from `namedEntities` or `setExternalEntities`, contrary to the documentation. Only
  *   {@link EntityDecoder.addExternalEntity} checks, and it drops the entry rather than storing it, so the same name registered either way can resolve
  *   to nothing.
- * - {@link EntityDecoderOptions.postCheck} is skipped entirely for input that never reaches the scan — an empty string, a non-string, or a string with
+ * - {@link EntityDecoderOptions.postCheck} is skipped entirely for input that never reaches the scan: an empty string, a non-string, or a string with
  *   no `&`.
  * - {@link EntityDecoder.decode} returns a non-string argument unchanged, despite being typed `string`.
  * - The expansion-limit errors are prefixed `EntityReplacer`, not `EntityDecoder`.
- * - Nothing in XML 1.0 §2.2 is enforced for U+007F–U+009F or for the U+FFFE/U+FFFF noncharacters, and the sweep for `&` leaves a name of
+ * - Nothing in XML 1.0 §2.2 is enforced for U+007F to U+009F or for the U+FFFE/U+FFFF noncharacters, and the sweep for `&` leaves a name of
  *   {@link MAX_TOKEN_LENGTH} + 1 characters unresolvable.
  * - Numeric references are parsed with `parseInt`, so a leading space, sign, or trailing garbage is accepted: `&# 41;`, `&#x+41;` and `&#41zz;` all
  *   decode, and `&#0x41;` parses as a null reference rather than `A`.
@@ -210,7 +210,7 @@ export interface EntityDecoderOptions {
  *   decoder.addInputEntities({ version: '1.0' });
  *
  *   decoder.decode('&brand; v&version; &copy;'); // 'Acme v1.0 ©'
- *   decoder.decode('&#x26;#38;');               // '&&' — one pass, the output is never re-scanned
+ *   decoder.decode('&#x26;#38;');               // '&&', one pass, the output is never re-scanned
  *
  *   decoder.reset(); // drops the input entities and the counters, keeps the external ones
  *   ```;
@@ -219,7 +219,7 @@ export declare class EntityDecoder {
   #private;
   /**
    * @description Create a decoder. A factory rather than a constructor, because it refuses a `null` options object. Every field is optional, so `null` is not "a
-   * decoder with the defaults" — a caller who wrote it meant something the signature does not allow, and a decoder built from it would be
+   * decoder with the defaults". A caller who wrote it meant something the signature does not allow, and a decoder built from it would be
    * indistinguishable from one built from `{}` while hiding the mistake. Saying so is worth a factory; `EntityDecoderOptions` is a plain object and
    * nothing else about construction can fail.
    *
@@ -236,8 +236,8 @@ export declare class EntityDecoder {
   static make: (options?: EntityDecoderOptions) => Effect.Effect<EntityDecoder, XmlError>;
   /**
    * @description Create a decoder. Every option is resolved here into the flat fields the decode loop reads, so nothing per-reference has to re-derive it. The
-   * options whose wrong type disables them rather than failing the construction — the two hooks, the two name lists — are read through
-   * {@link readHook} and {@link readNameList}, so that rule is written once instead of four times.
+   * options whose wrong type disables them rather than failing the construction (the two hooks, the two name lists) are read through {@link readHook}
+   * and {@link readNameList}, so that rule is written once instead of four times.
    *
    * @param resolved - Configuration, already checked. See {@link EntityDecoderOptions}.
    */
@@ -305,14 +305,14 @@ export declare class EntityDecoder {
   /**
    * @description Expand every entity reference in a string, in one pass. The output is never re-scanned, so no expansion can produce a _second_ one: a registered
    * value that itself contains reference text reaches the caller as that literal text, unexpanded. What the limits bound is the growth of this single
-   * pass — how much one round of expansion can add. Three inputs return before the scan and therefore never reach
+   * pass, meaning how much one round of expansion can add. Three inputs return before the scan and therefore never reach
    * {@link EntityDecoderOptions.postCheck}: a non-string, the empty string, and any string with no `&` in it. The scan itself is `#expandAll`; what
    * this method adds is the three inputs that skip it and the single join of what it collected.
    *
    * @example
    *   ```typescript
    *   import { Effect } from 'effect';
-   *   import { EntityDecoder } from '@endevops/effect-xml-codec';
+   *   import { EntityDecoder } from '@endevops/effect-codec-xml';
    *
    *   const decoder = new EntityDecoder({ namedEntities: { copy: '©' } });
    *   Effect.runSync(Effect.orElseSucceed(decoder.addExternalEntity('brand', 'Acme'), () => undefined));

package/dist/entities/entity-decoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-decoder.d.ts","names":[],"sources":["../../src/entities/entity-decoder.ts"],"mappings":";;;;;;;YA6HY;;;;;YAMA,eAAe,eAAe,qBAAqB,MAAM;;;;;;;;;;;YAYzD,0BAA0B,cAAc,kBAAkB;;;;;;;;;;;;qBAazD,eAAe;EAAW;EAAgB;EAAgB;;;;;;;;;;YAkB3D,8CAA8C;;;;;;iBAOzC;;;;;;;EAOf;;;;;;;EAQA;;;;;;;EAQA,gBAAgB;;;;;;iBAOD;;;;;;;EAOf;;;;;;;EAQA;;;;;;EAOA;;;;;iBAMe;;;;;;;;;;EAUf,gBAAgB;IAA0B,OAAO;IAAQ,cAAc;;;;;;;;;;EAUvE,cAAc,kBAAkB;;;;;;;;EAShC;;;;;;EAOA,QAAQ;;;;;;;;EASR,SAAS;;;;EAKT,QAAQ;;;;EAKR,MAAM;;;;;;;;EASN,mBAAmB;;;;;;;EAQnB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAoSL;;;;;;;;;;;;;;;;;;SAiHJ,OAAI,UAAa,yBAA4B,OAAO,OAAO,eAAe;;;;;;;;UAiB1E;;;;;;;;;;;EAkEP,sBAAmB,MAAA,eAAA,KAAA;IAEqB,OAAA;IAAa,cAAS;SAoB3D,OAAA,aAAA;;;;;;;;;;;;;EAcH,oBAAiB,MAAA,eAAA,aAAA,kBAAA,OAAA,aAAA;;;;;;;;;;;EAqBjB,mBAAgB,MAAA,eAAA,KAAA;IAEuB,MAAA;IAAa,cAAS;;IAAyB,OAAA;IAAa,cAAS;SAkBzG,OAAA,aAAA;;;;;;;EAQH;;;;;;;;;EAeA,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;EA6Bd,SAAM,MAAA,eAAA,gBAAA,OAAA,eAAA"}
+{"version":3,"file":"entity-decoder.d.ts","names":[],"sources":["../../src/entities/entity-decoder.ts"],"mappings":";;;;;;;YA6HY;;;;;YAMA,eAAe,eAAe,qBAAqB,MAAM;;;;;;;;;;;YAYzD,0BAA0B,cAAc,kBAAkB;;;;;;;;;;;;qBAazD,eAAe;EAAW;EAAgB;EAAgB;;;;;;;;;;YAkB3D,8CAA8C;;;;;;iBAOzC;;;;;;;EAOf;;;;;;;EAQA;;;;;;;EAQA,gBAAgB;;;;;;iBAOD;;;;;;;EAOf;;;;;;;EAQA;;;;;;EAOA;;;;;iBAMe;;;;;;;;;;EAUf,gBAAgB;IAA0B,OAAO;IAAQ,cAAc;;;;;;;;;;EAUvE,cAAc,kBAAkB;;;;;;;;EAShC;;;;;;EAOA,QAAQ;;;;;;;;EASR,SAAS;;;;EAKT,QAAQ;;;;EAKR,MAAM;;;;;;;;EASN,mBAAmB;;;;;;;EAQnB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmSL;;;;;;;;;;;;;;;;;;SAiHJ,OAAI,UAAa,yBAA4B,OAAO,OAAO,eAAe;;;;;;;;UAiB1E;;;;;;;;;;;EAkEP,sBAAmB,MAAA,eAAA,KAAA;IAEqB,OAAA;IAAa,cAAS;SAoB3D,OAAA,aAAA;;;;;;;;;;;;;EAcH,oBAAiB,MAAA,eAAA,aAAA,kBAAA,OAAA,aAAA;;;;;;;;;;;EAqBjB,mBAAgB,MAAA,eAAA,KAAA;IAEuB,MAAA;IAAa,cAAS;;IAAyB,OAAA;IAAa,cAAS;SAkBzG,OAAA,aAAA;;;;;;;EAQH;;;;;;;;;EAeA,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;EA6Bd,SAAM,MAAA,eAAA,gBAAA,OAAA,eAAA"}

package/dist/entities/entity-decoder.js

@@ -9,8 +9,8 @@ const CODE_LOWER_X = 120;
 const CODE_UPPER_X = 88;
 /**
 * @description The widest entity name {@link EntityDecoder.decode} will look for, in characters. The forward scan for `;` stops once more than this many characters
-* have passed since the `&`, so a longer run is not treated as one entity — it is copied through as literal text. The bound is what keeps a document
-* with a megabyte of non-entity text between two ampersands from being sliced.
+* have passed since the `&`, so a longer run is not treated as one entity. It is copied through as literal text. The bound keeps a document with a
+* megabyte of non-entity text between two ampersands from being sliced.
 */
 const MAX_TOKEN_LENGTH = 32;
 /**
@@ -19,14 +19,14 @@ const MAX_TOKEN_LENGTH = 32;
 */
 const MAX_CODE_POINT = 1114111;
 /**
-* @description Returned by `#classifyNCR` for a codepoint that carries no minimum action level, which is what distinguishes "no restriction" from
-* `NCR_LEVEL.allow` — both end up expanding, but only the first lets `numericAllowed: false` short-circuit the whole pipeline.
+* @description Returned by `#classifyNCR` for a codepoint that carries no minimum action level. This value distinguishes "no restriction" from `NCR_LEVEL.allow`:
+* both end up expanding, but only the first lets `numericAllowed: false` short-circuit the whole pipeline.
 */
 const NO_MINIMUM_LEVEL = -1;
 /**
 * @description Characters that may not appear in an entity name registered through {@link EntityDecoder.setExternalEntities} or
 * {@link EntityDecoder.addExternalEntity}. A name carrying one of these cannot be written as `&name;` at all, so registration refuses it rather than
-* storing a name no document could ever reference. The set is the upstream string verbatim, including its duplicated backslash — a `Set` discards the
+* storing a name no document could ever reference. The set is the upstream string verbatim, including its duplicated backslash. A `Set` discards the
 * duplicate, so the effective set is the eighteen characters below.
 */
 const SPECIAL_CHARS = /* @__PURE__ */ new Set("!?\\/[]$%{}^&*()<>|+");
@@ -46,7 +46,7 @@ const LIMIT_TIER_BASE = "base";
 const LIMIT_TIER_ALL = "all";
 /**
 * @description The NCR action levels, in severity order. A higher number is a stricter action, and the resolver takes the maximum of the configured level and the
-* minimum a codepoint range imposes, so a range can only ever make an entity stricter than the caller asked for — never more lenient.
+* minimum a codepoint range imposes. A range can therefore only make an entity stricter than the caller asked for, never more lenient.
 */
 const NCR_LEVEL = Object.freeze({
 	allow: 0,
@@ -55,7 +55,7 @@ const NCR_LEVEL = Object.freeze({
 	throw: 3
 });
 /**
-* @description The C0 control codes XML 1.0 §2.2 permits as literal characters. Every other code in U+0001–U+001F is prohibited.
+* @description The C0 control codes XML 1.0 §2.2 permits as literal characters. Every other code in U+0001 to U+001F is prohibited.
 */
 const XML10_ALLOWED_C0 = /* @__PURE__ */ new Set([
 	9,
@@ -86,7 +86,7 @@ const ENTITY_ACTION = Object.freeze({
 *
 * @returns An effect producing the name, unchanged, so the call can be inlined. Fails with {@link XmlError} and the `InvalidEntityName` reason,
 *   carrying the offending character. The `[EntityReplacer]` prefix in the message is preserved verbatim from the original throw, despite naming a
-*   class this decoder does not have — it is load-bearing for anything matching on it.
+*   class this decoder does not have. It is relied on by anything matching the message text.
 */
 const checkEntityName = (name) => {
 	if (name.charCodeAt(0) === CODE_HASH) return Effect.fail(new XmlError({
@@ -109,11 +109,11 @@ const checkEntityName = (name) => {
 };
 /**
 * @description Flatten registration maps into one name to string map, later maps winning over earlier ones for the same name. The result is a null-prototype
-* object, not a `Map`. That is not incidental: a `Map` iterates in pure insertion order, while `Object.keys` lifts array-index-like names to the
-* front in numeric order, and the registration hooks observe that order. A name of `"2"` registered after `"brand"` reaches the hook first here and
-* second in a `Map`.
+* object, not a `Map`. That is intentional. A `Map` iterates in pure insertion order, while `Object.keys` lifts array-index-like names to the front
+* in numeric order, and the registration hooks observe that order. A name of `"2"` registered after `"brand"` reaches the hook first here and second
+* in a `Map`.
 *
-* @param maps - The maps to merge. A falsy entry — `null`, `undefined`, `''`, `0` — contributes nothing rather than throwing.
+* @param maps - The maps to merge. A falsy entry (`null`, `undefined`, `''`, `0`) contributes nothing rather than throwing.
 *
 * @returns A null-prototype object of own string-valued entries. Nothing from `Object.prototype` can be read out of it, so a document naming
 *   `constructor` or `toString` finds nothing. Each entry is read through {@link flattenEntityValue}, so an entry that cannot be reduced to a string
@@ -132,15 +132,15 @@ function mergeEntityMaps(...maps) {
 }
 /**
 * @description Reduce one registration entry to the string a reference to it expands to, or to nothing when the entry is a form the scanner has no use for. Three
-* shapes survive: the string itself, and a `{ regex | regx, val }` envelope whose `val` is a string. Everything else — a number, `null`, `undefined`,
-* a bare function, an envelope whose `val` is a function — has no string to substitute, so the name is dropped and a reference to it comes back out
-* as the text it was written as. Dropping is silent on purpose: the runtime inspects whatever it is handed, and failing the construction over one
+* shapes survive: the string itself, and a `{ regex | regx, val }` envelope whose `val` is a string. Everything else (a number, `null`, `undefined`,
+* a bare function, an envelope whose `val` is a function) has no string to substitute, so the name is dropped and a reference to it comes back out as
+* the text it was written as. Dropping is silent on purpose: the runtime inspects whatever it is handed, and failing the construction over one
 * unreadable entry would take every other entity in the table down with it.
 *
-* @param raw - The entry as it arrived, in whatever shape the caller supplied it — including no entry at all, which a table with a hole in it
+* @param raw - The entry as it arrived, in whatever shape the caller supplied it, including no entry at all, which a table with a hole in it
 *   produces.
 *
-* @returns The replacement string, or `undefined` when the entry cannot be read. A name registered to the empty string yields `''`, which is why
+* @returns The replacement string, or `undefined` when the entry cannot be read. A name registered to the empty string yields `''`. That is why
 *   callers compare against `undefined` rather than testing for emptiness.
 */
 function flattenEntityValue(raw) {
@@ -155,7 +155,7 @@ function flattenEntityValue(raw) {
 * @param map - The map to read.
 * @param key - The entity name.
 *
-* @returns The registered string, or `undefined` when the name is not an own key. A name registered to the empty string returns `''`, which is why
+* @returns The registered string, or `undefined` when the name is not an own key. A name registered to the empty string returns `''`. That is why
 *   callers must compare against `undefined` rather than test for emptiness.
 */
 function ownEntity(map, key) {
@@ -168,8 +168,7 @@ function ownEntity(map, key) {
 * @param raw - The configured value.
 *
 * @returns The tier set. An unrecognised string falls back to `external` rather than to no filtering at all, so a typo cannot silently disable the
-*   limits. An array is taken as given, which is why an empty array disables limit accounting entirely while an empty string falls back to
-*   `external`.
+*   limits. An array is taken as given. An empty array therefore disables limit accounting entirely, while an empty string falls back to `external`.
 */
 function parseLimitTiers(raw) {
 	if (!raw || raw === LIMIT_TIER_EXTERNAL) return /* @__PURE__ */ new Set([LIMIT_TIER_EXTERNAL]);
@@ -229,7 +228,7 @@ function readPostCheck(raw) {
 *
 * @param raw - The configured hook, or nothing.
 *
-* @returns The hook itself, or `null` for an absent option and for a value that is not a function. `null` is what lets every registration path ask
+* @returns The hook itself, or `null` for an absent option and for a value that is not a function. `null` lets every registration path ask
 *   unconditionally: a hook that is not there accepts.
 */
 function readHook(raw) {
@@ -238,9 +237,9 @@ function readHook(raw) {
 }
 /**
 * @description Read one of the two entity-name lists as a set, under the same missing-value rule as the other options: absent is empty, not an error. The
-* `Array.isArray` test rather than a truthiness one is what keeps a mistyped list from reaching `new Set` and throwing there, so a caller's typo
-* disables the list instead of taking the decoder down. Matching against a set is also why a name in both lists is decided by the order
-* {@link EntityDecoder.decode} consults them in, not by the order the caller wrote them in.
+* `Array.isArray` test rather than a truthiness one keeps a mistyped list from reaching `new Set` and throwing there, so a caller's typo disables the
+* list instead of taking the decoder down. Matching against a set also means a name in both lists is decided by the order {@link EntityDecoder.decode}
+* consults them in, not by the order the caller wrote them in.
 *
 * @param raw - The configured list, or nothing.
 *
@@ -272,25 +271,25 @@ function scanTokenEnd(str, ampersand) {
 *
 * ### Entity lookup priority
 *
-* 1. **input / runtime** — injected per document through {@link EntityDecoder.addInputEntities}
-* 2. **persistent external** — set through {@link EntityDecoder.setExternalEntities} and {@link EntityDecoder.addExternalEntity}, surviving
+* 1. **input / runtime**: injected per document through {@link EntityDecoder.addInputEntities}
+* 2. **persistent external**: set through {@link EntityDecoder.setExternalEntities} and {@link EntityDecoder.addExternalEntity}, surviving
 *    {@link EntityDecoder.reset}
-* 3. **base** — the five XML predefined entities plus the constructor's `namedEntities` Both input and external resolve as the `external` tier for limit
+* 3. **base**: the five XML predefined entities plus the constructor's `namedEntities` Both input and external resolve as the `external` tier for limit
 *    purposes, because both are injected at runtime. Numeric references (`&#NNN;`, `&#xHH;`) resolve directly through `String.fromCodePoint` and are
 *    always `base` tier: they cannot recurse, so a limit that counted them would only punish a document that spells its characters out.
 *
 * ### Upstream behaviour preserved
 *
-* Several quirks of the original are kept deliberately, because a consumer's output already depends on them:
+* Several quirks of the original are kept intentionally, because a consumer's output already depends on them:
 *
 * - A value containing `&` is **not** filtered from `namedEntities` or `setExternalEntities`, contrary to the documentation. Only
 *   {@link EntityDecoder.addExternalEntity} checks, and it drops the entry rather than storing it, so the same name registered either way can resolve
 *   to nothing.
-* - {@link EntityDecoderOptions.postCheck} is skipped entirely for input that never reaches the scan — an empty string, a non-string, or a string with
+* - {@link EntityDecoderOptions.postCheck} is skipped entirely for input that never reaches the scan: an empty string, a non-string, or a string with
 *   no `&`.
 * - {@link EntityDecoder.decode} returns a non-string argument unchanged, despite being typed `string`.
 * - The expansion-limit errors are prefixed `EntityReplacer`, not `EntityDecoder`.
-* - Nothing in XML 1.0 §2.2 is enforced for U+007F–U+009F or for the U+FFFE/U+FFFF noncharacters, and the sweep for `&` leaves a name of
+* - Nothing in XML 1.0 §2.2 is enforced for U+007F to U+009F or for the U+FFFE/U+FFFF noncharacters, and the sweep for `&` leaves a name of
 *   {@link MAX_TOKEN_LENGTH} + 1 characters unresolvable.
 * - Numeric references are parsed with `parseInt`, so a leading space, sign, or trailing garbage is accepted: `&# 41;`, `&#x+41;` and `&#41zz;` all
 *   decode, and `&#0x41;` parses as a null reference rather than `A`.
@@ -304,7 +303,7 @@ function scanTokenEnd(str, ampersand) {
 *   decoder.addInputEntities({ version: '1.0' });
 *
 *   decoder.decode('&brand; v&version; &copy;'); // 'Acme v1.0 ©'
-*   decoder.decode('&#x26;#38;');               // '&&' — one pass, the output is never re-scanned
+*   decoder.decode('&#x26;#38;');               // '&&', one pass, the output is never re-scanned
 *
 *   decoder.reset(); // drops the input entities and the counters, keeps the external ones
 *   ```;
@@ -320,7 +319,7 @@ var EntityDecoder = class EntityDecoder {
 	*/
 	#maxExpandedLength;
 	/**
-	* @description {@link EntityDecoderOptions.postCheck}, or the identity function — so the decode loop can call it unconditionally on the path that actually
+	* @description {@link EntityDecoderOptions.postCheck}, or the identity function. That lets the decode loop call it unconditionally on the path that actually
 	* scanned, and never on the two fast paths that return early.
 	*/
 	#postCheck;
@@ -339,7 +338,7 @@ var EntityDecoder = class EntityDecoder {
 	#baseMap;
 	/**
 	* @description Persistent external entities, as a null-prototype object. Replaced wholesale by {@link EntityDecoder.setExternalEntities} and added to by
-	* {@link EntityDecoder.addExternalEntity}, and never touched by {@link EntityDecoder.reset} — that is the whole distinction from the input map.
+	* {@link EntityDecoder.addExternalEntity}, and never touched by {@link EntityDecoder.reset}. That is the whole distinction from the input map.
 	*/
 	#externalMap;
 	/**
@@ -348,8 +347,8 @@ var EntityDecoder = class EntityDecoder {
 	*/
 	#inputMap;
 	/**
-	* @description Tracked expansions since the last reset. Cumulative across {@link EntityDecoder.decode} calls, which is what makes a limit a per-document budget
-	* rather than a per-call one. Deliberately not reset by a thrown limit error, so the over-limit count is what the error message reports.
+	* @description Tracked expansions since the last reset. Cumulative across {@link EntityDecoder.decode} calls, which makes a limit a per-document budget rather
+	* than a per-call one. Intentionally not reset by a thrown limit error, so the error message reports the over-limit count.
 	*/
 	#totalExpansions;
 	/**
@@ -391,7 +390,7 @@ var EntityDecoder = class EntityDecoder {
 	#onInputEntity;
 	/**
 	* @description Create a decoder. A factory rather than a constructor, because it refuses a `null` options object. Every field is optional, so `null` is not "a
-	* decoder with the defaults" — a caller who wrote it meant something the signature does not allow, and a decoder built from it would be
+	* decoder with the defaults". A caller who wrote it meant something the signature does not allow, and a decoder built from it would be
 	* indistinguishable from one built from `{}` while hiding the mistake. Saying so is worth a factory; `EntityDecoderOptions` is a plain object and
 	* nothing else about construction can fail.
 	*
@@ -414,8 +413,8 @@ var EntityDecoder = class EntityDecoder {
 	})) : Effect.succeed(new EntityDecoder(options));
 	/**
 	* @description Create a decoder. Every option is resolved here into the flat fields the decode loop reads, so nothing per-reference has to re-derive it. The
-	* options whose wrong type disables them rather than failing the construction — the two hooks, the two name lists — are read through
-	* {@link readHook} and {@link readNameList}, so that rule is written once instead of four times.
+	* options whose wrong type disables them rather than failing the construction (the two hooks, the two name lists) are read through {@link readHook}
+	* and {@link readNameList}, so that rule is written once instead of four times.
 	*
 	* @param resolved - Configuration, already checked. See {@link EntityDecoderOptions}.
 	*/
@@ -443,7 +442,7 @@ var EntityDecoder = class EntityDecoder {
 	/**
 	* @description Ask a registration hook about one name and value.
 	*
-	* @param hook - The hook, or `null`. A `null` hook accepts, which is what lets {@link EntityDecoder.addExternalEntity} call this unconditionally.
+	* @param hook - The hook, or `null`. A `null` hook accepts, so {@link EntityDecoder.addExternalEntity} can call this unconditionally.
 	* @param name - The entity name, without `&` or `;`.
 	* @param value - The resolved value, after any `{ regex, val }` envelope was unwrapped.
 	* @param context - Which registration is in progress, for the error message.
@@ -552,14 +551,14 @@ var EntityDecoder = class EntityDecoder {
 	/**
 	* @description Expand every entity reference in a string, in one pass. The output is never re-scanned, so no expansion can produce a _second_ one: a registered
 	* value that itself contains reference text reaches the caller as that literal text, unexpanded. What the limits bound is the growth of this single
-	* pass — how much one round of expansion can add. Three inputs return before the scan and therefore never reach
+	* pass, meaning how much one round of expansion can add. Three inputs return before the scan and therefore never reach
 	* {@link EntityDecoderOptions.postCheck}: a non-string, the empty string, and any string with no `&` in it. The scan itself is `#expandAll`; what
 	* this method adds is the three inputs that skip it and the single join of what it collected.
 	*
 	* @example
 	*   ```typescript
 	*   import { Effect } from 'effect';
-	*   import { EntityDecoder } from '@endevops/effect-xml-codec';
+	*   import { EntityDecoder } from '@endevops/effect-codec-xml';
 	*
 	*   const decoder = new EntityDecoder({ namedEntities: { copy: '©' } });
 	*   Effect.runSync(Effect.orElseSucceed(decoder.addExternalEntity('brand', 'Acme'), () => undefined));
@@ -584,15 +583,15 @@ var EntityDecoder = class EntityDecoder {
 	/**
 	* @description Walk the string once and collect the pieces of every reference that resolved. Two advance rules make the walk terminate and keep it correct: an
 	* `&` that turns out to open nothing moves the cursor by one character rather than to the end of its run, so a second `&` in the same text is still
-	* found; and a reference that did resolve moves it to just past the `;`, so the text that was substituted for it is never looked at again — that is
-	* what makes the pass single, and a registered value containing `&` cannot expand a second level. What a reference becomes is `#resolveToken`'s to
-	* decide and what it costs is `#chargeExpansion`'s to apply, which leaves the scanning here as the only thing with a rule of its own.
+	* found; and a reference that did resolve moves it to just past the `;`, so the text that was substituted for it is never looked at again. The pass
+	* stays single because of that, and a registered value containing `&` cannot expand a second level. What a reference becomes is `#resolveToken`'s
+	* to decide and what it costs is `#chargeExpansion`'s to apply, which leaves the scanning here as the only thing with a rule of its own.
 	*
 	* @param str - The string to expand. It always holds at least one `&` and is never empty, or the caller would have returned before reaching the
 	*   walk.
 	*
 	* @returns An effect producing the pieces in order. The array is empty exactly when nothing was replaced, which the caller reads as "the input is
-	*   its own result". Fails with {@link XmlError} and the reason the offending reference carries — `ProhibitedCharacterReference`,
+	*   its own result". Fails with {@link XmlError} and the reason the offending reference carries: `ProhibitedCharacterReference`,
 	*   `ExpansionLimitExceeded` or `ExpandedLengthLimitExceeded`.
 	*/
 	#expandAll = Effect.fnUntraced(function* (str) {
@@ -628,19 +627,19 @@ var EntityDecoder = class EntityDecoder {
 	/**
 	* @description Decide what one reference expands to. The lists and maps are consulted in the one order the runtime uses, and the first that matches wins:
 	*
-	* 1. `remove` — deleted outright, without the name ever being resolved, so the name need not exist.
-	* 2. `leave` — emitted as the original `&token;`, and charged to nothing.
-	* 3. A `#`-prefixed token — the numeric pipeline, which is the only one of the four that can fail. Classification runs before any decision about
+	* 1. `remove`: deleted outright, without the name ever being resolved, so the name need not exist.
+	* 2. `leave`: emitted as the original `&token;`, and charged to nothing.
+	* 3. A `#`-prefixed token: the numeric pipeline, which is the only one of the four that can fail. Classification runs before any decision about
 	*    `numericAllowed`, because the ranges that carry a minimum have to be caught whichever way that option is set.
-	* 4. Anything else — resolved against the input map, then the external map, then the base map.
+	* 4. Anything else: resolved against the input map, then the external map, then the base map.
 	*
 	* @param token - The reference's token, e.g. `brand` or `#38`, with the `&` and the `;` already stripped. Never empty: the scanner drops `&;`
 	*   before calling.
 	*
 	* @returns An effect producing what the reference expands to and the tier to charge it to, or `undefined` to leave it as written and charge it
-	*   nothing. `undefined` covers all three ways of leaving a reference alone — a listed `leave` name, a numeric reference that is out of range, and
-	*   a name registered nowhere — and none of them is distinguishable from outside. Fails with {@link XmlError} and the
-	*   `ProhibitedCharacterReference` reason when the numeric policy throws on the codepoint.
+	*   nothing. `undefined` covers all three ways of leaving a reference alone (a listed `leave` name, a numeric reference that is out of range, and a
+	*   name registered nowhere), and none of them is distinguishable from outside. Fails with {@link XmlError} and the `ProhibitedCharacterReference`
+	*   reason when the numeric policy throws on the codepoint.
 	*/
 	#resolveToken = Effect.fnUntraced(function* (token) {
 		if (this.#removeSet.has(token)) return {
@@ -681,9 +680,9 @@ var EntityDecoder = class EntityDecoder {
 	});
 	/**
 	* @description Add one expansion to the running total and compare it against {@link EntityDecoderLimitOptions.maxTotalExpansions}. The comparison is `>` rather
-	* than `>=`, so a limit of `n` allows exactly `n` expansions and throws on the `n + 1`th. That is a contract — the option's own documentation
-	* states it — and the kind of off-by-one a tidy-up changes by accident. The counter is deliberately not reset before failing: the over-limit total
-	* is what the error message reports, and {@link EntityDecoder.reset} is the caller's way to start a new document.
+	* than `>=`, so a limit of `n` allows exactly `n` expansions and throws on the `n + 1`th. That is a contract, and the option's own documentation
+	* states it. It is also the kind of off-by-one a tidy-up changes by accident. The counter is intentionally not reset before failing: the over-limit
+	* total reports the over-limit total, and {@link EntityDecoder.reset} is the caller's way to start a new document.
 	*
 	* @returns An effect that fails with {@link XmlError} and the `ExpansionLimitExceeded` reason once the count is past the ceiling, and succeeds
 	*   otherwise. The `EntityReplacer` prefix in the message is preserved verbatim from the original throw, despite naming a class this decoder does
@@ -704,7 +703,7 @@ var EntityDecoder = class EntityDecoder {
 	/**
 	* @description Add one expansion's surplus to the running total and compare it against {@link EntityDecoderLimitOptions.maxExpandedLength}. Only the surplus
 	* counts, and only upward: a reference whose replacement is no longer than the `&token;` it replaces contributes zero, and a shrinking one
-	* contributes nothing and cannot trip the limit at all. That is what makes the ceiling a bound on growth rather than on document size.
+	* contributes nothing and cannot trip the limit at all. That keeps the ceiling a bound on growth rather than on document size.
 	*
 	* @param token - The reference's token, with the `&` and `;` stripped. The two delimiters count towards what the expansion displaced.
 	* @param replacement - What the reference expanded to, including `''` for a removal.
@@ -730,8 +729,8 @@ var EntityDecoder = class EntityDecoder {
 	/**
 	* @description Decide whether an entity of a given tier is charged against the limits.
 	*
-	* @param tier - The tier the replacement is charged to. Every expansion that reaches here carries one — a name deleted before it was ever resolved
-	*   still carries the `external` tier — so there is no absent case to answer.
+	* @param tier - The tier the replacement is charged to. Every expansion that reaches here carries one (a name deleted before it was ever resolved
+	*   still carries the `external` tier), so there is no absent case to answer.
 	*
 	* @returns `true` when it counts. `'all'` short-circuits, so a filter naming every tier charges everything regardless of which map it came from.
 	*/
@@ -767,9 +766,9 @@ var EntityDecoder = class EntityDecoder {
 	/**
 	* @description Find the strictest action a codepoint's range requires. Checked in this order:
 	*
-	* 1. U+0000 — governed by `nullNCR`, already clamped to `remove` or stricter
-	* 2. U+D800–U+DFFF — surrogates, always `remove`, under every policy and both XML versions
-	* 3. U+0001–U+001F other than tab, newline, carriage return — XML 1.0 only, `remove` Nothing else is classified. U+007F–U+009F (C1) and the
+	* 1. U+0000: governed by `nullNCR`, already clamped to `remove` or stricter
+	* 2. U+D800 to U+DFFF: surrogates, always `remove`, under every policy and both XML versions
+	* 3. U+0001 to U+001F other than tab, newline, carriage return: XML 1.0 only, `remove` Nothing else is classified. U+007F to U+009F (C1) and the
 	*    U+FFFE/U+FFFF noncharacters are not checked, even though XML 1.0 §2.2 prohibits them and the `xmlVersion` option's own documentation claims C1
 	*    is only permitted under 1.1. Both gaps are upstream's and are kept.
 	*
@@ -787,11 +786,11 @@ var EntityDecoder = class EntityDecoder {
 	* @description Turn a resolved action level into a replacement.
 	*
 	* @param action - A level from {@link NCR_LEVEL}. A level outside the four known ones falls through to the allow behaviour, so a bad level cannot
-	*   produce a wrong string — it can only fail open.
+	*   produce a wrong string. It can only fail open.
 	* @param token - The raw token, e.g. `#38`, for the error message.
 	* @param cp - The codepoint, for the error message.
 	*
-	* @returns An effect producing the character for `allow`, `''` for `remove`, and `undefined` for `leave` — which the caller reads as "emit the
+	* @returns An effect producing the character for `allow`, `''` for `remove`, and `undefined` for `leave`, which the caller reads as "emit the
 	*   original `&token;`". Fails with {@link XmlError} and the `ProhibitedCharacterReference` reason for `throw`, naming both the token and the
 	*   codepoint.
 	*/
@@ -820,7 +819,7 @@ var EntityDecoder = class EntityDecoder {
 	*
 	* @param token - The raw token without `&` and `;`, e.g. `#38`, `#x26`, `#X26`.
 	*
-	* @returns An effect producing the replacement — the empty string meaning "delete" — or `undefined` to leave the reference as written. Fails with
+	* @returns An effect producing the replacement (the empty string meaning "delete") or `undefined` to leave the reference as written. Fails with
 	*   {@link XmlError} and the `ProhibitedCharacterReference` reason when the effective action is `throw`.
 	*/
 	#resolveNCR(token) {