electron-effect-rpc 0.1.0

package/README.md

@@ -0,0 +1,241 @@
+# electron-effect-rpc
+
+Typed IPC RPC for Electron, built on Effect and @effect/schema. This library
+lets you define a shared contract, generate a typed RPC client in the renderer,
+register handlers in the main process, and stream typed events across processes.
+
+This package is ESM-only. It targets modern Electron runtimes (current project
+uses Electron 38) and assumes ESM-capable bundling.
+
+## Features
+- 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.
+
+## Requirements
+- Electron with context isolation enabled.
+- ESM-capable build pipeline.
+- Peer dependencies: `effect`, `@effect/schema`, `electron`.
+
+## Installation
+```sh
+bun add electron-effect-rpc effect @effect/schema
+```
+
+If you are in a monorepo workspace, add the dependency to the target package
+and let the workspace resolver handle the rest.
+
+## Core Concepts
+
+### Methods and events
+Define methods and events using schema-based helpers:
+
+```ts
+import * as S from "@effect/schema/Schema";
+import { defineContract, event, rpc } from "electron-effect-rpc/contract";
+
+export const GetAppVersion = rpc(
+  "GetAppVersion",
+  S.Struct({}),
+  S.Struct({ version: S.String })
+);
+
+export const WorkUnitProgress = event(
+  "WorkUnitProgress",
+  S.Struct({
+    requestId: S.String,
+    chunk: S.String,
+    done: S.Boolean,
+  })
+);
+
+const methods = [GetAppVersion] as const;
+const events = [WorkUnitProgress] as const;
+
+export const contract = defineContract({ methods, events });
+```
+
+### Errors
+Error schemas should be `Schema.TaggedError` classes. If a method does not
+declare an error schema, it uses `NoError` and the error channel is `never`.
+
+```ts
+import * as S from "@effect/schema/Schema";
+import { rpc } from "electron-effect-rpc/contract";
+
+export class FileReadError extends S.TaggedError<FileReadError>()("FileReadError", {
+  message: S.String,
+  path: S.String,
+}) {}
+
+export const ReadTextFile = rpc(
+  "ReadTextFile",
+  S.Struct({ path: S.String }),
+  S.Struct({ content: S.String }),
+  FileReadError
+);
+```
+
+## Usage
+
+### Main process: register handlers
+```ts
+import { app, ipcMain } from "electron";
+import { Effect } from "effect";
+import { createRpcServer, createEventBus } from "electron-effect-rpc/main";
+import { contract, WorkUnitProgress } from "./contract.ts";
+
+const implementations = {
+  GetAppVersion: () => Effect.succeed({ version: app.getVersion() }),
+};
+
+createRpcServer(contract, ipcMain, implementations);
+
+const eventBus = createEventBus(contract, {
+  getWindow: () => mainWindow,
+});
+
+eventBus.emit(WorkUnitProgress, {
+  requestId: "req-1",
+  chunk: "working...",
+  done: false,
+});
+```
+
+If your handlers require services in the Effect environment, provide a runtime:
+
+```ts
+import * as Runtime from "effect/Runtime";
+import { createRpcServer } from "electron-effect-rpc/main";
+import { contract } from "./contract.ts";
+
+createRpcServer(contract, ipcMain, implementations, {
+  runtime: Runtime.defaultRuntime,
+});
+```
+
+### Preload: expose bridge globals
+```ts
+import { exposeRpcBridge } from "electron-effect-rpc/preload";
+
+exposeRpcBridge();
+```
+
+Defaults:
+- RPC global: `window.rpc.invoke(method, payload)`
+- Events global: `window.events.subscribe(name, handler)`
+- Channel prefix: `rpc/` and `event/`
+
+You can override globals and prefixes:
+```ts
+exposeRpcBridge({
+  rpcGlobal: "rpcApi",
+  eventsGlobal: "rpcEvents",
+  channelPrefix: { rpc: "rpc/", event: "events/" },
+});
+```
+
+### 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 { version } = await client.GetAppVersion();
+
+events.subscribe(WorkUnitProgress, (payload) => {
+  console.log(payload.chunk);
+});
+```
+
+### Window type augmentation
+If you expose globals in preload, add a local `globals.d.ts`:
+
+```ts
+declare global {
+  interface Window {
+    rpc: {
+      invoke: (method: string, payload: unknown) => Promise<unknown>;
+    };
+    events: {
+      subscribe: (name: string, handler: (payload: unknown) => void) => () => void;
+    };
+  }
+}
+```
+
+## Testing
+
+### Renderer client tests
+Use the testing helpers to stub invoke behavior:
+
+```ts
+import { createRpcClient } from "electron-effect-rpc/renderer";
+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;
+});
+
+const client = createRpcClient(contract, { invoke });
+await client.GetAppVersion();
+
+expect(invoke.invocations).toEqual([
+  { method: "GetAppVersion", payload: {} },
+]);
+```
+
+### Main process tests
+You can stub `IpcMainLike` and collect registered handlers:
+
+```ts
+import { createRpcServer } from "electron-effect-rpc/main";
+import type { IpcMainLike } from "electron-effect-rpc/types";
+import { contract } from "./contract.ts";
+
+const handlers = new Map<string, (event: unknown, payload: unknown) => unknown>();
+const ipcMainStub: IpcMainLike = {
+  handle: (channel, handler) => {
+    handlers.set(channel, handler);
+  },
+};
+
+createRpcServer(contract, ipcMainStub, implementations);
+```
+
+## Error Handling
+- If a handler fails with a typed domain error, the renderer client rejects
+  with that error instance.
+- If a handler dies or throws a defect, the renderer client rejects with
+  `RpcDefectError`.
+
+## API Surface
+
+Entry points:
+- `electron-effect-rpc/contract`
+  - `rpc`, `event`, `defineContract`, `exitSchemaFor`, `SchemaNoContext`, `NoError`
+- `electron-effect-rpc/types`
+  - Type aliases such as `Implementations`, `RpcClient`, `RpcEventBus`, `IpcMainLike`
+- `electron-effect-rpc/main`
+  - `createRpcServer`, `createEventBus`
+- `electron-effect-rpc/renderer`
+  - `createRpcClient`, `createEventSubscriber`, `RpcDefectError`
+- `electron-effect-rpc/preload`
+  - `exposeRpcBridge`
+- `electron-effect-rpc/testing`
+  - `createInvokeStub`, `createDeferred`
+
+## Conventions
+- Relative imports use `.ts` extensions.
+- Package imports are extensionless.
+- No `index.ts` barrel files.
+
+## License
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "electron-effect-rpc",
+  "version": "0.1.0",
+  "description": "Typed IPC RPC for Electron, built on Effect and @effect/schema",
+  "type": "module",
+  "exports": {
+    "./main": "./src/main.ts",
+    "./renderer": "./src/renderer.ts",
+    "./preload": "./src/preload.ts",
+    "./contract": "./src/contract.ts",
+    "./types": "./src/types.ts",
+    "./testing": "./src/testing.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "electron",
+    "effect",
+    "rpc",
+    "ipc",
+    "typed",
+    "schema"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joaoeira/electron-effect-rpc"
+  },
+  "peerDependencies": {
+    "@effect/schema": ">=0.69.0",
+    "effect": ">=3.0.0",
+    "electron": ">=28.0.0"
+  },
+  "devDependencies": {
+    "@effect/schema": "^0.69.0",
+    "@types/node": "^22.0.0",
+    "bun-types": "^1.1.0",
+    "effect": "^3.11.0",
+    "electron": "^38.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/contract.ts

@@ -0,0 +1,165 @@
+import * as S from "@effect/schema/Schema";
+
+export type SchemaNoContext = S.Schema.AnyNoContext;
+
+export const NoError = S.Never;
+export type NoError = typeof NoError;
+
+export type ErrorSchema = SchemaNoContext | S.Schema<never, never, never>;
+
+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 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 function rpc<
+  const Name extends string,
+  Req extends SchemaNoContext,
+  Res extends SchemaNoContext
+>(name: Name, req: Req, res: Res): RpcMethod<Name, Req, Res, NoError>;
+
+export function rpc<const Name extends string>(
+  name: Name,
+  req: SchemaNoContext,
+  res: SchemaNoContext,
+  err: ErrorSchema = NoError
+): RpcMethod<Name, SchemaNoContext, SchemaNoContext, ErrorSchema> {
+  return { name, req, res, err };
+}
+
+export interface RpcEvent<
+  Payload extends SchemaNoContext,
+  Context extends SchemaNoContext | null,
+  Name extends string = string
+> {
+  readonly name: Name;
+  readonly payload: Payload;
+  readonly context: Context;
+}
+
+export function event<
+  const Name extends string,
+  Payload extends SchemaNoContext,
+  Context extends SchemaNoContext
+>(name: Name, payload: Payload, context: Context): RpcEvent<Payload, Context, Name>;
+
+export function event<const Name extends string, Payload extends SchemaNoContext>(
+  name: Name,
+  payload: Payload
+): RpcEvent<Payload, null, Name>;
+
+export function event<const Name extends string>(
+  name: Name,
+  payload: SchemaNoContext,
+  context?: SchemaNoContext | null
+): RpcEvent<SchemaNoContext, SchemaNoContext | null, Name> {
+  return { name, payload, context: context ?? null };
+}
+
+export const exitSchemaFor = <
+  Name extends string,
+  Req extends SchemaNoContext,
+  Res extends SchemaNoContext,
+  Err extends ErrorSchema
+>(
+  method: RpcMethod<Name, Req, Res, Err>
+) =>
+  S.Exit({
+    success: method.res,
+    failure: method.err,
+    defect: 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;
+}
+
+const collectDuplicates = (names: ReadonlyArray<string>): Array<string> => {
+  const counts = new Map<string, number>();
+  const duplicates: string[] = [];
+
+  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 const defineContract = <
+  const Methods extends ReadonlyArray<AnyMethod>,
+  const Events extends ReadonlyArray<AnyEvent>
+>(input: {
+  readonly methods: Methods;
+  readonly events: Events;
+}): RpcContract<Methods, Events> => {
+  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/src/main.ts

@@ -0,0 +1,169 @@
+import * as S from "@effect/schema/Schema";
+import { Effect, PubSub, Stream } from "effect";
+import * as Runtime from "effect/Runtime";
+import {
+  exitSchemaFor,
+  type RpcContract,
+  type RpcError,
+  type RpcEventPayload,
+  type RpcInput,
+  type RpcOutput,
+} from "./contract.ts";
+import {
+  defaultChannelPrefix,
+  type AnyEvent,
+  type AnyMethod,
+  type EventBusOptions,
+  type Implementations,
+  type IpcMainLike,
+  type RpcEventBus,
+  type RpcServerOptions,
+} from "./types.ts";
+
+const resolveChannelPrefix = (prefix: EventBusOptions["channelPrefix"]) =>
+  prefix ?? defaultChannelPrefix;
+
+export const createRpcServer = <
+  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?: RpcServerOptions<R>
+): void => {
+  const channelPrefix = resolveChannelPrefix(options?.channelPrefix);
+  const runPromiseExit = <A, E>(effect: Effect.Effect<A, E, R>) => {
+    if (options?.runtime) {
+      return Runtime.runPromiseExit(options.runtime)(effect);
+    }
+
+    // @ts-expect-error -- default runtime only supports R=never when no runtime is provided
+    return Effect.runPromiseExit(effect);
+  };
+  const implementationsByName: Implementations<RpcContract<Methods, Events>, R> &
+    Record<string, unknown> = 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}`);
+    }
+  }
+
+  contract.methods.forEach((method: Methods[number]) => {
+    const impl = implementationsByName[method.name];
+    if (!isImplementation<typeof method, R>(impl)) {
+      throw new Error(`Missing implementation for RPC method: ${method.name}`);
+    }
+
+    const exitSchema = exitSchemaFor(method);
+    const encodeExit = S.encodeUnknownSync(exitSchema);
+    const decodeInput = S.decodeUnknownSync(method.req);
+    const channel = `${channelPrefix.rpc}${method.name}`;
+
+    ipc.handle(channel, async (_event, rawPayload) => {
+      let input: RpcInput<typeof method>;
+      try {
+        input = decodeInput(rawPayload);
+      } catch (cause) {
+        const defectExit = await runPromiseExit(Effect.die(cause));
+        return encodeExit(defectExit);
+      }
+
+      const exit = await runPromiseExit(impl(input));
+      return encodeExit(exit);
+    });
+  });
+};
+
+type Envelope<E extends AnyEvent> = {
+  readonly event: E;
+  readonly payload: RpcEventPayload<E>;
+};
+
+const isImplementation = <M extends AnyMethod, R>(
+  value: unknown
+): value is (
+  input: RpcInput<M>
+) => Effect.Effect<RpcOutput<M>, RpcError<M>, R> => typeof value === "function";
+
+const encodePayload = <E extends AnyEvent>(
+  event: E,
+  payload: RpcEventPayload<E>
+) =>
+  Effect.try({
+    try: () => S.encodeSync(event.payload)(payload),
+    catch: (cause) =>
+      cause instanceof Error ? cause : new Error(String(cause)),
+  });
+
+const dispatchToRenderer = <E extends AnyEvent>(
+  getWindow: EventBusOptions["getWindow"],
+  channelPrefix: EventBusOptions["channelPrefix"],
+  event: E,
+  encoded: unknown
+) =>
+  Effect.sync(() => {
+    const window = getWindow();
+    if (window && !window.isDestroyed()) {
+      const prefix = resolveChannelPrefix(channelPrefix);
+      window.webContents.send(`${prefix.event}${event.name}`, encoded);
+    }
+  });
+
+export const createEventBus = <
+  const Methods extends ReadonlyArray<AnyMethod>,
+  const Events extends ReadonlyArray<AnyEvent>
+>(
+  _contract: RpcContract<Methods, Events>,
+  options: EventBusOptions
+): RpcEventBus<RpcContract<Methods, Events>> => {
+  const pubsub = Effect.runSync(
+    PubSub.unbounded<Envelope<Events[number]>>()
+  );
+
+  Effect.runFork(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const dequeue = yield* PubSub.subscribe(pubsub);
+        yield* Stream.fromQueue(dequeue, { shutdown: true }).pipe(
+          Stream.runForEach(({ event, payload }) =>
+            Effect.gen(function* () {
+              const encodeResult = yield* Effect.either(
+                encodePayload(event, payload)
+              );
+
+              if (encodeResult._tag === "Left") {
+                return;
+              }
+
+              yield* dispatchToRenderer(
+                options.getWindow,
+                options.channelPrefix,
+                event,
+                encodeResult.right
+              );
+            })
+          )
+        );
+      })
+    ).pipe(
+      Effect.catchAllCause(() => Effect.void),
+      Effect.retry({ times: 3 }),
+      Effect.catchAll(() => Effect.void)
+    )
+  );
+
+  const emit = <E extends Events[number]>(
+    event: E,
+    payload: RpcEventPayload<E>
+  ) =>
+    Effect.flatMap(PubSub.publish(pubsub, { event, payload }), () =>
+      Effect.void
+    );
+
+  return { emit };
+};

