@ts-graphviz/adapter 0.0.0-pr956-20240225073457

package/src/browser.ts

@@ -0,0 +1,19 @@
+/**
+ * @module @ts-graphviz/adapter
+ */
+export type Options = any;
+
+const ERROR_MESSAGE = 'This module cannot be run in a browser.';
+/**
+ * Execute the Graphviz dot command and make a Stream of the results.
+ */
+export function toStream(dot: string, options?: Options): never {
+  throw new Error(ERROR_MESSAGE);
+}
+
+/**
+ * Execute the Graphviz dot command and output the results to a file.
+ */
+export function toFile(dot: string, path: string, options?: Options): never {
+  throw new Error(ERROR_MESSAGE);
+}

package/src/create-command-and-args.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { createCommandAndArgs } from './create-command-and-args.js';
+import { Options } from './types.js';
+
+describe('createCommandAndArgs', () => {
+  it('should return the correct command and args', () => {
+    const options: Options = {
+      dotCommand: 'mydot',
+      suppressWarnings: true,
+      format: 'svg',
+      attributes: {
+        graph: <any>{
+          a: 'foo',
+          b: 'bar',
+        },
+        node: <any>{
+          c: 'baz',
+          d: 'qux',
+        },
+        edge: <any>{
+          e: 'quux',
+          f: 'corge',
+        },
+      },
+      library: ['lib1', 'lib2'],
+      y: true,
+      scale: 5,
+      layout: 'neato',
+      reduce: true,
+      noop: 3,
+    };
+
+    const [command, args] = createCommandAndArgs(options);
+    expect(command).toBe('mydot');
+    expect(args).toMatchInlineSnapshot(`
+      [
+        "-q",
+        "-Tsvg",
+        "-Ga=foo",
+        "-Gb=bar",
+        "-Nc=baz",
+        "-Nd=qux",
+        "-Ee=quux",
+        "-Ef=corge",
+        "-s5",
+        "-llib1",
+        "-llib2",
+        "-y",
+        "-Kneato",
+        "-x",
+        "-n3",
+      ]
+    `);
+  });
+
+  it('should return user customized command', () => {
+    const options: Options = {
+      dotCommand: 'mydot',
+    };
+    const [command] = createCommandAndArgs(options);
+    expect(command).toBe('mydot');
+  });
+});

package/src/create-command-and-args.ts

@@ -0,0 +1,14 @@
+import { createCommandArgs } from './create-command-args.js';
+import { Layout, Options } from './types.js';
+
+/**
+ * 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.
+ */
+export function createCommandAndArgs<T extends Layout>(
+  options: Options<T>,
+): [command: string, args: string[]] {
+  return [options.dotCommand ?? 'dot', Array.from(createCommandArgs(options))];
+}

package/src/create-command-args.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { createCommandArgs, escapeValue } from './create-command-args.js';
+import { Options } from './types.js';
+
+describe('createCommandArgs', () => {
+  it('should generate correct args for neato layout', () => {
+    const options: Options = {
+      suppressWarnings: true,
+      format: 'svg',
+      attributes: {
+        graph: <any>{
+          foo: 'bar',
+        },
+        node: <any>{
+          baz: 'qux',
+        },
+        edge: <any>{
+          quux: 'quuz',
+        },
+      },
+      library: ['lib1', 'lib2'],
+      y: true,
+      scale: 1.5,
+      layout: 'neato',
+      reduce: true,
+      noop: 10,
+    };
+
+    expect(Array.from(createCommandArgs(options))).toMatchInlineSnapshot(`
+      [
+        "-q",
+        "-Tsvg",
+        "-Gfoo=bar",
+        "-Nbaz=qux",
+        "-Equux=quuz",
+        "-s1.5",
+        "-llib1",
+        "-llib2",
+        "-y",
+        "-Kneato",
+        "-x",
+        "-n10",
+      ]
+    `);
+  });
+
+  it('should generate correct args for fdp layout', () => {
+    const options: Options = {
+      suppressWarnings: false,
+      format: 'png',
+      attributes: {
+        graph: <any>{
+          foo: 'bar',
+        },
+        node: <any>{
+          baz: 'qux',
+        },
+        edge: <any>{
+          quux: 'quuz',
+        },
+      },
+      library: ['lib1'],
+      y: false,
+      scale: 2,
+      layout: 'fdp',
+      grid: true,
+      oldAttractive: true,
+      iterations: 5,
+      unscaledFactor: 0.5,
+      overlapExpansionFactor: 10,
+      temperature: 3,
+    };
+    expect(Array.from(createCommandArgs(options))).toMatchInlineSnapshot(`
+      [
+        "-Tpng",
+        "-Gfoo=bar",
+        "-Nbaz=qux",
+        "-Equux=quuz",
+        "-s2",
+        "-llib1",
+        "-Kfdp",
+        "-LO",
+        "-Ln5",
+        "-LU0.5",
+        "-LC10",
+        "-LT3",
+      ]
+    `);
+  });
+});
+
+describe('escapeValue', () => {
+  it('should escape values correctly', () => {
+    expect(escapeValue('foo bar')).toEqual('="foo bar"');
+    expect(escapeValue('foo')).toEqual('=foo');
+    expect(escapeValue(true)).toEqual('');
+    expect(escapeValue(false)).toEqual('=false');
+    expect(escapeValue(10)).toEqual('=10');
+  });
+});

