ts-graphviz 1.0.0 → 1.0.1

package/lib/core/index.d.ts

@@ -28,8 +28,11 @@ import {
   GraphAttributesObject,
   DotObjectModel,
 } from '#lib/common';
-import { ConvertOptions, PrintOptions } from '#lib/ast';
+import { ConvertFromModelOptions, PrintOptions } from '#lib/ast';
 
+/**
+ * @group Attribute
+ */
 interface AttributeKeyDict {
   /**
    * Factor damping force motions.
@@ -2510,27 +2513,26 @@ interface AttributeKeyDict {
    */
   z: 'z';
 }
-declare const attribute: AttributeKeyDict;
-
 /**
- * Classes implemented in the 'ts-graphviz' library are designed to inherit from this class.
+ * @group Attribute
  */
-declare abstract class GraphvizObject {}
+declare const attribute: AttributeKeyDict;
+
 /**
- * Classes implemented in the 'ts-graphviz' library that implement the `toDot` method are designed to inherit from this class.
+ * Base class for DOT objects.
+ * @group Models
  */
-declare abstract class DotObject extends GraphvizObject {}
+declare abstract class DotObject {}
 /**
+ * Base class for DOT objects with attributes.
+ * @group Models
  */
 declare abstract class AttributesBase<T extends AttributeKey> extends DotObject implements Attributes<T> {
   #private;
   constructor(attributes?: AttributesObject<T>);
   get values(): ReadonlyArray<[T, Attribute<T>]>;
-  /** The size of the attribute. */
   get size(): number;
-  /** The size of the attribute. */
   get(key: T): Attribute<T> | undefined;
-  /** Set a value to the attribute. */
   set(key: T, value: Attribute<T>): void;
   delete(key: T): void;
   apply(attributes: AttributesObject<T> | AttributesEntities<T>): void;
@@ -2538,13 +2540,14 @@ declare abstract class AttributesBase<T extends AttributeKey> extends DotObject
 }
 /**
  * A set of attribute values for any object.
+ * @group Models
  */
 declare class AttributesGroupModel<T extends AttributeKey = AttributeKey> extends AttributesBase<T> {
-  /** Comments to include when outputting with toDot. */
   comment?: string;
 }
 /**
  * A set of attribute values for any object.
+ * @group Models
  */
 declare class AttributeList<K extends AttributeListKind, T extends AttributeKey = AttributeKey>
   extends AttributesBase<T>
