Skip to main content

TypeScript SDK

This guide documents both Flux TypeScript SDK layers:

  1. low-level protocol client (FLUXClient)
  2. high-level runtime API for producer/consumer workflows

Package Location​

packages/sdk/typescript

Install​

pnpm add ../../packages/sdk/typescript

Or after publish:

pnpm add @flux/typescript-sdk

Build​

cd packages/sdk/typescript
pnpm install
pnpm run build

Use FLUXClient for direct control.

import { FLUXClient } from '@flux/typescript-sdk';

const client = new FLUXClient({ host: '127.0.0.1', port: 9092 });
await client.connect();

await client.produce('orders', 'user1', 'created', '1');

const join = await client.join('analytics', 'orders', 'consumer-a', 'round_robin');
const sync = await client.sync('analytics', 'orders', 'consumer-a', join.generation);

for (const partition of sync.assigned) {
  const start = await client.offset('analytics', 'orders', partition);
  const messages = await client.consume('orders', partition, start);
  if (messages.length > 0) {
    const next = messages[messages.length - 1].offset + 1;
    await client.commit('analytics', 'orders', 'consumer-a', sync.generation, partition, next);
  }
}

await client.leave('analytics', 'orders', 'consumer-a', sync.generation);
await client.close();

Admin Control-Plane APIs (Operator/Platform Flow)​

Use these methods to manage control-plane metadata from platform/operator tooling. For regular app runtime code paths, keep to producer/consumer and group lifecycle APIs.

  • adminCreateTopic(topic, partitions, replicationFactor)
  • adminRegisterBroker(brokerId, host, port, epoch?)
  • adminBrokerHeartbeat(brokerId)
  • adminSetPartitionLeader(topic, partition, leaderId, isr)
  • adminGetMetadata()

Example:

import { FLUXClient } from '@flux/typescript-sdk';

const client = new FLUXClient({ host: '127.0.0.1', port: 9092 });
await client.connect();

await client.adminCreateTopic('payments', 3, 2);
await client.adminRegisterBroker(1, '127.0.0.1', 9093);
await client.adminBrokerHeartbeat(1);
await client.adminSetPartitionLeader('payments', 0, 0, [0, 1]);

const metadata = await client.adminGetMetadata();
console.log('metadata snapshot', metadata);

await client.close();

Low-Level API (FLUXClient)​

  • connect(), close()
  • produce(), consume()
  • join(), sync(), heartbeat(), leave()
  • commit(), offset()
  • replicaFetch(), setPartitionRole()
  • adminCreateTopic(), adminRegisterBroker(), adminBrokerHeartbeat()
  • adminSetPartitionLeader(), adminGetMetadata()

Error Handling​

Protocol errors throw FLUXProtocolError with:

  • code
  • message
  • parsed response

Important codes:

  • BAD_REQUEST
  • UNKNOWN_COMMAND
  • NOT_LEADER
  • REPLICATION_TIMEOUT
  • GENERATION_MISMATCH

Runnable Example​

packages/sdk/typescript/examples/basic-usage.ts

Run it:

cd packages/sdk/typescript
pnpm install
pnpm run build
npx tsc --module commonjs --target es2020 --outDir examples/dist examples/basic-usage.ts
node examples/dist/basic-usage.js

Admin example:

packages/sdk/typescript/examples/admin-usage.ts
cd packages/sdk/typescript
npx tsc --module commonjs --target es2020 --outDir examples/dist examples/admin-usage.ts
node examples/dist/admin-usage.js

Notes on Runtime Metadata Behavior​

The current Flux broker runtime now integrates with control-plane metadata on hot paths:

  • produce/consume paths read partition context from controller metadata snapshots
  • runtime can bootstrap missing topic metadata (EnsureTopicMetadata) to keep protocol flows operable while Phase 4 matures
  • this is an intentional bridge from local state assumptions toward quorum-backed metadata authority