2.47.1 • Published yesterdayCLI

@almadar/orb

Licence

BSL-1.1

Version

2.47.1

Deps

Size

1.7 MB

Vulns

Weekly

Stars

Install scriptsThis package runs scripts during installation (preinstall/install/postinstall)

Summary Dependency Versions

Orb

فيزياء البرمجيات — The Physics of Software

Just as physics lets us predict how the physical world behaves, Orb lets us predict how software systems behave.

Orb (المدار) is a world modeling language — a semantic layer above programming languages that describes how systems work, not just what they do. Write a formal world model once, and AI agents generate valid implementations, the compiler validates correctness deterministically, and you can observe every possible state before a single line of code runs.

World Model (.orb) → Compiler → Valid System
        ▲                              │
        │                              ▼
   Natural Language              Observable
   (Human or AI)                 Behavior

Built for the AI age: Token-efficient representations that agents can generate and reason about. Deterministic validation that catches errors before runtime. Observable state spaces that let you prove correctness.

Quick Start

# Install CLI globally
npm install -g @almadar/orb

# Create a new project
orb new my-app
cd my-app

# Install dependencies
npm install

# Start development server
orb dev

Core Philosophy

Model the World, Not Just the Code

Traditional programming languages tell computers what to do. Orb describes how things work:

Entities — What exists in your system (User, Order, Task)
Traits — How those things behave and change over time
Pages — How the world is observed and interacted with

This world model is a formal specification that both humans and AI can reason about.

The Orbital Formula

World Unit = Entity + Traits + Pages
System     = Σ(World Units)

Each orbital is a self-contained world model describing a domain of your system. Compose them to build complex, observable applications.

Observable by Design

Because Orb models behavior formally, you can:

Validate deterministically — The compiler proves your model is valid before runtime
Exhaustively test — Examine all possible states to ensure correctness
Generate efficiently — AI agents produce valid systems from natural language
Reason precisely — Both humans and machines understand the same model

Closed Circuit Pattern

Every interaction flows through a predictable path:

User Action → Event → State Machine → Effects → World Update → (loop)

No hidden state mutations. No side effects you can't trace. Observable causality throughout.

Architecture Overview

High-Level System Flow

Natural Language ──┐
(Human or AI)      │
                   │
Human-written ─────┼──► ┌─────────────────┐
.orb Schema        │    │  Builder IDE    │  Generates/Edits
                   │    │  (LLM Agent)    │  .orb schema
                   └──► └────────┬────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │ Rust Compiler   │  Parse → Validate → Resolve → Generate
                         │ (orbital-rust)  │
                         └────────┬────────┘
                                  │
                             ┌────┴────┐
                             ▼         ▼
                          TypeScript  Python
                             Shell     Shell
                          
                          (Rust shell coming soon)

Three Execution Models

Model	Use Case	Technology
TypeScript Runtime	Preview, development	`@almadar/runtime`
Rust Runtime	Standalone apps, CLI	`orbital-rust`
Compiled Code	Production deployment	Generated TS/Python (Rust coming soon)

entity Task [persistent: tasks] {
  id     : string!
  title  : string!
  status : string = "pending"
}

Entity Documentation

2. Traits (State Machines)

Define behavior with states, events, and transitions:

trait TaskBrowser -> Task [interaction] {
  state browsing {
    INIT -> browsing
      (fetch Task)
      (render-ui main { type: "entity-table", entity: "Task", fields: ["title", "status"] })
    CREATE -> creating
      (render-ui modal { type: "modal", isOpen: true, title: "New Task",
        children: [{ type: "form-section", entity: "Task", fields: ["title", "status"], mode: "create" }] })
  }
  state creating {
    SAVE -> browsing
      (persist create Task @payload.data)
      (render-ui modal null)
    CANCEL -> browsing
      (render-ui modal null)
  }
}

Trait Documentation | Closed Circuit

3. Patterns & UI

Patterns bridge schemas to UI components — declared inline in effects:

(render-ui main { type: "entity-table", entity: "Task", fields: ["title", "status"] })

Patterns Documentation

4. Standard Library

Reuse pre-built behaviors with uses:

orbital TaskOrbital {
  uses Browse from "std/behaviors/std-browse"

  entity Task [persistent: tasks] {
    id    : string!
    title : string!
  }

  trait TaskBrowse = Browse.traits.BrowseItemBrowse -> Task {}

  page "/tasks" -> TaskBrowse
}

Standard Library

Installation

CLI Installation

# npm (recommended)
npm install -g @almadar/orb

# Or use npx
npx @almadar/orb validate schema.orb

# macOS/Linux
curl -fsSL https://orb.almadar.io/install.sh | sh

# Windows PowerShell
irm https://orb.almadar.io/install.ps1 | iex

# Homebrew
brew install almadar-io/tap/orb

NPM Packages

# Core packages
npm install @almadar/core @almadar/validation @almadar/evaluator

# Standard library and operators
npm install @almadar/std @almadar/operators

# UI patterns and components
npm install @almadar/patterns @almadar/ui

# Runtime
npm install @almadar/runtime

Published Packages

The Orb language ecosystem is published to npm.

Core

Package	Description
`@almadar/core`	Core schema types and definitions
`@almadar/operators`	S-expression operator definitions
`@almadar/evaluator`	S-expression evaluator for guards and effects
`@almadar/std`	Standard library operators (math, string, array, etc.)
`@almadar/validation`	Schema validation rules
`@almadar/patterns`	Pattern registry and component mappings

Runtime & UI

Package	Description
`@almadar/runtime`	Interpreted runtime for orbital applications
`@almadar/ui`	React UI components, hooks, and providers
`@almadar/mobile`	React Native UI components

Tooling

Package	Description
`@almadar/orb`	Orb CLI (validate, compile, dev)
`@almadar/extensions`	Editor extensions (VSCode, Zed)
`@almadar/eslint-plugin`	ESLint rules for Almadar component architecture

Development Workflow

The Fix Priority Rule

When something breaks, follow this order:

Fix .lolo first — 99% of issues are in the lolo source
Update shell components — Component bugs
Modify compiler — LAST RESORT (ask first!)

Typical Flow

1. Edit .orb (write in .lolo syntax)
        ↓
2. Validate: orb validate app.orb
        ↓
3. Compile: orb compile app.orb --shell typescript
        ↓
4. Test generated code
        ↓
5. Iterate

Developer Guide

Documentation

Full documentation is available at orb.almadar.io/docs:

Core Concepts

Document	Purpose
Entities	Data models, field types, persistence
Traits	State machines, guards, effects
Pages	Routes, URL patterns, trait bindings
Closed Circuit	Event flow pattern
Patterns	UI patterns and components
Standard Library	Reusable behaviors and operators

Tutorials

Level	Topic
Beginner	Your First Schema
Intermediate	UI Patterns, Guards
Advanced	Full App

Full Documentation

Visit orb.almadar.io/docs for complete documentation.

Website Development

This repository also contains the orb.almadar.io documentation website, built with Docusaurus.

npm install
npm start          # Start dev server on port 3000
npm run build      # Production build
npm run serve      # Serve production build locally