@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/serialize/markup/writer.js

@@ -0,0 +1,183 @@
+/**
+ * The markup writer of the xml, xhtml and html output methods: writes the
+ * normalized sequence (see sequence.js) as markup, with the method's rules
+ * from dialect.js.
+ *
+ * The walk is iterative: every element whose children are being written
+ * is a frame on an explicit stack, so a tree nested deeper than the
+ * JavaScript call stack allows is written like any other, and the output
+ * is handed out in chunks as it grows.
+ *
+ * @module @tradik/xslt3/serialize/markup/writer
+ */
+
+import { Expander } from "../output/expander.js";
+import {
+  checkDocument,
+  childList,
+  escapeNamespaceUri,
+  isWhitespace,
+} from "./content.js";
+import { Dialect } from "./dialect.js";
+import { fixupElement, XML_NAMESPACE } from "./namespaces.js";
+import { contentTypeMeta, doctype, xmlDeclaration } from "./prolog.js";
+
+/** Indentation added per level. */
+const INDENT = "  ";
+
+/** Writes markup for one serialization. */
+export class MarkupWriter {
+  /**
+   * @param {import("../params/settings.js").Settings} settings
+   * @param {import("../output/buffer.js").OutputBuffer} buffer
+   */
+  constructor(settings, buffer) {
+    this.settings = settings;
+    this.buffer = buffer;
+    this.expander = new Expander(settings);
+    this.dialect = new Dialect(settings);
+    this.doctypePending = true;
+    this.fixup = {
+      top: true,
+      unprefixed: this.dialect.unprefixed,
+      undeclare: settings.undeclarePrefixes && settings.version === "1.1",
+    };
+  }
+
+  /** @param {string} text - Markup */
+  write(text) {
+    this.buffer.write(text);
+  }
+
+  /**
+   * Writes the normalized sequence.
+   * @param {Array<string|Node>} entries - From normalizeSequence
+   * @yields {string} chunks of output, when the buffer is full
+   * @returns {Generator<string, void, void>}
+   */
+  *run(entries) {
+    checkDocument(entries, this.settings);
+    const declaration = xmlDeclaration(this.settings);
+    const indent = this.settings.indent;
+    const indentTop = indent && !entries.some((e) => typeof e === "string");
+    this.write(declaration && indent ? `${declaration}\n` : declaration);
+    const top = { depth: -1, scope: new Map(), preserve: false };
+    for (let i = 0; i < entries.length; i++) {
+      if (indentTop && i > 0) this.write("\n");
+      const entry = entries[i];
+      if (typeof entry === "string") this.write(this.expander.text(entry));
+      else if (entry.nodeType === 1) yield* this.tree(entry, top);
+      else this.leaf(entry, "escape");
+      if (this.buffer.full) yield this.buffer.take();
+    }
+  }
+
+  /**
+   * Writes an element and its descendants.
+   * @param {Element} element
+   * @param {object} top - The frame of the document
+   * @yields {string} chunks of output
+   * @returns {Generator<string, void, void>}
+   */
+  *tree(element, top) {
+    const stack = [];
+    const root = this.openElement(element, top);
+    if (root) stack.push(root);
+    while (stack.length) {
+      const frame = stack[stack.length - 1];
+      if (frame.index === frame.children.length) {
+        stack.pop();
+        this.write(frame.end);
+        continue;
+      }
+      const child = frame.children[frame.index++];
+      if (frame.indent) this.write(`\n${INDENT.repeat(frame.depth + 1)}`);
+      if (typeof child === "object" && child.nodeType === 1) {
+        const opened = this.openElement(child, frame);
+        if (opened) stack.push(opened);
+      } else {
+        this.leaf(child, frame.textMode);
+      }
+      if (this.buffer.full) yield this.buffer.take();
+    }
+  }
+
+  /**
+   * Writes character data, a comment or a processing instruction.
+   * @param {string|Node} node
+   * @param {"escape"|"cdata"|"raw"} textMode
+   */
+  leaf(node, textMode) {
+    const { expander } = this;
+    if (typeof node === "string") {
+      this.write(expander[textMode === "escape" ? "text" : textMode](node));
+    } else if (node.nodeType === 8) {
+      this.write(`<!--${expander.unescaped(node.nodeValue)}-->`);
+    } else {
+      this.write(this.dialect.processingInstruction(node, expander));
+    }
+  }
+
+  /**
+   * Writes the start tag of an element, or the whole element when it is
+   * empty.
+   * @param {Element} element
+   * @param {object} parent - Frame of the parent
+   * @returns {object|null} the frame of its children, null when empty
+   */
+  openElement(element, parent) {
+    const { dialect, settings } = this;
+    this.fixup.top = parent.depth < 0;
+    const fixed = fixupElement(element, parent.scope, this.fixup);
+    const info = dialect.describe(element, fixed);
+    if (this.doctypePending) {
+      this.doctypePending = false;
+      const declaration = doctype(settings, fixed.name);
+      if (declaration) this.write(`${declaration}\n`);
+    }
+    let tag = `<${this.expander.unescaped(fixed.name)}`;
+    for (const [prefix, uri] of fixed.declarations) {
+      tag += ` xmlns${prefix ? `:${prefix}` : ""}="${escapeNamespaceUri(uri)}"`;
+    }
+    for (const attribute of fixed.attributes) {
+      tag += dialect.attribute(info, attribute, this.expander);
+    }
+    const head =
+      info.isHtml && info.lower === "head" && settings.includeContentType;
+    let children = childList(element, head);
+    const leading = head ? contentTypeMeta(settings) : "";
+    if (!children.length && !leading) {
+      this.write(tag + dialect.emptyElement(info));
+      return null;
+    }
+    this.write(`${tag}>`);
+    const space = element.getAttributeNS?.(XML_NAMESPACE, "space");
+    const preserve =
+      space === "preserve" || (space !== "default" && parent.preserve);
+    const suppressed = parent.suppressed || dialect.suppressesIndent(info);
+    const textMode = dialect.textMode(info);
+    const indent =
+      settings.indent &&
+      !preserve &&
+      !suppressed &&
+      textMode !== "raw" &&
+      children.some((child) => typeof child !== "string") &&
+      children.every((c) => typeof c !== "string" || isWhitespace(c)) &&
+      dialect.allowsIndent(children);
+    if (indent) children = children.filter((c) => typeof c !== "string");
+    const depth = parent.depth + 1;
+    const lineStart = indent ? `\n${INDENT.repeat(depth)}` : "";
+    if (leading) this.write(indent ? lineStart + INDENT + leading : leading);
+    return {
+      children,
+      index: 0,
+      indent,
+      depth,
+      scope: fixed.scope,
+      textMode,
+      preserve,
+      suppressed,
+      end: `${lineStart}</${fixed.name}>`,
+    };
+  }
+}

