@terra-graph/core 1.0.0-rc.4

package/dist/esm/Output/ArtifactTransformerFactory/DefaultArtifactTransformerFactory.test.js

@@ -0,0 +1,78 @@
+import { DefaultArtifactTransformerFactory } from './DefaultArtifactTransformerFactory.js';
+describe('DefaultArtifactTransformerFactory.create', () => {
+    it('shoud create dotcli transformer with mapped options', async () => {
+        const calls = [];
+        const factory = new DefaultArtifactTransformerFactory({
+            dotCliRunProcess: async (input) => {
+                calls.push(input);
+                return Buffer.from([1, 2, 3]);
+            },
+        });
+        const transformer = factory.create({
+            name: 'dotcli',
+            options: {
+                format: 'png',
+                executable: 'dot-custom',
+                dotArg: ['-Nshape=box', '-Ecolor=red'],
+                Gdpi: '200',
+            },
+        });
+        await transformer.transform({
+            artifact: {
+                content: 'digraph G {}',
+                mediaType: 'text/vnd.graphviz',
+                extension: 'dot',
+            },
+        });
+        expect(calls).toHaveLength(1);
+        expect(calls[0]).toEqual({
+            executable: 'dot-custom',
+            args: ['-Tpng', '-Nshape=box', '-Ecolor=red', '-Gdpi=200'],
+            stdin: 'digraph G {}',
+        });
+    });
+    it('shoud throw when transformer is not supported', () => {
+        const factory = new DefaultArtifactTransformerFactory();
+        expect(() => factory.create({
+            name: 'unknown',
+        })).toThrow("Unsupported transformer 'unknown'");
+    });
+    it('shoud require format for dotcli', () => {
+        const factory = new DefaultArtifactTransformerFactory();
+        expect(() => factory.create({
+            name: 'dotcli',
+        })).toThrow("Transformer 'dotcli' requires option 'format'");
+    });
+    it('shoud default to dot executable when none is provided', async () => {
+        const calls = [];
+        const factory = new DefaultArtifactTransformerFactory({
+            dotCliRunProcess: async (input) => {
+                calls.push(input);
+                return Buffer.from([4, 5, 6]);
+            },
+        });
+        const transformer = factory.create({
+            name: 'dotcli',
+            options: {
+                format: 'svg',
+            },
+        });
+        await transformer.transform({
+            artifact: {
+                content: 'digraph G {}',
+                mediaType: 'text/vnd.graphviz',
+                extension: 'dot',
+            },
+        });
+        expect(calls[0]).toEqual({
+            executable: 'dot',
+            args: ['-Tsvg'],
+            stdin: 'digraph G {}',
+        });
+    });
+    it('shoud return empty dot args when options are undefined', () => {
+        const factory = new DefaultArtifactTransformerFactory();
+        const resolver = factory;
+        expect(resolver.resolveDotArgs()).toEqual([]);
+    });
+});

package/dist/esm/Output/ArtifactTransformerFactory/OclifTransformerFlagParser.d.ts

@@ -0,0 +1,9 @@
+import { ArtifactTransformerOptions } from '../ArtifactTransformerFactory.js';
+export type TransformerFlagOptions = Record<string, ArtifactTransformerOptions>;
+export declare class OclifTransformerFlagParser {
+    stripOptionFlags(argv: string[]): string[];
+    parse(argv: string[]): TransformerFlagOptions;
+    private isTransformerOptionFlag;
+    private addOption;
+    private mergeOptionValues;
+}

package/dist/esm/Output/ArtifactTransformerFactory/OclifTransformerFlagParser.js

