Schema visualization

(no submodules)

Purpose

The visualization module renders a BitPackerSchema into one of five inspection-friendly formats — JSON, HTML, Markdown, plain text, or Graphviz DOT — for tooling, documentation, and debugging. Schemas are JSON-serialisable but their nested structure (objects of _optional, _oneOf, _conditional, primitive tokens, arrays) is fiddly to read at scale; this module produces a renderable tree view that surfaces the structure at a glance. It is the layer that downstream developer tools (schema explorers, doc generators, registry UIs) consume to display the contents of the registry without parsing the schema themselves.

Features

Five output formats (SchemaVisualizationFormat): JSON, HTML, MARKDOWN, TEXT, DOT.
Configurable via SchemaVisualizationOptions (format, depth limit, include/exclude metadata).
Recursive descent through nested objects, arrays, and the _optional / _oneOf / _conditional operators.
Recognises the canonical primitive tokens (UUID, float, integer, string).

Usage: Basic Example

import {
  visualizeSchema,
  SchemaVisualizationFormat,
} from "@suaveplan/bitpacker-schema";

const html = visualizeSchema(
  { name: "-16", age: 255, tags: [{ _optional: "-32" }] },
  { format: SchemaVisualizationFormat.HTML }
);

Usage: Advanced Example

import {
  visualizeSchema,
  SchemaVisualizationFormat,
} from "@suaveplan/bitpacker-schema";

// Render a Graphviz DOT graph for a docs site.
const dot = visualizeSchema(playerSchema, {
  format: SchemaVisualizationFormat.DOT,
  maxDepth: 5,
});
// Pipe through `dot -Tsvg` to produce an SVG of the schema tree.

API Reference

`enum SchemaVisualizationFormat`

JSON | HTML | MARKDOWN | TEXT | DOT — pick the renderer to apply.

`interface SchemaVisualizationOptions`

format?: SchemaVisualizationFormat — default JSON.
maxDepth?: number — recursion depth limit; deeper nodes render as ….
includeMetadata?: boolean — include description, tags, etc. when present.

`visualizeSchema(schema, options?): string`

Renders the schema as a string in the requested format. Returns valid syntax for the chosen format (parseable JSON, render-ready HTML, etc.).

Implementation Notes

HTML output is intentionally semantic (<details> / <summary> for nesting) so the result is keyboard-navigable and accessible without extra CSS.
DOT output names every node deterministically (path-based IDs) so two renders of the same schema produce identical graphs — useful for regression-diffing schema docs.
The renderer handles cycles via a max-depth limit, not via cycle detection. BitPackerSchema is a tree by construction, but _ref lookups can produce structural cycles; in practice the maxDepth ceiling keeps the renderer linear.

2.8 KiB Raw Blame History