ts-graphviz 1.5.4 → 1.5.5-dev.02afc3340

package/README.md

@@ -545,6 +545,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/murawakimitsuhiro"><img src="https://avatars.githubusercontent.com/u/13833242?v=4?s=100" width="100px;" alt="mrwk"/><br /><sub><b>mrwk</b></sub></a><br /><a href="#question-murawakimitsuhiro" title="Answering Questions">💬</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/svdvonde"><img src="https://avatars.githubusercontent.com/u/2751783?v=4?s=100" width="100px;" alt="svdvonde"/><br /><sub><b>svdvonde</b></sub></a><br /><a href="#question-svdvonde" title="Answering Questions">💬</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/seethroughdev"><img src="https://avatars.githubusercontent.com/u/203779?v=4?s=100" width="100px;" alt="Adam"/><br /><sub><b>Adam</b></sub></a><br /><a href="#question-seethroughdev" title="Answering Questions">💬</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/trevor-scheer"><img src="https://avatars.githubusercontent.com/u/29644393?v=4?s=100" width="100px;" alt="Trevor Scheer"/><br /><sub><b>Trevor Scheer</b></sub></a><br /><a href="#a11y-trevor-scheer" title="Accessibility">️️️️♿️</a></td>
     </tr>
   </tbody>
 </table>

package/lib/adapter/deno/mod.js

