@stxt-lang/core 0.5.1 → 0.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stxt-lang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @stxt-lang/core
+
+Parser and schema validator for **STXT**, an indentation-based structured-text format.
+
+STXT is a plain-text format for writing structured, semantic documents: no braces, no closing tags, just indentation. It is designed to be equally readable by humans and by machines, and it comes with an optional schema layer so documents can be validated.
+
+- Website and language reference: <https://stxt.dev>
+- VSCode extension: [STXT - Semantic Text](https://marketplace.visualstudio.com/items?itemName=stxt-lang.stxt)
+- Java implementation: [`dev.stxt:stxt-core`](https://central.sonatype.com/artifact/dev.stxt/stxt-core) on Maven Central
+
+## What STXT looks like
+
+```stxt
+# A line starting with '#' is a comment
+
+Article (blog.post):
+    Title: Getting started with STXT
+    Author: Joan
+    Published: 2026-07-28
+    Tags:
+        Tag: parser
+        Tag: text-format
+    Body >>
+        Everything indented under a '>>' node is kept verbatim
+        as a block of text lines.
+```
+
+- `Name: value` declares an **inline node**.
+- `Name >>` opens a **text block**; every deeper-indented line belongs to it.
+- Indentation is **one level per tab or per 4 spaces**.
+- `Name (a.b.c):` attaches a **namespace** to a node; children inherit it unless they declare their own.
+
+## Install
+
+```bash
+npm install @stxt-lang/core
+```
+
+The package ships CommonJS plus type declarations, so it works from both TypeScript and plain Node.
+
+## Parsing
+
+```ts
+import { Parser, ParseResult, Node } from '@stxt-lang/core';
+
+const text = [
+    'Article (blog.post):',
+    '\tTitle: Getting started with STXT',
+    '\tAuthor: Joan',
+].join('\n');
+
+const parser = new Parser();
+
+// parseResult() collects every error instead of stopping at the first one
+const result: ParseResult = parser.parseResult(text);
+
+if (result.hasErrors()) {
+    for (const error of result.getErrors()) {
+        console.error(`line ${error.line} [${error.code}]: ${error.message}`);
+    }
+}
+
+const article: Node = result.getNodes()[0];
+
+console.log(article.getName());                     // "Article"
+console.log(article.getNamespace());                // "blog.post"
+console.log(article.getChild('Title')?.getValue()); // "Getting started with STXT"
+```
+
+Use `parser.parse(text)` instead if you prefer an exception (`ParseException`) on the first error.
+
+Nodes are **frozen once parsed** — treat the tree as immutable.
+
+## Validating against a schema
+
+Schemas are themselves STXT documents, written in the reserved `@stxt.schema` namespace (or in the friendlier `@stxt.template` form, which compiles to a schema). `UnifiedSchemaProvider` loads either kind, validates it against the corresponding meta-schema, and registers it by namespace.
+
+```ts
+import {
+    Parser,
+    UnifiedSchemaProvider,
+    SchemaValidator,
+    ConditionalValidator,
+    ValidationException,
+} from '@stxt-lang/core';
+
+const schemaText = `
+Schema (@stxt.schema): blog.post
+\tNode: Article
+\t\tChildren:
+\t\t\tChild: Title
+\t\t\t\tMin: 1
+\t\t\t\tMax: 1
+\t\t\tChild: Author
+\t\t\t\tMin: 1
+\tNode: Title
+\tNode: Author
+`;
+
+const provider = new UnifiedSchemaProvider();
+provider.addFile(schemaText);
+
+const parser = new Parser();
+// ConditionalValidator only validates nodes that carry a namespace
+parser.registerValidator(new ConditionalValidator(new SchemaValidator(provider)));
+
+const result = parser.parseResult(documentText);
+
+for (const error of result.getErrors()) {
+    // Schema problems are ValidationException; syntax problems are plain ParseException
+    const severity = error instanceof ValidationException ? 'warning' : 'error';
+    console.log(`${severity} at line ${error.line} [${error.code}]: ${error.message}`);
+}
+```
+
+Available value types: `INLINE`, `BLOCK`, `TEXT`, `BOOLEAN`, `INTEGER`, `NATURAL`, `NUMBER`, `DATE`, `TIMESTAMP`, `EMAIL`, `URL`, `HEXADECIMAL`, `BASE64`, `GROUP`, `ENUM`.
+
+## Observing the parse
+
+`Observer` receives streaming callbacks while the document is parsed — useful for syntax highlighting, indexes or any per-line bookkeeping.
+
+```ts
+import { Parser, Observer, Node, Line } from '@stxt-lang/core';
+
+class LoggingObserver implements Observer {
+    onCreate(node: Node, line: string): void {
+        console.log('open', node.getQualifiedName());
+    }
+    onFinish(node: Node): void {
+        console.log('close', node.getQualifiedName());
+    }
+    onComment(lineNumber: number, line: string): void { /* ... */ }
+    onTextLine(node: Node, lineNumber: number, lineString: string, line: Line): void { /* ... */ }
+}
+
+const parser = new Parser();
+parser.registerObserver(new LoggingObserver());
+parser.parseResult(text);
+```
+
+## Writing STXT back out
+
+```ts
+import { NodeWriter, IndentStyle } from '@stxt-lang/core';
+
+// A single node, or a whole document list
+const text = NodeWriter.toSTXT(node, IndentStyle.TABS);
+const doc = NodeWriter.toSTXTDocs(result.getNodes(), IndentStyle.SPACES_4);
+```
+
+## API surface
+
+Everything importable from the package: `Node`, `Parser`, `ParseResult`, `Line`, `Constants`, `parseLine`, `StringUtils`, `ParseException`, `ValidationException`, `Observer`, `Schema`, `SchemaValidator`, `SchemaProvider`, `NodeDefinition`, `ChildDefinition`, `transformNodeToSchema`, `UnifiedSchemaProvider`, `ConditionalValidator`, `NodeWriter`, `IndentStyle`, `transformTemplateNodeToSchema`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/out/all.d.ts

@@ -6,6 +6,7 @@ export { Constants } from "./core/Constants";
 export { parseLine } from "./core/LineParser";
 export { StringUtils } from "./core/StringUtils";
 export { ParseException } from "./exceptions/ParseException";
+export { ValidationException } from "./exceptions/ValidationException";
 export { Observer } from "./processors/Observer";
 export { Schema } from "./schema/Schema";
 export { SchemaValidator } from "./schema/SchemaValidator";

package/out/all.js

@@ -1,9 +1,9 @@
 "use strict";
-// Punto de entrada público del paquete (out/all.js / out/all.d.ts).
-// Todo lo que deba ser consumible por terceros (p. ej. la extensión VSCode)
-// debe re-exportarse desde aquí.
+// Public entry point of the package (out/all.js / out/all.d.ts).
+// Anything that should be consumable by third parties (e.g. the VSCode extension)
+// has to be re-exported from here.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transformTemplateNodeToSchema = exports.IndentStyle = exports.NodeWriter = exports.ConditionalValidator = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.SchemaValidator = exports.Schema = exports.ParseException = exports.StringUtils = exports.parseLine = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.Node = void 0;
+exports.transformTemplateNodeToSchema = exports.IndentStyle = exports.NodeWriter = exports.ConditionalValidator = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.SchemaValidator = exports.Schema = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.Node = void 0;
 var Node_1 = require("./core/Node");
 Object.defineProperty(exports, "Node", { enumerable: true, get: function () { return Node_1.Node; } });
 var Parser_1 = require("./core/Parser");
@@ -20,6 +20,8 @@ var StringUtils_1 = require("./core/StringUtils");
 Object.defineProperty(exports, "StringUtils", { enumerable: true, get: function () { return StringUtils_1.StringUtils; } });
 var ParseException_1 = require("./exceptions/ParseException");
 Object.defineProperty(exports, "ParseException", { enumerable: true, get: function () { return ParseException_1.ParseException; } });
+var ValidationException_1 = require("./exceptions/ValidationException");
+Object.defineProperty(exports, "ValidationException", { enumerable: true, get: function () { return ValidationException_1.ValidationException; } });
 var Schema_1 = require("./schema/Schema");
 Object.defineProperty(exports, "Schema", { enumerable: true, get: function () { return Schema_1.Schema; } });
 var SchemaValidator_1 = require("./schema/SchemaValidator");

package/out/core/Constants.d.ts

@@ -1,9 +1,17 @@
+/** Characters and sizes fixed by STXT-SPEC that the parser and the writer share. */
 export declare class Constants {
+    /** Character that opens a comment line. */
     static readonly COMMENT_CHAR: string;
+    /** Number of spaces that make up one indentation level. */
     static readonly TAB_SPACES: number;
+    /** Tab character, the other way of indenting one level. */
     static readonly TAB: string;
+    /** Space character. */
     static readonly SPACE: string;
+    /** Separator between the name and the value of an INLINE node. */
     static readonly SEP_NODE: string;
+    /** Marker that turns a node into a BLOCK text node. */
     static readonly SEP_TEXT_NODE: string;
+    /** Namespace of a node that declares none and inherits none. */
     static readonly EMPTY_NAMESPACE: string;
 }

package/out/core/Constants.js

@@ -1,14 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Constants = void 0;
+/** Characters and sizes fixed by STXT-SPEC that the parser and the writer share. */
 class Constants {
 }
 exports.Constants = Constants;
+/** Character that opens a comment line. */
 Constants.COMMENT_CHAR = "#";
+/** Number of spaces that make up one indentation level. */
 Constants.TAB_SPACES = 4;
+/** Tab character, the other way of indenting one level. */
 Constants.TAB = "\t";
+/** Space character. */
 Constants.SPACE = " ";
+/** Separator between the name and the value of an INLINE node. */
 Constants.SEP_NODE = ":";
+/** Marker that turns a node into a BLOCK text node. */
 Constants.SEP_TEXT_NODE = ">>";
+/** Namespace of a node that declares none and inherits none. */
 Constants.EMPTY_NAMESPACE = "";
 //# sourceMappingURL=Constants.js.map

package/out/core/Line.d.ts

@@ -1,9 +1,29 @@
+/**
+ * A source line already split into its indentation and its content, as produced by
+ * {@link parseLine}. It is what tells the {@link Parser} whether the line opens a node, continues
+ * a text block or is just a comment.
+ */
 export declare class Line {
+    /** Indentation level of the line (one level per tab or per {@link Constants.TAB_SPACES} spaces). */
     readonly level: number;
+    /** Content of the line with the indentation already removed. */
     readonly content: string;
+    /** True if the line is a comment (`#`). */
     readonly isComment: boolean;
+    /** True if the line is a text line belonging to an open BLOCK node (`>>`). */
     readonly isBlock: boolean;
+    /** Number of characters the indentation took up. */
     readonly indentLength: number;
+    /**
+     * Creates a line already split into indentation and content.
+     *
+     * @param level indentation level of the line.
+     * @param content content of the line without its indentation.
+     * @param isComment true if the line is a comment.
+     * @param isBlock true if the line belongs to an open text block.
+     * @param indentLength number of characters the indentation took up.
+     */
     constructor(level: number, content: string, isComment: boolean, isBlock: boolean, indentLength: number);
+    /** @returns true if the line has no content beyond whitespace. */
     isEmpty(): boolean;
 }

package/out/core/Line.js

@@ -1,7 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Line = void 0;
+/**
+ * A source line already split into its indentation and its content, as produced by
+ * {@link parseLine}. It is what tells the {@link Parser} whether the line opens a node, continues
+ * a text block or is just a comment.
+ */
 class Line {
+    /**
+     * Creates a line already split into indentation and content.
+     *
+     * @param level indentation level of the line.
+     * @param content content of the line without its indentation.
+     * @param isComment true if the line is a comment.
+     * @param isBlock true if the line belongs to an open text block.
+     * @param indentLength number of characters the indentation took up.
+     */
     constructor(level, content, isComment, isBlock, indentLength) {
         this.level = level;
         this.content = content;
@@ -9,6 +23,7 @@ class Line {
         this.isBlock = isBlock;
         this.indentLength = indentLength;
     }
+    /** @returns true if the line has no content beyond whitespace. */
     isEmpty() {
         return this.content.trim() === "";
     }

package/out/core/LineParser.d.ts

@@ -1,2 +1,19 @@
 import { Line } from "./Line";
+/**
+ * Splits a source line into its indentation and its content, and classifies it as a comment, a
+ * text line of an open block or a regular line.
+ *
+ * Indentation is one level per tab or per {@link Constants.TAB_SPACES} spaces; mixing both, using
+ * a number of spaces that is not a multiple of four or going more than one level deeper than the
+ * previous node are errors (spec 8.1 and 8.3).
+ *
+ * @param line source line, with its indentation.
+ * @param lastNodeBlock true if the node currently open is a BLOCK text node.
+ * @param lastLevel indentation level of the node currently open.
+ * @param numLine line number, for the error messages.
+ * @param validate false to split the line without enforcing the indentation rules.
+ * @returns the line already split into indentation and content.
+ * @throws ParseException with code `MIXED_INDENTATION`, `INVALID_NUMBER_SPACES` or
+ *         `INDENTATION_LEVEL_NOT_VALID` if the indentation is not valid.
+ */
 export declare function parseLine(line: string, lastNodeBlock: boolean, lastLevel: number, numLine: number, validate?: boolean): Line;

package/out/core/LineParser.js

@@ -5,6 +5,23 @@ const Constants_1 = require("./Constants");
 const StringUtils_1 = require("./StringUtils");
 const ParseException_1 = require("../exceptions/ParseException");
 const Line_1 = require("./Line");
+/**
+ * Splits a source line into its indentation and its content, and classifies it as a comment, a
+ * text line of an open block or a regular line.
+ *
+ * Indentation is one level per tab or per {@link Constants.TAB_SPACES} spaces; mixing both, using
+ * a number of spaces that is not a multiple of four or going more than one level deeper than the
+ * previous node are errors (spec 8.1 and 8.3).
+ *
+ * @param line source line, with its indentation.
+ * @param lastNodeBlock true if the node currently open is a BLOCK text node.
+ * @param lastLevel indentation level of the node currently open.
+ * @param numLine line number, for the error messages.
+ * @param validate false to split the line without enforcing the indentation rules.
+ * @returns the line already split into indentation and content.
+ * @throws ParseException with code `MIXED_INDENTATION`, `INVALID_NUMBER_SPACES` or
+ *         `INDENTATION_LEVEL_NOT_VALID` if the indentation is not valid.
+ */
 function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
     let level = 0;
     let spaces = 0;
@@ -30,23 +47,23 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
             return new Line_1.Line(level, line.substring(pointer + 1), true, false, pointer);
         }
         else {
-            // Primer carácter no espacio/tab/comentario => fin de indentación
+            // First character that is not space/tab/comment => end of indentation
             break;
         }
-        // Dentro del bloque de texto
+        // Inside the text block
         if (lastNodeBlock && level > lastLevel) {
             const text = StringUtils_1.StringUtils.rightTrim(line.substring(pointer + 1));
-            // El prefijo que cubre el nivel de bloque debe ser homogéneo (spec 10.2, regla 2);
-            // las líneas vacías se preservan siempre y quedan exentas (spec 10.3)
+            // The prefix covering the block level must be homogeneous (spec 10.2, rule 2);
+            // empty lines are always preserved and are exempt from it (spec 10.3)
             if (validate && sawSpace && sawTab && text.length > 0) {
                 throw new ParseException_1.ParseException(numLine, "MIXED_INDENTATION", `Mixed tabs and spaces in indentation`);
             }
             return new Line_1.Line(level, text, false, true, pointer);
         }
-        // Aumentamos pointer
+        // Move the pointer forward
         pointer++;
     }
-    // En este punto ya estamos fuera de bloque de texto (si existía)
+    // From here on we are outside the text block (if there was one)
     // Empty
     if (pointer === line.length) {
         if (lastNodeBlock) {
@@ -54,19 +71,19 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
         }
         return new Line_1.Line(level, "", false, false, pointer);
     }
-    // Mezcla de espacios y tabuladores en la indentación (spec 8.1 y 8.3)
+    // Tabs and spaces mixed in the indentation (spec 8.1 and 8.3)
     if (validate && sawSpace && sawTab) {
         throw new ParseException_1.ParseException(numLine, "MIXED_INDENTATION", `Mixed tabs and spaces in indentation`);
     }
-    // Indentación no es múltiplo de 4 con espacios
+    // Indentation with spaces that is not a multiple of 4
     if (validate && spaces > 0) {
         throw new ParseException_1.ParseException(numLine, "INVALID_NUMBER_SPACES", `There are ${spaces} spaces before node`);
     }
-    // Validamos level
+    // Validate the level
     if (validate && level > lastLevel + 1) {
         throw new ParseException_1.ParseException(numLine, "INDENTATION_LEVEL_NOT_VALID", `Level of indent incorrect: ${level}`);
     }
-    // Caso general: devolver la línea sin la indentación consumida
+    // General case: return the line without the indentation already consumed
     return new Line_1.Line(level, line.substring(pointer).trim(), false, false, pointer);
 }
 //# sourceMappingURL=LineParser.js.map

package/out/core/NameNamespace.d.ts

@@ -1,7 +1,16 @@
+/** Result of splitting a raw node name into its resolved name and namespace. */
 export declare class NameNamespace {
     private readonly name;
     private readonly namespace;
+    /**
+     * Creates a resolved name and namespace pair.
+     *
+     * @param name name of the node without the namespace part.
+     * @param namespace resolved namespace (its own or inherited).
+     */
     constructor(name: string, namespace: string);
+    /** @returns the name of the node, without the namespace part. */
     getName(): string;
+    /** @returns the resolved namespace (its own or inherited from the parent), or the empty string if it has none. */
     getNamespace(): string;
 }

package/out/core/NameNamespace.js

@@ -1,14 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameNamespace = void 0;
+/** Result of splitting a raw node name into its resolved name and namespace. */
 class NameNamespace {
+    /**
+     * Creates a resolved name and namespace pair.
+     *
+     * @param name name of the node without the namespace part.
+     * @param namespace resolved namespace (its own or inherited).
+     */
     constructor(name, namespace) {
         this.name = name;
         this.namespace = namespace;
     }
+    /** @returns the name of the node, without the namespace part. */
     getName() {
         return this.name;
     }
+    /** @returns the resolved namespace (its own or inherited from the parent), or the empty string if it has none. */
     getNamespace() {
         return this.namespace;
     }

package/out/core/NameNamespaceParser.d.ts

@@ -1,5 +1,16 @@
 import { NameNamespace } from "./NameNamespace";
+/** Extracts the name and the namespace `(a.b.c)` from the left-hand side of an STXT line. */
 export declare class NameNamespaceParser {
     private constructor();
+    /**
+     * Splits a raw node name into its name and its namespace.
+     *
+     * @param rawName raw name, with the namespace in parentheses if it carries one.
+     * @param inheritedNs namespace inherited from the parent, used when `rawName` brings none of its own.
+     * @param lineNumber line number, for the error messages.
+     * @param fullLine original full line, for the error messages.
+     * @returns the name and the namespace, already split apart and resolved.
+     * @throws ParseException if the name or the namespace are not well formed.
+     */
     static parse(rawName: string | null | undefined, inheritedNs: string | null | undefined, lineNumber: number, fullLine: string): NameNamespace;
 }

package/out/core/NameNamespaceParser.js

@@ -3,9 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameNamespaceParser = void 0;
 const ParseException_1 = require("../exceptions/ParseException");
 const NameNamespace_1 = require("./NameNamespace");
+/** Extracts the name and the namespace `(a.b.c)` from the left-hand side of an STXT line. */
 class NameNamespaceParser {
     constructor() {
     }
+    /**
+     * Splits a raw node name into its name and its namespace.
+     *
+     * @param rawName raw name, with the namespace in parentheses if it carries one.
+     * @param inheritedNs namespace inherited from the parent, used when `rawName` brings none of its own.
+     * @param lineNumber line number, for the error messages.
+     * @param fullLine original full line, for the error messages.
+     * @returns the name and the namespace, already split apart and resolved.
+     * @throws ParseException if the name or the namespace are not well formed.
+     */
     static parse(rawName, inheritedNs, lineNumber, fullLine) {
         if (rawName === null || rawName === undefined) {
             throw new ParseException_1.ParseException(lineNumber, "INVALID_LINE", `Line not valid: ${fullLine}`);
@@ -15,27 +26,27 @@ class NameNamespaceParser {
         const endIndex = rawName.indexOf(")");
         let name;
         let namespace = inheritedNs ?? "";
-        // Encontrados los dos
+        // Both of them found
         if (startIndex !== -1 && endIndex !== -1) {
             if (startIndex > endIndex || endIndex !== rawName.length - 1) {
                 throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
             }
             name = rawName.substring(0, startIndex).trim();
-            // Sin trim: la gramática (STXT-SPEC 7/16) no admite espacios dentro de '( )'
+            // No trim: the grammar (STXT-SPEC 7/16) does not allow spaces inside '( )'
             namespace = rawName.substring(startIndex + 1, endIndex);
             if (namespace.length === 0) {
                 throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
             }
         }
-        // Ninguno de los dos
+        // Neither of them
         else if (startIndex === -1 && endIndex === -1) {
             name = rawName;
         }
-        // Solo uno de los dos
+        // Only one of the two
         else {
             throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
         }
-        // Retorno
+        // Return
         return new NameNamespace_1.NameNamespace(name, namespace.toLowerCase());
     }
 }

package/out/core/NamespaceValidator.d.ts

@@ -1,4 +1,22 @@
+/** Validates the format of STXT `(a.b.c)` namespaces. */
 export declare class NamespaceValidator {
+    /**
+     * Format of the logical namespace.
+     *
+     * Rules:
+     * - Lower-case letters, digits and dot only.
+     * - It may optionally start with '@'.
+     * - It must be one or more domain-style labels separated by '.':
+     *   label := [a-z0-9]+
+     * valid examples: "xxx", "xxx.ddd", "zzz.ttt.ooo", "@xxx", "@xxx.ddd".
+     */
     private static readonly NAMESPACE_FORMAT;
+    /**
+     * Validates the format of a namespace.
+     *
+     * @param namespace already normalized namespace to validate; ignored when null or empty.
+     * @param lineNumber line number, for the error message.
+     * @throws ParseException with code `INVALID_NAMESPACE` if it does not match the format.
+     */
     static validateNamespaceFormat(namespace: string | null | undefined, lineNumber: number): void;
 }

package/out/core/NamespaceValidator.js

@@ -2,7 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NamespaceValidator = void 0;
 const ParseException_1 = require("../exceptions/ParseException");
+/** Validates the format of STXT `(a.b.c)` namespaces. */
 class NamespaceValidator {
+    /**
+     * Validates the format of a namespace.
+     *
+     * @param namespace already normalized namespace to validate; ignored when null or empty.
+     * @param lineNumber line number, for the error message.
+     * @throws ParseException with code `INVALID_NAMESPACE` if it does not match the format.
+     */
     static validateNamespaceFormat(namespace, lineNumber) {
         if (!namespace) {
             return;
@@ -13,5 +21,15 @@ class NamespaceValidator {
     }
 }
 exports.NamespaceValidator = NamespaceValidator;
+/**
+ * Format of the logical namespace.
+ *
+ * Rules:
+ * - Lower-case letters, digits and dot only.
+ * - It may optionally start with '@'.
+ * - It must be one or more domain-style labels separated by '.':
+ *   label := [a-z0-9]+
+ * valid examples: "xxx", "xxx.ddd", "zzz.ttt.ooo", "@xxx", "@xxx.ddd".
+ */
 NamespaceValidator.NAMESPACE_FORMAT = /^@?[a-z0-9]+(\.[a-z0-9]+)+$/;
 //# sourceMappingURL=NamespaceValidator.js.map