@knowvah/dot-engine 1.8.1 → 2.0.0

package/dist/api.js

@@ -474,7 +474,91 @@ var Edge = class _Edge {
   }
 };
 
+// src/errors.ts
+var FRIENDLY_MESSAGES = {
+  SYNTAX_ERROR: "There is a syntax error in the DOT source.",
+  SYNTAX_UNEXPECTED_EOF: "The DOT source ended unexpectedly \u2014 a bracket or statement may be unclosed.",
+  EDGE_OP_DIRECTED_IN_UNDIRECTED: "A directed edge '->' was used in an undirected graph; use '--' instead.",
+  EDGE_OP_UNDIRECTED_IN_DIRECTED: "An undirected edge '--' was used in a directed graph; use '->' instead.",
+  HTML_PARSE_ERROR: "An HTML-like label could not be parsed.",
+  RENDER_ERROR: "The graph could not be laid out or rendered.",
+  INTERNAL_ERROR: "dot-engine hit an internal bug while processing the graph. Please report it with the DOT source that triggered it.",
+  UNKNOWN_LAYOUT: "The graph names a layout engine that is not available.",
+  UNSUPPORTED_FEATURE: "The graph uses a Graphviz feature that dot-engine does not support yet.",
+  GENERIC_ERROR: "An unexpected error occurred while rendering the graph."
+};
+function friendlyMessageFor(code) {
+  return FRIENDLY_MESSAGES[code];
+}
+var DotEngineError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+  }
+};
+var InternalError = class extends DotEngineError {
+  type = "render";
+  code = "INTERNAL_ERROR";
+  friendlyMessage = friendlyMessageFor("INTERNAL_ERROR");
+  constructor(message, options) {
+    super(message, options);
+    this.name = "InternalError";
+  }
+};
+var UsageTypeError = class extends TypeError {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+};
+var UsageStateError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+};
+function describeReceived(v) {
+  if (v === null || v === void 0) return String(v);
+  switch (typeof v) {
+    case "string":
+      return `string ${JSON.stringify(v)}`;
+    case "number":
+    case "boolean":
+    case "bigint":
+      return `${typeof v} ${String(v)}`;
+    case "function":
+      return "a function";
+    case "symbol":
+      return "a symbol";
+    default: {
+      const ctor = v.constructor;
+      return typeof ctor?.name === "string" && ctor.name !== "" ? `an instance of ${ctor.name}` : "an object";
+    }
+  }
+}
+function invalidArgType(param, expected, actual) {
+  return new UsageTypeError(
+    `The "${param}" argument must be of type ${expected}. Received ${describeReceived(actual)}`,
+    "ERR_INVALID_ARG_TYPE"
+  );
+}
+function invalidArgValue(param, value, allowed) {
+  return new UsageTypeError(
+    `The argument "${param}" is invalid. Received ${JSON.stringify(value)}; allowed: ${allowed.join(", ")}`,
+    "ERR_INVALID_ARG_VALUE"
+  );
+}
+function invalidState(message) {
+  return new UsageStateError(message, "ERR_INVALID_STATE");
+}
+
 // src/api/edge-ops.ts
+function requireObject(param, v) {
+  if (typeof v !== "object" || v === null) {
+    throw invalidArgType(param, "object", v);
+  }
+}
 function isUndirected(g) {
   const k = g.root.kind;
   return k === "undirected" || k === "strict-undirected";
@@ -500,6 +584,12 @@ function insertEdge(g, root, edge) {
   }
 }
 function addEdge(g, tail, head, name) {
+  requireObject("g", g);
+  requireObject("tail", tail);
+  requireObject("head", head);
+  if (name !== void 0 && typeof name !== "string") {
+    throw invalidArgType("name", "string or undefined", name);
+  }
   const root = g.root;
   const undirected = isUndirected(g);
   if (isStrict(g)) {
@@ -511,31 +601,6 @@ function addEdge(g, tail, head, name) {
   return edge;
 }
 
-// src/errors.ts
-var FRIENDLY_MESSAGES = {
-  SYNTAX_ERROR: "There is a syntax error in the DOT source.",
-  SYNTAX_UNEXPECTED_EOF: "The DOT source ended unexpectedly \u2014 a bracket or statement may be unclosed.",
-  EDGE_OP_DIRECTED_IN_UNDIRECTED: "A directed edge '->' was used in an undirected graph; use '--' instead.",
-  EDGE_OP_UNDIRECTED_IN_DIRECTED: "An undirected edge '--' was used in a directed graph; use '->' instead.",
-  HTML_PARSE_ERROR: "An HTML-like label could not be parsed.",
-  RENDER_ERROR: "The graph could not be laid out or rendered.",
-  GENERIC_ERROR: "An unexpected error occurred while rendering the graph."
-};
-function friendlyMessageFor(code) {
-  return FRIENDLY_MESSAGES[code];
-}
-var RenderError = class extends Error {
-  type = "render";
-  code;
-  friendlyMessage;
-  constructor(message, code = "RENDER_ERROR") {
-    super(message);
-    this.name = "RenderError";
-    this.code = code;
-    this.friendlyMessage = friendlyMessageFor(code);
-  }
-};
-
 // src/common/html-string.ts
 var HTML_STRING_MARK = "
";
 
@@ -550,12 +615,15 @@ var NodeHandle = class {
     return this._node.name;
   }
   setAttr(k, v) {
+    requireKeyValue(k, v);
     this._node.attrs.set(k, v);
   }
   setHtmlAttr(k, v) {
+    requireKeyValue(k, v);
     this._node.attrs.set(k, HTML_STRING_MARK + v);
   }
   getAttr(k) {
+    requireString("k", k);
     return this._node.attrs.get(k);
   }
 };
@@ -572,20 +640,59 @@ var EdgeHandle = class {
     return this._edge.head.name;
   }
   setAttr(k, v) {
+    requireKeyValue(k, v);
     this._edge.attrs.set(k, v);
   }
   setHtmlAttr(k, v) {
+    requireKeyValue(k, v);
     this._edge.attrs.set(k, HTML_STRING_MARK + v);
   }
   getAttr(k) {
+    requireString("k", k);
     return this._edge.attrs.get(k);
   }
 };
