Type-safe IPC for Electron. Define once. Infer everywhere.

import { defineApi, defineEvent, defineInvoke } from '@cc-heart/electron-use-ipc'

export interface User {
  id: string
  name: string
}

/**
 * Single source of truth: define the contract once.
 * Every arg / return / payload type flows from here to main, preload, renderer.
 */
export const api = defineApi({
  invoke: {
    getUser: defineInvoke<[string], User>(),
    listUsers: defineInvoke<[], User[]>(),
    createUser: defineInvoke<[string], User>(),
  },
  events: {
    'user:updated': defineEvent<User>(),
    'server:shutdown': defineEvent<void>(),
  },
})

import { registerMain } from '@cc-heart/electron-use-ipc/main'
import { api, type User } from './shared/api'

const users = new Map<string, User>()

// `main` is captured by closures below; declare first so handlers can emit.
const main = registerMain(api, {
  invoke: {
    // (id: string) => Promise<User>  — inferred from the token
    getUser: async (id) => {
      const u = users.get(id)
      if (!u) throw new Error(`no user ${id}`)
      return u
    },
    // () => Promise<User[]>
    listUsers: async () => [...users.values()],
    // (name: string) => Promise<User>
    createUser: async (name) => {
      const u: User = { id: crypto.randomUUID(), name }
      users.set(u.id, u)
      // typed event broadcast: payload must be User
      main.emit(api.events['user:updated'], u)
      return u
    },
  },
})

// void event: no payload allowed
main.emit(api.events['server:shutdown'])

main.dispose()

import { exposeBridge } from '@cc-heart/electron-use-ipc/preload'
import { api } from './shared/api'

// exposes window.api with the typed bridge
exposeBridge(api)

import { useEvent, useInvoke } from '@cc-heart/electron-use-ipc/renderer'
import { api } from './shared/api'

/* ---- request / response hook ---- */
const { data, loading, call } = useInvoke(api.invoke.getUser)
//    call: (id: string) => Promise<User>     ✅ inferred
//    data: Signal<User | undefined>          ✅ inferred

call('1').then(() => {
  const u = data.get() // User | undefined
  console.log(u?.name)
})

data.subscribe((u) => {
  // u: User | undefined
})

/* ---- immediate call (args still typed) ---- */
const list = useInvoke(api.invoke.listUsers, { immediate: [] })
//    list.data: Signal<User[] | undefined>

/* ---- event hook ---- */
const updated = useEvent(api.events['user:updated'])
//    updated: Signal<User | undefined>       ✅ inferred

updated.subscribe((u) => {
  if (u) console.log('updated:', u.name)
})

/* ---- compile-time type checks (uncomment to see errors) ---- */
// call(123)                              // ❌ Argument of type 'number'...
// main.emit(api.events['user:updated'])  // ❌ void-typed event still works, but
//   // a non-void event without payload errors. (void events allow no-arg emit)
// updated.subscribe((u: number) => {})   // ❌ u is User | undefined

/**
 * BEFORE — the same feature wired by hand.
 *
 * This file is illustrative content for the landing page, not
 * compiled. It is kept as a real file so it highlights from
 * source like every other snippet.
 *
 * Three files, three chances to drift: the channel name is a
 * bare string, the payload types are restated at each boundary,
 * and nothing connects them.
 */

// ── main.ts ─────────────────────────
import { ipcMain } from 'electron'

ipcMain.handle('get-user', async (_event, id) => {
  // `id` is `any` here — the cast is a promise, not a check
  return db.users.get(id as string)
})

// ── preload.ts ──────────────────────
import { contextBridge, ipcRenderer } from 'electron'

contextBridge.exposeInMainWorld('api', {
  getUser: (id: string) => ipcRenderer.invoke('get-user', id),
  onUserUpdated: (cb: (user: User) => void) =>
    ipcRenderer.on('user:updated', (_e, user) => cb(user)),
})

// ── renderer.ts ─────────────────────
interface User {
  id: string
  name: string
}

// cast it and hope
const user = (await window.api.getUser('1')) as User
// `any` all the way down
window.api.onUserUpdated((u: any) => console.log(u.name))

// Negative test: each @ts-expect-error must be "used" (i.e. a real error occurs).
// If tsc passes, the types are BOTH correct (positive cases) AND strict
// (these bad cases really error). If an @ts-expect-error becomes unused,
// that line leaked `any`.
import { useEvent, useInvoke } from '@cc-heart/electron-use-ipc/renderer'
import { api } from './shared/api'

const { call } = useInvoke(api.invoke.getUser)
// @ts-expect-error number is not assignable to string
call(123)

const updated = useEvent(api.events['user:updated'])
// @ts-expect-error payload is User | undefined, not number
updated.subscribe((u: number) => {})