@flexiberry/berrycore

The official compiler, runtime engine, lexer, parser, and formatter for Berry DSL—an elegant, indentation-aware scripting language designed to orchestrate API workflows, test automation suites, and task execution plans.

@flexiberry/berrycore is a lightweight, zero-dependency engine built in TypeScript that processes clean .berry scripts through a complete language engineering pipeline: parsing them into a strongly-typed Abstract Syntax Tree (AST), formatting them back to source code, and executing them in isolated, event-driven runtime environments with full support for variables, HTTP requests, steps, and control-flow.

✨ Overview

BerryCore is a lightweight, zero-dependency compiler architecture built entirely in TypeScript. It provides the foundational tools required to interpret the Berry DSL (Domain Specific Language), a custom scripting language explicitly designed to orchestrate API flows, manage testing environments, and execute complex task runners.

This package exposes the complete language engineering pipeline:

1. LexerEngine - Scans characters and generates grammar-aware tokens.
2. AstEngine - Parses tokens into a strongly-typed Abstract Syntax Tree (AST).
3. Interpreter - The runtime execution engine that evaluates the AST, manages isolated environment scopes, and fires runtime events.
4. Formatter - Converts the AST back into cleanly formatted .berry script.

📦 Installation

Install @flexiberry/berrycore as a core dependency for your own test runners, CI pipelines, or editor integrations:

npm install @flexiberry/berrycore

🛠️ Programmatic Usage

The core engine is heavily decoupled, allowing you to use just the parts you need—whether you are building a language server, an IDE, or a CLI.

📖 Language Syntax Reference

The Berry DSL was designed to be easily readable, removing complex syntax clutter in favor of a clean, indentation-aware syntax.

1. Environments (Env)

Defines the deployment environments available for the script.

Env UAT, SIT, PROD

2. Variables (Var)

Isolated memory scopes for storing state. Variables are initialized directly in the runtime environment.

Var UserData
- id: 101
- name: "John Doe"

3. API Declarations (Api)

Defines HTTP endpoints with strict schema definitions.

Api POST #CreateUser "Creates a new user"
Url 'https://api.example.com/users'
Body JSON
`{
  "name": "{{UserData.name}}"
}`
Header
- Authorization: 'Bearer {{token}}'

4. Tasks and Steps (Task / Step)

The execution blocks where the interpreter orchestrates logic.

Task "User Onboarding"
  Step "Register New User"
    Call #CreateUser
    Capture
    - token: "response.data.token"
    Check
    - status == 201

5. Control Flow (Jump, Break)

The interpreter supports localized control flow within Tasks.

Break if status == 400
Jump To @2 If status == 401

🧠 Architectural Principles

Following standard language engineering practices, berrycore adheres strictly to:

• Separation of Concerns: The parser never executes code. The interpreter never scans tokens.
• Type Safety: All AST nodes are backed by strict TypeScript interfaces (BaseNode, TaskBlockNode, etc.).
• Immutability: The AST generated by AstEngine is treated as a pure, immutable data layer.
• Event-Driven Execution: The Interpreter engine acts as an event emitter, allowing external UI layers (like CLI spinners or web dashboards) to hook directly into the runtime state.

🤝 Contributing

This package is part of the FlexiBerry monorepo. We welcome contributions to grammar definitions, execution optimizations, and AST tooling.

Please see the root CONTRIBUTING.md for guidelines, or join our community on the GitHub Discussions Page.

📄 License

MIT © FlexiBerry.dev