@@ -2552,362 +2555,55 @@ declare class AttributeList<K extends AttributeListKind, T extends AttributeKey
 {
   $$kind: K;
   get $$type(): 'AttributeList';
-  /** Comments to include when outputting with toDot. */
   comment?: string;
   constructor($$kind: K, attributes?: AttributesObject<T>);
 }
 /**
- * Base class for clusters.
- * @hidden
+ * Base class for Graph objects.
+ * @group Models
  */
 declare abstract class GraphBase<T extends AttributeKey> extends AttributesBase<T> implements GraphBaseModel<T> {
   #private;
-  /** Cluster ID */
   readonly id?: string;
-  /** Comments to include when outputting with toDot. */
   comment?: string;
-  /** Common attributes of objects in the cluster. */
   abstract readonly attributes: Readonly<GraphCommonAttributes>;
-  /**
-   * Nodes in the cluster.
-   * @hidden
-   */
   get nodes(): ReadonlyArray<NodeModel>;
-  /**
-   * Edges in the cluster.
-   * @hidden
-   */
   get edges(): ReadonlyArray<EdgeModel>;
-  /**
-   * Subgraphs in the cluster.
-   * @hidden
-   */
   get subgraphs(): ReadonlyArray<SubgraphModel>;
-  /**
-   * Add a Node to the cluster.
-   */
   addNode(node: NodeModel): void;
-  /**
-   * Add Edge to the cluster.
-   */
   addEdge(edge: EdgeModel): void;
-  /**
-   * Add a Subgraph to the cluster.
-   */
   addSubgraph(subgraph: SubgraphModel): void;
-  /**
-   * Check if the Node exists in the cluster.
-   */
   existNode(nodeId: string): boolean;
-  /**
-   * Check if the Edge exists in the cluster.
-   */
   existEdge(edge: EdgeModel): boolean;
-  /**
-   * Check if the Subgraph exists in the cluster.
-   */
   existSubgraph(subgraph: SubgraphModel): boolean;
-  /**
-   * Create a Subgraph and add it to the cluster.
-   */
   createSubgraph(id?: string, attributes?: SubgraphAttributesObject): SubgraphModel;
   createSubgraph(attributes?: SubgraphAttributesObject): SubgraphModel;
-  /**
-   * Remove Node from the cluster.
-   */
   removeNode(node: NodeModel | string): void;
-  /**
-   * Remove Edge from the cluster.
-   */
   removeEdge(edge: EdgeModel): void;
-  /**
-   * Remove Subgraph from the cluster.
-   */
   removeSubgraph(subgraph: SubgraphModel): void;
-  /**
-   * Create a Node in the cluster.
-   */
   createNode(id: string, attributes?: NodeAttributesObject): NodeModel;
-  /**
-   * Get Subgraph in cluster by specifying id.
-   *
-   * If there is no Subgraph with the specified id in the cluster, return undefined.
-   */
   getSubgraph(id: string): SubgraphModel | undefined;
-  /**EdgeAttributesObject
-   * Get Node in cluster by specifying id.
-   *
-   * @description
-   * If there is no Node with the specified id in the cluster, return undefined.
-   */
   getNode(id: string): NodeModel | undefined;
-  /** Create Edge and add it to the cluster. */
   createEdge(targets: EdgeTargetLikeTuple, attributes?: EdgeAttributesObject): EdgeModel;
-  /**
-   * Create a subgraph by specifying its id (or get it if it already exists).
-   *
-   * By specifying a callback function, the target subgraph can be received and manipulated as an argument.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Create a cluster with id as A.
-   *   g.subgraph('A', (A) => {
-   *     // Create a node with id as A1 in cluster A.
-   *     A.node('A1');
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   subgraph "A" {
-   * //     "A1";
-   * //   }
-   * // }
-   * ```
-   *
-   * @param id Subgraph ID.
-   * @param callback Callbacks for manipulating created or retrieved subgraph.
-   */
   subgraph(id: string, callback?: (subgraph: SubgraphModel) => void): SubgraphModel;
-  /**
-   * Create a subgraph (or get one if it already exists) and adapt the attributes.
-   *
-   * By specifying a callback function, the target subgraph can be received and manipulated as an argument.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Create a cluster with id as A and specifying its attributes.
-   *   g.subgraph('A', { [attribute.color]: 'red', [attribute.label]: 'my label' }, (A) => {
-   *     // Create a node with id as A1 in cluster A.
-   *     A.node('A1');
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   subgraph "A" {
-   * //     color = "red";
-   * //     label = "my label";
-   * //     "A1";
-   * //   }
-   * // }
-   * ```
-   *
-   * @param id  Subgraph ID.
-   * @param attributes Object of attributes to be adapted to the subgraph.
-   * @param callback Callbacks for manipulating created or retrieved subgraph.
-   */
   subgraph(
     id: string,
     attributes: SubgraphAttributesObject,
     callback?: (subgraph: SubgraphModel) => void,
   ): SubgraphModel;
-  /**
-   * Create anonymous subgraphs and and adapt the attributes.
-   *
-   * By specifying a callback function, the target subgraph can be received and manipulated as an argument.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Create a anonymous cluster and specifying its attributes.
-   *   g.subgraph({ [attribute.color]: 'red', [attribute.label]: 'my label' }, (A) => {
-   *     // Create a node with id as A1 in anonymous cluster.
-   *     A.node('A1');
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   subgraph {
-   * //     color = "red";
-   * //     label = "my label";
-   * //     "A1";
-   * //   }
-   * // }
-   * ```
-   *
-   * @param attributes Object of attributes to be adapted to the subgraph.
-   * @param callback Callbacks for manipulating created or retrieved subgraph.
-   */
   subgraph(attributes: SubgraphAttributesObject, callback?: (subgraph: SubgraphModel) => void): SubgraphModel;
-  /**
-   * Create anonymous subgraphs and manipulate them with callback functions.
-   *
-   * By specifying a callback function, the target subgraph can be received and manipulated as an argument.
-   *
-   * @param callback Callbacks for manipulating created or retrieved subgraph.
-   */
   subgraph(callback?: (subgraph: SubgraphModel) => void): SubgraphModel;
-  /**
-   * Create a node by specifying its id (or get it if it already exists).
-   *
-   * By specifying a callback function, the target node can be received and manipulated as an argument.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Create a node with id as A.
-   *   g.node('A');
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   "A";
-   * // }
-   * ```
-   *
-   * @param id Node ID.
-   * @param callback Callbacks for manipulating created or retrieved node.
-   */
   node(id: string, callback?: (node: NodeModel) => void): NodeModel;
-  /**
-   * Create a node (or get one if it already exists) and adapt the attributes.
-   *
-   * By specifying a callback function, the target node can be received and manipulated as an argument.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Create a node by specifying its id and specifying its attributes.
-   *   g.node('A', {
-   *     [attribute.color]: 'red',
-   *     [attribute.label]: 'my label',
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   "A" [
-   * //     color = "red",
-   * //     label = "my label",
-   * //   ];
-   * // }
-   * ```
-   *
-   * @param id Node ID.
-   * @param attributes Object of attributes to be adapted to the node.
-   * @param callback Callbacks for manipulating created or retrieved node.
-   */
   node(id: string, attributes: NodeAttributesObject, callback?: (node: NodeModel) => void): NodeModel;
-  /**
-   * Set a common attribute for the nodes in the cluster.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Set a common attribute for the nodes in the cluster.
-   *   g.node({
-   *     [attribute.color]: 'red',
-   *     [attribute.label]: 'my label',
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   node [
-   * //     color = "red",
-   * //     label = "my label",
-   * //   ];
-   * // }
-   * ```
-   *
-   * @param attributes Object of attributes to be adapted to the nodes.
-   */
   node(attributes: NodeAttributesObject): void;
-  /**
-   * Create a edge.
-   *
-   * By specifying a callback function, the target edge can be received and manipulated as an argument.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Create a edge.
-   *   g.edge(['a', 'b']);
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   "a" -> "b";
-   * // }
-   * ```
-   * @param targets Nodes.
-   * @param callback Callbacks for manipulating created or retrieved edge.
-   */
   edge(targets: EdgeTargetLikeTuple, callback?: (edge: EdgeModel) => void): EdgeModel;
-  /**
-   * Create a edge and adapt the attributes.
-   *
-   * By specifying a callback function, the target edge can be received and manipulated as an argument.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Create a edge and specifying its attributes.
-   *   g.edge(['a', 'b'], {
-   *     [attribute.color]: 'red',
-   *     [attribute.label]: 'my label',
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   "a" -> "b" [
-   * //     color = "red",
-   * //     label = "my label",
-   * //   ];
-   * // }
-   * ```
-   *
-   * @param targets Edge targets.
-   * @param attributes Object of attributes to be adapted to the edge.
-   * @param callback Callbacks for manipulating created or retrieved edge.
-   */
   edge(targets: EdgeTargetLikeTuple, attributes: EdgeAttributesObject, callback?: (edge: EdgeModel) => void): EdgeModel;
-  /**
-   * Set a common attribute for the edges in the cluster.
-   *
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   // Set a common attribute for the edges in the cluster.
-   *   g.edge({
-   *     [attribute.color]: 'red',
-   *     [attribute.label]: 'my label',
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   edge [
-   * //     color = "red",
-   * //     label = "my label",
-   * //   ];
-   * // }
-   * ```
-   * @param attributes Object of attributes to be adapted to the edges.
-   */
   edge(attributes: EdgeAttributesObject): void;
-  /**
-   * Set a common attribute for the clusters in the cluster.
-   *
-   * ```ts
-   * const G = digraph('G', (g) => {
-   *   g.graph({
-   *     [attribute.color]: 'red',
-   *     [attribute.label]: 'my label',
-   *   });
-   * });
-   *
-   * console.log(toDot(G));
-   * // digraph "G" {
-   * //   graph [
-   * //     color = "red",
-   * //     label = "my label",
-   * //   ];
-   * // }
-   * ```
-   * @param attributes Object of attributes to be adapted to the clusters.
-   */
   graph(attributes: SubgraphAttributesObject): void;
 }
 /**
- * Subgraph object.
+ * DOT object class representing a subgraph.
+ * @group Models
  */
 declare class Subgraph extends GraphBase<SubgraphAttributeKey | ClusterSubgraphAttributeKey> implements SubgraphModel {
   get $$type(): 'Subgraph';
@@ -2919,49 +2615,39 @@ declare class Subgraph extends GraphBase<SubgraphAttributeKey | ClusterSubgraphA
   }>;
   constructor(id?: string, attributes?: SubgraphAttributesObject);
   constructor(attributes?: SubgraphAttributesObject);