package/src/preload.ts

@@ -0,0 +1,33 @@
+import { contextBridge, ipcRenderer, type IpcRendererEvent } from "electron";
+import { defaultChannelPrefix, type ChannelPrefix } from "./types.ts";
+
+type Listener = (payload: unknown) => void;
+
+type BridgeOptions = {
+  readonly rpcGlobal?: string;
+  readonly eventsGlobal?: string;
+  readonly channelPrefix?: ChannelPrefix;
+};
+
+export const exposeRpcBridge = (options?: BridgeOptions): void => {
+  const rpcGlobal = options?.rpcGlobal ?? "rpc";
+  const eventsGlobal = options?.eventsGlobal ?? "events";
+  const channelPrefix = options?.channelPrefix ?? defaultChannelPrefix;
+
+  const invoke = (method: string, payload: unknown): Promise<unknown> =>
+    ipcRenderer.invoke(`${channelPrefix.rpc}${method}`, payload);
+
+  const subscribe = (event: string, listener: Listener): (() => void) => {
+    const wrapped = (_event: IpcRendererEvent, payload: unknown) =>
+      listener(payload);
+
+    ipcRenderer.on(`${channelPrefix.event}${event}`, wrapped);
+
+    return () => {
+      ipcRenderer.removeListener(`${channelPrefix.event}${event}`, wrapped);
+    };
+  };
+
+  contextBridge.exposeInMainWorld(rpcGlobal, { invoke });
+  contextBridge.exposeInMainWorld(eventsGlobal, { subscribe });
+};

