qhttpx 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (197) hide show
  1. package/.eslintrc.json +22 -0
  2. package/.github/workflows/ci.yml +32 -0
  3. package/.github/workflows/npm-publish.yml +37 -0
  4. package/.github/workflows/release.yml +21 -0
  5. package/.prettierrc +7 -0
  6. package/CHANGELOG.md +145 -0
  7. package/LICENSE +21 -0
  8. package/README.md +343 -0
  9. package/dist/package.json +61 -0
  10. package/dist/src/benchmarks/compare-frameworks.js +119 -0
  11. package/dist/src/benchmarks/quantam-users.js +56 -0
  12. package/dist/src/benchmarks/simple-json.js +58 -0
  13. package/dist/src/benchmarks/ultra-mode.js +122 -0
  14. package/dist/src/cli/index.js +200 -0
  15. package/dist/src/client/index.js +72 -0
  16. package/dist/src/core/batch.js +97 -0
  17. package/dist/src/core/body-parser.js +121 -0
  18. package/dist/src/core/buffer-pool.js +70 -0
  19. package/dist/src/core/config.js +50 -0
  20. package/dist/src/core/fusion.js +183 -0
  21. package/dist/src/core/logger.js +49 -0
  22. package/dist/src/core/metrics.js +111 -0
  23. package/dist/src/core/resources.js +25 -0
  24. package/dist/src/core/scheduler.js +85 -0
  25. package/dist/src/core/scope.js +68 -0
  26. package/dist/src/core/serializer.js +44 -0
  27. package/dist/src/core/server.js +905 -0
  28. package/dist/src/core/stream.js +71 -0
  29. package/dist/src/core/tasks.js +87 -0
  30. package/dist/src/core/types.js +19 -0
  31. package/dist/src/core/websocket.js +86 -0
  32. package/dist/src/core/worker-queue.js +73 -0
  33. package/dist/src/database/adapters/memory.js +90 -0
  34. package/dist/src/database/adapters/mongo.js +141 -0
  35. package/dist/src/database/adapters/postgres.js +111 -0
  36. package/dist/src/database/adapters/sqlite.js +42 -0
  37. package/dist/src/database/coalescer.js +134 -0
  38. package/dist/src/database/manager.js +87 -0
  39. package/dist/src/database/types.js +2 -0
  40. package/dist/src/index.js +61 -0
  41. package/dist/src/middleware/compression.js +133 -0
  42. package/dist/src/middleware/cors.js +66 -0
  43. package/dist/src/middleware/presets.js +33 -0
  44. package/dist/src/middleware/rate-limit.js +77 -0
  45. package/dist/src/middleware/security.js +69 -0
  46. package/dist/src/middleware/static.js +191 -0
  47. package/dist/src/openapi/generator.js +149 -0
  48. package/dist/src/router/radix-router.js +89 -0
  49. package/dist/src/router/radix-tree.js +81 -0
  50. package/dist/src/router/router.js +146 -0
  51. package/dist/src/testing/index.js +84 -0
  52. package/dist/src/utils/cookies.js +59 -0
  53. package/dist/src/utils/logger.js +45 -0
  54. package/dist/src/utils/signals.js +31 -0
  55. package/dist/src/utils/sse.js +32 -0
  56. package/dist/src/validation/index.js +19 -0
  57. package/dist/src/validation/simple.js +102 -0
  58. package/dist/src/validation/types.js +12 -0
  59. package/dist/src/validation/zod.js +18 -0
  60. package/dist/src/views/index.js +17 -0
  61. package/dist/src/views/types.js +2 -0
  62. package/dist/tests/adapters.test.js +106 -0
  63. package/dist/tests/batch.test.js +117 -0
  64. package/dist/tests/body-parser.test.js +52 -0
  65. package/dist/tests/compression-sse.test.js +87 -0
  66. package/dist/tests/cookies.test.js +63 -0
  67. package/dist/tests/cors.test.js +55 -0
  68. package/dist/tests/database.test.js +80 -0
  69. package/dist/tests/dx.test.js +64 -0
  70. package/dist/tests/ecosystem.test.js +133 -0
  71. package/dist/tests/features.test.js +47 -0
  72. package/dist/tests/fusion.test.js +92 -0
  73. package/dist/tests/http-basic.test.js +124 -0
  74. package/dist/tests/logger.test.js +33 -0
  75. package/dist/tests/middleware.test.js +109 -0
  76. package/dist/tests/observability.test.js +59 -0
  77. package/dist/tests/openapi.test.js +64 -0
  78. package/dist/tests/plugin.test.js +65 -0
  79. package/dist/tests/plugins.test.js +71 -0
  80. package/dist/tests/rate-limit.test.js +77 -0
  81. package/dist/tests/resources.test.js +44 -0
  82. package/dist/tests/scheduler.test.js +46 -0
  83. package/dist/tests/schema-routes.test.js +77 -0
  84. package/dist/tests/security.test.js +83 -0
  85. package/dist/tests/server-db.test.js +72 -0
  86. package/dist/tests/smoke.test.js +10 -0
  87. package/dist/tests/sqlite-fusion.test.js +92 -0
  88. package/dist/tests/static.test.js +102 -0
  89. package/dist/tests/stream.test.js +44 -0
  90. package/dist/tests/task-metrics.test.js +53 -0
  91. package/dist/tests/tasks.test.js +62 -0
  92. package/dist/tests/testing.test.js +47 -0
  93. package/dist/tests/validation.test.js +107 -0
  94. package/dist/tests/websocket.test.js +146 -0
  95. package/dist/vitest.config.js +9 -0
  96. package/docs/AEGIS.md +76 -0
  97. package/docs/BENCHMARKS.md +36 -0
  98. package/docs/CAPABILITIES.md +70 -0
  99. package/docs/CLI.md +43 -0
  100. package/docs/DATABASE.md +142 -0
  101. package/docs/ECOSYSTEM.md +146 -0
  102. package/docs/NEXT_STEPS.md +99 -0
  103. package/docs/OPENAPI.md +99 -0
  104. package/docs/PLUGINS.md +59 -0
  105. package/docs/REAL_WORLD_EXAMPLES.md +109 -0
  106. package/docs/ROADMAP.md +366 -0
  107. package/docs/VALIDATION.md +136 -0
  108. package/eslint.config.cjs +26 -0
  109. package/examples/api-server.ts +254 -0
  110. package/package.json +61 -0
  111. package/src/benchmarks/compare-frameworks.ts +149 -0
  112. package/src/benchmarks/quantam-users.ts +70 -0
  113. package/src/benchmarks/simple-json.ts +71 -0
  114. package/src/benchmarks/ultra-mode.ts +159 -0
  115. package/src/cli/index.ts +214 -0
  116. package/src/client/index.ts +93 -0
  117. package/src/core/batch.ts +110 -0
  118. package/src/core/body-parser.ts +151 -0
  119. package/src/core/buffer-pool.ts +96 -0
  120. package/src/core/config.ts +60 -0
  121. package/src/core/fusion.ts +210 -0
  122. package/src/core/logger.ts +70 -0
  123. package/src/core/metrics.ts +166 -0
  124. package/src/core/resources.ts +38 -0
  125. package/src/core/scheduler.ts +126 -0
  126. package/src/core/scope.ts +87 -0
  127. package/src/core/serializer.ts +41 -0
  128. package/src/core/server.ts +1113 -0
  129. package/src/core/stream.ts +111 -0
  130. package/src/core/tasks.ts +138 -0
  131. package/src/core/types.ts +178 -0
  132. package/src/core/websocket.ts +112 -0
  133. package/src/core/worker-queue.ts +90 -0
  134. package/src/database/adapters/memory.ts +99 -0
  135. package/src/database/adapters/mongo.ts +116 -0
  136. package/src/database/adapters/postgres.ts +86 -0
  137. package/src/database/adapters/sqlite.ts +44 -0
  138. package/src/database/coalescer.ts +153 -0
  139. package/src/database/manager.ts +97 -0
  140. package/src/database/types.ts +24 -0
  141. package/src/index.ts +42 -0
  142. package/src/middleware/compression.ts +147 -0
  143. package/src/middleware/cors.ts +98 -0
  144. package/src/middleware/presets.ts +50 -0
  145. package/src/middleware/rate-limit.ts +106 -0
  146. package/src/middleware/security.ts +109 -0
  147. package/src/middleware/static.ts +216 -0
  148. package/src/openapi/generator.ts +167 -0
  149. package/src/router/radix-router.ts +119 -0
  150. package/src/router/radix-tree.ts +106 -0
  151. package/src/router/router.ts +190 -0
  152. package/src/testing/index.ts +104 -0
  153. package/src/utils/cookies.ts +67 -0
  154. package/src/utils/logger.ts +59 -0
  155. package/src/utils/signals.ts +45 -0
  156. package/src/utils/sse.ts +41 -0
  157. package/src/validation/index.ts +3 -0
  158. package/src/validation/simple.ts +93 -0
  159. package/src/validation/types.ts +38 -0
  160. package/src/validation/zod.ts +14 -0
  161. package/src/views/index.ts +1 -0
  162. package/src/views/types.ts +4 -0
  163. package/tests/adapters.test.ts +120 -0
  164. package/tests/batch.test.ts +139 -0
  165. package/tests/body-parser.test.ts +83 -0
  166. package/tests/compression-sse.test.ts +98 -0
  167. package/tests/cookies.test.ts +74 -0
  168. package/tests/cors.test.ts +79 -0
  169. package/tests/database.test.ts +90 -0
  170. package/tests/dx.test.ts +78 -0
  171. package/tests/ecosystem.test.ts +156 -0
  172. package/tests/features.test.ts +51 -0
  173. package/tests/fusion.test.ts +121 -0
  174. package/tests/http-basic.test.ts +161 -0
  175. package/tests/logger.test.ts +48 -0
  176. package/tests/middleware.test.ts +137 -0
  177. package/tests/observability.test.ts +91 -0
  178. package/tests/openapi.test.ts +74 -0
  179. package/tests/plugin.test.ts +85 -0
  180. package/tests/plugins.test.ts +93 -0
  181. package/tests/rate-limit.test.ts +97 -0
  182. package/tests/resources.test.ts +64 -0
  183. package/tests/scheduler.test.ts +71 -0
  184. package/tests/schema-routes.test.ts +89 -0
  185. package/tests/security.test.ts +128 -0
  186. package/tests/server-db.test.ts +72 -0
  187. package/tests/smoke.test.ts +9 -0
  188. package/tests/sqlite-fusion.test.ts +106 -0
  189. package/tests/static.test.ts +111 -0
  190. package/tests/stream.test.ts +58 -0
  191. package/tests/task-metrics.test.ts +78 -0
  192. package/tests/tasks.test.ts +90 -0
  193. package/tests/testing.test.ts +53 -0
  194. package/tests/validation.test.ts +126 -0
  195. package/tests/websocket.test.ts +132 -0
  196. package/tsconfig.json +16 -0
  197. package/vitest.config.ts +9 -0
