@terra-graph/core 1.0.0-rc.4

package/dist/esm/Runtime/RuntimeCatalogLoader.test.js

@@ -0,0 +1,452 @@
+import { Profile } from '../Graph/Profile.js';
+import { ProfileRegistry } from '../Graph/ProfileRegistry.js';
+import { NamedRuleRegistry } from '../Graph/Rules/NamedRuleRegistry.js';
+import { NamedRuleSetRegistry } from '../Graph/Rules/NamedRuleSetRegistry.js';
+import { RemoveNode } from '../Graph/Rules/Node/RemoveNode.js';
+import { RuntimeCatalog } from './RuntimeCatalog.js';
+import { RuntimeCatalogLoader } from './RuntimeCatalogLoader.js';
+describe('RuntimeCatalogLoader.fromSerialized', () => {
+    it('shoud build runtime catalog assets from serialized config', () => {
+        const catalog = RuntimeCatalogLoader.fromSerialized({
+            namedRules: {
+                removeAlways: {
+                    id: 'RemoveNode',
+                    config: { node: { any: true } },
+                },
+            },
+            namedRuleSets: {
+                wrapper: {
+                    rules: [{ namedRule: 'removeAlways' }],
+                },
+            },
+            profiles: {
+                'custom.profile': {
+                    phases: [
+                        {
+                            phase: 'main',
+                            rules: [{ namedRuleSet: 'wrapper' }],
+                        },
+                    ],
+                },
+            },
+        });
+        const phases = catalog.resolveProfilePhases('custom.profile');
+        expect(phases).toHaveLength(1);
+        expect(phases[0]).toHaveLength(1);
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { any: true } },
+        });
+    });
+    it('shoud resolve serialized profile inheritance by profile name', () => {
+        const catalog = RuntimeCatalogLoader.fromSerialized({
+            namedRules: {
+                removeBase: {
+                    id: 'RemoveNode',
+                    config: { node: { attr: { key: 'label', eq: 'base' } } },
+                },
+                removeCurrent: {
+                    id: 'RemoveNode',
+                    config: { node: { attr: { key: 'label', eq: 'current' } } },
+                },
+            },
+            profiles: {
+                base: {
+                    phases: [{ phase: 'main', rules: [{ namedRule: 'removeBase' }] }],
+                },
+                current: {
+                    usesProfiles: ['base'],
+                    phases: [{ phase: 'main', rules: [{ namedRule: 'removeCurrent' }] }],
+                },
+            },
+        });
+        const phases = catalog.resolveProfilePhases('current');
+        expect(phases).toHaveLength(2);
+        expect(phases[0]).toHaveLength(1);
+        expect(phases[1]).toHaveLength(1);
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { attr: { key: 'label', eq: 'base' } } },
+        });
+        expect(phases[1][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { attr: { key: 'label', eq: 'current' } } },
+        });
+    });
+    it('shoud support the instance fromSerialized helper', () => {
+        const loader = new RuntimeCatalogLoader();
+        const catalog = loader.fromSerialized({
+            profiles: {
+                profile: {
+                    phases: [],
+                },
+            },
+        });
+        expect(catalog.resolveProfilePhases('profile')).toEqual([]);
+    });
+    it('shoud surface missing profile definitions during resolution', () => {
+        const internal = RuntimeCatalogLoader;
+        const originalGet = Map.prototype.get;
+        let callCount = 0;
+        const getSpy = jest
+            .spyOn(Map.prototype, 'get')
+            .mockImplementation(function (key) {
+            callCount += 1;
+            if (callCount === 2) {
+                return undefined;
+            }
+            return originalGet.call(this, key);
+        });
+        try {
+            expect(() => internal.resolveProfilesFromSerialized({
+                profile: { phases: [] },
+            })).toThrow("Runtime config profile 'profile' is not defined");
+        }
+        finally {
+            getSpy.mockRestore();
+        }
+    });
+    it('shoud throw when a serialized profile references an unknown parent profile', () => {
+        expect(() => RuntimeCatalogLoader.fromSerialized({
+            profiles: {
+                current: {
+                    usesProfiles: ['base'],
+                    phases: [],
+                },
+            },
+        })).toThrow("Runtime config profile 'current' uses unknown profile 'base'");
+    });
+    it('shoud throw when serialized profiles contain inheritance cycles', () => {
+        expect(() => RuntimeCatalogLoader.fromSerialized({
+            profiles: {
+                one: {
+                    usesProfiles: ['two'],
+                    phases: [],
+                },
+                two: {
+                    usesProfiles: ['one'],
+                    phases: [],
+                },
+            },
+        })).toThrow('Runtime config profile inheritance cycle detected: one -> two -> one');
+    });
+});
+describe('RuntimeCatalogLoader.load', () => {
+    it('shoud merge provider and serialized catalogs with config precedence', () => {
+        const providerCatalog = new RuntimeCatalog({
+            namedRules: new NamedRuleRegistry({
+                shared: new RemoveNode({
+                    node: { attr: { key: 'label', eq: 'provider' } },
+                }),
+            }),
+            namedRuleSets: new NamedRuleSetRegistry({
+                wrapper: {
+                    rules: [{ namedRule: 'shared' }],
+                },
+            }),
+            profiles: new ProfileRegistry({
+                profile: new Profile('profile', {
+                    phases: [{ phase: 'main', rules: [{ namedRuleSet: 'wrapper' }] }],
+                }),
+            }),
+        });
+        const catalog = RuntimeCatalogLoader.load({
+            providers: [providerCatalog],
+            config: {
+                namedRules: {
+                    shared: {
+                        id: 'RemoveNode',
+                        config: { node: { attr: { key: 'label', eq: 'config' } } },
+                    },
+                },
+            },
+        });
+        const phases = catalog.resolveProfilePhases('profile');
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { attr: { key: 'label', eq: 'config' } } },
+        });
+    });
+    it('shoud resolve profile inheritance from provider profiles', () => {
+        const providerCatalog = new RuntimeCatalog({
+            namedRules: new NamedRuleRegistry({
+                removeBase: new RemoveNode({
+                    node: { attr: { key: 'label', eq: 'base' } },
+                }),
+            }),
+            profiles: new ProfileRegistry({
+                base: new Profile('base', {
+                    phases: [{ phase: 'main', rules: [{ namedRule: 'removeBase' }] }],
+                }),
+            }),
+        });
+        const catalog = RuntimeCatalogLoader.load({
+            providers: [providerCatalog],
+            config: {
+                namedRules: {
+                    removeCurrent: {
+                        id: 'RemoveNode',
+                        config: { node: { attr: { key: 'label', eq: 'current' } } },
+                    },
+                },
+                profiles: {
+                    current: {
+                        usesProfiles: ['base'],
+                        phases: [
+                            { phase: 'main', rules: [{ namedRule: 'removeCurrent' }] },
+                        ],
+                    },
+                },
+            },
+        });
+        const phases = catalog.resolveProfilePhases('current');
+        expect(phases).toHaveLength(2);
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { attr: { key: 'label', eq: 'base' } } },
+        });
+        expect(phases[1][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { attr: { key: 'label', eq: 'current' } } },
+        });
+    });
+    it('shoud return the provider catalog when config is missing', () => {
+        const providerCatalog = new RuntimeCatalog({
+            namedRules: new NamedRuleRegistry({
+                shared: new RemoveNode({
+                    node: { attr: { key: 'label', eq: 'provider' } },
+                }),
+            }),
+            namedRuleSets: new NamedRuleSetRegistry({
+                wrapper: {
+                    rules: [{ namedRule: 'shared' }],
+                },
+            }),
+            profiles: new ProfileRegistry({
+                profile: new Profile('profile', {
+                    phases: [{ phase: 'main', rules: [{ namedRuleSet: 'wrapper' }] }],
+                }),
+            }),
+        });
+        const catalog = RuntimeCatalogLoader.load({
+            providers: [providerCatalog],
+        });
+        const phases = catalog.resolveProfilePhases('profile');
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { attr: { key: 'label', eq: 'provider' } } },
+        });
+    });
+    it('shoud load serialized config when no providers are supplied', () => {
+        const catalog = RuntimeCatalogLoader.load({
+            config: {
+                profiles: {
+                    profile: {
+                        phases: [],
+                    },
+                },
+            },
+        });
+        expect(catalog.resolveProfilePhases('profile')).toEqual([]);
+    });
+    it('shoud load an empty catalog when no input is provided', () => {
+        const catalog = RuntimeCatalogLoader.load();
+        expect(catalog).toBeInstanceOf(RuntimeCatalog);
+    });
+    it('shoud support the instance loader API', () => {
+        const loader = new RuntimeCatalogLoader({
+            config: {
+                namedRules: {
+                    removeAlways: {
+                        id: 'RemoveNode',
+                        config: { node: { any: true } },
+                    },
+                },
+                profiles: {
+                    profile: {
+                        phases: [{ phase: 'main', rules: [{ namedRule: 'removeAlways' }] }],
+                    },
+                },
+            },
+        });
+        const catalog = loader.load();
+        const phases = catalog.resolveProfilePhases('profile');
+        expect(phases).toHaveLength(1);
+        expect(phases[0]).toHaveLength(1);
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { any: true } },
+        });
+    });
+});
+describe('RuntimeCatalogLoader.resolveProfilesFromSerialized (external profiles)', () => {
+    it('shoud resolve external profiles referenced by name', () => {
+        const providerCatalog = new RuntimeCatalog({
+            namedRules: new NamedRuleRegistry({
+                removeBase: new RemoveNode({
+                    node: { attr: { key: 'label', eq: 'base' } },
+                }),
+            }),
+            profiles: new ProfileRegistry({
+                base: new Profile('base', {
+                    phases: [{ phase: 'main', rules: [{ namedRule: 'removeBase' }] }],
+                }),
+            }),
+        });
+        const catalog = RuntimeCatalogLoader.load({
+            providers: [providerCatalog],
+            config: {
+                profiles: {
+                    current: {
+                        usesProfiles: ['base'],
+                        phases: [],
+                    },
+                },
+            },
+        });
+        const phases = catalog.resolveProfilePhases('current');
+        expect(phases).toHaveLength(1);
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { attr: { key: 'label', eq: 'base' } } },
+        });
+    });
+    it('shoud reuse cached external profiles across multiple definitions', () => {
+        const providerCatalog = new RuntimeCatalog({
+            namedRules: new NamedRuleRegistry({
+                removeBase: new RemoveNode({
+                    node: { attr: { key: 'label', eq: 'base' } },
+                }),
+            }),
+            profiles: new ProfileRegistry({
+                base: new Profile('base', {
+                    phases: [{ phase: 'main', rules: [{ namedRule: 'removeBase' }] }],
+                }),
+            }),
+        });
+        const catalog = RuntimeCatalogLoader.load({
+            providers: [providerCatalog],
+            config: {
+                profiles: {
+                    currentA: {
+                        usesProfiles: ['base'],
+                        phases: [],
+                    },
+                    currentB: {
+                        usesProfiles: ['base'],
+                        phases: [],
+                    },
+                },
+            },
+        });
+        expect(catalog.resolveProfilePhases('currentA')).toHaveLength(1);
+        expect(catalog.resolveProfilePhases('currentB')).toHaveLength(1);
+    });
+    it('shoud resolve external profiles via registry resolve', () => {
+        const externalProfiles = new ProfileRegistry({
+            base: new Profile('base', {
+                phases: [],
+            }),
+        });
+        const resolveSpy = jest.spyOn(externalProfiles, 'resolve');
+        const catalog = RuntimeCatalogLoader.fromSerialized({
+            profiles: {
+                current: {
+                    usesProfiles: ['base'],
+                    phases: [],
+                },
+            },
+        }, undefined, externalProfiles);
+        catalog.resolveProfilePhases('current');
+        expect(resolveSpy).toHaveBeenCalledWith('base');
+    });
+    it('shoud serialize external profiles when resolving', () => {
+        const externalProfiles = new ProfileRegistry({
+            base: new Profile('base', {
+                phases: [],
+            }),
+        });
+        const resolveSpy = jest.spyOn(externalProfiles, 'resolve');
+        const serializeSpy = jest.spyOn(Profile.prototype, 'serialize');
+        const catalog = RuntimeCatalogLoader.fromSerialized({
+            profiles: {
+                current: {
+                    usesProfiles: ['base'],
+                    phases: [],
+                },
+            },
+        }, undefined, externalProfiles);
+        catalog.resolveProfilePhases('current');
+        expect(resolveSpy).toHaveBeenCalledWith('base');
+        expect(serializeSpy).toHaveBeenCalled();
+        resolveSpy.mockRestore();
+        serializeSpy.mockRestore();
+    });
+});
+describe('RuntimeCatalogLoader.resolveProfilesFromSerialized (external profile instances)', () => {
+    it('shoud use resolved external profile definitions', () => {
+        const externalProfiles = new ProfileRegistry({
+            base: new Profile('base', {
+                phases: [
+                    {
+                        phase: 'main',
+                        rules: [
+                            new RemoveNode({
+                                node: { any: true },
+                            }),
+                        ],
+                    },
+                ],
+            }),
+        });
+        const resolveSpy = jest.spyOn(externalProfiles, 'resolve');
+        const catalog = RuntimeCatalogLoader.fromSerialized({
+            profiles: {
+                current: {
+                    usesProfiles: ['base'],
+                    phases: [],
+                },
+            },
+        }, undefined, externalProfiles);
+        const phases = catalog.resolveProfilePhases('current');
+        expect(resolveSpy).toHaveBeenCalledWith('base');
+        expect(phases).toHaveLength(1);
+        expect(phases[0][0].serialize()).toEqual({
+            id: 'RemoveNode',
+            config: { node: { any: true } },
+        });
+    });
+});
+describe('RuntimeCatalogLoader.resolveProfilesFromSerialized (external profile branch)', () => {
+    it('shoud hit the externalProfile branch when resolve returns a profile', () => {
+        const externalProfile = new Profile('base', {
+            phases: [],
+        });
+        const externalProfiles = {
+            names: () => ['base'],
+            resolve: jest.fn(() => externalProfile),
+        };
+        const internal = RuntimeCatalogLoader;
+        const registry = internal.resolveProfilesFromSerialized({
+            current: {
+                usesProfiles: ['base'],
+                phases: [],
+            },
+        }, undefined, externalProfiles);
+        registry.resolve('current');
+        expect(externalProfiles.resolve).toHaveBeenCalledWith('base');
+    });
+    it('shoud throw when external profile name exists but resolve returns undefined', () => {
+        const externalProfiles = {
+            names: () => ['base'],
+            resolve: jest.fn(() => undefined),
+        };
+        const internal = RuntimeCatalogLoader;
+        expect(() => internal.resolveProfilesFromSerialized({
+            current: {
+                usesProfiles: ['base'],
+                phases: [],
+            },
+        }, undefined, externalProfiles)).toThrow(`Runtime config profile 'current' uses unknown profile 'base'`);
+    });
+});

