@nan0web/protocol

Minimalistic protocol for executing commands in a message‑driven environment. It validates input, runs a command (class or function) and returns a structured output.

Installation

How to install with npm?

npm install @nan0web/protocol

How to install with pnpm?

pnpm add @nan0web/protocol

How to install with yarn?

yarn add @nan0web/protocol

Basic usage – CommandProtocol

The protocol accepts an ExecutableCommand subclass or a plain function. It records a history of processed messages. @todo re-understand the logic of protocol commands due to new Message, UiMessage.

it.skip("How to create a CommandProtocol with a class command?", async () => { class EchoCommand extends ExecutableCommand { name = "Echo" async run(msg) { return msg.argv.join(" ") } } const protocol = new CommandProtocol({ command: new EchoCommand(), db: fs, logger: new NoConsole(), }) const input = { value: "Echo hello world", time: Date.now() } console.info(protocol.accepts(input)) // ← true const out = await protocol.process(input) console.info(out) // { content: ["hello world"], error: null, meta: { source: "Echo" }, priority: 0 } console.info(protocol.history[0].message) // Message { body: "Echo hello world", head: {} } @todo re-understand the logic of protocol commands due to new Message, UiMessage.

it.skip("How to use a plain function as command?", async () => { const fn = (msg) => msg.argv.map(v => v.toUpperCase()) const protocol = new CommandProtocol({ command: fn, db: fs, logger: new NoConsole(), }) const input = { value: "fn hello planet", time: Date.now() } const out = await protocol.process(input) console.info(protocol.accepts(input)) // ← true console.info(out.content) // ← ["HELLO", "PLANET"] console.info(out.meta.source) // ← "fn"

Object‑style command

Returning an object allows custom content, priority and meta. @todo re-understand the logic of protocol commands due to new Message, UiMessage.

it.skip("How to return an object from a command?", async () => { function ObjCmd(msg) { return { content: ["custom", ...msg.argv], priority: 7, meta: { extra: true }, } } const protocol = new CommandProtocol({ command: ObjCmd, db: fs, logger: new NoConsole(), }) const input = { value: "ObjCmd a b", time: Date.now() } const out = await protocol.process(input) console.info(out.content) // ← ["custom", "a", "b"] console.info(out.priority) // ← 7 console.info(out.meta) // ← { extra: true, source: "ObjCmd" }

Fallback response

When the command does not return a recognised shape.

How does fallback look like?

const fn = () => 12345
const protocol = new CommandProtocol({
	command: fn,
	db: fs,
	logger: new NoConsole(),
})
const input = { value: "fn any", time: Date.now() }
const out = await protocol.process(input)
console.info(out.content)
// [ "Command executed.", "(no output data)" ]
console.info(out.meta.source) // ← fn

Error handling

Thrown errors are caught and marked as critical (priority: 100).

How are errors reported?

const boom = () => {
	throw new Error("boom")
}
const protocol = new CommandProtocol({
	command: boom,
	db: fs,
	logger: new NoConsole(),
})
const input = { value: "boom test", time: Date.now() }
const out = await protocol.process(input)
console.info(out.content) // ← ["boom"]
console.info(out.priority) // ← 100
console.info(out.error instanceof Error) // ← true
console.info(out.meta.source) // ← boom

API surface

Exported symbols must be present.

All exported classes should be available

TypeScript declarations

Package provides .d.ts files

CLI Playground

Example command to run the playground script.

How to run playground script?

npm run play

Contributing

How to contribute? - check here

License

How to license ISC? - check here