ts-graphviz 1.0.0 → 1.0.1

package/lib/common/index.cjs

@@ -2,24 +2,31 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+/** @hidden */
 function isForwardRefNode(object) {
   return typeof object === 'object' && object !== null && typeof object.id === 'string';
 }
+/** @hidden */
 function isNodeModel(object) {
   return typeof object === 'object' && object !== null && object.$$type === 'Node' && typeof object.id === 'string';
 }
+/** @hidden */
 function isNodeRef(node) {
   return isNodeModel(node) || isForwardRefNode(node);
 }
+/** @hidden */
 function isNodeRefLike(node) {
   return typeof node === 'string' || isNodeRef(node);
 }
+/** @hidden */
 function isNodeRefGroupLike(target) {
   return Array.isArray(target) && target.every(isNodeRefLike);
 }
+/** @hidden */
 function isCompass(c) {
   return ['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', 'c'].includes(c);
 }
+/** @hidden */
 function toNodeRef(target) {
   if (isNodeRef(target)) {
     return target;
@@ -30,6 +37,7 @@ function toNodeRef(target) {
   }
   return { id, port };
 }
+/** @hidden */
 function toNodeRefGroup(targets) {
   if (targets.length < 2 && (isNodeRefLike(targets[0]) && isNodeRefLike(targets[1])) === false) {
     throw Error('EdgeTargets must have at least 2 elements.');

package/lib/common/index.d.ts

@@ -1,29 +1,34 @@
 /**
  * Directive indicating which direction the Edge should point.
+ * @group Attribute Types
  */
 declare type Compass = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw' | 'c' | '_';
 /**
  * A double with an optional prefix `'+'`.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/addDouble/ addDouble}
+ * @group Attribute Types
  */
 declare type AddDouble = `+${Double}`;
 /**
  * Double-precision floating point number.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/double/ double}
+ * @group Attribute Types
  */
 declare type Double = number;
 /**
  * Port Position
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/portPos/ portPos}
+ * @group Attribute Types
  */
 declare type PortPos = `${string}:${Compass}` | Compass;
 /**
  * A colon-separated list of doubles: `"%f(:%f)*"` where each %f is a double.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/doubleList/ doubleList}
+ * @group Attribute Types
  */
 declare type DoubleList =
   | Double
@@ -39,20 +44,25 @@ declare type DoubleList =
  * Integer number.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/int/ int}
+ * @group Attribute Types
  */
 declare type Int = number;
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/shape/ shape}
+ * @group Attribute Types
  */
 declare type Shape = string;
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/smoothType/ smoothType}
+ * @group Attribute Types
  */
 declare type SmoothType = 'none' | 'avg_dist' | 'graph_dist' | 'power_dist' | 'rng' | 'spring' | 'triangle';
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/splineType/ splineType}
+ * @group Attribute Types
  */
 declare type SplineType = SplineType.spline | string;
+/** @hidden */
 declare namespace SplineType {
   type prefix = endp | startp | `${endp}${startp}` | '';
   type spline = `${prefix}point ${triple}`;
@@ -62,20 +72,24 @@ declare namespace SplineType {
 }
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/startType/ startType}
+ * @group Attribute Types
  */
 declare type StartType = `${StartType.style}${StartType.seed}`;
+/** @hidden */
 declare namespace StartType {
   type style = 'regular' | 'self' | 'random';
   type seed = number;
 }
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/style/ style}
+ * @group Attribute Types
  */
 declare type Style =
   | Style.styleItem
   | `${Style.styleItem},${Style.styleItem}`
   | `${Style.styleItem},${Style.styleItem},${Style.styleItem}`
   | `${Style.styleItem},${Style.styleItem},${Style.styleItem},${Style.styleItem}`;