package/dist/esm/Runtime/RuntimeConfigLoader.d.ts

@@ -0,0 +1,33 @@
+import { RuntimeCatalog } from './RuntimeCatalog.js';
+import { RuntimeCatalogBuilder } from './RuntimeCatalogBuilder.js';
+import { SerializedRuntimeConfig } from './RuntimeCatalogLoader.js';
+import { RuntimeConfigParserRegistry } from './RuntimeConfigParserRegistry.js';
+import { RuntimeConfigSource } from './RuntimeConfigSource.js';
+import { RuntimeConfigValidator } from './RuntimeConfigValidator.js';
+import { RuntimeProvider } from './RuntimeProvider.js';
+import { RuntimeProviderLoader } from './RuntimeProviderLoader.js';
+export type RuntimeConfigLoadInput<TOptions extends Record<string, unknown> = Record<string, unknown>> = {
+    source: RuntimeConfigSource;
+};
+export type RuntimeConfigLoadResult<TOptions extends Record<string, unknown> = Record<string, unknown>> = {
+    catalog: RuntimeCatalog;
+    config: SerializedRuntimeConfig<TOptions>;
+};
+export type RuntimeConfigLoaderDependencies<TOptions extends Record<string, unknown> = Record<string, unknown>> = {
+    parserRegistry?: RuntimeConfigParserRegistry;
+    validator?: RuntimeConfigValidator<TOptions>;
+    catalogBuilder?: RuntimeCatalogBuilder<TOptions>;
+    providerLoader?: RuntimeProviderLoader;
+    baseProviders?: RuntimeProvider[];
+};
+export declare class RuntimeConfigLoader<TOptions extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly parserRegistry;
+    private readonly validator;
+    private readonly catalogBuilder;
+    private readonly providerLoader;
+    private readonly baseProviders;
+    constructor(dependencies?: RuntimeConfigLoaderDependencies<TOptions>);
+    load(input: RuntimeConfigLoadInput<TOptions>): Promise<RuntimeConfigLoadResult<TOptions>>;
+    private loadProviders;
+    private mergeSupportedAdapterOperationsRegistry;
+}

