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

package/README.md

@@ -1,15 +1,15 @@
-# @endevops/effect-xml-codec
+# @endevops/effect-codec-xml
 
 A round-trip Effect Schema codec for XML. `toCodecXml(schema)` returns a
 `Schema` whose `Encoded` is XML text, so `Schema.encodeSync` writes a document
-and `Schema.decodeSync` reads one back, the way `Schema.toCodecJson` works for
-JSON. There is no second call to a renderer or a parser at the call site.
+and `Schema.decodeSync` reads one back, in the same way `Schema.toCodecJson` does
+for JSON. There is no second call to a renderer or a parser at the call site.
 `renderXml` and `parseXml` are the text layer underneath, and remain available
 on their own.
 
 ```typescript
 import { Schema } from 'effect';
-import { toCodecXml } from '@endevops/effect-xml-codec';
+import { toCodecXml } from '@endevops/effect-codec-xml';
 
 const Book = Schema.Struct({ '@id': Schema.String, title: Schema.String, pages: Schema.Number, tag: Schema.Array(Schema.String) });
 
@@ -27,7 +27,7 @@ Schema.decodeSync(codec)('<book id="1"><title>Dune</title><pages>412</pages><tag
 
 Effect 4 ships `Schema.toEncoderXml`, and it is one-way: a value goes in, an XML
 string comes out, and there is no way back. It also has no notion of an
-attribute — a field named `@id` becomes an element called `<@id>` with its name
+attribute. A field named `@id` becomes an element called `<@id>` with its name
 rewritten.
 
 This package pairs Effect's own XML-value derivation, `Schema.toCodecStringTree`,
@@ -37,8 +37,8 @@ the text layer and the `@`/`#text` conventions.
 
 ## The mapping
 
-An `XmlValue` is the plainest value that can hold a document — strings, arrays
-and records. What gives it XML meaning is two key conventions:
+An `XmlValue` is the plainest value that can hold a document: strings, arrays
+and records. Two key conventions give it XML meaning:
 
 | In the value            | In the document                       |
 | ----------------------- | ------------------------------------- |
@@ -101,7 +101,7 @@ The annotation is attached with `Schema.annotate`:
 
 ```typescript
 import { Schema } from 'effect';
-import { toCodecXml } from '@endevops/effect-xml-codec';
+import { toCodecXml } from '@endevops/effect-codec-xml';
 
 const SOAP = 'http://schemas.xmlsoap.org/soap/envelope/';
 const AUTH = 'urn:auth';
@@ -163,9 +163,9 @@ Two limits:
 | `XmlError`                                                     | The failure `EntityDecoder` and `validate` report.                 |
 
 `toCodecXml` returns a `Schema`, so encoding and decoding are `Schema.encodeSync`
-and `Schema.decodeSync` (or the `Effect` forms), and every other Schema operation
-— `Schema.toFormatter`, `Schema.toJsonSchemaDocument`, the guards — applies to it
-unchanged. A failure in either direction arrives as a `SchemaIssue.Issue`: a
+and `Schema.decodeSync` (or the `Effect` forms). Every other Schema operation,
+including `Schema.toFormatter`, `Schema.toJsonSchemaDocument` and the guards,
+applies to it unchanged. A failure in either direction arrives as a
 document that will not parse or a value that will not write is reported with its
 underlying XML message, alongside the schema mismatches Effect already reports.
 The root element is named from the `rootName` option, then the schema's
@@ -176,21 +176,21 @@ The root element is named from the `rootName` option, then the schema's
 This package absorbed `@endevops/common-xml`, so the two primitives the text
 layer reads documents with ship here rather than as a sibling dependency.
 
-`EntityDecoder` expands the reference syntax XML inherits from HTML — `&name;`,
-`&#NNN;`, `&#xHH;` — with expansion limits, registration hooks, and a
+`EntityDecoder` expands the reference syntax XML inherits from HTML: `&name;`,
+`&#NNN;`, `&#xHH;`. It applies expansion limits, registration hooks, and a
 numeric-reference policy. `parseXml` uses it for character data and falls back
 to the raw text for a bare `&`. It reports failures as `XmlError`, a tagged
-error whose `reason` union is what `Effect.catchReason` narrows on.
+error whose `reason` union is the one `Effect.catchReason` narrows on.
 
-The name validators are plain synchronous predicates — `isName`, `isNcName`,
-`isQName`, `isNmToken`, `isNmTokens` — because a regex test cannot fail and the
+The name validators are plain synchronous predicates (`isName`, `isNcName`,
+`isQName`, `isNmToken`, `isNmTokens`), because a regex test cannot fail and the
 renderer and parser call them per name in their hot loops. `sanitize` rewrites
 an illegal name into the nearest legal one, and `validate` reports why a name
 failed through an `Effect`.
 
 ```typescript
 import { Effect } from 'effect';
-import { EntityDecoder, isQName, sanitize, validate } from '@endevops/effect-xml-codec';
+import { EntityDecoder, isQName, sanitize, validate } from '@endevops/effect-codec-xml';
 
 isQName('svg:circle'); // true
 sanitize('not a name', 'ncName'); // 'not_a_name'
@@ -208,10 +208,10 @@ did not come across: nothing in this package reaches them.
 **The derivation is Effect's.** `toCodecXml` derives
 `Schema.toCodecStringTree`, the same derivation `Schema.toEncoderXml` uses, and
 runs it through this package's `renderXml` and `parseXml` on the two text
-directions. That is what makes every schema feature Effect supports — structs,
-arrays, unions, records, recursion, refinements, branded types, transformations —
-work here without this package re-implementing the walk over a schema AST, and it
-is what the round-trip specs are exercising.
+directions. Every schema feature Effect supports then works here without this
+package re-implementing the walk over a schema AST: structs,
+arrays, unions, records, recursion, refinements, branded types, transformations.
+The round-trip specs exercise that.
 
 **The shape is `toCodecJson`'s.** The value `toCodecXml` returns is a `Schema`:
 `Type` is the source schema's `Type`, `Encoded` is XML text, the service
@@ -232,8 +232,8 @@ normalization would otherwise eat it: a literal newline in an attribute comes
 back as a space unless it is written `&#10;`.
 
 **Comments and processing instructions are markup, not data.** The parser skips
