@spikard/node 0.12.0 → 0.15.1

package/README.md

@@ -1,66 +1,91 @@
-# Spikard for Node.js
+# Spikard
+
+<div align="center" style="display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin: 20px 0;">
+  <!-- Language Bindings -->
+  <a href="https://crates.io/crates/spikard">
+    <img src="https://img.shields.io/crates/v/spikard?label=Rust&color=007ec6" alt="Rust">
+  </a>
+  <a href="https://pypi.org/project/spikard/">
+    <img src="https://img.shields.io/pypi/v/spikard?label=Python&color=007ec6" alt="Python">
+  </a>
+  <a href="https://www.npmjs.com/package/@spikard/node">
+    <img src="https://img.shields.io/npm/v/@spikard/node?label=Node.js&color=007ec6" alt="Node.js">
+  </a>
+  <a href="https://www.npmjs.com/package/@spikard/wasm">
+    <img src="https://img.shields.io/npm/v/@spikard/wasm?label=WASM&color=007ec6" alt="WASM">
+  </a>
+  <a href="https://rubygems.org/gems/spikard">
+    <img src="https://img.shields.io/gem/v/spikard?label=Ruby&color=007ec6" alt="Ruby">
+  </a>
+  <a href="https://packagist.org/packages/spikard/spikard">
+    <img src="https://img.shields.io/packagist/v/spikard/spikard?label=PHP&color=007ec6" alt="PHP">
+  </a>
+  <a href="https://hex.pm/packages/spikard">
+    <img src="https://img.shields.io/hexpm/v/spikard?label=Elixir&color=007ec6" alt="Elixir">
+  </a>
+  <a href="https://central.sonatype.com/artifact/dev.spikard/spikard">
+    <img src="https://img.shields.io/maven-central/v/dev.spikard/spikard?label=Java&color=007ec6" alt="Java">
+  </a>
+  <a href="https://github.com/Goldziher/spikard/releases">
+    <img src="https://img.shields.io/github/v/tag/Goldziher/spikard?label=Go&color=007ec6" alt="Go">
+  </a>
+  <a href="https://www.nuget.org/packages/Spikard/">
+    <img src="https://img.shields.io/nuget/v/Spikard?label=C%23&color=007ec6" alt="C#">
+  </a>
+
+  <!-- Project Info -->
+  <a href="https://github.com/Goldziher/spikard/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-007ec6" alt="License">
+  </a>
+  <a href="https://github.com/Goldziher/spikard">
+    <img src="https://img.shields.io/badge/docs-GitHub-007ec6" alt="Documentation">
+  </a>
+</div>
+
+Rust-centric polyglot HTTP framework with OpenAPI/AsyncAPI/GraphQL/JSON-RPC codegen, tower-http middleware, and fixture-driven cross-language testing. Native NAPI-RS bindings for Node.js with TypeScript type definitions.
 
