@stxt-lang/core 0.5.2 → 0.6.0

package/out/schema/NodeDefinition.js

@@ -3,7 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeDefinition = void 0;
 const ValidationException_1 = require("../exceptions/ValidationException");
 const StringUtils_1 = require("../core/StringUtils");
+/**
+ * Definition of a node inside a {@link Schema}: its name, its value type, the children it expects
+ * ({@link ChildDefinition}) and, for ENUM, the values it allows.
+ */
 class NodeDefinition {
+    /**
+     * Creates the definition of a node.
+     *
+     * @param name name of the node.
+     * @param type name of the type (see {@link TypeRegistry}).
+     * @param line line number, for the error message.
+     * @param description optional description of the node.
+     * @throws ValidationException with code `INVALID_NODE_NAME` if the name is not valid.
+     */
     constructor(name, type, line, description) {
         this.children = new Map();
         this.values = new Set();
@@ -15,24 +28,40 @@ class NodeDefinition {
             throw new ValidationException_1.ValidationException(line, "INVALID_NODE_NAME", `Node name not valid: ${name}`);
         }
     }
+    /** @returns the name of the node, as it appears in the schema. */
     getName() {
         return this.name;
     }
+    /** @returns the canonical name of the node. */
     getNormalizedName() {
         return this.normalizedName;
     }
+    /** @returns the name of the value type of this node (see {@link TypeRegistry}). */
     getType() {
         return this.type;
     }
+    /** @returns the definitions of the expected children, indexed by their qualified canonical name. */
     getChildren() {
         return this.children;
     }
+    /** @returns the optional description of the node, or undefined if it has none. */
     getDescription() {
         return this.description;
     }
+    /**
+     * Sets the optional description of the node.
+     *
+     * @param description new optional description of the node.
+     */
     setDescription(description) {
         this.description = description;
     }
+    /**
+     * Adds the definition of an expected child.
+     *
+     * @param childDefinition definition of the child to add.
+     * @throws ValidationException with code `CHILD_DEF_ALREADY_DEFINED` if a definition for that child already existed.
+     */
     addChildDefinition(childDefinition) {
         const qname = childDefinition.getQualifiedName();
         if (this.children.has(qname)) {
@@ -40,9 +69,16 @@ class NodeDefinition {
         }
         this.children.set(qname, childDefinition);
     }
-    // STXT-SCHEMA-SPEC 13.9 / STXT-TEMPLATE-SPEC 14.14: no puede haber valores duplicados
-    // tras la normalización por trim. Mismo código que ChildLineParser: es la misma condición
-    // por la otra puerta de entrada.
+    // STXT-SCHEMA-SPEC 13.9 / STXT-TEMPLATE-SPEC 14.14: there can be no duplicated values
+    // after the trim normalization. Same code as ChildLineParser: it is the same condition
+    // coming through the other entry point.
+    /**
+     * Adds a value to the list of values allowed for this node.
+     *
+     * @param value value to add to the list of allowed values.
+     * @param line line number, for the error message.
+     * @throws ValidationException with code `VALUE_DUPLICATED` if the value (once trimmed) had already been added.
+     */
     addValue(value, line) {
         const trimmed = value?.trim() ?? "";
         if (this.values.has(trimmed)) {
@@ -50,15 +86,23 @@ class NodeDefinition {
         }
         this.values.add(trimmed);
     }
+    /**
+     * Tells whether a value is allowed for this node.
+     *
+     * @param value value to check.
+     * @returns true if no restricted values are defined, or if the value is among the allowed ones.
+     */
     isAllowedValue(value) {
         if (this.values.size === 0) {
             return true;
         }
         return this.values.has(value);
     }
+    /** @returns the values allowed for this node (ENUM), or empty if there is no restriction. */
     getValues() {
         return this.values;
     }
+    /** @returns a plain object with the definition, so that JSON.stringify serializes it. */
     toJSON() {
         return {
             name: this.getName(),

package/out/schema/Schema.d.ts

@@ -1,14 +1,39 @@
 import { NodeDefinition } from "./NodeDefinition";
+/** Schema of a namespace: the set of {@link NodeDefinition} valid for the nodes of that namespace. */
 export declare class Schema {
+    /** Namespace of the schema language itself, `@stxt.schema`. */
     static readonly SCHEMA_NAMESPACE = "@stxt.schema";
     private readonly nodes;
     private readonly namespace;
     private readonly description;
+    /**
+     * Creates an empty schema for a namespace.
+     *
+     * @param namespace namespace this schema applies to.
+     * @param line line number, for the error message.
+     * @param description optional description of the schema.
+     * @throws ParseException if the namespace is not well formed.
+     */
     constructor(namespace: string | null | undefined, line: number, description: string | undefined);
+    /** @returns the node definitions, indexed by their canonical name. */
     getNodes(): ReadonlyMap<string, NodeDefinition>;
+    /**
+     * Looks up the definition of a node by name.
+     *
+     * @param name name of the node to look for.
+     * @returns the definition of the node with that name, or undefined if it is not defined in this schema.
+     */
     getNodeDefinition(name: string): NodeDefinition | undefined;
+    /**
+     * Adds the definition of a node to this schema.
+     *
+     * @param nodeDefinition node definition to add.
+     * @throws ValidationException with code `NODE_DEF_ALREADY_DEFINED` if there already was a node definition with the same name.
+     */
     addNodeDefinition(nodeDefinition: NodeDefinition): void;
+    /** @returns the namespace this schema applies to. */
     getNamespace(): string;
+    /** @returns a plain object with the schema, so that JSON.stringify serializes it. */
     toJSON(): {
         namespace: string;
         nodes: {
@@ -26,5 +51,6 @@ export declare class Schema {
             values: string[];
         }[];
     };
+    /** @returns the schema as pretty-printed JSON, for debugging. */
     toString(): string;
 }

package/out/schema/Schema.js

@@ -4,19 +4,41 @@ exports.Schema = void 0;
 const NamespaceValidator_1 = require("../core/NamespaceValidator");
 const StringUtils_1 = require("../core/StringUtils");
 const ValidationException_1 = require("../exceptions/ValidationException");
+/** Schema of a namespace: the set of {@link NodeDefinition} valid for the nodes of that namespace. */
 class Schema {
+    /**
+     * Creates an empty schema for a namespace.
+     *
+     * @param namespace namespace this schema applies to.
+     * @param line line number, for the error message.
+     * @param description optional description of the schema.
+     * @throws ParseException if the namespace is not well formed.
+     */
     constructor(namespace, line, description) {
         this.nodes = new Map();
         this.namespace = StringUtils_1.StringUtils.lowerCase(namespace);
         this.description = description;
         NamespaceValidator_1.NamespaceValidator.validateNamespaceFormat(this.namespace, line);
     }
+    /** @returns the node definitions, indexed by their canonical name. */
     getNodes() {
         return this.nodes;
     }
+    /**
+     * Looks up the definition of a node by name.
+     *
+     * @param name name of the node to look for.
+     * @returns the definition of the node with that name, or undefined if it is not defined in this schema.
+     */
     getNodeDefinition(name) {
         return this.nodes.get(StringUtils_1.StringUtils.normalize(name));
     }
+    /**
+     * Adds the definition of a node to this schema.
+     *
+     * @param nodeDefinition node definition to add.
+     * @throws ValidationException with code `NODE_DEF_ALREADY_DEFINED` if there already was a node definition with the same name.
+     */
     addNodeDefinition(nodeDefinition) {
         const qname = nodeDefinition.getNormalizedName();
         if (this.nodes.has(qname)) {
@@ -24,20 +46,23 @@ class Schema {
         }
         this.nodes.set(qname, nodeDefinition);
     }
+    /** @returns the namespace this schema applies to. */
     getNamespace() {
         return this.namespace;
     }
-    // Dentro de la clase Schema
+    /** @returns a plain object with the schema, so that JSON.stringify serializes it. */
     toJSON() {
         return {
             namespace: this.namespace,
             nodes: Array.from(this.nodes.values()).map(n => n.toJSON()),
         };
     }
+    /** @returns the schema as pretty-printed JSON, for debugging. */
     toString() {
         return JSON.stringify(this, null, 2); // pretty print
     }
 }
 exports.Schema = Schema;
+/** Namespace of the schema language itself, `@stxt.schema`. */
 Schema.SCHEMA_NAMESPACE = "@stxt.schema";
 //# sourceMappingURL=Schema.js.map

package/out/schema/SchemaParser.d.ts

@@ -1,3 +1,10 @@
 import { Schema } from "./Schema";
 import { Node } from "../core/Node";
+/**
+ * Turns the tree of an already parsed `@stxt.schema` document into a {@link Schema}.
+ *
+ * @param node root node of the schema document, `Schema (@stxt.schema): ...`.
+ * @returns the schema the document defines.
+ * @throws ValidationException if the document is not a valid `@stxt.schema` one.
+ */
 export declare function transformNodeToSchema(node: Node): Schema;

package/out/schema/SchemaParser.js

@@ -8,32 +8,39 @@ const ValidationException_1 = require("../exceptions/ValidationException");
 const RuntimeException_1 = require("../exceptions/RuntimeException");
 const NameNamespaceParser_1 = require("../core/NameNamespaceParser");
 const TypeRegistry_1 = require("./TypeRegistry");
+/**
+ * Turns the tree of an already parsed `@stxt.schema` document into a {@link Schema}.
+ *
+ * @param node root node of the schema document, `Schema (@stxt.schema): ...`.
+ * @returns the schema the document defines.
+ * @throws ValidationException if the document is not a valid `@stxt.schema` one.
+ */
 function transformNodeToSchema(node) {
     // Node name
     const nodeName = node.getNormalizedName();
     const namespaceSchema = node.getNamespace();
-    // Obtenemos name y namespace
+    // Get the name and the namespace
     if (nodeName !== "schema" || namespaceSchema !== Schema_1.Schema.SCHEMA_NAMESPACE) {
-        throw new ValidationException_1.ValidationException(node.getLine(), "NOT_STXT_SCHEMA", `Se espera schema(${Schema_1.Schema.SCHEMA_NAMESPACE}) y es ${nodeName}(${namespaceSchema})`);
+        throw new ValidationException_1.ValidationException(node.getLine(), "NOT_STXT_SCHEMA", `Expected schema(${Schema_1.Schema.SCHEMA_NAMESPACE}) but got ${nodeName}(${namespaceSchema})`);
     }
-    // Obtenemos description
+    // Get the description
     const descrip = node.getChild("description")?.getText();
     const schema = new Schema_1.Schema(node.getValue(), node.getLine(), descrip);
-    // Para validar
-    const allNames = new Set(); // Para validar que existan los childs
-    // Obtenemos los nodos
+    // Used to check that every child is defined
+    const allNames = new Set();
+    // Get the nodes
     for (const n of node.getChildrenByName("node")) {
         const schNode = createFrom(n, schema.getNamespace());
         schema.addNodeDefinition(schNode);
         allNames.add(schNode.getNormalizedName());
     }
-    // Validamos que todos los nombres estén definidos
+    // Check that every name is defined
     for (const schNode of schema.getNodes().values()) {
         for (const schChild of schNode.getChildren().values()) {
-            // Sólo validamos del mismo namespace
+            // Only names of the same namespace are checked
             if (schChild.getNamespace() === schema.getNamespace()) {
-                // Ojo: en Java aquí se usa schChild.getNormalizedName(), pero ChildDefinition no lo expone.
-                // Para mantener el comportamiento, se recomienda añadir getNormalizedName() a ChildDefinition.
+                // Defensive leftover from the Java port: ChildDefinition does expose
+                // getNormalizedName(), so this check can never fail with the current class.
                 const childNorm = schChild.getNormalizedName?.();
                 if (!childNorm) {
                     throw new RuntimeException_1.RuntimeException("CHILD_DEFINITION_API_MISMATCH", "ChildDefinition.getNormalizedName() is missing in TypeScript version. Add it to ChildDefinition.");
@@ -46,6 +53,7 @@ function transformNodeToSchema(node) {
     }
     return schema;
 }
+/** Builds the definition of a node from a `Node:` entry of the schema document. */
 function createFrom(n, namespace) {
     const name = n.getValue();
     let type = "INLINE";
@@ -57,7 +65,7 @@ function createFrom(n, namespace) {
     const result = new NodeDefinition_1.NodeDefinition(name, type, n.getLine(), description);
     const children = n.getChild("children");
     if (children) {
-        // Error de schema 13.5: Children en un Node cuyo tipo no admite hijos
+        // Schema error 13.5: Children in a Node whose type does not admit children
         if (!TypeRegistry_1.TypeRegistry.admitsChildren(type)) {
             throw new ValidationException_1.ValidationException(children.getLine(), "CHILDREN_NOT_ALLOWED_FOR_TYPE", `Type ${type} does not allow children (node ${name})`);
         }
@@ -65,7 +73,7 @@ function createFrom(n, namespace) {
             putChildToSchemaNode(result, child, namespace);
         }
     }
-    // Miramos values
+    // Look at the values
     let valuesNodes = n.getChildrenByName("values");
     if (valuesNodes && valuesNodes.length > 0) {
         if (type !== "ENUM") {
@@ -79,29 +87,31 @@ function createFrom(n, namespace) {
         for (const v of values) {
             result.addValue(v.getValue(), v.getLine());
         }
-        // Para la comprobación final de ENUM
+        // For the final ENUM check
         valuesNodes = values;
     }
-    // Miramos enum
+    // Look at the enum
     if (type === "ENUM" && (!valuesNodes || valuesNodes.length === 0)) {
         throw new ValidationException_1.ValidationException(n.getLine(), "VALUES_EMPTY_FOR_ENUM", "ENUM Type must include values");
     }
     return result;
 }
+/** Adds to a node definition the expected child a `Child:` entry declares. */
 function putChildToSchemaNode(schemaNode, child, defNamespace) {
-    // Obtenemos name y namespace
+    // Get the name and the namespace
     const ns = NameNamespaceParser_1.NameNamespaceParser.parse(child.getValue(), defNamespace, child.getLine(), child.getValue());
     const name = ns.getName();
     const namespace = ns.getNamespace();
     const min = getInteger(child, "min");
     const max = getInteger(child, "max");
-    // Cardinalidad inválida si Min > Max (STXT-SCHEMA-SPEC 10 y 13.7)
+    // Invalid cardinality when Min > Max (STXT-SCHEMA-SPEC 10 and 13.7)
     if (min !== null && max !== null && min > max) {
         throw new ValidationException_1.ValidationException(child.getLine(), "MIN_GREATER_THAN_MAX", `Min ${min} greater than Max ${max}`);
     }
     const schemaChild = new ChildDefinition_1.ChildDefinition(name, namespace, min, max, child.getLine());
     schemaNode.addChildDefinition(schemaChild);
 }
+/** Reads an integer child (`Min`, `Max`) of a node, or null when it is not there. */
 function getInteger(node, name) {
     const n = node.getChild(name);
     if (!n) {

package/out/schema/SchemaProvider.d.ts

@@ -1,4 +1,11 @@
 import { Schema } from "./Schema";
+/** Resolves the {@link Schema} that applies to a namespace. Composable implementations (memory, meta-schema...). */
 export interface SchemaProvider {
+    /**
+     * Resolves the schema that applies to a namespace.
+     *
+     * @param namespace namespace whose schema is wanted.
+     * @returns the schema of the namespace, or null/undefined if there is none for that namespace.
+     */
     getSchema(namespace: string): Schema | null | undefined;
 }

package/out/schema/SchemaProviderMemory.d.ts

@@ -1,11 +1,38 @@
 import { Schema } from "./Schema";
 import { SchemaProvider } from "./SchemaProvider";
+/**
+ * In-memory {@link SchemaProvider}: it keeps the schemas added with {@link SchemaProviderMemory.addSchema}
+ * indexed by namespace, and falls back to a parent provider (the meta-schema by default) for the
+ * namespaces it does not know.
+ */
 export declare class SchemaProviderMemory implements SchemaProvider {
     private readonly parentSchema;
+    /**
+     * Creates an empty provider.
+     *
+     * @param parent provider to fall back to when a namespace is not registered here; the
+     *        meta-schema provider when omitted.
+     */
     constructor(parent?: SchemaProvider | null | undefined);
     protected readonly schemas: Map<string, Schema>;
+    /**
+     * Resolves the schema that applies to a namespace, delegating to the parent provider when it
+     * is not registered here.
+     *
+     * @param namespace namespace whose schema is wanted.
+     * @returns the schema of the namespace, or null/undefined if neither this provider nor its parent has one.
+     */
     getSchema(namespace: string): Schema | undefined | null;
+    /**
+     * Parses a schema document, validates it against the meta-schema and registers it under its
+     * own namespace.
+     *
+     * @param txt text of the `@stxt.schema` document.
+     * @throws ParseException or ValidationException if the document is not a valid schema.
+     */
     addSchema(txt: string): void;
+    /** Removes every schema registered in this provider (the parent one is left untouched). */
     clear(): void;
+    /** @returns every schema registered in this provider, in registration order. */
     getAllSchemas(): ReadonlyArray<Schema>;
 }

package/out/schema/SchemaProviderMemory.js

@@ -6,7 +6,18 @@ const StringUtils_1 = require("../core/StringUtils");
 const SchemaParser_1 = require("./SchemaParser");
 const SchemaProviderMeta_1 = require("./SchemaProviderMeta");
 const SchemaValidator_1 = require("./SchemaValidator");
+/**
+ * In-memory {@link SchemaProvider}: it keeps the schemas added with {@link SchemaProviderMemory.addSchema}
+ * indexed by namespace, and falls back to a parent provider (the meta-schema by default) for the
+ * namespaces it does not know.
+ */
 class SchemaProviderMemory {
+    /**
+     * Creates an empty provider.
+     *
+     * @param parent provider to fall back to when a namespace is not registered here; the
+     *        meta-schema provider when omitted.
+     */
     constructor(parent) {
         this.schemas = new Map();
         if (!parent) {
@@ -16,6 +27,13 @@ class SchemaProviderMemory {
             this.parentSchema = parent;
         }
     }
+    /**
+     * Resolves the schema that applies to a namespace, delegating to the parent provider when it
+     * is not registered here.
+     *
+     * @param namespace namespace whose schema is wanted.
+     * @returns the schema of the namespace, or null/undefined if neither this provider nor its parent has one.
+     */
     getSchema(namespace) {
         const key = StringUtils_1.StringUtils.lowerCase(namespace);
         let result = this.schemas.get(key);
@@ -24,6 +42,13 @@ class SchemaProviderMemory {
         }
         return result;
     }
+    /**
+     * Parses a schema document, validates it against the meta-schema and registers it under its
+     * own namespace.
+     *
+     * @param txt text of the `@stxt.schema` document.
+     * @throws ParseException or ValidationException if the document is not a valid schema.
+     */
     addSchema(txt) {
         const parser = new Parser_1.Parser();
         const node = parser.parse(txt)[0];
@@ -33,9 +58,11 @@ class SchemaProviderMemory {
         const key = schema.getNamespace();
         this.schemas.set(key, schema);
     }
+    /** Removes every schema registered in this provider (the parent one is left untouched). */
     clear() {
         this.schemas.clear();
     }
+    /** @returns every schema registered in this provider, in registration order. */
     getAllSchemas() {
         return Array.from(this.schemas.values());
     }

package/out/schema/SchemaProviderMeta.d.ts

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

package/out/schema/SchemaProviderMeta.js

@@ -6,7 +6,16 @@ const Parser_1 = require("../core/Parser");
 const ValidationException_1 = require("../exceptions/ValidationException");
 const RuntimeException_1 = require("../exceptions/RuntimeException");
 const SchemaParser_1 = require("./SchemaParser");
+/**
+ * {@link SchemaProvider} that defines in code the meta-schema of the schema language itself
+ * (`@stxt.schema`), so that a loaded schema can validate itself.
+ */
 class SchemaProviderMeta {
+    /**
+     * Parses the meta-schema and keeps it ready to be served.
+     *
+     * @throws ValidationException with code `META_SCHEMA_INVALID` if the meta-schema does not produce exactly one document.
+     */
     constructor() {
         const parser = new Parser_1.Parser();
         const nodes = parser.parse(SchemaProviderMeta.META_TEXT);
@@ -15,6 +24,13 @@ class SchemaProviderMeta {
         }
         this.meta = (0, SchemaParser_1.transformNodeToSchema)(nodes[0]);
     }
+    /**
+     * Serves the meta-schema of the schema language.
+     *
+     * @param namespace namespace whose schema is wanted; only `@stxt.schema` is served.
+     * @returns the meta-schema of the schema language.
+     * @throws RuntimeException with code `RESOURCE_NOT_FOUND` if any other namespace is asked for.
+     */
     getSchema(namespace) {
         if (namespace !== Schema_1.Schema.SCHEMA_NAMESPACE) {
             throw new RuntimeException_1.RuntimeException("RESOURCE_NOT_FOUND", `Not found '${namespace}' in namespace: ${Schema_1.Schema.SCHEMA_NAMESPACE}`);

package/out/schema/SchemaValidator.d.ts

@@ -3,11 +3,31 @@ import { ValidationException } from "../exceptions/ValidationException";
 import { Validator } from "../processors/Validator";
 import { SchemaProvider } from "./SchemaProvider";
 import { Schema } from "./Schema";
+/** {@link Validator} that, for each node, resolves its {@link Schema} through a {@link SchemaProvider} and validates type and cardinality. */
 export declare class SchemaValidator implements Validator {
     private readonly schemaProvider;
     private readonly recursiveValidation;
+    /**
+     * Creates a validator that resolves schemas through the given provider.
+     *
+     * @param schemaProvider where to resolve the schema of each namespace from.
+     * @param recursive whether the children of each node are validated recursively too.
+     */
     constructor(schemaProvider: SchemaProvider, recursive?: boolean);
+    /**
+     * Validates a node against the schema of its namespace.
+     *
+     * @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[];
+    /**
+     * Validates a node against an already resolved schema: existence, value type and cardinalities of its children.
+     *
+     * @param node node to validate.
+     * @param schema schema to validate against.
+     * @returns the validation errors found, empty if the node is valid.
+     */
     validateAgainstSchema(node: Node, schema: Schema): ValidationException[];
     private static validateChildrenDeclared;
     private static validateValue;

package/out/schema/SchemaValidator.js

@@ -3,23 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SchemaValidator = void 0;
 const ValidationException_1 = require("../exceptions/ValidationException");
 const TypeRegistry_1 = require("./TypeRegistry");
+/** {@link Validator} that, for each node, resolves its {@link Schema} through a {@link SchemaProvider} and validates type and cardinality. */
 class SchemaValidator {
+    /**
+     * Creates a validator that resolves schemas through the given provider.
+     *
+     * @param schemaProvider where to resolve the schema of each namespace from.
+     * @param recursive whether the children of each node are validated recursively too.
+     */
     constructor(schemaProvider, recursive = false) {
         this.schemaProvider = schemaProvider;
         this.recursiveValidation = recursive;
     }
+    /**
+     * Validates a node against the schema of its namespace.
+     *
+     * @param node already closed node to validate.
+     * @returns the validation errors found, or an empty array if the node is valid.
+     */
     validate(node) {
         const errors = [];
-        // Obtenemos namespace
+        // Get the namespace
         const namespace = node.getNamespace();
         const schema = this.schemaProvider.getSchema(namespace);
         if (!schema) {
             errors.push(new ValidationException_1.ValidationException(node.getLine(), "SCHEMA_NOT_FOUND", `Not found schema: ${namespace}`));
             return errors;
         }
-        // Validamos nodo
+        // Validate the node
         errors.push(...this.validateAgainstSchema(node, schema));
-        // Validamos children
+        // Validate the children
         if (this.recursiveValidation) {
             for (const childNode of node.getChildren()) {
                 errors.push(...this.validate(childNode));
@@ -27,6 +40,13 @@ class SchemaValidator {
         }
         return errors;
     }
+    /**
+     * Validates a node against an already resolved schema: existence, value type and cardinalities of its children.
+     *
+     * @param node node to validate.
+     * @param schema schema to validate against.
+     * @returns the validation errors found, empty if the node is valid.
+     */
     validateAgainstSchema(node, schema) {
         const errors = [];
         const schemaNode = schema.getNodeDefinition(node.getNormalizedName());
@@ -40,8 +60,8 @@ class SchemaValidator {
         errors.push(...SchemaValidator.validateCount(schemaNode, node));
         return errors;
     }
-    // Modelo de contenido cerrado (STXT-SCHEMA-SPEC, sección 6): solo se permiten
-    // los hijos directos declarados en la definición del padre; sin Children, cierre total
+    // Closed content model (STXT-SCHEMA-SPEC, section 6): only the direct children declared
+    // in the definition of the parent are allowed; with no Children, nothing is
     static validateChildrenDeclared(nodeDef, node) {
         const errors = [];
         for (const child of node.getChildren()) {
@@ -101,9 +121,9 @@ class SchemaValidator {
             errors.push(new ValidationException_1.ValidationException(node.getLine(), "INVALID_NUMBER", `${childCount} nodes of '${childDef.getQualifiedName()}' and min is ${min}`));
         }
         if (max !== null && childCount > max) {
-            // Error en el parent
+            // Error on the parent
             errors.push(new ValidationException_1.ValidationException(node.getLine(), "INVALID_NUMBER", `${childCount} nodes of '${childDef.getQualifiedName()}' and max is ${max}`));
-            // Error en cada nodo hijo que excede el máximo permitido
+            // Error on each child node beyond the allowed maximum
             for (const child of children) {
                 errors.push(new ValidationException_1.ValidationException(child.getLine(), "INVALID_NUMBER", `Too many '${childDef.getQualifiedName()}' nodes: found ${childCount}, max is ${max}`));
             }

package/out/schema/Type.d.ts

@@ -1,6 +1,15 @@
 import { Node } from "../core/Node";
 import { NodeDefinition } from "./NodeDefinition";
+/** Value type of a node (TEXT, INTEGER, URL...). Each type lives in `src/schema/type` as a singleton. */
 export interface Type {
+    /**
+     * Validates the value of a node against this type.
+     *
+     * @param nodeDef definition of the node in the schema.
+     * @param node node to validate.
+     * @throws ValidationException if the value of the node does not match the type.
+     */
     validate(nodeDef: NodeDefinition, node: Node): void;
+    /** @returns the name of the type, as used in the schemas (e.g. `"TEXT"`). */
     getName(): string;
 }

package/out/schema/TypeRegistry.d.ts

@@ -1,8 +1,21 @@
 import { Type } from "./Type";
+/** Static registry of the STXT value types, indexed by name. Adding a new type: a new {@link Type} + `register(...)` here. */
 export declare class TypeRegistry {
     private static readonly REGISTRY;
     private static readonly _init;
+    /**
+     * Tells whether nodes of a type may have children.
+     *
+     * @param nodeType name of the type.
+     * @returns true if nodes of this type may have children (only INLINE and GROUP).
+     */
     static admitsChildren(nodeType: string): boolean;
+    /**
+     * Looks up a registered type by name.
+     *
+     * @param nodeType name of the type to look for.
+     * @returns the {@link Type} registered under that name, or undefined if it does not exist.
+     */
     static get(nodeType: string): Type | undefined;
     private static register;
 }