@endevops/effect-codec-xml 0.0.1

package/dist/conventions.d.ts

@@ -0,0 +1,88 @@
+import { XmlVersion } from "./naming.js";
+import { XmlParseError } from "./errors.js";
+import { Effect } from "effect";
+//#region src/conventions.d.ts
+/**
+ * @description The key prefix that marks a field as an XML attribute. `@xmlns` is written as `xmlns="…"`.
+ */
+export declare const ATTRIBUTE_PREFIX = "@";
+/**
+ * @description The reserved key holding an element's character data, alongside its attributes and child elements.
+ */
+export declare const TEXT_KEY = "#text";
+/**
+ * @description The element name used when nothing else names the root. Matches the default Effect uses in `Schema.toEncoderXml`.
+ */
+export declare const DEFAULT_ROOT_NAME = "root";
+/**
+ * @description The element name used for array members that have no natural name of their own. Matches the default in `Schema.toEncoderXml`.
+ */
+export declare const DEFAULT_ITEM_NAME = "item";
+/**
+ * @description What to do with a name that is not a legal XML name.
+ *
+ * - `repair` rewrites it into the nearest legal name. The default, because a serializer that silently produces a different tag name is worse than one
+ *   that produces a legal one.
+ * - `error` fails the render. Use it when a rewritten name would silently change the meaning of the document.
+ * - `ignore` writes the name as given, producing a document that is not well-formed. Only useful when a downstream step rewrites names anyway.
+ */
+export type NameMode = 'error' | 'ignore' | 'repair';
+/**
+ * @description Options for {@link resolveName}.
+ */
+export interface ResolveNameOptions {
+  /**
+   * @description What to do with an illegal name. Defaults to `'repair'`.
+   */
+  readonly mode?: NameMode | undefined;
+  /**
+   * @description XML version to validate against. Defaults to `'1.0'`.
+   */
+  readonly xmlVersion?: XmlVersion | undefined;
+}
+/**
+ * @description Whether a record key names an attribute rather than a child element.
+ *
+ * @param key - The key to classify.
+ *
+ * @returns Whether the key carries the {@link ATTRIBUTE_PREFIX}.
+ */
+export declare const isAttributeKey: (key: string) => boolean;
+/**
+ * @description The attribute name a record key stands for: `@xmlns` becomes `xmlns`.
+ *
+ * @param key - A key that {@link isAttributeKey} accepted.
+ *
+ * @returns The name with the prefix removed.
+ */
+export declare const attributeName: (key: string) => string;
+/**
+ * @description Whether a record key holds character data rather than a child element or an attribute.
+ *
+ * @param key - The key to classify.
+ *
+ * @returns Whether the key is the reserved {@link TEXT_KEY}.
+ */
+export declare const isTextKey: (key: string) => boolean;
+/**
+ * @description Whether a key is one this package reserves. Only {@link TEXT_KEY} is reserved today; every other key is read as a child element name.
+ *
+ * @param key - The key to classify.
+ *
+ * @returns Whether the key is reserved.
+ */
+export declare const isReservedKey: (key: string) => boolean;
+/**
+ * @description Resolves a name to something legal in an XML document. The renderer and the parser both resolve a name per element and per attribute, and an
+ * illegal name under `'error'` mode is a rejection rather than a value, so this returns an `Effect` with the `XmlParseError` in its error channel
+ * rather than throwing it. Callers `yield*` it and the failure composes with `catchTag` and the rest; the two internal call sites in `parse.ts` and
+ * `render.ts` use {@link resolveNameSync} directly, because their walks are synchronous hot paths.
+ *
+ * @param name - The candidate element or attribute name.
+ * @param options - Repair mode and XML version.
+ *
+ * @returns An effect producing the name to write, unchanged when it was already legal.
+ */
+export declare const resolveName: (name: string, options?: ResolveNameOptions) => Effect.Effect<string, XmlParseError>;
+//#endregion
+//# sourceMappingURL=conventions.d.ts.map

