@spikard/node 0.9.1 → 0.10.1

package/README.md

@@ -1,39 +1,41 @@
-# spikard-node
+# Spikard for Node.js
 
-High-performance Node.js bindings for Spikard HTTP framework via napi-rs.
+[![Documentation](https://img.shields.io/badge/docs-spikard.dev-blue)](https://spikard.dev)
+[![Crates.io](https://img.shields.io/crates/v/spikard.svg?color=blue)](https://crates.io/crates/spikard)
+[![PyPI](https://img.shields.io/pypi/v/spikard.svg?color=blue)](https://pypi.org/project/spikard/)
+[![npm](https://img.shields.io/npm/v/@spikard/node.svg?color=blue)](https://www.npmjs.com/package/@spikard/node)
+[![Gem](https://img.shields.io/gem/v/spikard.svg?color=blue)](https://rubygems.org/gems/spikard)
+[![Packagist](https://img.shields.io/packagist/v/spikard/spikard.svg?color=blue)](https://packagist.org/packages/spikard/spikard)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
 
-## Status & Badges
+High-performance HTTP framework for Node.js powered by a Rust core. Provides type-safe routing, validation, middleware, and testing via **napi-rs** bindings with zero-copy JSON conversion.
 
-[![npm](https://img.shields.io/npm/v/spikard.svg)](https://www.npmjs.com/package/spikard)
-[![npm downloads](https://img.shields.io/npm/dm/spikard.svg)](https://www.npmjs.com/package/spikard)
-[![Crates.io](https://img.shields.io/crates/v/spikard-node.svg)](https://crates.io/crates/spikard-node)
-[![Documentation](https://docs.rs/spikard-node/badge.svg)](https://docs.rs/spikard-node)
-[![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)
+## Features
 
-## Overview
-
-High-performance TypeScript/Node.js web framework with a Rust core. Build REST APIs with type-safe routing backed by Axum and Tower-HTTP.
+- **Rust-Powered Performance**: Native speed via Tokio with dedicated thread pool
+- **Full TypeScript Support**: Auto-generated types from napi-rs FFI bindings
+- **Zero-Copy JSON**: Direct conversion without serialization overhead
+- **Tower-HTTP Middleware**: Compression, rate limiting, timeouts, auth, CORS, request IDs
+- **Schema Validation**: Zod integration for request/response validation
+- **Lifecycle Hooks**: onRequest, preValidation, preHandler, onResponse, onError
+- **Testing**: TestClient for HTTP, WebSocket, and SSE assertions
 
 ## Installation
 
-**From source (currently):**
-
 ```bash
-cd packages/node
-pnpm install
-pnpm build
+npm install @spikard/node
+# or
+pnpm add @spikard/node
 ```
 
-**Requirements:**
-- Node.js 20+
-- pnpm 10+
-- Rust toolchain (for building from source)
+**Requirements:** Node.js 20+
+
+For building from source, see the [main README](../../README.md#development).
 
 ## Quick Start
 
 ```typescript
-import { Spikard, type Request } from "spikard";
+import { Spikard, type Request } from "@spikard/node";
 import { z } from "zod";
 
 const UserSchema = z.object({
@@ -56,12 +58,7 @@ const createUser = async (req: Request): Promise<User> => {
 };
 
 app.addRoute(
-  {
-    method: "GET",
-    path: "/users/:id",
-    handler_name: "getUser",
-    is_async: true,
-  },
+  { method: "GET", path: "/users/:id", handler_name: "getUser", is_async: true },
   getUser,
 );
 
@@ -77,261 +74,127 @@ app.addRoute(
   createUser,
 );
 
-if (require.main === module) {
-  app.run({ port: 8000 });
-}
+app.run({ port: 8000 });
 ```
 
-## Route Registration
+## Routing & Schemas
 
-### Manual Registration with `addRoute`
-
-Routes are registered manually using `app.addRoute(metadata, handler)`:
+Routes support Zod validation (recommended) or raw JSON Schema:
 
 ```typescript
-import { Spikard, type Request } from "spikard";
+import { Spikard, type Request } from "@spikard/node";
+import { z } from "zod";
 
 const app = new Spikard();
 
-async function listUsers(_req: Request): Promise<{ users: unknown[] }> {
-  return { users: [] };
-}
-
-async function createUser(_req: Request): Promise<{ created: boolean }> {
-  return { created: true };
-}
+const UserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
 
-app.addRoute(
-  {
-    method: "GET",
-    path: "/users",
-    handler_name: "listUsers",
-    is_async: true,
-  },
-  listUsers
-);
+const createUser = async (req: Request) => {
+  const user = req.json();
+  return { id: 1, ...user };
+};
 
 app.addRoute(
   {
     method: "POST",
     path: "/users",
     handler_name: "createUser",
+    request_schema: UserSchema,
+    response_schema: UserSchema,
     is_async: true,
   },
-  createUser
+  createUser,
 );
 ```
 
-### Supported HTTP Methods
+Supported HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE.
 
-- `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
+## Dependency Injection
 
-### With Schemas
-
-Spikard supports **Zod schemas** and **raw JSON Schema objects**.
-
-**With Zod (recommended - type inference):**
+Register values or factories and access them via `request.dependencies`:
 
 ```typescript
-import { post } from "spikard";
-import { z } from "zod";
-
-const CreateUserSchema = z.object({
-  name: z.string().min(1),
-  email: z.string().email(),
-  age: z.number().int().min(18),
-});
-
-post("/users", {
-  bodySchema: CreateUserSchema,
-  responseSchema: z.object({ id: z.number(), name: z.string() }),
-})(async function createUser(req) {
-  const user = req.json();
-  return { id: 1, name: user.name };
-});
-```
+const app = new Spikard();
 
-**With raw JSON Schema:**
+app.provide("config", { dbUrl: "postgresql://localhost/app" });
+app.provide(
+  "dbPool",
+  async ({ config }) => ({ url: config.dbUrl, driver: "pool" }),
+  { dependsOn: ["config"], singleton: true },
+);
 
-```typescript
-const userSchema = {
-  type: "object",
-  properties: {
-    name: { type: "string" },
-    email: { type: "string", format: "email" },
+app.addRoute(
+  { method: "GET", path: "/stats", handler_name: "stats", is_async: true },
+  async (req) => {
+    const deps = req.dependencies ?? {};
+    return { db: deps.dbPool?.url, env: deps.config?.dbUrl };
   },
-  required: ["name", "email"],
-};
-
-post("/users", { bodySchema: userSchema })(async function createUser(req) {
-  const user = req.json<{ name: string; email: string }>();
-  return { id: 1, ...user };
-});
+);
 ```
 
 ## Request Handling
 
-### Accessing Request Data
+Access query, path params, headers, cookies, and body:
 
 ```typescript
-get("/search")(async function search(req) {
-  // Query parameters
-  const params = new URLSearchParams(req.queryString);
-  const q = params.get("q");
-  const limit = params.get("limit") ?? "10";
-
-  // Headers
-  const auth = req.headers["authorization"];
-
-  // Method and path
-  console.log(`${req.method} ${req.path}`);
-
-  return { query: q, limit: parseInt(limit) };
-});
-```
-
-### JSON Body
-
-```typescript
-post("/users")(async function createUser(req) {
-  const body = req.json<{ name: string; email: string }>();
-  return { id: 1, ...body };
-});
-```
-
-### Form Data
-
-```typescript
-post("/login")(async function login(req) {
+get("/search")(async (req) => {
+  const q = req.query.q;
+  const id = req.params.id;
+  const auth = req.headers.authorization;
+  const session = req.cookies.session_id;
+  const body = req.json<{ name: string }>();
   const form = req.form();
-  return {
-    username: form.username,
-    password: form.password,
-  };
+  return { query: q, id };
 });
 ```
 
-## Handler Wrappers
-
-For automatic parameter extraction:
-
-```typescript
-import { wrapHandler, wrapBodyHandler } from "spikard";
-
-// Body-only wrapper
-post("/users", {}, wrapBodyHandler(async (body: CreateUserRequest) => {
-  return { id: 1, name: body.name };
-}));
-
-// Full context wrapper
-get(
-  "/users/:id",
-  {},
-  wrapHandler(async (params: { id: string }, query: Record<string, unknown>) => {
-    return { id: Number(params.id), query };
-  }),
-);
-```
-
-## File Uploads
+## Advanced Features
 
+**File Uploads:**
 ```typescript
-import { UploadFile } from "spikard";
-
-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,
-  };
+post("/upload")(async (req) => {
+  const body = req.json<{ file: UploadFile }>();
+  return { filename: body.file.filename, size: body.file.size };
 });
 ```
 
-## Streaming Responses
-
+**Streaming Responses:**
 ```typescript
-import { StreamingResponse } from "spikard";
-
-async function* generateData() {
+get("/stream")(async function* () {
   for (let i = 0; i < 10; i++) {
     yield JSON.stringify({ count: i }) + "\n";
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    await new Promise(r => setTimeout(r, 100));
   }
-}
-
-get("/stream")(async function stream() {
-  return new StreamingResponse(generateData(), {
-    statusCode: 200,
-    headers: { "Content-Type": "application/x-ndjson" },
-  });
 });
 ```
 
 ## Configuration
 
-```typescript
-import { Spikard, runServer, type ServerConfig } from "spikard";
-
-const app = new Spikard();
+Configure middleware, compression, rate limiting, and authentication:
 
+```typescript
 const config: ServerConfig = {
-  host: "0.0.0.0",
   port: 8080,
   workers: 4,
-  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,
-  },
-  jwtAuth: {
-    secret: "your-secret-key",
-    algorithm: "HS256",
-  },
-  staticFiles: [
-    {
-      directory: "./public",
-      routePrefix: "/static",
-      indexFile: true,
-    },
-  ],
-  openapi: {
-    enabled: true,
-    title: "My API",
-    version: "1.0.0",
-    swaggerUiPath: "/docs",
-    redocPath: "/redoc",
-  },
+  maxBodySize: 10 * 1024 * 1024,
+  requestTimeout: 30,
+  compression: { gzip: true, brotli: true, minSize: 1024 },
+  rateLimit: { perSecond: 100, burst: 200 },
+  jwtAuth: { secret: "key", algorithm: "HS256" },
 };
 
-runServer(app, config);
+app.run(config);
 ```
 
+See [ServerConfig](../../docs/adr/0002-runtime-and-middleware.md) for all options.
+
 ## Lifecycle Hooks
 
+Execute code at key request/response stages:
+
 ```typescript
 app.onRequest(async (request) => {
   console.log(`${request.method} ${request.path}`);
@@ -339,171 +202,82 @@ app.onRequest(async (request) => {
 });
 
 app.preValidation(async (request) => {
-  // Check before validation
   if (!request.headers["authorization"]) {
-    return {
-      status: 401,
-      body: { error: "Unauthorized" },
-    };
+    return { status: 401, body: { error: "Unauthorized" } };
   }
   return request;
 });
 
-app.preHandler(async (request) => {
-  // After validation, before handler
-  return request;
-});
-
 app.onResponse(async (response) => {
   response.headers["X-Frame-Options"] = "DENY";
   return response;
 });
-
-app.onError(async (response) => {
-  console.error(`Error: ${response.status}`);
-  return response;
-});
-```
-
-## Background Tasks
-
-```typescript
-import * as background from "spikard/background";
-
-post("/process")(async function process(req) {
-  const data = req.json();
-
-  background.run(() => {
-    // Heavy processing after response sent
-    processData(data);
-  });
-
-  return { status: "processing" };
-});
 ```
 
 ## Testing
 
+Use TestClient for HTTP, WebSocket, and SSE testing:
+
 ```typescript
-import { TestClient } from "spikard";
+import { TestClient } from "@spikard/node";
 import { expect } from "vitest";
 
-const app = {
-  routes: [
-    /* ... */
-  ],
-  handlers: {
-    /* ... */
-  },
-};
-
 const client = new TestClient(app);
 
+// HTTP testing
 const response = await client.get("/users/123");
 expect(response.statusCode).toBe(200);
-expect(response.json()).toEqual({ id: "123", name: "Alice" });
-```
 
-### WebSocket Testing
-
-```typescript
+// WebSocket testing
 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 Testing
 
-```typescript
-const response = await client.get("/events");
-const sse = new SseStream(response.text());
-const events = sse.eventsAsJson();
-expect(events.length).toBeGreaterThan(0);
+// SSE testing
+const sse = await client.get("/events");
 ```
 
-## Type Safety
-
-Full TypeScript support with auto-generated types:
-
-```typescript
-import {
-  type Request,
-  type Response,
-  type ServerConfig,
-  type RouteOptions,
-  type HandlerFunction,
-} from "spikard";
-```
-
-### Parameter Types
-
-```typescript
-import { Query, Path, Body, QueryDefault } from "spikard";
-
-function handler(
-  id: Path<number>,
-  limit: Query<string | undefined>,
-  body: Body<UserType>
-) {
-  // Full type inference
-}
-```
-
-## Validation with Zod
-
-```typescript
-import { z } from "zod";
-
-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([]),
-});
-
-post("/users", { bodySchema: UserSchema })(async function createUser(req) {
-  const user = req.json<z.infer<typeof UserSchema>>();
-  // user is fully typed and validated
-  return user;
-});
-```
-
-## Running the Server
-
-```typescript
-// Simple start
-app.run({ port: 8000 });
+## Performance
 
-// With full configuration
-import { runServer } from "spikard";
+Benchmarked across 34 workloads at 100 concurrency ([methodology](../../docs/benchmarks/methodology.md)):
 
-runServer(app, {
-  host: "0.0.0.0",
-  port: 8080,
-  workers: 4,
-});
-```
+| Framework | Avg RPS | P50 (ms) | P99 (ms) |
+|-----------|--------:|----------:|----------:|
+| **spikard (Bun)** | 49,460 | 2.18 | 4.21 |
+| **spikard (Node)** | 46,160 | 2.18 | 3.35 |
+| elysia | 44,326 | 2.41 | 4.68 |
+| kito | 36,958 | 4.94 | 12.86 |
+| fastify | 19,167 | 6.74 | 14.76 |
+| morojs | 14,196 | 6.44 | 12.61 |
+| hono | 10,928 | 10.91 | 18.62 |
 
-## Performance
+Spikard Node is **1.2x faster** than Kito and **2.4x faster** than Fastify.
 
-Node.js bindings use:
-- **napi-rs** for zero-copy FFI
+Key optimizations:
+- **napi-rs** zero-copy FFI bindings
+- **Dedicated Tokio runtime** without blocking Node event loop
+- **Zero-copy JSON** conversion (30-40% faster than JSON.parse)
 - **ThreadsafeFunction** for async JavaScript callbacks
-- Dedicated Tokio runtime (doesn't block Node event loop)
-- Direct type conversion without JSON serialization overhead
 
 ## Examples
 
-See `/examples/node/` for more examples.
+See [examples/](../../examples/) for runnable projects. Code generation is supported for OpenAPI, GraphQL, AsyncAPI, and JSON-RPC specifications.
 
 ## Documentation
 
-- [Main Project README](../../README.md)
-- [Contributing Guide](../../CONTRIBUTING.md)
-- [TypeScript API Reference](./src/index.ts)
+Full documentation at [spikard.dev](https://spikard.dev). See also [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+## Ecosystem
+
+Spikard is available across multiple languages:
+
+| Platform | Package | Status |
+|----------|---------|--------|
+| **Node.js** | [@spikard/node](https://www.npmjs.com/package/@spikard/node) | Stable |
+| **Python** | [spikard](https://pypi.org/project/spikard/) | Stable |
+| **Rust** | [spikard](https://crates.io/crates/spikard) | Stable |
+| **Ruby** | [spikard](https://rubygems.org/gems/spikard) | Stable |
+| **PHP** | [spikard/spikard](https://packagist.org/packages/spikard/spikard) | Stable |
 
 ## License
 
-MIT
+MIT - See [LICENSE](../../LICENSE) for details