@raven.js/cli 1.1.2 → 1.2.1

package/dist/source/core/router.ts

@@ -0,0 +1,128 @@
+// =============================================================================
+// Radix Router - Efficient URL pattern matching
+// =============================================================================
+
+/**
+ * Result of a successful route match.
+ * @template T The type of data associated with the route (e.g., handler and pipeline).
+ */
+export interface RouteMatch<T> {
+  /** The data payload stored for the matched route. */
+  data: T;
+  /** Extracted path parameters. */
+  params: Record<string, string>;
+}
+
+/**
+ * Internal tree node for the Radix router.
+ * @template T The type of data stored at the node.
+ */
+class RouterNode<T> {
+  children: Map<string, RouterNode<T>> = new Map();
+  paramChild: RouterNode<T> | null = null;
+  wildcardChild: RouterNode<T> | null = null;
+  paramName: string | null = null;
+  handlers: Map<string, T> = new Map();
+
+  /**
+   * Inserts a route into the node tree.
+   */
+  insert(segments: string[], method: string, data: T) {
+    let current: RouterNode<T> = this;
+
+    for (const segment of segments) {
+      if (segment.startsWith(":")) {
+        if (!current.paramChild) {
+          current.paramChild = new RouterNode<T>();
+          current.paramName = segment.slice(1);
+        }
+        current = current.paramChild;
+      } else if (segment === "*") {
+        if (!current.wildcardChild) {
+          current.wildcardChild = new RouterNode<T>();
+        }
+        current = current.wildcardChild;
+        break;
+      } else {
+        if (!current.children.has(segment)) {
+          current.children.set(segment, new RouterNode<T>());
+        }
+        current = current.children.get(segment)!;
+      }
+    }
+
+    current.handlers.set(method.toUpperCase(), data);
+  }
+
+  /**
+   * Searches for a matching route in the node tree.
+   */
+  search(
+    segments: string[],
+    method: string,
+    params: Record<string, string>,
+  ): T | null {
+    let current: RouterNode<T> = this;
+
+    for (const segment of segments) {
+      const next = current.children.get(segment);
+      if (next) {
+        current = next;
+      } else if (current.paramChild) {
+        if (current.paramName) {
+          params[current.paramName] = segment;
+        }
+        current = current.paramChild;
+      } else if (current.wildcardChild) {
+        current = current.wildcardChild;
+        return current.handlers.get(method.toUpperCase()) || null;
+      } else {
+        return null;
+      }
+    }
+
+    return current.handlers.get(method.toUpperCase()) || null;
+  }
+}
+
+/**
+ * Radix tree based router for efficient URL pattern matching.
+ * @template T The type of data associated with each route.
+ */
+export class RadixRouter<T> {
+  private root = new RouterNode<T>();
+
+  /**
+   * Adds a new route to the router.
+   * @param method HTTP method.
+   * @param path URL path pattern.
+   * @param data Data payload to store with the route.
+   */
+  add(method: string, path: string, data: T) {
+    const segments = this.splitPath(path);
+    this.root.insert(segments, method, data);
+  }
+
+  /**
+   * Finds a matching route for the given method and path.
+   * @param method HTTP method.
+   * @param path URL path to match.
+   * @returns RouteMatch containing the data and extracted parameters, or null if not found.
+   */
+  find(method: string, path: string): RouteMatch<T> | null {
+    const segments = this.splitPath(path);
+    const params: Record<string, string> = {};
+    const data = this.root.search(segments, method, params);
+
+    if (data === null) {
+      return null;
+    }
+
+    return { data, params };
+  }
+
+  /** Helper to split a path into normalized segments. */
+  private splitPath(path: string): string[] {
+    return path.split("/").filter((s) => s.length > 0);
+  }
+}

package/dist/source/schema-validator/GUIDE.md

@@ -0,0 +1,12 @@
+# REQUIRED READING
+
+| File                     | When to Read                                          |
+| ------------------------ | ----------------------------------------------------- |
+| [README.md](./README.md) | Quick start, understand basic usage                   |
+| [index.ts](./index.ts)   | Understand core API (`withSchema`, `ValidationError`) |
+
+# OPTIONAL READING
+
+| File                                       | When to Read                                                         |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| [standard-schema.ts](./standard-schema.ts) | Learn Standard Schema interface spec, or implement custom validators |