package/dist/conventions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.d.ts","names":[],"sources":["../src/conventions.ts"],"mappings":";;;;;;;qBAUa;;;;qBAKA;;;;qBAKA;;;;qBAKA;;;;;;;;;YAUD;;;;iBAKK;;;;WAIN,OAAO;;;;WAKP,aAAa;;;;;;;;;qBAUX,iBAAc;;;;;;;;qBASd,gBAAa;;;;;;;;qBASb,YAAS;;;;;;;;qBAST,gBAAa;;;;;;;;;;;;qBAyDb,cAAW,cAAgB,UAAW,uBAA0B,OAAO,eAAe"}

package/dist/conventions.js

@@ -0,0 +1,113 @@
+import { XmlParseError } from "./errors.js";
+import { isQName, sanitize, validate } from "./naming.js";
+import { Effect, Predicate, Result } from "effect";
+//#region src/conventions.ts
+/**
+* @description The key prefix that marks a field as an XML attribute. `@xmlns` is written as `xmlns="…"`.
+*/
+const ATTRIBUTE_PREFIX = "@";
+/**
+* @description The reserved key holding an element's character data, alongside its attributes and child elements.
+*/
+const TEXT_KEY = "#text";
+/**
+* @description The element name used when nothing else names the root. Matches the default Effect uses in `Schema.toEncoderXml`.
+*/
+const DEFAULT_ROOT_NAME = "root";
+/**
+* @description The element name used for array members that have no natural name of their own. Matches the default in `Schema.toEncoderXml`.
+*/
+const DEFAULT_ITEM_NAME = "item";
+/**
+* @description Whether a record key names an attribute rather than a child element.
+*
+* @param key - The key to classify.
+*
+* @returns Whether the key carries the {@link ATTRIBUTE_PREFIX}.
+*/
+const isAttributeKey = (key) => key.charCodeAt(0) === 64 && key.length > 1;
+/**
+* @description The attribute name a record key stands for: `@xmlns` becomes `xmlns`.
+*
+* @param key - A key that {@link isAttributeKey} accepted.
+*
+* @returns The name with the prefix removed.
+*/
+const attributeName = (key) => key.slice(1);
+/**
+* @description Whether a record key holds character data rather than a child element or an attribute.
+*
+* @param key - The key to classify.
+*
+* @returns Whether the key is the reserved {@link TEXT_KEY}.
+*/
+const isTextKey = (key) => key === TEXT_KEY;
+/**
+* @description Whether a key is one this package reserves. Only {@link TEXT_KEY} is reserved today; every other key is read as a child element name.
+*
+* @param key - The key to classify.
+*
+* @returns Whether the key is reserved.
+*/
+const isReservedKey = (key) => isTextKey(key);
+/**
+* @description Resolves a name to something legal in an XML document, synchronously. The renderer and the parser both resolve a name per element and per attribute
+* — the codec's hot path — so the walk calls this directly and keeps the work in plain JavaScript. `'error'` mode reports an illegal name by throwing
+* an {@link XmlParseError}; the callers that need it in a typed channel use {@link resolveName}, which wraps this.
+*
+* @param name - The candidate element or attribute name.
+* @param options - Repair mode and XML version.
+*
+* @returns The name to write, unchanged when it was already legal.
+*
+* @throws {XmlParseError} When the name is illegal and the mode is `'error'`.
+*/
+const resolveNameSync = (name, { mode = "repair", xmlVersion = "1.0" } = {}) => {
+	if (isQName(name, { xmlVersion })) return name;
+	if (mode === "ignore") return name;
+	if (mode === "repair") return sanitize(name, "name", { replacement: "_" });
+	const result = Effect.runSync(validate(name, "qName", { xmlVersion }));
+	const reason = !result.valid ? result.reason : "is not a legal XML name";
+	throw new XmlParseError({
+		message: `Invalid XML name ${JSON.stringify(name)}: ${reason}`,
+		position: -1,
+		input: name
+	});
+};
+/**
+* @description {@link resolveNameSync} with the thrown failure folded into a {@link Result}, so an effectful caller can carry it in a typed channel without a
+* try/catch of its own.
+*
+* @param name - The candidate element or attribute name.
+* @param options - Repair mode and XML version.
+*
+* @returns The resolved name, or the failure to report.
+*/
+const resolveNameResult = (name, options) => {
+	try {
+		return Result.succeed(resolveNameSync(name, options));
+	} catch (cause) {
+		if (cause instanceof XmlParseError) return Result.fail(cause);
+		return Result.fail(new XmlParseError({
+			message: Predicate.isError(cause) ? cause.message : String(cause),
+			position: -1,
+			input: name
+		}));
+	}
+};
+/**
+* @description Resolves a name to something legal in an XML document. The renderer and the parser both resolve a name per element and per attribute, and an
+* illegal name under `'error'` mode is a rejection rather than a value, so this returns an `Effect` with the `XmlParseError` in its error channel
+* rather than throwing it. Callers `yield*` it and the failure composes with `catchTag` and the rest; the two internal call sites in `parse.ts` and
+* `render.ts` use {@link resolveNameSync} directly, because their walks are synchronous hot paths.
+*
+* @param name - The candidate element or attribute name.
+* @param options - Repair mode and XML version.
+*
+* @returns An effect producing the name to write, unchanged when it was already legal.
+*/
+const resolveName = (name, options = {}) => Effect.suspend(() => Effect.fromResult(resolveNameResult(name, options)));
+//#endregion
+export { ATTRIBUTE_PREFIX, DEFAULT_ITEM_NAME, DEFAULT_ROOT_NAME, TEXT_KEY, attributeName, isAttributeKey, isReservedKey, isTextKey, resolveName, resolveNameSync };
+
+//# sourceMappingURL=conventions.js.map

