@raven.js/cli 1.1.1 → 1.2.0

package/dist/source/core/PLUGIN.md

@@ -0,0 +1,225 @@
+# PLUGIN AUTHORING GUIDE
+
+A plugin is a **named object** returned by a factory function and registered via `app.register()`.
+
+```typescript
+import { definePlugin, type Raven } from "@raven.js/core";
+
+export function myPlugin(config: { prefix: string }) {
+  return definePlugin({
+    name: "my-plugin",   // required — shown in error messages
+    states: [],          // ScopedState instances created inside this factory
+    load(app: Raven) {   // called during registration
+      app.onRequest((req) => { /* ... */ });
+    },
+  });
+}
+
+const app = new Raven();
+await app.register(myPlugin({ prefix: "/api" }));
+```
+
+**`definePlugin`** is a type helper — it ensures TypeScript infers `states` as a tuple rather than an array, which makes the return type of `register()` precise. It has no runtime effect.
+
+Use `app.onLoaded(hook)` for one-time app initialization that should happen after plugin registration and before requests are served.
+
+---
+
+# STATE PATTERNS
+
+Plugins interact with the `ScopedState` DI system in two patterns. Choose based on who owns the state.
+
+## Pattern A — Per-registration isolated states
+
+Declare states **inside the factory function**. Each call to the factory creates a new state instance. `app.register()` returns these states — the caller destructures them.
+
+```typescript
+// config-plugin.ts
+import { definePlugin, createAppState, type Raven } from "@raven.js/core";
+
+interface Config { value: string }
+
+export function configPlugin(value: string) {
+  const ConfigState = createAppState<Config>();  // new instance per factory call
+  return definePlugin({
+    name: "config-plugin",
+    states: [ConfigState] as const,
+    load(app: Raven) {
+      ConfigState.set({ value });
+    },
+  });
+}
+```
+
+```typescript
+// app.ts
+import { configPlugin } from "./config-plugin.ts";
+
+const app = new Raven();
+const [primaryConfig]   = await app.register(configPlugin("primary-value"));
+const [secondaryConfig] = await app.register(configPlugin("secondary-value"));
+
+app.get("/", () => {
+  const a = primaryConfig.getOrFailed();
+  const b = secondaryConfig.getOrFailed();
+  return Response.json({ a: a.value, b: b.value });
+});
+```
+
+**When to use**: any plugin that owns its state — whether registered once or multiple times. Each registration holds independent state; the caller gets it back from `register()`.
+
+> **Note**: `as const` on the `states` array is required to help TypeScript infer a tuple type, so the destructured value from `register()` is typed correctly.
+
+---
+
+## Pattern B — Caller-provided state (inter-plugin dependency)
+
+Accept a `ScopedState` instance as a parameter. The caller creates and owns the state; the plugin only writes to it. This is the standard way for one plugin to depend on another.
+
+```typescript
+// logger-plugin.ts
+import { definePlugin, type AppState, type Raven } from "@raven.js/core";
+
+interface Logger { log: (msg: string) => void }
+
+export function loggerPlugin(loggerState: AppState<Logger>) {
+  return definePlugin({
+    name: "logger-plugin",
+    states: [],
+    load(app: Raven) {
+      loggerState.set({ log: (msg) => console.log(msg) });
+    },
+  });
+}
+```
+
+```typescript
+// app.ts
+import { loggerPlugin } from "./logger-plugin.ts";
+import { createAppState } from "@raven.js/core";
+
+interface Logger { log: (msg: string) => void }
+
+const loggerState = createAppState<Logger>();
+
+const app = new Raven();
+await app.register(loggerPlugin(loggerState));
+
+// pass loggerState to any other plugin that needs it
+await app.register(someOtherPlugin(loggerState));
+```
+
+**When to use**: a plugin depends on state owned by another plugin, or the caller needs explicit control over the state's identity and lifecycle.
+
+---
+
+# GOTCHAS
+
+## Do not declare state outside the factory
+
+States declared at module level are shared across all `Raven` instances in the same process. This breaks test isolation and makes it impossible to register the same plugin more than once with independent state.
+
+```typescript
+// ❌ Wrong: shared across all app instances
+export const DbState = createAppState<DB>();
+
+export function dbPlugin(dsn: string) {
+  return definePlugin({
+    name: "db-plugin",
+    states: [],
+    async load() { DbState.set(await connectDatabase(dsn)); },
+  });
+}
+```
+
+```typescript
+// ✓ Correct: one state instance per registration
+export function dbPlugin(dsn: string) {
+  const DbState = createAppState<DB>();
+  return definePlugin({
+    name: "db-plugin",
+    states: [DbState] as const,
+    async load() { DbState.set(await connectDatabase(dsn)); },
+  });
+}
+
+// app.ts
+export const [DbState] = await app.register(dbPlugin("postgres://localhost/mydb"));
+```
+
+---
+
+## `register()` must be awaited
+
+`register()` returns `Promise<states>`. Not awaiting it means `load()` may not have run before you register routes or subsequent plugins.
+
+```typescript
+// ❌ Wrong
+app.register(myPlugin());
+app.get("/", handler);   // load() may not have run yet
+
+// ✓ Correct
+await app.register(myPlugin());
+app.get("/", handler);
+```
+
+## `AppState.set()` requires AppStorage context
+
+`AppState.set()` only works when `currentAppStorage` is active. Inside `load()` this is always the case. Outside of `load()` (e.g. at module top level) it throws `ERR_STATE_CANNOT_SET`.
+
+```typescript
+const dbState = createAppState<DB>();
+
+// ❌ Wrong: outside any context
+dbState.set(db);
+
+// ✓ Correct: inside load()
+export function myPlugin() {
+  return definePlugin({
+    name: "my-plugin",
+    states: [],
+    load(app) {
+      dbState.set(db);   // ✓ safe
+    },
+  });
+}
+```
+
+## Hooks registered in `load()` apply in registration order
+
+Hooks added in `load()` are appended to the global hook list. Plugins registered first have their hooks run first. Register plugins before routes to ensure hooks apply to all routes.
+
+```typescript
+await app.register(authPlugin());    // onRequest hook added first
+await app.register(loggerPlugin());  // onRequest hook added second
+
+app.get("/", handler);               // both hooks apply to this route
+```
+
+## `onLoaded` runs once before the first request
+
+`onLoaded` is app-level (not request-level). Hooks run in registration order, are awaited serially, and execute once before the first request lifecycle.
+
+```typescript
+await app.register(authPlugin());
+await app.register(loggerPlugin());
+
+app.onLoaded(async () => {
+  await initMetrics();
+});
+
+// onLoaded executes once on the first request
+await app.handle(new Request("http://localhost/"));
+```
+
+If an `onLoaded` hook throws, remaining `onLoaded` hooks are skipped and the error is propagated.
+
+## `load()` errors are attributed to the plugin
+
+If `load()` throws, the error message is wrapped with the plugin name:
+
+```
+[my-plugin] Plugin load failed: connection refused
+```
+
+The original error is available as `error.cause`.