@@ -0,0 +1,76 @@
+export class OclifTransformerFlagParser {
+    stripOptionFlags(argv) {
+        const stripped = [];
+        for (let index = 0; index < argv.length; index += 1) {
+            const token = argv[index];
+            if (!this.isTransformerOptionFlag(token)) {
+                stripped.push(token);
+                continue;
+            }
+            const equalsIndex = token.indexOf('=');
+            if (equalsIndex < 0 &&
+                index + 1 < argv.length &&
+                !argv[index + 1].startsWith('--')) {
+                index += 1;
+            }
+        }
+        return stripped;
+    }
+    parse(argv) {
+        const options = {};
+        for (let index = 0; index < argv.length; index += 1) {
+            const token = argv[index];
+            if (!token.startsWith('--transformer-')) {
+                continue;
+            }
+            if (token === '--transformer' || token.startsWith('--transformer=')) {
+                continue;
+            }
+            const equalsIndex = token.indexOf('=');
+            const flag = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
+            const match = /^--transformer-([A-Za-z0-9_-]+)-([A-Za-z0-9_-]+)$/.exec(flag);
+            if (!match) {
+                continue;
+            }
+            let value = equalsIndex >= 0 ? token.slice(equalsIndex + 1) : undefined;
+            if (value === undefined &&
+                index + 1 < argv.length &&
+                !argv[index + 1].startsWith('--')) {
+                value = argv[index + 1];
+                index += 1;
+            }
+            const [, transformerName, optionName] = match;
+            this.addOption(options, transformerName, optionName, value ?? 'true');
+        }
+        return options;
+    }
+    isTransformerOptionFlag(token) {
+        if (!token.startsWith('--transformer-')) {
+            return false;
+        }
+        if (token === '--transformer' || token.startsWith('--transformer=')) {
+            return false;
+        }
+        const equalsIndex = token.indexOf('=');
+        const flag = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
+        return /^--transformer-([A-Za-z0-9_-]+)-([A-Za-z0-9_-]+)$/.test(flag);
+    }
+    addOption(options, transformerName, optionName, optionValue) {
+        if (!options[transformerName]) {
+            options[transformerName] = {};
+        }
+        const transformerOptions = options[transformerName];
+        const current = transformerOptions[optionName];
+        if (current === undefined) {
+            transformerOptions[optionName] = optionValue;
+            return;
+        }
+        transformerOptions[optionName] = this.mergeOptionValues(current, optionValue);
+    }
+    mergeOptionValues(current, next) {
+        if (Array.isArray(current)) {
+            return [...current, next];
+        }
+        return [current, next];
+    }
+}

package/dist/esm/Output/ArtifactTransformerFactory/OclifTransformerFlagParser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/Output/ArtifactTransformerFactory/OclifTransformerFlagParser.test.js