@@ -1,9 +1,9 @@
-import { commandBuilder } from '../utils/index.js';
+import { createCommandAndArgs } from '../utils/index.js';
 /**
  * Execute the Graphviz dot command and make a Stream of the results.
  */
 export async function toStream(dot, options) {
-  const [command, args] = commandBuilder(options);
+  const [command, args] = createCommandAndArgs(options);
   const cp = new Deno.Command(command, {
     args: args,
     stdin: 'piped',

package/lib/adapter/node/index.cjs

@@ -17,7 +17,7 @@ const pipeline = node_util.promisify(node_stream.pipeline);
  * Execute the Graphviz dot command and make a Stream of the results.
  */
 async function toStream(dot, options) {
-  const [command, args] = index_js.commandBuilder(options ?? {});
+  const [command, args] = index_js.createCommandAndArgs(options ?? {});
   return new Promise(async function toStreamInternal(resolve, reject) {
     const p = node_child_process.spawn(command, args, { stdio: 'pipe' });
     // error handling

package/lib/adapter/node/index.js

@@ -1,6 +1,6 @@
 import { pipeline as pipeline$1, PassThrough, Readable } from 'node:stream';
 import { spawn } from 'node:child_process';
-import { commandBuilder } from '../utils/index.js';
+import { createCommandAndArgs } from '../utils/index.js';
 import { promisify } from 'node:util';
 import { createWriteStream } from 'node:fs';
 
@@ -15,7 +15,7 @@ const pipeline = promisify(pipeline$1);
  * Execute the Graphviz dot command and make a Stream of the results.
  */
 async function toStream(dot, options) {
-  const [command, args] = commandBuilder(options ?? {});
+  const [command, args] = createCommandAndArgs(options ?? {});
   return new Promise(async function toStreamInternal(resolve, reject) {
     const p = spawn(command, args, { stdio: 'pipe' });
     // error handling

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

@@ -7,6 +7,9 @@ import {
 
 type Format = 'png' | 'svg' | 'json' | 'jpg' | 'pdf' | 'xdot' | 'dot' | 'plain' | 'dot_json';
 type Layout = 'dot' | 'neato' | 'fdp' | 'sfdp' | 'circo' | 'twopi' | 'nop' | 'nop2' | 'osage' | 'patchwork';
+/**
+ * NeatoOptions interface provides options for the neato layout.
+ */
 interface NeatoOptions {
   layout: 'neato';
   /**
@@ -18,6 +21,9 @@ interface NeatoOptions {
    */
   reduce?: boolean;
 }
+/**
+ * FdpOptions interface provides options for the fdp layout.
+ */
 interface FdpOptions {
   layout: 'fdp';
   /**
@@ -49,6 +55,12 @@ interface FdpOptions {
    */
   temperature?: number;
 }
+/**
+ * @description
+ * This interface describes an optional parameter called "layout" which is used to set a layout engine.
+ * The default value for this parameter is 'dot', and it must be an option of the Layout type,
+ * excluding 'neato' and 'fdp'.
+ */
 interface OtherOptions {
   /**
    * Set layout engine.
@@ -57,6 +69,9 @@ interface OtherOptions {
    */
   layout?: Exclude<Layout, 'neato' | 'fdp'>;
 }
+/**
+ * This interface represents the CommonOptions for setting output format.
+ */
 interface CommonOptions {
   /**
    * Set output format.

package/lib/adapter/utils/index.cjs

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * escapeValue is a function that escapes a given Attribute value of a given AttributeKey.
+ * It checks the type of the value and adds quotes if the value is of type string and contains whitespace.
+ *
+ * @param value The value of an Attribute of type T that extends AttributeKey
+ * @returns The escaped Attribute value
+ */
 function escapeValue(value) {
   if (value !== true) {
     if (typeof value === 'string' && /\s/g.test(value)) {
@@ -10,7 +17,14 @@ function escapeValue(value) {
   }
   return '';
 }
-function* args(options) {
+/**
+ * createCommandArgs is a function that creates command arguments from a given Options object.
+ * It reads the properties of the Options object and creates corresponding command line arguments accordingly.
+ *
+ * @param options The Options object used to create command arguments
+ * @returns A generator that yields strings for command arguments
+ */
+function* createCommandArgs(options) {
   const { suppressWarnings = true, format = 'svg', attributes = {}, library = [], y = false, scale } = options;
   if (suppressWarnings) yield '-q';
   yield `-T${format}`;
@@ -50,8 +64,15 @@ function* args(options) {
     }
   }
 }
-function commandBuilder(options) {
-  return [options.dotCommand ?? 'dot', Array.from(args(options))];
+
+/**
+ * createCommandAndArgs creates a command and an array of arguments, based on the given {@link Options}.
+ *
+ * @param options Options to create the command and args from.
+ * @returns A tuple containing the command and an array of arguments.
+ */
+function createCommandAndArgs(options) {
+  return [options.dotCommand ?? 'dot', Array.from(createCommandArgs(options))];
 }
 
-exports.commandBuilder = commandBuilder;
+exports.createCommandAndArgs = createCommandAndArgs;

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

@@ -1,5 +1,11 @@
 import { Layout, Options } from '../types/index.js';
 
-declare function commandBuilder<T extends Layout>(options: Options<T>): [command: string, args: string[]];
+/**
+ * createCommandAndArgs creates a command and an array of arguments, based on the given {@link Options}.
+ *
+ * @param options Options to create the command and args from.
+ * @returns A tuple containing the command and an array of arguments.
+ */
+declare function createCommandAndArgs<T extends Layout>(options: Options<T>): [command: string, args: string[]];
 
-export { commandBuilder };
+export { createCommandAndArgs };

package/lib/adapter/utils/index.js

@@ -1,3 +1,10 @@
+/**
+ * escapeValue is a function that escapes a given Attribute value of a given AttributeKey.
+ * It checks the type of the value and adds quotes if the value is of type string and contains whitespace.
+ *
+ * @param value The value of an Attribute of type T that extends AttributeKey
+ * @returns The escaped Attribute value
+ */
 function escapeValue(value) {
   if (value !== true) {
     if (typeof value === 'string' && /\s/g.test(value)) {
@@ -8,7 +15,14 @@ function escapeValue(value) {
   }
   return '';
 }
-function* args(options) {
+/**
+ * createCommandArgs is a function that creates command arguments from a given Options object.
+ * It reads the properties of the Options object and creates corresponding command line arguments accordingly.
+ *
+ * @param options The Options object used to create command arguments
+ * @returns A generator that yields strings for command arguments
+ */
+function* createCommandArgs(options) {
   const { suppressWarnings = true, format = 'svg', attributes = {}, library = [], y = false, scale } = options;
   if (suppressWarnings) yield '-q';
   yield `-T${format}`;
@@ -48,8 +62,15 @@ function* args(options) {
     }
   }
 }
-function commandBuilder(options) {
-  return [options.dotCommand ?? 'dot', Array.from(args(options))];
+
+/**
+ * createCommandAndArgs creates a command and an array of arguments, based on the given {@link Options}.
+ *
+ * @param options Options to create the command and args from.
+ * @returns A tuple containing the command and an array of arguments.
+ */
+function createCommandAndArgs(options) {
+  return [options.dotCommand ?? 'dot', Array.from(createCommandArgs(options))];
 }
 
-export { commandBuilder };
+export { createCommandAndArgs };

package/lib/ast/index.cjs

@@ -4,17 +4,34 @@ var index_js = require('../utils/index.cjs');
 var index_js$1 = require('../common/index.cjs');
 
 /**
+ * Builder is an ASTBuilder that provides a method to create an ASTNode.
+ *
  * @group Create AST
  */
 class Builder {
   options;
-  /** @internal */
+  /**
+   * Get the current file range or null
+   * @internal
+   */
   getLocation() {
     return this.options?.locationFunction?.() ?? null;
   }
+  /**
+   * Constructor of Builder
+   * @param options - Options to initialize Builder
+   */
   constructor(options) {
     this.options = options;
   }
+  /**
+   * Create an {@link ASTNode} of the specified type
+   *
+   * @param type - Type of the {@link ASTNode}
+   * @param props - Properties of the {@link ASTNode}
+   * @param children - Children of the {@link ASTNode}
+   * @returns An {@link ASTNode}
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   createElement(type, props, children) {
     return {
@@ -27,7 +44,13 @@ class Builder {
 }
 
 /**
+ * Create an {@link ASTNode} of the specified type
+ *
+ * @param type - Type of the {@link ASTNode}
+ * @param props - Properties of the {@link ASTNode}
+ * @param children - Children of the {@link ASTNode}
  * @group Create AST
+ * @returns An {@link ASTNode}
  */
 const createElement = Builder.prototype.createElement.bind(new Builder());
 
@@ -266,15 +289,24 @@ const defaultPlugins$2 = [
 ];
 
 /**
+ * Printer is a class responsible for converting an AST into a DOT string.
  * @group Convert AST to DOT
  */
 class Printer {
   options;
   /** @internal */
   #plugins = [...defaultPlugins$2];
+  /**
+   * @param options Options to be used when generating the DOT string.
+   */
   constructor(options = {}) {
     this.options = options;
   }
+  /**
+   * Generates a DOT string from an ASTNode.
+   * @param ast The ASTNode to be converted into a DOT string.
+   * @returns The DOT string generated from the ASTNode.
+   */
   print(ast) {
     const plugins = [...this.#plugins];
     const { indentSize = 2, indentStyle = 'space', endOfLine = 'lf' } = this.options;
@@ -297,10 +329,11 @@ class Printer {
 }
 
 /**
- * Stringify Graphviz AST Node.
+ * stringify is a function that converts a Graphviz AST Node into a string in DOT language.
  *
- * @param ast Graphviz AST node.
- * @returns DOT language string.
+ * @param ast Graphviz AST node that is to be converted.
+ * @param options PrintOptions object containing formatting options.
+ * @returns A string in DOT language.
  * @group Convert AST to DOT
  */
 function stringify(ast, options) {
@@ -5563,6 +5596,8 @@ const SubgraphPlugin$1 = {
 const defaultPlugins$1 = [AttributeListPlugin, EdgePlugin$1, NodePlugin$1, GraphPlugin$1, SubgraphPlugin$1];
 
 /**
+ * FromModelConverter is a class used to convert a {@link DotObjectModel} into an ASTNode.
+ *
  * @group Convert Model to AST
  */
 class FromModelConverter {
@@ -5572,6 +5607,12 @@ class FromModelConverter {
   constructor(options = {}) {
     this.options = options;
   }
+  /**
+   * Converts a DotObjectModel into an AST.
+   *
+   * @param model The {@link DotObjectModel} to be converted.
+   * @returns The AST generated from the model.
+   */
   convert(model) {
     const plugins = [...this.#plugins];
     const { commentKind = 'Slash' } = this.options;
@@ -5591,6 +5632,12 @@ class FromModelConverter {
 }
 
 /**
+ * A function used to convert a DotObjectModel into an AST.
+ *
+ * @param model - The {@link DotObjectModel} to be converted.
+ * @param options - An optional {@link ConvertFromModelOptions} object.
+ * @returns ModelToAST - The AST representation of the {@link DotObjectModel}.
+ *
  * @group Convert Model to AST
  */
 function fromModel(model, options) {