Types Reference

1type DiagramType = 'mermaid' | 'excalidraw' | 'drawio' | 'graphviz'

1type OutputFormat = 'svg' | 'png' | 'jpeg' | 'webp' | 'avif'

1type Theme = 'light' | 'dark' | 'both'

1type LogLevel =2  | 'silent'3  | 'error'4  | 'errors'5  | 'warn'6  | 'warning'7  | 'warnings'8  | 'info'9  | 'log'10  | 'verbose'

1type DiagramkitErrorCode =2  | 'UNKNOWN_TYPE'3  | 'RENDER_FAILED'4  | 'MISSING_DEPENDENCY'5  | 'CONFIG_INVALID'6  | 'BROWSER_LAUNCH_FAILED'7  | 'BUNDLE_FAILED'

1interface Logger {2  log: (message: string, ...args: unknown[]) => void3  warn: (message: string, ...args: unknown[]) => void4  error: (message: string, ...args: unknown[]) => void5}6

1interface OutputNamingOptions {2  prefix?: string3  suffix?: string4}

1interface DiagramkitConfig {2  /** Output folder name. Default: '.diagramkit' */3  outputDir: string45  /** Manifest filename. Default: 'manifest.json' */6  manifestFile: string78  /** Enable incremental builds. Default: true */9  useManifest: boolean1011  /** Place outputs next to source (no subfolder). Default: false */12  sameFolder: boolean1314  /** Default output formats. Default: ['svg'] */15  defaultFormats: OutputFormat[]1617  /** Default theme. Default: 'both' */18  defaultTheme: Theme1920  /** Output filename prefix. Default: '' */21  outputPrefix: string2223  /** Output filename suffix. Default: '' */24  outputSuffix: string2526  /** Custom extension-to-type overrides */27  extensionMap?: Record<string, DiagramType>2829  /** Directories to scan for diagram files */30  inputDirs?: string[]3132  /** Per-file render overrides (keyed by filename, path, or glob) */33  overrides?: Record<string, FileOverride>3435  /**36   * Mermaid aspect-ratio rebalance options. Applies only to mermaid renders.37   * Default: `{ mode: 'warn', targetAspectRatio: 4 / 3, tolerance: 2.5 }`.38   * See [`MermaidLayoutOptions`](#mermaidlayoutoptions) below.39   */40  mermaidLayout?: MermaidLayoutOptions41}

1interface DiagramFile {2  /** Absolute path to source file */3  path: string4  /** Filename without extension */5  name: string6  /** Directory containing the file */7  dir: string8  /** File extension (e.g. .mermaid, .dot) */9  ext: string10}

1interface RenderableFile extends DiagramFile {2  /** SHA-256 content hash (internal) */3  _hash?: string4  /** Effective formats after applying overrides (internal) */5  _effectiveFormats?: OutputFormat[]6  /** Per-output metadata for manifest entries (internal) */7  _outputMeta?: OutputMetadata[]8  /** Last-seen source mtime, used for fast no-op skips before re-hashing (internal) */9  _mtimeMs?: number10  /** Last-seen source size in bytes, paired with `_mtimeMs` (internal) */11  _size?: number12}

1interface OutputMetadata {2  /** Output filename */3  file: string4  /** Output format */5  format: OutputFormat6  /** Theme variant */7  theme: 'light' | 'dark'8  /** SVG width in pixels (SVG only) */9  width?: number10  /** SVG height in pixels (SVG only) */11  height?: number12  /** JPEG/WebP/AVIF quality used */13  quality?: number14  /** Raster scale factor used */15  scale?: number16}

1type StaleFile = RenderableFile

1interface StalePlanEntry {2  path: string3  effectiveFormats: OutputFormat[]4  reasons: StaleReason[]5}

1type StaleReasonCode =2  | 'forced'3  | 'manifest_disabled'4  | 'no_manifest_entry'5  | 'theme_changed'6  | 'missing_outputs'7  | 'content_changed'

