ts-graphviz 1.5.5 → 1.5.6-dev.afd5830bd

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.
  */