-them, which is what `XMLBuilder` does by default. CDATA becomes character data,
-since that is what it is.
+them, which is the default `XMLBuilder` behaviour. CDATA becomes character data,
+because that is what it is.
 
 ## Performance
 
@@ -256,40 +256,41 @@ Four findings shaped the code, and all are measured rather than assumed:
 
 - **Escaping was the whole cost of a large document.** The entity encoder that
   used to live here escaped by applying five sequential global replacements, one
-  per character, so a document with a single `&` in twenty thousand characters
-  was scanned five times over to change one byte — 58µs for that one document.
-  Escaping is now a single pattern scan to find the first character that needs
-  replacing, then one pass to build the result, which is 7.6x faster for clean
-  text and 28x faster for text with a character in it. `src/render.spec.ts` pins
-  the fast path with explicit expectations.
+  per character. A document with a single `&` in twenty thousand characters was
+  therefore scanned five times over to change one byte, at 58µs for that one
+  document. Escaping is now a single pattern scan to find the first character
+  that needs replacing, then one pass to build the result. That is 7.6x faster
+  for clean text and 28x faster for text with a character in it.
+  `src/render.spec.ts` pins the fast path with explicit expectations.
 - **Resolving a name is a regex test, not an `Effect`.** The validators used to
   return `Effect`s for pure questions, which left the renderer and the parser
   running an effect per distinct element and attribute name in every document.
   Running a runtime to read a boolean cost roughly 1µs per name, and a small
-  document has about a dozen names, so name resolution was most of what a
+  document has about a dozen names. Name resolution was therefore most of what a
   serialize and a parse did. The merged package now exposes plain synchronous
   predicates (`isQName` and the rest, `sanitize`) with no `Effect` wrapper, and
   the renderer's namer and the parser's name cache call them directly.
   `resolveName` is the one exception: it is effectful because `'error'` mode
-  rejects an illegal name, and a rejection is a failure rather than a value, so
-  it reports through the error channel like every other fallible step of a parse
-  or a render. That is the bulk of the gain on a small document; the 500-row
-  document improves by a few percent because it asks the same handful of names,
-  and the per-row work is what dominates there.
+  rejects an illegal name, and a rejection is a failure rather than a value. It
+  reports through the error channel like every other fallible step of a parse
+  or a render. That accounts for most of the gain on a small document. The
+  500-row document improves by a few percent because it asks the same handful of
+  names, and the per-row work dominates there.
 - **The codec adds no layer of its own.** `toCodecXml` derives
   `Schema.toCodecStringTree` and runs the tree through `renderXml`, so a value is
   encoded by Effect's parser and then rendered, with nothing wrapped around
-  either. Dropping the extra `Schema.toCodecArrayFromSingle` layer the codec used
-  to carry is part of why the table above is higher than the numbers this README
-  quoted before: the single-element-array leniency is the caller's to compose now,
-  and the plain codec does not pay for it on every array.
+  either. The codec also no longer carries an extra
+  `Schema.toCodecArrayFromSingle` layer. Dropping it is part of why the table
+  above is higher than the numbers this README quoted before: the
+  single-element-array leniency is the caller's to compose now, and the plain
+  codec does not pay for it on every array.
 - **A small document is dominated by something this package does not own.** Of
   the ~9µs it takes to serialize one, roughly 2.5µs is Effect's
   `toCodecStringTree` derivation, which walks the schema on every call, and the
   rest is this package's renderer. The renderer and parser underneath run at
-  roughly 2.5µs and 2.5µs on a flat document. A caller serializing the same
-  shape on every request should build the codec once and reuse it, which is what
-  the API is shaped for.
+  roughly 2.5µs and 2.5µs on a flat document. A caller that serializes the same
+  shape on every request should build the codec once and reuse it, which is the
+  shape the API encourages.
 
 The other things the benchmarks changed: one pass over a record's keys instead of
 one per role a key can play, name resolution memoized per document rather than
@@ -311,14 +312,14 @@ fallback all see it.
 ### Against the libraries on npm
 
 `packages/benchmarks/bench/comparison.bench.ts` measures the same object through
-this codec and
-through three npm libraries — `fast-xml-builder`, `fast-xml-parser`, and
-`@nodable/flexible-xml-parser`. The equivalence is established rather than
-assumed: with `attributeNamePrefix: '@'`, **`fast-xml-builder` produces
-byte-identical output to this codec**, and the benchmark asserts it, so a change
-that breaks it fails the suite instead of quietly comparing different work.
+this codec and through three npm libraries: `fast-xml-builder`, `fast-xml-parser`,
+and `@nodable/flexible-xml-parser`. The benchmark establishes the equivalence
+rather than assuming it. With `attributeNamePrefix: '@'`,
+**`fast-xml-builder` produces byte-identical output to this codec**, and the
+benchmark asserts it, so a change that breaks it fails the suite instead of
+quietly comparing different work.
 
