@spikard/wasm 0.6.2 → 0.7.0

package/README.md

@@ -1,74 +1,72 @@
-# spikard-wasm
+# @spikard/wasm
 
-WebAssembly bindings for Spikard HTTP framework via wasm-bindgen.
+> **Note:** As of v0.2.1, this package has moved to `@spikard/wasm`. Update your imports from `'spikard-wasm'` to `'@spikard/wasm'`. See [MIGRATION-0.2.1.md](../../MIGRATION-0.2.1.md) for details.
 
-## Status & Badges
-
-[![Documentation](https://img.shields.io/badge/docs-spikard.dev-58FBDA)](https://spikard.dev)
-[![npm](https://img.shields.io/npm/v/spikard-wasm.svg)](https://www.npmjs.com/package/spikard-wasm)
-[![npm downloads](https://img.shields.io/npm/dm/spikard-wasm.svg)](https://www.npmjs.com/package/spikard-wasm)
-[![Crates.io](https://img.shields.io/crates/v/spikard-wasm.svg)](https://crates.io/crates/spikard-wasm)
-[![Documentation (Rust)](https://docs.rs/spikard-wasm/badge.svg)](https://docs.rs/spikard-wasm)
+[![npm](https://img.shields.io/npm/v/@spikard/wasm.svg)](https://www.npmjs.com/package/@spikard/wasm)
+[![npm downloads](https://img.shields.io/npm/dm/@spikard/wasm.svg)](https://www.npmjs.com/package/@spikard/wasm)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Discord](https://img.shields.io/badge/Discord-Join%20our%20community-7289da)](https://discord.gg/pXxagNK2zN)
-
-## Overview
-
-Edge-friendly TypeScript web framework for WASM runtimes (Deno, Cloudflare Workers, browsers). Build REST APIs with the same routing primitives as spikard Node.js bindings, compiled to WebAssembly for maximum portability.
+[![codecov](https://codecov.io/gh/Goldziher/spikard/graph/badge.svg?token=H4ZXDZ4A69)](https://codecov.io/gh/Goldziher/spikard)
+[![PyPI](https://img.shields.io/pypi/v/spikard.svg)](https://pypi.org/project/spikard/)
+[![Crates.io](https://img.shields.io/crates/v/spikard.svg)](https://crates.io/crates/spikard)
+[![RubyGems](https://img.shields.io/gem/v/spikard.svg)](https://rubygems.org/gems/spikard)
+[![Packagist](https://img.shields.io/packagist/v/spikard/spikard.svg)](https://packagist.org/packages/spikard/spikard)
+
+Spikard HTTP framework compiled to **WebAssembly with full TypeScript support** for edge runtimes, browsers, and server-side JavaScript environments. Build type-safe web services that run anywhere.
+
+## Features
+
+- **WASM-first**: Compiled from Rust to WebAssembly for maximum performance and portability
+- **Type-safe routing**: Full TypeScript support with auto-completed route definitions
+- **Edge runtime support**: Works in browsers, Cloudflare Workers, Deno, and Node.js
+- **Zero Node.js dependencies**: Pure fetch API—no Node globals required
+- **Async/await native**: Seamless async/await for handlers and middleware
+- **Lightweight**: Optimized WASM binaries with aggressive tree-shaking
+- **Schema validation**: Built-in request/response validation with Zod
+- **WebSocket & SSE**: Full support for real-time features on compatible runtimes
+- **Testing utilities**: In-memory test client for easy unit testing
+- **Code generation**: Generate TypeScript apps and tests from OpenAPI/AsyncAPI
 
 ## Installation
 
-**From npm:**
+### From npm
 
 ```bash
-npm install spikard-wasm
-# or
-pnpm add spikard-wasm
-# or
-yarn add spikard-wasm
-# or
-deno add npm:spikard-wasm
+npm install @spikard/wasm
+# or with yarn
+yarn add @spikard/wasm
+# or with pnpm
+pnpm add @spikard/wasm
 ```
 
-**From source:**
+### From source
 
 ```bash
 cd packages/wasm
 pnpm install
-pnpm build   # emits ESM to dist/
+pnpm build   # outputs to dist/
 ```
 
-**Requirements:**
-- Node.js 20+ / Deno 1.40+ / Bun 1.0+
-- For Cloudflare Workers: Wrangler 3+
-- For browsers: Modern browser with WASM support
-
 ## Quick Start
 
 ### Cloudflare Workers
 
 ```typescript
-import { Spikard, get, post, createFetchHandler } from "spikard-wasm";
-import { z } from "zod";
+import { Spikard, createFetchHandler, get, post } from "@spikard/wasm";
 
 const app = new Spikard();
 
-get("/hello")(async () => ({
-  message: "Hello from the edge!"
+// Define routes with type safety
+get("/hello", async (req) => ({
+  message: "Hello from the edge!",
+  timestamp: new Date().toISOString(),
 }));
 
-const UserSchema = z.object({
-  name: z.string(),
-  email: z.string().email(),
-});
-
-post("/users", {
-  bodySchema: UserSchema
-})(async (req) => {
-  const user = req.json<z.infer<typeof UserSchema>>();
-  return { id: 1, ...user };
+post("/echo", async (req) => {
+  const body = await req.json();
+  return { echo: body };
 });
 
+// Export as a Cloudflare Worker
 export default {
   fetch: createFetchHandler(app),
 };
@@ -77,663 +75,497 @@ export default {
 ### Deno
 
 ```typescript
-import { Spikard, get } from "npm:spikard-wasm";
+import { Spikard, get, post } from "npm:@spikard/wasm@0.2.1";
 
 const app = new Spikard();
 
-get("/")(async () => ({
-  message: "Hello from Deno!"
+get("/hello", async (req) => ({
+  message: "Hello from Deno",
 }));
 
-Deno.serve({ port: 8000 }, (request) => {
-  return app.handleRequest(request);
+post("/api/users", async (req) => {
+  const data = await req.json();
+  return { created: true, id: Math.random() };
 });
+
+Deno.serve({ port: 8000 }, (request) => app.handleRequest(request));
 ```
 
-### Browser
+### Node.js / Bun
 
 ```typescript
-import { Spikard, get, TestClient } from "spikard-wasm";
+import { Spikard, createFetchHandler, get } from "@spikard/wasm";
 
 const app = new Spikard();
 
-get("/api/data")(async () => ({
-  timestamp: Date.now(),
-  data: [1, 2, 3],
+get("/api/status", async (req) => ({
+  status: "ok",
+  runtime: "node",
 }));
 
-// Use TestClient for in-browser API calls
-const client = new TestClient(app);
-const response = await client.get("/api/data");
-console.log(response.json());
+const server = Bun.serve({
+  port: 3000,
+  fetch: createFetchHandler(app),
+});
+
+console.log(`Server running on http://localhost:${server.port}`);
 ```
 
-## Route Registration
+### Browser (with bundler)
 
-### Decorator-Style Registration
+```typescript
+import { Spikard, get } from "@spikard/wasm";
+
+const app = new Spikard();
 
-Routes are registered using HTTP method decorators:
+get("/worker", async (req) => ({
+  message: "Running in a browser Web Worker",
+}));
+
+// Simulate incoming requests in a worker context
+self.addEventListener("message", async (event) => {
+  const response = await app.handleRequest(event.data.request);
+  self.postMessage({ response });
+});
+```
+
+## API Documentation
+
+### Routing Helpers
 
 ```typescript
-import { get, post, put, patch, del } from "spikard-wasm";
+import { Spikard, get, post, put, patch, delete_, head, options } from "@spikard/wasm";
+
+const app = new Spikard();
 
-get("/users")(async () => {
-  return { users: [] };
+// Define routes with automatic method binding
+get("/users", async (req) => {
+  // GET /users
 });
 
-post("/users")(async (req) => {
-  const user = req.json();
-  return { created: true, user };
+post("/users", async (req) => {
+  // POST /users with body parsing
+  const body = await req.json();
 });
 
-put("/users/:id")(async (req) => {
-  const id = req.pathParams.id;
-  return { id, updated: true };
+put("/users/:id", async (req, { id }) => {
+  // PUT /users/:id with path params
 });
 
-patch("/users/:id")(async (req) => {
-  return { id: req.pathParams.id, patched: true };
+patch("/users/:id", async (req, { id }) => {
+  // PATCH /users/:id
 });
 
-del("/users/:id")(async (req) => {
-  return { deleted: true };
+delete_("/users/:id", async (req, { id }) => {
+  // DELETE /users/:id (note: delete_ to avoid keyword)
 });
 ```
 
-### Manual Registration with `addRoute`
-
-For dynamic route registration:
+### Request Handling
 
 ```typescript
-import { Spikard } from "spikard-wasm";
+// Access request properties
+get("/example", async (req) => {
+  const method = req.method; // "GET"
+  const url = req.url; // Full URL
+  const headers = req.headers; // Headers object
 
-const app = new Spikard();
+  // Parse JSON body
+  const json = await req.json();
 
-async function listUsers() {
-  return { users: [] };
-}
+  // Parse form data
+  const form = await req.formData();
 
-app.addRoute(
-  {
-    method: "GET",
-    path: "/users",
-    handler_name: "listUsers",
-    is_async: true,
-  },
-  listUsers
-);
-```
+  // Get raw text
+  const text = await req.text();
 
-### Supported HTTP Methods
+  // Get ArrayBuffer
+  const buffer = await req.arrayBuffer();
 
-- `GET` - Retrieve resources
-- `POST` - Create resources
-- `PUT` - Replace resources
-- `PATCH` - Update resources
-- `DELETE` - Delete resources
-- `HEAD` - Get headers only
-- `OPTIONS` - Get allowed methods
-- `TRACE` - Echo the request
+  return { received: true };
+});
+```
 
-### With Schemas
+### Response Building
+
+```typescript
+import { Spikard, get, json, status, withHeaders } from "@spikard/wasm";
+
+get("/users", async (req) => {
+  return json(
+    {
+      users: [
+        { id: 1, name: "Alice" },
+        { id: 2, name: "Bob" },
+      ],
+    },
+    {
+      status: 200,
+      headers: {
+        "X-Total-Count": "2",
+        "Cache-Control": "max-age=3600",
+      },
+    }
+  );
+});
 
-Spikard WASM supports **Zod schemas** and **raw JSON Schema objects**.
+get("/created", async (req) => {
+  return status(201, { id: 123, created: true });
+});
+```
 
-**With Zod (recommended - type inference):**
+### Schema Validation with Zod
 
 ```typescript
-import { post } from "spikard-wasm";
 import { z } from "zod";
 
-const CreateUserSchema = z.object({
+const userSchema = z.object({
   name: z.string().min(1),
   email: z.string().email(),
-  age: z.number().int().min(18),
+  age: z.number().int().positive().optional(),
 });
 
-post("/users", {
-  bodySchema: CreateUserSchema,
-  responseSchema: z.object({ id: z.number(), name: z.string() }),
-})(async function createUser(req) {
-  const user = req.json<z.infer<typeof CreateUserSchema>>();
-  return { id: 1, name: user.name };
-});
-```
+post("/users", async (req) => {
+  const body = await req.json();
 
-**With raw JSON Schema:**
+  // Validate with Zod
+  const result = userSchema.safeParse(body);
 
-```typescript
-const userSchema = {
-  type: "object",
-  properties: {
-    name: { type: "string" },
-    email: { type: "string", format: "email" },
-  },
-  required: ["name", "email"],
-};
+  if (!result.success) {
+    return {
+      error: "Invalid user data",
+      issues: result.error.issues,
+    };
+  }
+
+  // result.data is now type-safe
+  const user = result.data;
 
-post("/users", { bodySchema: userSchema })(async function createUser(req) {
-  const user = req.json<{ name: string; email: string }>();
-  return { id: 1, ...user };
+  return json({ id: 1, ...user }, { status: 201 });
 });
 ```
 
-## Request Handling
-
-### Accessing Request Data
+### Testing with TestClient
 
 ```typescript
-get("/search")(async function search(req) {
-  // Path parameters
-  const userId = req.pathParams.id;
+import { describe, it, expect } from "vitest";
+import { Spikard, TestClient, get } from "@spikard/wasm";
 
-  // Query parameters
-  const params = new URLSearchParams(req.queryString);
-  const q = params.get("q");
-  const limit = params.get("limit") ?? "10";
+describe("API routes", () => {
+  const app = new Spikard();
 
-  // Headers
-  const auth = req.headers["authorization"];
-  const userAgent = req.headers["user-agent"];
+  get("/hello", async () => ({
+    message: "Hello",
+  }));
 
-  // Cookies (if available)
-  const sessionId = req.cookies?.session_id;
+  const client = new TestClient(app);
 
-  // Method and path
-  console.log(`${req.method} ${req.path}`);
+  it("returns greeting", async () => {
+    const res = await client.get("/hello");
 
-  return { query: q, limit: parseInt(limit) };
-});
-```
+    expect(res.status).toBe(200);
+    expect(res.json()).toEqual({
+      message: "Hello",
+    });
+  });
 
-### JSON Body
+  it("handles POST with body", async () => {
+    post("/echo", async (req) => {
+      const body = await req.json();
+      return { echo: body };
+    });
 
-```typescript
-post("/users")(async function createUser(req) {
-  const body = req.json<{ name: string; email: string }>();
-  return { id: 1, ...body };
-});
-```
-
-### Form Data
+    const res = await client.post("/echo", { message: "test" });
 
-```typescript
-post("/login")(async function login(req) {
-  const form = req.form();
-  return {
-    username: form.username,
-    password: form.password,
-  };
+    expect(res.status).toBe(200);
+    expect(res.json()).toEqual({
+      echo: { message: "test" },
+    });
+  });
 });
 ```
 
-## Handler Wrappers
-
-For automatic parameter extraction:
+## Bundle Size
 
-```typescript
-import { wrapHandler, wrapBodyHandler } from "spikard-wasm";
-
-interface CreateUserRequest {
-  name: string;
-  email: string;
-}
-
-// Body-only wrapper
-post("/users", {}, wrapBodyHandler(async (body: CreateUserRequest) => {
-  return { id: 1, name: body.name };
-}));
+Optimized for minimal bundle size:
 
-// Full context wrapper
-get("/users/:id", {}, wrapHandler(async (params, query, body) => {
-  return { id: params.id, query };
-}));
-```
+- **Uncompressed**: ~200KB (varies by feature set)
+- **Gzip**: ~60KB
+- **Brotli**: ~45KB
 
-## File Uploads
+Bundle size analysis:
 
-```typescript
-import { UploadFile } from "spikard-wasm";
-
-interface UploadRequest {
-  file: UploadFile;
-  description: string;
-}
-
-post("/upload")(async function upload(req) {
-  const body = req.json<UploadRequest>();
-  const content = body.file.read();
-
-  return {
-    filename: body.file.filename,
-    size: body.file.size,
-    contentType: body.file.contentType,
-  };
-});
+```bash
+# Use source-map-explorer or similar
+npx source-map-explorer 'dist/**/*.js'
 ```
 
-## Streaming Responses
-
-```typescript
-import { StreamingResponse } from "spikard-wasm";
+## WebAssembly Configuration
 
-async function* generateData() {
-  for (let i = 0; i < 10; i++) {
-    yield JSON.stringify({ count: i }) + "\n";
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-}
+Compiled with aggressive optimizations in `Cargo.toml`:
 
-get("/stream")(async function stream() {
-  return new StreamingResponse(generateData(), {
-    statusCode: 200,
-    headers: { "Content-Type": "application/x-ndjson" },
-  });
-});
+```toml
+[package.metadata.wasm-pack.profile.release]
+wasm-opt = ["-O3", "--enable-bulk-memory", "--enable-nontrapping-float-to-int", "--enable-simd"]
 ```
 
-### Server-Sent Events (SSE)
+Build options:
 
-```typescript
-get("/events")(async function events() {
-  async function* sseGenerator() {
-    for (let i = 0; i < 10; i++) {
-      yield `data: ${JSON.stringify({ count: i })}\n\n`;
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-    }
-  }
+```bash
+# Development (debug symbols, fast compile)
+wasm-pack build --dev
 
-  return new StreamingResponse(sseGenerator(), {
-    statusCode: 200,
-    headers: {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      "Connection": "keep-alive",
-    },
-  });
-});
+# Release (optimized, minimal size)
+wasm-pack build --release
 ```
 
-## Configuration
-
-```typescript
-import { Spikard, type ServerConfig } from "spikard-wasm";
+## Code Generation
 
-const app = new Spikard();
+Generate TypeScript applications and tests from OpenAPI/AsyncAPI specifications:
 
-const config: ServerConfig = {
-  enableRequestId: true,
-  maxBodySize: 10 * 1024 * 1024, // 10 MB
-  requestTimeout: 30, // seconds
-  compression: {
-    gzip: true,
-    brotli: true,
-    quality: 9,
-    minSize: 1024,
-  },
-  rateLimit: {
-    perSecond: 100,
-    burst: 200,
-    ipBased: true,
-  },
-  cors: {
-    allowOrigins: ["*"],
-    allowMethods: ["GET", "POST", "PUT", "DELETE"],
-    allowHeaders: ["Content-Type", "Authorization"],
-    maxAge: 86400,
-  },
-  openapi: {
-    enabled: true,
-    title: "Edge API",
-    version: "1.0.0",
-  },
-};
+```bash
+# Generate from OpenAPI spec
+spikard generate openapi \
+  --fixtures ../../testing_data \
+  --output ./generated
 
-// Apply configuration
-app.configure(config);
+# Generate WebSocket handlers from AsyncAPI
+spikard generate asyncapi \
+  --fixtures ../../testing_data/websockets \
+  --output ./generated
 ```
 
 ## Lifecycle Hooks
 
 ```typescript
-app.onRequest(async (request) => {
-  console.log(`${request.method} ${request.path}`);
-  return request;
-});
+import { Spikard, HookTypes } from "@spikard/wasm";
 
-app.preValidation(async (request) => {
-  // Check before validation
-  if (!request.headers["authorization"]) {
-    return {
-      status: 401,
-      body: { error: "Unauthorized" },
-    };
-  }
-  return request;
+const app = new Spikard();
+
+// On every request (before validation)
+app.onRequest(async (req) => {
+  console.log(`${req.method} ${req.url}`);
 });
 
-app.preHandler(async (request) => {
-  // After validation, before handler
-  request.startTime = Date.now();
-  return request;
+// Before handler execution
+app.preHandler(async (req) => {
+  // Add request ID, timing, etc.
 });
 
-app.onResponse(async (response) => {
-  response.headers["X-Frame-Options"] = "DENY";
-  response.headers["X-Content-Type-Options"] = "nosniff";
-  return response;
+// After response
+app.onResponse(async (req, res) => {
+  console.log(`${req.method} ${req.url} -> ${res.status}`);
 });
 
-app.onError(async (response) => {
-  console.error(`Error: ${response.status}`);
-  return response;
+// On error
+app.onError(async (error, req) => {
+  console.error(`Error: ${error.message}`);
+  return { error: "Internal Server Error" };
 });
 ```
 
-## Testing
+## Real-Time Features
 
-### In-Memory Test Client
+### WebSocket Support
 
 ```typescript
-import { TestClient } from "spikard-wasm";
-import { expect } from "vitest";
+import { Spikard, ws } from "@spikard/wasm";
 
 const app = new Spikard();
 
-get("/users/:id")(async (req) => {
-  return { id: req.pathParams.id, name: "Alice" };
+ws("/chat", {
+  onOpen: (socket) => {
+    console.log("Client connected");
+  },
+  onMessage: (socket, data) => {
+    socket.broadcast(data);
+  },
+  onClose: (socket) => {
+    console.log("Client disconnected");
+  },
 });
-
-const client = new TestClient(app);
-
-const response = await client.get("/users/123");
-expect(response.statusCode).toBe(200);
-expect(response.json()).toEqual({ id: "123", name: "Alice" });
 ```
 
-### WebSocket Testing
+### Server-Sent Events (SSE)
 
 ```typescript
-import { ws } from "spikard-wasm";
+import { Spikard, sse } from "@spikard/wasm";
 
-ws("/ws")(async (socket) => {
-  socket.on("message", (msg) => {
-    socket.send({ echo: msg });
-  });
-});
+const app = new Spikard();
 
-const client = new TestClient(app);
-const ws = await client.websocketConnect("/ws");
-await ws.sendJson({ message: "hello" });
-const response = await ws.receiveJson();
-expect(response.echo.message).toBe("hello");
-await ws.close();
-```
+sse("/events", async (req, res) => {
+  res.write("data: " + JSON.stringify({ event: "connected" }) + "\n\n");
 
-### SSE Testing
+  const interval = setInterval(() => {
+    res.write(
+      "data: " + JSON.stringify({ event: "ping", time: Date.now() }) + "\n\n"
+    );
+  }, 5000);
 
-```typescript
-const response = await client.get("/events");
-const sse = new SseStream(response.text());
-const events = sse.eventsAsJson();
-expect(events.length).toBeGreaterThan(0);
+  return () => clearInterval(interval);
+});
 ```
 
-## Type Safety
-
-Full TypeScript support with auto-generated types:
+## Error Handling
 
 ```typescript
-import {
-  type Request,
-  type Response,
-  type ServerConfig,
-  type RouteOptions,
-  type HandlerFunction,
-} from "spikard-wasm";
-```
-
-### Parameter Types
+import { Spikard, HttpError } from "@spikard/wasm";
 
-```typescript
-import { Query, Path, Body, QueryDefault } from "spikard-wasm";
-
-function handler(
-  id: Path<number>,
-  limit: Query<string | undefined>,
-  body: Body<UserType>
-) {
-  // Full type inference
-}
-```
+const app = new Spikard();
 
-## Validation with Zod
+get("/users/:id", async (req, { id }) => {
+  if (!id) {
+    throw new HttpError(400, "User ID is required");
+  }
 
-```typescript
-import { z } from "zod";
+  const user = await fetchUser(id);
 
-const UserSchema = z.object({
-  name: z.string().min(1).max(100),
-  email: z.string().email(),
-  age: z.number().int().min(18).optional(),
-  tags: z.array(z.string()).default([]),
-});
+  if (!user) {
+    throw new HttpError(404, `User ${id} not found`);
+  }
 
-post("/users", { bodySchema: UserSchema })(async function createUser(req) {
-  const user = req.json<z.infer<typeof UserSchema>>();
-  // user is fully typed and validated
   return user;
 });
+
+// Automatic error response
+// 404 -> { error: "User 123 not found", status: 404 }
 ```
 
-## Performance
+## CI Benchmarks (2025-12-20)
+
+Run: `snapshots/benchmarks/20397054933` (commit `25e4fdf`, oha, 50 concurrency, 10s, Linux x86_64).
 
-### Benchmark Results
+| Metric | Value |
+| --- | --- |
+| Avg RPS (all workloads) | 10,658 |
+| Avg latency (ms) | 5.70 |
 
-Latest comparative run (2025-12-20, commit `25e4fdf`, Linux x86_64, AMD EPYC 7763 2c/4t, 50 concurrency, 10s, oha). Full artifacts: `snapshots/benchmarks/20397054933`.
+Category breakdown:
 
-| Binding | Avg RPS (all workloads) | Avg latency (ms) |
+| Category | Avg RPS | Avg latency (ms) |
 | --- | --- | --- |
-| spikard-rust | 55,755 | 1.00 |
-| spikard-node | 24,283 | 2.22 |
-| spikard-php | 20,176 | 2.66 |
-| spikard-python | 11,902 | 4.41 |
-| **spikard-wasm** | **10,658** | **5.70** |
-| spikard-ruby | 8,271 | 6.50 |
+| path-params | 15,841 | 3.19 |
+| multipart | 10,838 | 5.24 |
+| query-params | 8,082 | 6.88 |
+| json-bodies | 6,890 | 7.37 |
+| forms | 6,241 | 8.80 |
 
-WASM bindings deliver solid edge runtime performance—ideal for serverless platforms (Cloudflare Workers, Vercel Edge, Deno Deploy) where startup time and memory efficiency matter more than absolute throughput. Trade-offs vs Node.js bindings:
-- **Advantages:** Portable across all runtimes, smaller bundle size, cold start friendly
-- **Trade-offs:** ~2.3x lower RPS on traditional servers vs native napi-rs bindings
+## Performance Tips
 
-### Runtime Characteristics
+1. **Lazy load routes**: Only define routes you need to minimize WASM size
+2. **Compression**: Enable Brotli/Gzip compression for responses
+3. **Caching**: Use Cache-Control headers for static content
+4. **Streaming**: For large responses, use streaming responses
+5. **Worker threads**: Offload heavy computation to Web Workers
 
-WASM bindings provide:
-- **WebAssembly compilation** for near-native performance in edge runtimes
-- **Zero-copy data structures** where supported by runtime
-- **Shared memory optimization** for large payloads
-- **Streaming support** for efficient data transfer
-- **Tree-shakable ESM** for minimal bundle sizes
-- **Multi-runtime support:** Cloudflare Workers, Deno Deploy, Vercel Edge, browsers, Node.js
+## Environment Variables
 
-### Bundle Size Optimization
+Access environment variables based on runtime:
 
 ```typescript
-// Import only what you need
-import { get, post } from "spikard-wasm/routing";
-import { TestClient } from "spikard-wasm/testing";
-```
-
-## Platform-Specific Examples
-
-### Cloudflare Workers
-
-```typescript
-import { Spikard, get, createFetchHandler } from "spikard-wasm";
-
-const app = new Spikard();
+// Cloudflare Workers
+get("/env", async (req, { env }) => {
+  const apiKey = env.API_KEY;
+  return { apiKey };
+});
 
-get("/")(async (req) => {
-  return {
-    message: "Hello from Cloudflare Workers",
-    cf: req.cf, // Cloudflare-specific properties
-  };
+// Deno
+get("/env", async (req) => {
+  const apiKey = Deno.env.get("API_KEY");
+  return { apiKey };
 });
 
-export default {
-  fetch: createFetchHandler(app),
-};
+// Node.js / Bun
+get("/env", async (req) => {
+  const apiKey = process.env.API_KEY;
+  return { apiKey };
+});
 ```
 
-### Deno Deploy
-
-```typescript
-import { Spikard, get } from "npm:spikard-wasm";
-
-const app = new Spikard();
-
-get("/")(async () => ({ message: "Hello from Deno Deploy" }));
-
-Deno.serve(
-  { port: 8000 },
-  (request: Request) => app.handleRequest(request)
-);
-```
+## Debugging
 
-### Vercel Edge Functions
+Enable debug logging:
 
 ```typescript
-import { Spikard, get, createFetchHandler } from "spikard-wasm";
-
-const app = new Spikard();
+const app = new Spikard({ debug: true });
 
-get("/api/hello")(async () => ({ message: "Hello from Vercel Edge" }));
-
-export const config = { runtime: "edge" };
-export default createFetchHandler(app);
+// Or via environment
+// SPIKARD_DEBUG=1 npm run dev
 ```
 
-### Browser (Service Worker)
+## Examples
 
-```typescript
-import { Spikard, get } from "spikard-wasm";
+Full working examples for different runtimes:
 
-const app = new Spikard();
+- **[Rollup Bundler](https://github.com/Goldziher/spikard/tree/main/examples/wasm-rollup)** - Build with Rollup for browsers and Node.js
+- **[Deno Runtime](https://github.com/Goldziher/spikard/tree/main/examples/wasm-deno)** - Native Deno with zero build step
+- **[Cloudflare Workers](https://github.com/Goldziher/spikard/tree/main/examples/wasm-cloudflare)** - Deploy to the edge with Wrangler
 
-get("/api/data")(async () => ({
-  cached: true,
-  timestamp: Date.now(),
-}));
+Each example includes:
+- Complete TypeScript source code with strict typing
+- Configuration files (tsconfig.json, package.json)
+- Comprehensive README with usage instructions
+- Consistent API routes demonstrating core features
 
-self.addEventListener("fetch", (event) => {
-  if (event.request.url.includes("/api/")) {
-    event.respondWith(app.handleRequest(event.request));
-  }
-});
-```
+Browse all examples: [`examples/`](https://github.com/Goldziher/spikard/tree/main/examples)
 
-## Code Generation
+## Testing
 
-Generate type-safe WASM applications from OpenAPI/AsyncAPI specs:
+Run tests with Vitest:
 
 ```bash
-# Generate from OpenAPI
-spikard generate openapi \
-  --fixtures ../../testing_data \
-  --output ./generated \
-  --target wasm
-
-# Generate from AsyncAPI
-spikard generate asyncapi \
-  --fixtures ../../testing_data/websockets \
-  --output ./generated \
-  --target wasm
+pnpm test              # Run all tests
+pnpm test:watch       # Watch mode
+pnpm test:coverage    # With coverage
 ```
 
-## Examples
-
-See `/examples/wasm/` for more examples:
-- **Basic REST API** - Simple CRUD operations
-- **Cloudflare Workers** - Edge deployment
-- **Deno Deploy** - Deno-specific features
-- **WebSocket Chat** - Real-time communication
-- **SSE Dashboard** - Server-sent events
-- **File Upload** - Multipart form handling
+Test coverage minimum: **80%**
 
-## Development Notes
-
-### Building from Source
+Run integration tests:
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Build WASM module
-cd crates/spikard-wasm
-wasm-pack build --target web
-
-# Build TypeScript wrapper
-cd ../../packages/wasm
-pnpm build
+task test:wasm
+task test:wasm:integration
 ```
 
-### Running Tests
-
-```bash
-# Run all tests
-pnpm test
-
-# Run specific test file
-pnpm test -- routing.spec.ts
-
-# Run with coverage
-pnpm test:coverage
-```
+## Documentation
 
-### Debugging WASM
+- **API Docs**: [docs/api.md](./docs/api.md)
+- **Architecture**: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+- **Architecture Decision Records**: [../../docs/adr/](../../docs/adr/)
+  - [ADR 0001: Architecture & Layering](../../docs/adr/0001-architecture.md)
+  - [ADR 0002: Tower-HTTP & Middleware](../../docs/adr/0002-runtime-and-middleware.md)
+  - [ADR 0006: Async & Streaming](../../docs/adr/0006-async-and-streaming.md)
 
-Enable WASM debugging in your browser:
-1. Open DevTools
-2. Enable "WebAssembly Debugging" in Experiments
-3. Reload the page
-4. Set breakpoints in WASM code
+## TypeScript Support
 
-## Differences from Node.js Bindings
+Full TypeScript support with strict type checking:
 
-### What's the Same
-- Routing API (same decorators and methods)
-- Request/Response types
-- Validation with Zod/JSON Schema
-- Lifecycle hooks
-- Test client API
+```bash
+pnpm typecheck    # Run tsc
+pnpm lint         # Run Biome
+```
 
-### What's Different
-- **No native modules** - Pure WASM, no Node.js addons
-- **Fetch API only** - No Node.js `http` module
-- **Smaller bundle** - Tree-shakable ESM exports
-- **Platform-agnostic** - Works in browsers, Deno, Workers
-- **Edge-optimized** - Designed for edge runtimes
+Generated `.d.ts` files via wasm-bindgen for complete IDE support.
 
-### When to Use WASM vs Node.js
+## Contributing
 
-**Use WASM bindings when:**
-- Deploying to edge runtimes (Cloudflare, Vercel, Deno Deploy)
-- Running in browsers or service workers
-- Need maximum portability across platforms
-- Want smallest possible bundle size
+Contributions welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md)
 
-**Use Node.js bindings when:**
-- Running on traditional Node.js servers
-- Need native performance (napi-rs is ~10% faster)
-- Using Node.js-specific features (file system, child processes)
-- Maximum throughput is critical
+Code standards:
+- TypeScript 5.x with strict mode enabled
+- Biome for linting and formatting
+- Vitest for testing
+- 80%+ test coverage required
 
-## Documentation
+## Related Packages
 
-- [Main Project README](../../README.md)
-- [Contributing Guide](../../CONTRIBUTING.md)
-- [TypeScript API Reference](./src/index.ts)
-- [Architecture Decision Records](../../docs/adr/)
+- **@spikard/node**: [npm.im/@spikard/node](https://npm.im/@spikard/node) - Node.js native bindings
+- **spikard**: [pypi.org/project/spikard](https://pypi.org/project/spikard) - Python bindings
+- **spikard**: [rubygems.org/gems/spikard](https://rubygems.org/gems/spikard) - Ruby bindings
+- **spikard/spikard**: [packagist.org/packages/spikard/spikard](https://packagist.org/packages/spikard/spikard) - PHP bindings
+- **spikard**: [crates.io/crates/spikard](https://crates.io/crates/spikard) - Rust native
 
 ## License
 
-MIT
+MIT - see [LICENSE](LICENSE) file