@terra-graph/core 1.0.0-rc.4

package/dist/esm/Graph/Rules/Edge/EdgeDirectionSemantic.test.js

@@ -0,0 +1,452 @@
+import { DirectedGraph } from 'graphology';
+import { GraphologyAdapter } from '../../Adapters/GraphologyAdapter.js';
+import { TG_SCHEMA_VERSION, TgEdgeDirectionSemantics, asEdgeId, asNodeId, } from '../../TgGraph.js';
+import { EdgeDirectionSemantic } from './EdgeDirectionSemantic.js';
+describe('EdgeDirectionSemantic.constructor', () => {
+    it('shoud require options', () => {
+        expect(() => new EdgeDirectionSemantic({
+            edge: { from: { any: true }, to: { any: true } },
+        })).toThrow(`Rule 'EdgeDirectionSemantic' requires options in config`);
+    });
+    it('shoud require a valid semantic option', () => {
+        expect(() => new EdgeDirectionSemantic({
+            edge: { from: { any: true }, to: { any: true } },
+            options: {
+                semantic: 'invalid',
+            },
+        })).toThrow(`Rule 'EdgeDirectionSemantic' requires options.semantic`);
+    });
+    it('shoud require overwrite to be a boolean when provided', () => {
+        expect(() => new EdgeDirectionSemantic({
+            edge: { from: { any: true }, to: { any: true } },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+                overwrite: 'yes',
+            },
+        })).toThrow(`Rule 'EdgeDirectionSemantic' options.overwrite must be a boolean when provided`);
+    });
+    it('shoud require enforceDirection to be a boolean when provided', () => {
+        expect(() => new EdgeDirectionSemantic({
+            edge: { from: { any: true }, to: { any: true } },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+                enforceDirection: 'yes',
+            },
+        })).toThrow(`Rule 'EdgeDirectionSemantic' options.enforceDirection must be a boolean when provided`);
+    });
+});
+describe('EdgeDirectionSemantic.apply', () => {
+    it('shoud set edge direction semantic for matching edges', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-a-b');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeA,
+                    to: nodeB,
+                    attributes: { weight: 1 },
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-b' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({
+            weight: 1,
+            directionSemantic: TgEdgeDirectionSemantics.Invokes,
+        });
+    });
+    it('shoud preserve existing direction semantic by default', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-a-b');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeA,
+                    to: nodeB,
+                    attributes: {
+                        weight: 1,
+                        directionSemantic: TgEdgeDirectionSemantics.Accesses,
+                    },
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-b' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({
+            weight: 1,
+            directionSemantic: TgEdgeDirectionSemantics.Accesses,
+        });
+    });
+    it('shoud overwrite existing direction semantic when configured', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-a-b');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeA,
+                    to: nodeB,
+                    attributes: {
+                        weight: 1,
+                        directionSemantic: TgEdgeDirectionSemantics.Accesses,
+                    },
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-b' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+                overwrite: true,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({
+            weight: 1,
+            directionSemantic: TgEdgeDirectionSemantics.Invokes,
+        });
+    });
+    it('shoud keep inbound matching edges unchanged when enforceDirection is false', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-b-a');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeB,
+                    to: nodeA,
+                    attributes: { weight: 1 },
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-b' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.edgeSource(edgeId)).toBe(nodeB);
+        expect(result.edgeTarget(edgeId)).toBe(nodeA);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({ weight: 1 });
+    });
+    it('shoud reverse inbound matching edges when enforceDirection is true', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-b-a');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeB,
+                    to: nodeA,
+                    attributes: { weight: 1 },
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-b' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+                enforceDirection: true,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.edgeSource(edgeId)).toBe(nodeA);
+        expect(result.edgeTarget(edgeId)).toBe(nodeB);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({
+            weight: 1,
+            directionSemantic: TgEdgeDirectionSemantics.Invokes,
+        });
+    });
+    it('shoud skip reversing inbound edges with conflicting semantics when overwrite is false', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-b-a');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeB,
+                    to: nodeA,
+                    attributes: {
+                        directionSemantic: TgEdgeDirectionSemantics.Accesses,
+                    },
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-b' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+                enforceDirection: true,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.edgeSource(edgeId)).toBe(nodeB);
+        expect(result.edgeTarget(edgeId)).toBe(nodeA);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({
+            directionSemantic: TgEdgeDirectionSemantics.Accesses,
+        });
+    });
+    it('shoud return early when the source node no longer matches', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-a-b');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeA,
+                    to: nodeB,
+                    attributes: {},
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { attr: { key: 'label', eq: 'A' } },
+                to: { any: true },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const mismatchedNode = { ...node, label: 'mismatch' };
+        const result = rule.apply(nodeA, mismatchedNode, adapter);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({});
+    });
+    it('shoud skip outbound edges when the target does not match', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-a-b');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeA,
+                    to: nodeB,
+                    attributes: {},
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-c' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({});
+    });
+    it('shoud ignore inbound edges when the source does not match the target query', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-b-a');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeB,
+                    to: nodeA,
+                    attributes: {},
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-c' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+                enforceDirection: true,
+            },
+        });
+        rule.match(nodeA, node, adapter);
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.edgeSource(edgeId)).toBe(nodeB);
+        expect(result.edgeTarget(edgeId)).toBe(nodeA);
+    });
+    it('shoud keep graph unchanged when apply is called without a match', () => {
+        const nodeA = asNodeId('node-a');
+        const nodeB = asNodeId('node-b');
+        const edgeId = asEdgeId('edge-a-b');
+        const tg = {
+            schemaVersion: TG_SCHEMA_VERSION,
+            description: {},
+            nodes: {
+                [nodeA]: { id: nodeA, label: 'A' },
+                [nodeB]: { id: nodeB, label: 'B' },
+            },
+            edges: [
+                {
+                    id: edgeId,
+                    from: nodeA,
+                    to: nodeB,
+                    attributes: {},
+                },
+            ],
+        };
+        const adapter = new GraphologyAdapter(new DirectedGraph()).withTgGraph(tg);
+        const node = adapter.getNodeAttributes(nodeA);
+        if (!node) {
+            throw new Error('Missing node attributes for node-a');
+        }
+        const rule = new EdgeDirectionSemantic({
+            edge: {
+                from: { nodeId: { eq: 'node-a' } },
+                to: { nodeId: { eq: 'node-b' } },
+            },
+            options: {
+                semantic: TgEdgeDirectionSemantics.Invokes,
+            },
+        });
+        const result = rule.apply(nodeA, node, adapter);
+        expect(result.getEdgeAttributes(edgeId)).toEqual({});
+    });
+});