-**Encoding** — one object to the same bytes:
+**Encoding**: one object to the same bytes:
 
 | Document            | This codec | `fast-xml-builder` |
 | ------------------- | ---------- | ------------------ |
@@ -326,7 +327,7 @@ that breaks it fails the suite instead of quietly comparing different work.
 | 500 rows            | 1,698/s    | 1,269/s (0.75x)    |
 | one large text node | 584,358/s  | 254,355/s (0.44x)  |
 
-**Decoding** — one document to the same value:
+**Decoding**: one document to the same value:
 
 | Document            | This codec | `@nodable/flexible-xml-parser` | `fast-xml-parser` |
 | ------------------- | ---------- | ------------------------------ | ----------------- |
@@ -334,9 +335,9 @@ that breaks it fails the suite instead of quietly comparing different work.
 | 500 rows            | 1,975/s    | 70/s (0.04x)                   | 486/s (0.25x)     |
 | one large text node | 20,715/s   | 5,694/s (0.27x)                | 8,209/s (0.40x)   |
 
-**A full round trip**, which is the number an application actually pays. Neither
-a builder nor a parser can do both halves, so the last two rows are each
-ecosystem doing the same work with two libraries and hand-joining them:
+**A full round trip**, the number an application actually pays. Neither a
+builder nor a parser can do both halves, so the last two rows are each ecosystem
+doing the same work with two libraries and hand-joining them:
 
 | Path                                                        | Throughput       |
 | ----------------------------------------------------------- | ---------------- |
@@ -346,14 +347,14 @@ ecosystem doing the same work with two libraries and hand-joining them:
 
 **This codec reaches the parser and renderer directly.** It encodes and decodes
 through `Schema.encodeSync` and `Schema.decodeSync`, with no runtime per call,
-which is why it is the fastest row on both sides. The npm parsers do less work —
-they do not validate the result against a schema — so the comparison is
+so it is the fastest row on both sides. The npm parsers do less work, because
+they do not validate the result against a schema, so the comparison is
 directional rather than like-for-like.
 
-Four things to be straight about when reading those tables:
+Four caveats apply when reading those tables:
 
 - **These are one machine's numbers, from one run.** The relative error is under
-  2% on every row, but the machine's load moved between runs, so treat the
+  2% on every row, but the machine's load moved between runs. Treat the
   ratios as the durable part and the absolute figures as a range.
 - **This codec's decode does strictly more work.** It parses _and_ validates the
   result against the schema, coercing `"30"` to `30` and failing on a mismatch.
@@ -361,11 +362,11 @@ Four things to be straight about when reading those tables:
   2,984/s and the schema pass brings it to 1,975/s, so roughly a third of the
   decode time is validation the comparison rows do not pay.
 - **The parsers do work this codec does not.** They coerce tag values through a
-  value-parser pipeline — entity decoding, whitespace normalizing, boolean and
-  number parsing — where a schema already decided the type. Both sides have work
-  the other lacks, and neither is idle.
+  value-parser pipeline: entity decoding, whitespace normalizing, boolean and
+  number parsing, where a schema already decided the type. Both sides have work
+  the other lacks, and both are busy.
 - **Neither ecosystem is doing the whole job on its own.** A builder has no
-  reader and a parser has no writer, so the round-trip table is the honest
+  reader and a parser has no writer, so the round-trip table is the fair
   comparison and the single-direction tables are the diagnostic ones.
 
 ## Limitations
@@ -396,7 +397,7 @@ quietly.
   children and read back as a single run, so `<p>a<b/>c</p>` reads as
   `{ b: '', '#text': 'ac' }`. Reading and re-rendering is stable from there on.
 - **Whitespace at the edges of text is trimmed** unless `preserveWhitespace` is
-  set. That is what makes a pretty-printed document read as the same value as an
+  set. That lets a pretty-printed document read as the same value as an
   unindented one. Whitespace _inside_ a run is never touched.
 - **`Schema.BigInt` is write-only.** Effect's `StringTree` derivation lowers one
   to its decimal text and has no way to raise it again.

package/dist/codec.d.ts

@@ -5,8 +5,8 @@ import { Schema } from "effect";
 /**
  * @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, taking it from the schema's `identifier` or `title` annotation and falling
- * back to `'root'`.
+ * `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'`.
  */
 export type XmlCodecOptions = XmlRenderOptions & XmlParseOptions;
 /**
@@ -19,15 +19,18 @@ export interface toCodecXml<S extends Schema.Constraint> extends Schema.decodeTo
 /**
  * @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}.
+ * 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.
  *
  * @example
  *   ```typescript
- *   import { Schema } from 'effect';
- *   import { toCodecXml } from '@endevops/effect-xml-codec';
+ *   import { Schema, pipe } from 'effect';
+ *   import { toCodecXml } from '@endevops/effect-codec-xml';
  *
  *   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 };
  *
@@ -38,11 +41,16 @@ export interface toCodecXml<S extends Schema.Constraint> extends Schema.decodeTo
  *   // => { '@id': '1', title: 'Dune', pages: 412 }
  *   ```;
  *
- * @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'`.
+ * @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`.
  *
- * @returns The codec, with the source schema's `Type` and the same service requirements.
+ * @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.
  */