package/src/create-command-args.ts

@@ -0,0 +1,90 @@
+import { Attribute, AttributeKey } from '@ts-graphviz/common';
+import { Layout, Options } from './types.js';
+
+/**
+ * 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
+ */
+export function escapeValue<T extends AttributeKey>(value: Attribute<T>) {
+  if (value !== true) {
+    if (typeof value === 'string' && /\s/g.test(value)) {
+      return `="${value}"`;
+    }
+    return `=${value}`;
+  }
+  return '';
+}
+
+/**
+ * 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
+ */
+export function* createCommandArgs<T extends Layout>(
+  options: Options<T>,
+): Generator<string> {
+  const {
+    suppressWarnings = true,
+    format = 'svg',
+    attributes = {},
+    library = [],
+    y = false,
+    scale,
+  } = options;
+  if (suppressWarnings) yield '-q';
+  yield `-T${format}`;
+  if (attributes.graph) {
+    for (const [key, value] of Object.entries(attributes.graph)) {
+      yield `-G${key}${escapeValue(value)}`;
+    }
+  }
+  if (attributes.node) {
+    for (const [key, value] of Object.entries(attributes.node)) {
+      yield `-N${key}${escapeValue(value)}`;
+    }
+  }
+  if (attributes.edge) {
+    for (const [key, value] of Object.entries(attributes.edge)) {
+      yield `-E${key}${escapeValue(value)}`;
+    }
+  }
+  if (typeof scale === 'number' && !Number.isNaN(scale)) yield `-s${scale}`;
+  if (Array.isArray(library)) for (const lib of library) yield `-l${lib}`;
+  if (y === true) yield '-y';
+
+  if (typeof options.layout === 'string') {
+    yield `-K${options.layout}`;
+    switch (options.layout) {
+      case 'neato': {
+        const { reduce, noop } = options;
+        if (reduce === true) yield '-x';
+        if (typeof noop === 'number') yield `-n${noop}`;
+        break;
+      }
+      case 'fdp': {
+        const {
+          grid,
+          oldAttractive,
+          iterations,
+          unscaledFactor,
+          overlapExpansionFactor,
+          temperature,
+        } = options;
+        yield ['-L', grid ? '' : 'g', oldAttractive ? 'O' : ''].join('');
+        if (typeof iterations === 'number') yield `-Ln${iterations}`;
+        if (typeof unscaledFactor === 'number') yield `-LU${unscaledFactor}`;
+        if (typeof overlapExpansionFactor === 'number')
+          yield `-LC${overlapExpansionFactor}`;
+        if (typeof temperature === 'number') yield `-LT${temperature}`;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+}

package/src/deno.ts

@@ -0,0 +1,49 @@
+import { createCommandAndArgs } from './create-command-and-args.js';
+/**
+ * @module @ts-graphviz/adapter
+ */
+/// <reference types="../types/deno.d.ts" />
+import { Layout, Options } from './types.js';
+
+/**
+ * Execute the Graphviz dot command and make a Stream of the results.
+ */
+export async function toStream<T extends Layout>(
+  dot: string,
+  options?: Options<T>,
+): Promise<ReadableStream<Uint8Array>> {
+  const [command, args] = createCommandAndArgs(options ?? {});
+  const cp = new Deno.Command(command, {
+    args: args,
+    stdin: 'piped',
+    stdout: 'piped',
+  }).spawn();
+  const stdin = cp.stdin.getWriter();
+  await stdin.write(new TextEncoder().encode(dot));
+  await stdin.close();
+  return cp.stdout;
+}
+
+function open(path: string) {
+  try {
+    return Deno.open(path, { write: true });
+  } catch (e) {
+    if (e instanceof Deno.errors.NotFound) {
+      return Deno.open(path, { createNew: true, write: true });
+    }
+    throw e;
+  }
+}
+
+/**
+ * Execute the Graphviz dot command and output the results to a file.
+ */
+export async function toFile<T extends Layout>(
+  dot: string,
+  path: string,
+  options?: Options<T>,
+): Promise<void> {
+  const output = await open(path);
+  const stream = await toStream(dot, options);
+  await stream.pipeTo(output.writable);
+}

package/src/node.ts

@@ -0,0 +1,6 @@
+/**
+ * @module @ts-graphviz/adapter
+ */
+export type { Options, Format, Layout } from './types.js';
+export * from './to-stream.node.js';
+export * from './to-file.node.js';

package/src/to-file.node.ts

@@ -0,0 +1,16 @@
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { toStream } from './to-stream.node.js';
+import { Layout, Options } from './types.js';
+
+/**
+ * Execute the Graphviz dot command and output the results to a file.
+ */
+export async function toFile<T extends Layout>(
+  dot: string,
+  path: string,
+  options?: Options<T>,
+): Promise<void> {
+  const stream = await toStream(dot, options);
+  await pipeline(stream, createWriteStream(path));
+}

package/src/to-stream.node.ts

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { PassThrough, Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createCommandAndArgs } from './create-command-and-args.js';
+import { Layout, Options } from './types.js';
+
+/**
+ * Execute the Graphviz dot command and make a Stream of the results.
+ */
+export async function toStream<T extends Layout>(
+  dot: string,
+  options?: Options<T>,
+): Promise<NodeJS.ReadableStream> {
+  const [command, args] = createCommandAndArgs(options ?? {});
+  return new Promise(function toStreamInternal(resolve, reject) {
+    const p = spawn(command, args, { stdio: 'pipe' });
+
+    // error handling
+    p.on('error', (e) => {
+      reject(
+        new Error(`Command "${command}" failed.\nMESSAGE:${e.message}`, {
+          cause: e,
+        }),
+      );
+    });
+
+    const stderrChunks: Uint8Array[] = [];
+    p.stdout.on('pause', () => p.stdout.resume());
+    p.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+    p.stderr.on('pause', () => p.stderr.resume());
+
+    const dist = p.stdout.pipe(new PassThrough());
+    p.on('close', async (code, signal) => {
+      if (code === 0) {
+        resolve(dist);
+      } else {
+        const message = Buffer.concat(
+          stderrChunks as ReadonlyArray<Uint8Array>,
+        ).toString();
+        reject(
+          new Error(
+            `Command "${command}" failed.\nCODE: ${code}\nSIGNAL: ${signal}\nMESSAGE: ${message}`,
+          ),
+        );
+      }
+    });
+
+    pipeline(Readable.from([dot]), p.stdin);
+  });
+}

package/src/types.ts

@@ -0,0 +1,166 @@
+import {
+  $keywords,
+  $keywordsValidation,
+  EdgeAttributesObject,
+  GraphAttributesObject,
+  NodeAttributesObject,
+  SubgraphAttributesObject,
+} from '@ts-graphviz/common';
+
+export type Format = Format.values;
+export namespace Format {
+  export type values = Exclude<keyof $values, keyof $exclude | symbol | number>;
+  export interface $values
+    extends $keywords<
+      | 'png'
+      | 'svg'
+      | 'json'
+      | 'jpg'
+      | 'pdf'
+      | 'xdot'
+      | 'dot'
+      | 'plain'
+      | 'dot_json'
+    > {}
+  export interface $exclude extends $keywordsValidation {}
+}
+
+export type Layout = Layout.values;
+export namespace Layout {
+  export type values = Exclude<keyof $values, keyof $exclude | symbol | number>;
+  export interface $values
+    extends $keywords<
+      | 'dot'
+      | 'neato'
+      | 'fdp'
+      | 'sfdp'
+      | 'circo'
+      | 'twopi'
+      | 'nop'
+      | 'nop2'
+      | 'osage'
+      | 'patchwork'
+    > {}
+  export interface $exclude extends $keywordsValidation {}
+}
+
+/**
+ * NeatoOptions interface provides options for the neato layout.
+ */
+export interface NeatoOptions {
+  layout: 'neato';
+  /**
+   * Sets no-op flag in neato.
+   */
+  noop?: number;
+  /**
+   * Reduce graph.
+   */
+  reduce?: boolean;
+}
+
+/**
+ * FdpOptions interface provides options for the fdp layout.
+ */
+export interface FdpOptions {
+  layout: 'fdp';
+  /**
+   * Use grid.
+   *
+   * @default true
+   */
+  grid?: boolean;
+  /**
+   * Use old attractive force
+   *
+   * @default true
+   */
+  oldAttractive?: boolean;
+
+  /**
+   * Set number of iterations.
+   */
+  iterations?: number;
+  /**
+   * Set unscaled factor
+   */
+  unscaledFactor?: number;
+  /**
+   * Set overlap expansion factor.
+   */
+  overlapExpansionFactor?: number;
+  /**
+   * Set temperature.
+   */
+  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'.
+ */
+export interface OtherOptions {
+  /**
+   * Set layout engine.
+   *
+   * @default 'dot'
+   */
+  layout?: Exclude<Layout, 'neato' | 'fdp'>;
+}
+
+/**
+ * This interface represents the CommonOptions for setting output format.
+ */
+export interface CommonOptions {
+  /**
+   * Set output format.
+   *
+   * @default 'svg'
+   */
+  format?: Format;
+  /**
+   * If true, set level of message suppression (=1).
+   *
+   * @default true
+   */
+  suppressWarnings?: boolean;
+  /**
+   * Path of graphviz dot command.
+   */
+  dotCommand?: string;
+  attributes?: {
+    /**
+     * Set edge attribute.
+     */
+    edge?: EdgeAttributesObject;
+    /**
+     * Set node attribute.
+     */
+    node?: NodeAttributesObject;
+    /**
+     * Set graph attribute.
+     */
+    graph?: GraphAttributesObject & SubgraphAttributesObject;
+  };
+  /**
+   * Scale input
+   */
+  scale?: number;
+  /**
+   * Use external library.
+   */
+  library?: string[];
+  /**
+   * Invert y coordinate in output.
+   */
+  y?: boolean;
+}
+
+export type Options<T extends Layout = Layout> = CommonOptions &
+  (T extends 'neato'
+    ? NeatoOptions
+    : T extends 'fdp'
+      ? FdpOptions
+      : OtherOptions);

package/tsconfig.browser.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "lib"
+  },
+  "include": ["src/browser.ts", "src/*.ts"],
+  "exclude": [
+    "src/deno.ts",
+    "src/node.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts"
+  ]
+}

package/tsconfig.deno.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "lib"
+  },
+  "include": ["src/deno.ts", "src/*.ts"],
+  "exclude": [
+    "src/browser.ts",
+    "src/node.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts"
+  ]
+}