package/src/serialize/methods/adaptive.js

@@ -0,0 +1,131 @@
+/**
+ * The adaptive output method (Serialization 3.1 section 11): any
+ * sequence, written in a form close to XPath syntax. Items are separated
+ * by item-separator (a newline by default); nodes are written with the
+ * xml method, attributes as name="value", maps as map{key:value,...},
+ * arrays as [...], strings quoted, other atomic values as constructor
+ * calls (xs:date("...")), functions as name#arity.
+ *
+ * @module @tradik/xslt3/serialize/methods/adaptive
+ */
+
+import { canonicalString, itemKind } from "../../xdm/index.js";
+
+/** Prefixes of the standard function namespaces. */
+const FUNCTION_PREFIXES = {
+  "http://www.w3.org/2005/xpath-functions": "fn",
+  "http://www.w3.org/2005/xpath-functions/math": "math",
+  "http://www.w3.org/2005/xpath-functions/map": "map",
+  "http://www.w3.org/2005/xpath-functions/array": "array",
+  "http://www.w3.org/2001/XMLSchema": "xs",
+};
+
+/** Types written as quoted strings. */
+const STRING_TYPES = new Set(["string", "anyURI", "untypedAtomic"]);
+
+/**
+ * An xs:double in exponential notation, e.g. 1.0e0 or -1.25e-3.
+ * @param {number} value
+ * @returns {string}
+ */
+export function doubleText(value) {
+  if (Number.isNaN(value)) return "NaN";
+  if (!Number.isFinite(value)) return value > 0 ? "INF" : "-INF";
+  if (value === 0) return Object.is(value, -0) ? "-0.0e0" : "0.0e0";
+  const [mantissa, exponent] = value.toExponential().split("e");
+  const digits = mantissa.includes(".") ? mantissa : `${mantissa}.0`;
+  return `${digits}e${Number(exponent)}`;
+}
+
+/**
+ * @param {{namespaceURI: string, localName: string, prefix?: string}} name
+ * @returns {string} prefix:local for known namespaces, else Q{uri}local
+ */
+function functionName(name) {
+  const prefix = FUNCTION_PREFIXES[name.namespaceURI] ?? name.prefix;
+  if (prefix) return `${prefix}:${name.localName}`;
+  return name.namespaceURI
+    ? `Q{${name.namespaceURI}}${name.localName}`
+    : name.localName;
+}
+
+/** Writes the adaptive form of items. */
+export class AdaptiveWriter {
+  /**
+   * @param {import("../output/expander.js").Expander} expander
+   * @param {(node: Node) => string} serializeNode - The xml method
+   */
+  constructor(expander, serializeNode) {
+    this.expander = expander;
+    this.serializeNode = serializeNode;
+  }
+
+  /**
+   * @param {Array} sequence
+   * @returns {string} one item as is, others in parentheses
+   */
+  sequence(sequence) {
+    if (sequence.length === 1) return this.item(sequence[0]);
+    return `(${sequence.map((item) => this.item(item)).join(",")})`;
+  }
+
+  /**
+   * @param {*} item
+   * @returns {string}
+   */
+  item(item) {
+    switch (itemKind(item)) {
+      case "atomic":
+        return this.atomic(item);
+      case "node":
+        return this.node(item);
+      case "map": {
+        const entries = [...item.entries.values()].map(
+          ({ key, value }) => `${this.atomic(key)}:${this.sequence(value)}`,
+        );
+        return `map{${entries.join(",")}}`;
+      }
+      case "array":
+        return `[${item.members.map((m) => this.sequence(m)).join(",")}]`;
+      default: {
+        const name = item.name
+          ? functionName(item.name)
+          : "(anonymous-function)";
+        return `${name}#${item.arity}`;
+      }
+    }
+  }
+
+  /**
+   * @param {Node} node
+   * @returns {string}
+   */
+  node(node) {
+    if (node.nodeType === 2) {
+      const value = this.expander.attribute(node.value);
+      return `${node.name}="${value}"`;
+    }
+    if (node.nodeType === 13) {
+      const name = node.localName ? `xmlns:${node.localName}` : "xmlns";
+      return `${name}="${this.expander.attribute(node.nodeValue)}"`;
+    }
+    return this.serializeNode(node);
+  }
+
+  /**
+   * @param {import("../../xdm/atomic.js").AtomicValue} item
+   * @returns {string}
+   */
+  atomic(item) {
+    const primitive = item.type.primitive;
+    const name = primitive.localName;
+    if (STRING_TYPES.has(name)) return `"${item.value.replaceAll('"', '""')}"`;
+    if (name === "boolean") return item.value ? "true()" : "false()";
+    if (name === "decimal") return canonicalString(item);
+    if (name === "double") return doubleText(item.value);
+    if (name === "QName") {
+      return `Q{${item.value.namespaceURI}}${item.value.localName}`;
+    }
+    return `${primitive.prefixedName}("${canonicalString(item)}")`;
+  }
+}

