@stxt-lang/core 0.5.2 → 0.5.3

package/out/schema/type/HEXADECIMAL.js

@@ -3,11 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HEXADECIMAL = void 0;
 const ValidationException_1 = require("../../exceptions/ValidationException");
 const binaryValue_1 = require("./binaryValue");
+/** `HEXADECIMAL` type: checks a hexadecimal string (`[0-9A-Fa-f]+`), with no prefix and no mandatory even length. */
 exports.HEXADECIMAL = {
     getName() {
         return "HEXADECIMAL";
     },
-    // STXT-SCHEMA-SPEC 9.5: cadena [0-9A-Fa-f]+ (sin prefijo '#' ni longitud par)
+    // STXT-SCHEMA-SPEC 9.5: [0-9A-Fa-f]+ string, with no '#' prefix and no even-length requirement
     validate(ndef, n) {
         const value = (0, binaryValue_1.binaryValue)(n);
         if (!/^[0-9A-Fa-f]+$/.test(value)) {

package/out/schema/type/INLINE.d.ts

@@ -1,2 +1,3 @@
 import { Type } from "../Type";
+/** `INLINE` type: node with an inline value (after `:`), accepting children. */
 export declare const INLINE: Type;

package/out/schema/type/INLINE.js

@@ -2,12 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INLINE = void 0;
 const ValidationException_1 = require("../../exceptions/ValidationException");
+/** `INLINE` type: node with an inline value (after `:`), accepting children. */
 exports.INLINE = {
     getName() {
         return "INLINE";
     },
     validate(nodeDef, node) {
-        // Forma del valor INLINE (STXT-SCHEMA-SPEC 9.2): no admite bloque '>>'
+        // INLINE value form (STXT-SCHEMA-SPEC 9.2): the block '>>' form is not allowed
         if (node.isTextNode()) {
             throw new ValidationException_1.ValidationException(node.getLine(), "NOT_ALLOWED_TEXT", `Not allowed text in node ${node.getQualifiedName()}`);
         }

package/out/schema/type/INTEGER.d.ts

@@ -1 +1,2 @@
+/** `INTEGER` type: checks an integer with an optional sign. */
 export declare const INTEGER: import("../Type").Type;

package/out/schema/type/INTEGER.js

@@ -2,5 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INTEGER = void 0;
 const regexType_1 = require("./regexType");
+/** `INTEGER` type: checks an integer with an optional sign. */
 exports.INTEGER = (0, regexType_1.regexType)("INTEGER", /^[-+]?\d+$/, "Invalid integer");
 //# sourceMappingURL=INTEGER.js.map

package/out/schema/type/MARKDOWN.d.ts

@@ -1,2 +1,6 @@
 import { Type } from "../Type";
+/**
+ * `MARKDOWN` type. STXT-SCHEMA-SPEC 9.7: for validation purposes it is equivalent to TEXT
+ * (any content is valid Markdown); only children are forbidden.
+ */
 export declare const MARKDOWN: Type;

package/out/schema/type/MARKDOWN.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MARKDOWN = void 0;
 const ValidationException_1 = require("../../exceptions/ValidationException");
-// STXT-SCHEMA-SPEC 9.7: a efectos de validación equivale a TEXT
-// (cualquier contenido es válido; solo se prohíben hijos)
+/**
+ * `MARKDOWN` type. STXT-SCHEMA-SPEC 9.7: for validation purposes it is equivalent to TEXT
+ * (any content is valid Markdown); only children are forbidden.
+ */
 exports.MARKDOWN = {
     getName() {
         return "MARKDOWN";

package/out/schema/type/NATURAL.d.ts

@@ -1 +1,2 @@
+/** `NATURAL` type: checks an unsigned integer. */
 export declare const NATURAL: import("../Type").Type;

package/out/schema/type/NATURAL.js

@@ -2,5 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NATURAL = void 0;
 const regexType_1 = require("./regexType");
+/** `NATURAL` type: checks an unsigned integer. */
 exports.NATURAL = (0, regexType_1.regexType)("NATURAL", /^\d+$/, "Invalid natural");
 //# sourceMappingURL=NATURAL.js.map

package/out/schema/type/NUMBER.d.ts

@@ -1 +1,2 @@
+/** `NUMBER` type: checks a decimal number, with optional sign and exponent notation. */
 export declare const NUMBER: import("../Type").Type;

package/out/schema/type/NUMBER.js

@@ -2,5 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NUMBER = void 0;
 const regexType_1 = require("./regexType");
+/** `NUMBER` type: checks a decimal number, with optional sign and exponent notation. */
 exports.NUMBER = (0, regexType_1.regexType)("NUMBER", /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/, "Invalid number");
 //# sourceMappingURL=NUMBER.js.map

package/out/schema/type/TEXT.d.ts

@@ -1,2 +1,3 @@
 import { Type } from "../Type";
+/** `TEXT` type: free text node, with no children allowed. */
 export declare const TEXT: Type;

package/out/schema/type/TEXT.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TEXT = void 0;
 const ValidationException_1 = require("../../exceptions/ValidationException");
+/** `TEXT` type: free text node, with no children allowed. */
 exports.TEXT = {
     getName() {
         return "TEXT";

package/out/schema/type/TIME.d.ts

@@ -1 +1,2 @@
+/** `TIME` type: checks the `HH:MM:SS` format. */
 export declare const TIME: import("../Type").Type;

package/out/schema/type/TIME.js

@@ -2,5 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TIME = void 0;
 const regexType_1 = require("./regexType");
+/** `TIME` type: checks the `HH:MM:SS` format. */
 exports.TIME = (0, regexType_1.regexType)("TIME", /^\d{2}:\d{2}:\d{2}$/, "Invalid time");
 //# sourceMappingURL=TIME.js.map

package/out/schema/type/TIMESTAMP.d.ts

@@ -1 +1,2 @@
+/** `TIMESTAMP` type: checks an ISO-8601 timestamp. */
 export declare const TIMESTAMP: import("../Type").Type;

package/out/schema/type/TIMESTAMP.js

@@ -2,5 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TIMESTAMP = void 0;
 const regexType_1 = require("./regexType");
+/** `TIMESTAMP` type: checks an ISO-8601 timestamp. */
 exports.TIMESTAMP = (0, regexType_1.regexType)("TIMESTAMP", /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{3})?)?(Z|[+-]\d{2}:\d{2})?$/, "Invalid timestamp");
 //# sourceMappingURL=TIMESTAMP.js.map

package/out/schema/type/URL.d.ts

@@ -1,2 +1,3 @@
 import { Type } from "../Type";
+/** `URL` type: checks that the value is a syntactically valid URI/URL. */
 export declare const URL: Type;

package/out/schema/type/URL.js

@@ -2,12 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.URL = void 0;
 const ValidationException_1 = require("../../exceptions/ValidationException");
+/** `URL` type: checks that the value is a syntactically valid URI/URL. */
 exports.URL = {
     getName() {
         return "URL";
     },
     validate(ndef, n) {
-        // Forma del valor INLINE (STXT-SCHEMA-SPEC 9.4): no admite bloque '>>'
+        // INLINE value form (STXT-SCHEMA-SPEC 9.4): the block '>>' form is not allowed
         if (n.isTextNode()) {
             throw new ValidationException_1.ValidationException(n.getLine(), "NOT_ALLOWED_TEXT", `Not allowed text in node ${n.getQualifiedName()}`);
         }

package/out/schema/type/UUID.d.ts

@@ -1 +1,2 @@
+/** `UUID` type: checks the standard UUID format (`8-4-4-4-12` hexadecimal). */
 export declare const UUID: import("../Type").Type;

package/out/schema/type/UUID.js

@@ -2,5 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UUID = void 0;
 const regexType_1 = require("./regexType");
+/** `UUID` type: checks the standard UUID format (`8-4-4-4-12` hexadecimal). */
 exports.UUID = (0, regexType_1.regexType)("UUID", /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/, "Invalid UUID");
 //# sourceMappingURL=UUID.js.map

package/out/schema/type/binaryValue.d.ts

@@ -1,2 +1,11 @@
 import { Node } from "../../core/Node";
+/**
+ * STXT-SCHEMA-SPEC 9.5: effective value for the INLINE/BLOCK binary types
+ * (HEXADECIMAL, BINARY, BASE64). In BLOCK form, validation applies to the
+ * concatenation of the lines of the block, ignoring line breaks, empty lines
+ * and the leading and trailing spaces or tabs of each line.
+ *
+ * @param node node whose value is wanted.
+ * @returns the inline value, or the lines of the block already concatenated.
+ */
 export declare function binaryValue(node: Node): string;

package/out/schema/type/binaryValue.js

@@ -1,9 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.binaryValue = binaryValue;
-// STXT-SCHEMA-SPEC 9.5: en la forma BLOCK la validación se aplica sobre la
-// concatenación de las líneas del bloque, ignorando saltos de línea, líneas
-// vacías y espacios o tabuladores iniciales y finales de cada línea.
+/**
+ * STXT-SCHEMA-SPEC 9.5: effective value for the INLINE/BLOCK binary types
+ * (HEXADECIMAL, BINARY, BASE64). In BLOCK form, validation applies to the
+ * concatenation of the lines of the block, ignoring line breaks, empty lines
+ * and the leading and trailing spaces or tabs of each line.
+ *
+ * @param node node whose value is wanted.
+ * @returns the inline value, or the lines of the block already concatenated.
+ */
 function binaryValue(node) {
     if (!node.isTextNode()) {
         return node.getValue();

package/out/schema/type/regexType.d.ts

@@ -1,2 +1,10 @@
 import { Type } from "../Type";
+/**
+ * Base builder for the simple value types, those checked with a regular expression.
+ *
+ * @param name name of the type, as used in the schemas (e.g. `"DATE"`).
+ * @param pattern regular expression the value has to match.
+ * @param error message of the error thrown when the value does not match.
+ * @returns the {@link Type} that validates the value against that pattern.
+ */
 export declare function regexType(name: string, pattern: RegExp, error: string): Type;

package/out/schema/type/regexType.js

@@ -2,11 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.regexType = regexType;
 const ValidationException_1 = require("../../exceptions/ValidationException");
+/**
+ * Base builder for the simple value types, those checked with a regular expression.
+ *
+ * @param name name of the type, as used in the schemas (e.g. `"DATE"`).
+ * @param pattern regular expression the value has to match.
+ * @param error message of the error thrown when the value does not match.
+ * @returns the {@link Type} that validates the value against that pattern.
+ */
 function regexType(name, pattern, error) {
     return {
         getName: () => name,
         validate(nodeDef, node) {
-            // Forma del valor INLINE (STXT-SCHEMA-SPEC 9.3/9.4): no admite bloque '>>'
+            // INLINE value form (STXT-SCHEMA-SPEC 9.3/9.4): the block '>>' form is not allowed
             if (node.isTextNode()) {
                 throw new ValidationException_1.ValidationException(node.getLine(), "NOT_ALLOWED_TEXT", `Not allowed text in node ${node.getQualifiedName()}`);
             }

package/out/template/ChildLine.d.ts

@@ -1,12 +1,26 @@
+/** A child definition line inside an `@stxt.template`: type, cardinality and allowed values. */
 export declare class ChildLine {
     private readonly min;
     private readonly max;
     private readonly values;
     private readonly type;
+    /**
+     * Creates the already parsed content of a definition line.
+     *
+     * @param type declared type, or null if the line declares none.
+     * @param min minimum cardinality, or null if there is no minimum.
+     * @param max maximum cardinality, or null if there is no maximum.
+     * @param values values declared between brackets, or null if the line has no brackets at all.
+     */
     constructor(type: string | null, min: number | null, max: number | null, values: string[] | null);
+    /** @returns the declared type, or null if the line declares none. */
     getType(): string | null;
+    /** @returns the minimum cardinality, or null if there is no minimum. */
     getMin(): number | null;
+    /** @returns the maximum cardinality, or null if there is no maximum. */
     getMax(): number | null;
+    /** @returns the values declared between brackets, or null if the line has no brackets at all. */
     getValues(): string[] | null;
+    /** @returns a readable representation of the line, for debugging. */
     toString(): string;
 }

package/out/template/ChildLine.js

@@ -1,25 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChildLine = void 0;
+/** A child definition line inside an `@stxt.template`: type, cardinality and allowed values. */
 class ChildLine {
+    /**
+     * Creates the already parsed content of a definition line.
+     *
+     * @param type declared type, or null if the line declares none.
+     * @param min minimum cardinality, or null if there is no minimum.
+     * @param max maximum cardinality, or null if there is no maximum.
+     * @param values values declared between brackets, or null if the line has no brackets at all.
+     */
     constructor(type, min, max, values) {
         this.type = type;
         this.min = min;
         this.max = max;
         this.values = values;
     }
+    /** @returns the declared type, or null if the line declares none. */
     getType() {
         return this.type;
     }
+    /** @returns the minimum cardinality, or null if there is no minimum. */
     getMin() {
         return this.min;
     }
+    /** @returns the maximum cardinality, or null if there is no maximum. */
     getMax() {
         return this.max;
     }
+    /** @returns the values declared between brackets, or null if the line has no brackets at all. */
     getValues() {
         return this.values;
     }
+    /** @returns a readable representation of the line, for debugging. */
     toString() {
         return `ChildLine [type=${this.type}, min=${this.min}, max=${this.max}, values=${this.values ? `[${this.values.join(", ")}]` : "null"}]`;
     }

package/out/template/ChildLineParser.d.ts

@@ -1,7 +1,17 @@
 import { ChildLine } from "./ChildLine";
+/** Parses the inline value of a child node inside an `@stxt.template`, shaped as `(min,max) TYPE [values]`. */
 export declare class ChildLineParser {
     private constructor();
     private static readonly CHILD_LINE_PATTERN;
+    /**
+     * Parses a definition line into its type, its cardinality and its allowed values.
+     *
+     * @param rawLine inline value of the node, `(min,max) TYPE [values]`.
+     * @param lineNumber line number, for the error messages.
+     * @returns the line already split into type, cardinality and values.
+     * @throws ValidationException with code `INVALID_CHILD_LINE`, `INVALID_CHILD_COUNT`,
+     *         `MIN_GREATER_THAN_MAX` or `VALUE_DUPLICATED` if the line is not valid.
+     */
     static parse(rawLine: string, lineNumber: number): ChildLine;
     private static parseCount;
 }

package/out/template/ChildLineParser.js

@@ -3,8 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChildLineParser = void 0;
 const ValidationException_1 = require("../exceptions/ValidationException");
 const ChildLine_1 = require("./ChildLine");
+/** Parses the inline value of a child node inside an `@stxt.template`, shaped as `(min,max) TYPE [values]`. */
 class ChildLineParser {
     constructor() { }
+    /**
+     * Parses a definition line into its type, its cardinality and its allowed values.
+     *
+     * @param rawLine inline value of the node, `(min,max) TYPE [values]`.
+     * @param lineNumber line number, for the error messages.
+     * @returns the line already split into type, cardinality and values.
+     * @throws ValidationException with code `INVALID_CHILD_LINE`, `INVALID_CHILD_COUNT`,
+     *         `MIN_GREATER_THAN_MAX` or `VALUE_DUPLICATED` if the line is not valid.
+     */
     static parse(rawLine, lineNumber) {
         if (rawLine.trim().length === 0) {
             return new ChildLine_1.ChildLine(null, null, null, null);
@@ -48,7 +58,7 @@ class ChildLineParser {
             }
             const aNum = ChildLineParser.parseCount(parts[0].trim(), count, rawLine, lineNumber);
             const bNum = ChildLineParser.parseCount(parts[1].trim(), count, rawLine, lineNumber);
-            // Cardinalidad inválida si min > max (STXT-TEMPLATE-SPEC 7.1)
+            // Invalid cardinality when min > max (STXT-TEMPLATE-SPEC 7.1)
             if (aNum > bNum) {
                 throw new ValidationException_1.ValidationException(lineNumber, "MIN_GREATER_THAN_MAX", `Min ${aNum} greater than Max ${bNum} in line: ${rawLine}`);
             }
@@ -75,17 +85,16 @@ class ChildLineParser {
                 }
                 list.push(part);
             }
-            // Los corchetes presentes (aunque vengan vacíos, "[]") cuentan como una definición
-            // explícita de valores: se devuelve un array no-nulo (posiblemente vacío) para
-            // distinguirlo de la ausencia total de corchetes (valuesStr null/undefined, values
-            // permanece null). Así "[]" se trata como redefinición/definición real (ported
-            // from stxt-java).
+            // Brackets being there (even empty ones, "[]") count as an explicit definition of
+            // values: a non-null array is returned (possibly empty) to tell it apart from having
+            // no brackets at all (valuesStr null/undefined, values stays null). That way "[]" is
+            // treated as a real definition/redefinition (ported from stxt-java).
             values = list;
         }
-        // type es string|null en nuestra clase
+        // type is string|null in our class
         return new ChildLine_1.ChildLine(type ?? null, min, max, values);
     }
-    // num, min y max deben ser enteros no negativos, sin texto sobrante (STXT-TEMPLATE-SPEC 7.1)
+    // num, min and max must be non-negative integers, with no trailing text (STXT-TEMPLATE-SPEC 7.1)
     static parseCount(num, count, rawLine, lineNumber) {
         if (!/^\d+$/.test(num)) {
             throw new ValidationException_1.ValidationException(lineNumber, "INVALID_CHILD_COUNT", `Invalid count ${count} in line: ${rawLine}`);

package/out/template/MetaTemplateSchemaProvider.d.ts

@@ -1,8 +1,24 @@
 import { Schema } from "../schema/Schema";
 import { SchemaProvider } from "../schema/SchemaProvider";
+/**
+ * {@link SchemaProvider} that defines in code the meta-schema of the template language itself
+ * (`@stxt.template`), so that a loaded template can validate itself.
+ */
 export declare class MetaTemplateSchemaProvider implements SchemaProvider {
     private static readonly META_TEXT;
     private readonly meta;
+    /**
+     * Parses the meta-template and keeps the schema it produces ready to be served.
+     *
+     * @throws ValidationException with code `META_SCHEMA_INVALID` if the meta-template does not produce exactly one document.
+     */
     constructor();
+    /**
+     * Serves the meta-schema of the template language.
+     *
+     * @param namespace namespace whose schema is wanted; only `@stxt.template` is served.
+     * @returns the meta-schema of the template language.
+     * @throws RuntimeException with code `RESOURCE_NOT_FOUND` if any other namespace is asked for.
+     */
     getSchema(namespace: string): Schema;
 }

package/out/template/MetaTemplateSchemaProvider.js

@@ -5,7 +5,16 @@ const Parser_1 = require("../core/Parser");
 const ValidationException_1 = require("../exceptions/ValidationException");
 const RuntimeException_1 = require("../exceptions/RuntimeException");
 const TemplateParser_1 = require("./TemplateParser");
+/**
+ * {@link SchemaProvider} that defines in code the meta-schema of the template language itself
+ * (`@stxt.template`), so that a loaded template can validate itself.
+ */
 class MetaTemplateSchemaProvider {
+    /**
+     * Parses the meta-template and keeps the schema it produces ready to be served.
+     *
+     * @throws ValidationException with code `META_SCHEMA_INVALID` if the meta-template does not produce exactly one document.
+     */
     constructor() {
         const parser = new Parser_1.Parser();
         const nodes = parser.parse(MetaTemplateSchemaProvider.META_TEXT);
@@ -14,11 +23,18 @@ class MetaTemplateSchemaProvider {
         }
         this.meta = (0, TemplateParser_1.transformTemplateNodeToSchema)(nodes[0]);
     }
+    /**
+     * Serves the meta-schema of the template language.
+     *
+     * @param namespace namespace whose schema is wanted; only `@stxt.template` is served.
+     * @returns the meta-schema of the template language.
+     * @throws RuntimeException with code `RESOURCE_NOT_FOUND` if any other namespace is asked for.
+     */
     getSchema(namespace) {
         if (namespace !== "@stxt.template") {
             throw new RuntimeException_1.RuntimeException("RESOURCE_NOT_FOUND", `Not found '${namespace}' in namespace: @stxt.template`);
         }
-        // meta siempre existe si el constructor terminó, pero lo dejamos equivalente al Java
+        // meta always exists once the constructor finished, but this mirrors the Java version
         if (!this.meta) {
             throw new ValidationException_1.ValidationException(0, "META_SCHEMA_NOT_AVAILABLE", "Meta schema not available");
         }

package/out/template/TemplateParser.d.ts

@@ -1,3 +1,11 @@
 import { Node } from "../core/Node";
 import { Schema } from "../schema/Schema";
+/**
+ * Turns the tree of an already parsed `@stxt.template` document into an equivalent {@link Schema}.
+ *
+ * @param node root of the already parsed `@stxt.template` document.
+ * @returns the resulting {@link Schema}.
+ * @throws ValidationException if the template is not valid, with the line already shifted to the
+ *         one of the original document.
+ */
 export declare function transformTemplateNodeToSchema(node: Node): Schema;