http-air 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "Bash(npm test)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(npx tsc:*)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,313 @@
+# http-air
+
+HTTP library for batched RPC calls and real-time server-push over a single endpoint.
+
+- **RPC** — calls made in the same tick are grouped into one HTTP request. The server executes them concurrently and streams each result back as it resolves, matched to the original call by index. The client resolves each promise individually as its result arrives.
+- **Events** — server pushes named events to subscribed clients over a persistent HTTP connection, with heartbeat and auto-reconnect.
+- **SWR cache** — RPC calls support stale-while-revalidate: return a cached value immediately and revalidate in the background, with a cancel handle.
+
+## Why http-air
+
+**Single endpoint, two transports.** RPC and event streaming share one URL and one framework route. No WebSocket upgrade negotiation, no separate SSE endpoint to manage.
+
+**Automatic batching.** RPC calls queued in the same tick are merged into one HTTP request with no configuration. Ten calls become one round trip. Duplicate calls (same method and params) are deduplicated and resolved from the same result.
+
+**Streaming results.** The server responds to each batch as soon as individual calls resolve — fast methods return immediately without waiting for slow ones. The client matches results to promises by index.
+
+**Plain HTTP.** Works through any proxy, CDN, or load balancer that handles standard HTTP POST requests. No protocol upgrades, no persistent TCP connections for RPC.
+
+**Auto-reconnect built in.** The event connection reconnects automatically on drop, resubscribes to all active events, and detects dead connections via heartbeat — without any user code.
+
+**Framework agnostic.** Ships with adapters for Express, Next.js, Hono, and Micro. Any other framework is supported by implementing a two-method interface.
+
+**Zero config to start.** Both `Client` and `Server` work out of the box. URL, fetch, deduplication, and reconnection all have sensible defaults.
+
+## Quick start
+
+**Server**
+
+```ts
+import express from 'express'
+import { Server } from 'http-air/server'
+import { expressHandler } from 'http-air/server/adapters/express'
+
+const server = new Server()
+
+server.handleRpc(async ({ method, params }) => {
+  return myService[method](...params)
+})
+
+// push an event whenever something happens
+setInterval(() => {
+  server.notifyEvent('price-update', { symbol: 'BTC', price: 70000 })
+}, 5000)
+
+const app = express()
+app.post('/api', expressHandler(server))
+```
+
+**Client**
+
+```ts
+import { Client } from 'http-air/client'
+
+const client = new Client({ url: '/api' })
+
+// RPC
+const result = await client.callRpc('double', [10])
+
+// Events
+const unsubscribeEvent = client.subscribeEvent('price-update', (event) => {
+  console.log(event.data)
+})
+
+// later
+unsubscribeEvent()
+client.disconnect()
+```
+
+---
+
+## Server
+
+`Server` composes the router, RPC handler, and event emitter into a single instance.
+
+```ts
+import { Server } from 'http-air/server'
+
+const server = new Server()
+
+server.handleRpc(async ({ method, params }) => {
+  return myService[method](...params)
+})
+
+// push to all subscribers whenever something happens
+server.notifyEvent('price-update', { symbol: 'BTC', price: 70000 })
+```
+
+### Framework adapters
+
+Each adapter takes a `Server` instance and returns a framework-specific handler. Body parsing is handled inside the adapter.
+
+**Express**
+```ts
+import express from 'express'
+import { expressHandler } from 'http-air/server/adapters/express'
+
+const app = express()
+app.post('/api', expressHandler(server))
+```
+
+**Next.js**
+```ts
+import { nextHandler } from 'http-air/server/adapters/next'
+
+export default nextHandler(server)
+```
+
+**Hono**
+```ts
+import { Hono } from 'hono'
+import { honoHandler } from 'http-air/server/adapters/hono'
+
+const app = new Hono()
+app.post('/api', honoHandler(server))
+```
+
+**Micro**
+```ts
+import { microHandler } from 'http-air/server/adapters/micro'
+
+export default microHandler(server)
+```
+
+### Custom adapter
+
+Implement `ServerReq` and `ServerRes` to support any other framework:
+
+```ts
+import { ServerReq, ServerRes } from 'http-air/server'
+
+server.handleHttp(
+  {
+    getHeader: (key) => req.headers[key],
+    getUrl: () => req.url,
+    getMethod: () => req.method,
+    getBody: () => req.body,
+  },
+  {
+    write: (content) => res.write(content),
+    isClosed: () => res.writableEnded,
+    writeHead: (status, headers) => res.writeHead(status, headers),
+    flushHeaders: () => res.flushHeaders(),
+    onClose: (cb) => res.on('close', cb),
+    end: () => res.end(),
+    destroy: () => res.destroy(),
+  }
+)
+```
+
+### Lower-level API
+
+For custom setups, use the building blocks directly:
+
+```ts
+import { Router, RpcServer, EventsServer } from 'http-air/server'
+
+const router = new Router()
+const rpc = new RpcServer(router)
+rpc.handle(handler)
+const events = new EventsServer(router)
+```
+
+---
+
+## Client
+
+`Client` composes `RpcClient` and `EventsClient` behind a single instance. Use it when you need both RPC and events from the same endpoint.
+
+```ts
+import { Client } from 'http-air/client'
+
+const client = new Client({ url: '/api' })
+```
+
+All clients accept the same base config:
+
+```ts
+interface ClientConfig {
+  url?: string                     // endpoint URL, defaults to current page location
+  fetch?: typeof globalThis.fetch  // custom fetch implementation
+  init?: RequestInit               // base RequestInit merged into every request
+}
+```
+
+`RpcClient` and `Client` also accept:
+
+```ts
+interface RpcClientConfig extends ClientConfig {
+  batch?: boolean                                // group calls in the same tick, default true
+  deduplicate?: boolean                          // deduplicate calls by method+params, default true
+  onResponse?: (resp: ResponseMessage) => void  // called on each result or error message
+}
+```
+
+### RPC
+
+Calls made in the same tick are grouped into one HTTP request automatically. Duplicate calls (same method + params) within a batch are deduplicated.
+
+```ts
+import { RpcClient } from 'http-air/client'
+
+const client = new RpcClient({ url: '/api' })
+
+// these three calls go out in a single request on the next tick
+const [r1, r2, r3] = await Promise.all([
+  client.call('double', [10]),
+  client.call('add', [1, 2]),
+  client.call('double', [10]), // deduplicated — resolved from the same result as r1
+])
+```
+
+### SWR (stale-while-revalidate)
+
+`callSwr` returns a tuple `[stale, fresh, cancel]` — immediately a cached (stale) value and a background revalidation promise. If no cache exists both point to the same request. If the cached value is within `ttl` (ms) no request is made.
+
+```ts
+const [stale, fresh, cancel] = client.callSwr('getUser', [42], 5000)
+
+// render immediately with cached data
+const user = await stale
+
+// update once revalidated
+const updated = await fresh
+
+// cancel the background revalidation (e.g. component unmounted)
+cancel()
+```
+
+Works well inside a React `useEffect`:
+
+```ts
+useEffect(() => {
+  const [stale, fresh, cancel] = rpcClient.callSwr('getUser', [id], 5_000)
+  stale.then(setUser)
+  fresh.then(setUser)
+  return cancel
+}, [id])
+```
+
+`Client` exposes the same method as `callRpcSwr`.
+
+---
+
+### Events
+
+Connects automatically on the first `subscribe()` call and disconnects when all subscriptions are removed. Multiple subscribe/unsubscribe calls in the same tick are batched. Auto-reconnect is always enabled.
+
+```ts
+import { EventsClient } from 'http-air/client'
+
+const events = new EventsClient({ url: '/api' })
+
+const unsubscribe = events.subscribe('price-update', (event) => {
+  console.log(event.data)
+})
+
+// later — disconnects automatically when no subscriptions remain
+unsubscribe()
+```
+
+---
+
+## Protocol
+
+All requests use `POST` with the `action` query param. Unknown actions return `400`.
+
+### RPC (`action=rpc`)
+
+Requests are sent as `\n\n`-delimited JSON. The server responds with `207` and streams results back as they complete — out of order is fine, matched by `index`.
+
+```
+→ POST /api?action=rpc
+{"index":0,"method":"double","params":[5]}\n\n
+{"index":1,"method":"increment","params":[9]}\n\n
+
+← 207
+{"index":1,"result":10}\n\n
+{"index":0,"result":10}\n\n
+```
+
+Errors are returned inline:
+
+```
+{"index":0,"error":{"name":"Error","message":"something went wrong"}}\n\n
+```
+
+### Events (`action=events-connect`)
+
+The client opens a persistent connection. The server streams `\n\n`-delimited JSON indefinitely. A heartbeat fires every 25 seconds to detect dead connections; the client reconnects automatically if one is missed.
+
+```
+→ POST /api?action=events-connect
+← 200 (connection held open)
+{"type":"heartbeat","ts":1234567890}\n\n
+{"type":"event","name":"price-update","data":{...}}\n\n
+```
+
+Subscribe and unsubscribe send event names as `\n\n`-delimited objects in the body:
+
+```
+→ POST /api?action=events-subscribe
+{"name":"price-update"}\n\n
+{"name":"order-filled"}\n\n
+
+→ POST /api?action=events-unsubscribe
+{"name":"order-filled"}\n\n
+```
+
+---
+
+## License
+
+MIT © [Yosbel Marín](https://github.com/yosbelms)

package/index.js

@@ -0,0 +1 @@
+"use strict";

package/lib/client/batch.d.ts

@@ -0,0 +1,15 @@
+export interface BatchOptions<T> {
+    /** If provided, duplicate keys are ignored while items are queued */
+    key?: (item: T) => string;
+}
+/** Generic batch accumulator. Collects items and auto-flushes on next tick or at max size. */
+export declare class Batch<T> {
+    private onFlush;
+    private items;
+    private keySet;
+    private scheduleTimeout?;
+    private key?;
+    constructor(onFlush: (items: T[]) => void, options?: BatchOptions<T>);
+    add(item: T): void;
+    flush(): void;
+}

package/lib/client/batch.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Batch = void 0;
+const MAX_BATCH_SIZE = 1000;
+/** Generic batch accumulator. Collects items and auto-flushes on next tick or at max size. */
+class Batch {
+    onFlush;
+    items = [];
+    keySet = new Set();
+    scheduleTimeout;
+    key;
+    constructor(onFlush, options = {}) {
+        this.onFlush = onFlush;
+        this.key = options.key;
+    }
+    add(item) {
+        if (this.key) {
+            const k = this.key(item);
+            if (this.keySet.has(k))
+                return;
+            this.keySet.add(k);
+        }
+        this.items.push(item);
+        if (this.items.length >= MAX_BATCH_SIZE) {
+            this.flush();
+        }
+        else if (this.scheduleTimeout === void 0) {
+            this.scheduleTimeout = setTimeout(() => this.flush(), 0);
+        }
+    }
+    flush() {
+        clearTimeout(this.scheduleTimeout);
+        this.scheduleTimeout = void 0;
+        if (this.items.length === 0)
+            return;
+        const items = this.items;
+        this.items = [];
+        this.keySet.clear();
+        this.onFlush(items);
+    }
+}
+exports.Batch = Batch;

package/lib/client/client.d.ts

@@ -0,0 +1,28 @@
+import { RpcClientConfig, SwrResult } from './rpc';
+export interface ClientConfig {
+    /** Endpoint URL. Defaults to current page location */
+    url?: string;
+    /** Fetch implementation. Defaults to globalThis.fetch */
+    fetch?: typeof globalThis.fetch;
+    /** Base RequestInit merged into every request */
+    init?: RequestInit;
+}
+/** Resolve url and fetch from config */
+export declare function resolveConfig(config: ClientConfig): {
+    url: any;
+    fetchFn: typeof fetch;
+};
+/** Serialize items to \n\n-delimited JSON */
+export declare function toNdjson<T>(items: T[]): string;
+export declare class Client {
+    private rpc;
+    private events;
+    constructor(config?: RpcClientConfig);
+    callRpc(method: string, params: any[]): Promise<any>;
+    callRpcSwr(method: string, params: any[], ttl: number): SwrResult;
+    subscribeEvent(eventName: string | string[], handler: (data: any) => void): () => void;
+    unsubscribeEvent(eventName: string | string[], handler: (data: any) => void): void;
+    disconnect(): void;
+}
+/** Read a response body as text chunks */
+export declare function readResponseBody(response: Response, onChunk: (chunk: string) => void, onDone: () => void): Promise<void>;

package/lib/client/client.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+exports.resolveConfig = resolveConfig;
+exports.toNdjson = toNdjson;
+exports.readResponseBody = readResponseBody;
+const stream_constants_1 = require("../shared/stream-constants");
+const rpc_1 = require("./rpc");
+const events_1 = require("./events");
+/** Resolve url and fetch from config */
+function resolveConfig(config) {
+    return {
+        url: config.url ?? globalThis?.location?.href ?? 'http://localhost/',
+        fetchFn: config.fetch ?? globalThis.fetch,
+    };
+}
+/** Serialize items to \n\n-delimited JSON */
+function toNdjson(items) {
+    return items.map(i => JSON.stringify(i)).join(stream_constants_1.DELIMITER) + stream_constants_1.DELIMITER;
+}
+class Client {
+    rpc;
+    events;
+    constructor(config = {}) {
+        this.rpc = new rpc_1.RpcClient(config);
+        this.events = new events_1.EventsClient(config);
+    }
+    callRpc(method, params) {
+        return this.rpc.call(method, params);
+    }
+    callRpcSwr(method, params, ttl) {
+        return this.rpc.callSwr(method, params, ttl);
+    }
+    subscribeEvent(eventName, handler) {
+        return this.events.subscribe(eventName, handler);
+    }
+    unsubscribeEvent(eventName, handler) {
+        this.events.unsubscribe(eventName, handler);
+    }
+    disconnect() {
+        this.events.disconnect();
+    }
+}
+exports.Client = Client;
+/** Read a response body as text chunks */
+async function readResponseBody(response, onChunk, onDone) {
+    const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done) {
+                onDone();
+                return;
+            }
+            onChunk(value);
+        }
+    }
+    catch {
+        onDone();
+    }
+}

package/lib/client/events.d.ts

@@ -0,0 +1,21 @@
+import { ClientConfig } from './client';
+export declare class EventsClient {
+    private fetcher;
+    private sessionId;
+    private serverId;
+    private response;
+    private abortController;
+    private status;
+    private listenersMap;
+    private subscribedSet;
+    private subscribeBatch;
+    private unsubscribeBatch;
+    constructor(config?: ClientConfig);
+    private buildFetcher;
+    private connect;
+    private performConnect;
+    private read;
+    disconnect(): void;
+    subscribe(eventName: string | string[], handler: (data: any) => void): () => void;
+    unsubscribe(eventName: string | string[], handler: (data: any) => void): void;
+}