@canlooks/roost-electron-renderer 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C.CanLiang
+
+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,275 @@
+# @canlooks/roost-electron-renderer
+
+Electron renderer process plugin for the [Roost](https://github.com/canlooks/roost) micro-service framework. Provides seamless IPC-based remote procedure call (RPC) proxying — call main-process controller actions from the renderer as if they were local methods.
+
+## Overview
+
+In an Electron application, business logic typically runs in the main process via Roost controllers decorated with `@Controller` and `@Action`. This package creates transparent **proxy instances** of those controllers in the renderer process. Every `@Action`-decorated method on a proxy is replaced with an `ipcRenderer.invoke()` call, routing arguments through Electron's IPC channel to the main process and returning the result as a promise.
+
+The renderer code never touches IPC directly — it simply calls methods on controller instances.
+
+```
+┌─ Renderer Process ─────────────────────┐
+│                                         │
+│  const { myCtrl } =                     │
+│    await createRoostRenderer(           │
+│      { MyController },                  │
+│      { ipcRenderer }                    │
+│    )                                    │
+│                                         │
+│  // Looks like a local call...          │
+│  const result = await myCtrl.doWork(x)  │
+│                     │                   │
+└─────────────────────┼───────────────────┘
+                      │ ipcRenderer.invoke(channel, path, ...args)
+                      ▼
+┌─ Main Process ─────────────────────────┐
+│                                         │
+│  @Controller('api')                     │
+│  class MyController {                   │
+│    @Action('doWork')                    │
+│    doWork(x) { ... }                    │
+│  }                                      │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+npm install @canlooks/roost-electron-renderer
+```
+
+**Peer dependencies:**
+
+- [`@canlooks/roost`](https://www.npmjs.com/package/@canlooks/roost) — the core Roost framework
+- [`electron`](https://www.npmjs.com/package/electron) — provides `ipcRenderer`
+
+## API Reference
+
+### `createRoostRenderer(controllers, options)`
+
+Creates proxy controller instances whose `@Action` methods are wired to `ipcRenderer.invoke`.
+
+```typescript
+function createRoostRenderer<T extends Record<string, ComponentType>>(
+  controllers: T,
+  options: CreateRoostRendererOptions
+): Promise<{ [K in keyof T]: InstanceType<T[K]> }>
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `controllers` | `Record<string, ComponentType>` | Map of controller classes keyed by name. Each class must be decorated with `@Controller` from `@canlooks/roost`. |
+| `options` | `CreateRoostRendererOptions` | Configuration for the renderer proxy. |
+
+#### Returns
+
+An object with the same keys as the input `controllers` map, where each value is an **instance** of the corresponding controller class with its `@Action` methods rewritten to invoke IPC.
+
+#### `CreateRoostRendererOptions`
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `ipcRenderer` | `IpcRenderer` | Yes | — | The Electron `ipcRenderer` instance from the renderer process. |
+| `channel` | `string` | No | `'@canlooks/roost-electron'` | Custom IPC channel name. |
+
+### `rewriteActions(instances, options)`
+
+> **Internal.** Exported for advanced use cases. Rewrites `@Action` methods on controller instances to proxy through `ipcRenderer.invoke`.
+
+```typescript
+function rewriteActions(
+  instances: any[],
+  options: CreateRoostRendererOptions
+): void
+```
+
+## How It Works
+
+### Action Path Resolution
+
+Each `@Action`-decorated method is mapped to an IPC key derived from the controller and action paths:
+
+| Controller Decorator | Action Decorator | Resolved IPC Key |
+|----------------------|------------------|------------------|
+| `@Controller('api')` | `@Action('hello')` | `'/api/hello'` |
+| `@Controller('users')` | `@Action('list')` | `'/users/list'` |
+| `@Controller()` | `@Action('status')` | `'/status'` |
+
+The resolved key is passed as the second argument to `ipcRenderer.invoke(channel, key, ...args)`.
+
+### Method Rewriting
+
+- Only methods decorated with `@Action` are rewritten. Regular methods and properties are left untouched.
+- Rewriting happens **per-instance**, not on the prototype. The original class prototype remains intact.
+- Each call to a rewritten method results in a fresh `ipcRenderer.invoke()` call — no caching or batching.
+- All arguments passed to the method are forwarded as variadic arguments to `ipcRenderer.invoke`.
+- The return value of `ipcRenderer.invoke` (a `Promise`) is returned directly, preserving the original reference.
+
+### Error Propagation
+
+Errors thrown by the main process handler (or IPC errors) are propagated as rejected promises:
+
+```typescript
+const { ctrl } = await createRoostRenderer({ TestController }, { ipcRenderer })
+
+try {
+  await ctrl.hello('World')
+} catch (err) {
+  // err is the exact rejection from ipcRenderer.invoke
+}
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════
+// Shared controller definition (e.g., in a shared package)
+// ═══════════════════════════════════════════════════════════════════
+
+import { Controller, Action } from '@canlooks/roost'
+
+@Controller('api')
+export class ApiController {
+  @Action('greet')
+  greet(name: string): string {
+    return `Hello, ${name}!`
+  }
+
+  @Action('add')
+  add(a: number, b: number): number {
+    return a + b
+  }
+
+  // Regular methods are NOT proxied
+  getVersion(): string {
+    return '1.0.0'
+  }
+}
+```
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════
+// Main process — sets up IPC handler with Roost
+// ═══════════════════════════════════════════════════════════════════
+
+import { app, BrowserWindow, ipcMain } from 'electron'
+import { Roost } from '@canlooks/roost'
+
+app.whenReady().then(async () => {
+  const roost = await Roost.create({
+    named: { ApiController }
+  })
+
+  // Handle incoming IPC calls
+  ipcMain.handle('@canlooks/roost-electron', async (_event, path, ...args) => {
+    const results = await roost.invoke(path, ...args)
+    return results[0] // Return the first result for single-action calls
+  })
+
+  // ... create BrowserWindow, load renderer
+})
+```
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════
+// Renderer process — creates proxy and calls methods transparently
+// ═══════════════════════════════════════════════════════════════════
+
+import { createRoostRenderer } from '@canlooks/roost-electron-renderer'
+import { ipcRenderer } from 'electron'
+
+async function main() {
+  const { ApiController: api } = await createRoostRenderer(
+    { ApiController },
+    { ipcRenderer }
+  )
+
+  // These look like local calls but go through IPC to the main process:
+  const greeting = await api.greet('World')  // → "Hello, World!"
+  const sum = await api.add(3, 4)            // → 7
+
+  // Non-action methods are NOT proxied — they run locally:
+  const version = api.getVersion()            // → "1.0.0" (local call)
+}
+```
+
+### Multiple Controllers
+
+```typescript
+const { UserController, OrderController } = await createRoostRenderer(
+  { UserController, OrderController },
+  { ipcRenderer }
+)
+
+// Each controller's @Action methods are independently proxied
+const users = await UserController.list()
+const order = await OrderController.findById(42)
+```
+
+### Custom IPC Channel
+
+```typescript
+const { ApiController: api } = await createRoostRenderer(
+  { ApiController },
+  {
+    ipcRenderer,
+    channel: 'my-custom-channel' // Must match main process ipcMain.handle()
+  }
+)
+```
+
+### Controllers Without Actions
+
+Controllers with no `@Action` methods are handled gracefully — the instance is returned as-is with no method rewriting:
+
+```typescript
+@Controller('config')
+class ConfigController {
+  theme = 'dark'
+  setTheme(t: string) { this.theme = t }
+}
+
+const { ConfigController: config } = await createRoostRenderer(
+  { ConfigController },
+  { ipcRenderer }
+)
+
+console.log(config.theme) // 'dark' — normal property access
+```
+
+## TypeScript Support
+
+The package is written in TypeScript and ships with full type declarations. The return type of `createRoostRenderer` is **fully inferred** from the input controller map — each property is correctly typed as an instance of the corresponding class.
+
+```typescript
+const renderers = await createRoostRenderer(
+  { ApiController, UserController },
+  { ipcRenderer }
+)
+
+// TypeScript knows these types:
+renderers.ApiController.greet(name: string): Promise<string>
+renderers.UserController.list(): Promise<string[]>
+```
+
+The `ComponentType` constraint ensures only class constructors (not plain objects or primitives) can be passed as controllers.
+
+## Main Process Integration
+
+This package handles the **renderer side** of the IPC bridge. The main process must:
+
+1. Create a Roost app with the same controllers.
+2. Register an `ipcMain.handle()` listener on the same channel.
+3. Call `roost.invoke(path, ...args)` and return the result.
+
+See the [Roost framework documentation](https://github.com/canlooks/roost) for details on main-process setup, including the `@canlooks/roost-electron` package which provides main-process IPC handling out of the box.
+
+## License
+
+MIT © [C.CanLiang](https://github.com/canlooks)

package/dist/cjs/createRenderer.d.ts

@@ -0,0 +1,7 @@
+import type { IpcRenderer } from 'electron';
+import { ComponentType } from '@canlooks/roost';
+export type CreateRoostRendererOptions = {
+    channel?: string;
+    ipcRenderer: IpcRenderer;
+};
+export declare function createRoostRenderer<T extends Record<string, ComponentType>>(controllers: T, options: CreateRoostRendererOptions): Promise<{ [K in keyof T]: InstanceType<T[K]>; }>;

package/dist/cjs/createRenderer.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRoostRenderer = createRoostRenderer;
+const roost_1 = require("@canlooks/roost");
+const rewriteAction_1 = require("./rewriteAction");
+async function createRoostRenderer(controllers, options) {
+    const renderers = {};
+    const app = await roost_1.Roost.create({
+        named: controllers,
+        readOnly: true
+    });
+    const instances = await Promise.all(Object.keys(controllers).map(async (name) => {
+        return renderers[name] = await app.container.get(name);
+    }));
+    (0, rewriteAction_1.rewriteActions)(instances, options);
+    return renderers;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1 @@
+export * from './createRenderer';

package/dist/cjs/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./createRenderer"), exports);

package/dist/cjs/rewriteAction.d.ts

@@ -0,0 +1,2 @@
+import { CreateRoostRendererOptions } from './createRenderer';
+export declare function rewriteActions(instances: any[], options: CreateRoostRendererOptions): void;

package/dist/cjs/rewriteAction.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rewriteActions = rewriteActions;
+const roost_1 = require("@canlooks/roost");
+function rewriteActions(instances, options) {
+    instances.forEach(instance => {
+        const completeKeyMap = (0, roost_1.getActionsKey)(instance);
+        if (completeKeyMap) {
+            for (const [property, { path, pattern }] of completeKeyMap) {
+                const key = path || pattern;
+                if (key) {
+                    instance[property] = (...args) => {
+                        return options.ipcRenderer.invoke(options.channel || '@canlooks/roost-electron', key, ...args);
+                    };
+                }
+            }
+        }
+    });
+}

package/dist/esm/createRenderer.d.ts

@@ -0,0 +1,7 @@
+import type { IpcRenderer } from 'electron';
+import { ComponentType } from '@canlooks/roost';
+export type CreateRoostRendererOptions = {
+    channel?: string;
+    ipcRenderer: IpcRenderer;
+};
+export declare function createRoostRenderer<T extends Record<string, ComponentType>>(controllers: T, options: CreateRoostRendererOptions): Promise<{ [K in keyof T]: InstanceType<T[K]>; }>;

package/dist/esm/createRenderer.js

@@ -0,0 +1,14 @@
+import { Roost } from '@canlooks/roost';
+import { rewriteActions } from './rewriteAction.js';
+export async function createRoostRenderer(controllers, options) {
+    const renderers = {};
+    const app = await Roost.create({
+        named: controllers,
+        readOnly: true
+    });
+    const instances = await Promise.all(Object.keys(controllers).map(async (name) => {
+        return renderers[name] = await app.container.get(name);
+    }));
+    rewriteActions(instances, options);
+    return renderers;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1 @@
+export * from './createRenderer.js';

package/dist/esm/index.js

@@ -0,0 +1 @@
+export * from './createRenderer.js';

package/dist/esm/rewriteAction.d.ts

@@ -0,0 +1,2 @@
+import { CreateRoostRendererOptions } from './createRenderer.js';
+export declare function rewriteActions(instances: any[], options: CreateRoostRendererOptions): void;

package/dist/esm/rewriteAction.js

@@ -0,0 +1,16 @@
+import { getActionsKey } from '@canlooks/roost';
+export function rewriteActions(instances, options) {
+    instances.forEach(instance => {
+        const completeKeyMap = getActionsKey(instance);
+        if (completeKeyMap) {
+            for (const [property, { path, pattern }] of completeKeyMap) {
+                const key = path || pattern;
+                if (key) {
+                    instance[property] = (...args) => {
+                        return options.ipcRenderer.invoke(options.channel || '@canlooks/roost-electron', key, ...args);
+                    };
+                }
+            }
+        }
+    });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@canlooks/roost-electron-renderer",
+  "version": "0.0.1",
+  "author": "C.CanLiang <canlooks@gmail.com>",
+  "description": "A backend micro service framework",
+  "keywords": [
+    "micro service"
+  ],
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/canlooks/roost"
+  },
+  "homepage": "https://github.com/canlooks/roost",
+  "bugs": {
+    "url": "https://github.com/canlooks/roost/issues",
+    "email": "canlooks@gmail.com"
+  },
+  "license": "MIT",
+  "scripts": {
+    "clean": "npx shx rm -rf dist",
+    "build": "tsc -m esnext --outDir dist/esm & tsc -m commonjs --outDir dist/cjs",
+    "build:alias": "tsc-alias --outDir dist/esm",
+    "rebuild": "npm run clean && npm run build && npm run build:alias",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@canlooks/roost": "^0.0.1",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "electron": "^42.3.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.7"
+  }
+}