@@ -0,0 +1,154 @@
+import { OclifTransformerFlagParser } from './OclifTransformerFlagParser.js';
+describe('OclifTransformerFlagParser.parse', () => {
+    it('shoud parse transformer option flags using equals syntax', () => {
+        const parser = new OclifTransformerFlagParser();
+        const options = parser.parse([
+            '--transformer=dotcli',
+            '--transformer-dotcli-format=png',
+            '--transformer-dotcli-dotArg=-Gdpi=200',
+        ]);
+        expect(options).toEqual({
+            dotcli: {
+                format: 'png',
+                dotArg: '-Gdpi=200',
+            },
+        });
+    });
+    it('shoud parse transformer option flags using spaced values', () => {
+        const parser = new OclifTransformerFlagParser();
+        const options = parser.parse([
+            '--transformer',
+            'dotcli',
+            '--transformer-dotcli-format',
+            'svg',
+            '--transformer-dotcli-verbose',
+        ]);
+        expect(options).toEqual({
+            dotcli: {
+                format: 'svg',
+                verbose: 'true',
+            },
+        });
+    });
+    it('shoud accumulate repeated option values', () => {
+        const parser = new OclifTransformerFlagParser();
+        const options = parser.parse([
+            '--transformer-dotcli-dotArg=-Nshape=box',
+            '--transformer-dotcli-dotArg=-Ecolor=red',
+        ]);
+        expect(options).toEqual({
+            dotcli: {
+                dotArg: ['-Nshape=box', '-Ecolor=red'],
+            },
+        });
+    });
+    it('shoud treat missing values as true when followed by another flag', () => {
+        const parser = new OclifTransformerFlagParser();
+        const options = parser.parse(['--transformer-dotcli-format', '--verbose']);
+        expect(options).toEqual({
+            dotcli: {
+                format: 'true',
+            },
+        });
+    });
+    it('shoud skip non-transformer tokens and plain transformer flags', () => {
+        const parser = new OclifTransformerFlagParser();
+        const options = parser.parse([
+            '--profile=edf.aws.dot',
+            '--transformer',
+            'dotcli',
+            '--transformer-dotcli-format=png',
+        ]);
+        expect(options).toEqual({
+            dotcli: {
+                format: 'png',
+            },
+        });
+    });
+    it('shoud ignore transformer base flags even when prefix checks pass', () => {
+        const parser = new OclifTransformerFlagParser();
+        const trickyToken = {
+            startsWith: (value) => value === '--transformer-' || value === '--transformer=',
+        };
+        const options = parser.parse([
+            trickyToken,
+            '--transformer-dotcli-format=png',
+        ]);
+        expect(options).toEqual({
+            dotcli: {
+                format: 'png',
+            },
+        });
+    });
+    it('shoud ignore invalid transformer option flags', () => {
+        const parser = new OclifTransformerFlagParser();
+        const options = parser.parse(['--transformer-dotcli']);
+        expect(options).toEqual({});
+    });
+    it('shoud append repeated option values once already an array', () => {
+        const parser = new OclifTransformerFlagParser();
+        const options = parser.parse([
+            '--transformer-dotcli-dotArg=-a',
+            '--transformer-dotcli-dotArg=-b',
+            '--transformer-dotcli-dotArg=-c',
+        ]);
+        expect(options).toEqual({
+            dotcli: {
+                dotArg: ['-a', '-b', '-c'],
+            },
+        });
+    });
+    it('shoud validate transformer option flags directly', () => {
+        const parser = new OclifTransformerFlagParser();
+        const checker = parser;
+        expect(checker.isTransformerOptionFlag('--transformer-dotcli-format=png')).toBe(true);
+        expect(checker.isTransformerOptionFlag('--transformer-dotcli-format')).toBe(true);
+        expect(checker.isTransformerOptionFlag('--profile=edf.aws.dot')).toBe(false);
+        const trickyToken = {
+            startsWith: (value) => value === '--transformer-' || value === '--transformer=',
+        };
+        expect(checker.isTransformerOptionFlag(trickyToken)).toBe(false);
+        expect(checker.isTransformerOptionFlag('--transformer')).toBe(false);
+        expect(checker.isTransformerOptionFlag('--transformer=dotcli')).toBe(false);
+    });
+});
+describe('OclifTransformerFlagParser.stripOptionFlags', () => {
+    it('shoud remove transformer option flags while keeping declared flags', () => {
+        const parser = new OclifTransformerFlagParser();
+        const stripped = parser.stripOptionFlags([
+            '--profile=edf.aws.dot',
+            '--transformer=dotcli',
+            '--transformer-dotcli-format=png',
+            '--transformer-dotcli-dotArg',
+            '-Gdpi=200',
+            '--verbose',
+        ]);
+        expect(stripped).toEqual([
+            '--profile=edf.aws.dot',
+            '--transformer=dotcli',
+            '--verbose',
+        ]);
+    });
+    it('shoud keep non-matching flags that share the prefix', () => {
+        const parser = new OclifTransformerFlagParser();
+        const stripped = parser.stripOptionFlags([
+            '--transformer-dotcli',
+            '--transformer-dotcli-format=png',
+            '--transformer',
+            'dotcli',
+        ]);
+        expect(stripped).toEqual([
+            '--transformer-dotcli',
+            '--transformer',
+            'dotcli',
+        ]);
+    });
+    it('shoud not consume the next flag when a value is missing', () => {
+        const parser = new OclifTransformerFlagParser();
+        const stripped = parser.stripOptionFlags([
+            '--transformer-dotcli-format',
+            '--verbose',
+        ]);
+        expect(stripped).toEqual(['--verbose']);
+    });
+});

package/dist/esm/Output/ArtifactTransformerFactory/index.d.ts

@@ -0,0 +1,2 @@
+export * from './DefaultArtifactTransformerFactory.js';
+export * from './OclifTransformerFlagParser.js';

package/dist/esm/Output/ArtifactTransformerFactory/index.js

@@ -0,0 +1,2 @@
+export * from './DefaultArtifactTransformerFactory.js';
+export * from './OclifTransformerFlagParser.js';

package/dist/esm/Output/ArtifactTransformerFactory.d.ts

@@ -0,0 +1,10 @@
+import { ArtifactTransformer } from './ArtifactTransformer.js';
+export type ArtifactTransformerOptionValue = string | string[];
+export type ArtifactTransformerOptions = Record<string, ArtifactTransformerOptionValue>;
+export type ArtifactTransformerFactoryInput = {
+    name: string;
+    options?: ArtifactTransformerOptions;
+};
+export interface ArtifactTransformerFactory {
+    create(input: ArtifactTransformerFactoryInput): ArtifactTransformer;
+}

package/dist/esm/Output/ArtifactTransformerFactory.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/Output/ArtifactWriter/FileArtifactWriter.d.ts

@@ -0,0 +1,9 @@
+import { ArtifactWriteInput, ArtifactWriter } from '../ArtifactWriter.js';
+export type FileArtifactWriterOptions = {
+    createDirectories?: boolean;
+};
+export declare class FileArtifactWriter implements ArtifactWriter {
+    private readonly createDirectories;
+    constructor(options?: FileArtifactWriterOptions);
+    write(input: ArtifactWriteInput): Promise<void>;
+}

