@fresho/router 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fresho.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,418 @@
 # @fresho/router
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Type-safe routing for Cloudflare Workers, Deno, Bun, and Node.js. Define routes once, get validated handlers, typed clients, and OpenAPI docs.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+**~2KB gzipped. Zero dependencies.**
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```typescript
+import { route, router } from "@fresho/router";
 
-## Purpose
+const api = router({
+	health: router({
+		get: async () => ({ status: "ok" }),
+	}),
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@fresho/router`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+	users: router({
+		// GET /users - list with optional limit
+		get: route({
+			query: { limit: "number?" },
+			handler: async (c) => db.users.list(c.query.limit),
+		}),
 
-## What is OIDC Trusted Publishing?
+		// POST /users - create user
+		post: route({
+			body: { name: "string", email: "string" },
+			handler: async (c) => db.users.create(c.body),
+		}),
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+		// GET /users/:id - get by id
+		$id: router({
+			// Bare function shorthand instead of `route` type
+			get: async (c) => db.users.get(c.path.id),
+		}),
+	}),
+});
 
-## Setup Instructions
+// Cloudflare Worker / Deno / Bun
+export default { fetch: api.handler() };
+```
 
-To properly configure OIDC trusted publishing for this package:
+## Features
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+- **Type-safe path params** — `$id` creates dynamic segments, typed via `route.ctx<>()`
+- **Schema validation** — query and body validated at runtime, typed at compile time
+- **Property-based routing** — property names become URL segments
+- **Typed HTTP client** — call your API with full type safety
+- **Typed local client** — test handlers directly without HTTP
+- **OpenAPI generation** — auto-generate docs from your routes
+- **Middleware** — cors, auth, rate limiting, and more
+- **Streaming** — SSE and JSON lines helpers
+- **HTTP-compliant** — automatic HEAD support for GET routes
+- **Zero dependencies** — just Web APIs
 
-## DO NOT USE THIS PACKAGE
+## Installation
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```bash
+npm install @fresho/router
+```
 
-## More Information
+## Path Convention
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+Property names become URL path segments:
 
----
+```typescript
+router({
+  api: router({           // /api
+    users: router({       // /api/users
+      get: async () => ...,
+      $id: router({       // /api/users/:id
+        get: async (c) => c.path.id,
+      }),
+    }),
+  }),
+});
+```
 
-**Maintained for OIDC setup purposes only**
+- Regular properties → static segments (`users` → `/users`)
+- `$param` properties → dynamic segments (`$id` → `/:id`)
+- HTTP methods (`get`, `post`, etc.) → handlers at that path
+
+## Schemas
+
+Define query and body schemas using shorthand syntax:
+
+```typescript
+// Primitives
+{ name: 'string' }      // required string
+{ age: 'number' }       // required number (coerced from string in query)
+{ active: 'boolean' }   // required boolean (accepts "true"/"false"/"1"/"0")
+
+// Optional (append ?)
+{ name: 'string?' }     // optional string
+
+// Arrays
+{ tags: 'string[]' }    // string array
+{ scores: 'number[]' }  // number array
+
+// Nested objects
+{
+  address: {
+    street: 'string',
+    city: 'string',
+    zip: 'number?'
+  }
+}
+```
+
+Types are automatically inferred:
+
+```typescript
+post: route({
+	body: {
+		title: "string",
+		tags: "string[]",
+		metadata: { priority: "number", draft: "boolean?" },
+	},
+	handler: async (c) => {
+		c.body.title; // string
+		c.body.tags; // string[]
+		c.body.metadata; // { priority: number, draft: boolean | undefined }
+	},
+});
+```
+
+## Typing Best Practices
+
+**Schemas** (`query`/`body`) provide runtime validation AND type inference:
+
+```typescript
+get: route({
+	query: { limit: "number?" },
+	handler: async (c) => c.query.limit, // number | undefined
+});
+```
+
+**Context** (`route.ctx<T>()`) provides types only for things schemas don't cover:
+
+```typescript
+interface MyContext {
+	path: { id: string }; // from $id segment
+	env: { DB: Database }; // runtime environment
+	user: { name: string }; // from auth middleware
+}
+
+get: route.ctx<MyContext>()({
+	query: { include: "string?" }, // validated
+	handler: async (c) => ({
+		id: c.path.id, // from context
+		user: c.user.name, // from context
+		include: c.query.include, // from schema
+	}),
+});
+```
+
+**Don't add explicit type annotations to handlers** — let types flow from schemas and context:
+
+```typescript
+// GOOD: types inferred
+handler: async (c) => c.query.limit;
+
+// BAD: redundant annotation
+handler: async (c: { query: { limit?: number } }) => c.query.limit;
+```
+
+## Nested Routers
+
+Compose routers:
+
+```typescript
+const users = router({
+  get: async () => db.users.list(),
+  post: route({
+    body: { name: 'string' },
+    handler: async (c) => db.users.create(c.body),
+  }),
+  $id: router({
+    get: async (c) => db.users.get(c.path.id),
+    delete: async (c) => db.users.delete(c.path.id),
+  }),
+});
+
+const api = router({
+  users,
+  posts: router({ ... }),
+});
+
+// Routes:
+// GET    /users
+// POST   /users
+// GET    /users/:id
+// DELETE /users/:id
+```
+
+## Middleware
+
+Add middleware to routers:
+
+```typescript
+import { router, route } from "@fresho/router";
+import { cors, errorHandler, jwtAuth } from "@fresho/router/middleware";
+
+const api = router(
+	{
+		hello: router({
+			get: async () => ({ message: "world" }),
+		}),
+	},
+	cors(),
+	errorHandler(),
+	jwtAuth({ secret: process.env.JWT_SECRET, claims: (p) => ({ user: p.sub }) })
+);
+```
+
+Built-in middleware: `cors`, `errorHandler`, `logger`, `rateLimit`, `requestId`, `timeout`, `basicAuth`, `bearerAuth`, `jwtAuth`, `contentType`.
+
+See **[Middleware Documentation](docs/middleware.md)** for detailed usage.
+
+## HTTP Client
+
+Generate a typed client for your API:
+
+```typescript
+// === Server (api.ts) ===
+import { route, router } from "@fresho/router";
+
+export const api = router({
+	users: router({
+		get: route({
+			query: { limit: "number?" },
+			handler: async (c) => ({ users: [], limit: c.query.limit }),
+		}),
+		$id: router({
+			get: async (c) => ({ id: c.path.id, name: "Alice" }),
+		}),
+	}),
+});
+
+// === Client ===
+import { createHttpClient } from "@fresho/router";
+import type { api } from "./api"; // Type-only import!
+
+const client = createHttpClient<typeof api>({
+	baseUrl: "https://api.example.com",
+});
+
+// Direct call for implicit GET
+const users = await client.users({ query: { limit: 10 } });
+
+// Path params
+const user = await client.users.$id({ path: { id: "123" } });
+// user is typed as { id: string, name: string }
+
+// Explicit HTTP methods use $-prefix
+await client.users.$get();                    // GET /users
+await client.users.$post({ body: { name: "Bob" } }); // POST /users
+```
+
+### HTTP Method Syntax
+
+HTTP methods are prefixed with `$` to distinguish them from path navigation:
+
+```typescript
+// $-prefixed = execute HTTP method
+client.users.$get();     // GET /users
+client.users.$post({});  // POST /users
+client.users.$put({});   // PUT /users
+client.users.$delete();  // DELETE /users
+
+// No prefix = navigate to path segment
+client.api.get.$get();   // GET /api/get (navigate to "get", then execute GET)
+```
+
+This allows routes with path segments named after HTTP methods (e.g., `/api/get`, `/resources/delete`).
+
+## Local Client
+
+Test handlers directly without HTTP overhead:
+
+```typescript
+import { createLocalClient } from "@fresho/router";
+
+const client = createLocalClient(api);
+client.configure({ env: { DB: mockDb } });
+
+const user = await client.users.$id({ path: { id: "123" } });
+assert.equal(user.name, "Alice");
+```
+
+## OpenAPI Generation
+
+Generate OpenAPI 3.0 documentation:
+
+```typescript
+import { generateDocs } from "@fresho/router";
+
+const spec = generateDocs(api, {
+	title: "My API",
+	version: "1.0.0",
+});
+
+// Serve at /openapi.json
+const docs = router({
+	openapi: router({
+		get: async () => spec,
+	}),
+});
+```
+
+## Streaming
+
+### Server-Sent Events
+
+```typescript
+import { sseResponse } from "@fresho/router";
+
+events: router({
+	get: async () =>
+		sseResponse(async (send, close) => {
+			send({ data: "connected" });
+			send({ event: "update", data: { count: 1 } });
+			close();
+		}),
+});
+```
+
+### JSON Lines
+
+```typescript
+import { streamJsonLines } from "@fresho/router";
+
+logs: router({
+	get: async () =>
+		streamJsonLines(async (send, close) => {
+			send({ level: "info", message: "Starting..." });
+			send({ level: "info", message: "Done" });
+			close();
+		}),
+});
+```
+
+## Cloudflare Workers
+
+```typescript
+import { route, router } from '@fresho/router';
+
+const api = router({ ... });
+
+export default {
+  fetch: api.handler(),
+};
+```
+
+### Typed Context
+
+Use `route.ctx<T>()` for environment bindings and middleware-added properties:
+
+```typescript
+interface AppContext {
+	env: { DB: D1Database };
+	user: { id: string }; // from auth middleware
+}
+
+const api = router(
+	{
+		profile: router({
+			get: route.ctx<AppContext>()({
+				handler: async (c) => {
+					const data = await c.env.DB.prepare("...").all();
+					return { userId: c.user.id, data };
+				},
+			}),
+		}),
+	},
+	jwtAuth({
+		secret: (c) => c.env.JWT_SECRET,
+		claims: (p) => ({ user: { id: p.sub } }),
+	})
+);
+
+export default { fetch: api.handler() };
+```
+
+## HEAD Requests
+
+Per [RFC 9110](https://httpwg.org/specs/rfc9110.html#HEAD), HEAD requests are automatically handled for any GET route:
+
+```typescript
+users: router({
+	get: async () => ({ users: await db.getUsers() }),
+});
+
+// GET /users  → 200 with body
+// HEAD /users → 200 with no body (same headers)
+```
+
+Define an explicit `head` handler if you need different behavior:
+
+```typescript
+users: router({
+	head: async () => new Response(null, { headers: { "X-Count": "100" } }),
+	get: async () => ({ users: await db.getUsers() }),
+});
+```
+
+## Size
+
+| Usage                       | Minified | Gzipped |
+| --------------------------- | -------- | ------- |
+| Core (routing + validation) | 4.2 KB   | 1.9 KB  |
+| + HTTP client               | 5.8 KB   | 2.4 KB  |
+| + OpenAPI docs              | 5.3 KB   | 2.3 KB  |
+| + cors, errorHandler        | 6.5 KB   | 2.7 KB  |
+| + all middleware            | 11.6 KB  | 4.4 KB  |
+
+Tree-shakeable: only pay for what you import.
+
+## License
+
+MIT