@endevops/effect-codec-xml 0.0.1

package/dist/entities/entity-decoder.js

@@ -0,0 +1,841 @@
+import { XmlError } from "../xml-error.js";
+import { XML } from "./entity-tables.js";
+import { Effect, Match, Predicate } from "effect";
+//#region src/entities/entity-decoder.ts
+const CODE_AMPERSAND = 38;
+const CODE_SEMICOLON = 59;
+const CODE_HASH = 35;
+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.
+*/
+const MAX_TOKEN_LENGTH = 32;
+/**
+* @description The largest codepoint `String.fromCodePoint` accepts, and the bound a numeric reference is checked against before it gets that far. Out of range is
+* `leave`, not `remove`: the reference is preserved verbatim rather than deleted.
+*/
+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.
+*/
+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
+* duplicate, so the effective set is the eighteen characters below.
+*/
+const SPECIAL_CHARS = /* @__PURE__ */ new Set("!?\\/[]$%{}^&*()<>|+");
+/**
+* @description Injected at runtime: DOCTYPE entities for the current document, and persistent external entities. The untrusted tier, and the only one the
+* expansion limits count by default.
+*/
+const LIMIT_TIER_EXTERNAL = "external";
+/**
+* @description Trusted: the five XML predefined entities, the caller's `namedEntities`, and every numeric reference.
+*/
+const LIMIT_TIER_BASE = "base";
+/**
+* @description Not a tier an entity belongs to but a switch on the tier filter. Selecting it makes every entity count against the limits regardless of where it
+* came from.
+*/
+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.
+*/
+const NCR_LEVEL = Object.freeze({
+	allow: 0,
+	leave: 1,
+	remove: 2,
+	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.
+*/
+const XML10_ALLOWED_C0 = /* @__PURE__ */ new Set([
+	9,
+	10,
+	13
+]);
+/**
+* @description The three actions a registration hook can return, as a frozen object. Prefer it over the bare strings: the literals stay narrow string-literal
+* types, so `ENTITY_ACTION.BLOK` fails to compile instead of silently registering the entity.
+*
+* @example
+*   ```typescript
+*   const decoder = new EntityDecoder({
+*     onInputEntity: () => ENTITY_ACTION.BLOCK,
+*   });
+*   ```;
+*/
+const ENTITY_ACTION = Object.freeze({
+	ALLOW: "allow",
+	BLOCK: "block",
+	THROW: "throw"
+});
+/**
+* @description Reject an entity name that could never be written as a reference. `#` is refused positionally rather than by the character sweep, because a name
+* starting with `#` is a numeric reference's token and would collide with `#resolveNCR`. Everything else is refused per character.
+*
+* @param name - The name to check.
+*
+* @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.
+*/
+const checkEntityName = (name) => {
+	if (name.charCodeAt(0) === CODE_HASH) return Effect.fail(new XmlError({
+		reason: {
+			_tag: "InvalidEntityName",
+			name,
+			character: "#"
+		},
+		message: `[EntityReplacer] Invalid character '#' in entity name: "${name}"`
+	}));
+	for (const ch of name) if (SPECIAL_CHARS.has(ch)) return Effect.fail(new XmlError({
+		reason: {
+			_tag: "InvalidEntityName",
+			name,
+			character: ch
+		},
+		message: `[EntityReplacer] Invalid character '${ch}' in entity name: "${name}"`
+	}));
+	return Effect.succeed(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`.
+*
+* @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
+*   is absent rather than present-and-unusable.
+*/
+function mergeEntityMaps(...maps) {
+	const out = Object.create(null);
+	for (const map of maps) {
+		if (!map) continue;
+		for (const key of Object.keys(map)) {
+			const value = flattenEntityValue(map[key]);
+			if (value !== void 0) out[key] = value;
+		}
+	}
+	return out;
+}
+/**
+* @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
+* 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
+*   produces.
+*
+* @returns The replacement string, or `undefined` when the entry cannot be read. A name registered to the empty string yields `''`, which is why
+*   callers compare against `undefined` rather than testing for emptiness.
+*/
+function flattenEntityValue(raw) {
+	if (Predicate.isString(raw)) return raw;
+	if (Predicate.isNullish(raw) || !Predicate.isObject(raw) || raw.val === void 0) return void 0;
+	const val = raw.val;
+	return Predicate.isString(val) ? val : void 0;
+}
+/**
+* @description Read one own entry out of a null-prototype entity map.
+*
+* @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
+*   callers must compare against `undefined` rather than test for emptiness.
+*/
+function ownEntity(map, key) {
+	if (!Object.hasOwn(map, key)) return void 0;
+	return map[key];
+}
+/**
+* @description Normalise the `applyLimitsTo` option into the set of tiers that count against the limits.
+*
+* @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`.
+*/
+function parseLimitTiers(raw) {
+	if (!raw || raw === LIMIT_TIER_EXTERNAL) return /* @__PURE__ */ new Set([LIMIT_TIER_EXTERNAL]);
+	if (raw === LIMIT_TIER_ALL) return /* @__PURE__ */ new Set([LIMIT_TIER_ALL]);
+	if (raw === LIMIT_TIER_BASE) return /* @__PURE__ */ new Set([LIMIT_TIER_BASE]);
+	if (Array.isArray(raw)) return new Set(raw);
+	return /* @__PURE__ */ new Set([LIMIT_TIER_EXTERNAL]);
+}
+/**
+* @description Read one level out of {@link NCR_LEVEL} by name.
+*
+* @param name - The configured action name, or nothing.
+* @param fallback - The level to use when the name is absent.
+*
+* @returns The level. A name the table does not carry also yields `fallback`, so a value outside the union degrades to the default action rather than
+*   to `NaN`.
+*/
+function ncrLevelOf(name, fallback) {
+	if (name === void 0) return fallback;
+	return NCR_LEVEL[name] ?? fallback;
+}
+/**
+* @description Flatten the `ncr` option into the three numeric fields the decode loop reads, so nothing has to be re-derived per reference.
+*
+* @param ncr - The configured policy, or nothing.
+*
+* @returns The XML version, the base action level, and the null action level already clamped up to `remove`.
+*/
+function parseNCRConfig(ncr) {
+	if (!ncr) return {
+		xmlVersion: 1,
+		onLevel: NCR_LEVEL.allow,
+		nullLevel: NCR_LEVEL.remove
+	};
+	return {
+		xmlVersion: ncr.xmlVersion === 1.1 ? 1.1 : 1,
+		onLevel: ncrLevelOf(ncr.onNCR, NCR_LEVEL.allow),
+		nullLevel: Math.max(ncrLevelOf(ncr.nullNCR, NCR_LEVEL.remove), NCR_LEVEL.remove)
+	};
+}
+/**
+* @description Resolve {@link EntityDecoderOptions.postCheck} to something the decode loop can call unconditionally, or to the identity function. The fallback
+* exists so the path that actually scanned does not have to test for the option, while the two fast paths that return before the scan still skip the
+* call entirely. A non-function value is treated as an absent option rather than rejected, matching the hook rules: a mistyped option disables its
+* feature instead of failing the construction.
+*
+* @param raw - The configured hook, or nothing.
+*
+* @returns The hook itself, or a function returning its first argument.
+*/
+function readPostCheck(raw) {
+	if (Predicate.isFunction(raw)) return raw;
+	return (r) => r;
+}
+/**
+* @description Resolve a registration hook option to something safe to call, under the same non-function rule as {@link readPostCheck}.
+*
+* @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
+*   unconditionally: a hook that is not there accepts.
+*/
+function readHook(raw) {
+	if (Predicate.isFunction(raw)) return raw;
+	return null;
+}
+/**
+* @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.
+*
+* @param raw - The configured list, or nothing.
+*
+* @returns The names as a set, empty when the option is absent or is not an array.
+*/
+function readNameList(raw) {
+	if (Array.isArray(raw)) return new Set(raw);
+	return /* @__PURE__ */ new Set();
+}
+/**
+* @description Scan forward from a `&` for the `;` that would close the reference it opens, giving up once more than {@link MAX_TOKEN_LENGTH} characters have
+* passed since the `&`.
+*
+* @param str - The string being scanned.
+* @param ampersand - The index of the `&`.
+*
+* @returns The index of the closing `;`, or `-1` when the run holds none inside the window. A `;` one character past the `&` is returned rather than
+*   refused: that is the empty token `&;`, and the caller decides it is not a reference.
+*/
+function scanTokenEnd(str, ampersand) {
+	const len = str.length;
+	let j = ampersand + 1;
+	while (j < len && str.charCodeAt(j) !== CODE_SEMICOLON && j - ampersand <= MAX_TOKEN_LENGTH) j++;
+	if (j >= len || str.charCodeAt(j) !== CODE_SEMICOLON) return -1;
+	return j;
+}
+/**
+* @description Single-pass, zero-regex entity decoder for XML and HTML content.
+*
+* ### 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
+*    {@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
+*    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:
+*
+* - 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
+*   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
+*   {@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`.
+* - {@link EntityDecoder.addInputEntities} validates no names, so a `#`-prefixed or `&`-bearing name registers without complaint, where the two
+*   external setters would throw.
+*
+* @example
+*   ```typescript
+*   const decoder = new EntityDecoder({ namedEntities: { copy: '©' } });
+*   decoder.setExternalEntities({ brand: 'Acme' });
+*   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.reset(); // drops the input entities and the counters, keeps the external ones
+*   ```;
+*/
+var EntityDecoder = class EntityDecoder {
+	/**
+	* @description {@link EntityDecoderLimitOptions.maxTotalExpansions}, or `0` for unlimited. A negative number or `NaN` is also unlimited, since the decode loop
+	* tests `> 0`.
+	*/
+	#maxTotalExpansions;
+	/**
+	* @description {@link EntityDecoderLimitOptions.maxExpandedLength}, or `0` for unlimited, read the same way as `#maxTotalExpansions`.
+	*/
+	#maxExpandedLength;
+	/**
+	* @description {@link EntityDecoderOptions.postCheck}, or the identity function — so the decode loop can call it unconditionally on the path that actually
+	* scanned, and never on the two fast paths that return early.
+	*/
+	#postCheck;
+	/**
+	* @description The resolved tier filter. See {@link parseLimitTiers}.
+	*/
+	#limitTiers;
+	/**
+	* @description {@link EntityDecoderOptions.numericAllowed}. Only an explicit `false` turns it off, so an absent option cannot disable it.
+	*/
+	#numericAllowed;
+	/**
+	* @description The five XML predefined entities plus `namedEntities`, merged once at construction and never written again. The built-ins lose to a
+	* `namedEntities` entry of the same name, since it is merged second.
+	*/
+	#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.
+	*/
+	#externalMap;
+	/**
+	* @description DOCTYPE entities for the document being processed, as a null-prototype object. Wiped by both {@link EntityDecoder.reset} and
+	* {@link EntityDecoder.addInputEntities}.
+	*/
+	#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.
+	*/
+	#totalExpansions;
+	/**
+	* @description Characters _added_ by expansion since the last reset, accumulated the same way as `#totalExpansions`. Only positive contributions are counted.
+	*/
+	#expandedLength;
+	/**
+	* @description {@link EntityDecoderOptions.remove} as a set, or empty. Checked before every other classification, so a name in here is deleted without the name
+	* ever being resolved.
+	*/
+	#removeSet;
+	/**
+	* @description {@link EntityDecoderOptions.leave} as a set, or empty. Checked after `remove` and before the numeric test, so a name in here is emitted as the
+	* original `&name;` text.
+	*/
+	#leaveSet;
+	/**
+	* @description The XML version governing numeric classification. Mutable, because a `<?xml version?>` declaration is normally only known after the decoder
+	* exists; see {@link EntityDecoder.setXmlVersion}.
+	*/
+	#ncrXmlVersion;
+	/**
+	* @description {@link EntityDecoderNCROptions.onNCR} as a level from {@link NCR_LEVEL}. A floor, not an override: the resolver takes the maximum of this and
+	* whatever minimum a codepoint range imposes.
+	*/
+	#ncrOnLevel;
+	/**
+	* @description {@link EntityDecoderNCROptions.nullNCR} as a level from {@link NCR_LEVEL}, already clamped to `remove` or stricter.
+	*/
+	#ncrNullLevel;
+	/**
+	* @description {@link EntityDecoderOptions.onExternalEntity}, or `null` when absent or not a function. A non-function is dropped rather than rejected, so a
+	* mistyped option disables the hook instead of failing the construction.
+	*/
+	#onExternalEntity;
+	/**
+	* @description {@link EntityDecoderOptions.onInputEntity}, or `null`, under the same non-function rule as `#onExternalEntity`.
+	*/
+	#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
+	* 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.
+	*
+	* @example
+	*   ```typescript
+	*   const decoder = yield* EntityDecoder.make({ numericAllowed: false });
+	*   yield* decoder.decode('caf&eacute;'); // 'café'
+	*   ```;
+	*
+	* @param options - Configuration. See {@link EntityDecoderOptions}. Defaults to every field's own default.
+	*
+	* @returns An effect producing the decoder. Fails with {@link XmlError} and the `MissingOptions` reason for a `null`.
+	*/
+	static make = (options = {}) => Predicate.isNullish(options) ? Effect.fail(new XmlError({
+		reason: {
+			_tag: "MissingOptions",
+			parameter: "options"
+		},
+		message: "EntityDecoder.make: options is required. Use make({}) for a decoder with every default."
+	})) : 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.
+	*
+	* @param resolved - Configuration, already checked. See {@link EntityDecoderOptions}.
+	*/
+	constructor(resolved) {
+		const limit = resolved.limit ?? {};
+		this.#maxTotalExpansions = limit.maxTotalExpansions || 0;
+		this.#maxExpandedLength = limit.maxExpandedLength || 0;
+		this.#postCheck = readPostCheck(resolved.postCheck);
+		this.#limitTiers = parseLimitTiers(limit.applyLimitsTo ?? LIMIT_TIER_EXTERNAL);
+		this.#numericAllowed = resolved.numericAllowed ?? true;
+		this.#baseMap = mergeEntityMaps(XML, resolved.namedEntities || null);
+		this.#externalMap = Object.create(null);
+		this.#inputMap = Object.create(null);
+		this.#totalExpansions = 0;
+		this.#expandedLength = 0;
+		this.#removeSet = readNameList(resolved.remove);
+		this.#leaveSet = readNameList(resolved.leave);
+		const ncrConfig = parseNCRConfig(resolved.ncr);
+		this.#ncrXmlVersion = ncrConfig.xmlVersion;
+		this.#ncrOnLevel = ncrConfig.onLevel;
+		this.#ncrNullLevel = ncrConfig.nullLevel;
+		this.#onExternalEntity = readHook(resolved.onExternalEntity);
+		this.#onInputEntity = readHook(resolved.onInputEntity);
+	}
+	/**
+	* @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 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.
+	*
+	* @returns An effect producing `true` to register, `false` to skip silently. Fails with {@link XmlError} and the `EntityRejected` reason when the
+	*   hook returns `throw`. The message quotes the entity, so it is the only record left that a document was rejected.
+	*/
+	#applyRegistrationHook(hook, name, value, context) {
+		if (!hook) return Effect.succeed(true);
+		const action = hook(name, value);
+		if (action === ENTITY_ACTION.BLOCK) return Effect.succeed(false);
+		if (action === ENTITY_ACTION.THROW) return Effect.fail(new XmlError({
+			reason: {
+				_tag: "EntityRejected",
+				context,
+				name
+			},
+			message: `[EntityDecoder] Registration of ${context} entity "&${name};" was rejected by hook`
+		}));
+		return Effect.succeed(true);
+	}
+	/**
+	* @description Replace the whole set of persistent external entities. Every key is validated _before_ any value is read, so an invalid name fails even when its
+	* value is a form the merge would have dropped. A non-object or `null` map clears the set without validating anything.
+	*
+	* @param map - The entities to register, or nothing to clear.
+	*
+	* @returns An effect that registers the map. Fails with {@link XmlError} when a key contains a character from {@link SPECIAL_CHARS} or begins with
+	*   `#` (`InvalidEntityName`), or when {@link EntityDecoderOptions.onExternalEntity} returns `throw` (`EntityRejected`). A rejection from the hook
+	*   aborts before the assignment, so the previous map survives.
+	*/
+	setExternalEntities = Effect.fnUntraced(function* (map) {
+		if (map) for (const key of Object.keys(map)) yield* checkEntityName(key);
+		if (!this.#onExternalEntity) {
+			this.#externalMap = mergeEntityMaps(map);
+			return;
+		}
+		const flat = mergeEntityMaps(map);
+		const filtered = Object.create(null);
+		for (const [name, value] of Object.entries(flat)) if (yield* this.#applyRegistrationHook(this.#onExternalEntity, name, value, "external")) filtered[name] = value;
+		this.#externalMap = filtered;
+	});
+	/**
+	* @description Add one persistent external entity, keeping whatever is already registered. This is the only registration path that refuses a value containing
+	* `&`; the two map setters store one unchanged. The omission is upstream's, and it is kept: the same name registered through either route can end
+	* up resolving, or not resolving at all.
+	*
+	* @param key - The entity name, without `&` or `;`.
+	* @param value - The replacement text.
+	*
+	* @returns An effect that adds the entity. Fails with {@link XmlError} and the `InvalidEntityName` reason when `key` contains a character from
+	*   {@link SPECIAL_CHARS} or begins with `#`, or with the `EntityRejected` reason when {@link EntityDecoderOptions.onExternalEntity} returns
+	*   `throw`.
+	*/
+	addExternalEntity = Effect.fnUntraced(function* (key, value) {
+		yield* checkEntityName(key);
+		if (Predicate.isString(value) && value.indexOf("&") === -1) {
+			if (yield* this.#applyRegistrationHook(this.#onExternalEntity, key, value, "external")) this.#externalMap[key] = value;
+		}
+	});
+	/**
+	* @description Register the DOCTYPE entities for the document about to be decoded, replacing any previous set and clearing both counters. Unlike the external
+	* setters, no name is validated: a `#`-prefixed name, or one containing `&` or `<`, registers without complaint. A `#`-prefixed name is then
+	* unreachable, since `decode` routes `#`-prefixed tokens to the numeric pipeline first.
+	*
+	* @param map - The entities to register, or nothing to clear.
+	*
+	* @returns An effect that registers the map. Fails with {@link XmlError} and the `EntityRejected` reason when
+	*   {@link EntityDecoderOptions.onInputEntity} returns `throw`. The counters have already been cleared by then.
+	*/
+	addInputEntities = Effect.fnUntraced(function* (map) {
+		this.#totalExpansions = 0;
+		this.#expandedLength = 0;
+		if (!this.#onInputEntity) {
+			this.#inputMap = mergeEntityMaps(map);
+			return;
+		}
+		const flat = mergeEntityMaps(map);
+		const filtered = Object.create(null);
+		for (const [name, value] of Object.entries(flat)) if (yield* this.#applyRegistrationHook(this.#onInputEntity, name, value, "input")) filtered[name] = value;
+		this.#inputMap = filtered;
+	});
+	/**
+	* @description Start a new document: drop the input entities and both counters. The persistent external entities, the base map, the limits, the NCR policy and
+	* the XML version all survive, which is the difference between this and constructing a fresh decoder.
+	*
+	* @returns This decoder, so a call can be chained onto the document it ends.
+	*/
+	reset() {
+		this.#inputMap = Object.create(null);
+		this.#totalExpansions = 0;
+		this.#expandedLength = 0;
+		return this;
+	}
+	/**
+	* @description Set the XML version used to classify numeric references, once a `<?xml version="…"?>` declaration has been read. Only the exact number `1.1`
+	* selects XML 1.1; `1.0`, `1.15`, `'1.1'` and `NaN` all become `1.0`, so the stricter classification is the default rather than the looser one.
+	*
+	* @param version - The declared version.
+	*
+	* @returns Nothing.
+	*/
+	setXmlVersion(version) {
+		this.#ncrXmlVersion = version === 1.1 ? 1.1 : 1;
+	}
+	/**
+	* @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
+	* {@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';
+	*
+	*   const decoder = new EntityDecoder({ namedEntities: { copy: '©' } });
+	*   Effect.runSync(Effect.orElseSucceed(decoder.addExternalEntity('brand', 'Acme'), () => undefined));
+	*   Effect.runSync(decoder.decode('&brand; &copy;')); // 'Acme ©'
+	*   ```;
+	*
+	* @param str - The string to decode.
+	*
+	* @returns An effect producing the decoded string. A non-string argument comes back as the same non-string, which the `string` return type does not
+	*   describe but callers passing untyped values depend on. Fails with {@link XmlError} when a numeric reference is prohibited under the configured
+	*   policy (`ProhibitedCharacterReference`), or when a tracked tier would exceed {@link EntityDecoderLimitOptions.maxTotalExpansions}
+	*   (`ExpansionLimitExceeded`) or {@link EntityDecoderLimitOptions.maxExpandedLength} (`ExpandedLengthLimitExceeded`). The two limit messages keep
+	*   the `EntityReplacer` prefix from the original throw, which named a class this decoder does not have.
+	*/
+	decode = Effect.fnUntraced(function* (str) {
+		if (!Predicate.isString(str) || str.length === 0) return str;
+		if (str.indexOf("&") === -1) return str;
+		const chunks = yield* this.#expandAll(str);
+		const result = chunks.length === 0 ? str : chunks.join("");
+		return this.#postCheck(result, str);
+	});
+	/**
+	* @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.
+	*
+	* @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`,
+	*   `ExpansionLimitExceeded` or `ExpandedLengthLimitExceeded`.
+	*/
+	#expandAll = Effect.fnUntraced(function* (str) {
+		const chunks = [];
+		const len = str.length;
+		let last = 0;
+		let i = 0;
+		while (i < len) {
+			if (str.charCodeAt(i) !== CODE_AMPERSAND) {
+				i++;
+				continue;
+			}
+			const end = scanTokenEnd(str, i);
+			if (end <= i + 1) {
+				i++;
+				continue;
+			}
+			const token = str.slice(i + 1, end);
+			const resolved = yield* this.#resolveToken(token);
+			if (resolved === void 0) {
+				i++;
+				continue;
+			}
+			if (i > last) chunks.push(str.slice(last, i));
+			chunks.push(resolved.value);
+			last = end + 1;
+			i = last;
+			yield* this.#chargeExpansion(token, resolved.value, resolved.tier);
+		}
+		if (last < len) chunks.push(str.slice(last));
+		return chunks;
+	});
+	/**
+	* @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
+	*    `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.
+	*
+	* @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.
+	*/
+	#resolveToken = Effect.fnUntraced(function* (token) {
+		if (this.#removeSet.has(token)) return {
+			value: "",
+			tier: LIMIT_TIER_EXTERNAL
+		};
+		if (this.#leaveSet.has(token)) return void 0;
+		if (token.charCodeAt(0) === CODE_HASH) {
+			const character = yield* this.#resolveNCR(token);
+			if (character === void 0) return void 0;
+			return {
+				value: character,
+				tier: LIMIT_TIER_BASE
+			};
+		}
+		return this.#resolveName(token);
+	});
+	/**
+	* @description Charge one expansion against the ceilings, or against neither. An expansion counts only when its tier passes `#tierCounts` and at least one
+	* ceiling is configured, so a decoder with no limits set does no accounting at all, and an entity in a tier the filter excludes is free. Each
+	* ceiling is guarded separately rather than left to its own check, because an unconfigured ceiling is not a ceiling of zero: `maxExpandedLength: 0`
+	* means unlimited, so a decoder with only a count limit must not accumulate length it will then be compared against.
+	*
+	* @param token - The reference's token, with the `&` and `;` stripped. Its width is the baseline the expansion is measured against.
+	* @param replacement - What the reference expanded to, including `''` for a removal.
+	* @param tier - The tier the expansion is charged to.
+	*
+	* @returns An effect that fails with {@link XmlError} once a ceiling is exceeded, and succeeds otherwise. The count is checked before the length,
+	*   so a document that breaches both is reported against the count.
+	*/
+	#chargeExpansion = Effect.fnUntraced(function* (token, replacement, tier) {
+		const counts = this.#maxTotalExpansions > 0;
+		const grows = this.#maxExpandedLength > 0;
+		if (!counts && !grows) return;
+		if (!this.#tierCounts(tier)) return;
+		if (counts) yield* this.#countExpansion();
+		if (grows) yield* this.#countExpandedLength(token, replacement);
+	});
+	/**
+	* @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.
+	*
+	* @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
+	*   not have.
+	*/
+	#countExpansion() {
+		this.#totalExpansions++;
+		if (this.#totalExpansions > this.#maxTotalExpansions) return Effect.fail(new XmlError({
+			reason: {
+				_tag: "ExpansionLimitExceeded",
+				actual: this.#totalExpansions,
+				limit: this.#maxTotalExpansions
+			},
+			message: `[EntityReplacer] Entity expansion count limit exceeded: ${this.#totalExpansions} > ${this.#maxTotalExpansions}`
+		}));
+		return Effect.void;
+	}
+	/**
+	* @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.
+	*
+	* @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.
+	*
+	* @returns An effect that fails with {@link XmlError} and the `ExpandedLengthLimitExceeded` reason once the total is past the ceiling, and succeeds
+	*   otherwise. The `EntityReplacer` prefix in the message is preserved verbatim from the original throw, for the same reason as in
+	*   `#countExpansion`.
+	*/
+	#countExpandedLength(token, replacement) {
+		const delta = replacement.length - (token.length + 2);
+		if (delta <= 0) return Effect.void;
+		this.#expandedLength += delta;
+		if (this.#expandedLength > this.#maxExpandedLength) return Effect.fail(new XmlError({
+			reason: {
+				_tag: "ExpandedLengthLimitExceeded",
+				actual: this.#expandedLength,
+				limit: this.#maxExpandedLength
+			},
+			message: `[EntityReplacer] Expanded content length limit exceeded: ${this.#expandedLength} > ${this.#maxExpandedLength}`
+		}));
+		return Effect.void;
+	}
+	/**
+	* @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.
+	*
+	* @returns `true` when it counts. `'all'` short-circuits, so a filter naming every tier charges everything regardless of which map it came from.
+	*/
+	#tierCounts(tier) {
+		if (this.#limitTiers.has(LIMIT_TIER_ALL)) return true;
+		return this.#limitTiers.has(tier);
+	}
+	/**
+	* @description Resolve a named entity token, with the `&` and `;` already stripped.
+	*
+	* @param name - The token, e.g. `brand`.
+	*
+	* @returns The value and the tier to charge it to, or `undefined` when the name is registered nowhere. A name registered to the empty string
+	*   resolves to `''` rather than to `undefined`, so it deletes the reference instead of leaving it alone.
+	*/
+	#resolveName(name) {
+		const fromInput = ownEntity(this.#inputMap, name);
+		if (fromInput !== void 0) return {
+			value: fromInput,
+			tier: LIMIT_TIER_EXTERNAL
+		};
+		const fromExternal = ownEntity(this.#externalMap, name);
+		if (fromExternal !== void 0) return {
+			value: fromExternal,
+			tier: LIMIT_TIER_EXTERNAL
+		};
+		const fromBase = ownEntity(this.#baseMap, name);
+		if (fromBase !== void 0) return {
+			value: fromBase,
+			tier: LIMIT_TIER_BASE
+		};
+	}
+	/**
+	* @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
+	*    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.
+	*
+	* @param cp - The codepoint.
+	*
+	* @returns The minimum level from {@link NCR_LEVEL}, or {@link NO_MINIMUM_LEVEL} when the codepoint carries none.
+	*/
+	#classifyNCR(cp) {
+		if (cp === 0) return this.#ncrNullLevel;
+		if (cp >= 55296 && cp <= 57343) return NCR_LEVEL.remove;
+		if (this.#ncrXmlVersion === 1 && cp >= 1 && cp <= 31 && !XML10_ALLOWED_C0.has(cp)) return NCR_LEVEL.remove;
+		return NO_MINIMUM_LEVEL;
+	}
+	/**
+	* @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.
+	* @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
+	*   original `&token;`". Fails with {@link XmlError} and the `ProhibitedCharacterReference` reason for `throw`, naming both the token and the
+	*   codepoint.
+	*/
+	#applyNCRAction(action, token, cp) {
+		return Match.value(action).pipe(Match.when(NCR_LEVEL.allow, () => Effect.succeed(String.fromCodePoint(cp))), Match.when(NCR_LEVEL.remove, () => Effect.succeed("")), Match.when(NCR_LEVEL.leave, () => Effect.succeed(void 0)), Match.when(NCR_LEVEL.throw, () => Effect.fail(new XmlError({
+			reason: {
+				_tag: "ProhibitedCharacterReference",
+				token,
+				codepoint: cp
+			},
+			message: `[EntityDecoder] Prohibited numeric character reference &${token}; (U+${cp.toString(16).toUpperCase().padStart(4, "0")})`
+		}))), Match.orElse(() => Effect.succeed(String.fromCodePoint(cp))));
+	}
+	/**
+	* @description The full numeric-reference pipeline for one `#`-prefixed token.
+	*
+	* 1. Parse the codepoint, decimal or hex.
+	* 2. Reject NaN, negatives, and anything above {@link MAX_CODE_POINT}, leaving the reference as written.
+	* 3. Classify the codepoint for a minimum level.
+	* 4. If `numericAllowed` is off and no minimum reaches `remove`, leave the reference as written.
+	* 5. Take the stricter of the configured level and the minimum.
+	* 6. Apply it. Step 4 is why `numericAllowed: false` does not neutralise `onNCR: 'throw'` for surrogates, the XML 1.0 C0 controls or null: their
+	*    minimum already reaches `remove`, so they are handled no matter what the option says. It does neutralise the throw for every other codepoint.
+	*    The parse is `parseInt`, which stops at the first character it cannot use. That is upstream's choice and it is permissive: a leading space or
+	*    `+`, and trailing garbage, are all accepted, and a decimal token beginning `0x` parses as `0` rather than as hex.
+	*
+	* @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
+	*   {@link XmlError} and the `ProhibitedCharacterReference` reason when the effective action is `throw`.
+	*/
+	#resolveNCR(token) {
+		const second = token.charCodeAt(1);
+		let cp;
+		if (second === CODE_LOWER_X || second === CODE_UPPER_X) cp = parseInt(token.slice(2), 16);
+		else cp = parseInt(token.slice(1), 10);
+		if (Number.isNaN(cp) || cp < 0 || cp > MAX_CODE_POINT) return Effect.succeed(void 0);
+		const minimum = this.#classifyNCR(cp);
+		if (!this.#numericAllowed && minimum < NCR_LEVEL.remove) return Effect.succeed(void 0);
+		const effective = minimum === NO_MINIMUM_LEVEL ? this.#ncrOnLevel : Math.max(this.#ncrOnLevel, minimum);
+		return this.#applyNCRAction(effective, token, cp);
+	}
+};
+//#endregion
+export { ENTITY_ACTION, EntityDecoder };
+
+//# sourceMappingURL=entity-decoder.js.map