package/.eslintrc.json ADDED
@@ -0,0 +1,22 @@
1
+ {
2
+ "root": true,
3
+ "env": {
4
+ "es2020": true,
5
+ "node": true
6
+ },
7
+ "parser": "@typescript-eslint/parser",
8
+ "parserOptions": {
9
+ "project": "./tsconfig.json",
10
+ "sourceType": "module"
11
+ },
12
+ "plugins": ["@typescript-eslint"],
13
+ "extends": [
14
+ "eslint:recommended",
15
+ "plugin:@typescript-eslint/recommended",
16
+ "plugin:prettier/recommended"
17
+ ],
18
+ "rules": {
19
+ "@typescript-eslint/no-explicit-any": "off"
20
+ },
21
+ "ignorePatterns": ["dist/**", "node_modules/**"]
22
+ }
@@ -0,0 +1,32 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ - master
8
+ pull_request:
9
+
10
+ jobs:
11
+ build-and-test:
12
+ runs-on: ubuntu-latest
13
+
14
+ steps:
15
+ - name: Checkout
16
+ uses: actions/checkout@v4
17
+
18
+ - name: Setup Node.js
19
+ uses: actions/setup-node@v4
20
+ with:
21
+ node-version: 20
22
+ cache: "npm"
23
+
24
+ - name: Install dependencies
25
+ run: npm ci
26
+
27
+ - name: Lint
28
+ run: npm run lint
29
+
30
+ - name: Test
31
+ run: npm test
32
+
@@ -0,0 +1,37 @@
1
+ name: Publish to NPM
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ jobs:
8
+ publish:
9
+ runs-on: ubuntu-latest
10
+ permissions:
11
+ contents: read
12
+ id-token: write
13
+
14
+ steps:
15
+ - name: Checkout
16
+ uses: actions/checkout@v4
17
+
18
+ - name: Setup Node.js
19
+ uses: actions/setup-node@v4
20
+ with:
21
+ node-version: 20
22
+ registry-url: 'https://registry.npmjs.org'
23
+ cache: 'npm'
24
+
25
+ - name: Install dependencies
26
+ run: npm ci
27
+
28
+ - name: Build
29
+ run: npm run build
30
+
31
+ - name: Test
32
+ run: npm test
33
+
34
+ - name: Publish to NPM
35
+ run: npm publish --access public
36
+ env:
37
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
@@ -0,0 +1,21 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ permissions:
9
+ contents: write
10
+
11
+ jobs:
12
+ release:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - name: Checkout
16
+ uses: actions/checkout@v4
17
+
18
+ - name: Create Release
19
+ uses: softprops/action-gh-release@v1
20
+ with:
21
+ generate_release_notes: true
package/.prettierrc ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "singleQuote": true,
3
+ "semi": true,
4
+ "trailingComma": "all",
5
+ "printWidth": 80,
6
+ "endOfLine": "auto"
7
+ }
package/CHANGELOG.md ADDED
@@ -0,0 +1,145 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [1.8.0] - 2026-01-20
6
+ **"The Full-Stack Update"**
7
+
8
+ ### Added
9
+ - **Compression Middleware**: Native support for Gzip, Brotli, and Deflate response compression with auto-thresholding (default 1KB) and stream piping.
10
+ - **Server-Sent Events (SSE)**: Built-in `createSSE()` helper for easy real-time event streaming with automatic header management and connection persistence.
11
+ - **Advanced Static Files**: Completely rewritten `static` middleware with support for **Streaming**, **Range Requests** (for video), and **HTTP Caching** (ETag/Last-Modified/304).
12
+ - **Multipart Support**: Integrated `busboy` for high-performance `multipart/form-data` parsing. Files are automatically available in `ctx.files`.
13
+ - **View Engine**: New `ViewEngine` interface and `ctx.render()` method for server-side template rendering (supports EJS, Pug, etc. via adapters).
14
+ - **WebSocket Channels**: Enhanced WebSocket support with a Pub/Sub "Rooms" system for easy broadcasting to specific groups of clients.
15
+ - **Zod Integration**: Official support for Zod schemas in `ctx.validate()`, enabling robust type-safe validation.
16
+
17
+ ## [1.7.0] - 2026-01-20
18
+ **"The Developer Experience Update"**
19
+
20
+ ### Added
21
+ - **QCLI**: New Command Line Interface (`qhttpx`) for streamlined development and deployment.
22
+ - **Cluster Mode**: `qhttpx start <file>` automatically forks workers across all CPU cores for maximum performance.
23
+ - **Dev Mode**: `qhttpx dev <file>` provides hot-reloading and TypeScript support out of the box.
24
+ - **Resilience**: Built-in worker monitoring and automatic restart on crash in production mode.
25
+
26
+ ## [1.6.0] - 2026-01-20
27
+ **"The Extension Update"**
28
+
29
+ ### Added
30
+ - **Plugin System**: Full-featured Extension Protocol allowing modular architecture via `app.register()`.
31
+ - **Scoped Routing**: Plugins run in isolated scopes with automatic path prefixing (e.g., `app.register(api, { prefix: '/api' })`).
32
+ - **Async Initialization**: Plugins can be async (e.g., for database connections), and the server waits for them.
33
+ - **Nested Plugins**: Plugins can register other plugins, inheriting and concatenating prefixes automatically.
34
+ - **Encapsulation**: `QHTTPXScope` ensures plugins don't accidentally pollute the global namespace.
35
+
36
+ ## [1.5.0] - 2026-01-20
37
+ **"The Aegis Update"**
38
+
39
+ ### Added
40
+ - **Aegis Rate Limiter**: High-performance, Token Bucket-based rate limiting middleware to protect against DDoS and abuse.
41
+ - **Dual-Layer Storage**: Default in-memory storage with automatic cleanup, designed to be swappable with Redis/KV stores.
42
+ - **Smart Headers**: Automatic `X-RateLimit-*` and `Retry-After` header injection for standard compliance.
43
+ - **Flexible Keys**: Support for custom key generators (IP, API Key, User ID) to enable tiered rate limiting.
44
+
45
+ ## [1.4.0] - 2026-01-20
46
+ **"The Quantum Collapse Update"**
47
+
48
+ ### Added
49
+ - **Request Fusion Engine**: A revolutionary request-level coalescing system (Layer 2) that collapses simultaneous requests to the same endpoint into a single execution.
50
+ - **In-Flight Deduplication**: Simultaneous requests for the same resource (based on semantic key) are merged into a "Leader-Follower" model where only one handler runs.
51
+ - **Micro-TTL Caching**: Optional short-lived cache (5-20ms) to coalesce burst traffic that arrives slightly out of sync.
52
+ - **Semantic Hashing**: Intelligent request key generation based on Method + Route + Query + Body + Vary Headers.
53
+ - **Vary Header Support**: Automatic isolation of authenticated requests (Authorization, Cookie) to prevent cross-user data leaks.
54
+
55
+ ## [1.3.0] - 2026-01-20
56
+ **"The Documentation Update"**
57
+
58
+ ### Added
59
+ - **OpenAPI Generator**: New `app.getOpenAPI()` method automatically generates OpenAPI 3.0 specs from your routes and schemas.
60
+ - **Schema Mapping**: `SimpleValidator` schemas are automatically converted to Swagger-compatible JSON schemas.
61
+ - **Auto-Discovery**: Automatically infers path parameters (e.g., `/{id}`) and query parameters from your code.
62
+
63
+ ## [1.2.0] - 2026-01-20
64
+ **"The Guardrails Update"**
65
+
66
+ ### Added
67
+ - **Input Validation**: Built-in, zero-dependency `SimpleValidator` for Request Body, Query Parameters, and URL Params.
68
+ - **Automatic Coercion**: Query parameters (e.g., `?page=1`) are automatically converted to numbers/booleans if defined in the schema.
69
+ - **Type Safety**: Routes now reject invalid requests with `400 Bad Request` and detailed error messages before they reach your handler.
70
+ - **Extensible Validation**: Support for custom validators (e.g., Zod, Joi) via the `Validator` interface.
71
+ - **Route Schema**: New `schema` structure supporting `{ body, query, params, response }`.
72
+
73
+ ## [1.1.0] - 2026-01-20
74
+ **"The Database & Batch Engine Update"**
75
+
76
+ ### Added
77
+ - **Multi-Database Engine**: New `DatabaseManager` supporting multiple database backends with connection pooling.
78
+ - **Database Adapters**: Built-in, zero-dependency adapters for:
79
+ - **PostgreSQL**: High-performance pooling via `pg`.
80
+ - **MongoDB**: Native query and aggregation support via `mongodb`.
81
+ - **Memory**: In-memory database for testing and prototyping.
82
+ - **Smart Query Fusion**: `QueryCoalescer` automatically merges identical queries (e.g., `SELECT ... WHERE id = ?`) into single batched queries (e.g., `WHERE id IN (...)`) to reduce network roundtrips.
83
+ - **Batch Execution Engine**: New `BatchExecutor` allows clients to send multiple operations in a single HTTP request, automatically routed to fused database queries.
84
+ - **Dynamic Imports**: Database drivers (`pg`, `mongodb`) are now optional peer dependencies, keeping the core lightweight.
85
+ - **Flexible Registration**: Support for bringing your own pre-initialized database connections via `registerConnection()`.
86
+
87
+ ## [1.0.0] - 2026-01-19
88
+ **"The Enterprise Release"**
89
+
90
+ ### Added
91
+ - **Simplification**: Introduced `createHttpApp()` for instant, Express-like server setup.
92
+ - **WebSocket Support**: Full WebSocket upgrade handling via `app.websocket()` and `WebSocketManager`.
93
+ - **Cookie Management**: Native cookie parsing and serialization support (`ctx.cookies`, `ctx.setCookie`).
94
+ - **Body Parsing**: Integrated `BodyParser` for automatic JSON and URL-encoded body handling.
95
+ - **Developer Experience**: Enhanced logging with color-coded status and precise timing.
96
+
97
+ ### Changed
98
+ - **Architecture**: Complete codebase restructuring into modular domains (`core`, `router`, `middleware`, `utils`).
99
+ - **Refactoring**: Decoupled monolithic `server.ts` into specialized components.
100
+ - **Imports**: Optimized internal imports and fixed circular dependencies.
101
+
102
+ ### Fixed
103
+ - **Logging**: Fixed 200 OK logs appearing for 404/500 errors.
104
+ - **Timing**: Corrected request duration metrics (0ms bug).
105
+ - **Stability**: Resolved port conflicts and improved error propagation in async handlers.
106
+
107
+ ## [0.9.0] - 2025-12-20
108
+ **"The Performance Update"**
109
+
110
+ ### Added
111
+ - **Resource Management**: Added `BufferPool` for efficient memory reuse during high-load I/O.
112
+ - **Context Pooling**: Implemented zero-allocation `QHTTPXContext` reuse to reduce GC pressure.
113
+ - **Adaptive Scaling**: Added automatic worker calculation based on CPU cores (`calculateWorkerCount`).
114
+ - **Overload Protection**: Added `isResourceOverloaded` checks for memory/CPU thresholds.
115
+
116
+ ### Changed
117
+ - **Performance**: Optimized request pipeline to minimize closure allocations.
118
+
119
+ ## [0.8.0] - 2025-11-15
120
+ **"The Task Engine Update"**
121
+
122
+ ### Added
123
+ - **Background Tasks**: Introduced `TaskEngine` and `Scheduler` for async job processing.
124
+ - **API**: Added `app.task()` for registering job handlers and `app.enqueue()` for dispatching jobs.
125
+ - **Observability**: Added `/metrics` endpoint exposing task queue depths and worker status.
126
+
127
+ ## [0.5.0] - 2025-10-01
128
+ **"The Middleware Update"**
129
+
130
+ ### Added
131
+ - **Middleware Pipeline**: Implemented `app.use()` and the recursive middleware execution model.
132
+ - **Standard Middleware**: Added built-in middleware for:
133
+ - `cors`: Cross-Origin Resource Sharing support.
134
+ - `static`: Efficient static file serving.
135
+ - `security`: Helmet-like security headers.
136
+ - `logger`: Request/Response logging.
137
+
138
+ ## [0.1.0] - 2025-09-01
139
+ **"Genesis"**
140
+
141
+ ### Added
142
+ - **Core Server**: Initial HTTP server implementation using Node.js native `http` module.
143
+ - **Routing**: High-performance Radix Tree router (O(1) lookup) for dynamic and static routes.
144
+ - **Context API**: Unified `ctx` object wrapping `req` and `res` (inspired by Koa/Fastify).
145
+ - **JSON Support**: Basic `ctx.json()` helper.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Quantam Open Source
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,343 @@
1
+ <div align="center">
2
+ <img src="https://placehold.co/200x200?text=QHTTPX" alt="QHTTPX Logo" width="200" height="200" />
3
+ </div>
4
+
5
+ # QHTTPX
6
+
7
+ [![npm version](https://img.shields.io/npm/v/qhttpx.svg)](https://www.npmjs.com/package/qhttpx)
8
+ [![License](https://img.shields.io/npm/l/qhttpx.svg)](https://github.com/Quantam-Open-Source/qhttpx/blob/main/LICENSE)
9
+ [![Downloads](https://img.shields.io/npm/dm/qhttpx.svg)](https://www.npmjs.com/package/qhttpx)
10
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
11
+
12
+ **URL:** https://qhttpx.gridrr.com
13
+
14
+ QHTTPX is a high-performance, concurrency-native hybrid HTTP runtime for Node.js, designed to outperform traditional frameworks like Express and Fastify under real-world load, even on low-resource machines (1GB RAM and small CPUs).
15
+
16
+ It is built from the ground up for:
17
+ - Extreme concurrency
18
+ - Non-blocking execution
19
+ - Adaptive scaling
20
+ - Zero-waste resource usage
21
+ - Async-first, task-aware scheduling
22
+
23
+ QHTTPX is not just a web framework. It is a runtime engine for HTTP, background tasks, and streaming workloads sharing one unified scheduler.
24
+
25
+ ---
26
+
27
+ ## Vision
28
+
29
+ - One engine.
30
+ - Millions of concurrent connections.
31
+ - No blocking. No stalls. No wasted CPU.
32
+ - From 1GB VPS to multi-core servers — same code, linear scale.
33
+
34
+ ---
35
+
36
+ ## Key Features
37
+
38
+ ### 1. Concurrency-Native Core
39
+ - Cooperative async scheduler
40
+ - Backpressure-aware pipelines
41
+ - No blocking in hot paths
42
+ - Request, stream, and task execution share the same engine
43
+
44
+ ### 2. Hybrid Runtime
45
+ QHTTPX runs:
46
+ - HTTP requests
47
+ - Streaming responses
48
+ - Background jobs
49
+ - Long-running async workflows
50
+
51
+ All inside one unified concurrency model.
52
+
53
+ ### 3. Ultra-Fast Routing
54
+ - Radix tree based
55
+ - Zero regex
56
+ - O(1) static route resolution
57
+ - Minimal allocations per request
58
+
59
+ ### 4. Resource-Aware Scaling
60
+ - Auto worker scaling
61
+ - CPU pressure detection
62
+ - Memory pressure detection
63
+ - Adaptive queue limits
64
+ - Graceful overload handling (no crashes, no OOM)
65
+
66
+ ### 5. Zero-Overhead Pipeline
67
+ - Flattened async middleware
68
+ - No deep stacks
69
+ - No promise churn
70
+ - Context reuse and pooling
71
+
72
+ ### 7. Full-Stack Ready
73
+ - **Native Ecosystem**: Works with `jose` (JWT), `ioredis`, `Prisma`, `Drizzle`.
74
+ - **Advanced Static Files**: Streaming, Range Requests (Video), and Caching.
75
+ - **Real-Time**: Built-in SSE and WebSocket Rooms.
76
+ - **Multipart**: Native file upload support.
77
+
78
+ ---
79
+
80
+ ## Installation (Preview)
81
+
82
+ ```bash
83
+ npm install qhttpx
84
+ ```
85
+
86
+ ---
87
+
88
+ ## Basic Usage
89
+
90
+ ```ts
91
+ import { createHttpApp } from "qhttpx";
92
+
93
+ // Create an app (Express-style)
94
+ // Automatically includes: CORS, Security Headers, Logging, Body Parsing
95
+ const app = createHttpApp();
96
+
97
+ app.get("/", (ctx) => {
98
+ ctx.json({ message: "Hello from QHTTPX" });
99
+ });
100
+
101
+ // Cookie & Helper Support
102
+ app.get("/hello", (ctx) => {
103
+ ctx.setCookie("name", "QHTTPX");
104
+ ctx.html("<h1>Hello World</h1>");
105
+ });
106
+
107
+ app.listen(3000, "127.0.0.1").then(({ port }) => {
108
+ console.log(`Server running at http://localhost:${port}`);
109
+ });
110
+ ```
111
+
112
+ ## Features
113
+
114
+ ### 🍪 Built-in Cookie Support
115
+ RFC-compliant cookie parsing and serialization out of the box.
116
+
117
+ ```ts
118
+ app.get('/', (ctx) => {
119
+ const token = ctx.cookies['token'];
120
+ ctx.setCookie('visited', 'true', { httpOnly: true, maxAge: 3600 });
121
+ });
122
+ ```
123
+
124
+ ### 🛠️ DX Helpers
125
+ Built-in helpers for common tasks:
126
+ - `ctx.json(data, status)`
127
+ - `ctx.html(content, status)`
128
+ - `ctx.send(body, status)`
129
+ - `ctx.redirect(url, status)`
130
+
131
+ ## Advanced Usage
132
+
133
+ For full control over the runtime configuration:
134
+
135
+ ```ts
136
+ import { QHTTPX } from "qhttpx";
137
+
138
+ const app = new QHTTPX({
139
+ workers: "auto",
140
+ maxConcurrency: 1000,
141
+ requestTimeoutMs: 2_000,
142
+ maxMemoryBytes: 512 * 1024 * 1024,
143
+ });
144
+
145
+
146
+ ---
147
+
148
+ ## Core API
149
+
150
+ ### Server
151
+
152
+ ```ts
153
+ new QHTTPX(options);
154
+ ```
155
+
156
+ **Options**
157
+
158
+ | Option | Description |
159
+ | ----------------- | ------------------------------------------------ |
160
+ | `workers` | Number of workers or `"auto"` |
161
+ | `maxConcurrency` | Hard limit for in-flight scheduled tasks |
162
+ | `requestTimeoutMs`| Per-request timeout in milliseconds |
163
+ | `maxMemoryBytes` | RSS threshold for returning 503 overload |
164
+
165
+ ### Routing
166
+
167
+ ```ts
168
+ app.get(path, handler);
169
+ app.post(path, handler);
170
+ app.put(path, handler);
171
+ app.delete(path, handler);
172
+ ```
173
+
174
+ **Example**
175
+
176
+ ```ts
177
+ app.get("/users/:id", ctx => {
178
+ return ctx.json({ id: ctx.params.id });
179
+ });
180
+ ```
181
+
182
+ ---
183
+
184
+ ## Middleware
185
+
186
+ ```ts
187
+ app.use(async (ctx, next) => {
188
+ const start = Date.now();
189
+ await next();
190
+ const duration = Date.now() - start;
191
+ ctx.res.setHeader("x-response-time", `${duration}ms`);
192
+ });
193
+ ```
194
+
195
+ ### Built-in helpers
196
+
197
+ ```ts
198
+ import {
199
+ createCorsMiddleware,
200
+ createSecurityHeadersMiddleware,
201
+ createStaticMiddleware,
202
+ createLoggerMiddleware,
203
+ } from "qhttpx";
204
+
205
+ app.use(createCorsMiddleware());
206
+ app.use(createSecurityHeadersMiddleware());
207
+ app.use(
208
+ createStaticMiddleware({
209
+ root: "./public",
210
+ index: "index.html",
211
+ fallthrough: true,
212
+ }),
213
+ );
214
+ app.use(createLoggerMiddleware());
215
+ ```
216
+
217
+ These helpers provide:
218
+
219
+ - CORS headers and preflight handling
220
+ - Security headers (CSP, referrer policy, X-Frame-Options, etc.)
221
+ - Static file serving from a directory
222
+ - Structured request logging with pluggable sink
223
+
224
+ ---
225
+
226
+ ## Context
227
+
228
+ Each request receives a high-performance context:
229
+
230
+ - `ctx.req` – raw Node request
231
+ - `ctx.res` – raw Node response
232
+ - `ctx.body` – parsed body (JSON for application/json, otherwise Buffer)
233
+ - `ctx.query` – parsed query parameters
234
+ - `ctx.params` – route params from the path
235
+ - `ctx.json()` – fast JSON response helper
236
+ - `ctx.send()` – buffer / text response helper
237
+
238
+ ### Streaming helpers
239
+
240
+ QHTTPX also exposes helpers for streaming and Server-Sent Events:
241
+
242
+ ```ts
243
+ import { createSseStream, sendStream } from "qhttpx";
244
+
245
+ app.get("/events", (ctx) => {
246
+ const sse = createSseStream(ctx, { retryMs: 2000 });
247
+ sse.send({ message: "hello" });
248
+ sse.close();
249
+ });
250
+
251
+ app.get("/download", async (ctx) => {
252
+ const fileStream = fs.createReadStream("big-file.dat");
253
+ await sendStream(ctx, fileStream, {
254
+ contentType: "application/octet-stream",
255
+ status: 200,
256
+ });
257
+ });
258
+ ```
259
+
260
+ ---
261
+
262
+ ## Hybrid Task Engine (v0.2+)
263
+
264
+ ```ts
265
+ app.task("email-worker", async job => {
266
+ // background execution using same scheduler as HTTP
267
+ });
268
+ ```
269
+
270
+ The same scheduler that powers HTTP requests also powers background tasks and long-running async workflows.
271
+
272
+ ---
273
+
274
+ ## Built-in Observability
275
+
276
+ **Endpoints**
277
+ - `/__qhttpx/health`
278
+ - `/__qhttpx/metrics`
279
+
280
+ **Metrics include**
281
+ - Requests per second
282
+ - Active workers
283
+ - Event loop lag
284
+ - Memory usage
285
+ - Queue depth
286
+ - P50 / P95 / P99 latency
287
+
288
+ ---
289
+
290
+ ## Performance Goals
291
+
292
+ QHTTPX v1.0 targets:
293
+
294
+ | Metric | Goal |
295
+ | ------------- | ------------------------------------- |
296
+ | Throughput | Faster than Fastify by 15–30% |
297
+ | Latency | Lower P99 than Fastify |
298
+ | Memory | Lower per-connection footprint |
299
+ | Cold start | < 30ms |
300
+ | 1GB RAM | No OOM under 100k concurrent connections |
301
+
302
+ ---
303
+
304
+ ## Philosophy
305
+
306
+ - Fastify optimizes HTTP.
307
+ - Express simplifies developer experience.
308
+ - QHTTPX optimizes execution itself.
309
+
310
+ It treats HTTP as just one workload type inside a high-performance concurrency engine.
311
+
312
+ ---
313
+
314
+ ## Roadmap
315
+
316
+ ### v0.1.0
317
+ - Core runtime
318
+ - Scheduler
319
+ - Radix router
320
+ - HTTP/1.1
321
+ - Worker scaling
322
+ - Metrics
323
+ - Graceful shutdown
324
+
325
+ ### v0.5.0
326
+ - HTTP/2
327
+ - Zero-copy serializers
328
+ - C++ / WASM hot path
329
+ - Kernel socket tuning
330
+
331
+ ### v1.0.0
332
+ - Outperform Fastify in real benchmarks
333
+ - Hybrid task + HTTP engine
334
+ - Distributed mesh mode
335
+ - Quantam workflow native integration
336
+
337
+ ---
338
+
339
+ ## Positioning Statement
340
+
341
+ **QHTTPX**
342
+ A concurrency-native hybrid HTTP runtime built to extract maximum throughput from minimal hardware, designed to outperform Fastify and Express under extreme load while serving as the execution core for next-generation async systems.
343
+
@@ -0,0 +1,61 @@
1
+ {
2
+ "name": "qhttpx",
3
+ "version": "1.8.0",
4
+ "description": "**URL:** https://qhttpx.gridrr.com",
5
+ "main": "index.js",
6
+ "bin": {
7
+ "qhttpx": "./dist/src/cli/index.js"
8
+ },
9
+ "directories": {
10
+ "doc": "docs"
11
+ },
12
+ "scripts": {
13
+ "build": "tsc -p tsconfig.json",
14
+ "lint": "eslint src tests --ext .ts",
15
+ "test": "vitest run",
16
+ "example": "npx tsx examples/api-server.ts",
17
+ "bench": "npm run build && node dist/src/benchmarks/simple-json.js",
18
+ "bench:quantam": "npm run build && node dist/src/benchmarks/quantam-users.js",
19
+ "bench:compare": "npm run build && node dist/src/benchmarks/compare-frameworks.js",
20
+ "bench:ultra": "npm run build && node dist/src/benchmarks/ultra-mode.js"
21
+ },
22
+ "keywords": [],
23
+ "author": "",
24
+ "license": "ISC",
25
+ "type": "commonjs",
26
+ "devDependencies": {
27
+ "@types/autocannon": "^7.12.7",
28
+ "@types/better-sqlite3": "^7.6.13",
29
+ "@types/busboy": "^1.5.4",
30
+ "@types/express": "^5.0.6",
31
+ "@types/ioredis": "^4.28.10",
32
+ "@types/mongodb": "^4.0.6",
33
+ "@types/node": "^25.0.9",
34
+ "@types/pg": "^8.16.0",
35
+ "@types/ws": "^8.18.1",
36
+ "@typescript-eslint/eslint-plugin": "^8.53.0",
37
+ "@typescript-eslint/parser": "^8.53.0",
38
+ "autocannon": "^8.0.0",
39
+ "eslint": "^9.39.2",
40
+ "eslint-config-prettier": "^10.1.8",
41
+ "eslint-plugin-prettier": "^5.5.5",
42
+ "mongodb": "^7.0.0",
43
+ "pg": "^8.17.1",
44
+ "prettier": "^3.8.0",
45
+ "tsx": "^4.21.0",
46
+ "typescript": "^5.9.3",
47
+ "vitest": "^4.0.17"
48
+ },
49
+ "dependencies": {
50
+ "better-sqlite3": "^12.6.2",
51
+ "busboy": "^1.6.0",
52
+ "express": "^5.2.1",
53
+ "fast-json-stringify": "^5.15.1",
54
+ "fastify": "^5.7.1",
55
+ "pino": "^10.2.0",
56
+ "pino-pretty": "^13.1.3",
57
+ "quantam-async": "^0.1.1",
58
+ "ws": "^8.19.0",
59
+ "zod": "^4.3.5"
60
+ }
61
+ }