Zenith DSL Documentation

# Launch in web browser (http://localhost:3000):
zenith studio schema.zen

# Launch in dedicated native desktop application mode:
zenith studio schema.zen --desktop

config {
    app: "NexusCommerce"
    package: "com.nexus.commerce"
    basePath: "/api/v1"
    port: 8080
    database: postgres
    auth: jwt
    // Option 2 (Clean): Use a simple passphrase + duration unit (or omit both for auto 256-bit key & 24h default)
    jwtSecret: "nexus-commerce-secret"
    jwtExpiration: 24h
    // Option 1 (Explicit): Full 64-char hex secret + raw milliseconds is also supported
    storage: minio
    flyway: true
    swagger: true
    rateLimit: "500/minute"  // Global baseline token-bucket rate limit (HTTP 429 on exhaustion)
}

model CustomerProfile {
    id: UUID @id @auto
    fullName: String(min = 2, max = 100)
    bio: String? @text                    // Optional unbounded text
    rewardPoints: Int = 0                  // Defaults to 0
    balance: Decimal(precision = 10, scale = 2) @positive
    isVerified: Boolean = false
    birthDate: Date?
    lastLogin: DateTime?
}

model Order {
    id: UUID @id @auto
    orderNumber: String(length = 32) @unique
    status: OrderStatus = PENDING @index          // 1. Inline single-column index
    totalAmount: Decimal(precision = 12, scale = 2)
    createdAt: DateTime @autoNow

    relations {
        customer: Customer @relation(manyToOne)
    }

    // 2. Composite index on foreign key + status
    @index([customer, status])

    // 3. Composite index with explicit custom name
    @index([status, createdAt], name = "idx_orders_status_timeline")

    // 4. Composite unique index
    @uniqueIndex([orderNumber, customer])
}

config {
    rateLimit: "500/minute"               // Global baseline rate limit
}

model Checkout {
    id: UUID @id @auto
    amount: Decimal(12, 2)

    endpoints {
        // 1. Decorator syntax on custom route
        @rateLimit(requests = 5, per = "1m")
        post "/charge" -> OrderResponse {
            action: { }
        }

        // 2. Shorthand capacity/timeUnit syntax
        @rateLimit("10/minute")
        post "/instant-pay" -> Void {
            action: { }
        }

        // 3. Route body property
        post "/verify-card" -> Void {
            rateLimit: "3/second"
            action: { }
        }

        // 4. CRUD-wide rate limit
        crud {
            rateLimit: "100/minute"
            list: ["public"]
        }
    }
}

enum UserRole {
    ADMIN,
    STAFF,
    CUSTOMER
}

enum OrderStatus {
    PENDING,
    PAID,
    PROCESSING,
    SHIPPED,
    DELIVERED,
    CANCELLED
}

model UserEntity {
    id: UUID @id @auto
    email: String @email @unique
    password: String @password
    role: UserRole = CUSTOMER @role
    isActive: Boolean = true
}

model Category {
    id: Long @id @auto
    name: String @unique

    relations {
        products: List<Product> @relation(oneToMany, mappedBy = "category")
    }
}

model Product {
    id: Long @id @auto
    title: String
    price: Decimal

    relations {
        category: Category @relation(manyToOne)
        orderItems: List<OrderItem> @relation(oneToMany, mappedBy = "product")
    }
}

model Order {
    id: UUID @id @auto
    orderNumber: String @unique

    relations {
        customer: UserEntity @relation(manyToOne)
        items: List<OrderItem> @relation(oneToMany, mappedBy = "order")
    }
}

model OrderItem {
    id: Long @id @auto
    quantity: Int @min(1)
    unitPrice: Decimal

    relations {
        order: Order @relation(manyToOne)
        product: Product @relation(manyToOne)
    }
}

model Product {
    id: Long @id @auto
    title: String
    sku: String @unique
    status: ProductStatus
    price: Decimal

    endpoints {
        crud {
            paginate: true                      // PageResponse<T> with ?page=0&size=20
            search: [title, sku]               // Case-insensitive ?search= query
            filter: [status]                   // Exact match query ?status=ACTIVE
            sort: [price, createdAt]           // Sorting ?sort=price,desc
            rateLimit: "100/minute"            // Token-bucket rate limiting
            auth: true                         // Requires valid JWT token
            roles: {
                create: [ADMIN, STAFF],       // Emits @PreAuthorize("hasAnyRole('ADMIN','STAFF')")
                delete: [ADMIN],              // Emits @PreAuthorize("hasRole('ADMIN')")
                list: ["public"]              // Anonymous public access allowed
            }
        }
    }
}

dto CheckoutItemRequest {
    productId: Long
    quantity: Int
}

dto CheckoutRequest {
    shippingAddress: String
    notes: String?
    items: List<CheckoutItemRequest>
}

model Order {
    id: UUID @id @auto
    status: OrderStatus = PENDING

    endpoints {
        // Custom POST endpoint with rate limiting & typed request body
        @rateLimit(requests = 5, per = "1m")
        post "/checkout" (body: CheckoutRequest) -> OrderSummaryResponse {
            auth: true
            action: {
                // Execute domain mutation logic
            }
        }

        // Route with path variable
        post "/{id}/cancel" -> Void {
            auth: true
            guard: status == OrderStatus.PENDING, "Only pending orders can be cancelled"
            action: {
                status = OrderStatus.CANCELLED
            }
        }
    }
}

