@stxt-lang/core 0.5.2 → 0.5.3

package/out/core/NodeCreator.js

@@ -5,6 +5,17 @@ const NameNamespaceParser_1 = require("./NameNamespaceParser");
 const Node_1 = require("./Node");
 const ParseException_1 = require("../exceptions/ParseException");
 const Constants_1 = require("./Constants");
+/**
+ * Builds the node a line opens, telling apart the INLINE form (`Name: value`) from the BLOCK one
+ * (`Name >>`) and resolving the namespace against the parent.
+ *
+ * @param lineIndent line already split into indentation and content.
+ * @param lineNumber line number of the document where the node opens.
+ * @param level indentation level of the node.
+ * @param parent node currently open, whose namespace is inherited, or null at root level.
+ * @returns the node the line opens, still with no children and no text lines.
+ * @throws ParseException if the line is not a valid node declaration.
+ */
 function createNode(lineIndent, lineNumber, level, parent) {
     const line = lineIndent.content;
     let name;
@@ -38,15 +49,15 @@ function createNode(lineIndent, lineNumber, level, parent) {
     if (textNode && value.trim().length > 0) {
         throw new ParseException_1.ParseException(lineNumber, "INLINE_VALUE_NOT_VALID", `Line not valid: ${line}`);
     }
-    // Namespace por defecto: heredado del padre
+    // Default namespace: inherited from the parent
     const nameNamespace = NameNamespaceParser_1.NameNamespaceParser.parse(name, parent ? parent.getNamespace() : null, lineNumber, line);
     name = nameNamespace.getName();
     const namespace = nameNamespace.getNamespace();
-    // Validamos nombre
+    // Validate the name
     if (name.length === 0) {
         throw new ParseException_1.ParseException(lineNumber, "INVALID_LINE", `Line not valid: ${line}`);
     }
-    // Creamos nodo
+    // Create the node
     return new Node_1.Node(lineNumber, level, name, namespace, textNode, value);
 }
 //# sourceMappingURL=NodeCreator.js.map

package/out/core/ParseResult.d.ts

@@ -1,12 +1,38 @@
 import { Node } from "./Node";
 import { ParseException } from "../exceptions/ParseException";
+/**
+ * Result of a parse in multi-error mode: it collects the root nodes obtained and every error
+ * found (both syntax and validation ones), without bailing out on the first one.
+ *
+ * See {@link Parser.parseResult}. For the traditional fail-fast mode use {@link Parser.parse},
+ * which internally uses this result and throws the first error.
+ */
 export declare class ParseResult {
     private readonly nodes;
     private readonly errors;
+    /**
+     * Creates a result, empty by default.
+     *
+     * @param nodes root nodes to start from.
+     * @param errors errors to start from.
+     */
     constructor(nodes?: Node[], errors?: ParseException[]);
+    /** @returns the root nodes collected so far. */
     getNodes(): Node[];
+    /** @returns the syntax or validation errors collected so far, in order of appearance. */
     getErrors(): ParseException[];
+    /** @returns true if at least one error has been collected. */
     hasErrors(): boolean;
+    /**
+     * Adds an error found while parsing.
+     *
+     * @param error error found while parsing, without aborting the traversal.
+     */
     addError(error: ParseException): void;
+    /**
+     * Adds a root node to the result.
+     *
+     * @param node already closed root node to add to the result.
+     */
     addNode(node: Node): void;
 }

package/out/core/ParseResult.js

@@ -1,23 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ParseResult = void 0;
+/**
+ * Result of a parse in multi-error mode: it collects the root nodes obtained and every error
+ * found (both syntax and validation ones), without bailing out on the first one.
+ *
+ * See {@link Parser.parseResult}. For the traditional fail-fast mode use {@link Parser.parse},
+ * which internally uses this result and throws the first error.
+ */
 class ParseResult {
+    /**
+     * Creates a result, empty by default.
+     *
+     * @param nodes root nodes to start from.
+     * @param errors errors to start from.
+     */
     constructor(nodes = [], errors = []) {
         this.nodes = nodes;
         this.errors = errors;
     }
+    /** @returns the root nodes collected so far. */
     getNodes() {
         return this.nodes;
     }
+    /** @returns the syntax or validation errors collected so far, in order of appearance. */
     getErrors() {
         return this.errors;
     }
+    /** @returns true if at least one error has been collected. */
     hasErrors() {
         return this.errors.length > 0;
     }
+    /**
+     * Adds an error found while parsing.
+     *
+     * @param error error found while parsing, without aborting the traversal.
+     */
     addError(error) {
         this.errors.push(error);
     }
+    /**
+     * Adds a root node to the result.
+     *
+     * @param node already closed root node to add to the result.
+     */
     addNode(node) {
         this.nodes.push(node);
     }

package/out/core/Parser.d.ts

@@ -2,12 +2,43 @@ import { Node } from "./Node";
 import { Observer } from "../processors/Observer";
 import { Validator } from "../processors/Validator";
 import { ParseResult } from "./ParseResult";
+/**
+ * Line-by-line STXT parsing engine. It knows nothing about schemas: semantic validation is
+ * plugged in through {@link Parser.registerValidator} and {@link Parser.registerObserver}.
+ * See {@link UnifiedSchemaProvider} for the usual way of building the validators to register.
+ */
 export declare class Parser {
     private observers;
     private validators;
+    /**
+     * Registers an observer, notified when each node is opened and closed.
+     *
+     * @param observer the {@link Observer} to register, notified while parsing.
+     */
     registerObserver(observer: Observer): void;
+    /**
+     * Registers a validator, invoked when each node is closed.
+     *
+     * @param validator the {@link Validator} to register, invoked when each node is closed during parsing.
+     */
     registerValidator(validator: Validator): void;
+    /**
+     * Traditional fail-fast mode: throws the first error found (either syntax or validation).
+     * Internally it reuses the same traversal as {@link Parser.parseResult}, and throws the first
+     * error it collected.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the root nodes of the document.
+     * @throws ParseException the first error found, be it syntax or validation.
+     */
     parse(content: string): Node[];
+    /**
+     * Multi-error mode: parses the whole content collecting every error found (both syntax and
+     * validation) without bailing out on the first one. See {@link ParseResult}.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the collected result, with the root nodes obtained and every error found.
+     */
     parseResult(content: string): ParseResult;
     private processLine;
     private handleError;

package/out/core/Parser.js

@@ -5,17 +5,41 @@ const LineParser_1 = require("./LineParser");
 const NodeCreator_1 = require("./NodeCreator");
 const ParseResult_1 = require("./ParseResult");
 const ParseException_1 = require("../exceptions/ParseException");
+/**
+ * Line-by-line STXT parsing engine. It knows nothing about schemas: semantic validation is
+ * plugged in through {@link Parser.registerValidator} and {@link Parser.registerObserver}.
+ * See {@link UnifiedSchemaProvider} for the usual way of building the validators to register.
+ */
 class Parser {
     constructor() {
         this.observers = [];
         this.validators = [];
     }
+    /**
+     * Registers an observer, notified when each node is opened and closed.
+     *
+     * @param observer the {@link Observer} to register, notified while parsing.
+     */
     registerObserver(observer) {
         this.observers.push(observer);
     }
+    /**
+     * Registers a validator, invoked when each node is closed.
+     *
+     * @param validator the {@link Validator} to register, invoked when each node is closed during parsing.
+     */
     registerValidator(validator) {
         this.validators.push(validator);
     }
+    /**
+     * Traditional fail-fast mode: throws the first error found (either syntax or validation).
+     * Internally it reuses the same traversal as {@link Parser.parseResult}, and throws the first
+     * error it collected.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the root nodes of the document.
+     * @throws ParseException the first error found, be it syntax or validation.
+     */
     parse(content) {
         const result = this.parseResult(content);
         if (result.hasErrors()) {
@@ -24,6 +48,13 @@ class Parser {
         }
         return result.getNodes();
     }
+    /**
+     * Multi-error mode: parses the whole content collecting every error found (both syntax and
+     * validation) without bailing out on the first one. See {@link ParseResult}.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the collected result, with the root nodes obtained and every error found.
+     */
     parseResult(content) {
         content = this.removeUTF8BOM(content);
         const result = new ParseResult_1.ParseResult();
@@ -31,8 +62,8 @@ class Parser {
         const documents = [];
         let lineNumber = 0;
         const lines = content.split(/\r?\n/);
-        // El salto de línea final es terminador de la última línea, no una línea
-        // vacía adicional (evita añadir una línea espuria a un bloque >> en EOF, spec 10.3)
+        // The final line break terminates the last line, it is not an extra empty line
+        // (this avoids adding a spurious line to a >> block at EOF, spec 10.3)
         if (lines.length > 0 && lines[lines.length - 1] === "") {
             lines.pop();
         }
@@ -40,13 +71,13 @@ class Parser {
             lineNumber++;
             this.processLine(line, lineNumber, stack, documents, result);
         }
-        // Cerrar todos los nodos pendientes al EOF
+        // Close every node still open at EOF
         this.closeToLevel(stack, documents, 0, result);
-        // Agregar nodos al resultado
+        // Add the nodes to the result
         for (const doc of documents) {
             result.addNode(doc);
         }
-        // Retorno resultado
+        // Return the result
         return result;
     }
     processLine(lineString, lineNumber, stack, documents, result) {
@@ -54,40 +85,40 @@ class Parser {
             const lastNode = stack.length === 0 ? null : stack[stack.length - 1];
             const lastLevel = lastNode ? lastNode.getLevel() : 0;
             const lastNodeText = lastNode ? lastNode.isTextNode() : false;
-            // Parseamos línea
+            // Parse the line
             const line = (0, LineParser_1.parseLine)(lineString, lastNodeText, lastLevel, lineNumber);
             if (line.isComment) {
-                // Pasamos a observers
+                // Hand it over to the observers
                 this.observers.forEach(observer => {
                     observer.onComment(lineNumber, lineString);
                 });
                 return;
             }
             const currentLevel = line.level;
-            // Si estamos dentro de un nodo texto, y el nivel indica que sigue siendo texto,
-            // añadimos línea de texto y no creamos nodo.
+            // When we are inside a text node and the level says it is still text,
+            // append the text line instead of creating a node.
             if (line.isBlock) {
                 lastNode.addTextLine(line.content);
-                // Notificar a observers sobre la línea de texto
+                // Notify the observers about the text line
                 this.observers.forEach(observer => {
                     observer.onTextLine(lastNode, lineNumber, lineString, line);
                 });
                 return;
             }
-            // Si es línea vacía no hacemos nada
+            // Empty lines are ignored
             if (line.isEmpty()) {
                 return;
             }
-            // Cerramos nodos hasta el nivel actual (esto "finaliza" y adjunta al padre/documentos)
+            // Close the nodes down to the current level (this "finishes" them and attaches them to the parent/documents)
             this.closeToLevel(stack, documents, currentLevel, result);
-            // Creamos el nuevo nodo y lo dejamos "abierto" en la pila (NO lo adjuntamos aún)
+            // Create the new node and leave it "open" on the stack (do NOT attach it yet)
             const parent = stack.length === 0 ? null : stack[stack.length - 1];
             const node = (0, NodeCreator_1.createNode)(line, lineNumber, currentLevel, parent);
-            // Pasamos a observers
+            // Hand it over to the observers
             this.observers.forEach(observer => {
                 observer.onCreate(node, lineString);
             });
-            // Añadimos a stack
+            // Push it onto the stack
             stack.push(node);
         }
         catch (e) {
@@ -99,18 +130,18 @@ class Parser {
             result.addError(e);
         }
         else if (e instanceof Error) {
-            // Convertir errores genéricos a ParseException
+            // Turn generic errors into a ParseException
             result.addError(new ParseException_1.ParseException(line, errorCode, e.message));
         }
         else {
-            // Error desconocido
+            // Unknown error
             result.addError(new ParseException_1.ParseException(line, unknownErrorCode, String(e)));
         }
     }
     closeToLevel(stack, documents, targetLevel, result) {
         while (stack.length > targetLevel) {
             const completed = stack.pop();
-            // Pasamos validators
+            // Hand it over to the validators
             this.validators.forEach(validator => {
                 try {
                     const errors = validator.validate(completed);
@@ -128,7 +159,7 @@ class Parser {
             else {
                 stack[stack.length - 1].addChild(completed);
             }
-            // Pasamos a observers
+            // Hand it over to the observers
             this.observers.forEach(observer => {
                 observer.onFinish(completed);
             });

package/out/core/StringUtils.d.ts

@@ -1,8 +1,39 @@
+/** String normalization helpers used for names, namespaces and values. */
 export declare class StringUtils {
     private constructor();
+    /**
+     * 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: string | null | undefined): string;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string | null | undefined): string;
+    /**
+     * 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: string | null | undefined): string;
+    /**
+     * 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: string | null | undefined): string;
 }

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[];
 }