package/dist/source/schema-validator/README.md

@@ -0,0 +1,229 @@
+# OVERVIEW
+
+@raven.js/schema-validator is a framework-agnostic validation module for RavenJS, built on [Standard Schema](https://standardschema.dev).
+
+**Features**:
+- **Library Agnostic**: Works with Zod, Valibot, ArkType, or any Standard Schema compliant library.
+- **Full Request Validation**: Validates Body, Query, Params, and Headers.
+- **Type Safety**: Infers types from schemas for the handler context.
+- **Automatic Error Handling**: Throws structured `ValidationError` on failure.
+
+---
+
+# ARCHITECTURE
+
+**Validation lifecycle**:
+
+```
+incoming request
+      │
+      ▼
+[processStates]       ← Core populates BodyState / QueryState / etc.
+      │
+      ▼
+[withSchema wrapper]  ← Intercepts execution
+      │
+      ├─► Validates Body/Query/Params/Headers against schemas
+      │      │
+      │      ▼
+      │   Validation Failed ──► Throws ValidationError ──► [onError hook]
+      │
+      ▼
+   Validation Passed
+      │
+      ▼
+[handler(ctx)]        ← Receives typed context with validated data
+      │
+      ▼
+outgoing response
+```
+
+---
+
+# CORE CONCEPTS
+
+## Standard Schema
+
+This module relies on the [Standard Schema](https://standardschema.dev) interface. This means it doesn't depend on a specific validation library. You can use:
+
+- **Zod**: `bun add zod`
+- **Valibot**: `bun add valibot`
+- **ArkType**: `bun add arktype`
+
+Any library that implements the Standard Schema spec works out of the box.
+
+## `withSchema` Wrapper
+
+The primary API is a higher-order function that wraps your handler. It transforms a **schema-aware handler** (which accepts a context argument) into a **standard RavenJS handler** (zero-argument).
+
+It is recommended to define the handler directly within `withSchema` to leverage type inference automatically:
+
+```typescript
+const schema = {
+  body: z.object({ name: z.string() })
+};
+
+// Define handler inline for automatic type inference
+const createHandler = withSchema(schema, (ctx) => {
+  // ctx.body is automatically typed as { name: string }
+  return Response.json(ctx.body);
+});
+
+app.post("/route", createHandler);
+```
+
+## Context Integration
+
+While RavenJS Core uses global state (`BodyState`, etc.) for dependency injection, `schema-validator` passes a **typed context object** to your handler. This provides the best of both worlds:
+
+- **Type Inference**: The `ctx` argument matches your schema types.
+- **Runtime Integration**: The validator reads from RavenJS's internal states automatically.
+
+---
+
+# DESIGN DECISIONS
+
+## Why Standard Schema?
+
+By adopting Standard Schema, RavenJS avoids vendor lock-in. You are not forced to use Zod or any specific library. This aligns with RavenJS's philosophy of being a "reference implementation" that is flexible and adaptable.
+
+## Why a wrapper function instead of middleware?
+
+RavenJS hooks (`beforeHandle`) are void functions that cannot easily pass typed data to the handler.
+
+- **Middleware approach**: Validation runs in a hook, puts result in a weak-map or untyped state. Handler manually casts data.
+- **Wrapper approach**: The wrapper function *knows* the schema types and passes them directly to the handler function as an argument. This enables 100% type safety without manual casting.
+
+---
+
+# GOTCHAS
+
+## 1. Validation throws `ValidationError`
+
+When validation fails, `withSchema` throws a `ValidationError`. It does **not** return a 400 Response automatically. You must handle this error, typically in a global `onError` hook.
+
+```typescript
+import { isValidationError } from "@raven.js/schema-validator";
+
+app.onError((err) => {
+  if (isValidationError(err)) {
+    return Response.json({ issues: err.bodyIssues }, { status: 400 });
+  }
+});
+```
+
+## 2. Handler signature changes
+
+When using `withSchema`, your handler function **must** accept a context argument, unlike standard RavenJS handlers which are zero-argument.
+
+```typescript
+// Standard handler
+const standard = () => new Response();
+
+// Schema handler
+const schemaHandler = (ctx) => new Response();
+```
+
+## 3. Schema libraries must be installed separately
+
+This package does not bundle Zod or Valibot. You must install your preferred validation library in your project.
+
+---
+
+# USAGE EXAMPLES
+
+## Minimal (Zod)
+
+```typescript
+import { z } from "zod";
+import { withSchema } from "@raven.js/schema-validator";
+import { Raven } from "@raven.js/core";
+
+const schema = {
+  body: z.object({
+    username: z.string(),
+  }),
+};
+
+// Define handler directly inside withSchema for best developer experience
+const createUser = withSchema(schema, (ctx) => {
+  // ctx.body is typed: { username: string }
+  return new Response(`Hello ${ctx.body.username}`);
+});
+
+const app = new Raven();
+app.post("/user", createUser);
+```
+
+## Validating Multiple Sources
+
+```typescript
+const schema = {
+  body: z.object({ name: z.string() }),
+  query: z.object({ page: z.string().transform(Number) }),
+  headers: z.object({ "x-api-key": z.string() }),
+};
+
+const handler = withSchema(schema, (ctx) => {
+  const { name } = ctx.body;
+  const { page } = ctx.query;
+  const apiKey = ctx.headers["x-api-key"];
+  return Response.json({ name, page, apiKey });
+});
+```
+
+## Global Error Handling
+
+```typescript
+import { isValidationError } from "@raven.js/schema-validator";
+
+app.onError((error) => {
+  if (isValidationError(error)) {
+    return new Response(JSON.stringify({
+      error: "Validation Failed",
+      details: {
+        body: error.bodyIssues,
+        query: error.queryIssues,
+      }
+    }), { 
+      status: 400,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  return new Response("Internal Error", { status: 500 });
+});
+```
+
+---
+
+# ANTI-PATTERNS
+
+## Do not validate manually inside handler
+
+```typescript
+// ❌ Manual validation loses type inference benefits and clutters logic
+app.post("/user", async () => {
+  const rawBody = BodyState.getOrFailed();
+  const result = UserSchema.safeParse(rawBody); // ❌
+  if (!result.success) return new Response("Error", { status: 400 });
+  // ...
+});
+
+// ✓ Use withSchema to separate validation from logic
+app.post("/user", withSchema({ body: UserSchema }, (ctx) => {
+  // ...
+}));
+```
+
+## Do not separate handler definition from schema
+
+```typescript
+// ❌ Defining handler separately requires manual type definition or complex inference
+const handler = (ctx: any) => { ... };
+const wrapped = withSchema(schema, handler);
+
+// ✓ Define inline for automatic type inference
+const wrapped = withSchema(schema, (ctx) => {
+  // ctx is fully typed here!
+});
+```

package/dist/source/schema-validator/index.ts

@@ -0,0 +1,139 @@
+import {
+  BodyState,
+  QueryState,
+  ParamsState,
+  HeadersState,
+} from "@raven.js/core";
+import type { StandardSchemaV1 } from "./standard-schema";
+
+export interface Context<
+  B = unknown,
+  Q = Record<string, string>,
+  P = Record<string, string>,
+  H = Record<string, string>,
+> {
+  body: B;
+  query: Q;
+  params: P;
+  headers: H;
+}
+
+export interface Schemas<
+  B = unknown,
+  Q = Record<string, string>,
+  P = Record<string, string>,
+  H = Record<string, string>,
+> {
+  body?: StandardSchemaV1<unknown, B>;
+  query?: StandardSchemaV1<Record<string, string>, Q>;
+  params?: StandardSchemaV1<Record<string, string>, P>;
+  headers?: StandardSchemaV1<Record<string, string>, H>;
+}
+
+export type SchemaHandler<B, Q, P, H> = (
+  ctx: Context<B, Q, P, H>,
+) => Response | Promise<Response>;
+
+export type ValidationSource = "body" | "query" | "params" | "headers";
+
+export class ValidationError extends Error {
+  public readonly bodyIssues?: readonly StandardSchemaV1.Issue[];
+  public readonly queryIssues?: readonly StandardSchemaV1.Issue[];
+  public readonly paramsIssues?: readonly StandardSchemaV1.Issue[];
+  public readonly headersIssues?: readonly StandardSchemaV1.Issue[];
+
+  constructor(results: {
+    body?: StandardSchemaV1.FailureResult;
+    query?: StandardSchemaV1.FailureResult;
+    params?: StandardSchemaV1.FailureResult;
+    headers?: StandardSchemaV1.FailureResult;
+  }) {
+    const allIssues = [
+      ...(results.body?.issues ?? []),
+      ...(results.query?.issues ?? []),
+      ...(results.params?.issues ?? []),
+      ...(results.headers?.issues ?? []),
+    ];
+    const message = allIssues.map((issue) => issue.message).join(", ");
+    super(message);
+    this.name = "ValidationError";
+    this.bodyIssues = results.body?.issues;
+    this.queryIssues = results.query?.issues;
+    this.paramsIssues = results.params?.issues;
+    this.headersIssues = results.headers?.issues;
+  }
+}
+
+async function validateSchema<T>(
+  schema: StandardSchemaV1<unknown, T> | undefined,
+  value: unknown,
+): Promise<StandardSchemaV1.Result<T> | undefined> {
+  if (!schema) {
+    return undefined;
+  }
+
+  return schema["~standard"].validate(value);
+}
+
+export function isValidationError(value: unknown): value is ValidationError {
+  return value instanceof ValidationError;
+}
+
+export function withSchema<B, Q, P, H>(
+  schemas: Schemas<B, Q, P, H>,
+  handler: SchemaHandler<B, Q, P, H>,
+): () => Promise<Response> {
+  return async () => {
+    const body = BodyState.get();
+    const query = QueryState.get() ?? {};
+    const params = ParamsState.get() ?? {};
+    const headers = HeadersState.get() ?? {};
+
+    const [bodyResult, queryResult, paramsResult, headersResult] =
+      await Promise.all([
+        validateSchema(schemas.body, body),
+        validateSchema(schemas.query, query),
+        validateSchema(schemas.params, params),
+        validateSchema(schemas.headers, headers),
+      ]);
+
+    if (
+      bodyResult?.issues ||
+      queryResult?.issues ||
+      paramsResult?.issues ||
+      headersResult?.issues
+    ) {
+      throw new ValidationError({
+        body: bodyResult?.issues
+          ? (bodyResult as StandardSchemaV1.FailureResult)
+          : undefined,
+        query: queryResult?.issues
+          ? (queryResult as StandardSchemaV1.FailureResult)
+          : undefined,
+        params: paramsResult?.issues
+          ? (paramsResult as StandardSchemaV1.FailureResult)
+          : undefined,
+        headers: headersResult?.issues
+          ? (headersResult as StandardSchemaV1.FailureResult)
+          : undefined,
+      });
+    }
+
+    const ctx: Context<B, Q, P, H> = {
+      body: bodyResult
+        ? (bodyResult as StandardSchemaV1.SuccessResult<B>).value
+        : (body as B),
+      query: queryResult
+        ? (queryResult as StandardSchemaV1.SuccessResult<Q>).value
+        : (query as Q),
+      params: paramsResult
+        ? (paramsResult as StandardSchemaV1.SuccessResult<P>).value
+        : (params as P),
+      headers: headersResult
+        ? (headersResult as StandardSchemaV1.SuccessResult<H>).value
+        : (headers as H),
+    };
+
+    return handler(ctx);
+  };
+}

package/dist/source/schema-validator/standard-schema.ts

@@ -0,0 +1,76 @@
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown,
+      options?: StandardSchemaV1.Options | undefined,
+    ) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+
+  export interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["input"];
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["output"];
+}

package/dist/source/sql/GUIDE.md

@@ -0,0 +1,12 @@
+# REQUIRED READING
+
+| File                     | When to Read                            |
+| ------------------------ | --------------------------------------- |
+| [README.md](./README.md) | Quick start, understand basic usage     |
+| [index.ts](./index.ts)   | Understand implementation (`sqlPlugin`) |
+
+# OPTIONAL READING
+
+| File                                       | When to Read                                                                  |
+| ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [SQL](https://bun.com/docs/runtime/sql.md) | If you don't know how to use Bun native SQL bindings, read this file to learn |