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

package/dist/xml-error.js

@@ -8,35 +8,35 @@ import { Schema } from "effect";
 *
 * ## 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. A caller does not usually want to
-* decide between the causes separately. They are all "this XML input was not acceptable", and the useful split is coarse: a bad _configuration_
-* versus a bad _document_. So there is one error, and `reason` narrows to the specific cause. Recovery is a `catchReason` away:
+* 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-codec-xml';
+*   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 callers depend on the text. The
-*   `[EntityReplacer]` prefix in particular is documented as something callers match on, so the codec reproduces it exactly
-*   rather than rewording it.
+*   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.
 */
 /**
 * @description The specific cause of an {@link XmlError}, as a tagged union. The `_tag` on each member is the discriminant `Effect.catchReason` matches on, and
-* the payload is what a handler needs in order to decide or to report. Every member is a case the decoder or the name validators actually raise.
-* There is no catch-all member, so an exhaustive `match` stays exhaustive as causes are added.
+* the payload is what a handler needs in order to decide or to report. Every member is a case the decoder or the name validators actually raise —
+* there is no catch-all member, so an exhaustive `match` stays exhaustive as causes are added.
 */
 const XmlErrorReason = Schema.TaggedUnion({
 	/**
 	* @description A required argument was `null` or another non-value where the package requires a real one. Raised by the factories that take caller-supplied
-	* input, {@link EntityDecoder.make} among them, when they are handed `null` for an options object that has no meaningful default. It is a distinct
-	* case from the rest because the argument is not _wrong_, it is _absent_, and a caller who wrote `make(null)` meant something the type system does
-	* not allow. A decoder with every default is `make({})`, and saying so here is more useful than silently producing one.
+	* input — {@link EntityDecoder.make} among them — when they are handed `null` for an options object that has no meaningful default. It is a
+	* distinct case from the rest because the argument is not _wrong_, it is _absent_, and a caller who wrote `make(null)` meant something the type
+	* system does not allow: a decoder with every default is `make({})`, and saying so here is more useful than silently producing one.
 	*/
 	MissingOptions: { 
 	/**
@@ -45,7 +45,7 @@ const XmlErrorReason = Schema.TaggedUnion({
 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`.
+	* closed union — it is the guard for untyped JavaScript callers and for values that crossed a boundary as `unknown`.
 	*/
 	InvalidProduction: {
 		production: Schema.String,
@@ -73,7 +73,7 @@ parameter: Schema.String },
 	*/
 	EntityRejected: {
 		/**
-		* @description Which registration was in progress. The runtime injects both, so they share a tier for limit accounting.
+		* @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"]),
 		/**
@@ -87,7 +87,7 @@ parameter: Schema.String },
 	*/
 	ExpansionLimitExceeded: {
 		/**
-		* @description The count that tripped the limit. The counter is not reset on failure, so this is the real over-limit total rather than the ceiling.
+		* @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,
 		/**
@@ -125,14 +125,14 @@ parameter: Schema.String },
 	}
 });
 /**
-* @description Every failure this package can report, in the `E` channel of the effects that can fail. Carries both a `reason`, the typed and matchable cause, and
+* @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-codec-xml';
+*   import { EntityDecoder } from '@endevops/effect-xml-codec';
 *
 *   const program = Effect.gen(function*() {
 *     const decoder = yield* EntityDecoder.make({});
@@ -147,7 +147,7 @@ var XmlError = class extends Schema.TaggedError()("XmlError", {
 	reason: XmlErrorReason,
 	/**
 	* @description Human-readable description. The `[EntityReplacer]` and `[EntityDecoder]` prefixes are reproduced verbatim from the original throw sites, because
-	* anything matching on them depends on them.
+	* they are documented as load-bearing for anything matching on them.
 	*/
 	message: Schema.String
 }) {};

package/dist/xml-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"xml-error.js","names":[],"sources":["../src/xml-error.ts"],"sourcesContent":["/**\n * @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\n * 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\n * 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\n * a string.\n *\n * ## Why one error with a `reason`, and not one error per cause\n *\n * The causes would mean a class each, and a caller handling \"any of these\" would need `catchTags` with all of them. A caller does not usually want to\n * decide between the causes separately. They are all \"this XML input was not acceptable\", and the useful split is coarse: a bad _configuration_\n * versus a bad _document_. So there is one error, and `reason` narrows to the specific cause. Recovery is a `catchReason` away:\n *\n * @example\n *   ```typescript\n *   import { Effect } from 'effect';\n *   import { EntityDecoder, XmlError } from '@endevops/effect-codec-xml';\n *\n *   const limited = new EntityDecoder({ limit: { maxTotalExpansions: 2 } }).decode('&amp;&amp;&amp;').pipe(\n *   Effect.catchReason('XmlError', 'ExpansionLimitExceeded', reason => Effect.succeed(`gave up after ${reason.actual}`)),\n *   );\n *   ```;\n *\n *   The message is kept alongside `reason` and is part of the schema, because callers depend on the text. The\n *   `[EntityReplacer]` prefix in particular is documented as something callers match on, so the codec reproduces it exactly\n *   rather than rewording it.\n */\n\nimport { Schema } from 'effect';\n\n/**\n * @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\n * 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.\n * There is no catch-all member, so an exhaustive `match` stays exhaustive as causes are added.\n */\nexport const XmlErrorReason = Schema.TaggedUnion({\n  /**\n   * @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\n   * input, {@link EntityDecoder.make} among them, when they are handed `null` for an options object that has no meaningful default. It is a distinct\n   * 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\n   * not allow. A decoder with every default is `make({})`, and saying so here is more useful than silently producing one.\n   */\n  MissingOptions: {\n    /**\n     * @description The parameter that was given nothing, named as it appears in the signature.\n     */\n    parameter: Schema.String,\n  },\n\n  /**\n   * @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\n   * closed union. It is the guard for untyped JavaScript callers and for values that crossed a boundary as `unknown`.\n   */\n  InvalidProduction: {\n    production: Schema.String,\n    /**\n     * @description The productions that would have been accepted, comma-separated, as they appear in the message.\n     */\n    expected: Schema.String,\n  },\n\n  /**\n   * @description An entity name cannot be written as a reference, so it is refused at registration.\n   */\n  InvalidEntityName: {\n    /**\n     * @description The rejected name, as it was passed in.\n     */\n    name: Schema.String,\n    /**\n     * @description The offending character, or `#` for a name that starts with one. A leading `#` is refused by position rather than by the character sweep,\n     * because a name starting with `#` is a numeric reference's token and would collide with the numeric pipeline.\n     */\n    character: Schema.String,\n  },\n\n  /**\n   * @description A registration hook refused an entity and asked for the registration to abort.\n   */\n  EntityRejected: {\n    /**\n     * @description Which registration was in progress. The runtime injects both, so they share a tier for limit accounting.\n     */\n    context: Schema.Literals(['external', 'input']),\n    /**\n     * @description The entity name, without `&` or `;`.\n     */\n    name: Schema.String,\n  },\n\n  /**\n   * @description A document expanded more tracked entity references than {@link EntityDecoderLimitOptions.maxTotalExpansions} allows. A document can define an\n   * entity that references another ten times over. Ten deep is a denial of service; a hundred is a fork bomb written in XML.\n   */\n  ExpansionLimitExceeded: {\n    /**\n     * @description The count that tripped the limit. The counter is not reset on failure, so this is the real over-limit total rather than the ceiling.\n     */\n    actual: Schema.Number,\n    /**\n     * @description The configured ceiling. The check is `actual > limit`, so a limit of `2` allows two expansions.\n     */\n    limit: Schema.Number,\n  },\n\n  /**\n   * @description A document grew by more characters through entity expansion than {@link EntityDecoderLimitOptions.maxExpandedLength} allows. Only the surplus\n   * counts: a reference whose replacement is no longer than the `&token;` it replaces contributes nothing, so this bounds growth rather than document\n   * size.\n   */\n  ExpandedLengthLimitExceeded: {\n    /**\n     * @description The accumulated growth that tripped the limit.\n     */\n    actual: Schema.Number,\n    /**\n     * @description The configured ceiling.\n     */\n    limit: Schema.Number,\n  },\n\n  /**\n   * @description A numeric character reference was prohibited by the configured policy.\n   */\n  ProhibitedCharacterReference: {\n    /**\n     * @description The raw token without `&` and `;`, e.g. `#38` or `#x26`.\n     */\n    token: Schema.String,\n    /**\n     * @description The codepoint the reference resolved to, so a log can name the character that was refused.\n     */\n    codepoint: Schema.Number,\n  },\n});\n\n/**\n * @description The reason a well-formedness or policy failure occurred.\n */\nexport type XmlErrorReason = typeof XmlErrorReason.Type;\n\n/**\n * @description Every failure this package can report, in the `E` channel of the effects that can fail. Carries both a `reason`, the typed and matchable cause, and\n * 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\n * through a serialised boundary without losing either.\n *\n * @example\n *   ```typescript\n *   import { Effect } from 'effect';\n *   import { EntityDecoder } from '@endevops/effect-codec-xml';\n *\n *   const program = Effect.gen(function*() {\n *     const decoder = yield* EntityDecoder.make({});\n *     return yield* decoder.decode('a &amp; b');\n *   });\n *   ```;\n */\nexport class XmlError extends Schema.TaggedError<XmlError>()('XmlError', {\n  /**\n   * @description The specific cause. Narrow on `_tag`, or recover with `Effect.catchReason`.\n   */\n  reason: XmlErrorReason,\n\n  /**\n   * @description Human-readable description. The `[EntityReplacer]` and `[EntityDecoder]` prefixes are reproduced verbatim from the original throw sites, because\n   * anything matching on them depends on them.\n   */\n  message: Schema.String,\n}) {}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAa,iBAAiB,OAAO,YAAY;;;;;;;CAO/C,gBAAgB;;;;AAId,WAAW,OAAO,OACpB;;;;;CAMA,mBAAmB;EACjB,YAAY,OAAO;;;;EAInB,UAAU,OAAO;CACnB;;;;CAKA,mBAAmB;;;;EAIjB,MAAM,OAAO;;;;;EAKb,WAAW,OAAO;CACpB;;;;CAKA,gBAAgB;;;;EAId,SAAS,OAAO,SAAS,CAAC,YAAY,OAAO,CAAC;;;;EAI9C,MAAM,OAAO;CACf;;;;;CAMA,wBAAwB;;;;EAItB,QAAQ,OAAO;;;;EAIf,OAAO,OAAO;CAChB;;;;;;CAOA,6BAA6B;;;;EAI3B,QAAQ,OAAO;;;;EAIf,OAAO,OAAO;CAChB;;;;CAKA,8BAA8B;;;;EAI5B,OAAO,OAAO;;;;EAId,WAAW,OAAO;CACpB;AACF,CAAC;;;;;;;;;;;;;;;;;AAuBD,IAAa,WAAb,cAA8B,OAAO,YAAsB,CAAC,CAAC,YAAY;;;;CAIvE,QAAQ;;;;;CAMR,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"xml-error.js","names":[],"sources":["../src/xml-error.ts"],"sourcesContent":["/**\n * @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\n * 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\n * 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\n * a string.\n *\n * ## Why one error with a `reason`, and not one error per cause\n *\n * 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\n * 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\n * _configuration_ versus a bad _document_. So there is one error, and `reason` narrows to the specific cause. Recovery is a `catchReason` away:\n *\n * @example\n *   ```typescript\n *   import { Effect } from 'effect';\n *   import { EntityDecoder, XmlError } from '@endevops/effect-xml-codec';\n *\n *   const limited = new EntityDecoder({ limit: { maxTotalExpansions: 2 } }).decode('&amp;&amp;&amp;').pipe(\n *   Effect.catchReason('XmlError', 'ExpansionLimitExceeded', reason => Effect.succeed(`gave up after ${reason.actual}`)),\n *   );\n *   ```;\n *\n *   The message is kept alongside `reason` and is part of the schema, because the text is load-bearing: the\n *   `[EntityReplacer]` prefix in particular is documented as something callers match on, so it is reproduced exactly\n *   rather than reworded.\n */\n\nimport { Schema } from 'effect';\n\n/**\n * @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\n * 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 —\n * there is no catch-all member, so an exhaustive `match` stays exhaustive as causes are added.\n */\nexport const XmlErrorReason = Schema.TaggedUnion({\n  /**\n   * @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\n   * input — {@link EntityDecoder.make} among them — when they are handed `null` for an options object that has no meaningful default. It is a\n   * 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\n   * system does not allow: a decoder with every default is `make({})`, and saying so here is more useful than silently producing one.\n   */\n  MissingOptions: {\n    /**\n     * @description The parameter that was given nothing, named as it appears in the signature.\n     */\n    parameter: Schema.String,\n  },\n\n  /**\n   * @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\n   * closed union — it is the guard for untyped JavaScript callers and for values that crossed a boundary as `unknown`.\n   */\n  InvalidProduction: {\n    production: Schema.String,\n    /**\n     * @description The productions that would have been accepted, comma-separated, as they appear in the message.\n     */\n    expected: Schema.String,\n  },\n\n  /**\n   * @description An entity name cannot be written as a reference, so it is refused at registration.\n   */\n  InvalidEntityName: {\n    /**\n     * @description The rejected name, as it was passed in.\n     */\n    name: Schema.String,\n    /**\n     * @description The offending character, or `#` for a name that starts with one. A leading `#` is refused by position rather than by the character sweep,\n     * because a name starting with `#` is a numeric reference's token and would collide with the numeric pipeline.\n     */\n    character: Schema.String,\n  },\n\n  /**\n   * @description A registration hook refused an entity and asked for the registration to abort.\n   */\n  EntityRejected: {\n    /**\n     * @description Which registration was in progress. Both are runtime-injected, which is why they share a tier for limit accounting.\n     */\n    context: Schema.Literals(['external', 'input']),\n    /**\n     * @description The entity name, without `&` or `;`.\n     */\n    name: Schema.String,\n  },\n\n  /**\n   * @description A document expanded more tracked entity references than {@link EntityDecoderLimitOptions.maxTotalExpansions} allows. A document can define an\n   * entity that references another ten times over. Ten deep is a denial of service; a hundred is a fork bomb written in XML.\n   */\n  ExpansionLimitExceeded: {\n    /**\n     * @description The count that tripped the limit. Deliberately not reset on failure, so this is the real over-limit total rather than the ceiling.\n     */\n    actual: Schema.Number,\n    /**\n     * @description The configured ceiling. The check is `actual > limit`, so a limit of `2` allows two expansions.\n     */\n    limit: Schema.Number,\n  },\n\n  /**\n   * @description A document grew by more characters through entity expansion than {@link EntityDecoderLimitOptions.maxExpandedLength} allows. Only the surplus\n   * counts: a reference whose replacement is no longer than the `&token;` it replaces contributes nothing, so this bounds growth rather than document\n   * size.\n   */\n  ExpandedLengthLimitExceeded: {\n    /**\n     * @description The accumulated growth that tripped the limit.\n     */\n    actual: Schema.Number,\n    /**\n     * @description The configured ceiling.\n     */\n    limit: Schema.Number,\n  },\n\n  /**\n   * @description A numeric character reference was prohibited by the configured policy.\n   */\n  ProhibitedCharacterReference: {\n    /**\n     * @description The raw token without `&` and `;`, e.g. `#38` or `#x26`.\n     */\n    token: Schema.String,\n    /**\n     * @description The codepoint the reference resolved to, so a log can name the character that was refused.\n     */\n    codepoint: Schema.Number,\n  },\n});\n\n/**\n * @description The reason a well-formedness or policy failure occurred.\n */\nexport type XmlErrorReason = typeof XmlErrorReason.Type;\n\n/**\n * @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\n * 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\n * through a serialised boundary without losing either.\n *\n * @example\n *   ```typescript\n *   import { Effect } from 'effect';\n *   import { EntityDecoder } from '@endevops/effect-xml-codec';\n *\n *   const program = Effect.gen(function*() {\n *     const decoder = yield* EntityDecoder.make({});\n *     return yield* decoder.decode('a &amp; b');\n *   });\n *   ```;\n */\nexport class XmlError extends Schema.TaggedError<XmlError>()('XmlError', {\n  /**\n   * @description The specific cause. Narrow on `_tag`, or recover with `Effect.catchReason`.\n   */\n  reason: XmlErrorReason,\n\n  /**\n   * @description Human-readable description. The `[EntityReplacer]` and `[EntityDecoder]` prefixes are reproduced verbatim from the original throw sites, because\n   * they are documented as load-bearing for anything matching on them.\n   */\n  message: Schema.String,\n}) {}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAa,iBAAiB,OAAO,YAAY;;;;;;;CAO/C,gBAAgB;;;;AAId,WAAW,OAAO,OACpB;;;;;CAMA,mBAAmB;EACjB,YAAY,OAAO;;;;EAInB,UAAU,OAAO;CACnB;;;;CAKA,mBAAmB;;;;EAIjB,MAAM,OAAO;;;;;EAKb,WAAW,OAAO;CACpB;;;;CAKA,gBAAgB;;;;EAId,SAAS,OAAO,SAAS,CAAC,YAAY,OAAO,CAAC;;;;EAI9C,MAAM,OAAO;CACf;;;;;CAMA,wBAAwB;;;;EAItB,QAAQ,OAAO;;;;EAIf,OAAO,OAAO;CAChB;;;;;;CAOA,6BAA6B;;;;EAI3B,QAAQ,OAAO;;;;EAIf,OAAO,OAAO;CAChB;;;;CAKA,8BAA8B;;;;EAI5B,OAAO,OAAO;;;;EAId,WAAW,OAAO;CACpB;AACF,CAAC;;;;;;;;;;;;;;;;;AAuBD,IAAa,WAAb,cAA8B,OAAO,YAAsB,CAAC,CAAC,YAAY;;;;CAIvE,QAAQ;;;;;CAMR,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC"}

package/dist/xml-value.d.ts

@@ -10,10 +10,10 @@ export interface XmlRecord {
 }
 /**
  * @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 the same one
- * `Schema.toCodecStringTree` derives, and sharing that shape is what lets every schema feature Effect supports round-trip through this package
- * without re-implementing the derivation.
+ * `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;
 /**
@@ -25,13 +25,13 @@ export type XmlValue = string | undefined | ReadonlyArray<XmlValue> | XmlRecord;
  */
 export declare const isXmlValue: (input: unknown) => input is XmlValue;
 /**
- * @description A schema for {@link XmlValue}, so a value can be validated on its own. This helps when it arrives from a store or a queue rather than from
- * {@link parseXml}, and the schema it belongs to is not in hand.
+ * @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-codec-xml';
+ *   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

package/dist/xml-value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xml-value.d.ts","names":[],"sources":["../src/xml-value.ts"],"mappings":";;;;;;;iBAOiB;YACL,eAAe;;;;;;;;;YAUf,gCAAgC,cAAc,YAAY;;;;;;;;qBAezD,aAAU,mBAAqB,SAAS;;;;;;;;;;;;;;qBAsExC,UAAU,OAAO,MAAM"}
+{"version":3,"file":"xml-value.d.ts","names":[],"sources":["../src/xml-value.ts"],"mappings":";;;;;;;iBAOiB;YACL,eAAe;;;;;;;;;YAUf,gCAAgC,cAAc,YAAY;;;;;;;;qBAezD,aAAU,mBAAqB,SAAS;;;;;;;;;;;;;;qBAuExC,UAAU,OAAO,MAAM"}

package/dist/xml-value.js

@@ -14,9 +14,10 @@ const MAX_GUARD_DEPTH = 512;
 */
 const isXmlValue = (input) => 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. This rejects
-* both, so it is a bounded recursion rather than a loop. The model is a tree, and walking a tree means walking it.
+* @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.
@@ -56,13 +57,13 @@ const everyFieldIs = (input, depth) => {
 	return true;
 };
 /**
-* @description A schema for {@link XmlValue}, so a value can be validated on its own. This helps when it arrives from a store or a queue rather than from
-* {@link parseXml}, and the schema it belongs to is not in hand.
+* @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-codec-xml';
+*   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

package/dist/xml-value.js.map

@@ -1 +1 @@
-{"version":3,"file":"xml-value.js","names":[],"sources":["../src/xml-value.ts"],"sourcesContent":["import { Predicate, Schema } from 'effect';\n\n/**\n * @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\n * every other key is a child element name. An `undefined` value means the field is absent, which is how an absent optional field stays\n * distinguishable from an empty one.\n */\nexport interface XmlRecord {\n  readonly [name: string]: XmlValue | undefined;\n}\n\n/**\n * @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.\n * `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\n * value stays distinguishable from a field whose value is the empty string, and the renderer writes neither of them. The shape is the same one\n * `Schema.toCodecStringTree` derives, and sharing that shape is what lets every schema feature Effect supports round-trip through this package\n * without re-implementing the derivation.\n */\nexport type XmlValue = string | undefined | ReadonlyArray<XmlValue> | XmlRecord;\n\n/**\n * @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\n * stack.\n */\nconst MAX_GUARD_DEPTH = 512;\n\n/**\n * @description Whether an arbitrary value is a well-formed {@link XmlValue}.\n *\n * @param input - The candidate value.\n *\n * @returns Whether the value is absent, character data, an array of `XmlValue`, or a plain record of them.\n */\nexport const isXmlValue = (input: unknown): input is XmlValue => check(input, 0);\n\n/**\n * @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\n * self-referential object would otherwise recurse until the stack gave out, and a value nested thousands deep would take it with it. This rejects\n * both, so it is a bounded recursion rather than a loop. The model is a tree, and walking a tree means walking it.\n *\n * @param input - The candidate value.\n * @param depth - How many levels down this value sits.\n *\n * @returns Whether this level is legal, and the rest of the value with it.\n */\nconst check = (input: unknown, depth: number): boolean => {\n  // `undefined` is a value in its own right: it is how an absent optional field survives a round trip, so a\n  // record is allowed to hold one and a document is allowed to be missing a field.\n  if (Predicate.isUndefined(input) || Predicate.isString(input)) return true;\n  if (Predicate.isNull(input) || !Predicate.isObjectOrArray(input)) return false;\n\n  if (depth > MAX_GUARD_DEPTH) return false;\n\n  // Arrays and records are the only two things left, and each is a walk of its\n  // own rather than another branch here: an array of them or a record of them.\n  return Array.isArray(input) ? everyMemberIs(input, depth) : everyFieldIs(input, depth);\n};\n\n/**\n * @description Whether an array holds nothing but legal values one level down.\n *\n * @param members - The array's members.\n * @param depth - The depth the array itself sits at.\n *\n * @returns Whether every member is a legal `XmlValue`.\n */\nconst everyMemberIs = (members: ReadonlyArray<unknown>, depth: number): boolean => {\n  for (const member of members) {\n    if (!check(member, depth + 1)) return false;\n  }\n  return true;\n};\n\n/**\n * @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`\n * has values a record cannot hold, and walking them would be walking something the model has no way to represent.\n *\n * @param input - The object to walk.\n * @param depth - The depth the object itself sits at.\n *\n * @returns Whether the object is a plain record whose every field is a legal `XmlValue`.\n */\nconst everyFieldIs = (input: object, depth: number): boolean => {\n  if (!Predicate.isReadonlyObject(input)) return false;\n  for (const key of Object.keys(input)) {\n    if (!check(input[key], depth + 1)) return false;\n  }\n  return true;\n};\n\n/**\n * @description A schema for {@link XmlValue}, so a value can be validated on its own. This helps when it arrives from a store or a queue rather than from\n * {@link parseXml}, and the schema it belongs to is not in hand.\n *\n * @example\n *   ```typescript\n *   import { Schema } from 'effect';\n *   import { XmlValue } from '@endevops/effect-codec-xml';\n *\n *   Schema.decodeUnknownSync(XmlValue)({ book: { '@id': '1', title: 'Dune' } }); // => { book: { '@id': '1', title: 'Dune' } }\n *   Schema.decodeUnknownSync(XmlValue)({ book: { title: 42 } }); // => throws XmlValue\n *   ```;\n */\nexport const XmlValue: Schema.Codec<XmlValue> = Schema.declare<XmlValue>(isXmlValue, {\n  identifier: 'XmlValue',\n  expected: 'an XML value: character data, an array of them, or a record of them',\n});\n"],"mappings":";;;;;;AAwBA,MAAM,kBAAkB;;;;;;;;AASxB,MAAa,cAAc,UAAsC,MAAM,OAAO,CAAC;;;;;;;;;;;AAY/E,MAAM,SAAS,OAAgB,UAA2B;CAGxD,IAAI,UAAU,YAAY,KAAK,KAAK,UAAU,SAAS,KAAK,GAAG,OAAO;CACtE,IAAI,UAAU,OAAO,KAAK,KAAK,CAAC,UAAU,gBAAgB,KAAK,GAAG,OAAO;CAEzE,IAAI,QAAQ,iBAAiB,OAAO;CAIpC,OAAO,MAAM,QAAQ,KAAK,IAAI,cAAc,OAAO,KAAK,IAAI,aAAa,OAAO,KAAK;AACvF;;;;;;;;;AAUA,MAAM,iBAAiB,SAAiC,UAA2B;CACjF,KAAK,MAAM,UAAU,SACnB,IAAI,CAAC,MAAM,QAAQ,QAAQ,CAAC,GAAG,OAAO;CAExC,OAAO;AACT;;;;;;;;;;AAWA,MAAM,gBAAgB,OAAe,UAA2B;CAC9D,IAAI,CAAC,UAAU,iBAAiB,KAAK,GAAG,OAAO;CAC/C,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GACjC,IAAI,CAAC,MAAM,MAAM,MAAM,QAAQ,CAAC,GAAG,OAAO;CAE5C,OAAO;AACT;;;;;;;;;;;;;;AAeA,MAAa,WAAmC,OAAO,QAAkB,YAAY;CACnF,YAAY;CACZ,UAAU;AACZ,CAAC"}
+{"version":3,"file":"xml-value.js","names":[],"sources":["../src/xml-value.ts"],"sourcesContent":["import { Predicate, Schema } from 'effect';\n\n/**\n * @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\n * every other key is a child element name. An `undefined` value means the field is absent, which is how an absent optional field stays\n * distinguishable from an empty one.\n */\nexport interface XmlRecord {\n  readonly [name: string]: XmlValue | undefined;\n}\n\n/**\n * @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.\n * `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\n * value stays distinguishable from a field whose value is the empty string, and the renderer writes neither of them. The shape is deliberately the\n * same one `Schema.toCodecStringTree` derives, which is what lets every schema feature Effect supports round-trip through this package without\n * re-implementing the derivation.\n */\nexport type XmlValue = string | undefined | ReadonlyArray<XmlValue> | XmlRecord;\n\n/**\n * @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\n * stack.\n */\nconst MAX_GUARD_DEPTH = 512;\n\n/**\n * @description Whether an arbitrary value is a well-formed {@link XmlValue}.\n *\n * @param input - The candidate value.\n *\n * @returns Whether the value is absent, character data, an array of `XmlValue`, or a plain record of them.\n */\nexport const isXmlValue = (input: unknown): input is XmlValue => check(input, 0);\n\n/**\n * @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\n * self-referential object would otherwise recurse until the stack gave out, and a value nested thousands deep would take it with it. Both are\n * 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\n * it.\n *\n * @param input - The candidate value.\n * @param depth - How many levels down this value sits.\n *\n * @returns Whether this level is legal, and the rest of the value with it.\n */\nconst check = (input: unknown, depth: number): boolean => {\n  // `undefined` is a value in its own right: it is how an absent optional field survives a round trip, so a\n  // record is allowed to hold one and a document is allowed to be missing a field.\n  if (Predicate.isUndefined(input) || Predicate.isString(input)) return true;\n  if (Predicate.isNull(input) || !Predicate.isObjectOrArray(input)) return false;\n\n  if (depth > MAX_GUARD_DEPTH) return false;\n\n  // Arrays and records are the only two things left, and each is a walk of its\n  // own rather than another branch here: an array of them or a record of them.\n  return Array.isArray(input) ? everyMemberIs(input, depth) : everyFieldIs(input, depth);\n};\n\n/**\n * @description Whether an array holds nothing but legal values one level down.\n *\n * @param members - The array's members.\n * @param depth - The depth the array itself sits at.\n *\n * @returns Whether every member is a legal `XmlValue`.\n */\nconst everyMemberIs = (members: ReadonlyArray<unknown>, depth: number): boolean => {\n  for (const member of members) {\n    if (!check(member, depth + 1)) return false;\n  }\n  return true;\n};\n\n/**\n * @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`\n * has values a record cannot hold, and walking them would be walking something the model has no way to represent.\n *\n * @param input - The object to walk.\n * @param depth - The depth the object itself sits at.\n *\n * @returns Whether the object is a plain record whose every field is a legal `XmlValue`.\n */\nconst everyFieldIs = (input: object, depth: number): boolean => {\n  if (!Predicate.isReadonlyObject(input)) return false;\n  for (const key of Object.keys(input)) {\n    if (!check(input[key], depth + 1)) return false;\n  }\n  return true;\n};\n\n/**\n * @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},\n * and the schema it belongs to is not in hand.\n *\n * @example\n *   ```typescript\n *   import { Schema } from 'effect';\n *   import { XmlValue } from '@endevops/effect-xml-codec';\n *\n *   Schema.decodeUnknownSync(XmlValue)({ book: { '@id': '1', title: 'Dune' } }); // => { book: { '@id': '1', title: 'Dune' } }\n *   Schema.decodeUnknownSync(XmlValue)({ book: { title: 42 } }); // => throws XmlValue\n *   ```;\n */\nexport const XmlValue: Schema.Codec<XmlValue> = Schema.declare<XmlValue>(isXmlValue, {\n  identifier: 'XmlValue',\n  expected: 'an XML value: character data, an array of them, or a record of them',\n});\n"],"mappings":";;;;;;AAwBA,MAAM,kBAAkB;;;;;;;;AASxB,MAAa,cAAc,UAAsC,MAAM,OAAO,CAAC;;;;;;;;;;;;AAa/E,MAAM,SAAS,OAAgB,UAA2B;CAGxD,IAAI,UAAU,YAAY,KAAK,KAAK,UAAU,SAAS,KAAK,GAAG,OAAO;CACtE,IAAI,UAAU,OAAO,KAAK,KAAK,CAAC,UAAU,gBAAgB,KAAK,GAAG,OAAO;CAEzE,IAAI,QAAQ,iBAAiB,OAAO;CAIpC,OAAO,MAAM,QAAQ,KAAK,IAAI,cAAc,OAAO,KAAK,IAAI,aAAa,OAAO,KAAK;AACvF;;;;;;;;;AAUA,MAAM,iBAAiB,SAAiC,UAA2B;CACjF,KAAK,MAAM,UAAU,SACnB,IAAI,CAAC,MAAM,QAAQ,QAAQ,CAAC,GAAG,OAAO;CAExC,OAAO;AACT;;;;;;;;;;AAWA,MAAM,gBAAgB,OAAe,UAA2B;CAC9D,IAAI,CAAC,UAAU,iBAAiB,KAAK,GAAG,OAAO;CAC/C,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GACjC,IAAI,CAAC,MAAM,MAAM,MAAM,QAAQ,CAAC,GAAG,OAAO;CAE5C,OAAO;AACT;;;;;;;;;;;;;;AAeA,MAAa,WAAmC,OAAO,QAAkB,YAAY;CACnF,YAAY;CACZ,UAAU;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endevops/effect-codec-xml",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-effect.1",
   "description": "A round-trip Effect Schema codec for XML, with the entity decoder and XML name validators it reads documents with. Derives an XML representation from any Effect Schema and reads it back, with attributes as `@`-prefixed fields.",
   "keywords": [
     "codec",

package/src/codec.ts

@@ -3,18 +3,18 @@
 // `toCodecXml` is this package's counterpart to `Schema.toCodecJson`. It
 // returns a `Schema` whose `Type` is the source schema's `Type` and whose
 // `Encoded` is XML text, so a value is written with `Schema.encodeSync(codec)`
-// and read back with `Schema.decodeSync(codec)`. That is one call each, as with
-// the JSON codec. There is no value tree at the call site and no second call to
-// a renderer or a parser.
+// and read back with `Schema.decodeSync(codec)` — one call each, the way the
+// JSON codec works. There is no value tree at the call site and no second call
+// to a renderer or a parser.
 //
 // The derivation underneath is Effect's own `Schema.toCodecStringTree`, so
 // every schema feature Effect supports composes here without this package
-// re-implementing the walk over a schema AST. On encode the codec runs the value
-// tree through `renderXml`; on decode it runs the document through `parseXml`.
-// Both are the same text layer this package exports on its own, and both
-// failures arrive as the `SchemaIssue.Issue` a schema is expected to report,
-// with the underlying message preserved. Those failures are an illegal name and
-// a document that is not well-formed.
+// re-implementing the walk over a schema AST. On the way out the codec runs the
+// value tree through `renderXml`; on the way back in it runs the document
+// through `parseXml`. Both are the same text layer this package exports on
+// their own, and both failures — an illegal name, a document that is not
+// well-formed — arrive as the `SchemaIssue.Issue` a schema is expected to
+// report, with the underlying message preserved.
 //
 // The conventions stay in the keys: a key starting with `@` is an attribute,
 // `#text` is character data, and every other key is a child element. The root
@@ -22,9 +22,8 @@
 // has one, and from the `rootName` option otherwise; it defaults to `'root'`,
 // the same name Effect's own XML encoder uses.
 
-import { Effect, Function, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from 'effect';
+import { Effect, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from 'effect';
 
-import type { NamespacePlan } from './namespaces.ts';
 import type { XmlParseOptions } from './parse.ts';
 import type { XmlRenderOptions } from './render.ts';
 import type { XmlValue } from './xml-value.ts';
@@ -37,8 +36,8 @@ import { renderXml } from './render.ts';
 /**
  * @description Options for {@link toCodecXml}.\
  * The render options name and shape the document; the parse options decide how strictly it is read back.\
- * `rootName` is the one the codec resolves for itself when the caller leaves it out. The codec takes it from the schema's `identifier` or `title` annotation and
- * falls back to `'root'`.
+ * `rootName` is the one the codec resolves for itself when the caller leaves it out, taking it from the schema's `identifier` or `title` annotation and falling
+ * back to `'root'`.
  */
 export type XmlCodecOptions = XmlRenderOptions & XmlParseOptions;
 
@@ -50,40 +49,18 @@ export interface toCodecXml<S extends Schema.Constraint> extends Schema.decodeTo
   readonly Rebuild: toCodecXml<S>;
 }
 
-// Whether the plan places any node at all: a rename, an attribute, a value, or a root namespace or name. A plan with none of these leaves the value tree
-// alone on both sides, so the codec skips the name walk.
-const isActivePlan = (plan: NamespacePlan): boolean =>
-  plan.byKey.size > 0 ||
-  plan.nameByKey.size > 0 ||
-  plan.attributeKeys.size > 0 ||
-  plan.valueByElement.size > 0 ||
-  plan.root !== undefined ||
-  plan.rootName !== undefined;
-
-// The render options with the root name resolved and any root prefix applied. The caller's `rootName` wins, then the plan's, then the schema's `identifier`
-// or `title` annotation, then `'root'`. A root namespace with a prefix qualifies the name unless the caller already wrote one.
-const resolveRenderOptions = <S extends Schema.Constraint>(schema: S, plan: NamespacePlan, options: XmlCodecOptions): XmlRenderOptions => {
-  const rootName =
-    options.rootName ?? plan.rootName ?? SchemaAST.resolveIdentifier(schema.ast) ?? SchemaAST.resolveTitle(schema.ast) ?? DEFAULT_ROOT_NAME;
-  const wireRootName = plan.root !== undefined && plan.root.prefix !== '' && !rootName.includes(':') ? `${plan.root.prefix}:${rootName}` : rootName;
-  return { ...options, rootName: wireRootName };
-};
-
 /**
  * @description Derives the XML codec for a schema: a `Schema` whose `Encoded` is an XML document, so `Schema.encodeSync(codec)` writes text and
  * `Schema.decodeSync(codec)` reads it back. The derivation is Effect's `Schema.toCodecStringTree`; the text layer is this package's {@link renderXml}
- * and {@link parseXml}. Call it data-first, `toCodecXml(schema, options)`, or data-last, `toCodecXml(options)(schema)`, so it drops into `pipe` beside
- * the rest of the Effect combinators. The two forms are one function: the first argument decides the style, a schema is read as data-first and an
- * options object as data-last. `pipe(schema, toCodecXml)` carries no options and works because a schema on its own is data-first.
+ * and {@link parseXml}.
  *
  * @example
  *   ```typescript
- *   import { Schema, pipe } from 'effect';
- *   import { toCodecXml } from '@endevops/effect-codec-xml';
+ *   import { Schema } from 'effect';
+ *   import { toCodecXml } from '@endevops/effect-xml-codec';
  *
  *   const Book = Schema.Struct({ '@id': Schema.String, title: Schema.String, pages: Schema.Number });
  *   const codec = toCodecXml(Book, { rootName: 'book' });
- *   const piped = pipe(Book, toCodecXml({ rootName: 'book' }));
  *
  *   const value = { '@id': '1', title: 'Dune', pages: 412 };
  *
@@ -94,63 +71,66 @@ const resolveRenderOptions = <S extends Schema.Constraint>(schema: S, plan: Name
  *   // => { '@id': '1', title: 'Dune', pages: 412 }
  *   ```;
  *
- * @param schema - The schema describing the value, in the data-first form.
- * @param options - Render and parse options. `rootName` defaults to the schema's `identifier` or `title` annotation, then to `'root'`. In the
- *   data-last form this is the only argument, and the schema arrives from `pipe`.
+ * @param schema - The schema describing the value.
+ * @param options - Render and parse options. `rootName` defaults to the schema's `identifier` or `title` annotation, then to `'root'`.
  *
- * @returns The codec, with the source schema's `Type` and the same service requirements. In the data-last form, a function from the schema to the
- *   codec.
+ * @returns The codec, with the source schema's `Type` and the same service requirements.
  */
-export const toCodecXml: {
-  <S extends Schema.Constraint>(schema: S, options?: XmlCodecOptions): toCodecXml<S>;
-  (options?: XmlCodecOptions): <S extends Schema.Constraint>(schema: S) => toCodecXml<S>;
-} = Function.dual(
-  args => Schema.isSchema(args[0]),
-  <S extends Schema.Constraint>(schema: S, options: XmlCodecOptions = {}): toCodecXml<S> => {
-    const planned = namespacePlan(schema);
-    if (Predicate.hasProperty(planned, 'error')) {
-      throw new Error(`Invalid XML namespace annotation:\n\t- ${planned.error}.`);
-    }
-    const plan = planned.plan;
-    const active = isActivePlan(plan);
-    const renderOptions = resolveRenderOptions(schema, plan, options);
+export const toCodecXml = <S extends Schema.Constraint>(schema: S, options: XmlCodecOptions = {}): toCodecXml<S> => {
+  const planned = namespacePlan(schema);
+  if (Predicate.hasProperty(planned, 'error')) {
+    throw new Error(`Invalid XML namespace annotation:\n\t- ${planned.error}.`);
+  }
+  const plan = planned.plan;
+  const active =
+    plan.byKey.size > 0 ||
+    plan.nameByKey.size > 0 ||
+    plan.attributeKeys.size > 0 ||
+    plan.valueByElement.size > 0 ||
+    plan.root !== undefined ||
+    plan.rootName !== undefined;
 
-    return Schema.String.pipe(
-      Schema.decodeTo(
-        Schema.toCodecStringTree(schema),
-        SchemaTransformation.transformEffect({
-          decode: (text, parseOptions) => {
-            if (!Predicate.isString(text)) {
-              return Effect.fail(new SchemaIssue.InvalidValue({ message: `Expected a string, but received ${typeof text}.` }, text, parseOptions));
-            }
+  const rootName =
+    options.rootName ?? plan.rootName ?? SchemaAST.resolveIdentifier(schema.ast) ?? SchemaAST.resolveTitle(schema.ast) ?? DEFAULT_ROOT_NAME;
+  const wireRootName = plan.root !== undefined && plan.root.prefix !== '' && !rootName.includes(':') ? `${plan.root.prefix}:${rootName}` : rootName;
 
-            return parseXml(text, options).pipe(
-              Effect.map(value => (active ? decodeNames(value, plan, {}, ROOT_ELEMENT) : value)),
-              Effect.tapError(error =>
-                Effect.logError(`XML parse error: ${error.message}`).pipe(Effect.annotateLogs({ cause: error, message: 'XML parse error' }))
-              ),
-              Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, text, parseOptions))
-            );
-          },
+  const renderOptions: XmlRenderOptions = { ...options, rootName: wireRootName };
+
+  return Schema.String.pipe(
+    Schema.decodeTo(
+      Schema.toCodecStringTree(schema),
+      SchemaTransformation.transformEffect({
+        decode: (text, parseOptions) => {
+          if (!Predicate.isString(text)) {
+            return Effect.fail(new SchemaIssue.InvalidValue({ message: `Expected a string, but received ${typeof text}.` }, text, parseOptions));
+          }
 
-          encode: (value, parseOptions) => {
-            if (active && Array.isArray(value) && (plan.root !== undefined || plan.rootName !== undefined)) {
-              return Effect.fail(
-                new SchemaIssue.InvalidValue(
-                  { message: 'An array at the root of a namespaced schema cannot carry the root namespace or name.' },
-                  value,
-                  parseOptions
-                )
-              );
-            }
+          return parseXml(text, options).pipe(
+            Effect.map(value => (active ? decodeNames(value, plan, {}, ROOT_ELEMENT) : value)),
+            Effect.tapError(error =>
+              Effect.logError(`XML parse error: ${error.message}`).pipe(Effect.annotateLogs({ cause: error, message: 'XML parse error' }))
+            ),
+            Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, text, parseOptions))
+          );
+        },
 
-            const wire = active ? encodeNames(value as XmlValue, plan, plan.root, {}, ROOT_ELEMENT) : (value as XmlValue);
-            return renderXml(wire, renderOptions).pipe(
-              Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, value, parseOptions))
+        encode: (value, parseOptions) => {
+          if (active && Array.isArray(value) && (plan.root !== undefined || plan.rootName !== undefined)) {
+            return Effect.fail(
+              new SchemaIssue.InvalidValue(
+                { message: 'An array at the root of a namespaced schema cannot carry the root namespace or name.' },
+                value,
+                parseOptions
+              )
             );
-          },
-        })
-      )
-    );
-  }
-);
+          }
+
+          const wire = active ? encodeNames(value as XmlValue, plan, plan.root, {}, ROOT_ELEMENT) : (value as XmlValue);
+          return renderXml(wire, renderOptions).pipe(
+            Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, value, parseOptions))
+          );
+        },
+      })
+    )
+  );
+};

package/src/conventions.ts

@@ -87,9 +87,9 @@ export const isTextKey = (key: string): boolean => key === TEXT_KEY;
 export const isReservedKey = (key: string): boolean => 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, and that is 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.
+ * @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.
@@ -131,10 +131,10 @@ const resolveNameResult = (name: string, options: ResolveNameOptions): Result.Re
 };
 
 /**
- * @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. 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 instead of
- * 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.
+ * @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.