package/dist/esm/Output/ArtifactWriter/FileArtifactWriter.js

@@ -0,0 +1,21 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export class FileArtifactWriter {
+    createDirectories;
+    constructor(options = {}) {
+        this.createDirectories = options.createDirectories ?? true;
+    }
+    async write(input) {
+        if (!input.target) {
+            throw new Error('FileArtifactWriter requires a target path');
+        }
+        if (this.createDirectories) {
+            await mkdir(dirname(input.target), { recursive: true });
+        }
+        if (typeof input.artifact.content === 'string') {
+            await writeFile(input.target, input.artifact.content, 'utf8');
+            return;
+        }
+        await writeFile(input.target, Buffer.from(input.artifact.content));
+    }
+}

package/dist/esm/Output/ArtifactWriter/FileArtifactWriter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/Output/ArtifactWriter/FileArtifactWriter.test.js

@@ -0,0 +1,75 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { FileArtifactWriter } from './FileArtifactWriter.js';
+describe('FileArtifactWriter.write', () => {
+    it('shoud write string content to target path', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'file-artifact-writer-'));
+        const target = join(dir, 'nested', 'graph.dot');
+        const writer = new FileArtifactWriter();
+        try {
+            await writer.write({
+                target,
+                artifact: {
+                    content: 'digraph G {}',
+                    mediaType: 'text/vnd.graphviz',
+                    extension: 'dot',
+                },
+            });
+            const written = await readFile(target, 'utf8');
+            expect(written).toBe('digraph G {}');
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    it('shoud write binary content to target path', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'file-artifact-writer-'));
+        const target = join(dir, 'diagram.png');
+        const writer = new FileArtifactWriter();
+        try {
+            await writer.write({
+                target,
+                artifact: {
+                    content: Buffer.from([10, 20, 30]),
+                    mediaType: 'image/png',
+                    extension: 'png',
+                },
+            });
+            const written = await readFile(target);
+            expect(written).toEqual(Buffer.from([10, 20, 30]));
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    it('shoud fail when no target path is provided', async () => {
+        const writer = new FileArtifactWriter();
+        await expect(writer.write({
+            artifact: {
+                content: 'data',
+                mediaType: 'text/plain',
+            },
+        })).rejects.toThrow('FileArtifactWriter requires a target path');
+    });
+    it('shoud skip directory creation when disabled', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'file-artifact-writer-'));
+        const target = join(dir, 'graph.dot');
+        const writer = new FileArtifactWriter({ createDirectories: false });
+        try {
+            await writer.write({
+                target,
+                artifact: {
+                    content: 'digraph G {}',
+                    mediaType: 'text/vnd.graphviz',
+                    extension: 'dot',
+                },
+            });
+            const written = await readFile(target, 'utf8');
+            expect(written).toBe('digraph G {}');
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/esm/Output/ArtifactWriter/StdoutArtifactWriter.d.ts

@@ -0,0 +1,6 @@
+import { ArtifactWriteInput, ArtifactWriter } from '../ArtifactWriter.js';
+export declare class StdoutArtifactWriter implements ArtifactWriter {
+    private readonly stream;
+    constructor(stream?: NodeJS.WritableStream);
+    write(input: ArtifactWriteInput): Promise<void>;
+}

package/dist/esm/Output/ArtifactWriter/StdoutArtifactWriter.js

@@ -0,0 +1,13 @@
+import { once } from 'node:events';
+export class StdoutArtifactWriter {
+    stream;
+    constructor(stream = process.stdout) {
+        this.stream = stream;
+    }
+    async write(input) {
+        const wasWritten = this.stream.write(input.artifact.content);
+        if (!wasWritten) {
+            await once(this.stream, 'drain');
+        }
+    }
+}

package/dist/esm/Output/ArtifactWriter/StdoutArtifactWriter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/Output/ArtifactWriter/StdoutArtifactWriter.test.js

@@ -0,0 +1,81 @@
+import { Writable } from 'node:stream';
+import { StdoutArtifactWriter } from './StdoutArtifactWriter.js';
+class CaptureWritable extends Writable {
+    chunks = [];
+    _write(chunk, _encoding, callback) {
+        if (typeof chunk === 'string') {
+            this.chunks.push(Buffer.from(chunk));
+        }
+        else {
+            this.chunks.push(chunk);
+        }
+        callback();
+    }
+}
+class BackpressureWritable extends Writable {
+    drainCount = 0;
+    _write(_chunk, _encoding, callback) {
+        callback();
+    }
+    write(chunk, encoding, callback) {
+        if (typeof encoding === 'function') {
+            super.write(chunk, encoding);
+        }
+        else {
+            super.write(chunk, encoding, callback);
+        }
+        setImmediate(() => {
+            this.drainCount += 1;
+            this.emit('drain');
+        });
+        return false;
+    }
+}
+describe('StdoutArtifactWriter.write', () => {
+    it('shoud write artifact content to the configured stream', async () => {
+        const stream = new CaptureWritable();
+        const writer = new StdoutArtifactWriter(stream);
+        await writer.write({
+            artifact: {
+                content: 'digraph G {}',
+                mediaType: 'text/vnd.graphviz',
+            },
+        });
+        await writer.write({
+            artifact: {
+                content: Buffer.from([1, 2, 3]),
+                mediaType: 'application/octet-stream',
+            },
+        });
+        expect(Buffer.concat(stream.chunks)).toEqual(Buffer.concat([Buffer.from('digraph G {}'), Buffer.from([1, 2, 3])]));
+    });
+    it('shoud wait for drain when backpressure is signaled', async () => {
+        const stream = new BackpressureWritable();
+        const writer = new StdoutArtifactWriter(stream);
+        await writer.write({
+            artifact: {
+                content: 'digraph G {}',
+                mediaType: 'text/vnd.graphviz',
+            },
+        });
+        expect(stream.drainCount).toBeGreaterThan(0);
+    });
+    it('shoud default to process stdout when no stream is provided', async () => {
+        const originalWrite = process.stdout.write.bind(process.stdout);
+        const writeMock = jest.fn(() => true);
+        process.stdout.write = writeMock;
+        const writer = new StdoutArtifactWriter();
+        try {
+            await writer.write({
+                artifact: {
+                    content: 'digraph G {}',
+                    mediaType: 'text/vnd.graphviz',
+                },
+            });
+        }
+        finally {
+            process.stdout.write = originalWrite;
+        }
+        expect(writeMock).toHaveBeenCalled();
+    });
+});

package/dist/esm/Output/ArtifactWriter/index.d.ts

@@ -0,0 +1,2 @@
+export * from './FileArtifactWriter.js';
+export * from './StdoutArtifactWriter.js';

package/dist/esm/Output/ArtifactWriter/index.js

@@ -0,0 +1,2 @@
+export * from './FileArtifactWriter.js';
+export * from './StdoutArtifactWriter.js';

package/dist/esm/Output/ArtifactWriter.d.ts

@@ -0,0 +1,8 @@
+import { RenderArtifact } from '../Graph/Renderer.js';
+export type ArtifactWriteInput = {
+    artifact: RenderArtifact;
+    target?: string;
+};
+export interface ArtifactWriter<TInput extends ArtifactWriteInput = ArtifactWriteInput> {
+    write(input: TInput): Promise<void>;
+}

package/dist/esm/Output/ArtifactWriter.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/Output/RenderPipeline.d.ts

@@ -0,0 +1,12 @@
+import { RenderArtifact } from '../Graph/Renderer.js';
+import { ArtifactTransformer } from './ArtifactTransformer.js';
+import { ArtifactWriteInput, ArtifactWriter } from './ArtifactWriter.js';
+export type RenderPipelineExecuteInput<TWriteInput extends ArtifactWriteInput = ArtifactWriteInput> = {
+    artifact: RenderArtifact;
+    writer: ArtifactWriter<TWriteInput>;
+    write: Omit<TWriteInput, 'artifact'>;
+    transformers?: ArtifactTransformer[];
+};
+export declare class RenderPipeline {
+    execute<TWriteInput extends ArtifactWriteInput = ArtifactWriteInput>(input: RenderPipelineExecuteInput<TWriteInput>): Promise<RenderArtifact>;
+}

package/dist/esm/Output/RenderPipeline.js

@@ -0,0 +1,13 @@
+export class RenderPipeline {
+    async execute(input) {
+        let artifact = input.artifact;
+        for (const transformer of input.transformers ?? []) {
+            artifact = await transformer.transform({ artifact });
+        }
+        await input.writer.write({
+            ...input.write,
+            artifact,
+        });
+        return artifact;
+    }
+}

package/dist/esm/Output/RenderPipeline.test.d.ts

@@ -0,0 +1 @@
+export {};