package/src/renderer.ts

@@ -0,0 +1,167 @@
+import * as S from "@effect/schema/Schema";
+import { Cause, Exit } from "effect";
+import {
+  exitSchemaFor,
+  type RpcContract,
+  type RpcEventPayload,
+  type RpcInput,
+  type RpcOutput,
+} from "./contract.ts";
+import {
+  RpcDefectError,
+  type AnyEvent,
+  type AnyMethod,
+  type EventSubscriber,
+  type EventSubscriberOptions,
+  type RpcCaller,
+  type RpcClient,
+  type RpcClientOptions,
+} from "./types.ts";
+
+const formatCause = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);
+
+const requireInvoke = (options?: RpcClientOptions) => {
+  if (!options?.invoke) {
+    throw new Error("RpcClientOptions.invoke is required.");
+  }
+  return options.invoke;
+};
+
+const requireSubscribe = (options?: EventSubscriberOptions) => {
+  if (!options?.subscribe) {
+    throw new Error("EventSubscriberOptions.subscribe is required.");
+  }
+  return options.subscribe;
+};
+
+type MutableRpcClient<
+  C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[]>
+> = {
+  -readonly [Name in keyof RpcClient<C>]: RpcClient<C>[Name];
+};
+
+export const createRpcClient = <
+  const Methods extends ReadonlyArray<AnyMethod>,
+  const Events extends ReadonlyArray<AnyEvent>
+>(
+  contract: RpcContract<Methods, Events>,
+  options?: RpcClientOptions
+): RpcClient<RpcContract<Methods, Events>> => {
+  const invoke = requireInvoke(options);
+
+  const call = async <M extends Methods[number]>(
+    method: M,
+    input: RpcInput<M>
+  ): Promise<RpcOutput<M>> => {
+    let encoded: unknown;
+    try {
+      encoded = S.encodeSync(method.req)(input);
+    } catch (cause) {
+      throw new Error(
+        `RPC ${method.name} request encoding failed: ${formatCause(cause)}`
+      );
+    }
+
+    const raw = await invoke(method.name, encoded);
+
+    const exitSchema = exitSchemaFor(method);
+    const decodeExit = S.decodeUnknownSync(exitSchema);
+    let exit: ReturnType<typeof decodeExit>;
+
+    try {
+      exit = decodeExit(raw);
+    } catch (cause) {
+      throw new Error(
+        `RPC ${method.name} response decoding failed: ${formatCause(cause)}`
+      );
+    }
+
+    if (Exit.isSuccess(exit)) {
+      return exit.value;
+    }
+
+    const cause = exit.cause;
+    const failureOption = Cause.failureOption(cause);
+    if (failureOption._tag === "Some") {
+      throw failureOption.value;
+    }
+
+    const defectOption = Cause.dieOption(cause);
+    if (defectOption._tag === "Some") {
+      const defect = defectOption.value;
+      if (defect instanceof Error) {
+        throw new RpcDefectError(defect.message, defect);
+      }
+      throw new RpcDefectError(String(defect), defect);
+    }
+
+    throw new RpcDefectError(
+      "RPC call was interrupted or failed unexpectedly",
+      cause
+    );
+  };
+
+  const client: MutableRpcClient<RpcContract<Methods, Events>> =
+    Object.create(null);
+  const clientRecord: Record<string, unknown> = client;
+
+  contract.methods.forEach((method: Methods[number]) => {
+    const caller: RpcCaller<typeof method> = (
+      input?: RpcInput<typeof method>
+    ) => {
+      const payload = input ?? S.decodeUnknownSync(method.req)({});
+      return call(method, payload);
+    };
+
+    clientRecord[method.name] = caller;
+  });
+
+  return client;
+};
+
+export const createEventSubscriber = <
+  const Methods extends ReadonlyArray<AnyMethod>,
+  const Events extends ReadonlyArray<AnyEvent>
+>(
+  contract: RpcContract<Methods, Events>,
+  options?: EventSubscriberOptions
+): EventSubscriber<RpcContract<Methods, Events>> => {
+  const subscribe = requireSubscribe(options);
+  const eventMap = new Map<string, Events[number]>();
+
+  for (const event of contract.events) {
+    eventMap.set(event.name, event);
+  }
+
+  const subscribeEvent = <E extends Events[number]>(
+    event: E,
+    handler: (payload: RpcEventPayload<E>) => void
+  ) => {
+    const decoder = S.decodeUnknownSync(event.payload);
+    return subscribe(event.name, (payload) => {
+      const decoded = decoder(payload);
+      handler(decoded);
+    });
+  };
+
+  const subscribeByName = (
+    name: Events[number]["name"],
+    handler: (payload: unknown) => void
+  ) => {
+    const event = eventMap.get(name);
+    if (!event) {
+      throw new Error(`Unknown event: ${name}`);
+    }
+
+    const decoder = S.decodeUnknownSync(event.payload);
+    return subscribe(name, (payload) => handler(decoder(payload)));
+  };
+
+  return {
+    subscribe: subscribeEvent,
+    subscribeByName,
+  };
+};
+
+export { RpcDefectError } from "./types.ts";