package/dist/esm/Graph/Rules/Edge/EdgeDotProperties.d.ts

@@ -0,0 +1,9 @@
+import { AdapterOperations } from '../../Operations/Operations.js';
+import { NodeId, TgNodeAttributes } from '../../TgGraph.js';
+import { EdgeRule } from '../Rule.js';
+import { EdgeRuleConfig } from '../RuleConfig.js';
+export declare class EdgeDotProperties extends EdgeRule {
+    constructor(config: EdgeRuleConfig);
+    supports(adapter: AdapterOperations): boolean;
+    apply(nodeId: NodeId, node: TgNodeAttributes, graph: AdapterOperations): AdapterOperations;
+}

package/dist/esm/Graph/Rules/Edge/EdgeDotProperties.js

@@ -0,0 +1,46 @@
+import { DotAdapter } from '../../Adapters/DotAdapter.js';
+import { EdgeRule } from '../Rule.js';
+export class EdgeDotProperties extends EdgeRule {
+    constructor(config) {
+        if (config.options === undefined) {
+            throw new Error(`Rule '${EdgeDotProperties.name}' requires options in config`);
+        }
+        super(config);
+    }
+    supports(adapter) {
+        return adapter instanceof DotAdapter;
+    }
+    apply(nodeId, node, graph) {
+        if (!this.wasMatched(nodeId)) {
+            return graph;
+        }
+        let updated = graph;
+        const { from, to } = this.query;
+        if (!from.match(nodeId, node, updated)) {
+            return updated;
+        }
+        const adapterKey = DotAdapter.name;
+        const properties = this.config.options ?? {};
+        const edges = updated.outEdges(nodeId);
+        for (const edgeId of edges) {
+            const targetId = updated.edgeTarget(edgeId);
+            const target = updated.getNodeAttributes(targetId);
+            if (!target || !to.match(targetId, target, updated)) {
+                continue;
+            }
+            const current = updated.getEdgeAttributes(edgeId);
+            updated = updated.setEdge(edgeId, nodeId, targetId, {
+                ...current,
+                adapter: {
+                    ...(current.adapter ?? {}),
+                    [adapterKey]: {
+                        ...(current.adapter?.[adapterKey] ?? {}),
+                        ...properties,
+                    },
+                },
+            });
+        }
+        return updated;
+    }
+}
+EdgeRule.register(EdgeDotProperties);

package/dist/esm/Graph/Rules/Edge/EdgeDotProperties.test.d.ts

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