+/** @hidden */
 declare namespace Style {
   type styleItem =
     | 'dashed'
@@ -96,6 +110,7 @@ declare namespace Style {
 }
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/viewPort/ viewPort}
+ * @group Attribute Types
  */
 declare type ViewPort = `${Double},${Double},${Double},${Double},${Double}` | `${Double},${Double},${Double},${string}`;
 /**
@@ -103,12 +118,14 @@ declare type ViewPort = `${Double},${Double},${Double},${Double},${Double}` | `$
  * defining layer names and implicitly numbered 1,2,…
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/layerList/ layerList}
+ * @group Attribute Types
  */
 declare type LayerList = string;
 /**
  * specifies a list of layers defined by the layers attribute.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/layerRange/ layerRange}
+ * @group Attribute Types
  */
 declare type LayerRange = string;
 /**
@@ -130,16 +147,19 @@ declare type LayerRange = string;
  *
  * In all cases, the substring `"\L"` is replaced by the object's label attribute.
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/escString/ escString}
+ * @group Attribute Types
  */
 declare type EscString = string;
 /**
  * @see {@link https://graphviz.org/doc/info/shapes.html#html HTML-Like Labels}
+ * @group Attribute Types
  */
 declare type HTMLLikeLabel = `<${string}>`;
 /**
  * An escString or an HTML label.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/lblString/ lblString}
+ * @group Attribute Types
  */
 declare type LblString = HTMLLikeLabel | EscString;
 /**
@@ -148,8 +168,10 @@ declare type LblString = HTMLLikeLabel | EscString;
  * The optional `'!'` indicates the node position should not change (input-only).
  *
  * If dim=3, point may also have the format `"%f,%f,%f('!')?"` to represent the point (x,y,z).
+ * @group Attribute Types
  */
 declare type Point = Point.position | `${Point.position}!`;
+/** @hidden */
 declare namespace Point {
   type position =
     | `%${Double},%${Double}`
@@ -165,10 +187,12 @@ declare namespace Point {
  * A point with an optional prefix `'+'`.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/addPoint/ addPoint}
+ * @group Attribute Types
  */
 declare type AddPoint = `+${Point}`;
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/pointList/ pointList}
+ * @group Attribute Types
  */
 declare type PointList =
   | Point
@@ -183,10 +207,12 @@ declare type PointList =
  * - On the other hand, usually for aesthetic reasons, it may be desirable that all edges appear beneath nodes, even if the resulting drawing is ambiguous. This can be achieved by choosing `"edgesfirst"`.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/outputMode/ outputMode}
+ * @group Attribute Types
  */
 declare type OutputMode = 'breadthfirst' | 'nodesfirst' | 'edgesfirst';
 /**
  * @see {@link https://graphviz.org/docs/attr-types/packMode/ packMode}
+ * @group Attribute Types
  */
 declare type PackMode = 'node' | 'clust' | 'graph' | `array${string}`;
 /**
@@ -194,6 +220,7 @@ declare type PackMode = 'node' | 'clust' | 'graph' | `array${string}`;
  * though layout quality can suffer a little.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/quadType/ quadType}
+ * @group Attribute Types
  */
 declare type QuadType = 'normal' | 'fast' | 'none';
 /**
@@ -203,10 +230,12 @@ declare type QuadType = 'normal' | 'fast' | 'none';
  * from left to right, from bottom to top, and from right to left, respectively.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/rankdir/ rankdir}
+ * @group Attribute Types
  */
 declare type Rankdir = 'TB' | 'LR' | 'BT' | 'RL';
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/rankType/ rankType}
+ * @group Attribute Types
  */
 declare type RankType = 'same' | 'min' | 'source' | 'max' | 'sink';
 /**
@@ -216,6 +245,7 @@ declare type RankType = 'same' | 'min' | 'source' | 'max' | 'sink';
  * of the lower-left corner `(llx,lly)` and the upper-right corner `(urx,ury)`.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/rect/ rect}
+ * @group Attribute Types
  */
 declare type Rect = `${Double},${Double},${Double},${Double}`;
 /**
@@ -225,8 +255,10 @@ declare type Rect = `${Double},${Double},${Double},${Double}`;
  * combinations of the 42 variations of the primitive set of 11 arrows.
  *
  * @see {@link https://graphviz.org/docs/attr-types/arrowType/ arrowType}
+ * @group Attribute Types
  */
 declare type ArrowType = ArrowType.aname | `${ArrowType.aname}${ArrowType.aname}`;
+/** @hidden */
 declare namespace ArrowType {
   type shape = 'box' | 'crow' | 'curve' | 'icurve' | 'diamond' | 'dot' | 'inv' | 'none' | 'normal' | 'tee' | 'vee';
   type side = 'l' | 'r';
@@ -235,12 +267,15 @@ declare namespace ArrowType {
 }
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/clusterMode/ clusterMode}
+ * @group Attribute Types
  */
 declare type ClusterMode = 'local' | 'global' | 'none';
 /**
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/color/ color}
+ * @group Attribute Types
  */
 declare type Color = Color.RGB_RGBA | Color.HSV | Color.ColorName | number;
