@canlooks/roost-electron 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,224 @@
+# @canlooks/roost-electron
+
+Electron main process plugin for the [Roost](https://github.com/canlooks/roost) microservice framework. Bridges Electron's IPC (Inter-Process Communication) from renderer processes directly to Roost service controllers running in the main process.
+
+## Overview
+
+`@canlooks/roost-electron` is a lightweight plugin that registers an [`ipcMain.handle()`](https://www.electronjs.org/docs/latest/api/ipc-main#ipcmainhandlechannel-listener) listener on a configurable channel. When a renderer process sends an IPC invoke call, the plugin forwards the invocation key and arguments to `app.invoke()`, routing the request to the matching Roost controller action.
+
+Paired with [`@canlooks/roost-electron-renderer`](https://www.npmjs.com/package/@canlooks/roost-electron-renderer) on the renderer side, this enables seamless RPC-style communication where renderer-side controller method calls are transparently proxied via Electron IPC to the main process.
+
+## Installation
+
+```bash
+npm install @canlooks/roost-electron
+```
+
+**Peer dependencies:**
+- `@canlooks/roost` (core framework)
+- `electron` (main process runtime)
+
+## Quick Start
+
+### Main Process
+
+```typescript
+import { app, BrowserWindow } from 'electron'
+import Roost from '@canlooks/roost'
+import { ElectronMainPlugin } from '@canlooks/roost-electron'
+import { MyService } from './services/MyService'
+
+async function main() {
+    const roost = await Roost.create({
+        named: { MyService },
+        plugins: [
+            ElectronMainPlugin()
+        ]
+    })
+
+    const win = new BrowserWindow({
+        webPreferences: {
+            preload: path.join(__dirname, 'preload.js')
+        }
+    })
+    win.loadFile('index.html')
+}
+
+app.whenReady().then(main)
+```
+
+### Renderer Process (with `@canlooks/roost-electron-renderer`)
+
+```typescript
+import { contextBridge, ipcRenderer } from 'electron'
+import { createRoostRenderer } from '@canlooks/roost-electron-renderer'
+import { MyService } from '../services/MyService'
+
+contextBridge.exposeInMainWorld('roost', {
+    services: await createRoostRenderer(
+        { MyService },
+        { ipcRenderer }
+    )
+})
+```
+
+Then, in the renderer page:
+
+```typescript
+// MyService methods are transparently proxied to the main process
+const result = await window.roost.services.MyService.doSomething(args)
+```
+
+## API Reference
+
+### `ElectronMainPlugin(options?)`
+
+Factory function that creates a Roost `Plugin` object for the Electron main process.
+
+```typescript
+function ElectronMainPlugin(options?: ElectronMainPluginOptions): Plugin
+```
+
+#### `ElectronMainPluginOptions`
+
+| Property  | Type     | Default                       | Description                                                |
+| --------- | -------- | ----------------------------- | ---------------------------------------------------------- |
+| `channel` | `string` | `"@canlooks/roost-electron"` | The IPC channel name used for `ipcMain.handle()`. Customize this to avoid conflicts with other IPC handlers. |
+
+#### Return Value
+
+Returns a `Plugin` object conforming to the Roost `Plugin` interface:
+
+```typescript
+{
+    name: 'electron-main',
+    onStaticInjected: (app: Roost) => void
+}
+```
+
+### `registerIpcMain(app, options?)`
+
+Low-level function called internally by the plugin. Registers the `ipcMain.handle()` listener directly.
+
+```typescript
+function registerIpcMain(app: Roost, options?: ElectronMainPluginOptions): void
+```
+
+> This is exported for advanced use cases where you need to control registration timing manually. In most cases, use `ElectronMainPlugin()` instead.
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Renderer Process                                       │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │  createRoostRenderer({ MyService }, { ipcRenderer })│  │
+│  │  → Rewrites MyService methods to call              │  │
+│  │    ipcRenderer.invoke(channel, key, ...args)       │  │
+│  └───────────────────────┬───────────────────────────┘  │
+└──────────────────────────┼──────────────────────────────┘
+                           │ Electron IPC
+┌──────────────────────────┼──────────────────────────────┐
+│  Main Process            │                              │
+│  ┌───────────────────────▼───────────────────────────┐  │
+│  │  ElectronMainPlugin                                │  │
+│  │  → ipcMain.handle(channel, (e, key, ...args) => {  │  │
+│  │      return app.invoke(key, ...args)               │  │
+│  │    })                                              │  │
+│  └───────────────────────┬───────────────────────────┘  │
+│                          │                              │
+│  ┌───────────────────────▼───────────────────────────┐  │
+│  │  Roost App                                         │  │
+│  │  → app.invoke(key, ...args)                        │  │
+│  │  → Route to matching @Controller/@Action           │  │
+│  │  → Execute, return result                          │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Lifecycle
+
+The plugin hooks into the `onStaticInjected` lifecycle event of Roost:
+
+1. **`Roost.create()`** is called with the plugin in the `plugins` array.
+2. Roost registers all modules and performs dependency injection.
+3. **`onStaticInjected`** fires — the plugin registers `ipcMain.handle()` on the configured channel.
+4. The main process is now ready to receive IPC calls from renderer processes.
+
+### Invocation Flow
+
+When a renderer calls `window.roost.services.MyService.doSomething(arg)`:
+
+1. `@canlooks/roost-electron-renderer` rewrites the method to call `ipcRenderer.invoke('@canlooks/roost-electron', 'path/to/action', arg)`.
+2. The IPC message arrives in the main process.
+3. The `ipcMain.handle()` listener receives `(event, key, arg)`.
+4. It calls `app.invoke(key, arg)` on the Roost instance.
+5. Roost's `Invoker` matches the key against registered controllers and actions (path-based, pattern-based, or regex-based routing).
+6. The matched controller method executes and returns a result.
+7. The result is sent back through the IPC channel to the renderer.
+
+## Custom Channel
+
+If the default channel name conflicts with other IPC handlers in your application, provide a custom channel:
+
+```typescript
+ElectronMainPlugin({ channel: 'my-app:rpc' })
+```
+
+Make sure to use the same channel name in the renderer side:
+
+```typescript
+createRoostRenderer(
+    { MyService },
+    { ipcRenderer, channel: 'my-app:rpc' }
+)
+```
+
+## Project Structure
+
+```
+packages/electron/
+├── src/
+│   ├── index.ts              # Plugin factory + type exports
+│   └── registerIpcMain.ts    # IPC handler registration
+├── dist/
+│   ├── cjs/                  # CommonJS build output
+│   └── esm/                  # ES Module build output
+├── test/
+├── package.json
+├── tsconfig.json
+├── LICENSE
+└── README.md
+```
+
+## TypeScript
+
+The package is written in TypeScript and ships with declaration files. TypeScript 6.0+ and `strict` mode are used during development.
+
+### Exports
+
+```typescript
+// Factory function
+export function ElectronMainPlugin(options?: ElectronMainPluginOptions): Plugin
+
+// Options type
+export type ElectronMainPluginOptions = {
+    channel?: string
+}
+
+// Low-level registration function
+export function registerIpcMain(app: Roost, options?: ElectronMainPluginOptions): void
+```
+
+## Related Packages
+
+| Package | Description |
+| ------- | ----------- |
+| [`@canlooks/roost`](https://www.npmjs.com/package/@canlooks/roost) | Core microservice framework |
+| [`@canlooks/roost-electron-renderer`](https://www.npmjs.com/package/@canlooks/roost-electron-renderer) | Renderer-side companion — creates proxy controllers that communicate via IPC |
+
+## License
+
+MIT © [C.CanLiang](https://github.com/canlooks)

package/dist/cjs/index.d.ts

@@ -0,0 +1,5 @@
+import { Plugin } from '@canlooks/roost';
+export type ElectronMainPluginOptions = {
+    channel?: string;
+};
+export declare function ElectronMainPlugin(options?: ElectronMainPluginOptions): Plugin;

package/dist/cjs/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElectronMainPlugin = ElectronMainPlugin;
+const registerIpcMain_1 = require("./registerIpcMain");
+function ElectronMainPlugin(options) {
+    return {
+        name: 'electron-main',
+        onStaticInjected: app => (0, registerIpcMain_1.registerIpcMain)(app, options)
+    };
+}

package/dist/cjs/registerIpcMain.d.ts

@@ -0,0 +1,3 @@
+import { ElectronMainPluginOptions } from './index';
+import Roost from '@canlooks/roost';
+export declare function registerIpcMain(app: Roost, options?: ElectronMainPluginOptions): void;

package/dist/cjs/registerIpcMain.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerIpcMain = registerIpcMain;
+const electron_1 = require("electron");
+function registerIpcMain(app, options) {
+    const channel = options?.channel || '@canlooks/roost-electron';
+    electron_1.ipcMain.handle(channel, (e, key, ...args) => {
+        return app.invoke(key, ...args);
+    });
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+import { Plugin } from '@canlooks/roost';
+export type ElectronMainPluginOptions = {
+    channel?: string;
+};
+export declare function ElectronMainPlugin(options?: ElectronMainPluginOptions): Plugin;

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { registerIpcMain } from './registerIpcMain.js';
+export function ElectronMainPlugin(options) {
+    return {
+        name: 'electron-main',
+        onStaticInjected: app => registerIpcMain(app, options)
+    };
+}

package/dist/esm/registerIpcMain.d.ts

@@ -0,0 +1,3 @@
+import { ElectronMainPluginOptions } from './index.js';
+import Roost from '@canlooks/roost';
+export declare function registerIpcMain(app: Roost, options?: ElectronMainPluginOptions): void;

package/dist/esm/registerIpcMain.js

@@ -0,0 +1,7 @@
+import { ipcMain } from 'electron';
+export function registerIpcMain(app, options) {
+    const channel = options?.channel || '@canlooks/roost-electron';
+    ipcMain.handle(channel, (e, key, ...args) => {
+        return app.invoke(key, ...args);
+    });
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@canlooks/roost-electron",
+  "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"
+  },
+  "dependencies": {
+    "@canlooks/roost": "^0.0.1",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.1",
+    "electron": "^42.3.0",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3"
+  }
+}