# OGraph

**Event Sourcing + Projection + Reaction engine on Cloudflare Workers.**

Part of the [Uncaged](https://github.com/oc-xiaoju/uncaged) ecosystem.

## Packages

| Package | Description | npm |
|---|---|---|
| [`@uncaged/ograph`](packages/engine/) | CF Worker engine — events, projections, reactions | [![npm](https://img.shields.io/npm/v/@uncaged/ograph)](https://www.npmjs.com/package/@uncaged/ograph) |
| [`@uncaged/ograph-cli`](packages/cli/) | CLI for managing OGraph instances | [![npm](https://img.shields.io/npm/v/@uncaged/ograph-cli)](https://www.npmjs.com/package/@uncaged/ograph-cli) |

## Core Concepts

- **Event** — Immutable facts with typed properties and object references
- **Projection** — Derived state computed incrementally from events via reducers
- **Reaction** — Side effects triggered by projection state changes (webhooks, event emission, handlers)

## Quick Start

```bash
npm install -g @uncaged/ograph-cli
ograph deploy          # Deploy to Cloudflare Workers
ograph event-def add   # Define event types
ograph event add       # Emit events
ograph projection list # Query projections
```

## Development

```bash
npm install
npm test              # Run all tests
cd packages/engine && npm run dev  # Local dev server
```

## Architecture

- **D1** for storage (events, projections, reactions)
- **Hono** for API routing
- **Incremental reduce** — projections track `last_event_id` for O(delta) updates
- **Dynamic handlers** — `new Function()` sandboxed execution with emit/log/kv API injection

## License

MIT

---

*Built by 小橘 🍊 & 小墨 🖊️ — NEKO + KUMA Teams*