@terra-graph/core 1.0.0-rc.4

package/dist/esm/Graph/ProfileRegistry.d.ts

@@ -0,0 +1,18 @@
+import { Profile } from './Profile.js';
+type ProfileFactory = () => Profile;
+export type ProfileDefinition = Profile | ProfileFactory;
+export type ProfileDefinitions = Record<string, ProfileDefinition>;
+export declare class ProfileRegistry {
+    private readonly definitions;
+    constructor(definitions?: ProfileDefinitions, factories?: Record<string, ProfileFactory>);
+    static from(registries: ProfileRegistry[]): ProfileRegistry;
+    register(name: string, definition: ProfileDefinition): ProfileRegistry;
+    registerMany(definitions: ProfileDefinitions): ProfileRegistry;
+    use(registry: ProfileRegistry): ProfileRegistry;
+    resolve(name: string): Profile;
+    names(): string[];
+    private static fromFactories;
+    private static toFactories;
+    private static toFactory;
+}
+export {};

package/dist/esm/Graph/ProfileRegistry.js

@@ -0,0 +1,57 @@
+export class ProfileRegistry {
+    definitions;
+    constructor(definitions = {}, factories) {
+        this.definitions = Object.freeze(factories ?? ProfileRegistry.toFactories(definitions));
+    }
+    static from(registries) {
+        return registries.reduce((combined, registry) => combined.use(registry), new ProfileRegistry());
+    }
+    register(name, definition) {
+        return ProfileRegistry.fromFactories({
+            ...this.definitions,
+            [name]: ProfileRegistry.toFactory(definition),
+        });
+    }
+    registerMany(definitions) {
+        const nextFactories = {
+            ...this.definitions,
+            ...ProfileRegistry.toFactories(definitions),
+        };
+        return ProfileRegistry.fromFactories(nextFactories);
+    }
+    use(registry) {
+        return ProfileRegistry.fromFactories({
+            ...this.definitions,
+            ...registry.definitions,
+        });
+    }
+    resolve(name) {
+        const factory = this.definitions[name];
+        if (!factory) {
+            throw new Error(`Profile '${name}' is not registered`);
+        }
+        const profile = factory();
+        if (profile.name !== name) {
+            throw new Error(`Profile registry key '${name}' does not match profile.name '${profile.name}'`);
+        }
+        return profile;
+    }
+    names() {
+        return Object.keys(this.definitions);
+    }
+    static fromFactories(definitions) {
+        return new ProfileRegistry({}, { ...definitions });
+    }
+    static toFactories(definitions) {
+        return Object.fromEntries(Object.entries(definitions).map(([name, definition]) => [
+            name,
+            ProfileRegistry.toFactory(definition),
+        ]));
+    }
+    static toFactory(definition) {
+        if (typeof definition === 'function') {
+            return definition;
+        }
+        return () => definition;
+    }
+}

package/dist/esm/Graph/ProfileRegistry.test.d.ts

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

package/dist/esm/Graph/ProfileRegistry.test.js

