diagrams-js 0.3.1 → 0.5.0

package/README.md

@@ -18,6 +18,7 @@
 - **2000+ Node Classes**: Comprehensive coverage of cloud services and infrastructure components
 - **Cross-Platform**: Works in browsers, Node.js, Deno and Bun
 - **Multiple Output Formats**: SVG, PNG, JPG, and DOT
+- **Visual Diff**: Compare diagram versions side-by-side with color-coded changes (added, removed, modified, renamed)
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
 - **WebAssembly Powered**: Uses a WebAssembly build of [Graphviz](https://graphviz.org) ([viz](https://github.com/mdaines/viz-js)) for fast, client-side rendering
 - **Custom Nodes**: Support for external icons and images
@@ -68,6 +69,34 @@ api.to([db, storage]);
 const svg = await diagram.render();
 ```
 
+### Visual Diff
+
+Compare two versions of a diagram to see what changed:
+
+```typescript
+import { Diagram } from "diagrams-js";
+import { writeFileSync } from "fs";
+
+// Load two versions (e.g., from git or saved JSON)
+const before = JSON.parse(await fs.readFile("arch-v1.json", "utf8"));
+const after = JSON.parse(await fs.readFile("arch-v2.json", "utf8"));
+
+// Generate visual diff as self-contained HTML
+const html = await Diagram.renderDiff(before, after, {
+  format: "html",
+  theme: "light",
+  showUnchanged: "show", // "show" (default), "dim", or "hide"
+});
+
+await fs.writeFile("diff.html", html);
+```
+
+The diff shows:
+
+- 🟢 **Green**: Added elements
+- 🔴 **Red**: Removed elements
+- 🟠 **Amber**: Modified elements (including label changes)
+
 ### Browser
 
 ```html

package/dist/index.d.ts

@@ -210,6 +210,8 @@ interface RenderOptions {
   scale?: number;
   /** Whether to inject icons into SVG output */
   injectIcons?: boolean;
+  /** Whether to embed diagram metadata into SVG output (default: true) */
+  embedData?: boolean;
   /** Whether to return output as data URL */
   dataUrl?: boolean;
 }
@@ -794,9 +796,9 @@ interface DiagramNodeJSON {
   /** Cloud provider identifier (e.g., 'aws', 'gcp', 'azure') */
   provider?: string;
   /** Service type within the provider (e.g., 'compute', 'storage') */
-  service?: string;
-  /** Specific resource type (e.g., 'EC2', 'S3', 'RDS') */
   type?: string;
+  /** Specific resource type (e.g., 'EC2', 'S3', 'RDS') */
+  resource?: string;
   /** Custom icon URL or data URI */
   iconUrl?: string;
   /** Additional Graphviz attributes */
@@ -919,8 +921,8 @@ interface DiagramJSON {
  *   name: "My Architecture",
  *   direction: "LR",
  *   nodes: [
- *     { id: "web", label: "Web Server", provider: "aws", service: "compute", type: "EC2" },
- *     { id: "db", label: "Database", provider: "aws", service: "database", type: "RDS" }
+ *     { id: "web", label: "Web Server", provider: "aws", type: "compute", resource: "EC2" },
+ *     { id: "db", label: "Database", provider: "aws", type: "database", resource: "RDS" }
  *   ],
  *   edges: [
  *     { from: "web", to: "db", label: "SQL" }
@@ -933,6 +935,190 @@ interface DiagramJSON {
  */
 declare function fromJSON(input: DiagramJSON | string, opts?: FromJSONOptions): Promise<Diagram>;
 //#endregion
+//#region src/diff.d.ts
+/**
+ * Type of change detected during diff computation.
+ */
+type ChangeKind = "added" | "removed" | "modified" | "unchanged";
+/**
+ * Diff result for a single node.
+ */
+interface NodeDiff {
+  /** The type of change */
+  kind: ChangeKind;
+  /** The node before changes (for removed, modified) */
+  before?: DiagramNodeJSON;
+  /** The node after changes (for added, modified) */
+  after?: DiagramNodeJSON;
+  /** Array of field paths that changed (for modified) */
+  changes?: string[];
+}
+/**
+ * Diff result for a single edge.
+ */
+interface EdgeDiff {
+  /** The type of change */
+  kind: ChangeKind;
+  /** The edge before changes */
+  before?: DiagramEdgeJSON;
+  /** The edge after changes */
+  after?: DiagramEdgeJSON;
+  /** Array of field paths that changed */
+  changes?: string[];
+}
+/**
+ * Diff result for a cluster (recursive).
+ */
+interface ClusterDiff {
+  /** The type of change */
+  kind: ChangeKind;
+  /** Cluster label */
+  label: string;
+  /** The cluster before changes */
+  before?: DiagramClusterJSON;
+  /** The cluster after changes */
+  after?: DiagramClusterJSON;
+  /** Array of field paths that changed */
+  changes?: string[];
+  /** Nested cluster diffs */
+  clusters?: ClusterDiff[];
+  /** Node IDs in this cluster and their diff status */
+  nodes?: Map<string, NodeDiff>;
+}
+/**
+ * Summary of changes in the diff.
+ */
+interface DiffSummary {
+  /** Number of added nodes/edges/clusters */
+  added: number;
+  /** Number of removed nodes/edges/clusters */
+  removed: number;
+  /** Number of modified nodes/edges/clusters */
+  modified: number;
+  /** Number of unchanged nodes/edges/clusters */
+  unchanged: number;
+}
+/**
+ * Metadata-level changes (diagram options, not individual elements).
+ */
+interface DiffMeta {
+  /** Diagram name change */
+  name?: {
+    before?: string;
+    after?: string;
+  };
+  /** Theme change */
+  theme?: {
+    before?: string;
+    after?: string;
+  };
+  /** Direction change */
+  direction?: {
+    before?: string;
+    after?: string;
+  };
+  /** Curve style change */
+  curvestyle?: {
+    before?: string;
+    after?: string;
+  };
+  /** Graph attributes change */
+  graphAttr?: {
+    before?: Record<string, string>;
+    after?: Record<string, string>;
+  };
+  /** Node attributes change */
+  nodeAttr?: {
+    before?: Record<string, string>;
+    after?: Record<string, string>;
+  };
+  /** Edge attributes change */
+  edgeAttr?: {
+    before?: Record<string, string>;
+    after?: Record<string, string>;
+  };
+}
+/**
+ * Complete diff result for a diagram comparison.
+ */
+interface DiagramDiffResult {
+  /** Node diffs by node ID */
+  nodes: Map<string, NodeDiff>;
+  /** Edge diffs by composite key "from->to[label]" */
+  edges: Map<string, EdgeDiff>;
+  /** Cluster diffs */
+  clusters: ClusterDiff[];
+  /** Summary counts */
+  summary: DiffSummary;
+  /** Metadata-level changes */
+  meta: DiffMeta;
+}
+/**
+ * Options for computing a diff.
+ */
+interface DiffOptions {
+  /** Fields to ignore during comparison */
+  ignore?: {
+    /** Ignore position/layout changes (default: true) */position?: boolean; /** Ignore metadata changes entirely, or specific metadata keys */
+    metadata?: boolean | string[]; /** Ignore specific Graphviz attributes */
+    attrs?: string[]; /** Ignore node ID changes - treat same-fingerprint nodes as unchanged (default: false) */
+    nodeId?: boolean;
+  };
+  /** Custom node matching function (overrides default ID + fingerprint matching) */
+  matchNodes?: (a: DiagramNodeJSON, b: DiagramNodeJSON) => boolean;
+}
+/**
+ * Options for rendering a diff.
+ */
+interface RenderDiffOptions {
+  /** Output format: svg (combined) or html (self-contained page) */
+  format?: "svg" | "html";
+  /** Layout mode: side-by-side (default) or stacked */
+  layout?: "side-by-side" | "stacked";
+  /** Color theme: light (default) or dark */
+  theme?: "light" | "dark";
+  /** How to display unchanged elements: "show" | "dim" | "hide" (default: "show") */
+  showUnchanged?: "show" | "dim" | "hide";
+  /** Show legend in HTML output (default: true) */
+  showLegend?: boolean;
+  /** Show summary header in HTML output (default: true) */
+  showSummary?: boolean;
+  /** Enable hover tooltips in HTML output (default: true) */
+  hoverDetails?: boolean;
+}
+/**
+ * Compute the diff between two diagram versions.
+ *
+ * @param before - The original diagram (JSON or Diagram object)
+ * @param after - The updated diagram (JSON or Diagram object)
+ * @param opts - Options for diff computation
+ * @returns Complete diff result with nodes, edges, clusters, and summary
+ *
+ * @example
+ * ```typescript
+ * const diff = computeDiff(diagramV1.toJSON(), diagramV2.toJSON());
+ * console.log(diff.summary); // { added: 2, removed: 1, modified: 3, ... }
+ * ```
+ */
+declare function computeDiff(before: DiagramJSON | Diagram, after: DiagramJSON | Diagram, opts?: DiffOptions): DiagramDiffResult;
+/**
+ * Render a visual diff between two diagram versions.
+ *
+ * @param diff - The computed diff result from `computeDiff()`
+ * @param before - The original diagram (JSON or Diagram object)
+ * @param after - The updated diagram (JSON or Diagram object)
+ * @param opts - Options for rendering the diff
+ * @returns Promise resolving to SVG or HTML string
+ *
+ * @example
+ * ```typescript
+ * const diff = computeDiff(beforeJson, afterJson);
+ * const html = await renderDiff(diff, beforeJson, afterJson, { format: "html" });
+ * await fs.writeFile("diff.html", html);
+ * ```
+ */
+declare function renderDiff(diff: DiagramDiffResult, before: DiagramJSON | Diagram, after: DiagramJSON | Diagram, opts?: RenderDiffOptions): Promise<string>;
+//#endregion
 //#region src/icons.d.ts
 /**
  * Maps a node to its icon information
@@ -1170,6 +1356,15 @@ declare function Diagram(name?: string, options?: DiagramOptions): Diagram;
 declare namespace Diagram {
   var fromJSON: typeof fromJSON;
 }
+declare namespace Diagram {
+  var fromSVG: (svg: string) => Promise<Diagram>;
+}
+declare namespace Diagram {
+  var diff: (before: DiagramJSON | Diagram, after: DiagramJSON | Diagram, opts?: DiffOptions) => Promise<DiagramDiffResult>;
+}
+declare namespace Diagram {
+  var renderDiff: (before: DiagramJSON | Diagram, after: DiagramJSON | Diagram, opts?: RenderDiffOptions) => Promise<string>;
+}
 //#endregion
 //#region src/Custom.d.ts
 /**
@@ -1302,8 +1497,22 @@ declare function createJSONPlugin(): DiagramsPlugin;
  * Exported for convenience
  */
 declare const jsonPlugin: DiagramsPlugin;
+//#endregion
+//#region src/plugins/built-in/svg.d.ts
+/**
+ * Create the built-in SVG plugin
+ *
+ * This plugin is automatically registered with every diagram and provides
+ * SVG export/import with embedded metadata capabilities.
+ */
+declare function createSVGPlugin(): DiagramsPlugin;
+/**
+ * Default SVG plugin instance
+ * Exported for convenience
+ */
+declare const svgPlugin: DiagramsPlugin;
 declare namespace index_d_exports {
-  export { Cluster, CreatePlugin, Custom, DependencyError, Diagram, DiagramClusterJSON, DiagramEdgeJSON, DiagramJSON, DiagramNodeJSON, DiagramOptions, DiagramsPlugin, Edge, EdgeOptions, ExportContext, ExporterCapability, FromJSONOptions, HookCapability, HookContext, HookEvent, HookHandler, Iconify, ImportContext, ImporterCapability, MetadataCapability, MetadataContext, Node, NodeMetadata, NodeOptions, PluginCapability, PluginContext, PluginError, PluginRegistry, ProviderModule, RenderContext, RendererCapability, RuntimeError, RuntimeSupport, ThemeConfig, ThemeName, Yaml, createJSONPlugin, createPluginRegistry, jsonPlugin };
+  export { ChangeKind, Cluster, ClusterDiff, CreatePlugin, Custom, DependencyError, Diagram, DiagramClusterJSON, DiagramDiffResult, DiagramEdgeJSON, DiagramJSON, DiagramNodeJSON, DiagramOptions, DiagramsPlugin, DiffMeta, DiffOptions, DiffSummary, Edge, EdgeDiff, EdgeOptions, ExportContext, ExporterCapability, FromJSONOptions, HookCapability, HookContext, HookEvent, HookHandler, Iconify, ImportContext, ImporterCapability, MetadataCapability, MetadataContext, Node, NodeDiff, NodeMetadata, NodeOptions, PluginCapability, PluginContext, PluginError, PluginRegistry, ProviderModule, RenderContext, RenderDiffOptions, RendererCapability, RuntimeError, RuntimeSupport, ThemeConfig, ThemeName, Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };
 }
 //#endregion
-export { Cluster, type CreatePlugin, Custom, DependencyError, Diagram, type DiagramClusterJSON, type DiagramEdgeJSON, type DiagramJSON, type DiagramNodeJSON, type DiagramOptions, type DiagramsPlugin, Edge, type EdgeOptions, type ExportContext, type ExporterCapability, type FromJSONOptions, type HookCapability, type HookContext, HookEvent, type HookHandler, Iconify, type ImportContext, type ImporterCapability, type MetadataCapability, type MetadataContext, type Node, type NodeMetadata, type NodeOptions, type PluginCapability, type PluginContext, PluginError, type PluginRegistry, type ProviderModule, type RenderContext, type RendererCapability, RuntimeError, type RuntimeSupport, type ThemeConfig, type ThemeName, type Yaml, createJSONPlugin, createPluginRegistry, jsonPlugin };
+export { type ChangeKind, Cluster, type ClusterDiff, type CreatePlugin, Custom, DependencyError, Diagram, type DiagramClusterJSON, type DiagramDiffResult, type DiagramEdgeJSON, type DiagramJSON, type DiagramNodeJSON, type DiagramOptions, type DiagramsPlugin, type DiffMeta, type DiffOptions, type DiffSummary, Edge, type EdgeDiff, type EdgeOptions, type ExportContext, type ExporterCapability, type FromJSONOptions, type HookCapability, type HookContext, HookEvent, type HookHandler, Iconify, type ImportContext, type ImporterCapability, type MetadataCapability, type MetadataContext, type Node, type NodeDiff, type NodeMetadata, type NodeOptions, type PluginCapability, type PluginContext, PluginError, type PluginRegistry, type ProviderModule, type RenderContext, type RenderDiffOptions, type RendererCapability, RuntimeError, type RuntimeSupport, type ThemeConfig, type ThemeName, type Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };