@nexus-js/node-ipc

@nexus-js/node-ipc is the Nexus adapter for local daemon/client IPC over filesystem Unix domain sockets.

For the product guide, read docs/node-ipc/README.md from the repository root. This package README is a short reference for installation, exports, and the minimum setup shape.

Install

pnpm add @nexus-js/core @nexus-js/node-ipc

Exports

Factory helpers:

• usingNodeIpcDaemon(options)
• usingNodeIpcClient(options)

Matcher helpers:

• daemon(appId)
• client(appId)
• instance(name)
• group(name)

Public types and errors:

• NodeIpcError
• NodeIpcErrorCode
• NodeIpcAddress
• NodeIpcAddressResolver
• NodeIpcSocketAddress
• NodeIpcEndpointMeta
• NodeIpcDaemonMeta
• NodeIpcClientMeta
• NodeIpcPlatformMeta
• factory option types

Minimal Daemon

import { nexus } from "@nexus-js/core";
import { usingNodeIpcDaemon } from "@nexus-js/node-ipc";
import { EchoToken } from "./shared";

usingNodeIpcDaemon({ appId: "example-app" }).provide(EchoToken, {
  async echo(input) {
    return `echo:${input}`;
  },
});

Minimal Client

import { nexus } from "@nexus-js/core";
import { usingNodeIpcClient } from "@nexus-js/node-ipc";
import { EchoToken } from "./shared";

usingNodeIpcClient({
  appId: "example-app",
  connectTo: [
    {
      descriptor: { context: "node-ipc-daemon", appId: "example-app" },
    },
  ],
});

const echo = await nexus.create(EchoToken);

console.log(await echo.echo("hello"));

Runtime Notes

• Default socket path: $XDG_RUNTIME_DIR/nexus/<appId>/<instance>.sock
• Fallback socket path: /tmp/nexus-<uid>/<appId>/<instance>.sock
• instance defaults to default
• Shared-secret pre-auth is optional and configured with authToken
• Core policy.canConnect and policy.canCall remain the authorization authority after pre-auth
• create(EchoToken) requires a token defaultTarget or a unique connectTo fallback; use explicit target plus expects for complex daemon topologies
• Proxies and refs are session-bound; recreate them after daemon restart or disconnect

Error Codes

• E_IPC_ADDRESS_INVALID
• E_IPC_ADDRESS_IN_USE
• E_IPC_PATH_TOO_LONG
• E_IPC_CONNECT_FAILED
• E_IPC_AUTH_FAILED
• E_IPC_PROTOCOL_ERROR
• E_IPC_STALE_SOCKET_CLEANUP_FAILED

Tests

pnpm --filter @nexus-js/node-ipc test