@nifrajs/node 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+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

@@ -0,0 +1,62 @@
+# @nifrajs/node
+
+Run a [nifra](../../README.md) app on Node's `http` server — nifra's ergonomics, deployed
+on Node instead of Bun.
+
+```sh
+bun add @nifrajs/node   # or: npm add @nifrajs/node
+```
+
+```ts
+import { server } from "@nifrajs/core"
+import { serve } from "@nifrajs/node"
+
+const app = server().get("/users/:id", (c) => ({ id: c.params.id }))
+
+const node = await serve(app, { port: 3000 })
+// node.port            → the bound port (resolved; useful with `port: 0`)
+// await node.stop()    → drain in-flight, then force-close (graceful shutdown)
+```
+
+`serve(app, { port })` bridges Node's stream-based `(req, res)` to/from the Web
+`Request`/`Response` that `app.fetch` speaks — that's the only Bun-specific seam, since
+nifra's lifecycle is already Web-standard. It also gives you a graceful `stop()`, the
+Node equivalent of Bun's `app.listen()`.
+
+## Public URL protocol
+
+The adapter creates a plain Node `http` server, so `Request.url` uses `http://` by
+default. If TLS terminates in front of Node, set the public protocol explicitly:
+
+```ts
+await serve(app, { port: 3000, protocol: "https" })
+```
+
+Forwarded protocol headers are not trusted automatically; pass a function only when your
+own trusted infrastructure has validated the request:
+
+```ts
+await serve(app, {
+  port: 3000,
+  protocol: (req) => req.headers["x-forwarded-proto"] === "https" ? "https" : "http",
+})
+```
+
+## Graceful shutdown on signals
+
+Opt in to SIGTERM/SIGINT handling so a `docker stop` / Ctrl-C drains in-flight requests
+before exit (mirrors Bun's `listen({ gracefulSignals })` — off by default, since owning
+process signals should be a deliberate choice):
+
+```ts
+await serve(app, { port: 3000, signals: true })
+```
+
+## What you get for free
+
+The request timeout (`server({ requestTimeoutMs })` → `503 request_timeout`) and body-size
+cap live **inside `app.fetch`**, not Bun's `listen()` — so they apply through this adapter
+with no extra wiring. Slow-client / slow-loris protection is Node's built-in
+`requestTimeout` (300s) and `headersTimeout` (60s) defaults.
+
+Works with any `{ fetch(req): Promise<Response> }` handler, not just nifra. ESM-only. MIT.

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { type IncomingMessage } from "node:http";
+/** Anything exposing a Web `fetch` handler — a nifra `app`, for instance. */
+export interface FetchHandler {
+    fetch(request: Request): Response | Promise<Response>;
+    /** Nifra apps also expose this WS-upgrade seam; present → this adapter serves `app.ws()` routes via
+     * the optional `ws` package (lazy-imported on the first upgrade). Absent (a plain `{ fetch }`
+     * handler) → HTTP only, and an upgrade request gets a 404. */
+    resolveWebSocketUpgrade?(request: Request): WsUpgradeOutcome | Promise<WsUpgradeOutcome>;
+}
+/** A received frame, normalized: text → `string`, binary → `Uint8Array`. */
+type NifraWsData = string | Uint8Array;
+/** The portable socket a nifra WS handler sees (mirror of core's `NifraWebSocket`). */
+interface NifraWs {
+    send(data: string | ArrayBufferView | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    data: unknown;
+    readonly raw: unknown;
+}
+/** Mirror of core's `TopicRegistry` surface — the app's pub/sub the adapter wires `ws.subscribe` to. */
+interface WsPubSub {
+    subscribe(topic: string, ws: NifraWs): void;
+    unsubscribe(topic: string, ws: NifraWs): void;
+    unsubscribeAll(ws: NifraWs): void;
+}
+/** A nifra WS route's lifecycle (mirror of core's `WebSocketHandler` — the post-upgrade callbacks). */
+interface NifraWsHandler {
+    open?(ws: NifraWs): void | Promise<void>;
+    message?(ws: NifraWs, data: NifraWsData): void | Promise<void>;
+    close?(ws: NifraWs, code: number, reason: string): void | Promise<void>;
+    error?(ws: NifraWs, error: unknown): void | Promise<void>;
+}
+/** Mirror of core's `WebSocketUpgradeOutcome` — what `resolveWebSocketUpgrade` returns. */
+type WsUpgradeOutcome = {
+    readonly kind: "pass";
+} | {
+    readonly kind: "reject";
+    readonly response: Response;
+} | {
+    readonly kind: "upgrade";
+    readonly handler: NifraWsHandler;
+    readonly data: unknown;
+    readonly pubsub: WsPubSub;
+};
+export type RequestProtocol = "http" | "https";
+export type RequestProtocolOption = RequestProtocol | ((request: IncomingMessage) => RequestProtocol);
+/**
+ * Serve static files from a directory (e.g. the client build) under a URL prefix — so a self-hosted
+ * Node deploy doesn't need a CDN or a hand-rolled `/assets/*` handler. (On Cloudflare/Vercel the
+ * platform serves assets; this is for `node server.js`.)
+ */
+export interface ServeStaticOptions {
+    /** Directory to read files from — an absolute path or a `file://` URL (`new URL("./assets/", import.meta.url)`). */
+    readonly dir: string | URL;
+    /** URL prefix these files are served under. Default `"/assets"`. Use `"/"` to serve the whole dir. */
+    readonly prefix?: string;
+    /** Emit `cache-control: public, max-age=31536000, immutable` — correct for content-hashed files. Default `true`. */
+    readonly immutable?: boolean;
+    /** Extra headers merged onto every served file. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface ServeOptions {
+    readonly port: number;
+    readonly hostname?: string;
+    /**
+     * Protocol used when the adapter constructs `Request.url`.
+     *
+     * `@nifrajs/node` creates a plain Node `http` server, so the safe default is `"http"`. Deployments behind
+     * TLS termination can set `"https"` (or a trusted infra-aware function) so app code that reads
+     * `request.url` sees the public scheme. Forwarded headers are not trusted implicitly.
+     */
+    readonly protocol?: RequestProtocolOption;
+    /**
+     * Install SIGTERM/SIGINT handlers that call `stop()` for a graceful drain on
+     * `docker stop` / Ctrl-C. Off by default — taking over process signals is opt-in,
+     * mirroring nifra's Bun `listen({ gracefulSignals })`.
+     *
+     * The app-level request timeout (`server({ requestTimeoutMs })` → 503) and body cap
+     * are *not* set here — they live inside `app.fetch`, so they already apply through
+     * this adapter. Slow-client protection is Node's built-in `requestTimeout` (300s) /
+     * `headersTimeout` (60s) defaults.
+     */
+    readonly signals?: boolean;
+    /**
+     * Serve static files from disk for matching GET/HEAD requests *before* the app runs — non-matching
+     * requests fall through to `app.fetch` with the node-direct fast path intact (no perf regression on
+     * SSR/API routes). Replaces the hand-rolled `/assets/*` reader in self-hosted entries.
+     */
+    readonly static?: ServeStaticOptions;
+}
+export interface NodeServer {
+    /** The bound port (resolved when `port: 0` is requested). */
+    readonly port: number;
+    /**
+     * Stop accepting connections, let in-flight requests drain (up to `drainMs`), then
+     * force-close stragglers + idle keep-alives. Mirrors nifra's Bun `stop()`.
+     */
+    stop(options?: {
+        drainMs?: number;
+    }): Promise<void>;
+}
+/**
+ * Serve a Web-`fetch` app on a Node `http` server. Resolves once bound — Node binds
+ * the port asynchronously, so awaiting gives you the real port (matters for `port: 0`).
+ */
+export declare function serve(app: FetchHandler, options: ServeOptions): Promise<NodeServer>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}