ros-strongtypes

"Production has a way of teaching humility."

ros-strongtypes is a "boring solution" to a chaotic problem: Managing Mikrotik RouterOS devices programmatically without blowing things up. It enforces strict type safety and runtime validation at the network edge, turning unpredictable API responses into reliable, typed objects.

The Problem

RouterOS APIs are powerful but loosely typed. A string can be an IP address, a MAC address, or an interface name. A command path can be constructed incorrectly. When managing critical network infrastructure, these "clever" dynamicisms are liabilities.

We don't want "clever" code that guesses what the router meant. We want code that knows exactly what it's dealing with; otherwise, it crashes loudly (Fail-Fast) before applying a broken config.

The Solution

This library is built on honest constraints:

1. Nominal Typing (Branded Types): An IPAddress is not just a string. You cannot accidentally pass a MAC address to a function expecting an IP.
2. Runtime Integrity (Validation Barrier): All data entering the system is treated as "hostile" until validated against strict Zod schemas.
3. Fluent, Predictable API: A query builder that guides you down valid command paths (.ip().address()) and restricts you from invalid ones.

Architecture

We favor explicit design over implicit magic.

• Architecture.md: A deep dive into the four pillars of the library (Branded Types, Validation Barrier, Query Builder, Observable Sync).
• Architecture.md: A deep dive into the four pillars of the library (Branded Types, Validation Barrier, Query Builder, Observable Sync).
• API Reference: Run npm run docs locally to generate and view the full API documentation in docs/html.

Installation

# Install directly from GitHub
npm install github:engnhn/ros-strongtypes

# Or clone and build locally
git clone https://github.com/engnhn/ros-strongtypes.git
cd ros-strongtypes
npm install
npm run build

Usage

1. Basic Integration

(See examples/basic-usage.ts for a runnable script)

import { RootContext, IRouterClient } from 'ros-strongtypes';

// Bring your own low-level client (e.g., node-routeros, axios, ssh2)
const client: IRouterClient = new MyLowLevelClient();
const app = client.query(); // Preferred typed entry point

// Type-safe command construction
// The compiler guarantees you can't access .ethernet() under .ip()
await app.interface().ethernet().print();

// v1.1.0: Expanded Query Verbs
await app.interface().ethernet().disable('*1');
await app.ip().firewall().filter().add({ 
    chain: 'input', 
    action: 'drop', 
    'src-address': '10.0.0.5' 
});

2. Live State Monitoring

Network state is a stream, not a snapshot.

app.interface().ethernet().watch().subscribe(interfaces => {
    const ether1 = interfaces.find(i => i.name === 'ether1');
    if (ether1) console.log(`Traffic: ${ether1['rx-byte']} bytes`);
});

3. Expanded Coverage (v1.1.0)

The library now supports typed contexts for:

• IP Firewall: Filter, NAT, and Address-Lists.
• DHCP Server: Servers and Leases.
• System Identity: Manage device name safely.

Development

I write code, break it, and then fix it. Here's how to do the same:

# Install dependencies
npm install

# Run Unit Tests (Vitest)
npm test

# Build the project
npm run build

Contributing

Complexity is the enemy. Keep PRs simple, boring, and robust.

License

MIT