@@ -0,0 +1,96 @@
+import { Profile } from './Profile.js';
+import { ProfileRegistry } from './ProfileRegistry.js';
+describe('ProfileRegistry.resolve', () => {
+    it('shoud resolve a named profile instance', () => {
+        const profile = new Profile('example.profile', {});
+        const registry = new ProfileRegistry({
+            'example.profile': profile,
+        });
+        expect(registry.resolve('example.profile')).toBe(profile);
+    });
+    it('shoud resolve a fresh instance each time for a named profile factory', () => {
+        const registry = new ProfileRegistry({
+            'factory.profile': () => new Profile('factory.profile', {}),
+        });
+        const first = registry.resolve('factory.profile');
+        const second = registry.resolve('factory.profile');
+        expect(first).not.toBe(second);
+        expect(first.name).toBe(second.name);
+    });
+    it('shoud throw when a named profile is not registered', () => {
+        const registry = new ProfileRegistry();
+        expect(() => registry.resolve('doesNotExist')).toThrow("Profile 'doesNotExist' is not registered");
+    });
+    it('shoud throw when registry key and profile name do not match', () => {
+        const registry = new ProfileRegistry({
+            'expected.profile': new Profile('wrong.profile', {}),
+        });
+        expect(() => registry.resolve('expected.profile')).toThrow("Profile registry key 'expected.profile' does not match profile.name 'wrong.profile'");
+    });
+});
+describe('ProfileRegistry.register', () => {
+    it('shoud return a new registry without mutating the original', () => {
+        const base = new ProfileRegistry({
+            'one.profile': new Profile('one.profile', {}),
+        });
+        const next = base.register('two.profile', new Profile('two.profile', {}));
+        expect(base.names()).toEqual(['one.profile']);
+        expect(next.names()).toEqual(['one.profile', 'two.profile']);
+    });
+});
+describe('ProfileRegistry.registerMany', () => {
+    it('shoud return a new registry with merged definitions', () => {
+        const base = new ProfileRegistry({
+            'one.profile': new Profile('one.profile', {}),
+        });
+        const next = base.registerMany({
+            'two.profile': () => new Profile('two.profile', {}),
+        });
+        expect(base.names()).toEqual(['one.profile']);
+        expect(next.names()).toEqual(['one.profile', 'two.profile']);
+        expect(next.resolve('two.profile')).not.toBe(next.resolve('two.profile'));
+    });
+});
+describe('ProfileRegistry.use', () => {
+    it('shoud combine registries immutably', () => {
+        const one = new ProfileRegistry({
+            'one.profile': new Profile('one.profile', {}),
+        });
+        const two = new ProfileRegistry({
+            'two.profile': new Profile('two.profile', {}),
+        });
+        const combined = one.use(two);
+        expect(one.names()).toEqual(['one.profile']);
+        expect(two.names()).toEqual(['two.profile']);
+        expect(combined.names()).toEqual(['one.profile', 'two.profile']);
+    });
+});
+describe('ProfileRegistry.from', () => {
+    it('shoud combine an array of registries', () => {
+        const one = new ProfileRegistry({
+            'one.profile': new Profile('one.profile', {}),
+        });
+        const two = new ProfileRegistry({
+            'two.profile': new Profile('two.profile', {}),
+        });
+        const combined = ProfileRegistry.from([one, two]);
+        expect(combined.names()).toEqual(['one.profile', 'two.profile']);
+    });
+    it('shoud prefer later registries when names collide', () => {
+        const one = new ProfileRegistry({
+            'shared.profile': new Profile('shared.profile', {
+                phases: [{ phase: 'main', rules: [] }],
+            }),
+        });
+        const two = new ProfileRegistry({
+            'shared.profile': new Profile('shared.profile', {
+                phases: [{ phase: 'cleanup', rules: [] }],
+            }),
+        });
+        const combined = ProfileRegistry.from([one, two]);
+        const resolved = combined.resolve('shared.profile');
+        expect(resolved.serialize().phases).toEqual([
+            { phase: 'cleanup', rules: [] },
+        ]);
+    });
+});

package/dist/esm/Graph/Renderer.d.ts

@@ -0,0 +1,9 @@
+import { Adapter } from './Adapter.js';
+export type RenderArtifact = {
+    content: string | Uint8Array;
+    mediaType: string;
+    extension?: string;
+};
+export interface Renderer<TAdapter extends Adapter> {
+    render(adapter: TAdapter): RenderArtifact;
+}

package/dist/esm/Graph/Renderer.js

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

package/dist/esm/Graph/Renderers/DotRenderer.d.ts

