ts-graphviz 1.5.6-dev.ef6c929b6 → 1.6.1-dev.39dd9d4de

package/README.md

@@ -503,6 +503,80 @@ const ast = parse(`
 
 </details>
 
+### Extending the Type System 🧰
+
+> The status of this feature is ![beta](https://img.shields.io/badge/-beta-orange).
+
+With ts-graphviz, you can extend the library's type system to customize graph visualization solutions to meet specific needs.
+
+> **Note** To allow for customization, types are named with the `$` symbol.
+>
+> If you want to extend a type definition in cases not listed below, check the source code to see if you can extend it with `$...`.
+>
+> If not, please create an issue or pull request.
+
+#### Use Case: Specifying Custom Graph Layout and Output Formats
+
+```ts
+import { $keywords } from 'ts-graphviz';
+import { toFile } from 'ts-graphviz/adapter';
+
+// 1. Declare the 'ts-graphviz/adapter' module.
+declare module 'ts-graphviz/adapter' {
+  export namespace Layout {
+    // 2. Define the $values interface in the Layout namespace.
+    // 3. Inherit from $keywords<'my-custom-algorithm'> and specify the name of the new layout engine in <...>.
+    export interface $values extends $keywords<'my-custom-algorithm'> {}
+  }
+
+  export namespace Format {
+    // 4. Define the $values interface in the Format namespace.
+    // 5. Inherit from $keywords<'mp4'> and specify the name of the new output format in <...>.
+    export interface $values extends $keywords<'mp4'> {}
+  }
+}
+
+toFile('digraph { a -> b }', '/path/to/file', {
+  layout: 'my-custom-algorithm',
+  format: 'mp4',
+});
+```
+
+#### Use Case: Adding Custom Attributes
+
+```ts
+import { digraph, toDot, attribute as _, $keywords } from 'ts-graphviz';
+
+// 1. Declare the 'ts-graphviz' module.
+declare module 'ts-graphviz' {
+  export namespace GraphAttributeKey {
+    // 2. Define the $values interface in the GraphAttributeKey namespace.
+    // 3. Inherit from $keywords<'hoge'> and specify the name of the new attribute in <...>.
+    export interface $values extends $keywords<'hoge'> {}
+  }
+
+  export namespace Attribute {
+    // 4. Define the $keys interface in the Attribute namespace.
+    // 5. Inherit from $keywords<'hoge'> and specify the name of the new attribute in <...>.
+    export interface $keys extends $keywords<'hoge'> {}
+
+    // 6. Define the $types interface in the Attribute namespace.
+    // 7. Specify the new attribute in the key and define its corresponding value in the value.
+    export interface $types {
+      hoge: string;
+    }
+  }
+}
+
+console.log(
+  toDot(
+    digraph((g) => {
+      g.set(_.hoge, 'fuga');
+    }),
+  ),
+);
+```
+
 ## Who's using `ts-graphviz` 📜
 
 - [Apollo GraphQL](https://github.com/apollographql)
@@ -576,9 +650,13 @@ See [CONTRIBUTING.md](https://github.com/ts-graphviz/ts-graphviz/blob/main/CONTR
 
 ### Financial Support 💸
 
-Please support core member [kamiazya](https://github.com/sponsors/kamiazya).
+Please support [ts-graphviz](https://github.com/sponsors/ts-graphviz).
+
+Our goal for ts-graphviz is to attract 10 sponsors who can provide ongoing support to help cover development and maintenance costs,
+and help us continue expanding and improving the library. By achieving this goal, we can ensure that ts-graphviz remains a valuable resource
+for developers who need to analyze and visualize complex graph structures, while also fostering a strong and supportive community of users and sponsors.
 
-> **Note** Even just a dollar is enough motivation for me to develop 😊
+> **Note** Even just a dollar is enough motivation to develop 😊
 
 ## License ⚖️
 

package/lib/adapter/node/index.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import { Layout, Options } from '../types/index.js';
-export { Format, Options } from '../types/index.js';
+export { Format, Layout, Options } from '../types/index.js';
 
 /**
  * Execute the Graphviz dot command and make a Stream of the results.

package/lib/adapter/types/index.d.ts

@@ -4,9 +4,19 @@ import {
   GraphAttributesObject,
   SubgraphAttributesObject,
 } from '../../common/index.js';
+import { $keywords } from '../../utils/index.js';
 
-type Format = 'png' | 'svg' | 'json' | 'jpg' | 'pdf' | 'xdot' | 'dot' | 'plain' | 'dot_json';
-type Layout = 'dot' | 'neato' | 'fdp' | 'sfdp' | 'circo' | 'twopi' | 'nop' | 'nop2' | 'osage' | 'patchwork';
+type Format = Format.values;
+declare namespace Format {
+  type values = keyof $values;
+  interface $values extends $keywords<'png' | 'svg' | 'json' | 'jpg' | 'pdf' | 'xdot' | 'dot' | 'plain' | 'dot_json'> {}
+}
+type Layout = Layout.values;
+declare namespace Layout {
+  type values = keyof $values;
+  interface $values
+    extends $keywords<'dot' | 'neato' | 'fdp' | 'sfdp' | 'circo' | 'twopi' | 'nop' | 'nop2' | 'osage' | 'patchwork'> {}
+}
 /**
  * NeatoOptions interface provides options for the neato layout.
  */

package/lib/ast/index.cjs

@@ -11,11 +11,11 @@ class Builder {
   constructor(options) {
     this.options = options;
   }
-  createElement(type, props, children) {
+  createElement(type, props, children = []) {
     return {
+      location: this.getLocation(),
       ...props,
       type,
-      location: this.getLocation(),
       children,
     };
   }

package/lib/ast/index.d.ts

@@ -351,7 +351,7 @@ interface CreateElement {
   <T extends string>(
     type: 'Literal',
     props: LiteralASTPropaties<T>,
-    children: ASTChildNode<LiteralASTNode>[],
+    children?: ASTChildNode<LiteralASTNode>[],
   ): LiteralASTNode<T>;
   /**
    * Creates a LiteralASTNode with the given type, properties, and children.
@@ -361,7 +361,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns A {@link LiteralASTNode} with the given type, properties, and children.
    */
-  (type: 'Literal', props: LiteralASTPropaties, children: ASTChildNode<LiteralASTNode>[]): LiteralASTNode;
+  (type: 'Literal', props: LiteralASTPropaties, children?: ASTChildNode<LiteralASTNode>[]): LiteralASTNode;
   /**
    * Creates a {@link DotASTNode} with the given type, properties, and children.
    *
@@ -370,7 +370,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns A {@link DotASTNode} with the given type, properties, and children.
    */
-  (type: 'Dot', props: DotASTPropaties, children: ASTChildNode<DotASTNode>[]): DotASTNode;
+  (type: 'Dot', props: DotASTPropaties, children?: ASTChildNode<DotASTNode>[]): DotASTNode;
   /**
    * Creates a {@link GraphASTNode} with the given type, properties, and children.
    *
@@ -379,7 +379,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns A {GraphASTNode} with the given type, properties, and children.
    */
-  (type: 'Graph', props: GraphASTPropaties, children: ASTChildNode<GraphASTNode>[]): GraphASTNode;
+  (type: 'Graph', props: GraphASTPropaties, children?: ASTChildNode<GraphASTNode>[]): GraphASTNode;
   /**
    * Creates an {@link AttributeASTNode} with the given type, properties, and children.
    *
@@ -388,7 +388,12 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns An {@link AttributeASTNode} with the given type, properties, and children.
    */
-  (type: 'Attribute', props: AttributeASTPropaties, children: ASTChildNode<AttributeASTNode>[]): AttributeASTNode;
+  <T extends AttributeKey>(
+    type: 'Attribute',
+    props: AttributeASTPropaties<T>,
+    children?: ASTChildNode<AttributeASTNode>[],
+  ): AttributeASTNode<T>;
+  (type: 'Attribute', props: AttributeASTPropaties, children?: ASTChildNode<AttributeASTNode>[]): AttributeASTNode;
   /**
    * Creates a {@link CommentASTNode} with the given type, properties, and children.
    *
@@ -397,7 +402,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns A {@link CommentASTNode} with the given type, properties, and children.
    */
-  (type: 'Comment', props: CommentASTPropaties, children: ASTChildNode<CommentASTNode>[]): CommentASTNode;
+  (type: 'Comment', props: CommentASTPropaties, children?: ASTChildNode<CommentASTNode>[]): CommentASTNode;
   /**
    * Creates an {@link AttributeListASTNode} with the given type, properties, and children.
    *
@@ -409,7 +414,7 @@ interface CreateElement {
   (
     type: 'AttributeList',
     props: AttributeListASTPropaties,
-    children: ASTChildNode<AttributeListASTNode>[],
+    children?: ASTChildNode<AttributeListASTNode>[],
   ): AttributeListASTNode;
   /**
    * Creates a {@link NodeRefASTNode} with the given type, properties, and children.
@@ -419,7 +424,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns A {@link NodeRefASTNode} with the given type, properties, and children.
    */
-  (type: 'NodeRef', props: NodeRefASTPropaties, children: ASTChildNode<NodeRefASTNode>[]): NodeRefASTNode;
+  (type: 'NodeRef', props: NodeRefASTPropaties, children?: ASTChildNode<NodeRefASTNode>[]): NodeRefASTNode;
   /**
    * Creates a {@link NodeRefGroupASTNode} with the given type, properties, and children.
    *
@@ -431,7 +436,7 @@ interface CreateElement {
   (
     type: 'NodeRefGroup',
     props: NodeRefGroupASTPropaties,
-    children: ASTChildNode<NodeRefGroupASTNode>[],
+    children?: ASTChildNode<NodeRefGroupASTNode>[],
   ): NodeRefGroupASTNode;
   /**
    * Creates an {@link EdgeASTNode} with the given type, properties, and children.
@@ -441,7 +446,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns An {@link EdgeASTNode} with the given type, properties, and children.
    */
-  (type: 'Edge', props: EdgeASTPropaties, children: ASTChildNode<EdgeASTNode>[]): EdgeASTNode;
+  (type: 'Edge', props: EdgeASTPropaties, children?: ASTChildNode<EdgeASTNode>[]): EdgeASTNode;
   /**
    * Creates a {@link NodeASTNode} with the given type, properties, and children.
    *
@@ -450,7 +455,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns A {@link NodeASTNode} with the given type, properties, and children.
    */
-  (type: 'Node', props: NodeASTPropaties, children: ASTChildNode<NodeASTNode>[]): NodeASTNode;
+  (type: 'Node', props: NodeASTPropaties, children?: ASTChildNode<NodeASTNode>[]): NodeASTNode;
   /**
    * Creates a {@link SubgraphASTNode} with the given type, properties, and children.
    *
@@ -459,7 +464,7 @@ interface CreateElement {
    * @param children The children of the AST node.
    * @returns A {@link SubgraphASTNode} with the given type, properties, and children.
    */
-  (type: 'Subgraph', props: SubgraphASTPropaties, children: ASTChildNode<SubgraphASTNode>[]): SubgraphASTNode;
+  (type: 'Subgraph', props: SubgraphASTPropaties, children?: ASTChildNode<SubgraphASTNode>[]): SubgraphASTNode;
 }
 /**
  * This interface provides an ASTBuilder object with a createElement function.
@@ -495,7 +500,7 @@ declare class Builder implements ASTBuilder {
    * @param children - Children of the {@link ASTNode}
    * @returns An {@link ASTNode}
    */
-  createElement<T extends ASTNode>(type: T['type'], props: any, children: ASTChildNode<T>[]): T;
+  createElement<T extends ASTNode>(type: T['type'], props: any, children?: ASTChildNode<T>[]): T;
 }
 
 /**

package/lib/ast/index.js

@@ -9,11 +9,11 @@ class Builder {
   constructor(options) {
     this.options = options;
   }
-  createElement(type, props, children) {
+  createElement(type, props, children = []) {
     return {
+      location: this.getLocation(),
       ...props,
       type,
-      location: this.getLocation(),
       children,
     };
   }