async-call-rpc JSON RPC Client & Server

Common errors

• TypeError: AsyncCall is not a constructor

  cause Attempting to use `require` or incorrect default import syntax for a package primarily designed for ES Modules, or incorrect access in a UMD context.
  fix Use a named ESM import: `import { AsyncCall } from 'async-call-rpc';`. If in a browser UMD context, access via `const { AsyncCall } = globalThis.AsyncCall;`.

• Property 'serializer' is deprecated and will be removed in a future major release.

  cause Using the deprecated `serializer` option in the `AsyncCall` constructor.
  fix Refactor your code to use the `encoder` option instead. Replace `serializer.serialization` with `encoder.encode` and `serializer.deserialization` with `encoder.decode`.

• Cannot find name 'AsyncGeneratorCall' or 'AsyncGeneratorCall' is not defined.

  cause Attempting to import `AsyncGeneratorCall` from the default 'async-call-rpc' entry point, or the runtime environment lacks async generator support.
  fix Import `AsyncGeneratorCall` specifically from the full entry point: `import { AsyncGeneratorCall } from 'async-call-rpc/full';`. Ensure your JavaScript environment targets ES2018 or higher.

Warnings

• breaking The `serializer` option in AsyncCall constructor has been deprecated and replaced by the `encoder` option. Custom serialization logic needs to be migrated.
  Fix: Migrate your `serializer` option to the new `encoder` option. The `serialization(data)` and `deserialization(data)` methods should be renamed to `encode(data)` and `decode(data)` respectively.
• gotcha Async generator support in `async-call-rpc` can lead to memory leaks on the server side if not handled carefully.
  Fix: Exercise caution when using async generators, especially in long-running server processes. Monitor memory usage and implement proper resource management and cleanup for async generator streams.
• breaking This package ships with ECMAScript 2018 syntax (`async function`) and does not support ES5 environments or JSON RPC 1.0.
  Fix: Ensure your runtime environment supports ES2018 or newer. If targeting older browsers, transpile your code with a tool like Babel. Avoid using JSON RPC 1.0.
• gotcha When installing via JSR (e.g., Deno, Bun), the import path for `async-call-rpc` changes from `'async-call-rpc'` to `'@works/json-rpc'`. Additionally, the `utils/` entrypoint is not published on JSR.
  Fix: Adjust your import statements based on your package manager: `import { AsyncCall } from 'async-call-rpc'` for npm/yarn/pnpm, and `import { AsyncCall } from '@works/json-rpc'` for jsr users.

Install

• npm install async-call-rpc npm
• yarn add async-call-rpc yarn
• pnpm add async-call-rpc pnpm

Imports

• AsyncCall
  wrong:

  const AsyncCall = require('async-call-rpc');

  correct:

  import { AsyncCall } from 'async-call-rpc';

  Use named import for ESM. CommonJS `require` is not officially supported and may lead to issues or require specific bundler configurations. For Deno/Bun via JSR, import from '@works/json-rpc'.
• AsyncGeneratorCall
  wrong:

  import { AsyncGeneratorCall } from 'async-call-rpc';

  correct:

  import { AsyncGeneratorCall } from 'async-call-rpc/full';

  AsyncGeneratorCall is part of the 'full' entry point, not the default base entry point. Ensure your environment supports async generators.
• Encoder
  wrong:

  import { Encoder } from 'async-call-rpc';

  correct:

  import type { Encoder } from 'async-call-rpc';

  When using `Encoder` as a type for type annotations, `import type` is preferred to avoid bundling unused runtime code if not implemented as an actual class.

Quickstart

This quickstart demonstrates how to set up a basic in-memory JSON RPC client and server using `async-call-rpc`, define a simple API, and make remote procedure calls.

import { AsyncCall } from 'async-call-rpc';

// Define a simple in-memory channel for demonstration
class InMemoryChannel {
    private clientSend?: (data: string) => void;
    private serverSend?: (data: string) => void;

    // Simulate client sending to server
    clientChannel = {
        send: (data: string) => {
            if (this.serverSend) {
                this.serverSend(data);
            }
        },
        on: (cb: (data: string) => void) => {
            this.clientSend = cb;
        }
    };

    // Simulate server sending to client
    serverChannel = {
        send: (data: string) => {
            if (this.clientSend) {
                this.clientSend(data);
            }
        },
        on: (cb: (data: string) => void) => {
            this.serverSend = cb;
        }
    };
}

const channel = new InMemoryChannel();

// Define the server API interface
interface MyServerAPI {
    add(a: number, b: number): Promise<number>;
    greet(name: string): Promise<string>;
}

// Server implementation
const serverImpl: MyServerAPI = {
    async add(a, b) {
        console.log(`Server received: add(${a}, ${b})`);
        return a + b;
    },
    async greet(name) {
        console.log(`Server received: greet('${name}')`);
        return `Hello, ${name}!`;
    }
};

// Create the RPC server instance
const server = new AsyncCall(serverImpl, { channel: channel.serverChannel });

// Create the RPC client instance (null for `thisSideImplementation` means it's purely a client)
const client = new AsyncCall<MyServerAPI>(null, { channel: channel.clientChannel });

// Use the client to call server methods
async function runClient() {
    console.log('Client calling add(5, 3)');
    const resultAdd = await client.add(5, 3);
    console.log('Result of add(5, 3):', resultAdd); // Expected: 8

    console.log('Client calling greet("World")');
    const resultGreet = await client.greet('World');
    console.log('Result of greet("World"):', resultGreet); // Expected: "Hello, World!"

    // Clean up server (optional, for explicit shutdown)
    server.stop();
}

runClient().catch(console.error);