@@ -0,0 +1,27 @@
+import { DotAdapter } from '../Adapters/DotAdapter.js';
+import { RenderArtifact, Renderer } from '../Renderer.js';
+type DotGraphAttributes = {
+    rankdir?: 'TB' | 'BT' | 'LR' | 'RL';
+    ranksep?: number;
+    nodesep?: number;
+    pad?: number;
+} & Record<string, string | number | boolean | undefined>;
+export type DotRendererOptions = {
+    graph?: DotGraphAttributes;
+};
+export declare class DotRenderer implements Renderer<DotAdapter> {
+    private readonly options;
+    constructor(options?: DotRendererOptions);
+    render(adapter: DotAdapter): RenderArtifact;
+    private addNodes;
+    private addEdges;
+    private collectLegendEdges;
+    private collectLegendEntries;
+    private toDotNodeAttributes;
+    private toDotEdgeAttributes;
+    private applyRanks;
+    private applyLegend;
+    private buildNodeLabel;
+    private static resolveGraphOptions;
+}
+export {};

package/dist/esm/Graph/Renderers/DotRenderer.js

@@ -0,0 +1,179 @@
+import { Graph as GraphLibGraph } from 'graphlib';
+import dot from 'graphlib-dot';
+import { DotAdapter } from '../Adapters/DotAdapter.js';
+import { TgNodeLabel } from './TgNodeLabel.js';
+const defaultGraphOptions = {
+    graph: {
+        rankdir: 'LR',
+        ranksep: 2.5,
+        nodesep: 0.6,
+        pad: 1,
+    },
+};
+export class DotRenderer {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            graph: DotRenderer.resolveGraphOptions(options.graph),
+        };
+    }
+    render(adapter) {
+        const tg = adapter.toTgGraph();
+        const graph = new GraphLibGraph({
+            directed: true,
+            multigraph: true,
+            compound: true,
+        });
+        /* istanbul ignore next */
+        graph.setGraph(this.options.graph ?? {});
+        this.addNodes(graph, tg);
+        this.addEdges(graph, tg);
+        let output = dot.write(graph);
+        output = this.applyLegend(output, tg);
+        output = this.applyRanks(output, adapter);
+        return {
+            content: output,
+            mediaType: 'text/vnd.graphviz',
+            extension: 'dot',
+        };
+    }
+    addNodes(graph, tg) {
+        for (const node of Object.values(tg.nodes)) {
+            graph.setNode(node.id, this.toDotNodeAttributes(node));
+        }
+    }
+    addEdges(graph, tg) {
+        for (const edge of tg.edges) {
+            graph.setEdge({ v: edge.from, w: edge.to, name: edge.id }, this.toDotEdgeAttributes(edge));
+        }
+    }
+    collectLegendEdges(tg) {
+        return tg.edges.filter((edge) => edge.attributes?.legend !== undefined);
+    }
+    collectLegendEntries(tg) {
+        const entries = this.collectLegendEdges(tg)
+            .map((edge) => edge.attributes?.legend)
+            .filter((legend) => legend !== undefined);
+        const unique = new Map();
+        for (const entry of entries) {
+            unique.set(`${entry.title}:${entry.colour}`, entry);
+        }
+        return [...unique.values()];
+    }
+    toDotNodeAttributes(node) {
+        return {
+            label: this.buildNodeLabel(node),
+            ...(node.adapter?.[DotAdapter.name] ?? {}),
+        };
+    }
+    toDotEdgeAttributes(edge) {
+        const dotAdapterAttributes = edge.attributes?.adapter?.[DotAdapter.name] ?? {};
+        if (edge.attributes?.legend) {
+            return {
+                ...dotAdapterAttributes,
+                color: edge.attributes.legend.colour,
+            };
+        }
+        return {
+            ...dotAdapterAttributes,
+        };
+    }
+    applyRanks(output, adapter) {
+        const ranks = adapter.getRanks();
+        if (ranks.length === 0) {
+            return output;
+        }
+        const existingNodeIds = new Set(adapter.nodeIds());
+        const filteredRanks = ranks
+            .map((rank) => ({
+            ...rank,
+            nodes: rank.nodes.filter((nodeId) => existingNodeIds.has(nodeId)),
+        }))
+            .filter((rank) => rank.nodes.length > 1);
+        if (filteredRanks.length === 0) {
+            return output;
+        }
+        const rankBlock = filteredRanks
+            .map((rank) => {
+            const nodes = rank.nodes.map((nodeId) => `"${nodeId}"`).join(' ');
+            return `  { rank = ${rank.mode}; ${nodes} }`;
+        })
+            .join('\n');
+        const lastBrace = output.lastIndexOf('}');
+        if (lastBrace === -1) {
+            return output;
+        }
+        return `${output.slice(0, lastBrace)}\n${rankBlock}\n}`;
+    }
+    applyLegend(output, tg) {
+        const legends = this.collectLegendEntries(tg);
+        const hasDescription = Object.keys(tg.description).length > 0;
+        if (legends.length === 0 && !hasDescription) {
+            return output;
+        }
+        const clusterName = 'Legend';
+        const descriptionRows = Object.entries(tg.description)
+            .map(([key, value]) => {
+            return `<tr><td align="left"><font point-size="10" color="#999999">${key}:</font></td><td align="left"><font point-size="10" color="#000000">&nbsp;&nbsp;&nbsp;${String(value)}</font></td></tr>`;
+        })
+            .join('');
+        const descriptionNode = hasDescription
+            ? `    "${clusterName}_description" [shape="plaintext" fontname="sans-serif" label=<<table align="left" border="0" cellpadding="2" cellspacing="0" cellborder="0">${descriptionRows}</table>>];`
+            : '';
+        const legendRows = legends
+            .map((legend, index) => {
+            const descriptionLink = hasDescription
+                ? `\n    "${clusterName}_description" -> "${clusterName}.A${index}" [style="invis"];`
+                : '';
+            return [
+                `    "${clusterName}.A${index}" [label="" style="invis" height=0 width=0];`,
+                `    "${clusterName}.B${index}" [label="" style="invis" height=0 width=0];`,
+                `    "${clusterName}.A${index}" -> "${clusterName}.B${index}" [label="${legend.title}" fontname="sans-serif" fontsize="10" color="${legend.colour}"];${descriptionLink}`,
+            ].join('\n');
+        })
+            .join('\n');
+        const keySubgraph = `  subgraph "cluster_${clusterName}" {
+    label = "${clusterName}"
+    color = "#DDDDDD"
+    fontname = "sans-serif"
+    penwidth = 0.75
+    fontcolor = "#999999"
+    fontsize = 10
+${descriptionNode}
+${legendRows}
+  }
+  subgraph cluster_padKey {
+    style = "invis"
+    "S1" [style="invis"];
+    "S2" [style="invis"];
+    "S3" [style="invis"];
+    "S4" [style="invis"];
+    "S1" -> "S2" [style="invis"];
+    "S2" -> "S3" [style="invis"];
+    "S3" -> "S4" [style="invis"];
+  }`;
+        const firstBrace = output.indexOf('{');
+        if (firstBrace === -1) {
+            return output;
+        }
+        return `${output.slice(0, firstBrace + 1)}\n${keySubgraph}\n${output.slice(firstBrace + 1)}`;
+    }
+    buildNodeLabel(node) {
+        return new TgNodeLabel(node).getLabel();
+    }
+    static resolveGraphOptions(input) {
+        /* istanbul ignore next */
+        const graphOptions = {
+            ...(defaultGraphOptions.graph ?? {}),
+            ...(input ?? {}),
+        };
+        if (graphOptions.rankdir === 'TB' || graphOptions.rankdir === 'BT') {
+            return {
+                ...graphOptions,
+                nodesep: input?.nodesep ?? 2.5,
+                ranksep: input?.ranksep ?? 0.6,
+            };
+        }
+        return graphOptions;
+    }
+}

package/dist/esm/Graph/Renderers/DotRenderer.test.d.ts

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