The TypeScript library

This page is the usage guide of the library: parsing, walking and building trees, validating against schemas and templates, resolving which grammar applies to a document, obtaining its canonical JSON and writing STXT back out. Everything shown here comes from a single entry point, with no internal sub-paths.

Installation

npm install @stxt-lang/core

The package ships as CommonJS with type declarations, so it works the same from TypeScript, from require and from ES modules (import { Parser } from '@stxt-lang/core'). It has no runtime dependencies and touches neither the file system nor the environment —those are injected, as shown under Resolution—, so it runs equally in Node and in the browser: the playground is this very library bundled for the client. Its version, and that of the CLI that carries it, show up in stxt --version; the JSDoc travels in the .d.ts, so the editor shows the documentation of each method on hover.

Parsing

Parser has two entry points. parseResult(text) collects every error and also returns the nodes it managed to build; parse(text) throws a ParseException on the first one and returns Node[] when there is none. The former is what an editor or a validator wants; the latter, a program for which an invalid document is simply an exception.

import { Parser, ParseResult, ParseException } from '@stxt-lang/core';

const parser = new Parser();
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 roots = result.getNodes();   // the root nodes, in order; there may be several

// The "throw on first error" form
try {
    const nodes = parser.parse(text);
} catch (e) {
    if (e instanceof ParseException) console.error(e.line, e.code, e.message);
}

Every error is a ParseException with three fields: line (the line of the document, starting at 1), code (stable, upper-case: INVALID_LINE, MIXED_INDENTATION, INDENTATION_LEVEL_NOT_VALID…) and message. Grammar errors are ValidationException, a subclass with the same fields, so a single loop walks both and instanceof tells the severity apart. A document with a syntax error may still return nodes: the parser recovers and carries on, so that an editor can underline everything that is wrong at once.

The tree

Node is an abstract class with exactly two forms, and each one owns only what is really its own:

What they share lives in Node: getName() and getCanonicalName() (the canonical name of STXT-SPEC: lower-case, NFC, unified separators), getDeclaredNamespace() (what the node writes between parentheses, or "") and getNamespace() (the effective one, inherited through the chain of parents), getLine(), getLevel() (derived from the depth), getParent() (always an InlineNode, or null at the root), detach() and getText() —the value of an inline node or the joined lines of a block—. Walking a tree means asking for the form with instanceof, which in TypeScript also narrows the type, the same way the canonical tree of STXT-TREE-SPEC has children only for inline nodes and lines only for blocks.

With the document of the tutorial, a book record:

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Published: 2025-10-01
	Chapter: Introducción
		Content >>
			Conceptos básicos y objetivos del libro.

import { Parser, InlineNode, TextNode, Node } from '@stxt-lang/core';

const book = new Parser().parseResult(text).getNodes()[0];

book.getName();          // "Book"
book.getCanonicalName(); // "book"
book.getNamespace();     // "com.acme.book"
book.getLine();          // 1

if (book instanceof InlineNode) {
    book.getChild('Title')?.getText();                 // "Arquitectura de software moderna"
    book.getChild('title')?.getName();                 // "Title": lookups go by canonical name
    book.getChild('Publisher');                        // null: not there

    const authors = book.getChild('Authors') as InlineNode;
    authors.getChildrenByName('Author').map(a => a.getText());   // ["María Pérez", "Juan García"]
    authors.getDeclaredNamespace();                    // "": it declares none…
    authors.getNamespace();                            // "com.acme.book": …it inherits it

    const chapter = book.getChild('Chapter') as InlineNode;
    const content = chapter.getChild('Content');
    if (content instanceof TextNode) {
        content.getTextLines();   // ["Conceptos básicos y objetivos del libro."]
        content.getLevel();       // 2
        content.getParent() === chapter;   // true
    }
}

// A generic walk
function walk(node: Node, depth = 0): void {
    console.log('  '.repeat(depth) + node.getName());
    if (node instanceof InlineNode) {
        for (const child of node.getChildren()) walk(child, depth + 1);
    }
}

Building and editing

Trees are mutable and keep their own integrity: every node knows its parent, addChild links both ends and refuses a node that already has one (NODE_ALREADY_ATTACHED) or that is an ancestor (NODE_CYCLE); removeChild and detach() undo it. Levels are derived from the chain of parents, and the line is only set by the parser. In the factories with two strings, the second one is always the content (value or text); the namespace only appears in the three-argument form.

import { InlineNode, TextNode } from '@stxt-lang/core';

const email = new InlineNode('Email', 'com.example.mail', 'Weekly report');
email.addInlineNode('From', 'Ana García <[email protected]>');
const to = email.addInlineNode('To');
to.addInlineNode('Address', '[email protected]');
const body = email.addTextNode('Body', 'Hi Bob,\n\nSee attached.');

body.getParent() === email;   // true
body.getLevel();              // 1
to.getNamespace();            // "com.example.mail", inherited

// Reorder: "To" first
to.detach();
email.addChild(to, 0);