-[![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)
-[![Hex.pm](https://img.shields.io/hexpm/v/spikard.svg?color=blue)](https://hex.pm/packages/spikard)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+## Installation
 
-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:**
 
-## Features
+```bash
+npm install @spikard/node
+```
 
-- **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
+**pnpm:**
 
 ```bash
-npm install @spikard/node
-# or
 pnpm add @spikard/node
 ```
 
-**Requirements:** Node.js 20+
+**yarn:**
+
+```bash
+yarn add @spikard/node
+```
 
-For building from source, see the [main README](../../README.md#development).
+### System Requirements
+
+- **Node.js 18+** required (NAPI-RS native bindings)
+- Pre-built binaries for Linux (x86_64), macOS (arm64, x86_64), Windows (x86_64)
 
 ## Quick Start
 
 ```typescript
-import { Spikard, type Request } from "@spikard/node";
+import { Spikard, type Request } from "spikard";
 import { z } from "zod";
 
-const UserSchema = z.object({
-  id: z.number(),
-  name: z.string(),
-  email: z.string().email(),
-});
-
+const UserSchema = z.object({ id: z.number(), name: z.string() });
 type User = z.infer<typeof UserSchema>;
 
 const app = new Spikard();
 
-const getUser = async (req: Request): Promise<User> => {
-  const id = Number(req.params["id"] ?? 0);
-  return { id, name: "Alice", email: "alice@example.com" };
-};
-
-const createUser = async (req: Request): Promise<User> => {
-  return UserSchema.parse(req.json());
-};
-
 app.addRoute(
   { method: "GET", path: "/users/:id", handler_name: "getUser", is_async: true },
-  getUser,
+  async (req: Request): Promise<User> => {
+    const id = Number(req.params["id"] ?? 0);
+    return { id, name: "Alice" };
+  },
 );
 
 app.addRoute(
@@ -72,32 +97,42 @@ app.addRoute(
     response_schema: UserSchema,
     is_async: true,
   },
-  createUser,
+  async (req: Request): Promise<User> => UserSchema.parse(req.json()),
 );
 
-app.run({ port: 8000 });
+if (require.main === module) {
+  app.run({ port: 8000 });
+}
 ```
 
-## Routing & Schemas
+## Features
+
+- **HTTP routing** — type-safe route definitions with path, query, and body parameter validation
+- **OpenAPI / AsyncAPI / GraphQL / JSON-RPC** — code generation and spec parsing built in
+- **Tower middleware** — compression, rate limiting, timeouts, auth (JWT/API key), static files
+- **Lifecycle hooks** — `onRequest`, `preValidation`, `preHandler`, `onResponse`, `onError`
+- **Fixture-driven testing** — shared JSON fixtures drive tests across all language bindings
+- **Polyglot** — single Rust core, thin bindings for Python, Node.js, Ruby, PHP, Elixir, Go, Java, C#, Kotlin, Dart, Gleam, WASM, Swift, Zig, and C FFI
 
-Routes support Zod validation (recommended) or raw JSON Schema:
+## Routing
 
 ```typescript
-import { Spikard, type Request } from "@spikard/node";
+import { Spikard, type Request } from "spikard";
 import { z } from "zod";
 
+const UserSchema = z.object({ id: z.number(), name: z.string() });
+type User = z.infer<typeof UserSchema>;
+
 const app = new Spikard();
 
-const UserSchema = z.object({
-  name: z.string().min(1),
-  email: z.string().email(),
-});
+const health = async (): Promise<{ status: string }> => ({ status: "ok" });
 
-const createUser = async (req: Request) => {
-  const user = req.json();
-  return { id: 1, ...user };
+const createUser = async (req: Request): Promise<User> => {
+  return UserSchema.parse(req.json());
 };
 
+app.addRoute({ method: "GET", path: "/health", handler_name: "health", is_async: true }, health);
+
 app.addRoute(
   {
     method: "POST",
@@ -111,175 +146,60 @@ app.addRoute(
 );
 ```
 
-Supported HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE.
+## Validation
 
-## Dependency Injection
+```typescript
+import { Spikard, type Request } from "spikard";
+import { z } from "zod";
 
-Register values or factories and access them via `request.dependencies`:
+const PaymentSchema = z.object({
+  id: z.string().uuid(),
+  amount: z.number().positive(),
+});
+type Payment = z.infer<typeof PaymentSchema>;
 
-```typescript
 const app = new Spikard();
 
-app.provide("config", { dbUrl: "postgresql://localhost/app" });
-app.provide(
-  "dbPool",
-  async ({ config }) => ({ url: config.dbUrl, driver: "pool" }),
-  { dependsOn: ["config"], singleton: true },
-);
+const createPayment = async (req: Request): Promise<Payment> => {
+  return PaymentSchema.parse(req.json());
+};
 
 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 };
+  {
+    method: "POST",
+    path: "/payments",
+    handler_name: "createPayment",
+    request_schema: PaymentSchema,
+    response_schema: PaymentSchema,
+    is_async: true,
   },
+  createPayment,
 );
 ```
 
-## Request Handling
-
-Access query, path params, headers, cookies, and body:
-
-```typescript
-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 { query: q, id };
-});
-```
-
-## Advanced Features
+## Middleware
 
-**File Uploads:**
 ```typescript
