@endevops/effect-codec-xml 0.0.1

package/src/entities/entity-tables.ts

@@ -0,0 +1,18 @@
+// entity-tables
+//
+// The named-entity tables the decoder reads. Only the five XML predefined
+// entities survive here: the HTML tables belonged to the entity encoder, and
+// the encoder was removed when `@endevops/common-xml` was merged into this
+// package. The data is verbatim from `@nodable/entities@2.2.0`
+// (`src/entities.js`); see `LICENSE-is-entities`.
+
+/**
+ * @description A named-entity lookup: entity name to the replacement text it expands to. Every table in this module has this shape.
+ */
+export type EntityTable = Readonly<Record<string, string>>;
+
+/**
+ * @description The five XML predefined entities. The XML specification fixes these five names, so they are matched as a set rather than drawn from a table of
+ * aliases. `EntityDecoder` merges these into its base map by default.
+ */
+export const XML: EntityTable = { amp: '&', apos: "'", gt: '>', lt: '<', quot: '"' };

package/src/errors.ts

@@ -0,0 +1,55 @@
+// The one way XML serialization can fail that a `SchemaIssue.Issue` does not already describe.
+//
+// A schema mismatch — a `number` where the document says `text` — is a
+// `SchemaIssue.Issue` and comes from Effect's own parser. What is left is the
+// part Effect knows nothing about: a document that is not well-formed XML, and a
+// field name that cannot be written as one.
+
+import { Schema } from 'effect';
+
+/**
+ * @description A document could not be read as XML.
+ *
+ * @example
+ *   ```typescript
+ *   import { XmlParseError } from '@endevops/effect-xml-codec';
+ *
+ *   const error = new XmlParseError({ message: 'Unclosed element', position: 12, input: '<a><b>' });
+ *   ```;
+ */
+export class XmlParseError extends Schema.TaggedError<XmlParseError>()('XmlParseError', {
+  /**
+   * @description What was wrong with the document.
+   */
+  message: Schema.String,
+
+  /**
+   * @description Character offset into the source text where the problem was found. `-1` when the failure is not tied to a position, such as trailing content
+   * after the root element.
+   */
+  position: Schema.Finite,
+
+  /**
+   * @description The source text that failed to parse, so a log can carry the document without the caller re-reading it.
+   */
+  input: Schema.String,
+}) {}
+
+/**
+ * @description A value could not be written as XML. A field name that is not a legal XML name fails here, in `'error'` name mode; repair mode rewrites the name
+ * instead. The depth cap fails here too, when a value nests past `maxDepth`. Reading uses {@link XmlParseError}, because the two directions fail for
+ * different reasons and a caller recovering from one usually does not want to catch the other.
+ *
+ * @example
+ *   ```typescript
+ *   import { XmlRenderError } from '@endevops/effect-xml-codec';
+ *
+ *   const error = new XmlRenderError({ message: 'Invalid XML name "not a name"' });
+ *   ```;
+ */
+export class XmlRenderError extends Schema.TaggedError<XmlRenderError>()('XmlRenderError', {
+  /**
+   * @description What was wrong with the value.
+   */
+  message: Schema.String,
+}) {}

package/src/index.ts

@@ -0,0 +1,79 @@
+/**
+ * @description 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. Attributes are the fields whose names start with `@`,
+ * so `@xmlns` is written as `xmlns="…"`, and `#text` holds an element's character data. A schema node annotated with `xmlNamespace` is placed in that
+ * namespace, and the codec resolves the document's own prefixes back to it. `renderXml` and `parseXml` are the text layer the codec runs underneath,
+ * and remain available on their own.
+ *
+ * @example
+ *   ```typescript
+ *   import { Schema } from 'effect';
+ *   import { toCodecXml } from '@endevops/effect-xml-codec';
+ *
+ *   const Book = Schema.Struct({
+ *     '@id': Schema.String,
+ *     title: Schema.String,
+ *     tag: Schema.Array(Schema.String),
+ *   });
+ *
+ *   const codec = toCodecXml(Book, { rootName: 'book' });
+ *   const value = { '@id': '1', title: 'Dune', tag: ['sci-fi'] };
+ *
+ *   const text = Schema.encodeSync(codec)(value);
+ *   // => '<book id="1"><title>Dune</title><tag>sci-fi</tag></book>'
+ *
+ *   Schema.decodeSync(codec)(text); // => value
+ *   ```;
+ *
+ * @packageDocumentation
+ */
+
+export { toCodecXml } from './codec.ts';
+export type { XmlCodecOptions } from './codec.ts';
+
+export {
+  ATTRIBUTE_PREFIX,
+  DEFAULT_ITEM_NAME,
+  DEFAULT_ROOT_NAME,
+  TEXT_KEY,
+  attributeName,
+  isAttributeKey,
+  isReservedKey,
+  isTextKey,
+  resolveName,
+} from './conventions.ts';
+export type { NameMode, ResolveNameOptions } from './conventions.ts';
+
+export { XmlParseError, XmlRenderError } from './errors.ts';
+
+export { ATTRIBUTE_KEY, NAME_KEY, NAMESPACE_KEY, PREFIX_KEY, VALUE_KEY } from './namespaces.ts';
+export type { NamespacePlan, XmlNamespace } from './namespaces.ts';
+
+export { parseXml } from './parse.ts';
+export type { XmlDocument, XmlParseOptions } from './parse.ts';
+
+export { escapeAttribute, escapeText, renderXml } from './render.ts';
+export type { XmlRenderOptions } from './render.ts';
+
+export { XmlValue as XmlValueSchema, isXmlValue } from './xml-value.ts';
+export type { XmlRecord, XmlValue } from './xml-value.ts';
+
+// The primitives that were `@endevops/common-xml`. The entity decoder and the
+// name validators moved in with the codec; the path matcher, the entity encoder
+// and the HTML tables did not, because nothing in this package reaches them.
+export { EntityDecoder, ENTITY_ACTION } from './entities/entity-decoder.ts';
+export type {
+  ApplyLimitsTo,
+  EntityDecoderLimitOptions,
+  EntityDecoderNCROptions,
+  EntityDecoderOptions,
+  EntityHookAction,
+  EntityRegistrationHook,
+  EntityValFn,
+} from './entities/entity-decoder.ts';
+
+export { isName, isNcName, isNmToken, isNmTokens, isQName, sanitize, validate } from './naming.ts';
+export type { Production, SanitizeOptions, ValidationOptions, ValidationResult, XmlVersion } from './naming.ts';
+
+export { XmlError, XmlErrorReason } from './xml-error.ts';
+export type { XmlErrorReason as XmlErrorReasonType } from './xml-error.ts';