@stxt-lang/core 0.5.1 → 0.5.3

package/out/core/StringUtils.js

@@ -1,10 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StringUtils = void 0;
+/** String normalization helpers used for names, namespaces and values. */
 class StringUtils {
     constructor() {
     }
-    // Usado para nodos name>>
+    // Used for name>> nodes
+    /**
+     * Removes the trailing whitespace of a string.
+     *
+     * @param s string to strip the trailing spaces from.
+     * @returns the string without trailing whitespace; null/undefined is treated as the empty string.
+     */
     static rightTrim(s) {
         const value = s ?? "";
         let i = value.length - 1;
@@ -13,21 +20,45 @@ class StringUtils {
         }
         return value.substring(0, i + 1);
     }
-    // Usado para nodos tipo Base64 y Hex
+    // Used for BASE64 and HEXADECIMAL nodes
+    /**
+     * Removes every whitespace character of a string.
+     *
+     * @param input string to remove the spaces from.
+     * @returns the string without any whitespace at all.
+     */
     static cleanSpaces(input) {
         return input.replace(/\s+/g, "");
     }
-    // Usado para normalizar namespace
+    // Used to normalize namespaces
+    /**
+     * Lower-cases a string.
+     *
+     * @param input string to lower-case.
+     * @returns the lower-cased string; null/undefined is treated as the empty string.
+     */
     static lowerCase(input) {
-        // Equivalente práctico a Locale.ROOT en JS: evitar dependencias de locale del usuario
+        // Practical equivalent of Locale.ROOT in JS: keep the user's locale out of it
         return (input ?? "").toLowerCase();
     }
-    // Usados para name de los nodos
+    // Used for the name of the nodes
+    /**
+     * Trims a string and collapses its inner whitespace.
+     *
+     * @param s string to compact.
+     * @returns the string with the outer spaces trimmed and the inner ones collapsed into a single one; null/undefined is treated as the empty string.
+     */
     static compactSpaces(s) {
         return (s ?? "").trim().replace(/\s+/g, " ");
     }
-    // Usados para name normalizado de nodos (STXT-SPEC 4.3): NFC + minúsculas,
-    // conservando diacríticos y alfabetos no latinos (modelo IDN)
+    // Used for the normalized name of the nodes (STXT-SPEC 4.3): NFC + lower case,
+    // keeping diacritics and non-Latin alphabets (IDN model)
+    /**
+     * Builds the canonical name of a node, as defined by STXT-SPEC 4.3.
+     *
+     * @param input string to normalize.
+     * @returns the canonical name of a node: NFC + lower case, with separators collapsed into '-'; null/undefined is treated as the empty string.
+     */
     static normalize(input) {
         let s = (input ?? "").trim();
         if (s.length === 0) {
@@ -35,9 +66,9 @@ class StringUtils {
         }
         s = s.normalize("NFC");
         s = s.toLowerCase();
-        // toda secuencia de separadores ('-', '_', espacios) => un solo '-'
+        // every run of separators ('-', '_', spaces) => a single '-'
         s = s.replace(/[-_\s]+/g, "-");
-        // trim de '-'
+        // trim the '-'
         s = s.replace(/^-+|-+$/g, "");
         return s;
     }

package/out/exceptions/ParseException.d.ts

@@ -1,6 +1,20 @@
+/**
+ * Syntax error detected while parsing (lexical/structural phase, not schema). Every exception
+ * carries an UPPERCASE code and the line of the document where it was detected.
+ */
 export declare class ParseException extends Error {
+    /** Line number of the document where the error was detected. */
     readonly line: number;
+    /** Error code in UPPERCASE (e.g. `INVALID_LINE`). */
     readonly code: string;
+    /**
+     * Creates a syntax error located at a line of the document.
+     *
+     * @param line line number where the error was detected.
+     * @param code error code in UPPERCASE.
+     * @param message descriptive message.
+     */
     constructor(line: number, code: string, message: string);
+    /** @returns a readable representation of the error, with its line and its code. */
     toString(): string;
 }

package/out/exceptions/ParseException.js

@@ -1,7 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ParseException = void 0;
+/**
+ * Syntax error detected while parsing (lexical/structural phase, not schema). Every exception
+ * carries an UPPERCASE code and the line of the document where it was detected.
+ */
 class ParseException extends Error {
+    /**
+     * Creates a syntax error located at a line of the document.
+     *
+     * @param line line number where the error was detected.
+     * @param code error code in UPPERCASE.
+     * @param message descriptive message.
+     */
     constructor(line, code, message) {
         super(message);
         this.name = "ParseException";
@@ -9,6 +20,7 @@ class ParseException extends Error {
         this.code = code;
         Object.setPrototypeOf(this, ParseException.prototype);
     }
+    /** @returns a readable representation of the error, with its line and its code. */
     toString() {
         return `${this.name} [line=${this.line}, code=${this.code}]: ${this.message}`;
     }

package/out/exceptions/RuntimeException.d.ts

@@ -1,6 +1,20 @@
+/**
+ * Error that is not tied to a line of the document: a wrong use of the API or an inconsistency
+ * found at runtime (e.g. an ambiguous child, a type registered twice). It carries an UPPERCASE
+ * code, like the rest of the STXT exceptions.
+ */
 export declare class RuntimeException extends Error {
+    /** Error code in UPPERCASE (e.g. `AMBIGUOUS_CHILD`). */
     readonly code: string;
+    /**
+     * Creates an error with an error code and a message.
+     *
+     * @param code error code in UPPERCASE.
+     * @param message descriptive message.
+     */
     constructor(code: string, message: string);
+    /** @returns the error code in UPPERCASE. */
     getCode(): string;
+    /** @returns a readable representation of the error, with its code. */
     toString(): string;
 }

package/out/exceptions/RuntimeException.js

@@ -1,16 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RuntimeException = void 0;
+/**
+ * Error that is not tied to a line of the document: a wrong use of the API or an inconsistency
+ * found at runtime (e.g. an ambiguous child, a type registered twice). It carries an UPPERCASE
+ * code, like the rest of the STXT exceptions.
+ */
 class RuntimeException extends Error {
+    /**
+     * Creates an error with an error code and a message.
+     *
+     * @param code error code in UPPERCASE.
+     * @param message descriptive message.
+     */
     constructor(code, message) {
         super(message);
         this.name = "RuntimeException";
         this.code = code;
         Object.setPrototypeOf(this, RuntimeException.prototype);
     }
+    /** @returns the error code in UPPERCASE. */
     getCode() {
         return this.code;
     }
+    /** @returns a readable representation of the error, with its code. */
     toString() {
         const message = this.message;
         return `${this.name}[${this.code}]${message ? `: ${message}` : ""}`;

package/out/exceptions/ValidationException.d.ts

@@ -1,4 +1,12 @@
 import { ParseException } from "./ParseException";
+/** Semantic validation error (schema, type or cardinality), detected when a node is closed. */
 export declare class ValidationException extends ParseException {
+    /**
+     * Creates a validation error located at a line of the document.
+     *
+     * @param line line number where the error was detected.
+     * @param code error code in UPPERCASE.
+     * @param message descriptive message.
+     */
     constructor(line: number, code: string, message: string);
 }

package/out/exceptions/ValidationException.js

@@ -2,7 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ValidationException = void 0;
 const ParseException_1 = require("./ParseException");
+/** Semantic validation error (schema, type or cardinality), detected when a node is closed. */
 class ValidationException extends ParseException_1.ParseException {
+    /**
+     * Creates a validation error located at a line of the document.
+     *
+     * @param line line number where the error was detected.
+     * @param code error code in UPPERCASE.
+     * @param message descriptive message.
+     */
     constructor(line, code, message) {
         super(line, code, message);
         this.name = "ValidationException";

package/out/processors/Observer.d.ts

@@ -1,8 +1,37 @@
 import { Line } from "../core/Line";
 import { Node } from "../core/Node";
+/**
+ * Process hook notified by the {@link Parser} while parsing: when each node is opened and closed,
+ * and for every comment and text line it reads. Register it with {@link Parser.registerObserver}.
+ */
 export interface Observer {
+    /**
+     * Called when a node is opened.
+     *
+     * @param node node just opened (its children and its text lines are not complete yet).
+     * @param line source line that opened the node, as it appears in the document.
+     */
     onCreate(node: Node, line: string): void;
+    /**
+     * Called when a node is closed.
+     *
+     * @param node node just closed, with all its children and its value already complete.
+     */
     onFinish(node: Node): void;
+    /**
+     * Called for every comment line, which produces no node.
+     *
+     * @param lineNumber line number of the comment.
+     * @param line source line of the comment, as it appears in the document.
+     */
     onComment(lineNumber: number, line: string): void;
+    /**
+     * Called for every text line appended to an open BLOCK node.
+     *
+     * @param node BLOCK node the line was appended to.
+     * @param lineNumber line number of the text line.
+     * @param lineString source line, as it appears in the document.
+     * @param line the same line already split into indentation and content.
+     */
     onTextLine(node: Node, lineNumber: number, lineString: string, line: Line): void;
 }

package/out/processors/Validator.d.ts

@@ -1,5 +1,14 @@
 import { Node } from "../core/Node";
 import { ValidationException } from "../exceptions/ValidationException";
+/** Process hook invoked by the {@link Parser} when each node is closed, to validate in streaming. */
 export interface Validator {
+    /**
+     * Validates a node and returns every error found (without throwing), letting the caller
+     * collect errors from several nodes instead of bailing out on the first one. An empty array
+     * means the node is valid.
+     *
+     * @param node already closed node to validate.
+     * @returns the validation errors found, or an empty array if the node is valid.
+     */
     validate(node: Node): ValidationException[];
 }

package/out/runtime/ConditionalValidator.d.ts

@@ -2,8 +2,23 @@ import { Node } from "../core/Node";
 import { Validator } from "../processors/Validator";
 import { SchemaValidator } from "../schema/SchemaValidator";
 import { ValidationException } from "../exceptions/ValidationException";
+/**
+ * Wrapper around a {@link SchemaValidator} that only validates namespaced nodes, so that a
+ * document mixing schema-bound and free nodes does not report the free ones as unknown.
+ */
 export declare class ConditionalValidator implements Validator {
     private readonly schemaValidator;
+    /**
+     * Creates a validator that delegates to a schema validator.
+     *
+     * @param schemaValidator validator the namespaced nodes are handed over to.
+     */
     constructor(schemaValidator: SchemaValidator);
+    /**
+     * Validates a node when it has a namespace, and lets it through otherwise.
+     *
+     * @param node already closed node to validate.
+     * @returns the validation errors found, or an empty array if the node is valid or has no namespace.
+     */
     validate(node: Node): ValidationException[];
 }

package/out/runtime/ConditionalValidator.js

@@ -1,13 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConditionalValidator = void 0;
-// Wrapper del validador que solo valida nodos con namespace
+/**
+ * Wrapper around a {@link SchemaValidator} that only validates namespaced nodes, so that a
+ * document mixing schema-bound and free nodes does not report the free ones as unknown.
+ */
 class ConditionalValidator {
+    /**
+     * Creates a validator that delegates to a schema validator.
+     *
+     * @param schemaValidator validator the namespaced nodes are handed over to.
+     */
     constructor(schemaValidator) {
         this.schemaValidator = schemaValidator;
     }
+    /**
+     * Validates a node when it has a namespace, and lets it through otherwise.
+     *
+     * @param node already closed node to validate.
+     * @returns the validation errors found, or an empty array if the node is valid or has no namespace.
+     */
     validate(node) {
-        // Solo validar si tiene namespace
+        // Only validate the node when it has a namespace
         if (node.getNamespace() !== "") {
             return this.schemaValidator.validate(node);
         }

package/out/runtime/NodeWriter.d.ts

@@ -1,11 +1,29 @@
 import { Node } from "../core/Node";
+/** Indentation style to use when writing. */
 export declare enum IndentStyle {
+    /** One tab character per level. */
     TABS = "TABS",
+    /** Four spaces per level. */
     SPACES_4 = "SPACES_4"
 }
+/** Serializes a {@link Node} (or a list of root nodes) back to STXT text. */
 export declare class NodeWriter {
     private constructor();
+    /**
+     * Serializes a node to STXT text.
+     *
+     * @param node node to serialize (along with its children).
+     * @param style indentation style to use; tabs by default.
+     * @returns the node serialized to STXT text.
+     */
     static toSTXT(node: Node, style?: IndentStyle): string;
+    /**
+     * Serializes a list of root nodes to STXT text, separated by a blank line.
+     *
+     * @param docs root nodes to serialize.
+     * @param style indentation style to use; tabs by default.
+     * @returns the documents serialized to STXT text.
+     */
     static toSTXTDocs(docs: ReadonlyArray<Node>, style?: IndentStyle): string;
     private static writeNode;
     private static indent;

package/out/runtime/NodeWriter.js

@@ -1,18 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeWriter = exports.IndentStyle = void 0;
+/** Indentation style to use when writing. */
 var IndentStyle;
 (function (IndentStyle) {
+    /** One tab character per level. */
     IndentStyle["TABS"] = "TABS";
+    /** Four spaces per level. */
     IndentStyle["SPACES_4"] = "SPACES_4";
 })(IndentStyle || (exports.IndentStyle = IndentStyle = {}));
+/** Serializes a {@link Node} (or a list of root nodes) back to STXT text. */
 class NodeWriter {
     constructor() { }
+    /**
+     * Serializes a node to STXT text.
+     *
+     * @param node node to serialize (along with its children).
+     * @param style indentation style to use; tabs by default.
+     * @returns the node serialized to STXT text.
+     */
     static toSTXT(node, style = IndentStyle.TABS) {
         const out = [];
         NodeWriter.writeNode(out, node, 0, style, "");
         return out.join("");
     }
+    /**
+     * Serializes a list of root nodes to STXT text, separated by a blank line.
+     *
+     * @param docs root nodes to serialize.
+     * @param style indentation style to use; tabs by default.
+     * @returns the documents serialized to STXT text.
+     */
     static toSTXTDocs(docs, style = IndentStyle.TABS) {
         const out = [];
         for (let i = 0; i < docs.length; i++) {

package/out/runtime/UnifiedSchemaProvider.d.ts

@@ -1,22 +1,40 @@
 import { Schema } from "../schema/Schema";
 import { SchemaProvider } from "../schema/SchemaProvider";
 /**
- * Provider unificado que maneja tanto schemas como templates.
- * Detecta automáticamente el tipo según el namespace del nodo raíz:
- * - @stxt.template => procesa como template
- * - @stxt.schema => procesa como schema
- * - otros => no hace nada
+ * Unified provider that handles both schemas and templates.
+ * It detects which one it is from the namespace of the root node:
+ * - @stxt.template => processed as a template
+ * - @stxt.schema => processed as a schema
+ * - anything else => ignored
  */
 export declare class UnifiedSchemaProvider implements SchemaProvider {
     private readonly schemas;
     private readonly schemaMeta;
     private readonly templateMeta;
+    /** Creates an empty provider, with the two meta-schemas already loaded. */
     constructor();
+    /**
+     * Resolves the schema that applies to a namespace, serving the meta-schemas of the two
+     * reserved namespaces itself.
+     *
+     * @param namespace namespace whose schema is wanted.
+     * @returns the schema of the namespace, or null/undefined if none has been registered for it.
+     */
     getSchema(namespace: string): Schema | undefined | null;
+    /**
+     * Parses a document and registers every schema or template it defines, each one under its own
+     * namespace. Documents of any other namespace are ignored.
+     *
+     * @param text text of the document to load.
+     * @throws ParseException if the document cannot be parsed, or the first ValidationException if
+     *         a schema or a template does not validate against its meta-schema.
+     */
     addFile(text: string): void;
     private addTemplateNode;
     private addSchemaNode;
     private static throwIfInvalid;
+    /** Removes every schema and template registered in this provider. */
     clear(): void;
+    /** @returns every schema registered in this provider, in registration order. */
     getAllSchemas(): ReadonlyArray<Schema>;
 }

package/out/runtime/UnifiedSchemaProvider.js

@@ -9,18 +9,26 @@ const SchemaValidator_1 = require("../schema/SchemaValidator");
 const MetaTemplateSchemaProvider_1 = require("../template/MetaTemplateSchemaProvider");
 const TemplateParser_1 = require("../template/TemplateParser");
 /**
- * Provider unificado que maneja tanto schemas como templates.
- * Detecta automáticamente el tipo según el namespace del nodo raíz:
- * - @stxt.template => procesa como template
- * - @stxt.schema => procesa como schema
- * - otros => no hace nada
+ * Unified provider that handles both schemas and templates.
+ * It detects which one it is from the namespace of the root node:
+ * - @stxt.template => processed as a template
+ * - @stxt.schema => processed as a schema
+ * - anything else => ignored
  */
 class UnifiedSchemaProvider {
+    /** Creates an empty provider, with the two meta-schemas already loaded. */
     constructor() {
         this.schemas = new Map();
         this.schemaMeta = new SchemaProviderMeta_1.SchemaProviderMeta();
         this.templateMeta = new MetaTemplateSchemaProvider_1.MetaTemplateSchemaProvider();
     }
+    /**
+     * Resolves the schema that applies to a namespace, serving the meta-schemas of the two
+     * reserved namespaces itself.
+     *
+     * @param namespace namespace whose schema is wanted.
+     * @returns the schema of the namespace, or null/undefined if none has been registered for it.
+     */
     getSchema(namespace) {
         const key = StringUtils_1.StringUtils.lowerCase(namespace);
         if (namespace === "@stxt.template") {
@@ -32,6 +40,14 @@ class UnifiedSchemaProvider {
         let result = this.schemas.get(key);
         return result;
     }
+    /**
+     * Parses a document and registers every schema or template it defines, each one under its own
+     * namespace. Documents of any other namespace are ignored.
+     *
+     * @param text text of the document to load.
+     * @throws ParseException if the document cannot be parsed, or the first ValidationException if
+     *         a schema or a template does not validate against its meta-schema.
+     */
     addFile(text) {
         const parser = new Parser_1.Parser();
         const nodes = parser.parse(text);
@@ -46,32 +62,34 @@ class UnifiedSchemaProvider {
         }
     }
     addTemplateNode(node) {
-        // Validar contra el meta-schema de templates
+        // Validate against the meta-schema of templates
         const schemaValidator = new SchemaValidator_1.SchemaValidator(this.templateMeta, true);
         UnifiedSchemaProvider.throwIfInvalid(schemaValidator.validate(node));
-        // Transformar el template a schema
+        // Transform the template into a schema
         const schema = (0, TemplateParser_1.transformTemplateNodeToSchema)(node);
         const key = StringUtils_1.StringUtils.lowerCase(schema.getNamespace());
         this.schemas.set(key, schema);
     }
     addSchemaNode(node) {
-        // Validar contra el meta-schema de schemas
+        // Validate against the meta-schema of schemas
         const schemaValidator = new SchemaValidator_1.SchemaValidator(this.schemaMeta, true);
         UnifiedSchemaProvider.throwIfInvalid(schemaValidator.validate(node));
-        // Transformar el nodo a schema
+        // Transform the node into a schema
         const schema = (0, SchemaParser_1.transformNodeToSchema)(node);
         const key = StringUtils_1.StringUtils.lowerCase(schema.getNamespace());
         this.schemas.set(key, schema);
     }
-    // Un schema/template que no valida contra su meta-schema no debe cargarse
+    // A schema/template that does not validate against its meta-schema must not be loaded
     static throwIfInvalid(errors) {
         if (errors.length > 0) {
             throw errors[0];
         }
     }
+    /** Removes every schema and template registered in this provider. */
     clear() {
         this.schemas.clear();
     }
+    /** @returns every schema registered in this provider, in registration order. */
     getAllSchemas() {
         return Array.from(this.schemas.values());
     }

package/out/schema/ChildDefinition.d.ts

@@ -1,16 +1,34 @@
+/** Definition of an expected child inside a {@link NodeDefinition}: name, namespace and min/max cardinality. */
 export declare class ChildDefinition {
     private readonly normalizedName;
     private readonly name;
     private readonly namespace;
     private readonly min;
     private readonly max;
+    /**
+     * Creates the definition of an expected child.
+     *
+     * @param name name of the expected child.
+     * @param namespace namespace of the expected child (may be null/undefined).
+     * @param min minimum cardinality, or null if there is no minimum.
+     * @param max maximum cardinality, or null if there is no maximum.
+     * @param numLine line number, for the error messages.
+     * @throws ValidationException with code `INVALID_NODE_NAME` if the name is not valid.
+     */
     constructor(name: string, namespace: string | null | undefined, min: number | null, max: number | null, numLine: number);
+    /** @returns the name of the expected child, as it appears in the schema. */
     getName(): string;
+    /** @returns the canonical name of the expected child. */
     getNormalizedName(): string;
+    /** @returns the namespace of the expected child, or the empty string if it has none. */
     getNamespace(): string;
+    /** @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 canonical name prefixed by its namespace, used as the key in {@link NodeDefinition.getChildren}. */
     getQualifiedName(): string;
+    /** @returns a plain object with the definition, so that JSON.stringify serializes it. */
     toJSON(): {
         name: string;
         normalizedName: string;

package/out/schema/ChildDefinition.js

@@ -4,7 +4,18 @@ exports.ChildDefinition = void 0;
 const NamespaceValidator_1 = require("../core/NamespaceValidator");
 const ValidationException_1 = require("../exceptions/ValidationException");
 const StringUtils_1 = require("../core/StringUtils");
+/** Definition of an expected child inside a {@link NodeDefinition}: name, namespace and min/max cardinality. */
 class ChildDefinition {
+    /**
+     * Creates the definition of an expected child.
+     *
+     * @param name name of the expected child.
+     * @param namespace namespace of the expected child (may be null/undefined).
+     * @param min minimum cardinality, or null if there is no minimum.
+     * @param max maximum cardinality, or null if there is no maximum.
+     * @param numLine line number, for the error messages.
+     * @throws ValidationException with code `INVALID_NODE_NAME` if the name is not valid.
+     */
     constructor(name, namespace, min, max, numLine) {
         this.name = StringUtils_1.StringUtils.compactSpaces(name);
         this.normalizedName = StringUtils_1.StringUtils.normalize(name);
@@ -16,26 +27,33 @@ class ChildDefinition {
             throw new ValidationException_1.ValidationException(numLine, "INVALID_NODE_NAME", `Node name not valid: ${name}`);
         }
     }
+    /** @returns the name of the expected child, as it appears in the schema. */
     getName() {
         return this.name;
     }
+    /** @returns the canonical name of the expected child. */
     getNormalizedName() {
         return this.normalizedName;
     }
+    /** @returns the namespace of the expected child, or the empty string if it has none. */
     getNamespace() {
         return this.namespace;
     }
+    /** @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 canonical name prefixed by its namespace, used as the key in {@link NodeDefinition.getChildren}. */
     getQualifiedName() {
         return this.namespace.length === 0
             ? this.normalizedName
             : `${this.namespace}:${this.normalizedName}`;
     }
+    /** @returns a plain object with the definition, so that JSON.stringify serializes it. */
     toJSON() {
         return {
             name: this.getName(),