@oldzy/conduit-electron-adapter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Conduit
+
+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,151 @@
+# Conduit Electron Adapter
+
+Electron IPC adapter for [@oldzy/conduit](https://github.com/oldzy/conduit), enabling seamless communication between Electron's main and renderer processes.
+
+## Features
+
+- 🔌 IPC-based communication between main and renderer processes
+- 🎯 Request/Response pattern with UUID tracking
+- 📡 Support for streaming responses
+- 🚫 Request cancellation support
+- 💉 Automatic dependency injection for Electron App and IpcMain
+- 🔄 AbortController integration for async operations
+
+## Installation
+
+```bash
+npm install @oldzy/conduit-electron-adapter
+```
+
+## Usage
+
+### Main Process
+
+```typescript
+import { Application } from '@oldzy/conduit';
+import { ElectronAdapter } from '@oldzy/conduit-electron-adapter';
+
+const app = new Application();
+const electronAdapter = new ElectronAdapter();
+
+app.useAdapter(electronAdapter);
+
+// Register your handlers...
+await app.build();
+```
+
+### Preload Script
+
+Configure your Electron window to use the preload script:
+
+```typescript
+import { BrowserWindow } from 'electron';
+import path from 'path';
+
+// Use require.resolve to get the preload path from node_modules
+const preloadPath = require.resolve('@oldzy/conduit-electron-adapter/preload');
+
+const mainWindow = new BrowserWindow({
+  webPreferences: {
+    preload: preloadPath,
+    contextIsolation: true,
+    nodeIntegration: false
+  }
+});
+```
+
+The preload script automatically:
+- Exposes `electronService` to the renderer via `contextBridge`
+- Handles all IPC listeners for streaming, errors, and cancellation
+- Manages request timeout (30 seconds)
+- Cleans up listeners automatically
+
+### Renderer Process
+
+```typescript
+// TypeScript: add types to window
+declare global {
+  interface Window {
+    electronService: IElectronService;
+  }
+}
+
+// Simple request/response
+const response = await window.electronService.send({
+  uuid: crypto.randomUUID(),
+  // ... your request data
+});
+
+// Streaming request with callback
+await window.electronService.send(
+  {
+    uuid: crypto.randomUUID(),
+    // ... your request data
+  },
+  (chunk) => {
+    console.log('Received chunk:', chunk);
+  }
+);
+
+// Cancel a request
+await window.electronService.cancel('request-uuid');
+```
+
+## API
+
+### ElectronAdapter (Main Process)
+
+The adapter automatically:
+- Registers `conduit:send` IPC handler for sending requests
+- Registers `conduit:cancel` IPC handler for cancelling requests
+- Injects `ElectronApp` (app instance) and `IpcMain` into the service container
+- Manages streaming responses via IPC events
+- Handles request cancellation with AbortController
+
+### IElectronService (Renderer Process)
+
+```typescript
+interface IElectronService {
+  send: (
+    request: BaseRequest,
+    onData?: (response: BaseResponse) => void
+  ) => Promise<BaseResponse | void>;
+  cancel: (requestUuid: string) => Promise<void>;
+}
+```
+
+#### Methods
+
+- **`send(request, onData?)`** - Send a request to the main process
+  - Returns the response for simple requests
+  - Calls `onData` callback for each chunk in streaming responses
+  - Resolves when streaming is complete
+  - Automatically handles timeout (30s) and cleanup
+  
+- **`cancel(requestUuid)`** - Cancel a pending request by UUID
+
+### IPC Channels
+
+Internal channels (handled automatically by the preload script):
+- `conduit:send` - Send a request (invoke)
+- `conduit:cancel` - Cancel a pending request (invoke)
+- `conduit:response:data:{uuid}` - Streaming response data (listener)
+- `conduit:response:complete:{uuid}` - Stream completed (listener)
+- `conduit:response:error:{uuid}` - Error occurred (listener)
+- `conduit:response:cancelled:{uuid}` - Request was cancelled (listener)
+
+### Types
+
+```typescript
+interface ErrorResponse {
+  success: false;
+  requestUuid: string;
+  timestamp: Date;
+  error: string;
+  stack?: string;
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+import { IApplicationAdapter, ServiceCollection, Application } from '@oldzy/conduit';
+export { IElectronService } from './preload.mjs';
+
+declare class ElectronAdapter implements IApplicationAdapter {
+    name: string;
+    private app?;
+    private requestControllers;
+    configure(services: ServiceCollection): void | Promise<void>;
+    initialize(app: Application): void | Promise<void>;
+    private handleRequest;
+    private handleStream;
+    private handleCancel;
+    private createErrorResponse;
+    dispose(): void | Promise<void>;
+}
+
+interface ErrorResponse {
+    success: false;
+    requestUuid: string;
+    timestamp: Date;
+    error: string;
+    stack?: string;
+}
+
+export { ElectronAdapter, type ErrorResponse };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { IApplicationAdapter, ServiceCollection, Application } from '@oldzy/conduit';
+export { IElectronService } from './preload.js';
+
+declare class ElectronAdapter implements IApplicationAdapter {
+    name: string;
+    private app?;
+    private requestControllers;
+    configure(services: ServiceCollection): void | Promise<void>;
+    initialize(app: Application): void | Promise<void>;
+    private handleRequest;
+    private handleStream;
+    private handleCancel;
+    private createErrorResponse;
+    dispose(): void | Promise<void>;
+}
+
+interface ErrorResponse {
+    success: false;
+    requestUuid: string;
+    timestamp: Date;
+    error: string;
+    stack?: string;
+}
+
+export { ElectronAdapter, type ErrorResponse };

package/dist/index.js

@@ -0,0 +1,2 @@
+'use strict';var electron=require('electron'),conduit=require('@oldzy/conduit');/* conduit - MIT License */
+var c=Object.defineProperty;var h=(o,s,e)=>s in o?c(o,s,{enumerable:true,configurable:true,writable:true,value:e}):o[s]=e;var u=(o,s)=>c(o,"name",{value:s,configurable:true});var a=(o,s,e)=>h(o,typeof s!="symbol"?s+"":s,e);var l=class l{constructor(){a(this,"name","ElectronAdapter");a(this,"app");a(this,"requestControllers",new Map);}configure(s){s.addSingleton("ElectronApp",electron.app),s.addSingleton("IpcMain",electron.ipcMain);}initialize(s){if(this.app=s,!this.app)throw new Error("Application not initialized");electron.ipcMain.handle("conduit:send",async(e,n)=>await this.handleRequest(e,n)),electron.ipcMain.handle("conduit:cancel",async(e,n)=>{await this.handleCancel(e,n);});}async handleRequest(s,e){try{let n=new AbortController;this.requestControllers.set(e.uuid,n);let r=await this.app.send(e);if(r instanceof conduit.BaseResponse)return this.requestControllers.delete(e.uuid),r;await this.handleStream(s,e,r,n);}catch(n){let r=this.createErrorResponse(e.uuid,n);s.sender.send(`conduit:response:error:${e.uuid}`,r),this.requestControllers.delete(e.uuid);}}async handleStream(s,e,n,r){try{for await(let d of n){if(r.signal.aborted){s.sender.send(`conduit:response:cancelled:${e.uuid}`,{success:!1,requestUuid:e.uuid,error:"Request was cancelled"});return}s.sender.send(`conduit:response:data:${e.uuid}`,d);}s.sender.send(`conduit:response:complete:${e.uuid}`);}catch(d){if(r.signal.aborted)s.sender.send(`conduit:response:cancelled:${e.uuid}`,{success:false,requestUuid:e.uuid,error:"Request was cancelled"});else {let p=this.createErrorResponse(e.uuid,d);s.sender.send(`conduit:response:error:${e.uuid}`,p);}}finally{this.requestControllers.delete(e.uuid);}}async handleCancel(s,e){let n=this.requestControllers.get(e);n&&(n.abort(),this.requestControllers.delete(e),s.sender.send(`conduit:response:cancelled:${e}`,{success:false,requestUuid:e,error:"Request cancelled by user"}));}createErrorResponse(s,e){return {success:false,requestUuid:s,timestamp:new Date,error:e instanceof Error?e.message:"Unknown error",stack:e instanceof Error?e.stack:void 0}}dispose(){for(let[s,e]of this.requestControllers.entries())e.abort(),this.requestControllers.delete(s);electron.ipcMain.removeHandler("conduit:send"),electron.ipcMain.removeHandler("conduit:cancel");}};u(l,"ElectronAdapter");var i=l;exports.ElectronAdapter=i;

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import {app,ipcMain}from'electron';import {BaseResponse}from'@oldzy/conduit';/* conduit - MIT License */
+var c=Object.defineProperty;var h=(o,s,e)=>s in o?c(o,s,{enumerable:true,configurable:true,writable:true,value:e}):o[s]=e;var u=(o,s)=>c(o,"name",{value:s,configurable:true});var a=(o,s,e)=>h(o,typeof s!="symbol"?s+"":s,e);var l=class l{constructor(){a(this,"name","ElectronAdapter");a(this,"app");a(this,"requestControllers",new Map);}configure(s){s.addSingleton("ElectronApp",app),s.addSingleton("IpcMain",ipcMain);}initialize(s){if(this.app=s,!this.app)throw new Error("Application not initialized");ipcMain.handle("conduit:send",async(e,n)=>await this.handleRequest(e,n)),ipcMain.handle("conduit:cancel",async(e,n)=>{await this.handleCancel(e,n);});}async handleRequest(s,e){try{let n=new AbortController;this.requestControllers.set(e.uuid,n);let r=await this.app.send(e);if(r instanceof BaseResponse)return this.requestControllers.delete(e.uuid),r;await this.handleStream(s,e,r,n);}catch(n){let r=this.createErrorResponse(e.uuid,n);s.sender.send(`conduit:response:error:${e.uuid}`,r),this.requestControllers.delete(e.uuid);}}async handleStream(s,e,n,r){try{for await(let d of n){if(r.signal.aborted){s.sender.send(`conduit:response:cancelled:${e.uuid}`,{success:!1,requestUuid:e.uuid,error:"Request was cancelled"});return}s.sender.send(`conduit:response:data:${e.uuid}`,d);}s.sender.send(`conduit:response:complete:${e.uuid}`);}catch(d){if(r.signal.aborted)s.sender.send(`conduit:response:cancelled:${e.uuid}`,{success:false,requestUuid:e.uuid,error:"Request was cancelled"});else {let p=this.createErrorResponse(e.uuid,d);s.sender.send(`conduit:response:error:${e.uuid}`,p);}}finally{this.requestControllers.delete(e.uuid);}}async handleCancel(s,e){let n=this.requestControllers.get(e);n&&(n.abort(),this.requestControllers.delete(e),s.sender.send(`conduit:response:cancelled:${e}`,{success:false,requestUuid:e,error:"Request cancelled by user"}));}createErrorResponse(s,e){return {success:false,requestUuid:s,timestamp:new Date,error:e instanceof Error?e.message:"Unknown error",stack:e instanceof Error?e.stack:void 0}}dispose(){for(let[s,e]of this.requestControllers.entries())e.abort(),this.requestControllers.delete(s);ipcMain.removeHandler("conduit:send"),ipcMain.removeHandler("conduit:cancel");}};u(l,"ElectronAdapter");var i=l;export{i as ElectronAdapter};

package/dist/preload.d.mts

@@ -0,0 +1,8 @@
+import { BaseRequest, BaseResponse } from '@oldzy/conduit';
+
+interface IElectronService {
+    send: (request: BaseRequest, onData?: (response: BaseResponse) => void) => Promise<BaseResponse | void>;
+    cancel: (requestUuid: string) => Promise<void>;
+}
+
+export type { IElectronService };

package/dist/preload.d.ts

@@ -0,0 +1,8 @@
+import { BaseRequest, BaseResponse } from '@oldzy/conduit';
+
+interface IElectronService {
+    send: (request: BaseRequest, onData?: (response: BaseResponse) => void) => Promise<BaseResponse | void>;
+    cancel: (requestUuid: string) => Promise<void>;
+}
+
+export type { IElectronService };

package/dist/preload.js

@@ -0,0 +1,2 @@
+'use strict';var electron=require('electron');/* conduit - MIT License */
+var m=Object.defineProperty;var c=(e,o)=>m(e,"name",{value:o,configurable:true});function l(e,o){return setTimeout(()=>{e(),o({success:false,error:"The request timed out",timestamp:new Date});},3e4)}c(l,"setTimeoutError");electron.contextBridge.exposeInMainWorld("electronService",{send:c(async(e,o)=>new Promise(async(d,u)=>{let i=c(()=>{clearTimeout(s),electron.ipcRenderer.removeAllListeners(`conduit:response:data:${e.uuid}`),electron.ipcRenderer.removeAllListeners(`conduit:response:complete:${e.uuid}`),electron.ipcRenderer.removeAllListeners(`conduit:response:error:${e.uuid}`),electron.ipcRenderer.removeAllListeners(`conduit:response:cancelled:${e.uuid}`);},"cleanup"),s=l(i,u);electron.ipcRenderer.on(`conduit:response:data:${e.uuid}`,(t,r)=>{clearTimeout(s),s=l(i,u),o&&o(r);}),electron.ipcRenderer.on(`conduit:response:complete:${e.uuid}`,()=>{i(),d();}),electron.ipcRenderer.on(`conduit:response:error:${e.uuid}`,(t,r)=>{i(),u(r);}),electron.ipcRenderer.on(`conduit:response:cancelled:${e.uuid}`,(t,r)=>{i(),u(r);}),electron.ipcRenderer.invoke("conduit:send",e).then(t=>{t&&(i(),d(t));});}),"send"),cancel:c(async e=>electron.ipcRenderer.invoke("conduit:cancel",e),"cancel")});

package/dist/preload.mjs

@@ -0,0 +1,2 @@
+import {contextBridge,ipcRenderer}from'electron';/* conduit - MIT License */
+var m=Object.defineProperty;var c=(e,o)=>m(e,"name",{value:o,configurable:true});function l(e,o){return setTimeout(()=>{e(),o({success:false,error:"The request timed out",timestamp:new Date});},3e4)}c(l,"setTimeoutError");contextBridge.exposeInMainWorld("electronService",{send:c(async(e,o)=>new Promise(async(d,u)=>{let i=c(()=>{clearTimeout(s),ipcRenderer.removeAllListeners(`conduit:response:data:${e.uuid}`),ipcRenderer.removeAllListeners(`conduit:response:complete:${e.uuid}`),ipcRenderer.removeAllListeners(`conduit:response:error:${e.uuid}`),ipcRenderer.removeAllListeners(`conduit:response:cancelled:${e.uuid}`);},"cleanup"),s=l(i,u);ipcRenderer.on(`conduit:response:data:${e.uuid}`,(t,r)=>{clearTimeout(s),s=l(i,u),o&&o(r);}),ipcRenderer.on(`conduit:response:complete:${e.uuid}`,()=>{i(),d();}),ipcRenderer.on(`conduit:response:error:${e.uuid}`,(t,r)=>{i(),u(r);}),ipcRenderer.on(`conduit:response:cancelled:${e.uuid}`,(t,r)=>{i(),u(r);}),ipcRenderer.invoke("conduit:send",e).then(t=>{t&&(i(),d(t));});}),"send"),cancel:c(async e=>ipcRenderer.invoke("conduit:cancel",e),"cancel")});

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@oldzy/conduit-electron-adapter",
+  "version": "1.0.0",
+  "description": "Electron IPC adapter for @oldzy/conduit - enables seamless communication between main and renderer processes",
+  "author": "oldzy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oldzy/conduit-electron-adapter.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    },
+    "./preload": {
+      "types": "./dist/preload.d.ts",
+      "require": "./dist/preload.js",
+      "import": "./dist/preload.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:prod": "cross-env NODE_ENV=production tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:watch": "vitest --watch",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build:prod && npm test"
+  },
+  "keywords": [
+    "conduit",
+    "electron",
+    "ipc",
+    "adapter",
+    "electron-adapter",
+    "electron-ipc",
+    "mediator",
+    "request-response",
+    "streaming",
+    "contextbridge",
+    "preload"
+  ],
+  "devDependencies": {
+    "@swc/core": "^1.15.2",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.9",
+    "@vitest/ui": "^4.0.9",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "unplugin-swc": "^1.5.8",
+    "vitest": "^4.0.9"
+  },
+  "dependencies": {
+    "@oldzy/conduit": "^1.0.2",
+    "electron": "^39.2.7",
+    "reflect-metadata": "^0.2.2",
+    "uuid": "^13.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}