-post("/upload")(async (req) => {
-  const body = req.json<{ file: UploadFile }>();
-  return { filename: body.file.filename, size: body.file.size };
-});
-```
-
-**Streaming Responses:**
-```typescript
-get("/stream")(async function* () {
-  for (let i = 0; i < 10; i++) {
-    yield JSON.stringify({ count: i }) + "\n";
-    await new Promise(r => setTimeout(r, 100));
-  }
-});
-```
-
-## Configuration
-
-Configure middleware, compression, rate limiting, and authentication:
+import { Spikard, type Request } from "spikard";
 
-```typescript
-const config: ServerConfig = {
-  port: 8080,
-  workers: 4,
-  maxBodySize: 10 * 1024 * 1024,
-  requestTimeout: 30,
-  compression: { gzip: true, brotli: true, minSize: 1024 },
-  rateLimit: { perSecond: 100, burst: 200 },
-  jwtAuth: { secret: "key", algorithm: "HS256" },
-};
-
-app.run(config);
-```
-
-See [ServerConfig](../../docs/adr/0002-runtime-and-middleware.md) for all options.
-
-## Lifecycle Hooks
-
-Execute code at key request/response stages:
+const app = new Spikard();
 
-```typescript
-app.onRequest(async (request) => {
+app.onRequest(async (request: Request): Promise<Request> => {
   console.log(`${request.method} ${request.path}`);
   return request;
 });
-
-app.preValidation(async (request) => {
-  if (!request.headers["authorization"]) {
-    return { status: 401, body: { error: "Unauthorized" } };
-  }
-  return request;
-});
-
-app.onResponse(async (response) => {
-  response.headers["X-Frame-Options"] = "DENY";
-  return response;
-});
 ```
 
-## Testing
-
-Use TestClient for HTTP, WebSocket, and SSE testing:
-
-```typescript
-import { TestClient } from "@spikard/node";
-import { expect } from "vitest";
-
-const client = new TestClient(app);
-
-// HTTP testing
-const response = await client.get("/users/123");
-expect(response.statusCode).toBe(200);
-
-// WebSocket testing
-const ws = await client.websocketConnect("/ws");
-await ws.sendJson({ message: "hello" });
-
-// SSE testing
-const sse = await client.get("/events");
-```
-
-## Performance
-
-Benchmarked across 34 workloads at 100 concurrency ([methodology](../../docs/benchmarks/methodology.md)):
-
-| 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 |
-
-Spikard Node is **1.2x faster** than Kito and **2.4x faster** than Fastify.
-
-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
-
-## Examples
-
-See [examples/](../../examples/) for runnable projects. Code generation is supported for OpenAPI, GraphQL, AsyncAPI, and JSON-RPC specifications.
-
 ## Documentation
 
-Full documentation at [spikard.dev](https://spikard.dev). See also [CONTRIBUTING.md](../../CONTRIBUTING.md).
-
-## Ecosystem
+- **[Repository](https://github.com/Goldziher/spikard)** — source code, examples, and contributing guide
+- **[Examples](https://github.com/Goldziher/spikard/tree/main/examples)** — working examples per language
+- **[Issues](https://github.com/Goldziher/spikard/issues)** — bug reports and feature requests
 
-Spikard is available across multiple languages:
+## Contributing
 
-| 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 |
-| **Elixir** | [spikard](https://hex.pm/packages/spikard) | Stable |
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/Goldziher/spikard/blob/main/CONTRIBUTING.md).
 
 ## License
 
-MIT - See [LICENSE](../../LICENSE) for details
+MIT License — see [LICENSE](https://github.com/Goldziher/spikard/blob/main/LICENSE) for details.