jtlt 0.2.0 → 0.3.0

package/src/StringJoiningTransformer.js

@@ -2,11 +2,32 @@ import {jml} from 'jamilih';
 import * as JHTML from 'jhtml';
 import AbstractJoiningTransformer from './AbstractJoiningTransformer.js';
 
+/**
+ * @typedef {{
+ *   encoding?: string,
+ *   indent?: boolean,
+ *   omitXmlDeclaration?: boolean,
+ *   doctypePublic?: string,
+ *   doctypeSystem?: string,
+ *   cdataSectionElements?: string[]
+ *   mediaType?: string,
+ *   version?: string,
+ *   standalone?: boolean,
+ *   method?: "xml"|"html"|"text"|"json"|"xhtml"
+ * }} OutputConfig
+ */
+
+/**
+ * @callback SimpleCallback
+ * @this {StringJoiningTransformer}
+ * @returns {void}
+ */
+
 const camelCase = /[a-z][A-Z]/gv;
 
 /**
  * Type guard to detect DOM Elements.
- * @param {*} item
+ * @param {any} item
  * @returns {item is Element}
  */
 function _isElement (item) {
@@ -21,6 +42,15 @@ function _makeDatasetAttribute (n0) {
   return n0.charAt(0) + '-' + n0.charAt(1).toLowerCase();
 }
 
+/**
+ * Attributes object for element() allowing standard string attributes
+ * plus special helpers: dataset (object) and $a (ordered attribute array).
+ * @typedef {Record<string, unknown> & {
+ *   dataset?: Record<string, string>,
+ *   $a?: Array<[string, string]>
+ * }} ElementAttributes
+ */
+
 /**
  *
  */
@@ -50,11 +80,13 @@ function _makeDatasetAttribute (n0) {
  *   name mapping rules differ, etc.).
  * - cfg.preEscapedAttributes: skip escaping attribute values.
  * - cfg.JHTMLForJSON / cfg.mode: affect how object()/array() serialize.
+ * @extends {AbstractJoiningTransformer<"string">}
  */
 class StringJoiningTransformer extends AbstractJoiningTransformer {
   /**
    * @param {string} s - Initial string
-   * @param {object} cfg - Configuration object
+   * @param {import('./AbstractJoiningTransformer.js').
+   *   StringJoiningTransformerConfig} [cfg] - Configuration object
    */
   constructor (s, cfg) {
     super(cfg); // Include this in any subclass of AbstractJoiningTransformer
@@ -74,12 +106,18 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     this._arr = [];
     /** @type {string | undefined} */
     this._strTemp = undefined;
-    /** @type {Record<string, any>} */
+    /** @type {Record<string, unknown>} */
     this.propertySets = {};
+    /** @type {string[]} */
+    this._docs = [];
+    /** @type {boolean} */
+    this._insideDocument = false;
+    /** @type {Array<{href: string, document: string, format?: string}>} */
+    this._resultDocuments = [];
   }
 
   /**
-   * @param {string|*} s - String or value to append
+   * @param {string|any} s - String or value to append
    * @returns {StringJoiningTransformer}
    */
   append (s) {
@@ -104,15 +142,24 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @returns {string}
+   * @returns {string|string[]}
    */
   get () {
+    if (this._cfg.exposeDocuments) {
+      // If we built a document outside of document() calls and haven't
+      // pushed it yet, push the current string
+      if (this.root && !this._insideDocument && this._str &&
+          !this._docs.includes(this._str)) {
+        this._docs.push(this._str);
+      }
+      return this._docs;
+    }
     return this._str;
   }
 
   /**
    * @param {string} prop - Property name
-   * @param {*} val - Property value
+   * @param {any} val - Property value
    * @returns {StringJoiningTransformer}
    */
   propValue (prop, val) {
@@ -127,7 +174,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
 
   /**
    * @param {string} prop - Property name
-   * @param {Function} cb - Callback function
+   * @param {(this: StringJoiningTransformer) => void} cb - Callback function
    * @returns {StringJoiningTransformer}
    */
   propOnly (prop, cb) {
@@ -154,10 +201,10 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {object|Element} obj - Object to serialize
-   * @param {Function} cb - Callback function
+   * @param {Record<string, unknown>|Element} obj - Object to serialize
+   * @param {(this: StringJoiningTransformer) => void} cb - Callback function
    * @param {any[]} [usePropertySets] - Property sets to use
-   * @param {object} [propSets] - Additional property sets
+   * @param {Record<string, unknown>} [propSets] - Additional property sets
    * @returns {StringJoiningTransformer}
    */
   object (obj, cb, usePropertySets, propSets) {
@@ -173,7 +220,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     /** @type {any} */
     const oldObj = this._obj;
     this._obj = _isElement(obj)
-      ? JHTML.toJSONObject(obj, {mode: this._cfg?.mode})
+      ? JHTML.toJSONObject(obj, {mode: this._cfg.mode})
       : obj || {};
 
     // Todo: Allow in this and subsequent JSON methods ability to create
@@ -197,9 +244,9 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     // Not ready to serialize yet as still inside another array or object
     if (oldObjPropState || this._arrItemState) {
       this.append(this._obj);
-    } else if (this._cfg && this._cfg.JHTMLForJSON) {
+    } else if (this._cfg.JHTMLForJSON) {
       this.append(JHTML.toJHTMLString(this._obj));
-    } else if (this._cfg && this._cfg.mode !== 'JavaScript') {
+    } else if (this._cfg.mode !== 'JavaScript') {
       // Allow this method to operate on non-finite numbers and functions
       const stringifier = new JHTML.Stringifier({mode: 'JavaScript'});
       this.append(stringifier.walkJSONObject(this._obj));
@@ -212,7 +259,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
 
   /**
    * @param {any[]|Element} [arr] - Array to serialize
-   * @param {Function} [cb] - Callback function
+   * @param {(this: StringJoiningTransformer) => void} [cb] - Callback function
    * @returns {StringJoiningTransformer}
    */
   array (arr, cb) {
@@ -223,7 +270,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     const oldArr = this._arr;
     // Todo: copy array?
     this._arr = _isElement(arr)
-      ? /** @type {any[]} */ (JHTML.toJSONObject(arr, {mode: this._cfg?.mode}))
+      ? /** @type {any[]} */ (JHTML.toJSONObject(arr, {mode: this._cfg.mode}))
       : arr || [];
 
     /** @type {any} */
@@ -245,9 +292,9 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
       this.append(this._arr);
     /* c8 ignore next 2 -- JHTMLForJSON is a specialized output mode rarely used
      * in combination with nested array building at the root level. */
-    } else if (this._cfg && this._cfg.JHTMLForJSON) {
+    } else if (this._cfg.JHTMLForJSON) {
       this.append(JHTML.toJHTMLString(this._arr));
-    } else if (this._cfg && this._cfg.mode !== 'JavaScript') {
+    } else if (this._cfg.mode !== 'JavaScript') {
       // Allow this method to operate on non-finite numbers and functions
       const stringifier = new JHTML.Stringifier({mode: 'JavaScript'});
       this.append(stringifier.walkJSONObject(this._arr));
@@ -259,8 +306,9 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {string|Element|object} str - String value or element
-   * @param {Function} [cb] - Callback function
+   * @param {string|Element|Record<string, unknown>} str
+   *   String value or element
+   * @param {(this: StringJoiningTransformer) => void} [cb] - Callback function
    * @returns {StringJoiningTransformer}
    */
   string (str, cb) {
@@ -269,7 +317,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     // If a callback is provided, it composes a nested string value first.
     if (_isElement(str)) {
       str = /** @type {any} */ (
-        JHTML.toJSONObject(str, {mode: this._cfg?.mode})
+        JHTML.toJSONObject(str, {mode: this._cfg.mode})
       );
     }
 
@@ -292,14 +340,15 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {number|Element|object} num - Number value or element
+   * @param {number|Element|Record<string, unknown>} num
+   *   Number value or element
    * @returns {StringJoiningTransformer}
    */
   number (num) {
     // Appends the number as a string; no localization/formatting is applied.
     if (_isElement(num)) {
       num = /** @type {any} */ (
-        JHTML.toJSONObject(num, {mode: this._cfg?.mode})
+        JHTML.toJSONObject(num, {mode: this._cfg.mode})
       );
     }
     this.append(num.toString());
@@ -307,14 +356,15 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {boolean|Element|object} bool - Boolean value or element
+   * @param {boolean|Element|Record<string, unknown>} bool
+   *   Boolean value or element
    * @returns {StringJoiningTransformer}
    */
   boolean (bool) {
     // Appends 'true' or 'false'.
     if (_isElement(bool)) {
       bool = /** @type {any} */ (
-        JHTML.toJSONObject(bool, {mode: this._cfg?.mode})
+        JHTML.toJSONObject(bool, {mode: this._cfg.mode})
       );
     }
     this.append(bool ? 'true' : 'false');
@@ -335,7 +385,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
    */
   undefined () {
     // Appends the literal 'undefined' (only in JavaScript mode).
-    if (this._cfg && this._cfg.mode !== 'JavaScript') {
+    if (this._cfg.mode !== 'JavaScript') {
       throw new Error(
         'undefined is not allowed unless added in JavaScript mode'
       );
@@ -350,14 +400,14 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
    */
   nonfiniteNumber (num) {
     // Appends NaN/Infinity/-Infinity as-is (only in JavaScript mode).
-    if (this._cfg && this._cfg.mode !== 'JavaScript') {
+    if (this._cfg.mode !== 'JavaScript') {
       throw new Error(
         'Non-finite numbers are not allowed unless added in JavaScript mode'
       );
     }
     if (_isElement(num)) {
       num = /** @type {any} */ (
-        JHTML.toJSONObject(num, {mode: this._cfg?.mode})
+        JHTML.toJSONObject(num, {mode: this._cfg.mode})
       );
     }
     this.append(num.toString());
@@ -365,19 +415,19 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {Function|Element} func - Function to stringify
+   * @param {((...args: any[]) => any)|Element} func - Function to stringify
    * @returns {StringJoiningTransformer}
    */
   function (func) {
     // Appends function source (only in JavaScript mode).
-    if (this._cfg && this._cfg.mode !== 'JavaScript') {
+    if (this._cfg.mode !== 'JavaScript') {
       throw new Error(
         'function is not allowed unless added in JavaScript mode'
       );
     }
     if (_isElement(func)) {
       func = /** @type {any} */ (
-        JHTML.toJSONObject(func, {mode: this._cfg?.mode})
+        JHTML.toJSONObject(func, {mode: this._cfg.mode})
       );
     }
     this.append(func.toString());
@@ -385,13 +435,75 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {string|object} elName - Element name or element object
-   * @param {object} [atts] - Element attributes
+   * @param {OutputConfig} cfg
+   * @returns {StringJoiningTransformer}
+   */
+  output (cfg) {
+    // We wait until first element is set in `element()` to add
+    //   XML declaration and DOCTYPE as latter depends on root element
+    this._outputConfig = cfg;
+
+    // Use for file extension if making downloadable?
+    this.mediaType = cfg.mediaType;
+    return this;
+  }
+
+  /**
+   * @param {string|Element} elName - Element name or element object
+   * @param {ElementAttributes} [atts] - Element attributes
    * @param {any[]} [childNodes] - Child nodes
-   * @param {Function} [cb] - Callback function
+   * @param {(this: StringJoiningTransformer) => void} [cb] - Callback function
    * @returns {StringJoiningTransformer}
    */
   element (elName, atts, childNodes, cb) {
+    // If a parent element's start tag is still open, close it before
+    // starting a new element to ensure valid nesting.
+    if (this._openTagState) {
+      this.append('>');
+      this._openTagState = false;
+    }
+
+    if (!this.root) {
+      this.root = elName;
+
+      // todo: indent, cdataSectionElements
+      const {
+        omitXmlDeclaration, doctypePublic, doctypeSystem, method
+      } = this._outputConfig ?? {};
+
+      let xmlDeclaration = '';
+      /* c8 ignore start -- third OR condition short-circuits */
+      if (!omitXmlDeclaration && (
+        method === 'xml' || method === 'xhtml' || omitXmlDeclaration === false)
+      ) {
+        const {version, encoding, standalone} = this._outputConfig ?? {};
+        xmlDeclaration = `<?xml${
+          version ? ` version="${version}"` : ''
+        }${
+          encoding ? ` encoding="${encoding}"` : ''
+        }${
+          standalone ? ` standalone="yes"` : ''
+        }?>\n`;
+      }
+      /* c8 ignore stop */
+
+      let doctype = '';
+      if (doctypePublic !== undefined || doctypeSystem !== undefined) {
+        /* c8 ignore start -- nested ternary attribution issue */
+        doctype = `<!DOCTYPE ${elName}${
+          doctypePublic
+            ? ` PUBLIC "${doctypePublic}" "${doctypeSystem}"`
+            : doctypeSystem
+              ? ` SYSTEM "${doctypeSystem}"`
+              : ''
+        }>\n`;
+        /* c8 ignore stop */
+      }
+
+      this._str = xmlDeclaration + doctype + this._str;
+      // Document pushing is handled by document() method or get()
+    }
+
     // Emits an HTML/XML element using Jamilih under the hood, or allows a
     // callback to build attributes/children incrementally. Attribute values
     // are escaped unless cfg.preEscapedAttributes is true. When a callback is
@@ -399,23 +511,26 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
     const that = this;
     if (Array.isArray(atts)) {
-      cb = /** @type {Function} */ (/** @type {unknown} */ (childNodes));
+      cb = /** @type {(this: StringJoiningTransformer) => void} */ (
+        /** @type {unknown} */ (childNodes)
+      );
       childNodes = atts;
       atts = {};
     } else if (typeof atts === 'function') {
-      cb = atts;
+      cb = /** @type {(this: StringJoiningTransformer) => void} */ (atts);
       childNodes = [];
       atts = {};
     }
     if (typeof childNodes === 'function') {
-      cb = childNodes;
+      cb = /** @type {(this: StringJoiningTransformer) => void} */ (childNodes);
       childNodes = [];
     }
 
     // Todo: allow for cfg to produce Jamilih string output or hXML
     //   string output
-    const method = this._cfg && this._cfg.xmlElements ? 'toXML' : 'toHTML';
+    const method = this._cfg.xmlElements ? 'toXML' : 'toHTML';
     if (!cb) {
+      // Ensure any open parent start tag was closed (handled above)
       // Note that Jamilih currently has an issue with 'selected', 'checked',
       //  'value', 'defaultValue', 'for', 'on*', 'style' (workaround: pass
       //   an empty callback as the last argument to element())
@@ -428,7 +543,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     }
 
     if (typeof elName === 'object') {
-      /** @type {Record<string, any>} */
+      /** @type {Record<string, string>} */
       const objAtts = {};
       /** @type {any} */
       const elObj = elName;
@@ -444,9 +559,13 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     const oldTagState = this._openTagState;
     this._openTagState = true;
     if (atts) {
-      const attsObj = /** @type {Record<string, any>} */ (atts);
+      const attsObj = /** @type {Record<string, unknown>} */ (atts);
       Object.keys(attsObj).forEach((att) => {
-        that.attribute(att, attsObj[att], false);
+        that.attribute(
+          att,
+          /** @type {string|Record<string, unknown>} */ (attsObj[att]),
+          false
+        );
       });
     }
     if (childNodes && childNodes.length) {
@@ -468,7 +587,8 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
 
   /**
    * @param {string} name - Attribute name
-   * @param {string|object} val - Attribute value
+   * @param {string|Record<string, unknown>|
+   *   string[][]} val - Attribute value
    * @param {boolean} [avoidAttEscape] - Whether to avoid escaping the
    *   attribute value
    * @returns {StringJoiningTransformer}
@@ -486,9 +606,9 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
       );
     }
 
-    if (!this._cfg || !this._cfg.xmlElements) {
+    if (!this._cfg.xmlElements) {
       if (typeof val === 'object') {
-        /** @type {Record<string, any>} */
+        /** @type {Record<string, unknown>} */
         const valObj = /** @type {any} */ (val);
         switch (name) {
         case 'dataset': {
@@ -496,16 +616,22 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
             that.attribute(
               'data-' + att.replaceAll(
                 camelCase, _makeDatasetAttribute
-              ), valObj[att], false
+              ),
+              /** @type {string|Record<string, unknown>} */ (valObj[att]),
+              false
             );
           });
           break;
         }
         case '$a': { // Ordered attributes
-          /** @type {any[]} */
+          /** @type {unknown[][]} */
           const valArr = /** @type {any} */ (val);
           valArr.forEach(function (attArr) {
-            that.attribute(attArr[0], attArr[1], false);
+            that.attribute(
+              String(attArr[0]),
+              /** @type {string|Record<string, unknown>} */ (attArr[1]),
+              false
+            );
           });
           break;
         }
@@ -519,7 +645,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
 
     /** @type {string} */
     const valStr = /** @type {any} */ (val);
-    val = ((this._cfg && this._cfg.preEscapedAttributes) || avoidAttEscape)
+    val = (this._cfg.preEscapedAttributes || avoidAttEscape)
       ? valStr
       : valStr.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
     this.append(' ' + name + '="' + val + '"');
@@ -542,12 +668,31 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-  * Unlike text(), does not escape for HTML; unlike string(), does not perform
-  *   JSON stringification; unlike append(), does not do other checks (but still
-  *   varies in its role across transformers).
-  * @param {string} str
-  * @returns {StringJoiningTransformer}
-  */
+   * @param {string} text
+   * @returns {StringJoiningTransformer}}
+   */
+  comment (text) {
+    this.append(`<!--${text}-->`);
+    return this;
+  }
+
+  /**
+   * @param {string} target
+   * @param {string} data
+   * @returns {StringJoiningTransformer}}
+   */
+  processingInstruction (target, data) {
+    this.append(`<?${target} ${data}?>`);
+    return this;
+  }
+
+  /**
+   * Unlike text(), does not escape for HTML; unlike string(), does not perform
+   *   JSON stringification; unlike append(), does not do other checks (but
+   *   still varies in its role across transformers).
+   * @param {string} str
+   * @returns {StringJoiningTransformer}
+   */
   rawAppend (str) {
     // Lowest-level append: bypasses append() semantics and state checks.
     this._str += str;
@@ -566,11 +711,122 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     return this;
   }
 
+  /**
+   * Creates a new string document and executes a callback in its context.
+   * Similar to XSLT's xsl:document, this allows templates to generate
+   * multiple output documents. The created document is pushed to this._docs
+   * and will be included in the result when exposeDocuments is true.
+   *
+   * @param {(this: StringJoiningTransformer) => void} cb
+   *   Callback that builds the document content
+   * @param {OutputConfig} [cfg]
+   *   Output configuration for the document (encoding, doctype, etc.)
+   * @returns {StringJoiningTransformer}
+   */
+  document (cb, cfg) {
+    // If there's a current document being built (this.root is set and _str
+    // has content), save it to _docs before starting a new document
+    if (this._cfg.exposeDocuments && this.root && this._str &&
+        !this._docs.includes(this._str)) {
+      this._docs.push(this._str);
+    }
+
+    // Save current state
+    /** @type {any} */
+    const oldRoot = this.root;
+    /** @type {any} */
+    const oldOutputConfig = this._outputConfig;
+    const oldStr = this._str;
+    /** @type {any} */
+    const oldOpenTagState = this._openTagState;
+
+    // Reset state for new document
+    this.root = undefined;
+    /** @type {any} */
+    this._outputConfig = cfg;
+    this._str = '';
+    this._openTagState = false;
+    this._insideDocument = true;
+
+    // Execute callback to build document content
+    cb.call(this);
+
+    // Save the newly created document string
+    const newDoc = this._str;
+    this._docs.push(newDoc);
+
+    // Restore previous state
+    this.root = oldRoot;
+    this._outputConfig = oldOutputConfig;
+    this._str = oldStr;
+    this._openTagState = oldOpenTagState;
+    this._insideDocument = false;
+
+    return this;
+  }
+
+  /**
+   * Creates a new result document with metadata (href, format).
+   * Similar to XSLT's xsl:result-document, this allows templates to generate
+   * multiple output documents with associated metadata like URIs. The created
+   * document is stored in this._resultDocuments with the provided href.
+   *
+   * @param {string} href - URI/path for the result document
+   * @param {(this: StringJoiningTransformer) => void} cb
+   *   Callback that builds the document content
+   * @param {OutputConfig} [cfg]
+   *   Output configuration for the document (encoding, doctype, format, etc.)
+   * @returns {StringJoiningTransformer}
+   */
+  resultDocument (href, cb, cfg) {
+    // If there's a current document being built, save it first
+    if (this.root && this._str && !this._docs.includes(this._str)) {
+      this._docs.push(this._str);
+    }
+
+    // Save current state
+    /** @type {any} */
+    const oldRoot = this.root;
+    /** @type {any} */
+    const oldOutputConfig = this._outputConfig;
+    const oldStr = this._str;
+    /** @type {any} */
+    const oldOpenTagState = this._openTagState;
+
+    // Reset state for new document
+    this.root = undefined;
+    /** @type {any} */
+    this._outputConfig = cfg;
+    this._str = '';
+    this._openTagState = false;
+    this._insideDocument = true;
+
+    // Execute callback to build document content
+    cb.call(this);
+
+    // Save the newly created document string with metadata
+    const resultDoc = this._str;
+    this._resultDocuments.push({
+      href,
+      document: resultDoc,
+      format: this._outputConfig?.method || cfg?.method
+    });
+
+    // Restore previous state
+    this.root = oldRoot;
+    this._outputConfig = oldOutputConfig;
+    this._str = oldStr;
+    this._openTagState = oldOpenTagState;
+    this._insideDocument = false;
+
+    return this;
+  }
+
   /**
    * Helper method to use property sets.
-   * @param {object} obj - Object to apply property set to
+   * @param {Record<string, unknown>} obj - Object to apply property set to
    * @param {string} psName - Property set name
-   * @returns {object}
+   * @returns {Record<string, unknown>}
    */
   _usePropertySets (obj, psName) {
     // Merge named property set from this.propertySets into obj
@@ -584,6 +840,4 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
   }
 }
 
-// Todo: Implement comment(), processingInstruction(), etc.
-
 export default StringJoiningTransformer;