package/src/serialize/methods/json.js

@@ -0,0 +1,158 @@
+/**
+ * The JSON output method (Serialization 3.1 section 10): maps as objects,
+ * arrays as arrays, numbers, booleans and strings as themselves, other
+ * atomic values as strings, nodes as strings holding their serialization
+ * with json-node-output-method.
+ *
+ * Errors: SERE0020 for NaN and infinities, SERE0021 for function items,
+ * SERE0022 for duplicate keys (unless allow-duplicate-names), SERE0023
+ * for sequences of more than one item.
+ *
+ * @module @tradik/xslt3/serialize/methods/json
+ */
+
+import { XPathError } from "../../errors.js";
+import { canonicalString, itemKind } from "../../xdm/index.js";
+
+const ESCAPES = {
+  '"': '\\"',
+  "\\": "\\\\",
+  "/": "\\/",
+  "\b": "\\b",
+  "\f": "\\f",
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+};
+
+/**
+ * @param {number} unit - UTF-16 code unit
+ * @returns {string} a \u escape
+ */
+const unicodeEscape = (unit) =>
+  `\\u${unit.toString(16).toUpperCase().padStart(4, "0")}`;
+
+/** Writes JSON for one serialization. */
+export class JsonWriter {
+  /**
+   * @param {import("../params/settings.js").Settings} settings
+   * @param {import("../output/expander.js").Expander} expander - For
+   *   character maps and normalization
+   * @param {(node: Node) => string} serializeNode - Serializes a node
+   *   with json-node-output-method
+   */
+  constructor(settings, expander, serializeNode) {
+    this.settings = settings;
+    this.expander = expander;
+    this.serializeNode = serializeNode;
+    const encodable = settings.encoding.encodable;
+    this.escapeChar = (char) => {
+      if (ESCAPES[char]) return ESCAPES[char];
+      const cp = char.codePointAt(0);
+      if (cp < 0xa0 || (encodable && !encodable(cp))) {
+        let escaped = "";
+        for (let i = 0; i < char.length; i++) {
+          escaped += unicodeEscape(char.charCodeAt(i));
+        }
+        return escaped;
+      }
+      return char;
+    };
+    const escaped = '["\\\\/\\u0000-\\u001F\\u007F-\\u009F]';
+    this.pattern = new RegExp(
+      encodable ? `${escaped}|[^\\u0000-\\u007F]` : escaped,
+      "gu",
+    );
+  }
+
+  /**
+   * @param {string} text
+   * @returns {string} a JSON string literal
+   */
+  string(text) {
+    const body = this.expander.mapped(text, (run) =>
+      run.replace(this.pattern, this.escapeChar),
+    );
+    return `"${body}"`;
+  }
+
+  /**
+   * @param {Array} sequence - A value: at most one item
+   * @param {number} depth - Nesting depth, for indentation
+   * @returns {string}
+   */
+  sequence(sequence, depth) {
+    if (sequence.length > 1) {
+      throw new XPathError(
+        "SERE0023",
+        "The JSON output method cannot write a sequence of several items",
+      );
+    }
+    return sequence.length ? this.item(sequence[0], depth) : "null";
+  }
+
+  /**
+   * @param {string[]} members - Serialized members
+   * @param {string} open
+   * @param {string} close
+   * @param {number} depth
+   * @returns {string} an object or array
+   */
+  container(members, open, close, depth) {
+    if (!members.length) return open + close;
+    if (!this.settings.indent) return open + members.join(",") + close;
+    const inner = `\n${"  ".repeat(depth + 1)}`;
+    return `${open}${inner}${members.join(`,${inner}`)}\n${"  ".repeat(depth)}${close}`;
+  }
+
+  /**
+   * @param {*} item
+   * @param {number} depth
+   * @returns {string}
+   */
+  item(item, depth) {
+    const kind = itemKind(item);
+    if (kind === "map") {
+      const seen = new Set();
+      const separator = this.settings.indent ? ": " : ":";
+      const members = [...item.entries.values()].map(({ key, value }) => {
+        const name = canonicalString(key);
+        if (seen.has(name) && !this.settings.allowDuplicateNames) {
+          throw new XPathError("SERE0022", `Duplicate key ${name} in JSON`);
+        }
+        seen.add(name);
+        return this.string(name) + separator + this.sequence(value, depth + 1);
+      });
+      return this.container(members, "{", "}", depth);
+    }
+    if (kind === "array") {
+      const members = item.members.map((m) => this.sequence(m, depth + 1));
+      return this.container(members, "[", "]", depth);
+    }
+    if (kind === "node") return this.string(this.serializeNode(item));
+    if (kind === "function") {
+      throw new XPathError(
+        "SERE0021",
+        "A function item cannot be written as JSON",
+      );
+    }
+    return this.atomic(item);
+  }
+
+  /**
+   * @param {import("../../xdm/atomic.js").AtomicValue} item
+   * @returns {string}
+   */
+  atomic(item) {
+    const primitive = item.type.primitive.localName;
+    if (primitive === "boolean") return String(item.value);
+    const text = canonicalString(item);
+    if (primitive === "double" || primitive === "float") {
+      if (!Number.isFinite(item.value)) {
+        throw new XPathError("SERE0020", `${text} cannot be written as JSON`);
+      }
+      return text;
+    }
+    return primitive === "decimal" ? text : this.string(text);
+  }
+}

