ts-graphviz 1.0.1 → 1.1.0

package/README.ja.md

@@ -156,7 +156,7 @@ const dot = toDot(g);
 
 #### 宣言的な API 😎
 
-`Graph` や `Digraph` を作成する際に、より **DOT** 言語に近い記法を提供するために _Builder Functuion_ を使うことができます。
+`Graph` や `Digraph` を作成する際に、より **DOT** 言語に近い記法を提供するために _Model Factory_ を使うことができます。
 
 **Model** にも宣言的な API を用意しており、一貫して宣言的なパラダイムを選択することもできます。
 

package/README.md

@@ -155,7 +155,7 @@ const dot = toDot(g);
 
 #### Declarative API 😎
 
-When creating `Graph` or `Digraph`, you can use _Builder Function_ to provide a notation more similar to the **DOT** language.
+When creating `Graph` or `Digraph`, you can use _Model Factory_ to provide a notation more similar to the **DOT** language.
 
 **Model** also has a declarative API, so you can consistently choose a declarative paradigm.
 

package/lib/common/index.cjs

@@ -2,6 +2,8 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+require('#lib/core');
+
 /** @hidden */
 function isForwardRefNode(object) {
   return typeof object === 'object' && object !== null && typeof object.id === 'string';
@@ -45,6 +47,28 @@ function toNodeRefGroup(targets) {
   return targets.map((t) => toNodeRef(t));
 }
 
+/**
+ * @group Models Context
+ * @alpha
+ */
+const RootModelsContext = Object.seal({
+  // NOTE: RootModelsContext is also initialized after the model class is declared in the '#lib/core' module.
+  Graph: null,
+  Digraph: null,
+  Subgraph: null,
+  Node: null,
+  Edge: null,
+});
+/**
+ * @group Models Context
+ * @alpha
+ */
+function createModelsContext(models) {
+  return Object.assign(Object.seal(Object.assign({}, RootModelsContext)), models);
+}
+
+exports.RootModelsContext = RootModelsContext;
+exports.createModelsContext = createModelsContext;
 exports.isCompass = isCompass;
 exports.isForwardRefNode = isForwardRefNode;
 exports.isNodeModel = isNodeModel;

package/lib/common/index.d.ts

@@ -1612,6 +1612,28 @@ interface KeyValueMapping {
  */
 declare type Attribute<T extends AttributeKey> = KeyValueMapping[T];
 
+/**
+ * @group Models Context
+ * @beta
+ */
+interface ModelsContext {
+  Graph: RootGraphConstructor;
+  Digraph: RootGraphConstructor;
+  Subgraph: SubgraphConstructor;
+  Node: NodeConstructor;
+  Edge: EdgeConstructor;
+}
+/**
+ * @group Models Context
+ * @alpha
+ */
+declare const RootModelsContext: ModelsContext;
+/**
+ * @group Models Context
+ * @alpha
+ */
+declare function createModelsContext(models: Partial<ModelsContext>): ModelsContext;
+
 /**
  * @group Models
  */
@@ -1718,7 +1740,7 @@ interface HasComment {
  * @group Models
  */
 interface HasAttributes<T extends AttributeKey> {
-  readonly attributes: AttributesGroup<T>;
+  readonly attributes: AttributesGroupModel<T>;
 }
 /**
  * @group Models
@@ -1760,7 +1782,7 @@ interface Attributes<T extends AttributeKey> {
 /**
  * @group Models
  */
-interface AttributesGroup<T extends AttributeKey> extends Attributes<T>, HasComment {}
+interface AttributesGroupModel<T extends AttributeKey> extends Attributes<T>, HasComment {}
 /**
  * @group Models
  */
@@ -1829,6 +1851,10 @@ interface GraphBaseModel<T extends AttributeKey = AttributeKey> extends HasComme
   readonly edges: ReadonlyArray<EdgeModel>;
   /** Subgraph objects in the graph. */
   readonly subgraphs: ReadonlyArray<SubgraphModel>;
+  /**
+   * @beta
+   */
+  with(models: Partial<ModelsContext>): void;
   /**
    * Add a Node to the graph.
    */
@@ -2181,6 +2207,42 @@ interface RootGraphModel extends GraphBaseModel<GraphAttributeKey>, DotObjectMod
    */
   strict: boolean;
 }
+/**
+ * @group Models
+ * @beta
+ */
+interface RootGraphConstructor {
+  new (id?: string, attributes?: GraphAttributesObject): RootGraphModel;
+  new (id?: string, strict?: boolean, attributes?: GraphAttributesObject): RootGraphModel;
+  new (strict?: boolean, attributes?: GraphAttributesObject): RootGraphModel;
+  new (attributes?: GraphAttributesObject): RootGraphModel;
+  new (...args: any[]): RootGraphModel;
+}
+/**
+ * @group Models
+ * @beta
+ */
+interface SubgraphConstructor {
+  new (id?: string, attributes?: SubgraphAttributesObject): SubgraphModel;
+  new (attributes?: SubgraphAttributesObject): SubgraphModel;
+  new (...args: any[]): SubgraphModel;
+}
+/**
+ * @group Models
+ * @beta
+ */
+interface NodeConstructor {
+  new (id: string, attributes?: NodeAttributesObject): NodeModel;
+  new (...args: any[]): NodeModel;
+}
+/**
+ * @group Models
+ * @beta
+ */
+interface EdgeConstructor {
+  new (targets: EdgeTargetTuple, attributes?: EdgeAttributesObject): EdgeModel;
+  new (...args: any[]): EdgeModel;
+}
 /** @hidden */
 declare function isForwardRefNode(object: unknown): object is ForwardRefNode;
 /** @hidden */
@@ -2210,7 +2272,7 @@ export {
   AttributeValue,
   Attributes,
   AttributesEntities,
-  AttributesGroup,
+  AttributesGroupModel,
   AttributesObject,
   ClusterMode,
   ClusterSubgraphAttributeKey,
@@ -2224,6 +2286,7 @@ export {
   DoubleList,
   EdgeAttributeKey,
   EdgeAttributesObject,
+  EdgeConstructor,
   EdgeModel,
   EdgeTarget,
   EdgeTargetLike,
@@ -2242,8 +2305,10 @@ export {
   LayerList,
   LayerRange,
   LblString,
+  ModelsContext,
   NodeAttributeKey,
   NodeAttributesObject,
+  NodeConstructor,
   NodeModel,
   NodeRef,
   NodeRefGroup,
@@ -2260,7 +2325,9 @@ export {
   RankType,
   Rankdir,
   Rect,
+  RootGraphConstructor,
   RootGraphModel,
+  RootModelsContext,
   Shape,
   SmoothType,
   SplineType,
@@ -2268,8 +2335,10 @@ export {
   Style,
   SubgraphAttributeKey,
   SubgraphAttributesObject,
+  SubgraphConstructor,
   SubgraphModel,
   ViewPort,
+  createModelsContext,
   isCompass,
   isForwardRefNode,
   isNodeModel,

package/lib/common/index.js

@@ -1,3 +1,5 @@
+import '#lib/core';
+
 /** @hidden */
 function isForwardRefNode(object) {
   return typeof object === 'object' && object !== null && typeof object.id === 'string';
@@ -41,7 +43,29 @@ function toNodeRefGroup(targets) {
   return targets.map((t) => toNodeRef(t));
 }
 
+/**
+ * @group Models Context
+ * @alpha
+ */
+const RootModelsContext = Object.seal({
+  // NOTE: RootModelsContext is also initialized after the model class is declared in the '#lib/core' module.
+  Graph: null,
+  Digraph: null,
+  Subgraph: null,
+  Node: null,
+  Edge: null,
+});
+/**
+ * @group Models Context
+ * @alpha
+ */
+function createModelsContext(models) {
+  return Object.assign(Object.seal(Object.assign({}, RootModelsContext)), models);
+}
+
 export {
+  RootModelsContext,
+  createModelsContext,
   isCompass,
   isForwardRefNode,
   isNodeModel,

package/lib/core/index.cjs

@@ -17,6 +17,7 @@ const attribute = new Proxy(Object.freeze({}), {
  * @group Models
  */
 class DotObject {}
+
 /**
  * Base class for DOT objects with attributes.
  * @group Models
@@ -57,13 +58,7 @@ class AttributesBase extends DotObject {
     this.#attrs.clear();
   }
 }
-/**
- * A set of attribute values for any object.
- * @group Models
- */
-class AttributesGroupModel extends AttributesBase {
-  comment;
-}
+
 /**
  * A set of attribute values for any object.
  * @group Models
@@ -79,13 +74,21 @@ class AttributeList extends AttributesBase {
     this.$$kind = $$kind;
   }
 }
+
 /**
  * Base class for Graph objects.
  * @group Models
  */
 class GraphBase extends AttributesBase {
+  /** @hidden */
+  #models = common.RootModelsContext;
   id;
   comment;
+  attributes = Object.freeze({
+    graph: new AttributeList('Graph'),
+    edge: new AttributeList('Edge'),
+    node: new AttributeList('Node'),
+  });
   get nodes() {
     return Array.from(this.#objects.nodes.values());
   }
@@ -101,6 +104,9 @@ class GraphBase extends AttributesBase {
     edges: new Set(),
     subgraphs: new Set(),
   };
+  with(models) {
+    this.#models = common.createModelsContext(models);
+  }
   addNode(node) {
     this.#objects.nodes.set(node.id, node);
   }
@@ -120,11 +126,10 @@ class GraphBase extends AttributesBase {
     return this.#objects.subgraphs.has(subgraph);
   }
   createSubgraph(...args) {
-    const id = args.find((arg) => typeof arg === 'string');
-    const attributes = args.find((arg) => typeof arg === 'object');
-    const graph = new Subgraph(id, attributes);
-    this.#objects.subgraphs.add(graph);
-    return graph;
+    const subgraph = new this.#models.Subgraph(...args);
+    subgraph.with(this.#models);
+    this.addSubgraph(subgraph);
+    return subgraph;
   }
   removeNode(node) {
     this.#objects.nodes.delete(typeof node === 'string' ? node : node.id);
@@ -136,8 +141,8 @@ class GraphBase extends AttributesBase {
     this.#objects.subgraphs.delete(subgraph);
   }
   createNode(id, attributes) {
-    const node = new Node(id, attributes);
-    this.#objects.nodes.set(id, node);
+    const node = new this.#models.Node(id, attributes);
+    this.addNode(node);
     return node;
   }
   getSubgraph(id) {
@@ -148,8 +153,8 @@ class GraphBase extends AttributesBase {
   }
   createEdge(targets, attributes) {
     const ts = targets.map((t) => (common.isNodeRefGroupLike(t) ? common.toNodeRefGroup(t) : common.toNodeRef(t)));
-    const edge = new Edge(ts, attributes);
-    this.#objects.edges.add(edge);
+    const edge = new this.#models.Edge(ts, attributes);
+    this.addEdge(edge);
     return edge;
   }
   subgraph(...args) {
@@ -202,6 +207,48 @@ class GraphBase extends AttributesBase {
     this.attributes.graph.apply(attributes);
   }
 }
+
+/**
+ * Base class representing a root graph(digraph, graph).
+ * @group Models
+ */
+class RootGraph extends GraphBase {
+  get $$type() {
+    return 'Graph';
+  }
+  id;
+  strict;
+  constructor(...args) {
+    super();
+    this.id = args.find((arg) => typeof arg === 'string');
+    this.strict = args.find((arg) => typeof arg === 'boolean') ?? false;
+    const attributes = args.find((arg) => typeof arg === 'object' && arg !== null);
+    if (attributes !== undefined) {
+      this.apply(attributes);
+    }
+  }
+}
+
+/**
+ * DOT object class representing a digraph.
+ * @group Models
+ */
+class Digraph extends RootGraph {
+  get directed() {
+    return true;
+  }
+}
+
+/**
+ * DOT object class representing a graph.
+ * @group Models
+ */
+class Graph extends RootGraph {
+  get directed() {
+    return false;
+  }
+}
+
 /**
  * DOT object class representing a subgraph.
  * @group Models
@@ -211,11 +258,6 @@ class Subgraph extends GraphBase {
     return 'Subgraph';
   }
   id;
-  attributes = Object.freeze({
-    graph: new AttributeList('Graph'),
-    edge: new AttributeList('Edge'),
-    node: new AttributeList('Node'),
-  });
   constructor(...args) {
     super();
     this.id = args.find((arg) => typeof arg === 'string');
@@ -231,6 +273,15 @@ class Subgraph extends GraphBase {
     return false;
   }
 }
+
+/**
+ * A set of attribute values for any object.
+ * @group Models
+ */
+class AttributesGroup extends AttributesBase {
+  comment;
+}
+
 /**
  * DOT object class representing a node.
  * @group Models
@@ -245,7 +296,7 @@ class Node extends DotObject {
   constructor(id, attributes) {
     super();
     this.id = id;
-    this.attributes = new AttributesGroupModel(attributes);
+    this.attributes = new AttributesGroup(attributes);
   }
   port(port) {
     if (typeof port === 'string') {
@@ -254,6 +305,7 @@ class Node extends DotObject {
     return { id: this.id, ...port };
   }
 }
+
 /**
  * DOT object class representing a edge.
  * @group Models
@@ -271,93 +323,66 @@ class Edge extends DotObject {
     if (targets.length < 2 && (common.isNodeRefLike(targets[0]) && common.isNodeRefLike(targets[1])) === false) {
       throw Error('The element of Edge target is missing or not satisfied as Edge target.');
     }
-    this.attributes = new AttributesGroupModel(attributes);
-  }
-}
-/**
- * Base class representing a root graph(digraph, graph).
- * @group Models
- */
-class RootGraph extends GraphBase {
-  get $$type() {
-    return 'Graph';
-  }
-  id;
-  strict;
-  attributes = Object.freeze({
-    graph: new AttributeList('Graph'),
-    edge: new AttributeList('Edge'),
-    node: new AttributeList('Node'),
-  });
-  constructor(...args) {
-    super();
-    this.id = args.find((arg) => typeof arg === 'string');
-    this.strict = args.find((arg) => typeof arg === 'boolean') ?? false;
-    const attributes = args.find((arg) => typeof arg === 'object' && arg !== null);
-    if (attributes !== undefined) {
-      this.apply(attributes);
-    }
-  }
-}
-/**
- * DOT object class representing a graph.
- * @group Models
- */
-class Graph extends RootGraph {
-  get directed() {
-    return false;
-  }
-}
-/**
- * DOT object class representing a digraph.
- * @group Models
- */
-class Digraph extends RootGraph {
-  get directed() {
-    return true;
+    this.attributes = new AttributesGroup(attributes);
   }
 }
 
+Object.assign(common.RootModelsContext, {
+  Graph,
+  Digraph,
+  Subgraph,
+  Node,
+  Edge,
+});
+
 /** @hidden */
-function builder(directed, strictMode) {
-  const C = directed ? Digraph : Graph;
+function ModelFactoryBuilder(directed, strictMode) {
   return (...args) => {
+    const G = directed ? this.Digraph : this.Graph;
     const id = args.find((arg) => typeof arg === 'string');
     const attributes = args.find((arg) => typeof arg === 'object');
     const callback = args.find((arg) => typeof arg === 'function');
-    const g = new C(id, strictMode, attributes);
+    const g = new G(id, strictMode, attributes);
+    g.with(this);
     if (typeof callback === 'function') {
       callback(g);
     }
     return g;
   };
 }
+function createModelFactories(strict, context = common.RootModelsContext) {
+  return Object.freeze({
+    digraph: ModelFactoryBuilder.call(context, true, strict),
+    graph: ModelFactoryBuilder.call(context, false, strict),
+  });
+}
+
+const noStrict = createModelFactories(false);
 /**
  * API for creating directional graph objects.
- * @group Model Builder
+ * @group Model Factory
  */
-const digraph = builder(true, false);
+const digraph = noStrict.digraph;
 /**
  * API for creating omnidirectional graph objects.
- * @group Model Builder
+ * @group Model Factory
  */
-const graph = builder(false, false);
+const graph = noStrict.graph;
 /**
  * Provides a strict mode API.
- * @group Model Builder
+ * @group Model Factory
  */
-const strict = Object.freeze({
-  /**
-   * API for creating directional graph objects in strict mode.
-   * @group Model Builder
-   */
-  digraph: builder(true, true),
-  /**
-   * API for creating omnidirectional graph objects in strict mode.
-   * @group Model Builder
-   */
-  graph: builder(false, true),
-});
+const strict = createModelFactories(true);
+/**
+ * @group Model Factory
+ */
+function withContext(models) {
+  const context = common.createModelsContext(models);
+  return Object.freeze({
+    ...createModelFactories(false, context),
+    strict: createModelFactories(true, context),
+  });
+}
 
 /**
  * Convert Model to DOT string.
@@ -375,7 +400,7 @@ function toDot(model, options) {
 
 exports.AttributeList = AttributeList;
 exports.AttributesBase = AttributesBase;
-exports.AttributesGroupModel = AttributesGroupModel;
+exports.AttributesGroup = AttributesGroup;
 exports.Digraph = Digraph;
 exports.DotObject = DotObject;
 exports.Edge = Edge;
@@ -389,3 +414,4 @@ exports.digraph = digraph;
 exports.graph = graph;
 exports.strict = strict;
 exports.toDot = toDot;
+exports.withContext = withContext;