threadforge 0.1.0 → 0.2.1

package/dist/services/Service.d.ts

@@ -0,0 +1,164 @@
+import type { ForgeContext } from "../core/ForgeContext.js";
+/**
+ * Service Base Class v2
+ *
+ * Developers extend this to create ThreadForge services.
+ *
+ * NEW in v2:
+ *   - Auto-generated proxy clients for other services
+ *     (this.users.getUser(id) instead of this.request('users', {...}))
+ *   - @Expose, @Route, @Emit, @On decorators for contracts
+ *   - Plain JS fallback via static `contract` property
+ *   - Automatic HTTP route registration from @Route
+ *   - Automatic event subscription wiring from @On
+ *
+ * @example
+ * ```js
+ * import { Service, Expose, Route, Emit } from 'threadforge';
+ *
+ * export default class UserService extends Service {
+ *
+ *   @Expose()
+ *   async getUser(userId) {
+ *     return this.db.findUser(userId);
+ *   }
+ *
+ *   @Expose()
+ *   @Route('POST', '/users')
+ *   @Emit('user.created')
+ *   async createUser(data) {
+ *     const user = await this.db.insert(data);
+ *     await this.notifications.userCreated(user);  // auto-generated proxy
+ *     return user;
+ *   }
+ * }
+ * ```
+ *
+ * Plain JS equivalent (no decorators):
+ * ```js
+ * export default class UserService extends Service {
+ *   static contract = {
+ *     expose: ['getUser', 'createUser'],
+ *     routes: [
+ *       { method: 'POST', path: '/users', handler: 'createUser' },
+ *     ],
+ *     emits: { createUser: 'user.created' },
+ *   };
+ *
+ *   async getUser(userId) { ... }
+ *   async createUser(data) { ... }
+ * }
+ * ```
+ *
+ * **Route handler signatures — two approaches:**
+ *
+ * 1. Contract routes (`@Route` / `static contract.routes`):
+ *    Handler receives `(body, params, query)` and returns a value that is
+ *    auto-serialized as JSON (201 for POST, 200 otherwise).
+ *
+ *    **IMPORTANT: GET handler signature**
+ *    GET handlers receive the same `(body, params, query)` signature as all
+ *    other methods. Since GET requests have no request body, the first
+ *    argument is always an empty object `{}`. Use destructuring to skip it:
+ *
+ *    ```js
+ *    // Recommended — destructure to ignore the empty body:
+ *    @Route('GET', '/users/:id')
+ *    async getUser(_body, params, query) {
+ *      // _body is always {} for GET requests
+ *      return this.db.findUser(params.id);
+ *    }
+ *
+ *    // Also works — use positional args:
+ *    @Route('GET', '/search')
+ *    async search(_, _params, query) {
+ *      return this.db.search(query.q);
+ *    }
+ *    ```
+ *
+ *    The same applies to plain JS contracts:
+ *    ```js
+ *    static contract = {
+ *      routes: [{ method: 'GET', path: '/users/:id', handler: 'getUser' }],
+ *    };
+ *    async getUser(_body, params) {
+ *      return this.db.findUser(params.id);
+ *    }
+ *    ```
+ *
+ * 2. Manual routes (registered in `onStart` via `ctx.router`):
+ *    Handler receives the raw `(req, res)` and must call `res.json()` or
+ *    `res.end()` itself. These follow Node.js HTTP conventions and do not
+ *    have the empty body argument.
+ *
+ * See `autoRegisterRoutes` in `ServiceProxy.js` for full details.
+ */
+interface ProxyPayload {
+    __forge_method?: string;
+    __forge_args?: unknown[];
+    [key: string]: unknown;
+}
+export declare class Service {
+    ctx: ForgeContext | null;
+    /**
+     * Auto-generated proxy clients for connected services.
+     * Populated by the framework during initialization.
+     *
+     * Usage: this.users.getUser('123')
+     *        this.notifications.sendAlert({ ... })
+     */
+    [key: string]: unknown;
+    constructor();
+    /**
+     * Called when the service starts. Initialize resources here.
+     * Routes from @Route decorators are auto-registered BEFORE this is called,
+     * so you can add additional routes in onStart if needed.
+     */
+    onStart(_ctx: ForgeContext | null): Promise<void>;
+    /**
+     * Called when a message arrives from another service.
+     * For proxy-style calls, this is handled automatically.
+     * Override for custom fire-and-forget message handling.
+     */
+    onMessage(_from: string, _payload: unknown): Promise<void>;
+    /**
+     * Called when a request arrives from another service.
+     *
+     * For proxy-style calls (@Expose methods), this is dispatched
+     * automatically — you don't need to implement a switch/case.
+     *
+     * Override only for custom non-proxy request handling.
+     */
+    onRequest(from: string, payload: ProxyPayload): Promise<unknown>;
+    /**
+     * Called when the service is shutting down.
+     */
+    onStop(): Promise<void>;
+    /**
+     * Send a fire-and-forget message to another service.
+     * Prefer using proxy clients (this.serviceName.method()) for
+     * request/response patterns.
+     */
+    send(target: string, payload: unknown): Promise<void>;
+    /**
+     * Send a request to another service.
+     * Prefer using proxy clients instead of this low-level API.
+     */
+    request(target: string, payload: unknown, timeoutMs?: number): Promise<unknown>;
+    /** Broadcast to all workers of a target service. */
+    broadcast(target: string, payload: unknown): Promise<void>;
+    /** @internal */
+    _init(ctx: ForgeContext): Promise<void>;
+    /**
+     * @internal
+     * Set proxy clients on the service instance.
+     * Called by the worker bootstrap after all services are loaded.
+     */
+    _setProxies(proxies: Record<string, unknown>): void;
+    /** @internal */
+    _start(): Promise<void>;
+    /** @internal */
+    _stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=Service.d.ts.map

package/dist/services/Service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Service.d.ts","sourceRoot":"","sources":["../../src/services/Service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAQ5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAEH,UAAU,YAAY;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,OAAO;IAClB,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IAEzB;;;;;;OAMG;IAGH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;;IAQvB;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvD;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhE;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAStE;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;;;OAIG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrF,oDAAoD;IAC9C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhE,gBAAgB;IACV,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB7C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMnD,gBAAgB;IACV,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,gBAAgB;IACV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/services/Service.js

@@ -0,0 +1,106 @@
+import { autoRegisterRoutes, autoWireSubscriptions, handleProxyRequest, NOT_HANDLED, } from "../decorators/ServiceProxy.js";
+export class Service {
+    ctx;
+    constructor() {
+        this.ctx = null;
+    }
+    // ── Lifecycle hooks (override in subclass) ──
+    /**
+     * Called when the service starts. Initialize resources here.
+     * Routes from @Route decorators are auto-registered BEFORE this is called,
+     * so you can add additional routes in onStart if needed.
+     */
+    async onStart(_ctx) { }
+    /**
+     * Called when a message arrives from another service.
+     * For proxy-style calls, this is handled automatically.
+     * Override for custom fire-and-forget message handling.
+     */
+    async onMessage(_from, _payload) { }
+    /**
+     * Called when a request arrives from another service.
+     *
+     * For proxy-style calls (@Expose methods), this is dispatched
+     * automatically — you don't need to implement a switch/case.
+     *
+     * Override only for custom non-proxy request handling.
+     */
+    async onRequest(from, payload) {
+        // Try proxy-style dispatch first
+        const result = handleProxyRequest(this, from, payload);
+        if (result !== NOT_HANDLED)
+            return result;
+        // Subclass can handle other request formats
+        return null;
+    }
+    /**
+     * Called when the service is shutting down.
+     */
+    async onStop() { }
+    // ── Convenience methods ──
+    /**
+     * Send a fire-and-forget message to another service.
+     * Prefer using proxy clients (this.serviceName.method()) for
+     * request/response patterns.
+     */
+    async send(target, payload) {
+        if (!this.ctx)
+            throw new Error("Service not initialized");
+        return this.ctx.send(target, payload);
+    }
+    /**
+     * Send a request to another service.
+     * Prefer using proxy clients instead of this low-level API.
+     */
+    async request(target, payload, timeoutMs) {
+        if (!this.ctx)
+            throw new Error("Service not initialized");
+        return this.ctx.request(target, payload, timeoutMs);
+    }
+    /** Broadcast to all workers of a target service. */
+    async broadcast(target, payload) {
+        if (!this.ctx)
+            throw new Error("Service not initialized");
+        return this.ctx.broadcast(target, payload);
+    }
+    // ── Internal lifecycle (called by worker bootstrap) ──
+    /** @internal */
+    async _init(ctx) {
+        this.ctx = ctx;
+        // Wire IPC handlers
+        ctx._onMessage = (from, payload) => this.onMessage(from, payload);
+        ctx._onRequest = (from, payload) => this.onRequest(from, payload);
+        ctx._wireMessageHandlers();
+        // Auto-register HTTP routes from @Route decorators
+        autoRegisterRoutes(this, ctx);
+        // Auto-wire event subscriptions from @On decorators
+        autoWireSubscriptions(this, ctx);
+    }
+    /**
+     * @internal
+     * Set proxy clients on the service instance.
+     * Called by the worker bootstrap after all services are loaded.
+     */
+    _setProxies(proxies) {
+        for (const [name, proxy] of Object.entries(proxies)) {
+            this[name] = proxy;
+        }
+    }
+    /** @internal */
+    async _start() {
+        await this.onStart(this.ctx);
+        if (this.ctx?._needsHttpServer) {
+            await this.ctx.startServer();
+        }
+    }
+    /** @internal */
+    async _stop() {
+        try {
+            await this.onStop();
+        }
+        finally {
+            await this.ctx.stop();
+        }
+    }
+}
+//# sourceMappingURL=Service.js.map

package/dist/services/Service.js.map

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

package/dist/services/worker-bootstrap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Worker Bootstrap v3
+ *
+ * Loads services, builds proxy clients, and injects them.
+ *
+ * After bootstrap, a service can call:
+ *   await this.users.getUser('123')
+ *
+ * Which transparently routes through:
+ *   - Direct function call (colocated services, same process)
+ *   - UDS (different process, same machine)
+ *   - Supervisor IPC fallback (startup race)
+ */
+export {};
+//# sourceMappingURL=worker-bootstrap.d.ts.map

package/dist/services/worker-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-bootstrap.d.ts","sourceRoot":"","sources":["../../src/services/worker-bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}