// Edit
email.setNamespace('com.example.docs');   // the whole inheriting subtree follows
body.setText('Hi Bob,\n\nSee the new attachment.');

Validating against a schema or a template

Grammars are STXT documents in the reserved namespaces @stxt.schema and @stxt.template; the template is the short authoring form and compiles to a schema when loaded. UnifiedSchemaProvider loads either kind with addFile(text): it parses, validates against the corresponding meta-schema and registers the schema by namespace. Validation is a Validator registered on the Parser that runs on each node as it is closed; ConditionalValidator wraps it so that only nodes with a namespace are validated, which is the rule of the language: a document without a namespace is not wrong, it just cannot be validated.

Template (@stxt.template): com.acme.book
	Structure >>
		Book:
			Title: (1)
			Authors: (1)
				Author: (+)
			ISBN: (1)
			Publisher: (?)
			Published: (?) DATE
			Summary: (?) TEXT
			Chapter: (+)
				Content: (?) TEXT
	Description >>
		Book: Template for publisher book records

import {
    Parser, UnifiedSchemaProvider, SchemaValidator, ConditionalValidator,
    ValidationException,
} from '@stxt-lang/core';

const provider = new UnifiedSchemaProvider();
provider.addFile(templateText);            // throws if the template does not validate against its meta-schema

const parser = new Parser();
parser.registerValidator(new ConditionalValidator(new SchemaValidator(provider)));

const result = parser.parseResult(documentText);
for (const error of result.getErrors()) {
    const kind = error instanceof ValidationException ? 'schema' : 'syntax';
    console.log(`${kind} line ${error.line} [${error.code}]: ${error.message}`);
}

With a book that lacks its ISBN and whose date is not YYYY-MM-DD, the loop prints exactly what stxt validate would print:

schema line 5 [INVALID_VALUE]: Published: Invalid date (1 de octubre de 2025)
schema line 1 [INVALID_NUMBER]: 0 nodes of 'com.acme.book:isbn' and min is 1

Rules worth knowing:

• A cardinality error is reported on the line of the parent, which is the one with zero ISBN.
• If the document uses a namespace the provider does not know, each node produces a SCHEMA_NOT_FOUND; the provider never throws for a missing namespace (getSchema() returns null).
• Nodes without a namespace are not validated (thanks to ConditionalValidator); a document that is itself a definition is always validated against its meta-schema.
• addFile accepts files with several definitions, and getAllSchemas() lists them; clear() empties the provider.
• The available value types are those of STXT-SCHEMA-SPEC: INLINE, BLOCK, TEXT, MARKDOWN, BOOLEAN, INTEGER, NATURAL, NUMBER, DATE, TIME, TIMESTAMP, UUID, EMAIL, URL, HEXADECIMAL, BINARY, BASE64, GROUP and ENUM.

The compiled schema can be inspected: provider.getSchema(ns) returns a Schema with getNamespace() and getNodeDefinition(name); each NodeDefinition has getType(), getChildren() (a map of ChildDefinition with getMin() / getMax()), getValues() for an ENUM and getDescription(). It is what the extension uses for completion and hover.

Resolution: which grammar applies to a document

UnifiedSchemaProvider expects you to hand it the grammar text. Resolution answers the previous question: given this document, which definitions apply to it? DiscoveryResolver is the reference implementation of STXT-DISCOVERY-SPEC —the .stxt/ directories of the document and of all its ancestors, then ~/.stxt and /etc/stxt, per-namespace precedence, STXT_PATH replacing the chain—, and it is the same one the CLI and the extension use, so all three agree by construction.

The resolver touches neither the file system nor the environment by itself: a DiscoveryFileSystem and a DiscoveryEnvironment are injected. That is what lets the same logic run over Node's fs, over an editor's virtual file system or over an in-memory tree in a test. The Node adapters fit in twenty lines:

import * as fs from 'fs/promises';
import * as os from 'os';
import * as path from 'path';
import { DiscoveryEntry, DiscoveryEnvironment, DiscoveryFileSystem } from '@stxt-lang/core';

class NodeFileSystem implements DiscoveryFileSystem {
    async isDirectory(p: string): Promise<boolean> {
        try { return (await fs.stat(p)).isDirectory(); } catch { return false; }
    }
    async listDirectory(p: string): Promise<DiscoveryEntry[]> {
        const entries = await fs.readdir(p, { withFileTypes: true });
        return entries.map(e => ({ path: path.join(p, e.name), name: e.name, isDirectory: e.isDirectory() }));
    }
    readFile(p: string): Promise<string> { return fs.readFile(p, 'utf-8'); }
    parentOf(p: string): string | null {
        const parent = path.dirname(p);
        return parent === p ? null : parent;   // null at the file-system root
    }
    join(p: string, name: string): string { return path.join(p, name); }
}

