API Reference

Programmatic API for working with Aexol specifications in TypeScript/JavaScript.

Installation

npm install @aexol/parser

import { Parser, Validator } from "@aexol/parser";

Parser API

Parse Aexol source code into an Abstract Syntax Tree (AST).

import { Parser } from "@aexol/parser";

const source = `
type User {
  id: string
  name: string
  email: string
}

visitor Admin {
  "manage users"
  "view reports"
}
`;

const parser = new Parser(source);
const ast = parser.parse();

console.log(ast);
// { types: [...], visitors: [...], agents: [], workflows: [], roles: [] }

Parser Options

interface ParserOptions {
  includePositions?: boolean;    // Include line/column info in AST
  recoverFromErrors?: boolean;   // Continue parsing after errors
}

const parser = new Parser(source, {
  includePositions: true,
  recoverFromErrors: true,
});

AST Structure

interface AexolAST {
  types: TypeDefinition[];
  visitors: VisitorDefinition[];
  agents: AgentDefinition[];
  workflows: WorkflowDefinition[];
  roles: RoleDefinition[];
  enums: EnumDefinition[];
}

interface TypeDefinition {
  name: string;
  fields: FieldDefinition[];
  position?: Position;
}

interface FieldDefinition {
  name: string;
  type: string;
  isArray: boolean;
  isOptional: boolean;
}

interface VisitorDefinition {
  name?: string;                  // Omitted for anonymous visitor
  capabilities: Capability[];
}

Error Handling

try {
  const ast = parser.parse();
} catch (error) {
  if (error instanceof SyntaxError) {
    console.error("Syntax error:", error.message);
    console.error("Line:", error.line, "Column:", error.column);
  }
}

Validator API

Validate Aexol specifications for semantic correctness.

import { Parser, Validator } from "@aexol/parser";

const parser = new Parser(source);
const ast = parser.parse();

const validator = new Validator(ast);
const result = validator.validate();

if (!result.isValid) {
  console.error("Validation errors:", result.errors);
}

Validation Result

interface ValidationResult {
  isValid: boolean;
  errors: Diagnostic[];
  warnings: Diagnostic[];
  infos: Diagnostic[];
}

interface Diagnostic {
  severity: "error" | "warning" | "info";
  message: string;
  line?: number;
  column?: number;
  code?: string;
}

Validation Rules

• Unique names for types, visitors, agents, roles
• At most one anonymous visitor
• All type references must resolve
• Workflow transitions must reference defined states
• Valid capability verbs
• Circular reference detection

CLI Usage

# Parse and validate
aexol parse app.aexol
aexol validate app.aexol

# Generate documentation
aexol docs app.aexol -o README.md

# Analyze structure
aexol analyze app.aexol

Complete Example

import { Parser, Validator } from "@aexol/parser";

async function processAexol(source: string) {
  // 1. Parse
  const parser = new Parser(source);
  const ast = parser.parse();

  // 2. Validate
  const validator = new Validator(ast);
  const validation = validator.validate();

  if (!validation.isValid) {
    console.error("Validation errors:", validation.errors);
    return;
  }

  console.log("Types:", ast.types.length);
  console.log("Visitors:", ast.visitors.length);
  console.log("Workflows:", ast.workflows.length);
  console.log("✓ Valid specification!");
}

const source = `
type User {
  id: string
  name: string
  email: string
}
`;

await processAexol(source);

Package Exports

The @aexol/parser package exports:

See Also

• Language Reference — Full syntax guide
• CLI & Tooling — Command-line tools
• Workflows & Recipes — Workflow patterns