@fluojs/platform-nodejs 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+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.ko.md

@@ -0,0 +1,90 @@
+# @fluojs/platform-nodejs
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 런타임을 위한 raw Node.js HTTP 어댑터 패키지입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 패턴](#주요-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/platform-nodejs
+```
+
+## 사용 시점
+
+Express나 Fastify와 같은 중간 프레임워크의 오버헤드 없이 Node.js 내장 `http` 또는 `https` 모듈에서 직접 fluo 애플리케이션을 실행하려는 경우에 사용합니다. 최소한의 리소스 사용, 저수준 최적화 또는 표준 Node API가 선호되는 환경에 이상적입니다.
+
+## 빠른 시작
+
+```typescript
+import { createNodejsAdapter } from '@fluojs/platform-nodejs';
+import { fluoFactory } from '@fluojs/runtime';
+import { AppModule } from './app.module';
+
+const app = await fluoFactory.create(AppModule, {
+  adapter: createNodejsAdapter({ port: 3000 }),
+});
+
+await app.listen();
+```
+
+## 주요 패턴
+
+### 서버 옵션 커스텀
+어댑터는 HTTPS 설정 및 바디 크기 제한을 포함한 표준 Node.js 서버 옵션을 수용합니다.
+
+```typescript
+const adapter = createNodejsAdapter({
+  port: 443,
+  https: {
+    key: fs.readFileSync('key.pem'),
+    cert: fs.readFileSync('cert.pem'),
+  },
+  maxBodySize: '1mb',
+});
+```
+
+`maxBodySize`는 raw Node 요청 바디가 아직 스트리밍되는 동안 바로 강제되며, 부트스트랩 시 `multipart.maxTotalSize`를 따로 재정의하지 않으면 같은 값이 멀티파트 전체 페이로드 한도의 기본값으로도 사용됩니다.
+
+### 직접 애플리케이션 실행
+`runNodejsApplication`을 사용하여 graceful shutdown 및 로깅이 포함된 보일러플레이트 없는 시작이 가능합니다.
+
+시그널 기반 종료가 `forceExitTimeoutMs`를 넘기거나 실패하면 헬퍼는 해당 상태를 로그와 `process.exitCode`로 보고하지만, 최종 프로세스 종료는 호스트 프로세스 소유자에게 맡깁니다.
+
+```typescript
+import { runNodejsApplication } from '@fluojs/platform-nodejs';
+import { AppModule } from './app.module';
+
+await runNodejsApplication(AppModule, {
+  port: 3000,
+  globalPrefix: 'api',
+});
+```
+
+## 공개 API 개요
+
+- `createNodejsAdapter(options)`: raw Node.js HTTP 어댑터를 위한 기본 팩토리입니다.
+- `bootstrapNodejsApplication(module, options)`: 리스너를 시작하지 않고 애플리케이션 인스턴스를 생성합니다.
+- `runNodejsApplication(module, options)`: 생명주기 관리를 포함하여 애플리케이션을 부트스트랩하고 시작합니다.
+- `NodejsHttpApplicationAdapter`: `createNodejsAdapter(...)`가 반환하는 어댑터 인스턴스를 설명하는 타입 전용 별칭이며, `@fluojs/runtime/node`가 공개하는 어댑터 surface를 그대로 보존합니다.
+
+## 관련 패키지
+
+- `@fluojs/runtime`: 핵심 런타임 facade입니다.
+- `@fluojs/websockets`: 실시간 게이트웨이 지원을 제공합니다.
+- `@fluojs/http`: 공통 HTTP 추상화 및 데코레이터를 포함합니다.
+
+## 예제 소스
+
+- `packages/platform-nodejs/src/index.test.ts`
+- `examples/minimal/src/main.ts` (Fastify 기반이지만 구조적으로 유사함)

package/README.md

@@ -0,0 +1,90 @@
+# @fluojs/platform-nodejs
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Raw Node.js HTTP adapter package for the fluo runtime.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/platform-nodejs
+```
+
+## When to Use
+
+Use this package when you want to run a fluo application directly on the Node.js built-in `http` or `https` modules without the overhead of an intermediate framework like Express or Fastify. It is ideal for minimal footprints, custom low-level optimizations, or environments where standard Node APIs are preferred.
+
+## Quick Start
+
+```typescript
+import { createNodejsAdapter } from '@fluojs/platform-nodejs';
+import { fluoFactory } from '@fluojs/runtime';
+import { AppModule } from './app.module';
+
+const app = await fluoFactory.create(AppModule, {
+  adapter: createNodejsAdapter({ port: 3000 }),
+});
+
+await app.listen();
+```
+
+## Common Patterns
+
+### Customizing Server Options
+The adapter accepts standard Node.js server options including HTTPS configuration and body size limits.
+
+```typescript
+const adapter = createNodejsAdapter({
+  port: 443,
+  https: {
+    key: fs.readFileSync('key.pem'),
+    cert: fs.readFileSync('cert.pem'),
+  },
+  maxBodySize: '1mb',
+});
+```
+
+`maxBodySize` is enforced while the raw Node request body is still streaming, and the same limit becomes the default total multipart payload cap unless you override `multipart.maxTotalSize` during bootstrap.
+
+### Direct Application Execution
+You can use `runNodejsApplication` for a zero-boilerplate startup that includes graceful shutdown and logging.
+
+When signal-driven shutdown exceeds `forceExitTimeoutMs` or fails, the helper logs the condition and sets `process.exitCode`, but leaves final process termination to the host process owner.
+
+```typescript
+import { runNodejsApplication } from '@fluojs/platform-nodejs';
+import { AppModule } from './app.module';
+
+await runNodejsApplication(AppModule, {
+  port: 3000,
+  globalPrefix: 'api',
+});
+```
+
+## Public API Overview
+
+- `createNodejsAdapter(options)`: Primary factory for the raw Node.js HTTP adapter.
+- `bootstrapNodejsApplication(module, options)`: Creates an application instance without starting the listener.
+- `runNodejsApplication(module, options)`: Bootstraps and starts the application with lifecycle management.
+- `NodejsHttpApplicationAdapter`: Type-only alias describing the adapter instances returned by `createNodejsAdapter(...)`, while preserving the public adapter surface exported from `@fluojs/runtime/node`.
+
+## Related Packages
+
+- `@fluojs/runtime`: The core runtime facade.
+- `@fluojs/websockets`: Real-time gateway support.
+- `@fluojs/http`: Shared HTTP abstractions and decorators.
+
+## Example Sources
+
+- `packages/platform-nodejs/src/index.test.ts`
+- `examples/minimal/src/main.ts` (Fastify-based, but structurally similar)

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { type NodeHttpAdapterOptions, type NodeHttpApplicationAdapter } from '@fluojs/runtime/node';
+export { bootstrapNodeApplication as bootstrapNodejsApplication, runNodeApplication as runNodejsApplication, } from '@fluojs/runtime/node';
+export type { BootstrapNodeApplicationOptions as BootstrapNodejsApplicationOptions, NodeApplicationSignal as NodejsApplicationSignal, NodeHttpAdapterOptions as NodejsAdapterOptions, NodeHttpApplicationAdapter as NodejsHttpApplicationAdapter, RunNodeApplicationOptions as RunNodejsApplicationOptions, } from '@fluojs/runtime/node';
+/**
+ * Create the raw Node.js HTTP adapter exposed by `@fluojs/platform-nodejs`.
+ *
+ * @param options Transport-level Node.js settings such as port, retries, multipart, and HTTPS options.
+ * @returns The Node.js HTTP adapter instance used by the Fluo runtime.
+ */
+export declare function createNodejsAdapter(options?: NodeHttpAdapterOptions): NodeHttpApplicationAdapter;
+//# 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":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAChC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,wBAAwB,IAAI,0BAA0B,EACtD,kBAAkB,IAAI,oBAAoB,GAC3C,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,+BAA+B,IAAI,iCAAiC,EACpE,qBAAqB,IAAI,uBAAuB,EAChD,sBAAsB,IAAI,oBAAoB,EAC9C,0BAA0B,IAAI,4BAA4B,EAC1D,yBAAyB,IAAI,2BAA2B,GACzD,MAAM,sBAAsB,CAAC;AAE9B;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,sBAA2B,GACnC,0BAA0B,CAE5B"}

package/dist/index.js

@@ -0,0 +1,11 @@
+import { createNodeHttpAdapter } from '@fluojs/runtime/node';
+export { bootstrapNodeApplication as bootstrapNodejsApplication, runNodeApplication as runNodejsApplication } from '@fluojs/runtime/node';
+/**
+ * Create the raw Node.js HTTP adapter exposed by `@fluojs/platform-nodejs`.
+ *
+ * @param options Transport-level Node.js settings such as port, retries, multipart, and HTTPS options.
+ * @returns The Node.js HTTP adapter instance used by the Fluo runtime.
+ */
+export function createNodejsAdapter(options = {}) {
+  return createNodeHttpAdapter(options);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fluojs/platform-nodejs",
+  "description": "Raw Node.js HTTP adapter package for the Fluo runtime.",
+  "keywords": [
+    "fluo",
+    "nodejs",
+    "node",
+    "http-adapter",
+    "platform",
+    "server"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/platform-nodejs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/http": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}