threadforge 0.1.0

package/LICENSE

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

@@ -0,0 +1,152 @@
+# ThreadForge
+
+A multi-threaded Node.js service runtime framework. Deploy multiple services on the same machine, intelligently distributed across available CPU cores, with built-in IPC messaging, metrics, and lifecycle management.
+
+## Why ThreadForge?
+
+Node.js runs on a single thread. Modern servers have 16, 32, 64+ cores. ThreadForge bridges that gap by giving you a declarative way to run multiple services across all available cores — with zero-overhead inter-service communication via IPC instead of HTTP.
+
+**Key features:**
+
+- **Declarative service config** — define services, ports, thread allocation, and topology in one file
+- **Smart thread allocation** — auto-distributes cores by weight, or set fixed counts
+- **3-tier IPC resolution** — colocated (direct call) → Unix Domain Socket → HTTP fallback
+- **Colocation groups** — pack lightweight services into a shared process for zero-overhead calls
+- **TC39 decorators** — `@Route`, `@Expose`, `@Emit`, `@On`, `@Validate` and more
+- **Plugin system** — Redis, PostgreSQL, S3, CORS, Cron, Realtime — with custom plugin support
+- **Auto-restart** — crashed workers are automatically replaced
+- **Runtime scaling** — scale services up/down without restarting
+- **RequestContext propagation** — correlation IDs, auth, deadlines, and baggage across services
+- **Built-in metrics** — Prometheus-compatible endpoint out of the box
+- **Multi-machine deployment** — grow from one machine to a full cluster with `forge.deploy.js`
+
+## Quick Start
+
+> **Note:** ThreadForge is not yet published to npm. See installation options below.
+
+### Option 1: Local Development (Recommended)
+
+```bash
+# Clone and link ThreadForge locally
+git clone https://github.com/ChrisBland/threadforge.git
+cd threadforge
+npm install
+npm link
+
+# Create your project
+mkdir my-app && cd my-app
+npm link threadforge
+forge init . --source local
+npm install
+
+# Start
+npm run dev
+```
+
+### Option 2: Install from GitHub
+
+```bash
+# Scaffold a new project
+npx github:ChrisBland/threadforge init my-app
+cd my-app
+npm install
+
+# Start in development mode (hot reload)
+npm run dev
+
+# Start in production mode
+npm run start
+```
+
+If `npx github:ChrisBland/threadforge ...` fails with npm cache permission errors (`EPERM` on `~/.npm/_cacache`), use a writable cache directory for the command:
+
+```bash
+NPM_CONFIG_CACHE=/tmp/threadforge-npm-cache npx github:ChrisBland/threadforge init my-app
+```
+
+Create `forge.config.js`:
+
+```javascript
+import { defineServices } from 'threadforge';
+
+export default defineServices({
+  api: {
+    entry: './services/api.js',
+    type: 'edge',
+    port: 3000,
+    threads: 'auto',
+    connects: ['users'],
+  },
+
+  users: {
+    entry: './services/users.js',
+    type: 'internal',
+  },
+});
+```
+
+Create `services/api.js`:
+
+```javascript
+import { Service } from 'threadforge';
+
+export default class ApiService extends Service {
+  static contract = {
+    routes: [
+      { method: 'GET', path: '/users/:id', handler: 'getUser' },
+    ],
+  };
+
+  async getUser(body, params) {
+    return await this.users.getUser(params.id);
+  }
+}
+```
+
+Create `services/users.js`:
+
+```javascript
+import { Service } from 'threadforge';
+
+export default class UsersService extends Service {
+  static contract = {
+    expose: ['getUser'],
+  };
+
+  async onStart(ctx) {
+    this.store = new Map([['1', { id: '1', name: 'Alice' }]]);
+  }
+
+  async getUser(id) {
+    return this.store.get(String(id));
+  }
+}
+```
+
+```bash
+forge start
+# curl http://localhost:3000/users/1
+# → { "id": "1", "name": "Alice" }
+```
+
+## Documentation
+
+Full documentation is in the [`docs/`](./docs/) directory:
+
+- [**Getting Started**](./docs/getting-started.md) — Install, create your first service, and run it
+- [**Architecture**](./docs/architecture.md) — Process model, communication layers, request lifecycle
+- **Guides:**
+  - [Services](./docs/guides/services.md) — Types, lifecycle, colocation, plain JS fallback
+  - [IPC & Communication](./docs/guides/ipc.md) — Proxy clients, events, interceptors
+  - [Plugins](./docs/guides/plugins.md) — Redis, PostgreSQL, S3, CORS, Cron, Realtime
+  - [Deployment](./docs/guides/deployment.md) — Single machine to multi-machine scaling
+- **Reference:**
+  - [Configuration](./docs/reference/configuration.md) — All `forge.config.js` options
+  - [Decorators](./docs/reference/decorators.md) — Full decorator API
+  - [CLI](./docs/reference/cli.md) — Commands, options, metrics endpoints
+  - [API](./docs/reference/api.md) — All public exports
+- [**ForgeProxy**](./docs/FORGEPROXY_ARCHITECTURE.js) — Rust gateway design and performance
+
+## License
+
+MIT