-export declare const toCodecXml: <S extends Schema.Constraint>(schema: S, options?: XmlCodecOptions) => toCodecXml<S>;
+export declare const toCodecXml: {
+  <S extends Schema.Constraint>(schema: S, options?: XmlCodecOptions): toCodecXml<S>;
+  (options?: XmlCodecOptions): <S extends Schema.Constraint>(schema: S) => toCodecXml<S>;
+};
 //#endregion
 //# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","names":[],"sources":["../src/codec.ts"],"mappings":";;;;;;;;;;YAyCY,kBAAkB,mBAAmB;;;;;iBAMhC,WAAW,UAAU,OAAO,oBAAoB,OAAO,SAAS,OAAO,kBAAkB,IAAI,OAAO;WAC1G,SAAS,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8BlB,aAAc,UAAU,OAAO,YAAU,QAAU,GAAC,UAAW,oBAAuB,WAAW"}
+{"version":3,"file":"codec.d.ts","names":[],"sources":["../src/codec.ts"],"mappings":";;;;;;;;;;YA0CY,kBAAkB,mBAAmB;;;;;iBAMhC,WAAW,UAAU,OAAO,oBAAoB,OAAO,SAAS,OAAO,kBAAkB,IAAI,OAAO;WAC1G,SAAS,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAsDlB;GACV,UAAU,OAAO,YAAY,QAAQ,GAAG,UAAU,kBAAkB,WAAW;GAC/E,UAAU,mBAAmB,UAAU,OAAO,YAAY,QAAQ,MAAM,WAAW"}

package/dist/codec.js

@@ -2,20 +2,32 @@ import "./conventions.js";
 import { decodeNames, encodeNames, namespacePlan } from "./namespaces.js";
 import { parseXml } from "./parse.js";
 import { renderXml } from "./render.js";
