electron-effect-rpc 0.1.0 → 0.2.0

package/README.md

@@ -11,9 +11,10 @@ uses Electron 38) and assumes ESM-capable bundling.
 - Single shared contract for methods and events.
 - End-to-end type safety using @effect/schema.
 - Promise-based renderer client with typed errors.
-- Effect-based main handlers with optional runtime injection.
-- Event bus and subscriber for typed renderer events.
-- No protocol handshake or versioning; schema decoding is the source of truth.
+- Effect-based main handlers with explicit runtime injection.
+- Explicit lifecycle handles for main-process RPC and event publishing.
+- Bounded event queue with drop-oldest backpressure.
+- Structured diagnostics hooks for decode/protocol/dispatch failures.
 
 ## Requirements
 - Electron with context isolation enabled.
@@ -30,7 +31,21 @@ and let the workspace resolver handle the rest.
 
 ## Core Concepts
 
-### Methods and events
+### Communication directions
+
+This library provides two communication patterns for Electron IPC:
+
+| Direction | Mechanism | Pattern | Use case |
+|-----------|-----------|---------|----------|
+| **Renderer → Main** | RPC methods | Request/response | Fetching data, triggering actions, calling main process APIs |
+| **Main → Renderer** | Event bus | Push/broadcast | Progress updates, state changes, background task notifications |
+
+**RPC methods** are for when the renderer needs something from the main process. The renderer calls a method and awaits a typed response.
+
+**Events** are for when the main process needs to notify the renderer. The main process emits events whenever it wants, and the renderer subscribes to receive them.
+
+### Defining methods and events
+
 Define methods and events using schema-based helpers:
 
 ```ts
@@ -85,36 +100,43 @@ export const ReadTextFile = rpc(
 ```ts
 import { app, ipcMain } from "electron";
 import { Effect } from "effect";
-import { createRpcServer, createEventBus } from "electron-effect-rpc/main";
+import * as Runtime from "effect/Runtime";
+import { createRpcEndpoint, createEventPublisher } from "electron-effect-rpc/main";
 import { contract, WorkUnitProgress } from "./contract.ts";
 
 const implementations = {
   GetAppVersion: () => Effect.succeed({ version: app.getVersion() }),
 };
 
-createRpcServer(contract, ipcMain, implementations);
+const endpoint = createRpcEndpoint(contract, ipcMain, implementations, {
+  runtime: Runtime.defaultRuntime,
+});
+endpoint.start();
 