package/dist/esm/Runtime/RuntimeConfigLoader.js

@@ -0,0 +1,89 @@
+import { RuntimeCatalogFromConfigBuilder } from './RuntimeCatalogBuilder/RuntimeCatalogFromConfigBuilder.js';
+import { RuntimeConfigParserRegistry } from './RuntimeConfigParserRegistry.js';
+import { inferRuntimeConfigFormatFromReference, } from './RuntimeConfigSource.js';
+import { ZodRuntimeConfigValidator } from './RuntimeConfigValidator/ZodRuntimeConfigValidator.js';
+import { ModuleRuntimeProviderLoader } from './RuntimeProviderLoader/ModuleRuntimeProviderLoader.js';
+export class RuntimeConfigLoader {
+    parserRegistry;
+    validator;
+    catalogBuilder;
+    providerLoader;
+    baseProviders;
+    constructor(dependencies = {}) {
+        this.parserRegistry =
+            dependencies.parserRegistry ?? RuntimeConfigParserRegistry.defaults();
+        this.validator = dependencies.validator ?? new ZodRuntimeConfigValidator();
+        this.catalogBuilder =
+            dependencies.catalogBuilder ??
+                new RuntimeCatalogFromConfigBuilder();
+        this.providerLoader =
+            dependencies.providerLoader ?? new ModuleRuntimeProviderLoader();
+        this.baseProviders = Object.freeze([...(dependencies.baseProviders ?? [])]);
+    }
+    async load(input) {
+        const document = await input.source.read();
+        const format = document.format ??
+            inferRuntimeConfigFormatFromReference(document.reference);
+        if (!format) {
+            const from = document.reference ? ` from '${document.reference}'` : '';
+            throw new Error(`Unable to determine runtime config format${from}`);
+        }
+        let parsed;
+        try {
+            parsed = this.parserRegistry.resolve(format).parse(document.content);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to parse runtime config as '${format}': ${message}`);
+        }
+        let config;
+        try {
+            config = this.validator.validate(parsed);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Runtime config validation failed: ${message}`);
+        }
+        const loadedProviders = await this.loadProviders(config.providers ?? [], document.reference);
+        const providers = [...this.baseProviders, ...loadedProviders];
+        const supportedAdapterOperationsRegistry = this.mergeSupportedAdapterOperationsRegistry([
+            ...providers.map((provider) => provider.supportedAdapterOperationsRegistry),
+        ]);
+        const catalog = this.catalogBuilder.build({
+            providers,
+            config,
+            supportedAdapterOperationsRegistry,
+        });
+        return { catalog, config };
+    }
+    async loadProviders(providerReferences, sourceReference) {
+        const uniqueSpecifiers = [...new Set(providerReferences)];
+        const loadedProviders = [];
+        for (const specifier of uniqueSpecifiers) {
+            try {
+                loadedProviders.push(await this.providerLoader.load({
+                    specifier,
+                    sourceReference,
+                }));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to load runtime provider '${specifier}': ${message}`);
+            }
+        }
+        return loadedProviders;
+    }
+    mergeSupportedAdapterOperationsRegistry(registries) {
+        const merged = registries.reduce((acc, registry) => {
+            if (!registry) {
+                return acc;
+            }
+            return {
+                // biome-ignore lint/performance/noAccumulatingSpread: <explanation>
+                ...acc,
+                ...registry,
+            };
+        }, {});
+        return Object.keys(merged).length > 0 ? merged : undefined;
+    }
+}

package/dist/esm/Runtime/RuntimeConfigLoader.test.d.ts

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