+function requireString(param, v) {
+  if (typeof v !== "string") throw invalidArgType(param, "string", v);
+}
+function requireAttrs(param, attrs) {
+  if (attrs === void 0) return;
+  requireObject(param, attrs);
+  if (Array.isArray(attrs)) throw invalidArgType(param, "plain object", attrs);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (typeof v !== "string") {
+      throw invalidArgType(`${param}.${k}`, "string", v);
+    }
+  }
+}
+function requireNodeRef(param, ref) {
+  if (typeof ref === "string" || ref instanceof NodeHandle) return;
+  throw invalidArgType(param, "string or GvNode", ref);
+}
+function requireKeyValue(k, v) {
+  requireString("k", k);
+  requireString("v", v);
+}
+function requireGraphOptions(opts) {
+  if (opts === void 0) return;
+  requireObject("opts", opts);
+  const o = opts;
+  for (const key of ["directed", "strict"]) {
+    if (o[key] !== void 0 && typeof o[key] !== "boolean") {
+      throw invalidArgType(`opts.${key}`, "boolean or undefined", o[key]);
+    }
+  }
+  if (o["name"] !== void 0 && typeof o["name"] !== "string") {
+    throw invalidArgType("opts.name", "string or undefined", o["name"]);
+  }
+}
 function resolveNode(g, ref) {
   if (typeof ref === "string") {
     const node = agnode(g, ref, true);
     if (node === null) {
-      throw new RenderError(`Failed to resolve node '${ref}' in graph '${g.name}'`, "GENERIC_ERROR");
+      throw new InternalError(
+        `Failed to resolve node '${ref}' in graph '${g.name}'`
+      );
     }
     return node;
   }
@@ -611,6 +718,9 @@ var GraphBuilder = class _GraphBuilder {
     return addNodeToContext(this._graph, this._context, name, attrs);
   }
   addEdge(tail, head, attrs) {
+    requireNodeRef("tail", tail);
+    requireNodeRef("head", head);
+    requireAttrs("attrs", attrs);
     const tailNode = resolveNode(this._graph, tail);
     const headNode = resolveNode(this._graph, head);
     const edge = addEdge(this._graph, tailNode, headNode);
@@ -618,26 +728,33 @@ var GraphBuilder = class _GraphBuilder {
     return new EdgeHandle(edge);
   }
   addSubgraph(name, attrs) {
+    requireString("name", name);
+    requireAttrs("attrs", attrs);
     const sg = agsubg(this._context, name, true);
     if (sg === null) {
-      throw new RenderError(`Failed to create subgraph '${name}'`, "GENERIC_ERROR");
+      throw new InternalError(`Failed to create subgraph '${name}'`);
     }
     applyAttrs(sg.attrs, attrs);
     return new _GraphBuilder(this._graph, sg);
   }
   setAttr(k, v) {
+    requireKeyValue(k, v);
     this._context.attrs.set(k, v);
   }
   setHtmlAttr(k, v) {
+    requireKeyValue(k, v);
     this._context.attrs.set(k, HTML_STRING_MARK + v);
   }
   getAttr(k) {
+    requireString("k", k);
     return this._context.attrs.get(k);
   }
 };
 function addNodeToContext(root, context, name, attrs) {
+  requireString("name", name);
+  requireAttrs("attrs", attrs);
   const node = agnode(root, name, true);
-  if (node === null) throw new RenderError(`Failed to create node '${name}'`, "GENERIC_ERROR");
+  if (node === null) throw new InternalError(`Failed to create node '${name}'`);
   applyAttrs(node.attrs, attrs);
   if (context !== root) agsubnode(context, node, true);
   return new NodeHandle(node);
@@ -654,6 +771,7 @@ function resolveKind(opts) {
   return KIND_TABLE[`${d}:${s}`] ?? "directed";
 }
 function createGraph(opts) {
+  requireGraphOptions(opts);
   const g = new Graph(opts?.name ?? "", resolveKind(opts));
   return new GraphBuilder(g, g);
 }
@@ -747,11 +865,21 @@ function collectClusters(sg, yAxis, flipY, out) {
     collectClusters(c, yAxis, flipY, out);
   }
 }
+var Y_AXES = ["up", "down"];
+function checkGeometryOptions(opts) {
+  if (opts === void 0) return;
+  requireObject("opts", opts);
+  const y = opts.yAxis;
+  if (y !== void 0 && y !== "up" && y !== "down") {
+    throw invalidArgValue("opts.yAxis", y, Y_AXES);
+  }
+}
 function getLayout(g, opts) {
+  requireObject("g", g);
+  checkGeometryOptions(opts);
   if (g.info?.laidOut !== true) {
-    throw new RenderError(
-      "getLayout requires a laid-out graph; run ctx.layout(g, engine) or render() first",
-      "GENERIC_ERROR"
+    throw invalidState(
+      "getLayout requires a laid-out graph; run ctx.layout(g, engine) or render() first"
     );
   }
   const yAxis = opts?.yAxis ?? "down";