-const eventBus = createEventBus(contract, {
+const publisher = createEventPublisher(contract, {
   getWindow: () => mainWindow,
 });
+publisher.start();
 
-eventBus.emit(WorkUnitProgress, {
+publisher.publish(WorkUnitProgress, {
   requestId: "req-1",
   chunk: "working...",
   done: false,
 });
 ```
 
-If your handlers require services in the Effect environment, provide a runtime:
+Pass the runtime used to execute handler effects:
 
 ```ts
 import * as Runtime from "effect/Runtime";
-import { createRpcServer } from "electron-effect-rpc/main";
+import { createRpcEndpoint } from "electron-effect-rpc/main";
 import { contract } from "./contract.ts";
 
-createRpcServer(contract, ipcMain, implementations, {
+const endpoint = createRpcEndpoint(contract, ipcMain, implementations, {
   runtime: Runtime.defaultRuntime,
 });
+
+endpoint.start();
 ```
 
 ### Preload: expose bridge globals
@@ -138,13 +160,25 @@ exposeRpcBridge({
 });
 ```
 
+Or use low-level bridge adapters for custom exposure:
+```ts
+import { createBridgeAdapters } from "electron-effect-rpc/preload";
+
+const bridge = createBridgeAdapters();
+// bridge.invoke(method, payload)
+// bridge.subscribe(name, handler)
+```
+
 ### Renderer: create client and subscriber
 ```ts
 import { createRpcClient, createEventSubscriber } from "electron-effect-rpc/renderer";
 import { contract, WorkUnitProgress } from "./contract.ts";
 
 const client = createRpcClient(contract, { invoke: window.rpc.invoke });
-const events = createEventSubscriber(contract, { subscribe: window.events.subscribe });
+const events = createEventSubscriber(contract, {
+  subscribe: window.events.subscribe,
+  decodeMode: "safe", // default
+});
 
 const { version } = await client.GetAppVersion();
 
@@ -180,8 +214,10 @@ import { createInvokeStub } from "electron-effect-rpc/testing";
 import { contract } from "./contract.ts";
 
 const invoke = createInvokeStub(async (method, payload) => {
-  // return encoded Exit values from your handler logic
-  return payload;
+  return {
+    type: "success",
+    data: { version: "1.0.0" },
+  };
 });
 
 const client = createRpcClient(contract, { invoke });
@@ -196,7 +232,8 @@ expect(invoke.invocations).toEqual([
 You can stub `IpcMainLike` and collect registered handlers:
 
 ```ts
-import { createRpcServer } from "electron-effect-rpc/main";
+import * as Runtime from "effect/Runtime";
+import { createRpcEndpoint } from "electron-effect-rpc/main";
 import type { IpcMainLike } from "electron-effect-rpc/types";
 import { contract } from "./contract.ts";
 
@@ -205,9 +242,15 @@ const ipcMainStub: IpcMainLike = {
   handle: (channel, handler) => {
     handlers.set(channel, handler);
   },
+  removeHandler: (channel) => {
+    handlers.delete(channel);
+  },
 };
 
-createRpcServer(contract, ipcMainStub, implementations);
+const endpoint = createRpcEndpoint(contract, ipcMainStub, implementations, {
+  runtime: Runtime.defaultRuntime,
+});
+endpoint.start();
 ```
 
 ## Error Handling
@@ -222,13 +265,13 @@ Entry points:
 - `electron-effect-rpc/contract`
   - `rpc`, `event`, `defineContract`, `exitSchemaFor`, `SchemaNoContext`, `NoError`
 - `electron-effect-rpc/types`
-  - Type aliases such as `Implementations`, `RpcClient`, `RpcEventBus`, `IpcMainLike`
+  - Type aliases such as `Implementations`, `RpcClient`, `RpcEventPublisher`, `IpcMainLike`
 - `electron-effect-rpc/main`
-  - `createRpcServer`, `createEventBus`
+  - `createRpcEndpoint`, `createEventPublisher`
 - `electron-effect-rpc/renderer`
   - `createRpcClient`, `createEventSubscriber`, `RpcDefectError`
 - `electron-effect-rpc/preload`
-  - `exposeRpcBridge`
+  - `exposeRpcBridge`, `createBridgeAdapters`
 - `electron-effect-rpc/testing`
   - `createInvokeStub`, `createDeferred`
 

package/dist/contract.d.ts

@@ -0,0 +1,41 @@
+import * as S from "@effect/schema/Schema";
+export type SchemaNoContext = S.Schema.AnyNoContext;
+export declare const NoError: typeof S.Never;
+export type NoError = typeof NoError;
+export type ErrorSchema = SchemaNoContext | NoError;
+export declare function isNoErrorSchema(schema: ErrorSchema): schema is NoError;
+export interface RpcMethod<Name extends string, Req extends SchemaNoContext, Res extends SchemaNoContext, Err extends ErrorSchema = NoError> {
+    readonly name: Name;
+    readonly req: Req;
+    readonly res: Res;
+    readonly err: Err;
+}
+export declare function rpc<const Name extends string, Req extends SchemaNoContext, Res extends SchemaNoContext, Err extends ErrorSchema>(name: Name, req: Req, res: Res, err: Err): RpcMethod<Name, Req, Res, Err>;
+export declare function rpc<const Name extends string, Req extends SchemaNoContext, Res extends SchemaNoContext>(name: Name, req: Req, res: Res): RpcMethod<Name, Req, Res, NoError>;
+export interface RpcEvent<Payload extends SchemaNoContext, Context extends SchemaNoContext | null, Name extends string = string> {
+    readonly name: Name;
+    readonly payload: Payload;
+    readonly context: Context;
+}
+export declare function event<const Name extends string, Payload extends SchemaNoContext, Context extends SchemaNoContext>(name: Name, payload: Payload, context: Context): RpcEvent<Payload, Context, Name>;
+export declare function event<const Name extends string, Payload extends SchemaNoContext>(name: Name, payload: Payload): RpcEvent<Payload, null, Name>;
+export declare const exitSchemaFor: <Name extends string, Req extends SchemaNoContext, Res extends SchemaNoContext, Err extends ErrorSchema>(method: RpcMethod<Name, Req, Res, Err>) => S.Exit<Res, Err, S.Defect>;
+export type AnyMethod = RpcMethod<string, SchemaNoContext, SchemaNoContext, ErrorSchema>;
+export type AnyEvent = RpcEvent<SchemaNoContext, SchemaNoContext | null, string>;
+export type RpcInput<M extends AnyMethod> = S.Schema.Type<M["req"]>;
+export type RpcOutput<M extends AnyMethod> = S.Schema.Type<M["res"]>;
+export type RpcError<M extends AnyMethod> = S.Schema.Type<M["err"]>;
+export type RpcEventPayload<E extends AnyEvent> = S.Schema.Type<E["payload"]>;
+/** Extract a method from a tuple by its name string literal. */
+export type ExtractMethod<Methods extends readonly AnyMethod[], Name extends string> = Extract<Methods[number], {
+    readonly name: Name;
+}>;
+export interface RpcContract<Methods extends ReadonlyArray<AnyMethod>, Events extends ReadonlyArray<AnyEvent>> {
+    readonly methods: Methods;
+    readonly events: Events;
+}
+export declare function defineContract<const Methods extends ReadonlyArray<AnyMethod>, const Events extends ReadonlyArray<AnyEvent>>(input: {
+    readonly methods: Methods;
+    readonly events: Events;
+}): RpcContract<Methods, Events>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -0,0 +1,46 @@
+import * as S from "@effect/schema/Schema";
+export const NoError = S.Never;
+export function isNoErrorSchema(schema) {
+    return schema === NoError;
+}
+export function rpc(name, req, res, err = NoError) {
+    return { name, req, res, err };
+}
+export function event(name, payload, context) {
+    return { name, payload, context: context ?? null };
+}
+export const exitSchemaFor = (method) => S.Exit({
+    success: method.res,
+    failure: method.err,
+    defect: S.Defect,
+});
+function collectDuplicates(names) {
+    const counts = new Map();
+    const duplicates = [];
+    for (const name of names) {
+        const next = (counts.get(name) ?? 0) + 1;
+        counts.set(name, next);
+        if (next === 2) {
+            duplicates.push(name);
+        }
+    }
+    return duplicates;
+}
+export function defineContract(input) {
+    const { methods, events } = input;
+    if (!Array.isArray(methods)) {
+        throw new Error("RPC contract methods must be an array.");
+    }
+    if (!Array.isArray(events)) {
+        throw new Error("RPC contract events must be an array.");
+    }
+    const duplicateMethods = collectDuplicates(methods.map((method) => method.name));
+    if (duplicateMethods.length > 0) {
+        throw new Error(`Duplicate RPC method name(s): ${duplicateMethods.join(", ")}`);
+    }
+    const duplicateEvents = collectDuplicates(events.map((event) => event.name));
+    if (duplicateEvents.length > 0) {
+        throw new Error(`Duplicate RPC event name(s): ${duplicateEvents.join(", ")}`);
+    }
+    return input;
+}

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+import type { RpcContract } from "./contract.ts";
+import { type AnyEvent, type AnyMethod, type EventPublisherOptions, type Implementations, type IpcMainLike, type RpcEndpoint, type RpcEndpointOptions, type RpcEventPublisher } from "./types.ts";
+export declare function createRpcEndpoint<const Methods extends ReadonlyArray<AnyMethod>, const Events extends ReadonlyArray<AnyEvent>, R = never>(contract: RpcContract<Methods, Events>, ipc: IpcMainLike, implementations: Implementations<RpcContract<Methods, Events>, R>, options: RpcEndpointOptions<R>): RpcEndpoint;
+export declare function createEventPublisher<const Methods extends ReadonlyArray<AnyMethod>, const Events extends ReadonlyArray<AnyEvent>>(_contract: RpcContract<Methods, Events>, options: EventPublisherOptions): RpcEventPublisher<RpcContract<Methods, Events>>;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,eAAe,CAAC;AAQvB,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAmBpB,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,OAAO,SAAS,aAAa,CAAC,SAAS,CAAC,EAC9C,KAAK,CAAC,MAAM,SAAS,aAAa,CAAC,QAAQ,CAAC,EAC5C,CAAC,GAAG,KAAK,EAET,QAAQ,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,EACtC,GAAG,EAAE,WAAW,EAChB,eAAe,EAAE,eAAe,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,EACjE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,WAAW,CA4Kb;AAmBD,wBAAgB,oBAAoB,CAClC,KAAK,CAAC,OAAO,SAAS,aAAa,CAAC,SAAS,CAAC,EAC9C,KAAK,CAAC,MAAM,SAAS,aAAa,CAAC,QAAQ,CAAC,EAE5C,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,EACvC,OAAO,EAAE,qBAAqB,GAC7B,iBAAiB,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CA8KjD"}

package/dist/main.js

@@ -0,0 +1,296 @@
+import * as S from "@effect/schema/Schema";
+import { Cause, Effect, Exit } from "effect";
+import * as Runtime from "effect/Runtime";
+import { isNoErrorSchema } from "./contract.js";
+import { extractErrorTag, safelyCall, toDefectEnvelope, } from "./protocol.js";
+import { defaultChannelPrefix, } from "./types.js";
+function resolveChannelPrefix(prefix) {
+    return prefix ?? defaultChannelPrefix;
+}
+function isImplementation(value) {
+    return typeof value === "function";
+}
+export function createRpcEndpoint(contract, ipc, implementations, options) {
+    const channelPrefix = resolveChannelPrefix(options.channelPrefix);
+    const diagnostics = options.diagnostics;
+    const runPromiseExit = Runtime.runPromiseExit(options.runtime);
+    const implementationsByName = implementations;
+    const methodNames = new Set(contract.methods.map((method) => method.name));
+    for (const name in implementations) {
+        if (!methodNames.has(name)) {
+            throw new Error(`Implementation provided for unknown RPC method: ${name}`);
+        }
+    }
+    function reportProtocolError(method, response, cause) {
+        safelyCall(diagnostics?.onProtocolError, {
+            method,
+            response,
+            cause,
+        });
+    }
+    const listeners = new Map();
+    for (const method of contract.methods) {
+        const impl = implementationsByName[method.name];
+        if (!isImplementation(impl)) {
+            throw new Error(`Missing implementation for RPC method: ${method.name}`);
+        }
+        const decodeInput = S.decodeUnknownSync(method.req);
+        const encodeSuccess = S.encodeSync(method.res);
+        const encodeFailure = isNoErrorSchema(method.err)
+            ? null
+            : S.encodeSync(method.err);
+        const channel = `${channelPrefix.rpc}${method.name}`;
+        listeners.set(channel, async function handleRpcRequest(_event, rawPayload) {
+            let input;
+            try {
+                input = decodeInput(rawPayload);
+            }
+            catch (cause) {
+                safelyCall(diagnostics?.onDecodeFailure, {
+                    scope: "rpc-request",
+                    name: method.name,
+                    payload: rawPayload,
+                    cause,
+                });
+                return toDefectEnvelope(cause, `RPC ${method.name} request decode failed`);
+            }
+            let effect;
+            try {
+                effect = impl(input);
+            }
+            catch (cause) {
+                return toDefectEnvelope(cause, `RPC ${method.name} implementation threw`);
+            }
+            const exit = await runPromiseExit(effect);
+            if (Exit.isSuccess(exit)) {
+                try {
+                    return {
+                        type: "success",
+                        data: encodeSuccess(exit.value),
+                    };
+                }
+                catch (cause) {
+                    reportProtocolError(method.name, exit.value, cause);
+                    return toDefectEnvelope(cause, `RPC ${method.name} success encoding failed`);
+                }
+            }
+            const failure = Cause.failureOption(exit.cause);
+            if (failure._tag === "Some") {
+                if (!encodeFailure) {
+                    return toDefectEnvelope(failure.value, `RPC ${method.name} returned a typed failure, but method declares NoError`);
+                }
+                try {
+                    return {
+                        type: "failure",
+                        error: {
+                            tag: extractErrorTag(failure.value),
+                            data: encodeFailure(failure.value),
+                        },
+                    };
+                }
+                catch (cause) {
+                    reportProtocolError(method.name, failure.value, cause);
+                    return toDefectEnvelope(cause, `RPC ${method.name} failure encoding failed`);
+                }
+            }
+            const defect = Cause.dieOption(exit.cause);
+            if (defect._tag === "Some") {
+                return toDefectEnvelope(defect.value, `RPC ${method.name} defect`);
+            }
+            return toDefectEnvelope(exit.cause, `RPC ${method.name} interrupted`);
+        });
+    }
+    let running = false;
+    let disposed = false;
+    function start() {
+        if (disposed) {
+            throw new Error("RPC endpoint has already been disposed.");
+        }
+        if (running) {
+            return;
+        }
+        for (const [channel, listener] of listeners) {
+            ipc.handle(channel, listener);
+        }
+        running = true;
+    }
+    function stop() {
+        if (!running) {
+            return;
+        }
+        for (const channel of listeners.keys()) {
+            ipc.removeHandler(channel);
+        }
+        running = false;
+    }
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        stop();
+        disposed = true;
+    }
+    function isRunning() {
+        return running;
+    }
+    return {
+        start,
+        stop,
+        dispose,
+        isRunning,
+    };
+}
+function clampQueueSize(maxQueueSize) {
+    if (maxQueueSize === undefined) {
+        return 1000;
+    }
+    if (!Number.isFinite(maxQueueSize) || maxQueueSize < 1) {
+        throw new Error("Event publisher maxQueueSize must be a positive finite number.");
+    }
+    return Math.floor(maxQueueSize);
+}
+export function createEventPublisher(_contract, options) {
+    const channelPrefix = resolveChannelPrefix(options.channelPrefix);
+    const diagnostics = options.diagnostics;
+    const maxQueueSize = clampQueueSize(options.maxQueueSize);
+    const queue = [];
+    let dropped = 0;
+    let running = false;
+    let disposed = false;
+    let draining = false;
+    let drainScheduled = false;
+    function scheduleDrain() {
+        if (!running || disposed || draining || drainScheduled) {
+            return;
+        }
+        drainScheduled = true;
+        queueMicrotask(() => {
+            drainScheduled = false;
+            drain();
+        });
+    }
+    function dispatch(item) {
+        let encoded;
+        try {
+            encoded = S.encodeSync(item.event.payload)(item.payload);
+        }
+        catch (cause) {
+            dropped += 1;
+            safelyCall(diagnostics?.onDecodeFailure, {
+                scope: "event-payload",
+                name: item.event.name,
+                payload: item.payload,
+                cause,
+            });
+            safelyCall(diagnostics?.onDroppedEvent, {
+                event: item.event.name,
+                payload: item.payload,
+                reason: "encoding_failed",
+                queued: queue.length,
+                dropped,
+            });
+            return;
+        }
+        const window = options.getWindow();
+        if (!window || window.isDestroyed()) {
+            return;
+        }
+        try {
+            window.webContents.send(`${channelPrefix.event}${item.event.name}`, encoded);
+        }
+        catch (cause) {
+            safelyCall(diagnostics?.onDispatchFailure, {
+                event: item.event.name,
+                payload: item.payload,
+                cause,
+            });
+        }
+    }
+    function drain() {
+        if (!running || disposed || draining) {
+            return;
+        }
+        draining = true;
+        try {
+            while (running && !disposed && queue.length > 0) {
+                const next = queue.shift();
+                if (!next) {
+                    continue;
+                }
+                dispatch(next);
+            }
+        }
+        finally {
+            draining = false;
+            if (running && !disposed && queue.length > 0) {
+                scheduleDrain();
+            }
+        }
+    }
+    function enqueue(item) {
+        if (queue.length >= maxQueueSize) {
+            const evicted = queue.shift();
+            dropped += 1;
+            if (evicted) {
+                safelyCall(diagnostics?.onDroppedEvent, {
+                    event: evicted.event.name,
+                    payload: evicted.payload,
+                    reason: "queue_full",
+                    queued: queue.length,
+                    dropped,
+                });
+            }
+        }
+        queue.push(item);
+        scheduleDrain();
+    }
+    function publish(event, payload) {
+        return Effect.sync(() => {
+            if (disposed) {
+                return;
+            }
+            enqueue({ event, payload });
+        });
+    }
+    function start() {
+        if (disposed) {
+            throw new Error("Event publisher has already been disposed.");
+        }
+        if (running) {
+            return;
+        }
+        running = true;
+        scheduleDrain();
+    }
+    function stop() {
+        if (!running) {
+            return;
+        }
+        running = false;
+    }
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        stop();
+        queue.length = 0;
+        disposed = true;
+    }
+    function isRunning() {
+        return running;
+    }
+    function stats() {
+        return {
+            queued: queue.length,
+            dropped,
+        };
+    }
+    return {
+        publish,
+        start,
+        stop,
+        dispose,
+        isRunning,
+        stats,
+    };
+}

package/dist/preload.d.ts

@@ -0,0 +1,15 @@
+import { type ChannelPrefix, type EventSubscribe, type RpcInvoke } from "./types.ts";
+export type BridgeAdapters = {
+    readonly invoke: RpcInvoke;
+    readonly subscribe: EventSubscribe;
+};
+export type BridgeAdaptersOptions = {
+    readonly channelPrefix?: ChannelPrefix;
+};
+export type BridgeExposureOptions = BridgeAdaptersOptions & {
+    readonly rpcGlobal?: string;
+    readonly eventsGlobal?: string;
+};
+export declare function createBridgeAdapters(options?: BridgeAdaptersOptions): BridgeAdapters;
+export declare function exposeRpcBridge(options?: BridgeExposureOptions): void;
+//# sourceMappingURL=preload.d.ts.map

package/dist/preload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload.d.ts","sourceRoot":"","sources":["../src/preload.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,qBAAqB,GAAG;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAsBhB;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAerE"}

package/dist/preload.js

@@ -0,0 +1,31 @@
+import { contextBridge, ipcRenderer } from "electron";
+import { defaultChannelPrefix, } from "./types.js";
+export function createBridgeAdapters(options) {
+    const channelPrefix = options?.channelPrefix ?? defaultChannelPrefix;
+    const invoke = (method, payload) => ipcRenderer.invoke(`${channelPrefix.rpc}${method}`, payload);
+    const subscribe = (event, listener) => {
+        const wrapped = (_event, payload) => listener(payload);
+        const channel = `${channelPrefix.event}${event}`;
+        ipcRenderer.on(channel, wrapped);
+        return () => {
+            ipcRenderer.removeListener(channel, wrapped);
+        };
+    };
+    return {
+        invoke,
+        subscribe,
+    };
+}
+export function exposeRpcBridge(options) {
+    const rpcGlobal = options?.rpcGlobal ?? "rpc";
+    const eventsGlobal = options?.eventsGlobal ?? "events";
+    const adapters = createBridgeAdapters({
+        channelPrefix: options?.channelPrefix,
+    });
+    contextBridge.exposeInMainWorld(rpcGlobal, {
+        invoke: adapters.invoke,
+    });
+    contextBridge.exposeInMainWorld(eventsGlobal, {
+        subscribe: adapters.subscribe,
+    });
+}

package/dist/protocol.d.ts

@@ -0,0 +1,23 @@
+export type RpcSuccessEnvelope = {
+    readonly type: "success";
+    readonly data: unknown;
+};
+export type RpcFailureEnvelope = {
+    readonly type: "failure";
+    readonly error: {
+        readonly tag: string;
+        readonly data: unknown;
+    };
+};
+export type RpcDefectEnvelope = {
+    readonly type: "defect";
+    readonly message: string;
+    readonly cause?: unknown;
+};
+export type RpcResponseEnvelope = RpcSuccessEnvelope | RpcFailureEnvelope | RpcDefectEnvelope;
+export declare function formatUnknown(value: unknown): string;
+export declare function extractErrorTag(error: unknown): string;
+export declare function toDefectEnvelope(cause: unknown, prefix?: string): RpcDefectEnvelope;
+export declare function safelyCall<T>(callback: ((context: T) => void) | undefined, context: T): void;
+export declare function parseRpcResponseEnvelope(value: unknown): RpcResponseEnvelope | null;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;KACxB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,CAAC;AAUtB,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUtD;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,GACd,iBAAiB,CAOnB;AAED,wBAAgB,UAAU,CAAC,CAAC,EAC1B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,EAC5C,OAAO,EAAE,CAAC,GACT,IAAI,CAUN;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,GACb,mBAAmB,GAAG,IAAI,CA+C5B"}