package/tsconfig.node.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "lib"
+  },
+  "include": ["src/node.ts", "src/*.ts"],
+  "exclude": [
+    "src/browser.ts",
+    "src/deno.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts"
+  ]
+}

package/typedoc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../../typedoc.base.json"],
+  "entryPoints": ["src/node/index.ts"]
+}

package/types/deno.d.ts

@@ -0,0 +1,20 @@
+export declare global {
+  declare namespace Deno {
+    // biome-ignore lint/style/noVar: <explanation>
+    declare var open: typeof import('@deno/shim-deno').Deno.open;
+    // biome-ignore lint/style/noVar: <explanation>
+    declare var errors: typeof import('@deno/shim-deno').Deno.errors;
+
+    declare class Command {
+      constructor(
+        command: string,
+        options: {
+          args: string[];
+          stdin: 'piped';
+          stdout: 'piped';
+        },
+      );
+      spawn(): Deno.Process;
+    }
+  }
+}

package/vite.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig({
+  build: {
+    target: 'esnext',
+    outDir: './lib',
+    minify: false,
+    lib: {
+      entry: {
+        'create-command-and-args': './src/create-command-and-args.ts',
+        deno: './src/deno.ts',
+        browser: './src/browser.ts',
+        node: './src/node.ts',
+      },
+      formats: ['es', 'cjs'],
+    },
+    rollupOptions: {
+      external: [
+        '@ts-graphviz/common',
+        'node:stream',
+        'node:stream/promises',
+        'node:child_process',
+        'node:fs',
+      ],
+    },
+  },
+  plugins: [
+    dts({
+      tsconfigPath: './tsconfig.browser.json',
+    }),
+    dts({
+      tsconfigPath: './tsconfig.node.json',
+    }),
+    dts({
+      tsconfigPath: './tsconfig.deno.json',
+    }),
+  ],
+});