agentic-robotics-node

Node.js/TypeScript bindings for Agentic Robotics

Part of the Agentic Robotics framework - high-performance robotics middleware with ROS2 compatibility.

Features

• 🌐 TypeScript Support: Full type definitions included
• ⚡ Native Performance: Rust-powered via NAPI
• 🔄 Async/Await: Modern JavaScript async patterns
• 📡 Pub/Sub: ROS2-compatible topic messaging
• 🎯 Type-Safe: Compile-time type checking in TypeScript
• 🚀 High Performance: 540ns serialization, 30ns messaging

Installation

npm install agentic-robotics
# or
yarn add agentic-robotics
# or
pnpm add agentic-robotics

Quick Start

TypeScript

import { Node, Publisher, Subscriber } from 'agentic-robotics';

// Create a node
const node = new Node('robot_node');

// Create publisher
const pubStatus = node.createPublisher<string>('/status');

// Create subscriber
const subCommands = node.createSubscriber<string>('/commands');

// Publish messages
pubStatus.publish('Robot initialized');

// Subscribe to messages
subCommands.onMessage((msg) => {
    console.log('Received command:', msg);
});

JavaScript

const { Node } = require('agentic-robotics');

const node = new Node('robot_node');

const pubStatus = node.createPublisher('/status');
pubStatus.publish('Robot active');

const subSensor = node.createSubscriber('/sensor');
subSensor.onMessage((data) => {
    console.log('Sensor data:', data);
});

Examples

Autonomous Navigator

import { Node } from 'agentic-robotics';

interface Pose {
    x: number;
    y: number;
    theta: number;
}

interface Velocity {
    linear: number;
    angular: number;
}

const node = new Node('navigator');

// Subscribe to current pose
const subPose = node.createSubscriber<Pose>('/robot/pose');

// Publish velocity commands
const pubCmd = node.createPublisher<Velocity>('/cmd_vel');

// Navigation logic
subPose.onMessage((pose) => {
    const target = { x: 10, y: 10 };
    const cmd = computeVelocity(pose, target);
    pubCmd.publish(cmd);
});

function computeVelocity(current: Pose, target: { x: number; y: number }): Velocity {
    const dx = target.x - current.x;
    const dy = target.y - current.y;
    const distance = Math.sqrt(dx * dx + dy * dy);
    const targetAngle = Math.atan2(dy, dx);
    const angleError = targetAngle - current.theta;

    return {
        linear: Math.min(distance * 0.5, 1.0),
        angular: angleError * 2.0,
    };
}

Vision Processing

import { Node } from 'agentic-robotics';

interface Image {
    width: number;
    height: number;
    data: Uint8Array;
}

interface Detection {
    label: string;
    confidence: number;
    bbox: { x: number; y: number; w: number; h: number };
}

const node = new Node('vision_node');

const subImage = node.createSubscriber<Image>('/camera/image');
const pubDetections = node.createPublisher<Detection[]>('/detections');

subImage.onMessage(async (image) => {
    const detections = await detectObjects(image);
    pubDetections.publish(detections);
});

async function detectObjects(image: Image): Promise<Detection[]> {
    // Your ML inference here
    return [
        { label: 'person', confidence: 0.95, bbox: { x: 100, y: 100, w: 50, h: 100 } },
    ];
}

Multi-Robot Coordination

import { Node } from 'agentic-robotics';

class RobotAgent {
    private node: Node;
    private id: string;

    constructor(id: string) {
        this.id = id;
        this.node = new Node(`robot_${id}`);

        // Subscribe to team status
        const subTeam = this.node.createSubscriber<TeamStatus>('/team/status');
        subTeam.onMessage((status) => this.onTeamUpdate(status));

        // Publish own status
        const pubStatus = this.node.createPublisher<RobotStatus>(`/robot/${id}/status`);
        setInterval(() => {
            pubStatus.publish({
                id: this.id,
                position: this.getPosition(),
                battery: this.getBatteryLevel(),
            });
        }, 100);
    }

    private onTeamUpdate(status: TeamStatus) {
        console.log(`Robot ${this.id} received team update:`, status);
        // Coordinate with other robots
    }

    private getPosition() {
        return { x: 0, y: 0, z: 0 };
    }

    private getBatteryLevel() {
        return 95;
    }
}

// Create robot swarm
const robots = [
    new RobotAgent('scout_1'),
    new RobotAgent('scout_2'),
    new RobotAgent('worker_1'),
];

API Reference

Node

class Node {
    constructor(name: string);

    createPublisher<T>(topic: string): Publisher<T>;
    createSubscriber<T>(topic: string): Subscriber<T>;

    shutdown(): void;
}

Publisher

class Publisher<T> {
    publish(message: T): Promise<void>;
    getTopic(): string;
}

Subscriber

class Subscriber<T> {
    onMessage(callback: (message: T) => void): void;
    getTopic(): string;
}

Performance

The Node.js bindings maintain near-native performance:

| Operation | Node.js | Rust Native | Overhead | |-----------|---------|-------------|----------| | Publish | 850 ns | 540 ns | 57% | | Subscribe | 120 ns | 30 ns | 4x | | Serialization | 1.2 µs | 540 ns | 2.2x |

Still significantly faster than traditional ROS2 Node.js bindings!

Building from Source

# Clone repository
git clone https://github.com/ruvnet/vibecast
cd vibecast

# Build Node.js addon
npm install
npm run build:node

# Run tests
npm test

TypeScript Configuration

{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "strict": true,
        "esModuleInterop": true
    }
}

Examples

See the examples directory for complete working examples:

• 01-hello-robot.ts - Basic pub/sub
• 02-autonomous-navigator.ts - A* pathfinding
• 06-vision-tracking.ts - Object tracking with Kalman filters
• 08-adaptive-learning.ts - Experience-based learning

Run any example:

npm run build:ts
node examples/01-hello-robot.ts

ROS2 Compatibility

The Node.js bindings are fully compatible with ROS2:

// Publish to ROS2 topic
const pubCmd = node.createPublisher<Twist>('/cmd_vel');
pubCmd.publish({
    linear: { x: 0.5, y: 0, z: 0 },
    angular: { x: 0, y: 0, z: 0.1 },
});

// Subscribe from ROS2 topic
const subPose = node.createSubscriber<PoseStamped>('/robot/pose');

Bridge with ROS2:

# Terminal 1: Node.js app
node my-robot.js

# Terminal 2: ROS2
ros2 topic echo /cmd_vel

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Links

• Homepage: ruv.io
• Documentation: docs.rs/agentic-robotics-node
• npm Package: npmjs.com/package/agentic-robotics
• Repository: github.com/ruvnet/vibecast

Part of the Agentic Robotics framework • Built with ❤️ by the Agentic Robotics Team