🔷 hexon-engine-z

LIVE EXAMPLE

hexon-engine-z is a framework-agnostic intent execution engine for deterministic business logic for backend & application logic.

Hexon is about deterministic business flows, not services calling services.

Why hexon-engine-z

• Intent → Flow → Effect architecture
• No throw in business logic (Result-based)
• Deterministic async orchestration
• Short-circuit execution
• Side-effect isolation
• Framework-agnostic core
• First-class observability hooks
• Easy adapter to NestJS / Fastify / Express
• Execution order is explicit and traceable

Installation

npm install hexon-engine-z

Mental Model

HTTP / RPC / Queue / Cron
        ↓
     Adapter
        ↓
   hexon-engine (core)
        ↓
 Business Flow / Effects / Infrastructure

Basic Usage

import { createEngine, Ok, Err } from "hexon-engine-z"

const engine = createEngine({
  intents(reg) {
    reg.register({
      name: "ping",
      flow: async (flow, input) => {
        const res = await flow.run("log", input)
        if (!res.ok) return res
        return Ok({ pong: true })
      }
    })
  },

  effects(reg) {
    reg.register("log", async ({ input }) => {
      console.log("PING:", input)
      return Ok()
    })
  }
})

await engine.emit("ping", "hello")

Example: Create Order (Real Backend Flow)

engine.emit("createOrder", {
  userId: "u1",
  qty: 2,
  amount: 100
})

Flow:

1. Reserve inventory
2. Charge payment
3. Save order
4. Emit events
5. Short-circuit on failure

Real-world business flow

import { createEngine, Ok, Err } from "hexon-engine-z"

export const engine = createEngine({
  intents(reg) {
    reg.register({
      name: "createOrder",
      validate(input) {
        if (!input.userId) return Err("Missing userId")
        return Ok()
      },
      flow: async (flow, input) => {
        const inv = await flow.run("reserveInventory", input)
        if (!inv.ok) return inv

        const pay = await flow.run("chargePayment", input)
        if (!pay.ok) return pay

        flow.state.paymentId = pay.data.id

        return flow.run("saveOrder", input)
      }
    })
  },

  effects(reg) {
    reg.register("reserveInventory", async ({ input }) => {
      if (input.qty > 10) return Err(new Error("Out of stock"))
      return Ok()
    })

    reg.register("chargePayment", async ({ input }) => {
      return Ok({ id: "pay_123" })
    })

    reg.register("saveOrder", async ({ state }) => {
      return Ok({ orderId: "order_001", paymentId: state.paymentId })
    })
  }
})

Philosophy

• Explicit over implicit
• Orchestration over service-to-service calls
• No magic global state
• Effects are isolated
• Business logic is testable

What hexon-engine-z is NOT

• ❌ Not a framework
• ❌ Not a service container
• ❌ Not a state manager
• ❌ Not CQRS / Event Sourcing

Hexon complements frameworks — it does not replace them.

License

MIT