Binding · TypeScript (Node.js)

TypeScript (Node.js) — in 5 Minuten zum ersten Sample

Full DCPS + WebSocket/gRPC-Bridge-Plumbing für Node.js. FFI über koffi gegen die C-API in libzerodds. Strict TypeScript, no any. IDL→TS-Codegen via zerodds-idlc generate --lang typescript.

Node.js: 20 oder höher Install: npm install @zerodds/node@rc TypeScript: strict, kein any

5-Minuten-Quickstart

1 · Node-Binding installieren

@zerodds/node ist auf npm. Das Paket ist reines TypeScript und lädt libzerodds über koffi; die native Bibliothek ist nicht im Paket.

Schritt 1a: libzerodds Runtime (pre-built oder Source):

# Ubuntu/Debian (amd64; arm64: _arm64.deb)
wget https://github.com/zero-objects/zero-dds/releases/download/v1.0.0-rc.7/zerodds-core_1.0.0-rc.7_amd64.deb
sudo dpkg -i zerodds-core_1.0.0-rc.7_amd64.deb
# Fedora/RHEL: die RPMs von rc.7 lassen sich nicht installieren (zerodds-core verlangt libzerodds.so()(64bit), das kein Paket bereitstellt); aus der Quelle bauen, siehe User Guide
# Arch:  yay -S zerodds-bin
# macOS, Windows: libzerodds ist in keinem vorgebauten Paket (.pkg, MSI und Zip enthalten nur die Programme); aus dem Source bauen:
#   git clone https://github.com/zero-objects/zero-dds.git
#   cd zero-dds && cargo build --release -p zerodds-c-api

Die Bibliothek wird zuerst unter dem Pfad in ZERODDS_LIB gesucht, zuletzt in den Standardpfaden des Systems.

Schritt 1b: Projekt anlegen, Binding von npm:

mkdir zerodds-hello && cd zerodds-hello
npm init -y
npm install @zerodds/node@1.0.0-rc.7 typescript tsx
npx tsc --init

2 · Pub/Sub-Roundtrip (hello.ts)

import { DomainParticipantFactory } from '@zerodds/node';

async function main() {
    const factory = DomainParticipantFactory.instance();
    const participant = factory.createParticipant(0);

    const topic = participant.createBytesTopic('Chatter');
    const publisher = participant.createPublisher();
    const subscriber = participant.createSubscriber();

    const writer = publisher.createBytesWriter(topic);
    const reader = subscriber.createBytesReader(topic);

    await writer.waitForMatchedSubscription(1, 5000);
    await reader.waitForMatchedPublication(1, 5000);

    writer.write(new TextEncoder().encode('hello'));
    await reader.waitForData(3000);

    for (const sample of reader.take()) {
        console.log('got:', new TextDecoder().decode(sample));
    }
}

main().catch(console.error);

▶ Runnable example: typescript-node-quickstart

3 · Laufen

npx tsx hello.ts
# got: hello

Installation

npm

npm install @zerodds/node@1.0.0-rc.7
# zieht @zerodds/wire (XCDR-Codec des erzeugten Codes) mit; libzerodds kommt aus den Systempaketen

Aus dem Source

git clone https://github.com/zero-objects/zero-dds.git
cd zero-dds
cargo build --release -p zerodds-c-api   # libzerodds, die koffi lädt
cd crates/ts-node
npm install
npm run build      # tsc
npm test

Voraussetzungen

  • Node.js 20 oder höher (engines in package.json).
  • npm 9+ (für Workspace-fähigen Install).
  • libzerodds für die Plattform, aus den Systempaketen oder aus dem Source.
  • Bei Build aus Source: Rust 1.97+ für libzerodds (siehe Dev-Install).

Typisierte Topics — zerodds-idlc generate --lang typescript

# IDL
echo 'module sensor_msgs { module msg { struct Temperature { long celsius; string sensor_id; }; }; };' > temperature.idl
zerodds-idlc generate --lang typescript --out gen/ temperature.idl
# schreibt gen/temperature.ts: IDL-Module als Namespaces, je Typ ein interface und eine TypeSupport
// Nutzen
import { sensor_msgs } from './gen/temperature';

// IDL-Module sind Namespaces
const { TemperatureTypeSupport } = sensor_msgs.msg;
type Temperature = sensor_msgs.msg.Temperature;

const topic = participant.createTypedTopic('Temp', TemperatureTypeSupport);
const writer = publisher.createTypedWriter(topic);
await writer.write({ celsius: 23, sensor_id: 'A7' } satisfies Temperature);

▶ Runnable example: typescript-node-typed

async/await

Alle blocking Calls (wait_for_*, write_async, take_async) liefern Promise. CommonJS- + ESM-Builds.

