@endevops/effect-codec-xml 0.0.1

package/src/xml-error.ts

@@ -0,0 +1,168 @@
+/**
+ * @description Every way the entity decoder and the name validators can fail, as one typed error. The package used to throw plain `Error` and `TypeError` from
+ * places spread across the entity and naming areas. A caller had to match on message text, and there was nothing to narrow on. All of it is now a
+ * single {@link XmlError} in the `E` channel of the effects that can fail, with the specific cause in a `reason` field rather than parsed back out of
+ * a string.
+ *
+ * ## Why one error with a `reason`, and not one error per cause
+ *
+ * The causes would mean a class each, and a caller handling "any of these" would need `catchTags` with all of them. The causes are not independent
+ * decisions a caller usually wants to make separately — they are all "this XML input was not acceptable", and the useful split is coarse: a bad
+ * _configuration_ versus a bad _document_. So there is one error, and `reason` narrows to the specific cause. Recovery is a `catchReason` away:
+ *
+ * @example
+ *   ```typescript
+ *   import { Effect } from 'effect';
+ *   import { EntityDecoder, XmlError } from '@endevops/effect-xml-codec';
+ *
+ *   const limited = new EntityDecoder({ limit: { maxTotalExpansions: 2 } }).decode('&&&').pipe(
+ *   Effect.catchReason('XmlError', 'ExpansionLimitExceeded', reason => Effect.succeed(`gave up after ${reason.actual}`)),
+ *   );
+ *   ```;
+ *
+ *   The message is kept alongside `reason` and is part of the schema, because the text is load-bearing: the
+ *   `[EntityReplacer]` prefix in particular is documented as something callers match on, so it is reproduced exactly
+ *   rather than reworded.
+ */
+
+import { Schema } from 'effect';
+
+/**
+ * @description The specific cause of an {@link XmlError}, as a tagged union. The `_tag` on each member is the discriminant `Effect.catchReason` matches on, and
+ * the payload is what a handler needs in order to decide or to report. Every member is a case the decoder or the name validators actually raise —
+ * there is no catch-all member, so an exhaustive `match` stays exhaustive as causes are added.
+ */
+export const XmlErrorReason = Schema.TaggedUnion({
+  /**
+   * @description A required argument was `null` or another non-value where the package requires a real one. Raised by the factories that take caller-supplied
+   * input — {@link EntityDecoder.make} among them — when they are handed `null` for an options object that has no meaningful default. It is a
+   * distinct case from the rest because the argument is not _wrong_, it is _absent_, and a caller who wrote `make(null)` meant something the type
+   * system does not allow: a decoder with every default is `make({})`, and saying so here is more useful than silently producing one.
+   */
+  MissingOptions: {
+    /**
+     * @description The parameter that was given nothing, named as it appears in the signature.
+     */
+    parameter: Schema.String,
+  },
+
+  /**
+   * @description A name was checked against one of the five XML name productions and given a different one. Unreachable from TypeScript, where `Production` is a
+   * closed union — it is the guard for untyped JavaScript callers and for values that crossed a boundary as `unknown`.
+   */
+  InvalidProduction: {
+    production: Schema.String,
+    /**
+     * @description The productions that would have been accepted, comma-separated, as they appear in the message.
+     */
+    expected: Schema.String,
+  },
+
+  /**
+   * @description An entity name cannot be written as a reference, so it is refused at registration.
+   */
+  InvalidEntityName: {
+    /**
+     * @description The rejected name, as it was passed in.
+     */
+    name: Schema.String,
+    /**
+     * @description The offending character, or `#` for a name that starts with one. A leading `#` is refused by position rather than by the character sweep,
+     * because a name starting with `#` is a numeric reference's token and would collide with the numeric pipeline.
+     */
+    character: Schema.String,
+  },
+
+  /**
+   * @description A registration hook refused an entity and asked for the registration to abort.
+   */
+  EntityRejected: {
+    /**
+     * @description Which registration was in progress. Both are runtime-injected, which is why they share a tier for limit accounting.
+     */
+    context: Schema.Literals(['external', 'input']),
+    /**
+     * @description The entity name, without `&` or `;`.
+     */
+    name: Schema.String,
+  },
+
+  /**
+   * @description A document expanded more tracked entity references than {@link EntityDecoderLimitOptions.maxTotalExpansions} allows. A document can define an
+   * entity that references another ten times over. Ten deep is a denial of service; a hundred is a fork bomb written in XML.
+   */
+  ExpansionLimitExceeded: {
+    /**
+     * @description The count that tripped the limit. Deliberately not reset on failure, so this is the real over-limit total rather than the ceiling.
+     */
+    actual: Schema.Number,
+    /**
+     * @description The configured ceiling. The check is `actual > limit`, so a limit of `2` allows two expansions.
+     */
+    limit: Schema.Number,
+  },
+
+  /**
+   * @description A document grew by more characters through entity expansion than {@link EntityDecoderLimitOptions.maxExpandedLength} allows. Only the surplus
+   * counts: a reference whose replacement is no longer than the `&token;` it replaces contributes nothing, so this bounds growth rather than document
+   * size.
+   */
+  ExpandedLengthLimitExceeded: {
+    /**
+     * @description The accumulated growth that tripped the limit.
+     */
+    actual: Schema.Number,
+    /**
+     * @description The configured ceiling.
+     */
+    limit: Schema.Number,
+  },
+
+  /**
+   * @description A numeric character reference was prohibited by the configured policy.
+   */
+  ProhibitedCharacterReference: {
+    /**
+     * @description The raw token without `&` and `;`, e.g. `#38` or `#x26`.
+     */
+    token: Schema.String,
+    /**
+     * @description The codepoint the reference resolved to, so a log can name the character that was refused.
+     */
+    codepoint: Schema.Number,
+  },
+});
+
+/**
+ * @description The reason a well-formedness or policy failure occurred.
+ */
+export type XmlErrorReason = typeof XmlErrorReason.Type;
+
+/**
+ * @description Every failure this package can report, in the `E` channel of the effects that can fail. Carries both a `reason` — the typed, matchable cause — and
+ * a `message`, which is the human-readable form the package has always produced. Both are part of the schema, so an error survives a round-trip
+ * through a serialised boundary without losing either.
+ *
+ * @example
+ *   ```typescript
+ *   import { Effect } from 'effect';
+ *   import { EntityDecoder } from '@endevops/effect-xml-codec';
+ *
+ *   const program = Effect.gen(function*() {
+ *     const decoder = yield* EntityDecoder.make({});
+ *     return yield* decoder.decode('a & b');
+ *   });
+ *   ```;
+ */
+export class XmlError extends Schema.TaggedError<XmlError>()('XmlError', {
+  /**
+   * @description The specific cause. Narrow on `_tag`, or recover with `Effect.catchReason`.
+   */
+  reason: XmlErrorReason,
+
+  /**
+   * @description Human-readable description. The `[EntityReplacer]` and `[EntityDecoder]` prefixes are reproduced verbatim from the original throw sites, because
+   * they are documented as load-bearing for anything matching on them.
+   */
+  message: Schema.String,
+}) {}