+/** @hidden */
 declare namespace Color {
   /**
    * `"#%2x%2x%2x"` Red-Green-Blue (RGB)
@@ -1095,20 +1130,24 @@ declare namespace Color {
  * @note A type that is too complicated to express in TypeScript.
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/colorList/}
+ * @group Attribute Types
  */
 declare type ColorList = string;
 /**
  * Direction Type
  *
  * @see {@link https://graphviz.gitlab.io/docs/attr-types/dirType/ dirType}
+ * @group Attribute Types
  */
 declare type DirType = 'forward' | 'back' | 'both' | 'none';
 /**
  * Page Direction
  *
  * @see {@link https://graphviz.org/docs/attr-types/pagedir/ pagedir}
+ * @group Attribute Types
  */
 declare type Pagedir = `${Pagedir.TB}${Pagedir.RL}`;
+/** @hidden */
 declare namespace Pagedir {
   type TB = 'T' | 'B';
   type RL = 'R' | 'L';
@@ -1116,6 +1155,7 @@ declare namespace Pagedir {
 
 /**
  * Attribute types available for edges.
+ * @group Attribute
  */
 declare type EdgeAttributeKey =
   | 'URL'
@@ -1186,6 +1226,7 @@ declare type EdgeAttributeKey =
   | '_class';
 /**
  * Attribute types available for nodes.
+ * @group Attribute
  */
 declare type NodeAttributeKey =
   | 'URL'
@@ -1239,6 +1280,7 @@ declare type NodeAttributeKey =
   | '_class';
 /**
  * Attribute types available for graph.
+ * @group Attribute
  */
 declare type GraphAttributeKey =
   | 'Damping'
@@ -1342,10 +1384,12 @@ declare type GraphAttributeKey =
   | '_class';
 /**
  * Attribute types available for subgraph.
+ * @group Attribute
  */
 declare type SubgraphAttributeKey = 'rank';
 /**
  * Attribute types available for cluster subgraph.
+ * @group Attribute
  */
 declare type ClusterSubgraphAttributeKey =
   | 'K'
@@ -1380,6 +1424,7 @@ declare type ClusterSubgraphAttributeKey =
   | '_class';
 /**
  * Attribute types.
+ * @group Attribute
  */
 declare type AttributeKey =
   | NodeAttributeKey
@@ -1562,8 +1607,14 @@ interface KeyValueMapping {
   xlp: Point;
   z: Double;
 }
+/**
+ * @group Attribute
+ */
 declare type Attribute<T extends AttributeKey> = KeyValueMapping[T];
 
+/**
+ * @group Models
+ */
 declare type ASTType =
   | 'Literal'
   | 'Dot'
@@ -1578,87 +1629,205 @@ declare type ASTType =
   | 'Subgraph';
 /**
  * Objects that can be Edge destinations satisfy this interface.
+ * @group Models
  */
 declare type NodeRef = NodeModel | ForwardRefNode;
+/**
+ * @group Models
+ */
 declare type NodeRefGroup = NodeRef[];
 /**
- * string or an object implementing IEdgeTarget.
+ * string or an object implementing EdgeTarget.
+ * @group Models
  */
 declare type NodeRefLike = NodeRef | string;
+/**
+ * @group Models
+ */
 declare type NodeRefGroupLike = NodeRefLike[];
+/**
+ * @group Models
+ */
 declare type EdgeTarget = NodeRef | NodeRefGroup;
+/**
+ * @group Models
+ */
 declare type EdgeTargetLike = NodeRefLike | NodeRefGroupLike;
+/**
+ * @group Models
+ */
 declare type EdgeTargetTuple = [from: EdgeTarget, to: EdgeTarget, ...rest: EdgeTarget[]];
+/**
+ * @group Models
+ */
 declare type EdgeTargetLikeTuple = [from: EdgeTargetLike, to: EdgeTargetLike, ...rest: EdgeTargetLike[]];
+/**
+ * An objects of attribute key/value pairs.
+ * @group Models
+ */
 declare type AttributesObject<T extends AttributeKey> = {
   [K in T]?: Attribute<K>;
 };
+/**
+ * @group Models
+ */
 declare type AttributeValue = Attribute<AttributeKey>;
+/**
+ * An array of attribute key/value tuple.
+ * @group Models
+ */
 declare type AttributesEntities<T extends AttributeKey> = readonly [T, Attribute<T>][];
+/**
+ * Attribute object that can be set to Edge.
+ * @group Models
+ */
 declare type EdgeAttributesObject = AttributesObject<EdgeAttributeKey>;
+/**
+ * Attribute object that can be set to Node.
+ * @group Models
+ */
 declare type NodeAttributesObject = AttributesObject<NodeAttributeKey>;
+/**
+ * Attribute object that can be set to Graph.
+ * @group Models
+ */
 declare type GraphAttributesObject = AttributesObject<GraphAttributeKey>;
+/**
+ * Attribute object that can be set to Subgraph.
+ * @group Models
+ */
 declare type SubgraphAttributesObject = AttributesObject<ClusterSubgraphAttributeKey | SubgraphAttributeKey>;
+/**
+ * @group Models
+ */
 declare type DotObjectType = 'AttributeList' | 'Node' | 'Edge' | 'Subgraph' | 'Graph';
+/**
+ * @group Models
+ */
 interface DotObjectModel<T extends DotObjectType = DotObjectType> {
   $$type: T;
 }
+/**
+ * @group Models
+ */
 interface HasComment {
   /** Comments to include when outputting with toDot. */
   comment?: string;
 }
+/**
+ * @group Models
+ */
 interface HasAttributes<T extends AttributeKey> {
   readonly attributes: AttributesGroup<T>;
 }
+/**
+ * @group Models
+ */
 interface ForwardRefNode extends Partial<Port> {
   readonly id: string;
 }
+/**
+ * DOT object with the property
+ * that attributes can be held as a set of keys and values.
+ *
+ * @typeParam T - The attribute keys to set DOT object.
+ * @group Models
+ */
 interface Attributes<T extends AttributeKey> {
+  /** Size of the set of keys and values held by the DOT object. */
   readonly size: number;
+  /** The key/value tuples of the object attributes. */
   readonly values: ReadonlyArray<[T, Attribute<T>]>;
+  /**
+   * Get the value of an attribute by a DOT object by specifying its key.
+   *
+   * If the value corresponding to the key does not exist, undefined is returned.
+   */
   get(key: T): Attribute<T> | undefined;
+  /** Set a value, by specifying the key of the attributes in the DOT object. */
   set(key: T, value: Attribute<T>): void;
+  /**
+   * Apply keys and values that can be specified for DOT objects collectively.
+   *
+   * @param attributes - An array of objects or tuples of attribute key/value pairs.
+   */
   apply(attributes: AttributesObject<T> | AttributesEntities<T>): void;
+  /** Delete the value of an attribute from a DOT object by specifying a key. */
   delete(key: T): void;
+  /** Delete all attributes specified for the DOT object. */
   clear(): void;
 }
+/**
+ * @group Models
+ */
 interface AttributesGroup<T extends AttributeKey> extends Attributes<T>, HasComment {}
+/**
+ * @group Models
+ */
 declare type AttributeListKind = 'Graph' | 'Edge' | 'Node';
+/**
+ * A list object of attributes commonly specified for nodes, subgraphs, and edges
+ * under graph and subgraph.
+ *
+ * @typeParam K - The type of object is being specified.
+ * @typeParam T - The attribute keys to set DOT object.
+ * @group Models
+ */
 interface AttributeListModel<K extends AttributeListKind = AttributeListKind, T extends AttributeKey = AttributeKey>
   extends Attributes<T>,
     HasComment,
     DotObjectModel<'AttributeList'> {
   $$kind: K;
 }
+/**
+ * Port on an edge node.
+ * @group Models
+ */
 interface Port {
   port: string;
   compass: Compass;
 }
+/**
+ * Model that can be converted to Node in DOT language.
+ * @group Models
+ */
 interface NodeModel extends HasComment, HasAttributes<NodeAttributeKey>, DotObjectModel<'Node'> {
+  /** ID of the node */
   readonly id: string;
+  /** Returns ForwardRefNode with port and compass specified. */
   port(port: string | Partial<Port>): ForwardRefNode;
 }
+/**
+ * Model that can be converted to Edge in DOT language.
+ * @group Models
+ */
 interface EdgeModel extends HasComment, HasAttributes<EdgeAttributeKey>, DotObjectModel<'Edge'> {
   readonly targets: EdgeTargetTuple;
 }
 /**
  * Cluster common attribute interface.
- *
- * @hidden
+ * @group Models
  */
 interface GraphCommonAttributes {
-  /** Manage common attributes of graphs in a cluster. */
+  /** Manage common attributes of graphs in a graph. */
   graph: AttributeListModel<'Graph', SubgraphAttributeKey | ClusterSubgraphAttributeKey>;
-  /** Manage common attributes of edges in a cluster. */
+  /** Manage common attributes of edges in a graph. */
   edge: AttributeListModel<'Edge', EdgeAttributeKey>;
-  /** Manage common attributes of nodes in a cluster. */
+  /** Manage common attributes of nodes in a graph. */
   node: AttributeListModel<'Node', NodeAttributeKey>;
 }
+/**
+ * DOT model representing a graph/digraph/subgraph.
+ * @group Models
+ */
 interface GraphBaseModel<T extends AttributeKey = AttributeKey> extends HasComment, Attributes<T> {
   readonly id?: string;
   readonly attributes: Readonly<GraphCommonAttributes>;
+  /** Node objects in the graph. */
   readonly nodes: ReadonlyArray<NodeModel>;
+  /** Edge objects in the graph. */
   readonly edges: ReadonlyArray<EdgeModel>;
+  /** Subgraph objects in the graph. */
   readonly subgraphs: ReadonlyArray<SubgraphModel>;
   /**
    * Add a Node to the graph.
@@ -1702,6 +1871,9 @@ interface GraphBaseModel<T extends AttributeKey = AttributeKey> extends HasComme
   createNode(id: string, attributes?: NodeAttributesObject): NodeModel;
   /**
    * Create a Subgraph and add it to the graph.
+   *
+   * @param id - Subgraph ID
+   * @param attributes - Subgraph attribute object
    */
   createSubgraph(id?: string, attributes?: SubgraphAttributesObject): SubgraphModel;
   createSubgraph(attributes?: SubgraphAttributesObject): SubgraphModel;
@@ -1982,11 +2154,20 @@ interface GraphBaseModel<T extends AttributeKey = AttributeKey> extends HasComme
    */
   graph(attributes: SubgraphAttributesObject): void;
 }
+/**
+ * DOT model representing a subgraph.
+ * @group Models
+ */
 interface SubgraphModel
   extends GraphBaseModel<SubgraphAttributeKey | ClusterSubgraphAttributeKey>,
     DotObjectModel<'Subgraph'> {
+  /** Determines whether the Subgraph is a SubgraphCluster. */
   isSubgraphCluster(): boolean;
 }
+/**
+ * DOT model representing a root graphs(digraph and graph).
+ * @group Models
+ */
 interface RootGraphModel extends GraphBaseModel<GraphAttributeKey>, DotObjectModel<'Graph'> {
   directed: boolean;
   /**
@@ -2000,13 +2181,21 @@ interface RootGraphModel extends GraphBaseModel<GraphAttributeKey>, DotObjectMod
    */
   strict: boolean;
 }
+/** @hidden */
 declare function isForwardRefNode(object: unknown): object is ForwardRefNode;
+/** @hidden */
 declare function isNodeModel(object: unknown): object is NodeModel;
+/** @hidden */
 declare function isNodeRef(node: unknown): node is NodeRef;
+/** @hidden */
 declare function isNodeRefLike(node: unknown): node is NodeRefLike;
+/** @hidden */
 declare function isNodeRefGroupLike(target: NodeRefLike | NodeRefGroupLike): target is NodeRefGroupLike;
+/** @hidden */
 declare function isCompass(c: string): c is Compass;
+/** @hidden */
 declare function toNodeRef(target: NodeRefLike): NodeRef;
+/** @hidden */
 declare function toNodeRefGroup(targets: NodeRefGroupLike): NodeRefGroup;
 
 export {

package/lib/common/index.js

@@ -1,21 +1,28 @@
+/** @hidden */
 function isForwardRefNode(object) {
   return typeof object === 'object' && object !== null && typeof object.id === 'string';
 }
+/** @hidden */
 function isNodeModel(object) {
   return typeof object === 'object' && object !== null && object.$$type === 'Node' && typeof object.id === 'string';
 }
+/** @hidden */
 function isNodeRef(node) {
   return isNodeModel(node) || isForwardRefNode(node);
 }
+/** @hidden */
 function isNodeRefLike(node) {
   return typeof node === 'string' || isNodeRef(node);
 }
+/** @hidden */
 function isNodeRefGroupLike(target) {
   return Array.isArray(target) && target.every(isNodeRefLike);
 }
+/** @hidden */
 function isCompass(c) {
   return ['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', 'c'].includes(c);
 }
+/** @hidden */
 function toNodeRef(target) {
   if (isNodeRef(target)) {
     return target;
@@ -26,6 +33,7 @@ function toNodeRef(target) {
   }
   return { id, port };
 }
+/** @hidden */
 function toNodeRefGroup(targets) {
   if (targets.length < 2 && (isNodeRefLike(targets[0]) && isNodeRefLike(targets[1])) === false) {
     throw Error('EdgeTargets must have at least 2 elements.');