1interface RenderOptions {2  /** Output format. Default: 'svg' */3  format?: OutputFormat4  /** Theme variant(s). Default: 'both' */5  theme?: Theme6  /** JPEG/WebP quality (1-100). Default: 90 */7  quality?: number8  /** Raster scale factor. Default: 2 */9  scale?: number10  /** Dark SVG contrast optimization. Default: true */11  contrastOptimize?: boolean12  /** Custom Mermaid dark theme variables */13  mermaidDarkTheme?: Record<string, string>14  /** Per-call mermaid aspect-ratio rebalance overrides. Merged on top of the project config. */15  mermaidLayout?: MermaidLayoutOptions16  /** Config overrides */17  config?: Partial<DiagramkitConfig>18  /** Optional logger for non-fatal warnings (e.g. mermaid aspect-ratio rebalance notices) */19  logger?: Logger20  /** Browser pool instance for isolated runtimes (advanced) */21  pool?: BrowserPool22}

1interface MermaidLayoutOptions {2  /** Rebalance behaviour. Default: 'warn'. */3  mode?: 'off' | 'warn' | 'flip' | 'elk' | 'auto'4  /** Target aspect ratio (width / height). Default: 4 / 3 ≈ 1.333. */5  targetAspectRatio?: number6  /** Tolerance factor; ratio is acceptable when inside [target/tolerance, target*tolerance]. Must be > 1. Default: 2.5. */7  tolerance?: number8}

1interface RenderResult {2  /** Light theme output buffer */3  light?: Buffer4  /** Dark theme output buffer */5  dark?: Buffer6  /** Output format used */7  format: OutputFormat8  /** SVG width in pixels (SVG only) */9  width?: number10  /** SVG height in pixels (SVG only) */11  height?: number12}

1interface RenderAllResult {2  /** Files that were rendered */3  rendered: string[]4  /** Files skipped (cache hit) */5  skipped: string[]6  /** Files that failed */7  failed: string[]8  /** Structured failure details aligned with `failed` */9  failedDetails: RenderFailureDetail[]10  /** Optional batch timing and lane metrics (when includeMetrics is true) */11  metrics?: {12    durationMs: number13    lanesUsed: number14    countsByType: Partial<Record<DiagramType, { rendered: number; failed: number }>>15  }16}

1interface RenderFailureDetail {2  file: string3  message: string4  code: DiagramkitErrorCode5}

1interface BatchOptions extends RenderOptions {2  /** Root directory to scan. Default: cwd() */3  dir?: string4  /** Force re-render. Default: false */5  force?: boolean6  /** Filter by diagram type */7  type?: DiagramType8  /** Output formats (overrides config). */9  formats?: OutputFormat[]10  /** Custom logger */11  logger?: Logger12  /** Logging verbosity level */13  logLevel?: LogLevel14  /** Show per-file progress logs during batch rendering */15  progress?: boolean16  /** Max number of type lanes running concurrently (1-4). Default: 4. */17  maxConcurrentLanes?: number18  /** Include timing and lane metrics in result */19  includeMetrics?: boolean20  /** Throw a DiagramkitError after batch completes if any diagram failed. Default: false */21  strict?: boolean22}

1interface WatchOptions {2  /** Root directory to watch */3  dir: string4  /** Callback after render */5  onChange?: (file: string) => void6  /** Render options */7  renderOptions?: RenderOptions & { formats?: OutputFormat[] }8  /** Config overrides */9  config?: Partial<DiagramkitConfig>10  /** Explicit config file path (skips local auto-discovery) */11  configFile?: string12  /** Custom logger */13  logger?: Logger14  /** Logging verbosity level */15  logLevel?: LogLevel16  /** Strict config validation mode for watch startup */17  strictConfig?: boolean18  /** Optional browser pool instance for isolated runtimes */19  pool?: import('./pool').BrowserPool20  /** Debounce time for file events. Default: 200ms */21  debounceMs?: number22  /** Chokidar polling mode (useful for network volumes/containers) */23  usePolling?: boolean24  /** Chokidar polling interval in ms when usePolling=true */25  pollingInterval?: number26}

