@lengkapp/edge 0.0.14 → 0.0.15

package/readme.md

@@ -1,673 +1,514 @@
-# @lengkapp/edge
-
-A minimal, high-performance framework for Cloudflare Workers with built-in server-side rendering, routing, auth, rate limiting, caching, and a declarative client-side partial-update library.
-
-Inspired by [Hono](https://hono.dev), @lengkapp/edge aims for the same class of performance while shipping with **zero runtime dependencies**. See [Performance](#performance) for a local benchmark against Hono, `hono/tiny`, and a plain native Workers handler.
-
-> **Security:** This release hardens both the server and the client against the OWASP Top 10:2025 and ASVS 5.0 Layer 1 controls. See [Security](#security-controls) for the full breakdown of what's protected and how to opt into the strongest settings.
-
----
-
-## Features
-
-### Server
-- **Trie-based routing** – static & dynamic routes (`/users/:id`) with fast lookups.
-- **JSX support** – render JSX components to HTML without a build step (using `jsx` and `renderToString`).
-- **Middleware options** – authentication, rate limiting, CORS, logging, caching, compression, and custom validation.
-- **Cookie helpers** – set, get, and delete cookies with flexible options.
-- **Scheduled tasks** – built-in support for Cron triggers.
-- **Zero dependencies** – lightweight and fast.
-
-### Client
-- **Declarative partial updates** – enhance HTML with `_get`, `_post`, `_target`, `_trigger` attributes to fetch and replace content dynamically.
-- **Skeleton loaders & retry UI** – built-in loading and error states.
-- **Safe DOM updates** – server responses are parsed with `DOMParser` and inserted via `importNode`; scripts are stripped and never re-executed.
-- **CSRF-aware** – state-changing requests automatically send `X-CSRF-Token` from a `<meta name="csrf-token">` tag or an `XSRF-TOKEN` cookie.
-- **Trusted Types aware** – plays nicely with a `require-trusted-types-for 'script'` CSP.
-
-### Security (both)
-- **Prototype-pollution safe** – route params, cookies, JSON payloads, and JSX attributes all use forbidden-key filtering.
-- **XSS-hardened JSX** – event handlers (`on*`), malformed tag/attr names, and `javascript:`/`data:text/html` URIs are blocked.
-- **Structured security logging** – auth failures, rate-limit hits, and handler errors emit throttled JSON events.
-- **Fail-closed middleware** – validation, auth, and rate-limit errors deny by default.
-- **Opt-in token hashing** – SHA-256 hash auth tokens before KV lookup.
-- **Strict CORS allowlist** – supports per-origin reflection with `Vary: Origin` and credentials.
-
----
-
-## Installation
-
-```bash
-npm install @lengkapp/edge
-```
-
-## Quick Start
-
-**1. Create a worker script** (`worker.js` or `src/index.ts`):
-
-```ts
-import { Edge, renderToString } from '@lengkapp/edge';
-
-const app = new Edge();
-
-app.get('/', (ctx) => ctx.text('Hello World!'));
-
-app.get('/users/:id', (ctx) => {
-  return ctx.json({ id: ctx.params.id });
-});
-
-export default {
-  fetch: (request, env, ctx) => app.fetch(request, env, ctx),
-};
-```
-
-**2. Create `wrangler.jsonc`:**
-
-> Cloudflare recommends `wrangler.jsonc` for new projects (TOML is still supported — see [Configuration](#configuration)).
-
-```jsonc
-{
-  "$schema": "./node_modules/wrangler/config-schema.json",
-  "name": "my-edge-app",
-  "main": "worker.js",
-  // Set this to today's date
-  "compatibility_date": "2026-09-06",
-  "observability": {
-    "enabled": true
-  }
-}
-```
-
-**3. Deploy:**
-
-```bash
-wrangler deploy
-```
-
-> `wrangler publish` was removed in favor of `wrangler deploy`. If you're on an older Wrangler version, run `npm install -g wrangler@latest` first.
-
----
-
-## Server API
-
-### Creating an App
-
-```ts
-import { Edge } from '@lengkapp/edge';
-const app = new Edge();
-```
-
-### Routing
-
-Register routes using HTTP method helpers. Both static and dynamic paths are supported.
-
-```ts
-// Static
-app.get('/home', handler);
-app.post('/submit', handler);
-
-// Dynamic (colon-prefixed segments)
-app.get('/users/:id', (ctx) => {
-  const userId = ctx.params.id;
-});
-```
-
-Supported methods: `get`, `post`, `put`, `delete`, `patch`, `options`, `head`.
-
-### Context Object
-
-Each handler receives a `Context` object (`ctx`) with the following members:
-
-| Property / Method | Description |
-|---|---|
-| `ctx.req` | The original `Request` object |
-| `ctx.env` | The environment bindings (KV, secrets, etc.) |
-| `ctx.executionCtx` | The `ExecutionContext` (for `waitUntil`) |
-| `ctx.params` | Route parameters (prototype-safe object) |
-| `ctx.status` | HTTP status code (default 200) |
-| `ctx.headers` | `Headers` object for the response |
-| `ctx.query` | `URLSearchParams` (lazy) |
-| `ctx.getCookie(name)` | Get a cookie value |
-| `ctx.setCookie(name, value, options)` | Set a cookie (name is validated) |
-| `ctx.deleteCookie(name, options)` | Delete a cookie (expires immediately) |
-| `ctx.text(data, status?, headers?)` | Return plain text |
-| `ctx.json(data, status?, headers?)` | Return JSON |
-| `ctx.html(data, status?, headers?)` | Return HTML |
-
-Cookie options: `path`, `domain`, `maxAge`, `expires`, `secure`, `httpOnly`, `sameSite`.
-
-Every response automatically includes these safe headers:
-
-- `X-Content-Type-Options: nosniff`
-- `Referrer-Policy: strict-origin-when-cross-origin`
-
-You can add more via `app.security.extraHeaders` (see [Security Controls](#security-controls)).
-
-### Returning Responses
-
-You can return a `Response` object, a string (becomes text), or an object (automatically JSON).
-If the handler returns a JSX element, it will be rendered to HTML automatically (see [JSX Support](#jsx-support)).
-
-```ts
-app.get('/json', (ctx) => {
-  return { hello: 'world' }; // → ctx.json()
-});
-
-app.get('/html', (ctx) => {
-  return '<h1>Hi</h1>'; // → ctx.html()
-});
-```
-
-### Route Options
-
-Pass an options object as the second argument (before the handler) to enable middleware.
-
-#### Authentication (`auth`)
-
-Requires an `AUTH_KV` KV binding. Valid tokens are stored as keys with a JSON payload.
-
-```ts
-app.get('/protected', { auth: true }, handler);
-app.get('/admin', { auth: { role: 'admin' } }, handler);
-app.get('/scoped', { auth: { scopes: ['read', 'write'] } }, handler);
-```
-
-The client must send the token via `Authorization: Bearer <token>` or a cookie named `auth_token`.
-
-If the KV payload includes an `exp` field (Unix seconds), expired tokens are rejected with a `401`. Malformed JSON payloads are rejected with `401` and logged as a security event.
-
-#### Rate Limiting (`rateLimit`)
-
-Requires a `RATE_LIMIT_KV` binding. Rate-limit responses include a `Retry-After: 60` header.
-
-```ts
-app.get('/limited', { rateLimit: { max: 100, window: 60 } }, handler);
-```
-
-#### Caching (`cache`)
-
-Caches successful GET responses in the Cloudflare cache.
-
-```ts
-app.get('/cached', { cache: { ttl: 60, staleWhileRevalidate: 30 } }, handler);
-```
-
-#### CORS (`cors`)
-
-Enables CORS headers. The default (`origin: '*'`) preserves legacy behavior. For production, use a strict allowlist:
-
-```ts
-// Legacy wildcard (default)
-app.get('/api', { cors: true }, handler);
-
-// Single origin
-app.get('/api', { cors: { origin: 'https://example.com', methods: 'GET,POST' } }, handler);
-
-// Strict allowlist — reflects matching Origin, sets Vary: Origin and credentials
-app.get('/api', {
-  cors: {
-    origin: ['https://app.example.com', 'https://admin.example.com'],
-    methods: 'GET,POST,PUT,DELETE',
-    headers: 'Content-Type, Authorization, X-CSRF-Token',
-  },
-}, handler);
-```
-
-#### Logging (`log`)
-
-Logs method, URL, and status to the console. Separately, security events (auth failures, rate-limit hits, handler errors) are logged as structured JSON when `app.security.logSecurityEvents` is `true` (the default). Events are deduplicated per `(event, IP, path)` over a 60-second window to prevent log flooding.
-
-#### Compression (`compress`)
-
-Compresses the response using gzip/deflate if the client supports it.
-
-#### Custom Validation (`validate`)
-
-A function returning `true`/`false` (or a `Promise`) to allow/deny the request. Validation errors fail closed.
-
-```ts
-app.post('/submit', {
-  validate: (ctx) => ctx.req.headers.get('Authorization') === 'Bearer secret'
-}, handler);
-```
-
----
-
-## Security Controls
-
-All controls are optional and default to behavior that preserves previous releases. Enable them after construction:
-
-```ts
-const app = new Edge();
-
-// 1. Strict CORS allowlist (replaces the default '*')
-app.defaults.cors.origin = ['https://app.example.com', 'https://admin.example.com'];
-
-// 2. Hash auth tokens with SHA-256 before KV lookup.
-//    Only enable after migrating existing tokens to `tok:<sha256-hex>` keys.
-app.security.hashAuthTokens = true;
-
-// 3. Add HSTS, COOP, COEP, CORP at the edge.
-app.security.extraHeaders = {
-  'Strict-Transport-Security': 'max-age=63072000; includeSubDomains; preload',
-  'Cross-Origin-Opener-Policy': 'same-origin',
-  'Cross-Origin-Resource-Policy': 'same-origin',
-};
-
-// 4. Disable structured security logs if you ship logs elsewhere.
-// app.security.logSecurityEvents = false;
-```
-
-### What's Protected
-
-| OWASP 2025 Category | Protection in @lengkapp/edge |
-|---|---|
-| A01: Broken Access Control | Structured auth result with reasons; expiry enforcement when `exp` is present; role/scope checks; strict target resolution on the client. |
-| A02: Security Misconfiguration | Safe default headers (`nosniff`, `Referrer-Policy`); strict CORS allowlist support; per-origin reflection with `Vary: Origin`. |
-| A03: Software Supply Chain | Zero runtime dependencies; SRI attributes honored on the client for `x-js-required` / `x-css-required`. |
-| A04: Cryptographic Failures | Optional SHA-256 token hashing before KV lookup (`app.security.hashAuthTokens`). |
-| A05: Injection / XSS / Prototype Pollution | `Object.create(null)` for params, cookies, and JSON; forbidden-key filtering in route segments, JSON payloads, cookie names, and JSX attributes; event-handler attributes blocked; `javascript:`/`data:text/html` URIs rejected; client uses `DOMParser` + `importNode` and never executes inline scripts. |
-| A06: Insecure Design | Numeric-sanitized rate limiter; `Retry-After` on 429; sliding counter per IP. |
-| A07: Authentication Failures | Specific failure reasons logged; no swallowed catches in the auth path. |
-| A08: Data Integrity | Prototype-safe JSON parsing for KV payloads; `Set-Cookie` stripped from cached responses. |
-| A09: Logging Failures | Structured JSON security events with 60-second dedupe window. |
-| A10: Exceptional Conditions | Validation, auth, and rate-limit middleware fail closed on errors; handler errors never leak internals. |
-
----
-
-## JSX Support
-
-The package includes a minimal JSX runtime. Write components as functions returning JSX.
-
-```tsx
-import { jsx, renderToString, Fragment } from '@lengkapp/edge';
-
-function Card({ title }) {
-  return (
-    <div class="card">
-      <h2>{title}</h2>
-    </div>
-  );
-}
-
-app.get('/card', (ctx) => {
-  return ctx.html(renderToString(<Card title="Hello" />));
-});
-```
-
-If your handler returns a JSX element directly, Edge will automatically render it:
-
-```tsx
-app.get('/auto', (ctx) => <h1>Auto rendered</h1>);
-```
-
-### JSX Hardening
-
-`renderToString` applies the following protections automatically:
-
-- Tag names must match `^[A-Za-z][A-Za-z0-9-]*$` — anything else is dropped.
-- Attribute names must match `^[A-Za-z_:][A-Za-z0-9_:.-]*$` and are rejected if they start with `on` (event handlers never serialize).
-- `href`, `src`, `xlink:href`, `action`, and `formaction` values beginning with `javascript:`, `vbscript:`, or `data:text/html` are stripped.
-- All string values are HTML-escaped (`&`, `<`, `>`, `"`, `'`).
-- Prototype keys (`__proto__`, `constructor`, `prototype`) are rejected as attribute names.
-- `dangerouslySetInnerHTML` remains available but is opt-in and never applied to attribute values.
-
----
-
-## Scheduled Tasks
-
-Register a scheduled handler for Cron triggers.
-
-```ts
-app.scheduled(async (event, env, ctx) => {
-  console.log('Cron executed:', event.cron);
-});
-```
-
-Then export it in your worker:
-
-```ts
-export default {
-  fetch: (req, env, ctx) => app.fetch(req, env, ctx),
-  scheduled: (event, env, ctx) => app.scheduledHandler?.(event, env, ctx)
-};
-```
-
----
-
-## Client (Declarative Partial Updates)
-
-Add the client script to your page (or include it via a CDN):
-
-```html
-<script src="https://cdn.example.com/edge-client.min.js"></script>
-```
-
-Then use HTML attributes to make elements fetch content asynchronously.
-
-### Attributes
-
-| Attribute | Description |
-|---|---|
-| `_get` | URL to fetch via GET |
-| `_post` | URL to fetch via POST |
-| `_put`, `_patch`, `_delete` | Other HTTP methods |
-| `_target` | CSS selector for the container to replace. Use `"this"` to replace the element itself. Only simple selectors (`#id`, `.class`, `tag`) are accepted for safety. |
-| `_trigger` | Comma-separated list of events that trigger the fetch (default: `click`; `load` if `_target="this"`). Supported: `click`, `load`, `visible`, `intersect`, `submit`, etc. |
-| `_form` | (with `_post`) ID of a form to serialize as the POST body (URL-encoded). |
-| `_json` | (with `_post`) Comma-separated names of input fields to send as JSON. |
-| `_skeleton` | Set to `"false"` to disable the loading skeleton. |
-| `_retry` | Set to `"false"` to disable the retry button on error. |
-
-### Examples
-
-Load content on click:
-
-```html
-<button _get="/more-posts" _target="#posts" _trigger="click">Load More</button>
-<div id="posts"></div>
-```
-
-Auto-load on page load:
-
-```html
-<div _get="/user-profile" _target="this"></div>
-```
-
-Post a form via AJAX:
-
-```html
-<form id="contact-form">
-  <input name="email" />
-  <button _post="/submit" _form="contact-form" _target="#result">Submit</button>
-</form>
-<div id="result"></div>
-```
-
-Send JSON data:
-
-```html
-<input name="username" />
-<input name="password" />
-<button _post="/login" _json="username,password" _target="#status">Login</button>
-```
-
-Load when element becomes visible (IntersectionObserver):
-
-```html
-<div _get="/lazy-content" _target="this" _trigger="visible"></div>
-```
-
-### Skeleton Loading
-
-While the request is in progress, the target container is filled with a skeleton loader (a pulsing ring icon). On error, a "Retry" button is shown; clicking it re-runs the same request once.
-
-### Safe DOM Updates
-
-Server responses are handled as follows:
-
-- Fetched with `credentials: 'same-origin'` and `X-Requested-With: XMLHttpRequest`.
-- `Content-Type` is validated — only `text/html` and `text/plain` are accepted.
-- The HTML is parsed in a detached `DOMParser` document.
-- All `<script>` elements are removed before insertion.
-- Nodes are imported with `document.importNode()` — never `innerHTML`.
-- Any new AJAX-enabled elements in the response are bound to the same delegation system.
-
-### CSRF Protection
-
-For state-changing methods (POST, PUT, PATCH, DELETE), the client reads a CSRF token from:
-
-1. `<meta name="csrf-token" content="...">` (preferred), or
-2. The `XSRF-TOKEN` cookie.
-
-The token is sent as `X-CSRF-Token` on the request. Your server handler can verify it:
-
-```ts
-app.post('/submit', {
-  validate: (ctx) => {
-    const sent = ctx.req.headers.get('X-CSRF-Token');
-    return sent && sent === ctx.getCookie('csrf_token');
-  }
-}, handler);
-```
-
-### Resource Injection
-
-If the server response includes headers `x-css-required` or `x-js-required`, the client will automatically inject those resources (once per URL) into the page. Each URL can optionally include a matching `x-css-integrity` or `x-js-integrity` header containing a Subresource Integrity hash.
-
-Example server route:
-
-```ts
-app.get('/widget', (ctx) => {
-  ctx.headers.set('x-css-required', '["/widget.css"]');
-  ctx.headers.set('x-js-required', '["/widget.js"]');
-  // Optional SRI — applies to every URL in the corresponding list
-  ctx.headers.set('x-js-integrity', 'sha384-...');
-  return ctx.html('<div class="widget">...</div>');
-});
-```
-
-### Trusted Types
-
-If your page enforces `require-trusted-types-for 'script'`, the client detects `window.trustedTypes` and creates an `aj-policy`. Only hardcoded UI strings (skeleton, retry) pass through the policy; server content never does.
-
----
-
-## Configuration
-
-### wrangler.jsonc
-
-If you use authentication or rate limiting, you need KV namespaces. Create them first:
-
-```bash
-wrangler kv namespace create AUTH_KV
-wrangler kv namespace create RATE_LIMIT_KV
-```
-
-Then wire up the returned IDs in your config:
-
-```jsonc
-{
-  "$schema": "./node_modules/wrangler/config-schema.json",
-  "name": "my-edge-app",
-  "main": "worker.js",
-  // Set this to today's date
-  "compatibility_date": "2026-09-06",
-  "observability": {
-    "enabled": true
-  },
-  "kv_namespaces": [
-    { "binding": "AUTH_KV", "id": "your-auth-kv-id" },
-    { "binding": "RATE_LIMIT_KV", "id": "your-ratelimit-kv-id" }
-  ],
-  // Optional Cron triggers
-  "triggers": {
-    "crons": ["*/5 * * * *"]
-  }
-}
-```
-
-<details>
-<summary>Equivalent <code>wrangler.toml</code></summary>
-
-```toml
-name = "my-edge-app"
-main = "worker.js"
-compatibility_date = "2026-09-06"
-
-[observability]
-enabled = true
-
-[[kv_namespaces]]
-binding = "AUTH_KV"
-id = "your-auth-kv-id"
-
-[[kv_namespaces]]
-binding = "RATE_LIMIT_KV"
-id = "your-ratelimit-kv-id"
-
-# Optional Cron triggers
-[triggers]
-crons = ["*/5 * * * *"]
-```
-
-</details>
-
-> Wrangler supports both `wrangler.jsonc` and `wrangler.toml` — they configure the same fields, just in different syntax. Don't keep both in the same project. Keep `compatibility_date` current (Cloudflare recommends staying within the last 30 days); see the [compatibility dates docs](https://developers.cloudflare.com/workers/configuration/compatibility-dates/).
-
-### Environment Variables
-
-The KV binding names are configurable on the Edge instance:
-
-```ts
-app.authKvBinding = 'CUSTOM_AUTH_KV';
-app.rateLimitKvBinding = 'CUSTOM_RATE_KV';
-```
-
-### Recommended CSP
-
-The client and JSX runtime are compatible with a strict Content Security Policy. A reasonable starting point:
-
-```text
-Content-Security-Policy:
-  default-src 'self';
-  script-src 'self';
-  style-src 'self';
-  img-src 'self' data:;
-  require-trusted-types-for 'script';
-  frame-ancestors 'none';
-  base-uri 'self';
-```
-
-Set this via `app.security.extraHeaders` or at your edge/CDN layer.
-
----
-
-## Full Example
-
-```ts
-import { Edge, renderToString } from '@lengkapp/edge';
-import { HomePage } from './Page.jsx';
-
-const app = new Edge();
-
-// Strict CORS allowlist for production
-app.defaults.cors.origin = ['https://app.example.com'];
-
-// HSTS + isolation headers
-app.security.extraHeaders = {
-  'Strict-Transport-Security': 'max-age=63072000; includeSubDomains; preload',
-  'Cross-Origin-Opener-Policy': 'same-origin',
-  'Cross-Origin-Resource-Policy': 'same-origin',
-};
-
-// Basic text
-app.get('/', (ctx) => ctx.text('Hello from Edge!'));
-
-// JSX component
-app.get('/home', (ctx) => ctx.html(renderToString(<HomePage />)));
-
-// JSON with route params
-app.get('/users/:id', (ctx) => ctx.json({ userId: ctx.params.id }));
-
-// POST JSON
-app.post('/users', async (ctx) => {
-  const body = await ctx.req.json();
-  return ctx.json({ created: true, user: body }, 201);
-});
-
-// Auth
-app.get('/protected', { auth: true }, (ctx) => ctx.text('Authenticated'));
-
-// Rate limiting
-app.get('/limited', { rateLimit: { max: 5, window: 60 } }, (ctx) => ctx.text('Limited'));
-
-// Caching
-app.get('/cached', { cache: { ttl: 60 } }, (ctx) => ctx.text('Cached'));
-
-// Cookies
-app.get('/set-cookie', (ctx) => {
-  ctx.setCookie('session', 'abc123', { httpOnly: true, secure: true, sameSite: 'Lax', path: '/' });
-  return ctx.text('Cookie set');
-});
-
-app.get('/get-cookie', (ctx) => {
-  const session = ctx.getCookie('session');
-  return ctx.text(`Cookie: ${session}`);
-});
-
-// Scheduled
-app.scheduled(async (event, env, ctx) => {
-  console.log('Cron:', event.cron);
-});
-
-export default {
-  fetch: (req, env, ctx) => app.fetch(req, env, ctx),
-  scheduled: (event, env, ctx) => app.scheduledHandler?.(event, env, ctx)
-};
-```
-
----
-
-## Performance
-
-@lengkapp/edge is inspired by Hono — one of the fastest Workers frameworks around — but ships with zero dependencies. A quick local benchmark shows it holding its own against both Hono builds (`hono` and `hono/tiny`) and a plain native `fetch` handler with no framework at all.
-
-### Test setup
-
-- **Tool:** autocannon — 10 connections, 10s run per route
-- **Target:** local `wrangler dev` server
-- **Routes:** `GET /text` (plain text) and `GET /json` (JSON)
-- **Contenders:** @lengkapp/edge, hono, hono/tiny, and a native Workers handler with no framework
-
-> This is a single local run, not a formal benchmark suite — treat the numbers as directional. Latency stdev was ±3–4 ms across all four, so differences smaller than that are within noise.
-
-### Results
-
-| Framework | Route | Avg Req/sec | Avg Latency | Requests | Data Read |
-|---|---|---|---|---|---|
-| @lengkapp/edge | `/text` | 503.1 | 19.38 ms | 5,000 / 10.03s | 1.38 MB |
-| @lengkapp/edge | `/json` | 500.4 | 19.47 ms | 5,000 / 10.03s | 1.42 MB |
-| Hono | `/text` | 506.0 | 19.27 ms | 5,000 / 10.03s | 455 kB |
-| Hono | `/json` | 495.2 | 19.69 ms | 5,000 / 10.03s | 426 kB |
-| Hono (`hono/tiny`) | `/text` | 505.5 | 19.28 ms | 5,000 / 10.03s | 455 kB |
-| Hono (`hono/tiny`) | `/json` | 497.9 | 19.57 ms | 5,000 / 10.03s | 428 kB |
-| Native Workers (no framework) | `/text` | 498.4 | 19.55 ms | 5,000 / 10.02s | 379 kB |
-| Native Workers (no framework) | `/json` | 499.7 | 19.51 ms | 5,000 / 10.03s | 430 kB |
-
-### Takeaways
-
-- On `/json`, @lengkapp/edge posted the highest average throughput of the four, ahead of both Hono builds and the native handler.
-- On `/text`, it landed within ~1% of `hono`/`hono/tiny` and ahead of the native baseline — effectively a tie once you account for run-to-run variance.
-- All four sit in the same performance tier; the practical difference is that @lengkapp/edge gets there with zero runtime dependencies, matching `hono/tiny`'s footprint without having to choose a "tiny" build.
-- @lengkapp/edge read more bytes per request than the other three in this run — worth profiling if minimal payload size matters for your use case.
-- The 2025 security hardening adds only cheap operations to the request path: prototype-safe objects (`Object.create(null)`), two regex checks per JSX attribute, and a throttled logger that skips duplicate events within 60 seconds. No new async boundaries, no hashing on the hot path (`hashAuthTokens` defaults to `false`), and no added dependencies.
-
----
-
-## Migration Notes
-
-### Upgrading from ≤ 0.x
-
-The security release is backward-compatible. Existing apps continue to work without code changes. New defaults:
-
-- Every response now includes `X-Content-Type-Options: nosniff` and `Referrer-Policy: strict-origin-when-cross-origin`.
-- Rate-limited responses include `Retry-After: 60`.
-- Route params, cookie stores, and JSON payloads use prototype-safe objects. If you were relying on `ctx.params.hasOwnProperty(...)`, use `Object.prototype.hasOwnProperty.call(ctx.params, ...)` or `'x' in ctx.params`.
-- The JSX renderer now drops `on*` attributes. Handlers relying on server-rendered inline event handlers must be moved to the client.
-- Security events are logged as JSON. To disable: `app.security.logSecurityEvents = false`.
-
-### Client upgrade
-
-If you were using the old client that executed `<script>` tags in responses, replace those scripts with either:
-
-- DOM-based initialization (event delegation, `IntersectionObserver`, etc.), or
-- An explicit `<script src="...">` injected via `x-js-required` on the response.
-
-The new client refuses to run inline scripts for security reasons and will not execute `<script>` elements found in response bodies.
-
----
-
-## License
-
+# @lengkapp/edge
+
+A minimal, high-performance framework for Cloudflare Workers with built-in server-side rendering, routing, auth, rate limiting, caching, and a declarative client-side partial-update library.
+
+Inspired by [Hono](https://hono.dev), @lengkapp/edge aims for the same class of performance while shipping with **zero runtime dependencies**. See [Performance](#performance) for a local benchmark against Hono, `hono/tiny`, and a plain native Workers handler.
+
+---
+
+## Features
+
+- **Trie-based routing** – static & dynamic routes (`/users/:id`) with fast lookups.
+- **JSX support** – render JSX components to HTML without a build step (using `jsx` and `renderToString`).
+- **Middleware options** – authentication, rate limiting, CORS, logging, caching, compression, and custom validation.
+- **Cookie helpers** – set, get, and delete cookies with flexible options.
+- **Declarative client** – enhance HTML with `_get`, `_post`, `_target`, `_trigger` attributes to fetch and replace content dynamically, with skeleton loaders and retry buttons.
+- **Resource injection** – automatically load CSS/JS files from response headers.
+- **Scheduled tasks** – built-in support for Cron triggers.
+- **Zero dependencies** – lightweight and fast.
+
+---
+
+## Installation
+
+```bash
+npm install @lengkapp/edge
+```
+
+---
+
+## Quick Start
+
+**1. Create a worker script (`worker.js` or `src/index.ts`):**
+
+```ts
+import { Edge, renderToString } from '@lengkapp/edge';
+
+const app = new Edge();
+
+app.get('/', (ctx) => ctx.text('Hello World!'));
+
+app.get('/users/:id', (ctx) => {
+  return ctx.json({ id: ctx.params.id });
+});
+
+export default {
+  fetch: (request, env, ctx) => app.fetch(request, env, ctx),
+};
+```
+
+**2. Create `wrangler.jsonc`:**
+
+Cloudflare recommends `wrangler.jsonc` for new projects (TOML is still supported — see [Configuration](#configuration)).
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-edge-app",
+  "main": "worker.js",
+  // Set this to today's date
+  "compatibility_date": "2026-09-06",
+  "observability": {
+    "enabled": true
+  }
+}
+```
+
+**3. Deploy:**
+
+```bash
+wrangler deploy
+```
+
+> `wrangler publish` was removed in favor of `wrangler deploy`. If you're on an older Wrangler version, run `npm install -g wrangler@latest` first.
+
+---
+
+## Server API
+
+### Creating an App
+
+```ts
+import { Edge } from '@lengkapp/edge';
+const app = new Edge();
+```
+
+### Routing
+
+Register routes using HTTP method helpers. Both static and dynamic paths are supported.
+
+```ts
+// Static
+app.get('/home', handler);
+app.post('/submit', handler);
+
+// Dynamic (colon-prefixed segments)
+app.get('/users/:id', (ctx) => {
+  const userId = ctx.params.id;
+});
+```
+
+Supported methods: `get`, `post`, `put`, `delete`, `patch`, `options`, `head`.
+
+### Context Object
+
+Each handler receives a `Context` object (`ctx`) with the following members:
+
+| Property / Method | Description |
+| --- | --- |
+| `ctx.req` | The original `Request` object |
+| `ctx.env` | The environment bindings (KV, secrets, etc.) |
+| `ctx.executionCtx` | The `ExecutionContext` (for `waitUntil`) |
+| `ctx.params` | Route parameters (e.g., `{ id: '123' }`) |
+| `ctx.status` | HTTP status code (default `200`) |
+| `ctx.headers` | `Headers` object for the response |
+| `ctx.query` | `URLSearchParams` (lazy) |
+| `ctx.getCookie(name)` | Get a cookie value |
+| `ctx.setCookie(name, value, options)` | Set a cookie |
+| `ctx.deleteCookie(name, options)` | Delete a cookie (expires immediately) |
+| `ctx.text(data, status?, headers?)` | Return plain text |
+| `ctx.json(data, status?, headers?)` | Return JSON |
+| `ctx.html(data, status?, headers?)` | Return HTML |
+
+Cookie options: `path`, `domain`, `maxAge`, `expires`, `secure`, `httpOnly`, `sameSite`.
+
+### Returning Responses
+
+You can return a `Response` object, a string (becomes text), or an object (automatically JSON).
+If the handler returns a JSX element, it will be rendered to HTML automatically (see [JSX Support](#jsx-support)).
+
+```ts
+app.get('/json', (ctx) => {
+  return { hello: 'world' }; // → ctx.json()
+});
+
+app.get('/html', (ctx) => {
+  return '<h1>Hi</h1>'; // → ctx.html()
+});
+```
+
+### Route Options
+
+Pass an options object as the second argument (before the handler) to enable middleware.
+
+#### Authentication (`auth`)
+
+Requires an `AUTH_KV` KV binding. Valid tokens are stored as keys with a JSON payload.
+
+```ts
+app.get('/protected', { auth: true }, handler);
+app.get('/admin', { auth: { role: 'admin' } }, handler);
+app.get('/scoped', { auth: { scopes: ['read', 'write'] } }, handler);
+```
+
+The client must send the token via `Authorization: Bearer <token>` or a cookie named `auth_token`.
+
+#### Rate Limiting (`rateLimit`)
+
+Requires a `RATE_LIMIT_KV` binding.
+
+```ts
+app.get('/limited', { rateLimit: { max: 100, window: 60 } }, handler);
+```
+
+#### Caching (`cache`)
+
+Caches successful GET responses in the Cloudflare cache.
+
+```ts
+app.get('/cached', { cache: { ttl: 60, staleWhileRevalidate: 30 } }, handler);
+```
+
+#### CORS (`cors`)
+
+Enables CORS headers.
+
+```ts
+app.get('/api', { cors: true }, handler);
+
+// Custom origin / methods
+app.get('/api', { cors: { origin: 'https://example.com', methods: 'GET,POST' } }, handler);
+```
+
+#### Logging (`log`)
+
+Logs method, URL, and status to the console.
+
+#### Compression (`compress`)
+
+Compresses the response using gzip/deflate/br if the client supports it.
+
+#### Custom Validation (`validate`)
+
+A function returning `true`/`false` (or a `Promise`) to allow/deny the request.
+
+```ts
+app.post('/submit', {
+  validate: (ctx) => ctx.req.headers.get('Authorization') === 'Bearer secret'
+}, handler);
+```
+
+---
+
+## JSX Support
+
+The package includes a minimal JSX runtime. Write components as functions returning JSX.
+
+```tsx
+import { jsx, renderToString, Fragment } from '@lengkapp/edge';
+
+function Card({ title }) {
+  return (
+    <div class="card">
+      <h2>{title}</h2>
+    </div>
+  );
+}
+
+app.get('/card', (ctx) => {
+  return ctx.html(renderToString(<Card title="Hello" />));
+});
+```
+
+If your handler returns a JSX element directly, Edge will automatically render it:
+
+```tsx
+app.get('/auto', (ctx) => <h1>Auto rendered</h1>);
+```
+
+---
+
+## Scheduled Tasks
+
+Register a scheduled handler for Cron triggers.
+
+```ts
+app.scheduled(async (event, env, ctx) => {
+  console.log('Cron executed:', event.cron);
+});
+```
+
+Then export it in your worker:
+
+```ts
+export default {
+  fetch: (req, env, ctx) => app.fetch(req, env, ctx),
+  scheduled: (event, env, ctx) => app.scheduledHandler?.(event, env, ctx)
+};
+```
+
+---
+
+## Client (Declarative Partial Updates)
+
+Add the client script to your page (or include it via a CDN):
+
+```html
+<script src="https://cdn.example.com/edge-client.min.js"></script>
+```
+
+Then use HTML attributes to make elements fetch content asynchronously.
+
+### Attributes
+
+| Attribute | Description |
+| --- | --- |
+| `_get` | URL to fetch via GET |
+| `_post` | URL to fetch via POST |
+| `_target` | CSS selector for the container to replace. Use `"this"` to replace the element itself. |
+| `_trigger` | Comma-separated list of events that trigger the fetch (default: `click`; `load` if `_target="this"`). Supported: `click`, `load`, `visible`, `intersect`, `submit`, etc. |
+| `_form` | (with `_post`) ID of a form to serialize as the POST body (URL-encoded). |
+| `_json` | (with `_post`) Comma-separated names of input fields to send as JSON. |
+
+### Examples
+
+**Load content on click:**
+
+```html
+<button _get="/more-posts" _target="#posts" _trigger="click">Load More</button>
+<div id="posts"></div>
+```
+
+**Auto-load on page load:**
+
+```html
+<div _get="/user-profile" _target="this"></div>
+```
+
+**Post a form via AJAX:**
+
+```html
+<form id="contact-form">
+  <input name="email" />
+  <button _post="/submit" _form="contact-form" _target="#result">Submit</button>
+</form>
+<div id="result"></div>
+```
+
+**Send JSON data:**
+
+```html
+<input name="username" />
+<input name="password" />
+<button _post="/login" _json="username,password" _target="#status">Login</button>
+```
+
+**Load when element becomes visible (IntersectionObserver):**
+
+```html
+<div _get="/lazy-content" _target="this" _trigger="visible"></div>
+```
+
+### Skeleton Loading
+
+While the request is in progress, the target container is filled with a skeleton loader (three shimmer bars). On error, a "Retry" button is shown.
+
+### Resource Injection
+
+If the server response includes headers `x-css-required` or `x-js-required`, the client will automatically inject those resources (once per URL) into the page.
+
+Example server route:
+
+```ts
+app.get('/widget', (ctx) => {
+  ctx.headers.set('x-css-required', '["/widget.css"]');
+  ctx.headers.set('x-js-required', '["/widget.js"]');
+  return ctx.html('<div class="widget">...</div>');
+});
+```
+
+---
+
+## Configuration
+
+### `wrangler.jsonc`
+
+If you use authentication or rate limiting, you need KV namespaces. Create them first:
+
+```bash
+wrangler kv namespace create AUTH_KV
+wrangler kv namespace create RATE_LIMIT_KV
+```
+
+Then wire up the returned IDs in your config:
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-edge-app",
+  "main": "worker.js",
+  // Set this to today's date
+  "compatibility_date": "2026-09-06",
+  "observability": {
+    "enabled": true
+  },
+  "kv_namespaces": [
+    { "binding": "AUTH_KV", "id": "your-auth-kv-id" },
+    { "binding": "RATE_LIMIT_KV", "id": "your-ratelimit-kv-id" }
+  ],
+  // Optional Cron triggers
+  "triggers": {
+    "crons": ["*/5 * * * *"]
+  }
+}
+```
+
+<details>
+<summary>Equivalent <code>wrangler.toml</code></summary>
+
+```toml
+name = "my-edge-app"
+main = "worker.js"
+compatibility_date = "2026-09-06"
+
+[observability]
+enabled = true
+
+[[kv_namespaces]]
+binding = "AUTH_KV"
+id = "your-auth-kv-id"
+
+[[kv_namespaces]]
+binding = "RATE_LIMIT_KV"
+id = "your-ratelimit-kv-id"
+
+# Optional Cron triggers
+[triggers]
+crons = ["*/5 * * * *"]
+```
+
+</details>
+
+Wrangler supports both `wrangler.jsonc` and `wrangler.toml` — they configure the same fields, just in different syntax. Don't keep both in the same project. Keep `compatibility_date` current (Cloudflare recommends staying within the last 30 days); see the [compatibility dates docs](https://developers.cloudflare.com/workers/configuration/compatibility-dates/).
+
+### Environment Variables
+
+The KV binding names are configurable on the Edge instance:
+
+```ts
+app.authKvBinding = 'CUSTOM_AUTH_KV';
+app.rateLimitKvBinding = 'CUSTOM_RATE_KV';
+```
+
+---
+
+## Full Example
+
+```ts
+import { Edge, renderToString } from '@lengkapp/edge';
+import { HomePage } from './Page.jsx';
+
+const app = new Edge();
+
+// Basic text
+app.get('/', (ctx) => ctx.text('Hello from Edge!'));
+
+// JSX component
+app.get('/home', (ctx) => ctx.html(renderToString(<HomePage />)));
+
+// JSON with route params
+app.get('/users/:id', (ctx) => ctx.json({ userId: ctx.params.id }));
+
+// POST JSON
+app.post('/users', async (ctx) => {
+  const body = await ctx.req.json();
+  return ctx.json({ created: true, user: body }, 201);
+});
+
+// Auth
+app.get('/protected', { auth: true }, (ctx) => ctx.text('Authenticated'));
+
+// Rate limiting
+app.get('/limited', { rateLimit: { max: 5, window: 60 } }, (ctx) => ctx.text('Limited'));
+
+// Caching
+app.get('/cached', { cache: { ttl: 60 } }, (ctx) => ctx.text('Cached'));
+
+// Cookies
+app.get('/set-cookie', (ctx) => {
+  ctx.setCookie('session', 'abc123', { httpOnly: true, path: '/' });
+  return ctx.text('Cookie set');
+});
+
+app.get('/get-cookie', (ctx) => {
+  const session = ctx.getCookie('session');
+  return ctx.text(`Cookie: ${session}`);
+});
+
+// Scheduled
+app.scheduled(async (event, env, ctx) => {
+  console.log('Cron:', event.cron);
+});
+
+export default {
+  fetch: (req, env, ctx) => app.fetch(req, env, ctx),
+  scheduled: (event, env, ctx) => app.scheduledHandler?.(event, env, ctx)
+};
+```
+
+---
+
+## Performance
+
+@lengkapp/edge is inspired by [Hono](https://hono.dev) — one of the fastest Workers frameworks around — but ships with **zero dependencies**. A quick local benchmark shows it holding its own against both Hono builds (`hono` and `hono/tiny`) and a plain native `fetch` handler with no framework at all.
+
+### Test setup
+
+- **Tool:** `autocannon` — 10 connections, 10s run per route
+- **Target:** local `wrangler dev` server
+- **Routes:** `GET /text` (plain text) and `GET /json` (JSON)
+- **Contenders:** `@lengkapp/edge`, `hono`, `hono/tiny`, and a native Workers handler with no framework
+
+> This is a single local run, not a formal benchmark suite — treat the numbers as directional. Latency stdev was ±3–4 ms across all four, so differences smaller than that are within noise.
+
+### Results
+
+| Framework | Route | Avg Req/sec | Avg Latency | Requests | Data Read |
+| --- | --- | --- | --- | --- | --- |
+| **@lengkapp/edge** | `/text` | 503.1 | 19.38 ms | 5,000 / 10.03s | 1.38 MB |
+| **@lengkapp/edge** | `/json` | **500.4** | 19.47 ms | 5,000 / 10.03s | 1.42 MB |
+| Hono | `/text` | **506.0** | 19.27 ms | 5,000 / 10.03s | 455 kB |
+| Hono | `/json` | 495.2 | 19.69 ms | 5,000 / 10.03s | 426 kB |
+| Hono (`hono/tiny`) | `/text` | 505.5 | 19.28 ms | 5,000 / 10.03s | 455 kB |
+| Hono (`hono/tiny`) | `/json` | 497.9 | 19.57 ms | 5,000 / 10.03s | 428 kB |
+| Native Workers (no framework) | `/text` | 498.4 | 19.55 ms | 5,000 / 10.02s | 379 kB |
+| Native Workers (no framework) | `/json` | 499.7 | 19.51 ms | 5,000 / 10.03s | 430 kB |
+
+```mermaid
+xychart-beta
+    title "Avg requests/sec — GET /text"
+    x-axis ["@lengkapp/edge", "Hono", "Hono (tiny)", "Native Workers"]
+    y-axis "Req/sec" 490 --> 510
+    bar [503.1, 506.0, 505.5, 498.4]
+```
+
+```mermaid
+xychart-beta
+    title "Avg requests/sec — GET /json"
+    x-axis ["@lengkapp/edge", "Hono", "Hono (tiny)", "Native Workers"]
+    y-axis "Req/sec" 490 --> 505
+    bar [500.4, 495.2, 497.9, 499.7]
+```
+
+### Takeaways
+
+- On `/json`, @lengkapp/edge posted the highest average throughput of the four, ahead of both Hono builds and the native handler.
+- On `/text`, it landed within ~1% of `hono`/`hono/tiny` and ahead of the native baseline — effectively a tie once you account for run-to-run variance.
+- All four sit in the same performance tier; the practical difference is that @lengkapp/edge gets there with **zero runtime dependencies**, matching `hono/tiny`'s footprint without having to choose a "tiny" build.
+- @lengkapp/edge read more bytes per request than the other three in this run — worth profiling if minimal payload size matters for your use case.
+
+---
+
+## License
+
 See [LICENSE](./LICENSE). © LengkApp — Yasir Haris