Conduit Electron Adapter

Electron IPC adapter for @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
• 📡 Separate handlers for simple and streaming responses
• 🚫 Request cancellation support
• 💉 Automatic dependency injection for Electron App and IpcMain
• 🔄 AbortController integration for async operations
• 🔒 Type-safe with TypeScript generics

Installation

npm install @oldzy/conduit-electron-adapter

Usage

Main Process

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:

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 conduit 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

// Simple request/response (for SimpleHandler)
const response = await window.conduit.send<GetUserResponse>({
  uuid: crypto.randomUUID(),
  type: 'GET_USER',
  userId: '123'
});
console.log(response.userName);

// Streaming request (for StreamingHandler)
await window.conduit.stream<LogChunkResponse>(
  {
    uuid: crypto.randomUUID(),
    type: 'STREAM_LOGS',
    filename: 'app.log'
  },
  (chunk) => {
    console.log('Received chunk:', chunk.line);
  }
);

// Cancel a request
await window.conduit.cancel('request-uuid');

API

ElectronAdapter (Main Process)

The adapter automatically:

• Registers conduit:send IPC handler for simple requests (SimpleHandler)
• Registers conduit:stream IPC handler for streaming requests (StreamingHandler)
• 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

IConduitService (Renderer Process)

The window.conduit object is automatically typed when you import the package:

import '@oldzy/conduit-electron-adapter';

// Now window.conduit is fully typed!
const response = await window.conduit.send<MyResponse>(request);

interface IConduitService {
  send: <TResponse extends BaseResponse>(
    request: BaseRequest
  ) => Promise<TResponse>;
  stream: <TResponse extends BaseResponse>(
    request: BaseRequest,
    onData: (response: TResponse) => void
  ) => Promise<void>;
  cancel: (requestUuid: string) => Promise<void>;
}

Methodstimeout (30s) and cleanup

• cancel(requestUuid) - Cancel a pending request by UUID

Important: Use send() for SimpleHandler and stream() for StreamingHandler. Using the wrong method will result in an error.

IPC Channels

Internal channels (handled automatically by the preload script):

• conduit:send - Send a simple request (invoke) - returns response

• conduit:stream - Start a streaming request (invoke) - sends chunks via eventsuest (invoke) - sends chunks via eventsd cleanup

• cancel(requestUuid) - Cancel a pending request by UUID

Important: Use send() for SimpleHandler and stream() for StreamingHandler. Using the wrong method will result in an error.

• 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

interface ErrorResponse {
class ErrorResponse extends BaseResponse {
  constructor(
    public requestUuid: string,
    public error: string,
    public stack?: string
  );
}

Note: The window.conduit type is automatically available when you import the package in your TypeScript files.

License

MIT