Skip to main content

@livon/client

npm CI Vulnerability scan OpenSSF Scorecard OpenSSF Best Practices REUSE status license

Purpose​

@livon/client provides deterministic client interface execution and generated-client foundations.

Best for​

Use this package when frontend apps consume generated LIVON APIs and typed subscription handlers.

Exports include:

  • createClient
  • createClientModule
  • clientModule

Generator sync policy​

Generated client surfaces and hover docs are built from the client generator. When generator output changes, docs must be updated in sync.

Current generated typing behavior to keep in sync:

  • and(...) schema nodes are emitted as TypeScript intersections (Left & Right).
  • If schema composition passes an explicit name, that name is used as the generated type name.

Central TypeScript surface template​

Generated interface and signature syntax is centralized in:

  • packages/client/src/typeScriptSurfaceTemplate.ts

Use this file when TypeScript surface style should change globally (for example interface member syntax, callable signatures, or method/property signature formatting). This avoids editing many render call sites in packages/client/src/generate.ts.

Install​

pnpm add @livon/client

Runtime wiring (generated API path)​

import {runtime} from '@livon/runtime';
import {clientWsTransport} from '@livon/client-ws-transport';
import {api} from './generated/api';

runtime(
  clientWsTransport({url: 'ws://127.0.0.1:3002/ws'}),
  api,
);

Parameters in this example​

clientWsTransport({...}):

  • url (string): websocket endpoint used by client transport.

runtime(transport, api):

  • transport (RuntimeModule): client transport module.
  • api (RuntimeModule): generated client module built from server schema.

Subscription handling pattern​

api({
  onMessage: (payload, ctx) => {
    payload.text;
    ctx.state.get('lastMessage');
  },
});

api.onMessage.off();

Parameters in this example​

api({...}):

  • onMessage ((payload, ctx) => void): typed subscription callback.
  • payload (in callback): generated payload type from server schema.
  • ctx (in callback): runtime context for state/emit/room access.

api.onMessage.off():

  • no parameters; disables one subscription callback stream.

Room-scoped handlers​

api.room('global')({
  onMessage: (payload) => {
    payload.text;
  },
});

Parameters in this example​

api.room(roomId):

  • roomId (string): room selector for scoped schema handling.

api.room(... )({...}):

  • onMessage ((payload) => void): room-scoped subscription callback.

Low-level client module​

import {createClientModule} from '@livon/client';
import {runtime} from '@livon/runtime';

const module = createClientModule({ast});
runtime(transport, module);

Parameters in this example​

createClientModule({...}):

  • ast (AstNode): schema AST used to build executable client interface module.