-import { Effect, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from "effect";
+import { Effect, Function, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from "effect";
 //#region src/codec.ts
+const isActivePlan = (plan) => plan.byKey.size > 0 || plan.nameByKey.size > 0 || plan.attributeKeys.size > 0 || plan.valueByElement.size > 0 || plan.root !== void 0 || plan.rootName !== void 0;
+const resolveRenderOptions = (schema, plan, options) => {
+	const rootName = options.rootName ?? plan.rootName ?? SchemaAST.resolveIdentifier(schema.ast) ?? SchemaAST.resolveTitle(schema.ast) ?? "root";
+	const wireRootName = plan.root !== void 0 && 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}.
+* 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.
 *
 * @example
 *   ```typescript
-*   import { Schema } from 'effect';
-*   import { toCodecXml } from '@endevops/effect-xml-codec';
+*   import { Schema, pipe } from 'effect';
+*   import { toCodecXml } from '@endevops/effect-codec-xml';
 *
 *   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 };
 *
@@ -26,22 +38,19 @@ import { Effect, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation
 *   // => { '@id': '1', title: 'Dune', pages: 412 }
 *   ```;
 *
-* @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'`.
+* @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`.
 *
-* @returns The codec, with the source schema's `Type` and the same service requirements.
+* @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.
 */
-const toCodecXml = (schema, options = {}) => {
+const toCodecXml = Function.dual((args) => Schema.isSchema(args[0]), (schema, options = {}) => {
 	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 !== void 0 || plan.rootName !== void 0;
-	const rootName = options.rootName ?? plan.rootName ?? SchemaAST.resolveIdentifier(schema.ast) ?? SchemaAST.resolveTitle(schema.ast) ?? "root";
-	const wireRootName = plan.root !== void 0 && plan.root.prefix !== "" && !rootName.includes(":") ? `${plan.root.prefix}:${rootName}` : rootName;
-	const renderOptions = {
-		...options,
-		rootName: wireRootName
-	};
+	const active = isActivePlan(plan);
+	const renderOptions = resolveRenderOptions(schema, plan, options);
 	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));
@@ -56,7 +65,7 @@ const toCodecXml = (schema, options = {}) => {
 			return renderXml(wire, renderOptions).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, value, parseOptions)));
 		}
 	})));
-};
+});
 //#endregion
 export { toCodecXml };
 

package/dist/codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"codec.js","names":[],"sources":["../src/codec.ts"],"sourcesContent":["// The codec: a schema, and the XML text that carries it.\n//\n// `toCodecXml` is this package's counterpart to `Schema.toCodecJson`. It\n// returns a `Schema` whose `Type` is the source schema's `Type` and whose\n// `Encoded` is XML text, so a value is written with `Schema.encodeSync(codec)`\n// and read back with `Schema.decodeSync(codec)` — one call each, the way the\n// JSON codec works. There is no value tree at the call site and no second call\n// to a renderer or a parser.\n//\n// The derivation underneath is Effect's own `Schema.toCodecStringTree`, so\n// every schema feature Effect supports composes here without this package\n// re-implementing the walk over a schema AST. On the way out the codec runs the\n// value tree through `renderXml`; on the way back in it runs the document\n// through `parseXml`. Both are the same text layer this package exports on\n// their own, and both failures — an illegal name, a document that is not\n// well-formed — arrive as the `SchemaIssue.Issue` a schema is expected to\n// report, with the underlying message preserved.\n//\n// The conventions stay in the keys: a key starting with `@` is an attribute,\n// `#text` is character data, and every other key is a child element. The root\n// element is named from the schema's `identifier` or `title` annotation when it\n// has one, and from the `rootName` option otherwise; it defaults to `'root'`,\n// the same name Effect's own XML encoder uses.\n\nimport { Effect, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from 'effect';\n\nimport type { XmlParseOptions } from './parse.ts';\nimport type { XmlRenderOptions } from './render.ts';\nimport type { XmlValue } from './xml-value.ts';\n\nimport { DEFAULT_ROOT_NAME } from './conventions.ts';\nimport { decodeNames, encodeNames, namespacePlan, ROOT_ELEMENT } from './namespaces.ts';\nimport { parseXml } from './parse.ts';\nimport { renderXml } from './render.ts';\n\n/**\n * @description Options for {@link toCodecXml}.\\\n * The render options name and shape the document; the parse options decide how strictly it is read back.\\\n * `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\n * back to `'root'`.\n */\nexport type XmlCodecOptions = XmlRenderOptions & XmlParseOptions;\n\n/**\n * @description The XML codec for a schema, as a `Schema`. `Type` is the schema's own `Type` and `Encoded` is XML text, so it encodes a value to a document and\n * decodes a document to a value in one step each. The service requirements of the source schema are preserved.\n */\nexport interface toCodecXml<S extends Schema.Constraint> extends Schema.decodeTo<Schema.toCodecStringTree<S>, Schema.String> {\n  readonly Rebuild: toCodecXml<S>;\n}\n\n/**\n * @description Derives the XML codec for a schema: a `Schema` whose `Encoded` is an XML document, so `Schema.encodeSync(codec)` writes text and\n * `Schema.decodeSync(codec)` reads it back. The derivation is Effect's `Schema.toCodecStringTree`; the text layer is this package's {@link renderXml}\n * and {@link parseXml}.\n *\n * @example\n *   ```typescript\n *   import { Schema } from 'effect';\n *   import { toCodecXml } from '@endevops/effect-xml-codec';\n *\n *   const Book = Schema.Struct({ '@id': Schema.String, title: Schema.String, pages: Schema.Number });\n *   const codec = toCodecXml(Book, { rootName: 'book' });\n *\n *   const value = { '@id': '1', title: 'Dune', pages: 412 };\n *\n *   Schema.encodeSync(codec)(value);\n *   // => '<book id=\"1\"><title>Dune</title><pages>412</pages></book>'\n *\n *   Schema.decodeSync(codec)('<book id=\"1\"><title>Dune</title><pages>412</pages></book>');\n *   // => { '@id': '1', title: 'Dune', pages: 412 }\n *   ```;\n *\n * @param schema - The schema describing the value.\n * @param options - Render and parse options. `rootName` defaults to the schema's `identifier` or `title` annotation, then to `'root'`.\n *\n * @returns The codec, with the source schema's `Type` and the same service requirements.\n */\nexport const toCodecXml = <S extends Schema.Constraint>(schema: S, options: XmlCodecOptions = {}): toCodecXml<S> => {\n  const planned = namespacePlan(schema);\n  if (Predicate.hasProperty(planned, 'error')) {\n    throw new Error(`Invalid XML namespace annotation:\\n\\t- ${planned.error}.`);\n  }\n  const plan = planned.plan;\n  const active =\n    plan.byKey.size > 0 ||\n    plan.nameByKey.size > 0 ||\n    plan.attributeKeys.size > 0 ||\n    plan.valueByElement.size > 0 ||\n    plan.root !== undefined ||\n    plan.rootName !== undefined;\n\n  const rootName =\n    options.rootName ?? plan.rootName ?? SchemaAST.resolveIdentifier(schema.ast) ?? SchemaAST.resolveTitle(schema.ast) ?? DEFAULT_ROOT_NAME;\n  const wireRootName = plan.root !== undefined && plan.root.prefix !== '' && !rootName.includes(':') ? `${plan.root.prefix}:${rootName}` : rootName;\n\n  const renderOptions: XmlRenderOptions = { ...options, rootName: wireRootName };\n\n  return Schema.String.pipe(\n    Schema.decodeTo(\n      Schema.toCodecStringTree(schema),\n      SchemaTransformation.transformEffect({\n        decode: (text, parseOptions) => {\n          if (!Predicate.isString(text)) {\n            return Effect.fail(new SchemaIssue.InvalidValue({ message: `Expected a string, but received ${typeof text}.` }, text, parseOptions));\n          }\n\n          return parseXml(text, options).pipe(\n            Effect.map(value => (active ? decodeNames(value, plan, {}, ROOT_ELEMENT) : value)),\n            Effect.tapError(error =>\n              Effect.logError(`XML parse error: ${error.message}`).pipe(Effect.annotateLogs({ cause: error, message: 'XML parse error' }))\n            ),\n            Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, text, parseOptions))\n          );\n        },\n\n        encode: (value, parseOptions) => {\n          if (active && Array.isArray(value) && (plan.root !== undefined || plan.rootName !== undefined)) {\n            return Effect.fail(\n              new SchemaIssue.InvalidValue(\n                { message: 'An array at the root of a namespaced schema cannot carry the root namespace or name.' },\n                value,\n                parseOptions\n              )\n            );\n          }\n\n          const wire = active ? encodeNames(value as XmlValue, plan, plan.root, {}, ROOT_ELEMENT) : (value as XmlValue);\n          return renderXml(wire, renderOptions).pipe(\n            Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, value, parseOptions))\n          );\n        },\n      })\n    )\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8EA,MAAa,cAA2C,QAAW,UAA2B,CAAC,MAAqB;CAClH,MAAM,UAAU,cAAc,MAAM;CACpC,IAAI,UAAU,YAAY,SAAS,OAAO,GACxC,MAAM,IAAI,MAAM,0CAA0C,QAAQ,MAAM,EAAE;CAE5E,MAAM,OAAO,QAAQ;CACrB,MAAM,SACJ,KAAK,MAAM,OAAO,KAClB,KAAK,UAAU,OAAO,KACtB,KAAK,cAAc,OAAO,KAC1B,KAAK,eAAe,OAAO,KAC3B,KAAK,SAAS,KAAA,KACd,KAAK,aAAa,KAAA;CAEpB,MAAM,WACJ,QAAQ,YAAY,KAAK,YAAY,UAAU,kBAAkB,OAAO,GAAG,KAAK,UAAU,aAAa,OAAO,GAAG,KAAA;CACnH,MAAM,eAAe,KAAK,SAAS,KAAA,KAAa,KAAK,KAAK,WAAW,MAAM,CAAC,SAAS,SAAS,GAAG,IAAI,GAAG,KAAK,KAAK,OAAO,GAAG,aAAa;CAEzI,MAAM,gBAAkC;EAAE,GAAG;EAAS,UAAU;CAAa;CAE7E,OAAO,OAAO,OAAO,KACnB,OAAO,SACL,OAAO,kBAAkB,MAAM,GAC/B,qBAAqB,gBAAgB;EACnC,SAAS,MAAM,iBAAiB;GAC9B,IAAI,CAAC,UAAU,SAAS,IAAI,GAC1B,OAAO,OAAO,KAAK,IAAI,YAAY,aAAa,EAAE,SAAS,mCAAmC,OAAO,KAAK,GAAG,GAAG,MAAM,YAAY,CAAC;GAGrI,OAAO,SAAS,MAAM,OAAO,CAAC,CAAC,KAC7B,OAAO,KAAI,UAAU,SAAS,YAAY,OAAO,MAAM,CAAC,GAAA,EAAe,IAAI,KAAM,GACjF,OAAO,UAAS,UACd,OAAO,SAAS,oBAAoB,MAAM,SAAS,CAAC,CAAC,KAAK,OAAO,aAAa;IAAE,OAAO;IAAO,SAAS;GAAkB,CAAC,CAAC,CAC7H,GACA,OAAO,UAAS,UAAS,IAAI,YAAY,aAAa,EAAE,SAAS,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,CACvG;EACF;EAEA,SAAS,OAAO,iBAAiB;GAC/B,IAAI,UAAU,MAAM,QAAQ,KAAK,MAAM,KAAK,SAAS,KAAA,KAAa,KAAK,aAAa,KAAA,IAClF,OAAO,OAAO,KACZ,IAAI,YAAY,aACd,EAAE,SAAS,uFAAuF,GAClG,OACA,YACF,CACF;GAGF,MAAM,OAAO,SAAS,YAAY,OAAmB,MAAM,KAAK,MAAM,CAAC,GAAA,EAAe,IAAK;GAC3F,OAAO,UAAU,MAAM,aAAa,CAAC,CAAC,KACpC,OAAO,UAAS,UAAS,IAAI,YAAY,aAAa,EAAE,SAAS,MAAM,QAAQ,GAAG,OAAO,YAAY,CAAC,CACxG;EACF;CACF,CAAC,CACH,CACF;AACF"}
+{"version":3,"file":"codec.js","names":[],"sources":["../src/codec.ts"],"sourcesContent":["// The codec: a schema, and the XML text that carries it.\n//\n// `toCodecXml` is this package's counterpart to `Schema.toCodecJson`. It\n// returns a `Schema` whose `Type` is the source schema's `Type` and whose\n// `Encoded` is XML text, so a value is written with `Schema.encodeSync(codec)`\n// and read back with `Schema.decodeSync(codec)`. That is one call each, as with\n// the JSON codec. There is no value tree at the call site and no second call to\n// a renderer or a parser.\n//\n// The derivation underneath is Effect's own `Schema.toCodecStringTree`, so\n// every schema feature Effect supports composes here without this package\n// re-implementing the walk over a schema AST. On encode the codec runs the value\n// tree through `renderXml`; on decode it runs the document through `parseXml`.\n// Both are the same text layer this package exports on its own, and both\n// failures arrive as the `SchemaIssue.Issue` a schema is expected to report,\n// with the underlying message preserved. Those failures are an illegal name and\n// a document that is not well-formed.\n//\n// The conventions stay in the keys: a key starting with `@` is an attribute,\n// `#text` is character data, and every other key is a child element. The root\n// element is named from the schema's `identifier` or `title` annotation when it\n// has one, and from the `rootName` option otherwise; it defaults to `'root'`,\n// the same name Effect's own XML encoder uses.\n\nimport { Effect, Function, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from 'effect';\n\nimport type { NamespacePlan } from './namespaces.ts';\nimport type { XmlParseOptions } from './parse.ts';\nimport type { XmlRenderOptions } from './render.ts';\nimport type { XmlValue } from './xml-value.ts';\n\nimport { DEFAULT_ROOT_NAME } from './conventions.ts';\nimport { decodeNames, encodeNames, namespacePlan, ROOT_ELEMENT } from './namespaces.ts';\nimport { parseXml } from './parse.ts';\nimport { renderXml } from './render.ts';\n\n/**\n * @description Options for {@link toCodecXml}.\\\n * The render options name and shape the document; the parse options decide how strictly it is read back.\\\n * `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\n * falls back to `'root'`.\n */\nexport type XmlCodecOptions = XmlRenderOptions & XmlParseOptions;\n\n/**\n * @description The XML codec for a schema, as a `Schema`. `Type` is the schema's own `Type` and `Encoded` is XML text, so it encodes a value to a document and\n * decodes a document to a value in one step each. The service requirements of the source schema are preserved.\n */\nexport interface toCodecXml<S extends Schema.Constraint> extends Schema.decodeTo<Schema.toCodecStringTree<S>, Schema.String> {\n  readonly Rebuild: toCodecXml<S>;\n}\n\n// 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\n// alone on both sides, so the codec skips the name walk.\nconst isActivePlan = (plan: NamespacePlan): boolean =>\n  plan.byKey.size > 0 ||\n  plan.nameByKey.size > 0 ||\n  plan.attributeKeys.size > 0 ||\n  plan.valueByElement.size > 0 ||\n  plan.root !== undefined ||\n  plan.rootName !== undefined;\n\n// 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`\n// or `title` annotation, then `'root'`. A root namespace with a prefix qualifies the name unless the caller already wrote one.\nconst resolveRenderOptions = <S extends Schema.Constraint>(schema: S, plan: NamespacePlan, options: XmlCodecOptions): XmlRenderOptions => {\n  const rootName =\n    options.rootName ?? plan.rootName ?? SchemaAST.resolveIdentifier(schema.ast) ?? SchemaAST.resolveTitle(schema.ast) ?? DEFAULT_ROOT_NAME;\n  const wireRootName = plan.root !== undefined && plan.root.prefix !== '' && !rootName.includes(':') ? `${plan.root.prefix}:${rootName}` : rootName;\n  return { ...options, rootName: wireRootName };\n};\n\n/**\n * @description Derives the XML codec for a schema: a `Schema` whose `Encoded` is an XML document, so `Schema.encodeSync(codec)` writes text and\n * `Schema.decodeSync(codec)` reads it back. The derivation is Effect's `Schema.toCodecStringTree`; the text layer is this package's {@link renderXml}\n * and {@link parseXml}. Call it data-first, `toCodecXml(schema, options)`, or data-last, `toCodecXml(options)(schema)`, so it drops into `pipe` beside\n * 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\n * options object as data-last. `pipe(schema, toCodecXml)` carries no options and works because a schema on its own is data-first.\n *\n * @example\n *   ```typescript\n *   import { Schema, pipe } from 'effect';\n *   import { toCodecXml } from '@endevops/effect-codec-xml';\n *\n *   const Book = Schema.Struct({ '@id': Schema.String, title: Schema.String, pages: Schema.Number });\n *   const codec = toCodecXml(Book, { rootName: 'book' });\n *   const piped = pipe(Book, toCodecXml({ rootName: 'book' }));\n *\n *   const value = { '@id': '1', title: 'Dune', pages: 412 };\n *\n *   Schema.encodeSync(codec)(value);\n *   // => '<book id=\"1\"><title>Dune</title><pages>412</pages></book>'\n *\n *   Schema.decodeSync(codec)('<book id=\"1\"><title>Dune</title><pages>412</pages></book>');\n *   // => { '@id': '1', title: 'Dune', pages: 412 }\n *   ```;\n *\n * @param schema - The schema describing the value, in the data-first form.\n * @param options - Render and parse options. `rootName` defaults to the schema's `identifier` or `title` annotation, then to `'root'`. In the\n *   data-last form this is the only argument, and the schema arrives from `pipe`.\n *\n * @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\n *   codec.\n */\nexport const toCodecXml: {\n  <S extends Schema.Constraint>(schema: S, options?: XmlCodecOptions): toCodecXml<S>;\n  (options?: XmlCodecOptions): <S extends Schema.Constraint>(schema: S) => toCodecXml<S>;\n} = Function.dual(\n  args => Schema.isSchema(args[0]),\n  <S extends Schema.Constraint>(schema: S, options: XmlCodecOptions = {}): toCodecXml<S> => {\n    const planned = namespacePlan(schema);\n    if (Predicate.hasProperty(planned, 'error')) {\n      throw new Error(`Invalid XML namespace annotation:\\n\\t- ${planned.error}.`);\n    }\n    const plan = planned.plan;\n    const active = isActivePlan(plan);\n    const renderOptions = resolveRenderOptions(schema, plan, options);\n\n    return Schema.String.pipe(\n      Schema.decodeTo(\n        Schema.toCodecStringTree(schema),\n        SchemaTransformation.transformEffect({\n          decode: (text, parseOptions) => {\n            if (!Predicate.isString(text)) {\n              return Effect.fail(new SchemaIssue.InvalidValue({ message: `Expected a string, but received ${typeof text}.` }, text, parseOptions));\n            }\n\n            return parseXml(text, options).pipe(\n              Effect.map(value => (active ? decodeNames(value, plan, {}, ROOT_ELEMENT) : value)),\n              Effect.tapError(error =>\n                Effect.logError(`XML parse error: ${error.message}`).pipe(Effect.annotateLogs({ cause: error, message: 'XML parse error' }))\n              ),\n              Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, text, parseOptions))\n            );\n          },\n\n          encode: (value, parseOptions) => {\n            if (active && Array.isArray(value) && (plan.root !== undefined || plan.rootName !== undefined)) {\n              return Effect.fail(\n                new SchemaIssue.InvalidValue(\n                  { message: 'An array at the root of a namespaced schema cannot carry the root namespace or name.' },\n                  value,\n                  parseOptions\n                )\n              );\n            }\n\n            const wire = active ? encodeNames(value as XmlValue, plan, plan.root, {}, ROOT_ELEMENT) : (value as XmlValue);\n            return renderXml(wire, renderOptions).pipe(\n              Effect.mapError(error => new SchemaIssue.InvalidValue({ message: error.message }, value, parseOptions))\n            );\n          },\n        })\n      )\n    );\n  }\n);\n"],"mappings":";;;;;;AAsDA,MAAM,gBAAgB,SACpB,KAAK,MAAM,OAAO,KAClB,KAAK,UAAU,OAAO,KACtB,KAAK,cAAc,OAAO,KAC1B,KAAK,eAAe,OAAO,KAC3B,KAAK,SAAS,KAAA,KACd,KAAK,aAAa,KAAA;AAIpB,MAAM,wBAAqD,QAAW,MAAqB,YAA+C;CACxI,MAAM,WACJ,QAAQ,YAAY,KAAK,YAAY,UAAU,kBAAkB,OAAO,GAAG,KAAK,UAAU,aAAa,OAAO,GAAG,KAAA;CACnH,MAAM,eAAe,KAAK,SAAS,KAAA,KAAa,KAAK,KAAK,WAAW,MAAM,CAAC,SAAS,SAAS,GAAG,IAAI,GAAG,KAAK,KAAK,OAAO,GAAG,aAAa;CACzI,OAAO;EAAE,GAAG;EAAS,UAAU;CAAa;AAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAa,aAGT,SAAS,MACX,SAAQ,OAAO,SAAS,KAAK,EAAE,IACD,QAAW,UAA2B,CAAC,MAAqB;CACxF,MAAM,UAAU,cAAc,MAAM;CACpC,IAAI,UAAU,YAAY,SAAS,OAAO,GACxC,MAAM,IAAI,MAAM,0CAA0C,QAAQ,MAAM,EAAE;CAE5E,MAAM,OAAO,QAAQ;CACrB,MAAM,SAAS,aAAa,IAAI;CAChC,MAAM,gBAAgB,qBAAqB,QAAQ,MAAM,OAAO;CAEhE,OAAO,OAAO,OAAO,KACnB,OAAO,SACL,OAAO,kBAAkB,MAAM,GAC/B,qBAAqB,gBAAgB;EACnC,SAAS,MAAM,iBAAiB;GAC9B,IAAI,CAAC,UAAU,SAAS,IAAI,GAC1B,OAAO,OAAO,KAAK,IAAI,YAAY,aAAa,EAAE,SAAS,mCAAmC,OAAO,KAAK,GAAG,GAAG,MAAM,YAAY,CAAC;GAGrI,OAAO,SAAS,MAAM,OAAO,CAAC,CAAC,KAC7B,OAAO,KAAI,UAAU,SAAS,YAAY,OAAO,MAAM,CAAC,GAAA,EAAe,IAAI,KAAM,GACjF,OAAO,UAAS,UACd,OAAO,SAAS,oBAAoB,MAAM,SAAS,CAAC,CAAC,KAAK,OAAO,aAAa;IAAE,OAAO;IAAO,SAAS;GAAkB,CAAC,CAAC,CAC7H,GACA,OAAO,UAAS,UAAS,IAAI,YAAY,aAAa,EAAE,SAAS,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,CACvG;EACF;EAEA,SAAS,OAAO,iBAAiB;GAC/B,IAAI,UAAU,MAAM,QAAQ,KAAK,MAAM,KAAK,SAAS,KAAA,KAAa,KAAK,aAAa,KAAA,IAClF,OAAO,OAAO,KACZ,IAAI,YAAY,aACd,EAAE,SAAS,uFAAuF,GAClG,OACA,YACF,CACF;GAGF,MAAM,OAAO,SAAS,YAAY,OAAmB,MAAM,KAAK,MAAM,CAAC,GAAA,EAAe,IAAK;GAC3F,OAAO,UAAU,MAAM,aAAa,CAAC,CAAC,KACpC,OAAO,UAAS,UAAS,IAAI,YAAY,aAAa,EAAE,SAAS,MAAM,QAAQ,GAAG,OAAO,YAAY,CAAC,CACxG;EACF;CACF,CAAC,CACH,CACF;AACF,CACF"}

package/dist/conventions.d.ts

@@ -73,10 +73,10 @@ export declare const isTextKey: (key: string) => boolean;
  */
 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.
+ * @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.
  *
  * @param name - The candidate element or attribute name.
  * @param options - Repair mode and XML version.

package/dist/conventions.js

@@ -51,9 +51,9 @@ const isTextKey = (key) => key === TEXT_KEY;
 */
 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.
+* @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.
 *
 * @param name - The candidate element or attribute name.
 * @param options - Repair mode and XML version.
@@ -96,10 +96,10 @@ const resolveNameResult = (name, options) => {
 	}
 };
 /**
-* @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.
+* @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.
 *
 * @param name - The candidate element or attribute name.
 * @param options - Repair mode and XML version.

package/dist/conventions.js.map

@@ -1 +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"}
+{"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\n * 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\n * illegal name by throwing 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. An illegal\n * 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\n * 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`\n * 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"}