class NodeEnvironment implements DiscoveryEnvironment {
    getStxtPath(): string[] | null {
        const value = process.env.STXT_PATH;
        // null (not defined) and [] (defined but empty) mean different things
        return value === undefined ? null : value.split(path.delimiter).filter(e => e !== '');
    }
    getUserLevelDir(): string | null { return path.join(os.homedir(), '.stxt'); }
    getSystemLevelDir(): string | null { return '/etc/stxt'; }
}

With those in place, resolving a document and validating it are two steps, because DiscoveryResult implements SchemaProvider and goes straight into the validator. The chain is per document: pass the directory it lives in (null for standard input or an unsaved buffer, which starts the chain at the user level).

import { Parser, SchemaValidator, ConditionalValidator, DiscoveryResolver } from '@stxt-lang/core';

const resolver = new DiscoveryResolver(new NodeFileSystem(), new NodeEnvironment());
const discovery = await resolver.resolve('/home/ana/libros/docs');

discovery.getChain();        // ["/home/ana/libros/.stxt"]  (every ancestor, nearest first)

// Resolution errors are collected, never thrown: report them and carry on
for (const error of discovery.getErrors()) {
    console.error(`[${error.code}] ${error.file}: ${error.message}`);
}

const parser = new Parser();
parser.registerValidator(new ConditionalValidator(new SchemaValidator(discovery)));
const result = parser.parseResult(documentText);

DiscoveryResult also tells you where each grammar came from, which is what an editor needs for "go to definition" or a diagnostic that explains itself:

const definition = discovery.getDefinition('com.acme.book');
definition?.file;       // "/home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt"
definition?.levelDir;   // "/home/ana/libros/.stxt"  (the level that won)
definition?.schema;     // the compiled Schema

discovery.getActiveDefinitions();   // one per namespace, precedence applied
discovery.getAllSchemas();          // just the schemas of the above

Levels are cached by directory: resolving many documents that share ancestors reads each .stxt/ once. Call resolver.clearCache() when the definition files may have changed —from a file watcher, for instance—. The resolution error codes are DISCOVERY_DUPLICATE_NAMESPACE, DISCOVERY_NOT_A_DEFINITION, DISCOVERY_NOT_PARSEABLE and DISCOVERY_INVALID_DEFINITION; DiscoveryError is a data class (code, file, message, namespace), not an exception, because the spec wants a bad definition reported without stopping the load of the rest.

The canonical tree as JSON

toCanonicalTree(nodes) turns the root nodes into the JSON value of STXT-TREE-SPEC —the same one stxt describe emits— and toCanonicalJson(nodes) serialises it with two-space indentation. It is an explicit function, not JSON.stringify over the node: it emits only the normative fields, children for inline nodes and lines for blocks, with no positions or comments. The types CanonicalDocument, CanonicalNode, CanonicalInlineNode and CanonicalBlockNode describe the result.

import { Parser, toCanonicalTree, toCanonicalJson, CanonicalDocument } from '@stxt-lang/core';

const nodes = new Parser().parseResult(text).getNodes();
const tree: CanonicalDocument = toCanonicalTree(nodes);
tree[0].name;    // "Book"
tree[0].form;    // "inline"

process.stdout.write(toCanonicalJson(nodes));

Writing STXT

NodeWriter makes the trip back: it serialises a node, or a list of documents, to STXT text in canonical form, with IndentStyle.TABS (default) or IndentStyle.SPACES_4. It writes the namespace where the node declares it, not where it differs from the parent: faithful to the source. Since it starts from the logical tree, a text that goes through parse and NodeWriter comes out without comments or blank lines outside blocks —that is what stxt format --clean does—; the reformatting that keeps them is the job of the CLI and the extension, not of the library.

import { NodeWriter, IndentStyle } from '@stxt-lang/core';

const one = NodeWriter.toSTXT(email);                                   // one node, with tabs
const all = NodeWriter.toSTXTDocs(result.getNodes(), IndentStyle.SPACES_4);   // a whole document

The email built above, written with toSTXT:

Email (com.example.mail): Weekly report
	To:
		Address: [email protected]
	From: Ana García <[email protected]>
	Body >>
		Hi Bob,

		See attached.

Observing the parse

Observer receives streaming callbacks while the document is parsed: onCreate(node, line) when a node is opened —already with its parent, effective namespace and level—, onFinish(node) when it is closed, onComment(lineNumber, line) and onTextLine(node, lineNumber, lineString, line) for each line of a block. It is the basis of the extension's semantic colouring and of the line→node map of the CLI formatter.

import { Parser, Observer, Node, TextNode, 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: TextNode, lineNumber: number, lineString: string, line: Line): void { /* … */ }
}

const parser = new Parser();
parser.registerObserver(new LoggingObserver());
parser.parseResult(text);

The API surface

Everything importable, and only this; nothing else in the package is a contract:

Until 1.0, a minor release can change the in-memory API (0.7.0 redid the node model), but never the language or the canonical tree: a document that parses and validates today parses and validates the same tomorrow. The release notes of each version are in the repository, which is also where parser and validation errors are reported —including those seen through the CLI, the extension or the playground—.