await writer.writeAsync(payload);
const samples = await reader.takeAsync();
for await (const sample of reader.streamSamples()) {
    handle(sample);
}

▶ Runnable example: typescript-node-async

Binding · TypeScript (Node.js)

TypeScript (Node.js) — first sample in 5 minutes

Full DCPS + WebSocket/gRPC bridge plumbing for Node.js. FFI through koffi against the C API in libzerodds. Strict TypeScript, no any. IDL→TS codegen via zerodds-idlc generate --lang typescript.

Node.js: 20 or higher Install: npm install @zerodds/node@rc TypeScript: strict, no any

5-minute quickstart

1 · Install the Node binding

@zerodds/node is on npm. The package is pure TypeScript and loads libzerodds through koffi; the native library is not in the package.

Step 1a: the libzerodds runtime (pre-built or source):

# Ubuntu/Debian (amd64; arm64: _arm64.deb)
wget https://github.com/zero-objects/zero-dds/releases/download/v1.0.0-rc.7/zerodds-core_1.0.0-rc.7_amd64.deb
sudo dpkg -i zerodds-core_1.0.0-rc.7_amd64.deb
# Fedora/RHEL: the rc.7 RPMs cannot be installed (zerodds-core requires libzerodds.so()(64bit), which no package provides); build from source, see the User Guide
# Arch:  yay -S zerodds-bin
# macOS, Windows: libzerodds is in no pre-built package (.pkg, MSI and zip carry only the programs); build it from source:
#   git clone https://github.com/zero-objects/zero-dds.git
#   cd zero-dds && cargo build --release -p zerodds-c-api

The library is looked up first at the path in ZERODDS_LIB, last in the system’s default paths.

Step 1b: create the project, the binding from npm:

mkdir zerodds-hello && cd zerodds-hello
npm init -y
npm install @zerodds/node@1.0.0-rc.7 typescript tsx
npx tsc --init

2 · Pub/sub roundtrip (hello.ts)

import { DomainParticipantFactory } from '@zerodds/node';

async function main() {
    const factory = DomainParticipantFactory.instance();
    const participant = factory.createParticipant(0);

    const topic = participant.createBytesTopic('Chatter');
    const publisher = participant.createPublisher();
    const subscriber = participant.createSubscriber();

    const writer = publisher.createBytesWriter(topic);
    const reader = subscriber.createBytesReader(topic);

    await writer.waitForMatchedSubscription(1, 5000);
    await reader.waitForMatchedPublication(1, 5000);

    writer.write(new TextEncoder().encode('hello'));
    await reader.waitForData(3000);

    for (const sample of reader.take()) {
        console.log('got:', new TextDecoder().decode(sample));
    }
}

main().catch(console.error);

▶ Runnable example: typescript-node-quickstart

3 · Run

npx tsx hello.ts
# got: hello

Installation

npm

npm install @zerodds/node@1.0.0-rc.7
# pulls in @zerodds/wire (the XCDR codec of the generated code); libzerodds comes from the system packages

From source

git clone https://github.com/zero-objects/zero-dds.git
cd zero-dds
cargo build --release -p zerodds-c-api   # libzerodds, which koffi loads
cd crates/ts-node
npm install
npm run build      # tsc
npm test

Prerequisites

  • Node.js 20 or higher (engines in package.json).
  • npm 9+ (for a workspace-capable install).
  • libzerodds for the platform, from the system packages or from source.
  • For a build from source: Rust 1.97+ for libzerodds (see Dev Install).

Typed topics — zerodds-idlc generate --lang typescript

# IDL
echo 'module sensor_msgs { module msg { struct Temperature { long celsius; string sensor_id; }; }; };' > temperature.idl
zerodds-idlc generate --lang typescript --out gen/ temperature.idl
# writes gen/temperature.ts: IDL modules as namespaces, per type an interface and a TypeSupport
// use it
import { sensor_msgs } from './gen/temperature';

// IDL modules are namespaces
const { TemperatureTypeSupport } = sensor_msgs.msg;
type Temperature = sensor_msgs.msg.Temperature;

const topic = participant.createTypedTopic('Temp', TemperatureTypeSupport);
const writer = publisher.createTypedWriter(topic);
await writer.write({ celsius: 23, sensor_id: 'A7' } satisfies Temperature);

▶ Runnable example: typescript-node-typed

async/await

All blocking calls (wait_for_*, write_async, take_async) return a Promise. CommonJS + ESM builds.

await writer.writeAsync(payload);
const samples = await reader.takeAsync();
for await (const sample of reader.streamSamples()) {
    handle(sample);
}

▶ Runnable example: typescript-node-async