post "/{id}/pay" -> OrderSummaryResponse {
    auth: true

    // 1. Guard check: fails with 400 Bad Request if false
    guard: status == OrderStatus.PENDING, "Only pending orders can be marked as paid"

    action: {
        // 2. State mutation on primary entity
        status = OrderStatus.PAID

        // 3. Action Variable Binding: create and capture invoice
        var invoice = create Invoice {
            orderNumber = entity.orderNumber,
            amount = entity.totalAmount,
            status = InvoiceStatus.PAID
        }

        // 4. Instantiate secondary audit log entity referencing bound variable
        var audit = create AuditLog {
            action = "ORDER_PAYMENT_PROCESSED",
            invoiceId = invoice.id,
            details = "Order " + entity.orderNumber + " marked PAID by " + currentUser.email
        }

        // 5. Dispatch notification to customer
        notify(entity.customer.email, "Your payment for order " + entity.orderNumber + " succeeded!")

        // 6. Return explicit DTO
        return OrderSummaryResponse {
            orderNumber = entity.orderNumber,
            totalAmount = entity.totalAmount,
            status = entity.status,
            paidAt = now()
        }
    }
}

dto OrderSummaryResponse {
    orderNumber: String
    totalAmount: Decimal
    status: OrderStatus
    processedBy: String?
}

// Approach A: Explicit return construction inside action
post "/{id}/pay" -> OrderSummaryResponse {
    action: {
        status = OrderStatus.PAID
        return OrderSummaryResponse {
            orderNumber = entity.orderNumber,
            totalAmount = entity.totalAmount,
            status = entity.status,
            processedBy = currentUser.email
        }
    }
}

// Approach B: Automatic field mapping (zero boilerplate)
get "/{id}/summary" -> OrderSummaryResponse {
    // Coincident fields (orderNumber, totalAmount, status) map automatically
}

seed UserEntity [
    {
        email: "admin@nexus.dev",
        password: "AdminSecret2026!",       // Automatically BCrypt hashed
        fullName: "Platform Admin",
        role: ADMIN
    },
    {
        email: "customer@example.com",
        password: "Pass1234!",
        fullName: "John Doe",
        role: CUSTOMER
    }
]

seed Order [
    {
        orderNumber: "ORD-2026-001",
        totalAmount: 149.99,
        status: PENDING,
        customer: seed UserEntity[1]          // Cross-references 2nd UserEntity record
    }
]

import "./config.zen"
import "./auth.zen"
import "./catalog.zen"
import "./orders.zen"
import "./jobs.zen"
import "./seeds.zen"

model Product {
    id: Long @id @auto
    title: String

    // Media image upload with MIME type and size checks
    coverImage: String? @image(maxSize = "5MB", types = ["image/png", "image/jpeg"], path = "products/")

    // Datasheet PDF upload
    specSheet: String? @file(maxSize = "10MB", path = "specs/")
}

// Generated Endpoints:
// POST /api/v1/products/{id}/coverImage (multipart/form-data)
// GET  /api/v1/products/{id}/coverImage (download stream)

job ArchiveOldOrders {
    cron: "0 0 2 * * ?"               // Executes 2:00 AM daily
    description: "Nightly maintenance archiving delivered orders older than 60 days"
    action: {
        update Order {
            where: status == OrderStatus.DELIVERED and updatedAt < daysAgo(60)
            status = OrderStatus.CANCELLED
        }
    }
}

config {
    app: "NexusStore"
    mail: smtp
    mailFrom: "support@nexusstore.io"
}

// 1. Declare typed email contract
mail OrderConfirmation(order: Order, customer: Customer) {
    to: customer.email
    subject: "Order #" + order.orderNumber + " Confirmed"
    template: "emails/order-confirmation.html"
    from: "orders@nexusstore.io"  // Optional override
}

model Order {
    id: UUID @id @auto
    orderNumber: String @unique

    relations {
        customer: Customer @relation(manyToOne)
    }

    endpoints {
        post "/checkout" -> OrderResponse {
            action: {
                status = OrderStatus.CONFIRMED
                // 2. Trigger asynchronous email dispatch
                send OrderConfirmation(order = entity, customer = entity.customer)
            }
        }
    }
}

config {
    app: "HighTrafficStore"
    cache: redis        // redis | caffeine | memory | none
    cacheTtl: "15m"     // Default TTL for cached records
}

model Product {
    id: UUID @id @auto
    name: String
    price: Decimal

    endpoints {
        crud {
            cache: "15m"  // Enables @Cacheable on getById/getAll & @CacheEvict on mutations
        }

        get "/featured" -> List<ProductResponse> {
            cache: "1h"   // Custom endpoint cache TTL (1 hour)
        }
    }
}

import React from 'react';
import { createClient } from './sdk/typescript/src/client';
import { useOrderList } from './sdk/typescript/src/react-query';

const api = createClient({
  baseUrl: 'http://localhost:8080',
  getToken: () => localStorage.getItem('jwt_token')
});

export function OrdersDashboard() {
  const { data, isLoading } = useOrderList(api, { page: 0, size: 10, sort: 'createdAt,desc' });

  if (isLoading) return <div>Loading orders...</div>;

  return (
    <ul>
      {data?.content.map(order => (
        <li key={order.id}>{order.orderNumber} - ${order.totalAmount} ({order.status})</li>
      ))}
    </ul>
  );
}

mvn test

docker compose up --build

# Launch the Zenith MCP server over stdio
zenith mcp