package/src/xml-value.ts

@@ -0,0 +1,108 @@
+import { Predicate, Schema } from 'effect';
+
+/**
+ * @description A record of child elements, attributes and character data. A key starting with `@` is an attribute, the reserved `#text` key is character data, and
+ * every other key is a child element name. An `undefined` value means the field is absent, which is how an absent optional field stays
+ * distinguishable from an empty one.
+ */
+export interface XmlRecord {
+  readonly [name: string]: XmlValue | undefined;
+}
+
+/**
+ * @description One value in an XML document: nothing at all, character data, a repeated run of children, or a record of attributes, text and child elements.
+ * `undefined` is a value of its own rather than an omission, because that is how an absent optional field survives a round trip: a field with no
+ * value stays distinguishable from a field whose value is the empty string, and the renderer writes neither of them. The shape is deliberately the
+ * same one `Schema.toCodecStringTree` derives, which is what lets every schema feature Effect supports round-trip through this package without
+ * re-implementing the derivation.
+ */
+export type XmlValue = string | undefined | ReadonlyArray<XmlValue> | XmlRecord;
+
+/**
+ * @description How deep {@link isXmlValue} will walk before giving up. A document nested deeper than this is treated as invalid rather than allowed to exhaust the
+ * stack.
+ */
+const MAX_GUARD_DEPTH = 512;
+
+/**
+ * @description Whether an arbitrary value is a well-formed {@link XmlValue}.
+ *
+ * @param input - The candidate value.
+ *
+ * @returns Whether the value is absent, character data, an array of `XmlValue`, or a plain record of them.
+ */
+export const isXmlValue = (input: unknown): input is XmlValue => check(input, 0);
+
+/**
+ * @description One level of {@link isXmlValue}, with the depth it was reached at. The depth is the whole defence against a value built to be hostile: a
+ * self-referential object would otherwise recurse until the stack gave out, and a value nested thousands deep would take it with it. Both are
+ * rejected here instead, which is why this is a real recursion with a bound rather than a loop — the model is a tree, and a tree is walked by walking
+ * it.
+ *
+ * @param input - The candidate value.
+ * @param depth - How many levels down this value sits.
+ *
+ * @returns Whether this level is legal, and the rest of the value with it.
+ */
+const check = (input: unknown, depth: number): boolean => {
+  // `undefined` is a value in its own right: it is how an absent optional field survives a round trip, so a
+  // record is allowed to hold one and a document is allowed to be missing a field.
+  if (Predicate.isUndefined(input) || Predicate.isString(input)) return true;
+  if (Predicate.isNull(input) || !Predicate.isObjectOrArray(input)) return false;
+
+  if (depth > MAX_GUARD_DEPTH) return false;
+
+  // Arrays and records are the only two things left, and each is a walk of its
+  // own rather than another branch here: an array of them or a record of them.
+  return Array.isArray(input) ? everyMemberIs(input, depth) : everyFieldIs(input, depth);
+};
+
+/**
+ * @description Whether an array holds nothing but legal values one level down.
+ *
+ * @param members - The array's members.
+ * @param depth - The depth the array itself sits at.
+ *
+ * @returns Whether every member is a legal `XmlValue`.
+ */
+const everyMemberIs = (members: ReadonlyArray<unknown>, depth: number): boolean => {
+  for (const member of members) {
+    if (!check(member, depth + 1)) return false;
+  }
+  return true;
+};
+
+/**
+ * @description Whether an object is a plain record of legal values one level down. Plainness is checked here rather than by the caller because a `Date` or a `Map`
+ * has values a record cannot hold, and walking them would be walking something the model has no way to represent.
+ *
+ * @param input - The object to walk.
+ * @param depth - The depth the object itself sits at.
+ *
+ * @returns Whether the object is a plain record whose every field is a legal `XmlValue`.
+ */
+const everyFieldIs = (input: object, depth: number): boolean => {
+  if (!Predicate.isReadonlyObject(input)) return false;
+  for (const key of Object.keys(input)) {
+    if (!check(input[key], depth + 1)) return false;
+  }
+  return true;
+};
+
+/**
+ * @description A schema for {@link XmlValue}, so a value can be validated on its own — when it arrives from a store or a queue rather than from {@link parseXml},
+ * and the schema it belongs to is not in hand.
+ *
+ * @example
+ *   ```typescript
+ *   import { Schema } from 'effect';
+ *   import { XmlValue } from '@endevops/effect-xml-codec';
+ *
+ *   Schema.decodeUnknownSync(XmlValue)({ book: { '@id': '1', title: 'Dune' } }); // => { book: { '@id': '1', title: 'Dune' } }
+ *   Schema.decodeUnknownSync(XmlValue)({ book: { title: 42 } }); // => throws XmlValue
+ *   ```;
+ */
+export const XmlValue: Schema.Codec<XmlValue> = Schema.declare<XmlValue>(isXmlValue, {
+  identifier: 'XmlValue',
+  expected: 'an XML value: character data, an array of them, or a record of them',
+});