package/dist/source/core/README.md

@@ -0,0 +1,427 @@
+# OVERVIEW
+
+RavenJS Core is a lightweight, high-performance Web framework reference implementation for Bun.
+
+**Features**:
+- Logic layer: `app.handle` (FetchHandler)
+- Radix tree router (path parameters)
+- Dependency injection (DI) via AsyncLocalStorage (ScopedState)
+- Lifecycle hooks (onLoaded, onRequest, beforeHandle, beforeResponse, onError)
+- Plugin system
+
+---
+
+# ARCHITECTURE
+
+**Lifecycle overview**:
+
+```
+app startup / first handle()
+      │
+      ▼
+[plugin register/load]   ← `await app.register(plugin)`; plugin hooks/states are installed here.
+      │
+      ▼
+[onLoaded hooks]       ← app-level init; runs once before the first request lifecycle.
+      │
+      ▼
+app ready
+```
+
+```
+incoming request (each request)
+      │
+      ▼
+[onRequest hooks]     ← global; receives raw Request. Returning a Response short-circuits.
+      │
+      ▼
+[route matching]      ← no match → 404
+      │
+      ▼
+[processStates]       ← populates ParamsState / QueryState / HeadersState / BodyState
+      │
+      ▼
+[beforeHandle hooks]  ← route-scoped; no args. Returning a Response short-circuits.
+      │
+      ▼
+[handler()]           ← no args; returns Response
+      │
+      ▼
+[beforeResponse hooks] ← route-scoped; receives Response. Returning a new Response replaces it.
+      │
+      ▼
+outgoing response
+
+any uncaught exception → [onError hooks] → fallback 500
+```
+
+---
+
+# CORE CONCEPTS
+
+## Raven
+
+The main application class. Register routes with full paths (e.g. `app.get('/api/v1/users', handler)`).
+Raven is a **logic layer**—it exposes `handle(request) => Promise<Response>`:
+
+```typescript
+const app = new Raven();
+app.get("/", () => new Response("Hello"));
+Bun.serve({ fetch: (req) => app.handle(req) });
+```
+
+## Context
+
+The per-request context object, exposing `request`, `params`, `query`, `url`, `method`, `headers`, and `body`.
+
+Access it via the built-in `RavenContext` state:
+
+```typescript
+const ctx = RavenContext.getOrFailed();
+console.log(ctx.method); // "GET"
+console.log(ctx.params); // { id: "42" }
+```
+
+## Dependency Injection (DI)
+
+**ScopedState is RavenJS's dependency injection (DI) implementation.** It uses `AsyncLocalStorage` to inject state into the async call chain, allowing handlers and hooks to access dependencies without explicit parameter passing. Each ScopedState is a state container with a well-defined lifetime:
+
+| Type           | Lifetime                     | Typical use                          |
+| -------------- | ---------------------------- | ------------------------------------ |
+| `AppState`     | Shared across the entire app | DB connections, config, counters     |
+| `RequestState` | Isolated per HTTP request    | Current user, parsed body, auth info |
+
+**Built-in states** (populated automatically by the framework — do not set manually):
+
+| State          | Type                     | Description                             |
+| -------------- | ------------------------ | --------------------------------------- |
+| `RavenContext` | `Context`                | Full request context                    |
+| `ParamsState`  | `Record<string, string>` | URL path parameters                     |
+| `QueryState`   | `Record<string, string>` | Query string parameters                 |
+| `HeadersState` | `Record<string, string>` | Request headers (lowercased keys)       |
+| `BodyState`    | `unknown`                | Request body (JSON only; cast required) |
+
+## Plugin
+
+A plugin is a **named object** with a `load(app)` method, registered via `app.register()`. Plugins are created by factory functions so they can accept configuration. `app.register()` returns a `Promise` resolving to the plugin's `states` tuple — always `await` it.
+
+For post-registration initialization, use `app.onLoaded(hook)`. `onLoaded` hooks run in registration order, are awaited serially, and execute once before the first request is processed.
+
+→ **Creating a plugin?** See [PLUGIN.md](./PLUGIN.md) for the full authoring guide and state patterns.
+
+---
+
+# DESIGN DECISIONS
+
+## Why AsyncLocalStorage for state?
+
+ScopedState uses AsyncLocalStorage as the underlying mechanism for DI. Compared to traditional DI containers or class decorators:
+
+- **Async-safe**: state propagates automatically through the async call chain without cross-request leakage
+- **Zero boilerplate**: handlers don't need to receive a context argument — dependencies are injected into the call chain automatically
+- **Flexible access**: unlike decorators that bake dependencies into constructor or method signatures, you can obtain injected dependencies anywhere in the call chain, only when needed — no rigid injection points
+- **High performance**: zero-copy access, lighter than decorators or full-featured DI containers
+
+## Why are handlers zero-argument functions?
+
+```typescript
+type Handler = () => Response | Promise<Response>;
+```
+
+This is intentional:
+
+- A handler only needs to return a `Response` — no framework-specific types required
+- Data is accessed on demand via `BodyState.get()`, `RavenContext.getOrFailed()`, etc.
+- Any plain function can be a handler with zero migration cost
+
+## Why is the hook pipeline snapshotted at route registration?
+
+When `addRoute()` is called, it snapshots all currently registered hooks and stores them in the route's `pipeline`. This means:
+
+- **Hooks must be registered before routes** — hooks added after a route is registered will not apply to it
+- Each route's pipeline is an independent snapshot and does not affect other routes
+
+---
+
+# GOTCHAS
+
+## 1. Hooks must be declared before routes
+
+```typescript
+// ❌ Wrong: beforeHandle will NOT apply to /users
+app.get("/users", handler);
+app.beforeHandle(authHook);
+
+// ✓ Correct: register hooks first, then routes
+app.beforeHandle(authHook);
+app.get("/users", handler);
+```
+
+Reason: `addRoute()` snapshots all current hooks at call time.
+
+## 2. `register()` is async — always await it
+
+`register()` returns `Promise<states>`, not `Promise<app>`. Always await and destructure the returned states if needed.
+
+```typescript
+// ❌ Wrong: plugin may not have run yet
+app.register(myPlugin());
+
+// ✓ Correct: await it
+await app.register(myPlugin());
+
+// ✓ Correct: destructure states when plugin declares them
+const [configState] = await app.register(configPlugin({ dsn: "..." }));
+```
+
+## 3. `AppState.set()` only works inside an AppStorage context
+
+`AppState.set()` depends on `currentAppStorage`. It is only valid inside:
+
+- a plugin's `load(app)` callback
+- a request handler (after `handle` establishes the context)
+
+Calling it outside these locations throws `ERR_STATE_CANNOT_SET`.
+
+```typescript
+const dbState = createAppState<DB>({ name: "db" });
+
+// ❌ Wrong: called outside AppStorage context
+dbState.set(db);
+
+// ✓ Correct: called inside plugin load()
+await app.register(definePlugin({
+  name: "db",
+  states: [],
+  load(app) {
+    dbState.set(db);
+  },
+}));
+```
+
+## 4. `BodyState` only parses JSON
+
+The framework automatically parses the body and populates `BodyState` only when `Content-Type: application/json` is present. For all other content types (form-data, plain text, binary), `BodyState.get()` returns `undefined` — read the body manually via `RavenContext`.
+
+```typescript
+// Content-Type: application/json → populated automatically
+const body = BodyState.getOrFailed() as { name: string };
+
+// Content-Type: multipart/form-data → read manually
+const ctx = RavenContext.getOrFailed();
+const formData = await ctx.request.formData();
+```
+
+## 5. `BodyState` is typed `unknown` — cast required
+
+`ParamsState`, `QueryState`, and `HeadersState` are typed as `Record<string, string>` and can be used directly. Only `BodyState` remains `unknown` because JSON structure is arbitrary.
+
+```typescript
+// ParamsState / QueryState / HeadersState — use directly, no cast needed
+const { id } = ParamsState.getOrFailed();
+
+// BodyState — cast required
+const body = BodyState.getOrFailed() as { name: string };
+```
+
+## 6. `onRequest` has a different signature from all other hooks
+
+`onRequest` is the only hook that receives an argument — the raw `Request` object. At this point, `RavenContext`, `ParamsState`, and other states **are not yet initialized** (route matching hasn't happened).
+
+```typescript
+// onRequest: receives the raw Request
+app.onRequest((request) => {
+  // RavenContext is NOT set here — do not call RavenContext.get()
+  const token = request.headers.get("authorization");
+});
+
+// beforeHandle: no args, all states are ready
+app.beforeHandle(() => {
+  const ctx = RavenContext.getOrFailed(); // ✓ safe
+});
+```
+
+## 7. Do not pass `app.handle` directly to `Bun.serve`
+
+`handle` is a class method. Passing `app.handle` as the `fetch` callback loses the `this` context when Bun calls it, so `handle`'s internal use of `this` (e.g. for `currentAppStorage.run(this, ...)`) will break.
+
+```typescript
+// ❌ Wrong: this is lost when Bun invokes the callback
+Bun.serve({ fetch: app.handle });
+
+// ✓ Correct: wrap in an arrow function (or use app.handle.bind(app))
+Bun.serve({ fetch: (req) => app.handle(req), port: 3000 });
+```
+
+## 8. Register `onLoaded` before serving traffic
+
+`onLoaded` is triggered once, right before the first successful request lifecycle starts. Register all plugins and `onLoaded` hooks before calling `handle()` from live traffic.
+
+```typescript
+const app = new Raven();
+
+await app.register(authPlugin());
+await app.register(dbPlugin());
+
+app.onLoaded(async () => {
+  await warmupCaches();
+});
+
+Bun.serve({ fetch: (req) => app.handle(req), port: 3000 });
+```
+
+---
+
+# ANTI-PATTERNS
+
+## Do not store request-scoped data in AppState
+
+```typescript
+const userState = createAppState<User>({ name: "user" }); // ❌
+
+// AppState is shared across the entire app — concurrent requests will overwrite each other
+app.beforeHandle(async () => {
+  userState.set(await fetchUser()); // dangerous! concurrent requests corrupt this value
+});
+
+// ✓ Use RequestState instead
+const userState = createRequestState<User>({ name: "user" });
+```
+
+## Do not register route-specific hooks globally
+
+```typescript
+// ❌ Intended to only hook /api, but the hook applies to ALL routes
+app.get("/api/users", handler);
+app.beforeHandle(apiOnlyHook); // applies to all routes registered after this
+
+// ✓ Use path checks inside the hook, or structure routes so hooks apply only where needed
+app.beforeHandle(() => {
+  const ctx = RavenContext.getOrFailed();
+  if (!ctx.url.pathname.startsWith("/api")) return;
+  return apiOnlyHook();
+});
+app.get("/api/users", handler);
+```
+
+## Do not forget to return a Response from `onError`
+
+```typescript
+// ❌ Missing return — the framework falls through to subsequent hooks or the default 500
+app.onError((error) => {
+  console.error(error);
+  // no return!
+});
+
+// ✓ Always return a Response
+app.onError((error) => {
+  console.error(error);
+  return new Response("Something went wrong", { status: 500 });
+});
+```
+
+---
+
+# USAGE EXAMPLES
+
+## Minimal
+
+```typescript
+import { Raven } from "./index.ts";
+
+const app = new Raven();
+
+app.get("/", () => new Response("Hello, World!"));
+
+Bun.serve({ fetch: (req) => app.handle(req), port: 3000 });
+```
+
+## Path parameters
+
+```typescript
+import { Raven, ParamsState } from "./index.ts";
+
+const app = new Raven();
+
+app.get("/user/:id", () => {
+  const { id } = ParamsState.getOrFailed();
+  return new Response(`User ID: ${id}`);
+});
+```
+
+## Route prefix (use full paths)
+
+```typescript
+import { Raven } from "./index.ts";
+
+const app = new Raven();
+
+app.get("/api/v1/users", () => new Response("Users list"));
+app.post("/api/v1/users", () => new Response("Create user", { status: 201 }));
+```
+
+## Auth middleware (hooks must come before routes)
+
+```typescript
+import { Raven, createRequestState, RavenContext } from "./index.ts";
+
+interface User {
+  id: string;
+  role: string;
+}
+const currentUser = createRequestState<User>({ name: "currentUser" });
+
+const app = new Raven();
+
+// register hook first
+app.beforeHandle(async () => {
+  const ctx = RavenContext.getOrFailed();
+  const token = ctx.headers.get("authorization");
+  if (!token) return new Response("Unauthorized", { status: 401 });
+  currentUser.set(await verifyToken(token));
+});
+
+// then register routes
+app.get("/profile", () => {
+  const user = currentUser.getOrFailed();
+  return Response.json({ id: user.id });
+});
+```
+
+## Error handling
+
+```typescript
+import { Raven, RavenError, isRavenError, ParamsState } from "./index.ts";
+
+const app = new Raven();
+
+app.onError((error) => {
+  if (isRavenError(error)) {
+    return error.toResponse(); // serializes to JSON using statusCode
+  }
+  console.error("Unexpected error:", error);
+  return new Response("Internal Server Error", { status: 500 });
+});
+
+app.get("/items/:id", () => {
+  const { id } = ParamsState.getOrFailed();
+  if (!id.match(/^\d+$/)) {
+    throw RavenError.ERR_BAD_REQUEST("id must be numeric");
+  }
+  return Response.json({ id });
+});
+```
+
+## Mutating the response (beforeResponse hook)
+
+```typescript
+const app = new Raven();
+
+app.beforeResponse((response) => {
+  const newResponse = new Response(response.body, response);
+  newResponse.headers.set("Access-Control-Allow-Origin", "*");
+  return newResponse;
+});
+
+app.get("/data", () => Response.json({ ok: true }));
+```