npm package: @flareflow/cli
Description: flareflow CLI
Latest version: 0.0.3

# flareflow

### The Operating System for Edge Apps on Cloudflare

flareflow is a high-level, production-grade backend framework and infrastructure abstraction layer built specifically for the **Cloudflare** ecosystem. 

If Firebase is for GCP and Supabase is for Postgres, then **flareflow is for Cloudflare**.

---

## ✨ Features

- **Unified Context**: Access `db`, `cache`, `storage`, `jobs`, `actors`, and `auth` from a single, type-safe `ctx` object.
- **Stateful Edge Actors**: Durable Objects as first-class business entities with typed RPC and automatic state persistence.
- **Durable Workflow Engine**: Multi-step, resumable orchestrations (Sagas) with automatic retries and compensation logic.
- **Realtime Rooms**: WebSocket-based rooms with built-in presence and broadcasting using Durable Objects.
- **Type-safe SQL**: Integrated **Drizzle ORM** over **Cloudflare D1**.
- **Edge Auth & RBAC**: Stateless JWT-based authentication and Role-Based Access Control optimized for the edge.
- **Background Jobs**: Typed async tasks powered by **Cloudflare Queues**.
- **Modern CLI**: Scaffolding, boilerplate generators, and a typed `flareflow.config.ts`.

---

## 📦 Project Structure

flareflow is a modular TypeScript monorepo:

- `@flareflow/core`: The heart of the framework, HTTP engine (Hono), and DI Context.
- `@flareflow/db`: D1 wrapper with Drizzle ORM.
- `@flareflow/actor`: Durable Object abstraction and RPC bridge.
- `@flareflow/workflow`: Durable saga/workflow engine.
- `@flareflow/realtime`: WebSocket room management.
- `@flareflow/auth`: Edge-optimized authentication and RBAC.
- `@flareflow/jobs`: Cloudflare Queues abstraction.
- `@flareflow/cache`: KV-based typed caching.
- `@flareflow/storage`: R2-based object storage.
- `@flareflow/cli`: The `flareflow` command-line developer tool.

---

## 🚀 Getting Started

### 1. Initialize a new project
```bash
npx @flareflow/cli init my-edge-app
cd my-edge-app
npm install
```

### 2. Configure your app (`flareflow.config.ts`)
flareflow replaces manual `wrangler.toml` management with a typed TypeScript configuration.
```typescript
import { defineConfig } from "@flareflow/cli";

export default defineConfig({
  name: "my-edge-app",
  compatibilityDate: "2024-04-05",
  resources: {
    db: { type: "d1", name: "prod-db", database_id: "xxxx-yyyy-zzzz" },
    cache: { type: "kv", name: "prod-cache", id: "aaaa-bbbb-cccc" }
  },
  actors: ["CounterActor"],
  rooms: ["ChatRoom"],
  workflows: ["OrderWorkflow"]
});
```

### 3. Start development
```bash
flareflow dev
```

---

## 🛠️ Core Abstractions

### Entities (D1 + Drizzle)
Define your schema once, and it's automatically available on `ctx.db`.
```typescript
import { entity, field } from "@flareflow/db";

export const Users = entity("users", {
  id: field.id(),
  name: field.string("name"),
  email: field.string("email").unique(),
});

// usage in a route
app.get("/users/:id", async (ctx) => {
  return await ctx.db.select().from(Users).where(eq(Users.id, ctx.param("id")));
});
```

### Actors (Durable Objects)
Business logic that lives in a stateful, single-threaded isolate at the edge.
```typescript
export const CounterActor = actor("CounterActor", {
  state: { count: 0 },
  methods: {
    async increment(ctx) {
      ctx.state.count++; // State is automatically persisted
      return ctx.state.count;
    }
  }
});

// call from an HTTP handler
const count = await ctx.actor(CounterActor).id("global-counter").increment();
```

### Workflows (Durable Sagas)
Orchestrate complex, multi-step business logic with failure recovery.
```typescript
export const OrderWorkflow = workflow("OrderWorkflow", {
  steps: [
    {
      name: "reserve-inventory",
      action: async (ctx, state) => Inventory.reserve(state.itemId),
      compensate: async (ctx, state) => Inventory.release(state.itemId)
    },
    {
      name: "charge-card",
      action: async (ctx, state) => Stripe.charge(state.amount)
    }
  ]
});

// trigger the workflow
await ctx.workflow(OrderWorkflow).start("order_123", { itemId: "sku_1", amount: 100 });
```

### Realtime (WebSockets)
Built-in pub/sub and presence rooms.
```typescript
export const ChatRoom = room("ChatRoom", {
  onJoin: (ctx, client) => ctx.broadcast("user_joined", { id: client.id }),
  onMessage: (ctx, client, msg) => ctx.broadcast("message", { from: client.id, text: msg.text })
});

// upgrade to WebSocket in a route
app.get("/chat/:id", (ctx) => ctx.realtime(ChatRoom).id(ctx.param("id")).upgrade());
```

### Background Jobs (Queues)
Typed async tasks with automatic retries and dead-letter queues.
```typescript
export const WelcomeEmailJob = job("WelcomeEmail", {
  handler: async (ctx, payload: { email: string; name: string }) => {
    await ctx.email.send(payload.email, `Welcome to the app, ${payload.name}!`);
  }
});

// enqueue from a route or actor
await ctx.jobs.enqueue(WelcomeEmailJob, { email: "user@example.com", name: "Alice" });
```

### Storage (R2)
Interact with object storage using a simple, typed API.
```typescript
app.post("/upload", async (ctx) => {
  const { file } = await ctx.req.parseBody();
  await ctx.storage.bucket("avatars").put("user_1.jpg", file);
  return ctx.json({ status: "uploaded" });
});
```

### Cache (KV)
Fast, edge-optimized key-value storage with built-in `getOrSet`.
```typescript
app.get("/posts/:id", async (ctx) => {
  const cacheKey = `post:${ctx.param("id")}`;
  return await ctx.cache.getOrSet(cacheKey, async () => {
    return await ctx.db.select().from(Posts).where(eq(Posts.id, ctx.param("id")));
  }, { ttl: 3600 });
});
```

---

## 💻 CLI Commands

- `flareflow init <dir>`: Scaffold a new project.
- `flareflow dev`: Start local development with hot-reloading and infrastructure simulation.
- `flareflow generate <type> <name>`: Generate boilerplate for `entity`, `actor`, `job`, `workflow`, or `room`.
- `flareflow db:generate`: Generate SQL migrations from your Entities.
- `flareflow db:migrate`: Apply migrations to D1 (local or remote).
- `flareflow deploy`: Automatically generate `wrangler.toml` and deploy to Cloudflare.
- `flareflow studio`: Start the local web dashboard to inspect your data, actors, and workflows.





## 📄 License
MIT