package/dist/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","names":[],"sources":["../src/conventions.ts"],"sourcesContent":["import { Effect, Predicate, Result } from 'effect';\n\nimport type { XmlVersion } from './naming.ts';\n\nimport { XmlParseError } from './errors.ts';\nimport { isQName, sanitize, validate } from './naming.ts';\n\n/**\n * @description The key prefix that marks a field as an XML attribute. `@xmlns` is written as `xmlns=\"…\"`.\n */\nexport const ATTRIBUTE_PREFIX = '@';\n\n/**\n * @description The reserved key holding an element's character data, alongside its attributes and child elements.\n */\nexport const TEXT_KEY = '#text';\n\n/**\n * @description The element name used when nothing else names the root. Matches the default Effect uses in `Schema.toEncoderXml`.\n */\nexport const DEFAULT_ROOT_NAME = 'root';\n\n/**\n * @description The element name used for array members that have no natural name of their own. Matches the default in `Schema.toEncoderXml`.\n */\nexport const DEFAULT_ITEM_NAME = 'item';\n\n/**\n * @description What to do with a name that is not a legal XML name.\n *\n * - `repair` rewrites it into the nearest legal name. The default, because a serializer that silently produces a different tag name is worse than one\n *   that produces a legal one.\n * - `error` fails the render. Use it when a rewritten name would silently change the meaning of the document.\n * - `ignore` writes the name as given, producing a document that is not well-formed. Only useful when a downstream step rewrites names anyway.\n */\nexport type NameMode = 'error' | 'ignore' | 'repair';\n\n/**\n * @description Options for {@link resolveName}.\n */\nexport interface ResolveNameOptions {\n  /**\n   * @description What to do with an illegal name. Defaults to `'repair'`.\n   */\n  readonly mode?: NameMode | undefined;\n\n  /**\n   * @description XML version to validate against. Defaults to `'1.0'`.\n   */\n  readonly xmlVersion?: XmlVersion | undefined;\n}\n\n/**\n * @description Whether a record key names an attribute rather than a child element.\n *\n * @param key - The key to classify.\n *\n * @returns Whether the key carries the {@link ATTRIBUTE_PREFIX}.\n */\nexport const isAttributeKey = (key: string): boolean => key.charCodeAt(0) === 64 && key.length > 1;\n\n/**\n * @description The attribute name a record key stands for: `@xmlns` becomes `xmlns`.\n *\n * @param key - A key that {@link isAttributeKey} accepted.\n *\n * @returns The name with the prefix removed.\n */\nexport const attributeName = (key: string): string => key.slice(1);\n\n/**\n * @description Whether a record key holds character data rather than a child element or an attribute.\n *\n * @param key - The key to classify.\n *\n * @returns Whether the key is the reserved {@link TEXT_KEY}.\n */\nexport const isTextKey = (key: string): boolean => key === TEXT_KEY;\n\n/**\n * @description Whether a key is one this package reserves. Only {@link TEXT_KEY} is reserved today; every other key is read as a child element name.\n *\n * @param key - The key to classify.\n *\n * @returns Whether the key is reserved.\n */\nexport const isReservedKey = (key: string): boolean => isTextKey(key);\n\n/**\n * @description Resolves a name to something legal in an XML document, synchronously. The renderer and the parser both resolve a name per element and per attribute\n * — the codec's hot path — so the walk calls this directly and keeps the work in plain JavaScript. `'error'` mode reports an illegal name by throwing\n * an {@link XmlParseError}; the callers that need it in a typed channel use {@link resolveName}, which wraps this.\n *\n * @param name - The candidate element or attribute name.\n * @param options - Repair mode and XML version.\n *\n * @returns The name to write, unchanged when it was already legal.\n *\n * @throws {XmlParseError} When the name is illegal and the mode is `'error'`.\n */\nexport const resolveNameSync = (name: string, { mode = 'repair', xmlVersion = '1.0' }: ResolveNameOptions = {}): string => {\n  if (isQName(name, { xmlVersion })) return name;\n  if (mode === 'ignore') return name;\n  if (mode === 'repair') return sanitize(name, 'name', { replacement: '_' });\n\n  // `validate` only fails for an unknown production, which `'qName'` is not, so\n  // this runs a plain result and the failure is the reason the name is refused.\n  const result = Effect.runSync(validate(name, 'qName', { xmlVersion }));\n  const reason = !result.valid ? result.reason : 'is not a legal XML name';\n  throw new XmlParseError({ message: `Invalid XML name ${JSON.stringify(name)}: ${reason}`, position: -1, input: name });\n};\n\n/**\n * @description {@link resolveNameSync} with the thrown failure folded into a {@link Result}, so an effectful caller can carry it in a typed channel without a\n * try/catch of its own.\n *\n * @param name - The candidate element or attribute name.\n * @param options - Repair mode and XML version.\n *\n * @returns The resolved name, or the failure to report.\n */\nconst resolveNameResult = (name: string, options: ResolveNameOptions): Result.Result<string, XmlParseError> => {\n  try {\n    return Result.succeed(resolveNameSync(name, options));\n  } catch (cause) {\n    if (cause instanceof XmlParseError) {\n      return Result.fail(cause);\n    }\n    return Result.fail(new XmlParseError({ message: Predicate.isError(cause) ? cause.message : String(cause), position: -1, input: name }));\n  }\n};\n\n/**\n * @description Resolves a name to something legal in an XML document. The renderer and the parser both resolve a name per element and per attribute, and an\n * illegal name under `'error'` mode is a rejection rather than a value, so this returns an `Effect` with the `XmlParseError` in its error channel\n * rather than throwing it. Callers `yield*` it and the failure composes with `catchTag` and the rest; the two internal call sites in `parse.ts` and\n * `render.ts` use {@link resolveNameSync} directly, because their walks are synchronous hot paths.\n *\n * @param name - The candidate element or attribute name.\n * @param options - Repair mode and XML version.\n *\n * @returns An effect producing the name to write, unchanged when it was already legal.\n */\nexport const resolveName = (name: string, options: ResolveNameOptions = {}): Effect.Effect<string, XmlParseError> =>\n  Effect.suspend(() => Effect.fromResult(resolveNameResult(name, options)));\n"],"mappings":";;;;;;;AAUA,MAAa,mBAAmB;;;;AAKhC,MAAa,WAAW;;;;AAKxB,MAAa,oBAAoB;;;;AAKjC,MAAa,oBAAoB;;;;;;;;AAkCjC,MAAa,kBAAkB,QAAyB,IAAI,WAAW,CAAC,MAAM,MAAM,IAAI,SAAS;;;;;;;;AASjG,MAAa,iBAAiB,QAAwB,IAAI,MAAM,CAAC;;;;;;;;AASjE,MAAa,aAAa,QAAyB,QAAQ;;;;;;;;AAS3D,MAAa,iBAAiB,QAAyB,UAAU,GAAG;;;;;;;;;;;;;AAcpE,MAAa,mBAAmB,MAAc,EAAE,OAAO,UAAU,aAAa,UAA8B,CAAC,MAAc;CACzH,IAAI,QAAQ,MAAM,EAAE,WAAW,CAAC,GAAG,OAAO;CAC1C,IAAI,SAAS,UAAU,OAAO;CAC9B,IAAI,SAAS,UAAU,OAAO,SAAS,MAAM,QAAQ,EAAE,aAAa,IAAI,CAAC;CAIzE,MAAM,SAAS,OAAO,QAAQ,SAAS,MAAM,SAAS,EAAE,WAAW,CAAC,CAAC;CACrE,MAAM,SAAS,CAAC,OAAO,QAAQ,OAAO,SAAS;CAC/C,MAAM,IAAI,cAAc;EAAE,SAAS,oBAAoB,KAAK,UAAU,IAAI,EAAE,IAAI;EAAU,UAAU;EAAI,OAAO;CAAK,CAAC;AACvH;;;;;;;;;;AAWA,MAAM,qBAAqB,MAAc,YAAsE;CAC7G,IAAI;EACF,OAAO,OAAO,QAAQ,gBAAgB,MAAM,OAAO,CAAC;CACtD,SAAS,OAAO;EACd,IAAI,iBAAiB,eACnB,OAAO,OAAO,KAAK,KAAK;EAE1B,OAAO,OAAO,KAAK,IAAI,cAAc;GAAE,SAAS,UAAU,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GAAG,UAAU;GAAI,OAAO;EAAK,CAAC,CAAC;CACxI;AACF;;;;;;;;;;;;AAaA,MAAa,eAAe,MAAc,UAA8B,CAAC,MACvE,OAAO,cAAc,OAAO,WAAW,kBAAkB,MAAM,OAAO,CAAC,CAAC"}

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

@@ -0,0 +1,333 @@
+import { XmlError } from "../xml-error.js";
+import { Effect } from "effect";
+//#region src/entities/entity-decoder.d.ts
+/**
+ * @description What an {@link EntityRegistrationHook} returns. Use {@link ENTITY_ACTION} rather than the bare strings, so a typo is a type error instead of an
+ * entity that is accepted by default.
+ */
+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.
+ */
+export type EntityValFn = (match: string, captured: string, ...rest: Array<unknown>) => string;
+/**
+ * @description Called once per entity _at registration time_, never during {@link EntityDecoder.decode}. Receives the name without `&` and `;` and the resolved
+ * string value, after any `{ regex, val }` envelope has been unwrapped.
+ *
+ * @param name - The entity name, e.g. `brand`.
+ * @param value - The string the entity expands to.
+ *
+ * @returns The action to take. Anything other than `block` and `throw` is treated as `allow`, so an unrecognised return value never rejects an entity
+ *   by accident.
+ */
+export type EntityRegistrationHook = (name: string, value: string) => EntityHookAction;
+/**
+ * @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,
+ *   });
+ *   ```;
+ */
+export declare const ENTITY_ACTION: Readonly<{
+  ALLOW: 'allow';
+  BLOCK: 'block';
+  THROW: 'throw';
+}>;
+/**
+ * @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.
+ */
+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
+ * runtime tests `> 0` rather than truthiness of the configured number.
+ */
+export interface EntityDecoderLimitOptions {
+  /**
+   * @description Maximum number of tracked entity references expanded per document. The check is `> maxTotalExpansions`, so a limit of `2` allows two expansions
+   * and throws on the third.
+   *
+   * @default 0
+   */
+  maxTotalExpansions?: number;
+  /**
+   * @description Maximum number of characters _added_ by expansion per document. Only the surplus counts: 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.
+   *
+   * @default 0
+   */
+  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.
+   *
+   * @default 'external'
+   */
+  applyLimitsTo?: ApplyLimitsTo;
+}
+/**
+ * @description Policy for numeric character references. The three fields are flattened into numeric levels at construction so the decode loop never re-reads the
+ * object.
+ */
+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;
+   * `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.
+   *
+   * @default 'allow'
+   */
+  onNCR?: 'allow' | 'leave' | 'remove' | 'throw';
+  /**
+   * @description The action for U+0000. `'allow'` and `'leave'` are clamped up to `'remove'`, so a null reference is always at least deleted.
+   *
+   * @default 'remove'
+   */
+  nullNCR?: 'remove' | 'throw';
+}
+/**
+ * @description Construction options for {@link EntityDecoder}. Every field is optional, and the defaults are the permissive ones.
+ */
+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.
+   *
+   * @default null
+   */
+  namedEntities?: Record<string, string | {
+    regex: RegExp;
+    val: string | EntityValFn;
+  }> | 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
+   * 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.
+   *
+   * @default null
+   */
+  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
+   * on.
+   *
+   * @default true
+   */
+  numericAllowed?: boolean;
+  /**
+   * @description Names to keep as literal `&name;` text, matched against the token with no `&` or `;`. Numeric references are matched as `#38` or `#x26`.
+   *
+   * @default [ ]
+   */
+  leave?: Array<string>;
+  /**
+   * @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.
+   *
+   * @default [ ]
+   */
+  remove?: Array<string>;
+  /**
+   * @description Ceilings on expansion count and expanded length. See {@link EntityDecoderLimitOptions}.
+   */
+  limit?: EntityDecoderLimitOptions;
+  /**
+   * @description Policy for numeric references. See {@link EntityDecoderNCROptions}.
+   */
+  ncr?: EntityDecoderNCROptions;
+  /**
+   * @description Called once per entity as it is registered through {@link EntityDecoder.setExternalEntities} or {@link EntityDecoder.addExternalEntity}. `block`
+   * skips the entity, `throw` aborts the whole registration, anything else registers it. With {@link EntityDecoder.setExternalEntities} a `throw`
+   * leaves the previous external map in place, because the replacement is only assigned once every entry has passed.
+   *
+   * @default null
+   */
+  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.
+   *
+   * @default null
+   */
+  onInputEntity?: EntityRegistrationHook | null;
+}
+/**
+ * @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
+ *   ```;
+ */
+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
+   * 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?: 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.
+   *
+   * @param resolved - Configuration, already checked. See {@link EntityDecoderOptions}.
+   */
+  private constructor();
+  /**
+   * @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: (this: EntityDecoder, map: Record<string, string | {
+    regex: RegExp;
+    val: string | EntityValFn;
+  }>) => Effect.Effect<void, XmlError, never>;
+  /**
+   * @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: (this: EntityDecoder, key: string, value: string) => Effect.Effect<void, XmlError, never>;
+  /**
+   * @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: (this: EntityDecoder, map: Record<string, string | {
+    regx: RegExp;
+    val: string | EntityValFn;
+  } | {
+    regex: RegExp;
+    val: string | EntityValFn;
+  }>) => Effect.Effect<void, XmlError, never>;
+  /**
+   * @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;
+  /**
+   * @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: number): void;
+  /**
+   * @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: (this: EntityDecoder, str: string) => Effect.Effect<string, XmlError, never>;
+}
+//#endregion
+//# sourceMappingURL=entity-decoder.d.ts.map

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

@@ -0,0 +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"}