-  /** Determines whether the Subgraph is a SubgraphCluster. */
   isSubgraphCluster(): boolean;
 }
 /**
- * Node object.
+ * DOT object class representing a node.
+ * @group Models
  */
 declare class Node extends DotObject implements NodeModel {
   readonly id: string;
   get $$type(): 'Node';
-  /** Comments to include when outputting with toDot. */
   comment?: string;
   readonly attributes: AttributesGroup<NodeAttributeKey>;
   constructor(id: string, attributes?: NodeAttributesObject);
-  /** Returns ForwardRefNode with port and compass specified. */
   port(port: string | Partial<Port>): ForwardRefNode;
 }
 /**
+ * DOT object class representing a edge.
+ * @group Models
  */
 declare class Edge extends DotObject implements EdgeModel {
   readonly targets: EdgeTargetTuple;
   get $$type(): 'Edge';
-  /** Comments to include when outputting with toDot. */
   comment?: string;
   readonly attributes: AttributesGroup<EdgeAttributeKey>;
   constructor(targets: EdgeTargetTuple, attributes?: EdgeAttributesObject);
 }
 /**
- * Base class for RootGraph.
- *
+ * Base class representing a root graph(digraph, graph).
+ * @group Models
  */
 declare abstract class RootGraph extends GraphBase<GraphAttributeKey> implements RootGraphModel {
   get $$type(): 'Graph';
   readonly id?: string;
   abstract readonly directed: boolean;
-  /**
-   * Strict mode.
-   *
-   * @description
-   * A graph may also be described as strict.
-   * This forbids the creation of multi-edges, i.e., there can be at most one edge with a given tail node and head node in the directed case.
-   * For undirected graphs, there can be at most one edge connected to the same two nodes.
-   * Subsequent edge statements using the same two nodes will identify the edge with the previously defined one and apply any attributes given in the edge statement.
-   */
   strict: boolean;
   attributes: Readonly<{
     graph: AttributeList<'Graph', ClusterSubgraphAttributeKey | 'rank'>;
@@ -2973,35 +2659,66 @@ declare abstract class RootGraph extends GraphBase<GraphAttributeKey> implements
   constructor(strict?: boolean, attributes?: GraphAttributesObject);
   constructor(attributes?: GraphAttributesObject);
 }
+/**
+ * DOT object class representing a graph.
+ * @group Models
+ */
 declare class Graph extends RootGraph {
   get directed(): boolean;
 }
+/**
+ * DOT object class representing a digraph.
+ * @group Models
+ */
 declare class Digraph extends RootGraph {
   get directed(): boolean;
 }
 
+/**
+ * @group Model Builder
+ */
 interface CreateRootGraph {
   (id?: string, attributes?: GraphAttributesObject, callback?: (g: RootGraphModel) => void): RootGraphModel;
   (attributes?: GraphAttributesObject, callback?: (g: RootGraphModel) => void): RootGraphModel;
   (id?: string, callback?: (g: RootGraphModel) => void): RootGraphModel;
   (callback?: (g: RootGraphModel) => void): RootGraphModel;
 }
-/** API for creating directional graph objects. */
+/**
+ * API for creating directional graph objects.
+ * @group Model Builder
+ */
 declare const digraph: CreateRootGraph;
-/** API for creating omnidirectional graph objects. */
+/**
+ * API for creating omnidirectional graph objects.
+ * @group Model Builder
+ */
 declare const graph: CreateRootGraph;
-/** Provides a strict mode API. */
-declare const strict: Readonly<{
-  /** API for creating directional graph objects in strict mode. */
+/**
+ * Provides a strict mode API.
+ * @group Model Builder
+ */
+declare const strict: {
   digraph: CreateRootGraph;
-  /** API for creating omnidirectional graph objects in strict mode. */
   graph: CreateRootGraph;
-}>;
+};
 
+/**
+ * @group Convert Model to DOT
+ * @alpha
+ */
 interface ToDotOptions {
-  convert?: ConvertOptions;
+  convert?: ConvertFromModelOptions;
   print?: PrintOptions;
 }
+/**
+ * Convert Model to DOT string.
+ *
+ * @group Convert Model to DOT
+ *
+ * @param model Dot Object Model, like {@link Digraph}, {@link Graph}, {@link Node}, and {@link Edge}
+ * @param options
+ * @returns DOT string
+ */
 declare function toDot(model: DotObjectModel, options?: ToDotOptions): string;
 
 export {
@@ -3009,12 +2726,12 @@ export {
   AttributeList,
   AttributesBase,
   AttributesGroupModel,
+  CreateRootGraph,
   Digraph,
   DotObject,
   Edge,
   Graph,
   GraphBase,
-  GraphvizObject,
   Node,
   RootGraph,
   Subgraph,