@nan0web/interface

The interface package provides a thin abstraction layer for building interactive command‑line tools. It ships with:

• CLIInterface – low‑level I/O wrapper.
• InterfaceCore – protocol dispatcher.
• createCLIInterface – factory that returns a ready‑to‑use core.

|Status|Documentation|Test coverage|Features|Npm version| |---|---|---|---|---| |🟢 98.4% |🧪 English 🏴󠁧󠁢󠁥󠁮󠁧󠁿Українською 🇺🇦 |🟢 92.3% |✅ d.ts 📜 system.md 🕹️ playground |— |

Installation

How to install with npm?

npm install @nan0web/interface

How to install with pnpm?

pnpm add @nan0web/interface

How to install with yarn?

yarn add @nan0web/interface

Basic usage of CLIInterface

The class can be instantiated with custom streams.

How to create a CLIInterface with mocked streams?

import { CLIInterface } from "@nan0web/interface"
const stdin = new Readable({
	read() {
		this.push("example\n")
		this.push(null)
	},
})
const stdout = { writable: true }
const cli = new CLIInterface({ stdin, stdout, logger: console })

Output handling

output forwards messages to the provided logger.

How does CLIInterface output normal, warning and critical messages?

import { CLIInterface } from "@nan0web/interface"
const cli = new CLIInterface({ logger: console })
cli.output({
	content: ["normal msg"],
	priority: 0,
	meta: {},
	error: null,
})
cli.output({
	content: ["warn msg"],
	priority: 10,
	meta: {},
	error: null,
})
cli.output({
	content: ["fatal msg"],
	priority: 20,
	meta: {},
	error: null,
})

Factory helper

createCLIInterface returns an InterfaceCore instance that already wraps a CLIInterface.

How to obtain an InterfaceCore via the factory?

import { createCLIInterface, InterfaceCore } from "@nan0web/interface"
const core = createCLIInterface()

Registering a simple protocol

Demonstrates how a protocol can be added to the core.

How to register a trivial echo protocol and process input?

import { InterfaceCore } from "@nan0web/interface"
class Echo {
	constructor(trigger) {
		this._trigger = trigger
	}
	accepts(msg) {
		return msg.value === this._trigger
	}
	async process(msg) {
		return {
			content: ["echo:", msg.value],
			priority: 0,
			meta: {},
			error: null,
		}
	}
}
const stdin = new Readable({
	read() {
		this.push("ping\n")
		this.push(null)
	},
})
const core = new InterfaceCore(new CLIInterface({ stdin, logger: console }))
core.register(new Echo("ping"))
const status = await core.step()
console.info(status) // ← idle

API overview

The package exports the following symbols:

• createCLIInterface(config) – factory returning a ready core.
• CLIInterface – low‑level I/O implementation.
• InterfaceCore – protocol manager.

All exported symbols should be present

TypeScript declarations

The types field points to the generated declaration file.

Uses .d.ts for autocomplete

Contributing

How to contribute? - check here

License

How to license ISC? - check here