package/src/serialize/methods/text.js

@@ -0,0 +1,43 @@
+/**
+ * The text output method (Serialization 3.1 section 8): the string value
+ * of the normalized document, that is its text nodes in document order,
+ * without escaping. Character maps and Unicode normalization apply; a
+ * character the encoding cannot represent is a SERE0008 error.
+ *
+ * @module @tradik/xslt3/serialize/methods/text
+ */
+
+import { Expander } from "../output/expander.js";
+
+/**
+ * Writes the text of the normalized sequence.
+ * @param {Array<string|Node>} entries - From normalizeSequence
+ * @param {import("../params/settings.js").Settings} settings
+ * @param {import("../output/buffer.js").OutputBuffer} buffer
+ * @yields {string} chunks of output, when the buffer is full
+ * @returns {Generator<string, void, void>}
+ */
+export function* writeText(entries, settings, buffer) {
+  const expander = new Expander(settings);
+  for (const entry of entries) {
+    if (typeof entry === "string") {
+      buffer.write(expander.raw(entry));
+    } else if (entry.nodeType === 1) {
+      // descendant text nodes in document order, without recursion
+      const stack = [entry.firstChild];
+      while (stack.length) {
+        const node = stack.pop();
+        if (!node) continue;
+        stack.push(node.nextSibling);
+        const type = node.nodeType;
+        if (type === 3 || type === 4) {
+          buffer.write(expander.raw(node.nodeValue));
+        } else if (type === 1) {
+          stack.push(node.firstChild);
+        }
+        if (buffer.full) yield buffer.take();
+      }
+    }
+    if (buffer.full) yield buffer.take();
+  }
+}

