https://github.com/stone-foundation/stone-js-node-http-adapter
Node HTTP adapter for Stone.js. Run your app on any Node.js HTTP server using the Continuum Architecture.
https://github.com/stone-foundation/stone-js-node-http-adapter
context-aware continuum-architecture javascript official-stonejs stone-foundation stonejs stonejs-adapter typescript
Last synced: 3 months ago
JSON representation
Node HTTP adapter for Stone.js. Run your app on any Node.js HTTP server using the Continuum Architecture.
- Host: GitHub
- URL: https://github.com/stone-foundation/stone-js-node-http-adapter
- Owner: stone-foundation
- License: mit
- Created: 2023-12-17T04:11:11.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-11-02T05:06:04.000Z (8 months ago)
- Last Synced: 2026-03-28T00:37:21.018Z (3 months ago)
- Topics: context-aware, continuum-architecture, javascript, official-stonejs, stone-foundation, stonejs, stonejs-adapter, typescript
- Language: TypeScript
- Homepage: https://stonejs.dev
- Size: 263 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Stone.js - Node HTTP Adapter
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@stone-js/node-http-adapter)
[](https://www.npmjs.com/package/@stone-js/node-http-adapter)
[](https://github.com/stone-foundation/stone-js-node-http-adapter/actions/workflows/main.yml)
[](https://github.com/stone-foundation/stone-js-node-http-adapter/actions/workflows/release.yml)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-node-http-adapter)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-node-http-adapter)
[](./SECURITY.md)
[](https://github.com/stone-foundation/stone-js-node-http-adapter/security/code-scanning)
[](https://github.com/stone-foundation/stone-js-node-http-adapter/network/updates)
[](https://conventionalcommits.org)
The **Node HTTP Adapter** enables your Stone.js application to run in any Node.js HTTP environment. It provides a low-level bridge between raw Node HTTP events and the internal event system of Stone.js, fully aligned with the Continuum Architecture.
---
## Introduction
In Stone.js, **adapters** are the translation layer between the outside world and your internal logic. The Node HTTP Adapter handles incoming HTTP requests from Node’s built-in `http` module, transforming them into standardized `IncomingEvent` objects, and turning your system’s `OutgoingResponse` back into proper HTTP responses.
This adapter allows your Stone.js app to behave like a traditional web server, without requiring Express or any framework overhead, while still benefiting from Stone.js’s unified event model, clean lifecycle, and platform independence.
## Installation
```bash
npm install @stone-js/node-http-adapter
```
> This package is **pure ESM**. Make sure your project uses ESM (`"type": "module"` in `package.json`) or configure your tooling accordingly.
## Usage
You can integrate the adapter either declaratively with a decorator or imperatively using the `nodeHttpAdapterBlueprint`.
### Declarative API
```ts
import { NodeHttp } from '@stone-js/node-http-adapter'
import { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'
@StoneApp()
@NodeHttp({ url: 'http://localhost:8081' })
export class Application implements IEventHandler {
handle(event: IncomingEvent) {
const name = event.get('name', 'World')
return { message: `Hello ${name}` }
}
}
```
### Imperative API
```ts
import { defineStoneApp, IncomingEvent, defineConfig, IBlueprint } from '@stone-js/core'
import { nodeHttpAdapterBlueprint, NODE_HTTP_PLATFORM } from '@stone-js/node-http-adapter'
const handler = (event: IncomingEvent) => {
const name = event.get('name', 'World')
return { message: `Hi ${name}` }
}
export const App = defineStoneApp(handler, {}, [nodeHttpAdapterBlueprint])
export const AppConfig = defineConfig({
afterConfigure(blueprint: IBlueprint) {
if (blueprint.is('stone.adapter.platform', NODE_HTTP_PLATFORM)) {
blueprint.set('stone.adapter.url', 'http://localhost:8081')
}
}
})
```
## What It Enables
* **Universal HTTP Support**
Run your Stone.js app on any Node.js HTTP server. No Express or external framework needed.
* **Full Continuum Integration**
HTTP becomes a native dimension of your system: requests and responses are transformed into `IncomingEvent` and `OutgoingResponse`, respecting the Continuum model.
* **Server-Level Middleware**
Add `serverMiddleware[]` to intercept raw HTTP traffic before Stone.js handles it. Works with most connect-style middlewares.
* **Lifecycle and Hook Support**
Includes support for `onStart`, `onStop`, error hooks, and adapter middleware pipelines.
* **Rich Event Context**
Access IP, cookies, headers, body, uploaded files, and more in a normalized and typed format.
* **Streaming & File Uploads**
Direct access to Node’s `IncomingMessage` and `ServerResponse` for advanced use cases like streaming or file handling.
* **First-Class TypeScript Support**
Strong typings for all configuration, events, and response types.
* **Built-in Error Handling**
Customize how errors are caught and transformed into HTTP responses.
## Configuration Options
| Option | Type | Description |
| -------------------- | ----------------------------------------- | --------------------------------------------------------------- |
| `url` | `string` | Base URL of the server. Example: `http://localhost:3000` |
| `isSsl` | `boolean` | Whether to use HTTPS |
| `server` | `NodeServerOptions` | Native Node server configuration |
| `printUrls` | `boolean` | Log URL(s) to console on server start |
| `serverMiddleware[]` | `Array<(req, res, next) => void>` | Platform-level connect-like middleware before Stone.js kicks in |
| `alias` | `string` | Optional name for referencing the adapter |
| `default` | `boolean` | Set as default adapter for the app |
| `current` | `boolean` | Mark this as the active adapter during runtime |
| `middleware[]` | `AdapterMixedPipeType[]` | Middleware for request/response within the Stone.js lifecycle |
| `errorHandlers` | `Record` | Fine-grained adapter-level error handling |
## Adapter Context Shape
When middleware or integration hooks execute, they receive the following context object:
```ts
interface NodeHttpAdapterContext {
rawEvent: IncomingMessage;
rawResponse?: ServerResponse;
executionContext: NodeHttpServer;
incomingEvent?: IncomingHttpEvent;
outgoingResponse?: OutgoingHttpResponse;
incomingEventBuilder: IAdapterEventBuilder;
rawResponseBuilder: IAdapterEventBuilder>;
}
```
These values expose the full HTTP lifecycle and provide access to Stone.js event builders.
### Incoming HTTP Event Options
```ts
interface IncomingHttpEventOptions {
url: URL;
ip: string;
ips?: string[];
protocol?: string;
method?: HttpMethods;
queryString?: string;
cookies?: CookieCollection;
body?: Record;
files?: Record;
headers?: Record | Headers;
}
```
### Raw HTTP Response Options
```ts
interface RawHttpResponseOptions {
body: unknown;
charset?: string;
statusCode: number;
statusMessage: string;
headers: Map | Headers;
streamFile?: () => void | Promise;
}
```
This context flows through all adapter middleware and hooks.
## Summary
The `@stone-js/node-http-adapter` brings your Stone.js application to life in the HTTP world. With seamless integration, native Node support, and complete event transformation, you can build modern APIs, websites, or microservices that feel as fast and flexible as Node, but with the architectural rigor of Stone.js.
## Learn More
This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.
Explore the full documentation: [https://stonejs.dev](https://stonejs.dev)
## API documentation
* [API](https://github.com/stone-foundation/stone-js-node-http-adapter/blob/main/docs)
## Contributing
See [Contributing Guide](https://github.com/stone-foundation/stone-js-node-http-adapter/blob/main/CONTRIBUTING.md)