@lengkapp/edge 0.0.3 → 0.0.5

package/LICENSE

@@ -0,0 +1,27 @@
+LengkApp Edge License
+
+Copyright (c) LengkApp — Yasir Haris
+Contact: yh@lengk.app / yasir.haris@gmail.com
+
+Permission is granted to any person obtaining a copy of this software
+and associated documentation files (the "Software") to use, copy, and
+distribute the Software free of charge, for any purpose, including
+commercial use, subject to the following conditions:
+
+1. The Software may not be modified, adapted, or altered in any way
+   without prior written permission from the copyright holder.
+
+2. Redistribution of the Software, in whole or in part, must retain
+   this LICENSE file unmodified and include the copyright notice above.
+
+3. This permission notice does not grant any right to use the
+   LengkApp name, brand, or trademarks without separate written
+   permission.
+
+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 AUTHOR OR COPYRIGHT HOLDER 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

@@ -0,0 +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.
+
+---
+
+## 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