package/src/serialize/output/buffer.js

@@ -0,0 +1,48 @@
+/**
+ * The output buffer of the serializers: markup is appended piece by piece
+ * and handed out in chunks of about `chunkSize` UTF-16 code units, so a
+ * large result can be streamed without ever being held as one string.
+ *
+ * @module @tradik/xslt3/serialize/output/buffer
+ */
+
+/** Default chunk size of serializeChunks, in UTF-16 code units. */
+export const DEFAULT_CHUNK_SIZE = 16384;
+
+/** Collects output and releases it in chunks. */
+export class OutputBuffer {
+  /**
+   * @param {number} [chunkSize] - Chunk size; Infinity keeps everything
+   *   until the end
+   */
+  constructor(chunkSize = DEFAULT_CHUNK_SIZE) {
+    this.chunkSize = chunkSize;
+    /** @type {string[]} */
+    this.parts = [];
+    this.length = 0;
+  }
+
+  /** @param {string} text - Markup to append */
+  write(text) {
+    if (text) {
+      this.parts.push(text);
+      this.length += text.length;
+    }
+  }
+
+  /** @returns {boolean} whether a chunk is ready */
+  get full() {
+    return this.length >= this.chunkSize;
+  }
+
+  /**
+   * Takes the buffered output.
+   * @returns {string} everything written since the last take ("" if none)
+   */
+  take() {
+    const chunk = this.parts.join("");
+    this.parts = [];
+    this.length = 0;
+    return chunk;
+  }
+}