@endevops/effect-codec-xml 0.0.1

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@endevops/effect-codec-xml",
+  "version": "0.0.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",
+    "decode",
+    "effect",
+    "effect-schema",
+    "entities",
+    "entity-decoder",
+    "ncname",
+    "nmtoken",
+    "qname",
+    "xml",
+    "xml-codec",
+    "xml-naming",
+    "xml-parser",
+    "xml-serialization"
+  ],
+  "homepage": "https://github.com/Endevops/effect-xml/tree/master/packages/effect-xml-codec#readme",
+  "bugs": {
+    "url": "https://github.com/Endevops/effect-xml/issues"
+  },
+  "license": "MIT",
+  "author": "Endevops",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Endevops/effect-xml.git",
+    "directory": "packages/effect-xml-codec"
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "!src/**/*.{spec,test}.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#/*": "./src/*",
+    "#/test/*": "./test/*"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@effect/vitest": "^4.0.0",
+    "effect": "^4.0.0",
+    "publint": "^0.3.24",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
+    "vite-plus": "1.0.0"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch"
+  }
+}

package/src/codec.ts

@@ -0,0 +1,136 @@
+// The codec: a schema, and the XML text that carries it.
+//
+// `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)` — 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 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
+// element is named from the schema's `identifier` or `title` annotation when it
+// has one, and from the `rootName` option otherwise; it defaults to `'root'`,
+// the same name Effect's own XML encoder uses.
+
+import { Effect, Predicate, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from 'effect';
+
+import type { XmlParseOptions } from './parse.ts';
+import type { XmlRenderOptions } from './render.ts';
+import type { XmlValue } from './xml-value.ts';
+
+import { DEFAULT_ROOT_NAME } from './conventions.ts';
+import { decodeNames, encodeNames, namespacePlan, ROOT_ELEMENT } from './namespaces.ts';
+import { parseXml } from './parse.ts';
+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, taking it from the schema's `identifier` or `title` annotation and falling
+ * back to `'root'`.
+ */
+export type XmlCodecOptions = XmlRenderOptions & XmlParseOptions;
+
+/**
+ * @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
+ * decodes a document to a value in one step each. The service requirements of the source schema are preserved.
+ */
+export interface toCodecXml<S extends Schema.Constraint> extends Schema.decodeTo<Schema.toCodecStringTree<S>, Schema.String> {
+  readonly Rebuild: toCodecXml<S>;
+}
+
+/**
+ * @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}.
+ *
+ * @example
+ *   ```typescript
+ *   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 value = { '@id': '1', title: 'Dune', pages: 412 };
+ *
+ *   Schema.encodeSync(codec)(value);
+ *   // => '<book id="1"><title>Dune</title><pages>412</pages></book>'
+ *
+ *   Schema.decodeSync(codec)('<book id="1"><title>Dune</title><pages>412</pages></book>');
+ *   // => { '@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'`.
+ *
+ * @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> => {
+  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;
+
+  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;
+
+  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));
+          }
+
+          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))
+          );
+        },
+
+        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

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