@theophilusdev/silver

A typed node pipeline for building your own bot message formatter.

silver is not a formatter out of the box — it's a framework for building one. You define how each node type renders, then compose messages by assembling typed node arrays. The architecture handles the pipeline: registration, composition, indentation, newlines, custom nodes, and type safety. You own the output.

Think of it like building blocks: silver gives you the bricks and the system. You decide what they look like.

npm install @theophilusdev/silver

Quick Start

silver has no built-in default renderers. The first thing you do is register a renderer for each node type your formatter needs — this is what defines how your output looks. Then render a document by passing an array of typed nodes.

import { Silver } from "@theophilusdev/silver";

const silver = Silver.create()
  .register("header", (node) => `=== ${node.content} ===`)
  .register("body", (node) => node.content)
  .register("footer", (node) => `— ${node.content}`);

const output = silver.render([
  { type: "header", content: "Hello World" },
  { type: "body", content: "This is a bot message." },
  { type: "footer", content: "silver" },
]);

console.log(output);

=== Hello World ===
This is a bot message.
— silver

Core Concepts

Register -> Render

Silver.create() returns a fluent builder. Chain .register() calls to define a renderer for each node type, then call .render() with an array of nodes. Nodes are joined with newlines and rendered in order.

Typed Node Construction

Use silver.node() when you want full autocomplete on both the node type and its fields:

silver.render([
  silver.node("header", { content: "Title" }, { newline: true }),
  silver.node("body", { content: "Body text" }),
]);

Custom Nodes

Silver.createNode() lets you define fully custom node types outside the built-in map — no registration needed:

const wave = Silver.createNode<{ username: string }>(
  (node) => `👋 ${node.username}`,
);

silver.render([
  wave({ username: "Alice" })
]);
// 👋 Alice

Indentation & Newlines

Every node accepts optional indented and newline config:

silver.render([
  {
    type: "body",
    content: "indented line",
    indented: { indentCharacter: "  ", indentAmount: 2 },
  },
  { type: "body", content: "line with newline", newline: true },
  { type: "body", content: "next line" },
]);

    indented line
line with newline

next line

Extending the Node Map

Add your own entries to the built-in NodeMap via module augmentation on RawNodeMap:

declare module "@theophilusdev/silver" {
  interface RawNodeMap {
    badge: { text: string; color?: string };
  }
}

Your custom type is then available in .register(), .node(), and .render() with full type safety.

Built-in Node Types

Silver ships with a typed vocabulary of 40+ node schemas — structured data shapes you can use as the building blocks of your formatter. These are not pre-rendered; you register a renderer for each type you use. The output examples below illustrate what a typical renderer might produce, not what Silver outputs by default.

| Node | Example Output | |---|---| | header | === Welcome to Silver === | | subheader | --- Getting Started --- | | body | Plain text or multiline string array | | footer | — silver v1.0.0 | | caption | [ Figure 1: Example output ] | | code | Fenced code block with language | | codespan | `silver.render()` | | quote | "Keep it simple." — ryo | | blockquote | > First line / > — ryo | | divider | ──────────────────────── | | separator | ── section ── | | label | Status: Online | | keyvalue | CPU: 42% / RAM: 1.2GB | | list | • Apple / • Banana | | numbered | 1. First / 2. Second | | checklist | [x] Done / [ ] Pending | | badge | [stable] | | link | GitHub (https://...) | | spoiler | \|\| The butler did it. \|\| | | empty | (blank line) | | warning | ⚠️ Disk space low. | | error | ❌ Connection refused. | | success | ✅ Deployment complete. | | info | ℹ️ Update available. | | timestamp | 2 hours ago / 1/1/2025 / 6/15/2025, 2:30:00 PM | | mention | @ryo (123456) | | tag | #typescript | | progress | [█████████████░░░░░░░] 65/100 | | table | ASCII table with headers and rows | | tree | src / ├─ index.ts / └─ types.ts | | diff | + added line / - removed line | | stat | Latency: 42 ms | | profile | 👤 ryo / Developer / Location: Tokyo | | countdown | Launch: 9d remaining | | rating | ★★★★☆ | | poll | 📊 Favorite language? with vote bars | | command | /ping / Check bot latency / Usage: /ping | | token | <auth:abc123> | | redacted | ██████ | | ascii | Raw ASCII art lines | | columns | Fixed-width column layout | | bold | **Important** | | italic | _emphasis_ | | strikethrough | ~~deprecated~~ |

See docs/DOCS.md for the full field reference for each node type.

API Reference

Silver.create()

Creates and returns a new Silver instance. Preferred over new Silver() for a fluent builder style.

silver.register(type, renderer)

Registers a renderer for a built-in node type. Returns this for chaining.

| Parameter | Type | Description | |---|---|---| | type | keyof NodeMap | The built-in node type to register. | | renderer | (node: Node<T>) => string | Function that renders the node to a string. |

silver.node(type, data, config?)

Constructs a typed built-in node object with full autocomplete.

| Parameter | Type | Description | |---|---|---| | type | keyof NodeMap | The node type. | | data | Node fields (excluding type, indented, newline) | The node's content/data fields. | | config | Pick<NodeConfig, "indented" \| "newline"> (optional) | Rendering config options. |

silver.render(nodes)

Renders an array of nodes to a plain text string. Throws if a node has no registered renderer.

| Parameter | Type | Description | |---|---|---| | nodes | RenderNode[] | Array of built-in nodes or custom NodeFactoryResult nodes. |

Returns: string

Silver.createNode(renderer) (static)

Creates a custom node factory with full type safety. The returned factory is callable.

| Parameter | Type | Description | |---|---|---| | renderer | (node: T & NodeConfig) => string | Function that renders the node to a string. |

Returns: NodeFactory<T>

NodeConfig

Optional rendering config accepted by every node.

| Field | Type | Default | Description | |---|---|---|---| | indented | object | — | Prepends indentation before the rendered output. | | indented.indentCharacter | string | "\t" | The character used for indentation. | | indented.indentAmount | number | 1 | How many times to repeat the indent character. | | newline | boolean | — | Appends a \n after the rendered output. |

License

GPL V3