package/src/testing.ts

@@ -0,0 +1,33 @@
+import type { RpcInvoke } from "./types.ts";
+
+export type Invocation = {
+  readonly method: string;
+  readonly payload: unknown;
+};
+
+export type InvokeStub = RpcInvoke & { readonly invocations: Invocation[] };
+
+export const createInvokeStub = (impl: RpcInvoke): InvokeStub => {
+  const invocations: Invocation[] = [];
+
+  const wrapped = Object.assign(
+    async (method: string, payload: unknown) => {
+      invocations.push({ method, payload });
+      return impl(method, payload);
+    },
+    { invocations }
+  );
+
+  return wrapped;
+};
+
+export const createDeferred = <T>() => {
+  let resolve: (value: T | PromiseLike<T>) => void = () => {};
+  let reject: (reason?: unknown) => void = () => {};
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return { promise, resolve, reject };
+};

package/src/types.ts

@@ -0,0 +1,134 @@
+import type * as Effect from "effect/Effect";
+import type * as Runtime from "effect/Runtime";
+import type { BrowserWindow } from "electron";
+import type {
+  AnyEvent,
+  AnyMethod,
+  ErrorSchema,
+  ExtractMethod,
+  RpcContract,
+  RpcError,
+  RpcEvent,
+  RpcEventPayload,
+  RpcInput,
+  RpcMethod,
+  RpcOutput,
+  SchemaNoContext,
+} from "./contract.ts";
+
+export type {
+  AnyEvent,
+  AnyMethod,
+  ErrorSchema,
+  ExtractMethod,
+  RpcContract,
+  RpcError,
+  RpcEvent,
+  RpcEventPayload,
+  RpcInput,
+  RpcMethod,
+  RpcOutput,
+  SchemaNoContext,
+} from "./contract.ts";
+
+export type Implementations<
+  C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[]>,
+  R = never
+> = {
+  readonly [Name in C["methods"][number]["name"]]: (
+    input: RpcInput<ExtractMethod<C["methods"], Name>>
+  ) => Effect.Effect<
+    RpcOutput<ExtractMethod<C["methods"], Name>>,
+    RpcError<ExtractMethod<C["methods"], Name>>,
+    R
+  >;
+};
+
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+
+export type RpcCaller<M extends AnyMethod> =
+  IsEmptyObject<RpcInput<M>> extends true
+    ? () => Promise<RpcOutput<M>>
+    : (input: RpcInput<M>) => Promise<RpcOutput<M>>;
+
+export type RpcClient<
+  C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[]>
+> = {
+  readonly [Name in C["methods"][number]["name"]]: RpcCaller<
+    ExtractMethod<C["methods"], Name>
+  >;
+};
+
+export class RpcDefectError extends Error {
+  readonly _tag = "RpcDefectError";
+
+  constructor(
+    message: string,
+    public readonly cause: unknown
+  ) {
+    super(message);
+    this.name = "RpcDefectError";
+  }
+}
+
+export type ChannelPrefix = {
+  readonly rpc: string;
+  readonly event: string;
+};
+
+export const defaultChannelPrefix: ChannelPrefix = {
+  rpc: "rpc/",
+  event: "event/",
+};
+
+export type IpcMainLike = {
+  readonly handle: (
+    channel: string,
+    listener: (event: unknown, payload: unknown) => unknown
+  ) => unknown;
+};
+
+export type RpcInvoke = (method: string, payload: unknown) => Promise<unknown>;
+
+/** Provide a Runtime when handlers require services (R). */
+export type RpcServerOptions<R = never> = {
+  readonly channelPrefix?: ChannelPrefix;
+  readonly runtime?: Runtime.Runtime<R>;
+};
+
+export type RpcClientOptions = {
+  readonly invoke?: RpcInvoke;
+  readonly channelPrefix?: ChannelPrefix;
+};
+
+export type EventBusOptions = {
+  readonly channelPrefix?: ChannelPrefix;
+  readonly getWindow: () => BrowserWindow | null;
+};
+
+export type EventSubscriberOptions = {
+  readonly channelPrefix?: ChannelPrefix;
+  readonly subscribe?: (name: string, handler: (payload: unknown) => void) => () => void;
+};
+
+export interface RpcEventBus<
+  C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[]>
+> {
+  readonly emit: <E extends C["events"][number]>(
+    event: E,
+    payload: RpcEventPayload<E>
+  ) => Effect.Effect<void, never>;
+}
+
+export interface EventSubscriber<
+  C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[]>
+> {
+  readonly subscribe: <E extends C["events"][number]>(
+    event: E,
+    handler: (payload: RpcEventPayload<E>) => void
+  ) => () => void;
+  readonly subscribeByName: (
+    name: C["events"][number]["name"],
+    handler: (payload: unknown) => void
+  ) => () => void;
+}