1interface ConvertOptions {2  /** Target raster format */3  format: 'png' | 'jpeg' | 'webp' | 'avif'4  /** Scale multiplier for SVG rasterization. Default: 2 */5  scale?: number6  /** JPEG/WebP quality (1-100). Default: 90 */7  quality?: number8}

1type Manifest = {2  version: 23  diagrams: Record<string, ManifestEntry>4}

1type ManifestEntry = {2  hash: string3  generatedAt: string4  outputs: ManifestOutput[]5  formats: OutputFormat[]6  theme?: Theme7  mtimeMs?: number8  size?: number9}

1type ManifestOutput = {2  file: string3  format: OutputFormat4  theme: 'light' | 'dark'5  width?: number6  height?: number7  quality?: number8  scale?: number9}

1type FileOverride = {2  /** Output formats for this file */3  formats?: OutputFormat[]4  /** Theme variant(s) */5  theme?: Theme6  /** Raster scale factor */7  scale?: number8  /** JPEG/WebP/AVIF quality (1-100) */9  quality?: number10  /** Dark SVG contrast optimization */11  contrastOptimize?: boolean12}

1interface RendererRuntime {2  pool: BrowserPool3  render: (source: string, type: DiagramType, options?: RenderOptions) => Promise<RenderResult>4  renderFile: (filePath: string, options?: RenderOptions) => Promise<RenderResult>5  renderDiagramFileToDisk: (file: DiagramFile, options?: RenderOptions & { config?: DiagramkitConfig; outDir?: string; formats?: OutputFormat[] }) => Promise<string[]>6  renderAll: (options?: BatchOptions) => Promise<RenderAllResult>7  watchDiagrams: (options: WatchOptions) => () => Promise<void>8  warmup: () => Promise<void>9  dispose: () => Promise<void>10}

1type StaleReason =2  | { code: 'forced' }3  | { code: 'manifest_disabled' }4  | { code: 'no_manifest_entry' }5  | { code: 'theme_changed'; requestedTheme: Theme; manifestTheme?: Theme }6  | { code: 'missing_outputs'; files: string[] }7  | { code: 'content_changed'; previousHash: string; currentHash: string }

1type SvgIssueSeverity = 'error' | 'warning'

1type SvgIssueCode =2  | 'EMPTY_FILE'3  | 'MISSING_SVG_TAG'4  | 'MISSING_SVG_CLOSE'5  | 'MISSING_WIDTH'6  | 'MISSING_HEIGHT'7  | 'NO_VISUAL_ELEMENTS'8  | 'CONTAINS_SCRIPT'9  | 'CONTAINS_FOREIGN_OBJECT'10  | 'MISSING_XMLNS'11  | 'EXTERNAL_RESOURCE'12  | 'INVALID_VIEWBOX'13  | 'SVG_TOO_LARGE'14  | 'LOW_CONTRAST_TEXT'15  | 'ASPECT_RATIO_EXTREME'

1interface SvgIssue {2  code: SvgIssueCode3  severity: SvgIssueSeverity4  message: string5  suggestion?: string6}

1interface SvgValidateOptions {2  /** Run the WCAG 2.2 AA contrast scan against rendered text. Default: true. */3  checkContrast?: boolean4  /** Effective canvas/page background. Default: inferred from `-light.svg` / `-dark.svg` suffix. */5  backgroundOverride?: string6  /**7   * Aspect-ratio sanity check. When the rendered ratio falls outside8   * `[target / tolerance, target * tolerance]`, the validator emits9   * `ASPECT_RATIO_EXTREME`. Pass `false` to skip the check.10   * Default: `{ target: 4 / 3, tolerance: 2.5 }`.11   */12  aspectRatio?: { target: number; tolerance: number } | false13}

1interface SvgValidationResult {2  file?: string3  valid: boolean4  issues: SvgIssue[]5}

1interface SvgValidateOptions {2  /** Run the WCAG 2.2 AA contrast scan against rendered text. Default: true. */3  checkContrast?: boolean4  /** Effective canvas/page background. Defaults inferred from the filename suffix. */5  backgroundOverride?: string6}