@quadnix/octo 0.0.30 → 0.2.0

package/dist/functions/container/test-container.d.ts

@@ -12,40 +12,46 @@ type TestContainerSubjects = {
 };
 type TestContainerOptions = {
     factoryTimeoutInMs?: number;
+    force?: boolean;
 };
 /**
- * The TestContainer class is an isolated {@link Container} for tests.
+ * An isolated {@link Container} for tests.
+ *
+ * The Container is a process-wide singleton, which makes it awkward to mock. TestContainer solves
+ * that: create one in `beforeEach()` and it takes over the Container for that test, letting you
+ * replace any factory with a stub. `reset()` in `afterEach()` puts it back.
  *
  * :::info Info
- * A test framework like Jest, supports parallel test executions in different cores of the machine.
- * Each test is a single test file, whose `it()` blocks are executed serially.
+ * A test framework like Jest runs test *files* in parallel across cores, and the `it()` blocks
+ * within a file serially. So a TestContainer never leaks into a test running in parallel.
  * :::
  *
- * TestContainer is created with testing framework's parallel execution in mind.
- * A TestContainer should be created in the `beforeAll()` block of your test,
- * which modifies the Container for the duration of the test.
- * This TestContainer does not affect other tests in parallel since they are on a separate machine core.
- * Once tests are done executing, the `afterAll()` block cleans up the Container.
+ * @example
+ * ```ts
+ * beforeEach(async () => {
+ *   container = await TestContainer.create({ mocks: [] }, { factoryTimeoutInMs: 500 });
+ * });
+ *
+ * afterEach(async () => {
+ *   await TestContainer.reset();
+ * });
+ * ```
  *
  * @group Functions/Container
  */
 export declare class TestContainer {
     private static originalFactories;
-    private static bootstrap;
     /**
-     * The `TestContainer.create()` method allows you to mock factories.
+     * To take over the Container for one test, replacing the factories you name.
      *
      * @example
      * ```ts
-     * beforeAll(async () => {
-     *   await TestContainer.create({
-     *     mocks: [
-     *       { type: MyClass, value: jest.fn() },
-     *       { metadata: { key: 'value' }, type: AnotherClass, value: new AnotherClass() },
-     *     ],
-     *   }, { factoryTimeoutInMs: 500 });
-     * });
-     *
+     * await TestContainer.create({
+     *   mocks: [
+     *     { type: MyClass, value: jest.fn() },
+     *     { metadata: { key: 'value' }, type: AnotherClass, value: new AnotherClass() },
+     *   ],
+     * }, { factoryTimeoutInMs: 500 });
      * ```
      * @param subjects The subjects being mocked.
      * - `mocks` is an array of objects, to override the default factories.
@@ -54,20 +60,28 @@ export declare class TestContainer {
      *   - Use `value: T` to provide the mocked value.
      * @param options Options to configure TestContainer.
      * - `factoryTimeoutInMs?: number` is to override the default container timeout.
+     * - `force?: boolean` performs a complete container reset.
      */
     static create(subjects: TestContainerSubjects, options?: TestContainerOptions): Promise<Container>;
     /**
-     * The `TestContainer.reset()` method will completely destroy all factories from the Container.
-     * Because the entire Container is destroyed, and not just the mocks,
-     * it must always be called in your `afterAll()` block.
-     *
-     * @example
-     * ```ts
-     * afterAll(async () => {
-     *   await TestContainer.reset();
-     * });
-     * ```
+     * To destroy every factory in the Container. Because it destroys the whole Container and not only
+     * the mocks, it must always be called in your teardown block - otherwise the next test starts
+     * against a Container this test left behind.
      */
     static reset(): Promise<void>;
+    /**
+     * Bootstrap the Container with the necessary factories internal to Octo.
+     * Between test runs, when the container is reset, many of Octo's internal classes must be reset as well.
+     * Since these classes are not exposed outside of Octo, we must bootstrap them.
+     *
+     * Some factories defined in Octo using `@Factory` must be placed here,
+     * the exact criteria being any factory that needs to reset its state.
+     *
+     * Exceptions:
+     * - {@link ModelSerializationService}: We do not want to loose class mapping already instantiated via decorators.
+     * - {@link ResourceSerializationService}: We do not want to loose class mapping already instantiated via decorators.
+     * - {@link TransactionService}: We do not want to loose action mapping already instantiated via decorators.
+     */
+    private static bootstrap;
 }
 export {};

package/dist/functions/container/test-container.js

@@ -1,51 +1,50 @@
 import { ModuleContainer } from '../../modules/module.container.js';
 import { OverlayDataRepository } from '../../overlays/overlay-data.repository.js';
 import { ResourceDataRepository, } from '../../resources/resource-data.repository.js';
-import { CaptureService } from '../../services/capture/capture.service.js';
+import { EventService } from '../../services/event/event.service.js';
 import { InputService } from '../../services/input/input.service.js';
+import { ModelSerializationService } from '../../services/serialization/model/model-serialization.service.js';
+import { ResourceSerializationService } from '../../services/serialization/resource/resource-serialization.service.js';
+import { TerraformService } from '../../services/terraform/terraform.service.js';
+import { TransactionService } from '../../services/transaction/transaction.service.js';
 import { Container } from './container.js';
 /**
- * The TestContainer class is an isolated {@link Container} for tests.
+ * An isolated {@link Container} for tests.
+ *
+ * The Container is a process-wide singleton, which makes it awkward to mock. TestContainer solves
+ * that: create one in `beforeEach()` and it takes over the Container for that test, letting you
+ * replace any factory with a stub. `reset()` in `afterEach()` puts it back.
  *
  * :::info Info
- * A test framework like Jest, supports parallel test executions in different cores of the machine.
- * Each test is a single test file, whose `it()` blocks are executed serially.
+ * A test framework like Jest runs test *files* in parallel across cores, and the `it()` blocks
+ * within a file serially. So a TestContainer never leaks into a test running in parallel.
  * :::
  *
- * TestContainer is created with testing framework's parallel execution in mind.
- * A TestContainer should be created in the `beforeAll()` block of your test,
- * which modifies the Container for the duration of the test.
- * This TestContainer does not affect other tests in parallel since they are on a separate machine core.
- * Once tests are done executing, the `afterAll()` block cleans up the Container.
+ * @example
+ * ```ts
+ * beforeEach(async () => {
+ *   container = await TestContainer.create({ mocks: [] }, { factoryTimeoutInMs: 500 });
+ * });
+ *
+ * afterEach(async () => {
+ *   await TestContainer.reset();
+ * });
+ * ```
  *
  * @group Functions/Container
  */
 export class TestContainer {
-    static async bootstrap(container) {
-        await container.get(OverlayDataRepository, {
-            args: [true, []],
-        });
-        await container.get(ResourceDataRepository, {
-            args: [true, [], [], []],
-        });
-        await container.get(CaptureService, { args: [true] });
-        await container.get(InputService, { args: [true] });
-        await container.get(ModuleContainer, { args: [true] });
-    }
     /**
-     * The `TestContainer.create()` method allows you to mock factories.
+     * To take over the Container for one test, replacing the factories you name.
      *
      * @example
      * ```ts
-     * beforeAll(async () => {
-     *   await TestContainer.create({
-     *     mocks: [
-     *       { type: MyClass, value: jest.fn() },
-     *       { metadata: { key: 'value' }, type: AnotherClass, value: new AnotherClass() },
-     *     ],
-     *   }, { factoryTimeoutInMs: 500 });
-     * });
-     *
+     * await TestContainer.create({
+     *   mocks: [
+     *     { type: MyClass, value: jest.fn() },
+     *     { metadata: { key: 'value' }, type: AnotherClass, value: new AnotherClass() },
+     *   ],
+     * }, { factoryTimeoutInMs: 500 });
      * ```
      * @param subjects The subjects being mocked.
      * - `mocks` is an array of objects, to override the default factories.
@@ -54,6 +53,7 @@ export class TestContainer {
      *   - Use `value: T` to provide the mocked value.
      * @param options Options to configure TestContainer.
      * - `factoryTimeoutInMs?: number` is to override the default container timeout.
+     * - `force?: boolean` performs a complete container reset.
      */
     static async create(subjects, options) {
         if (!TestContainer.originalFactories) {
@@ -64,31 +64,59 @@ export class TestContainer {
         container.setFactories(this.originalFactories);
         // Reset state of eligible factories.
         // A factory is eligible if it has an internal structure and should be reset on every test.
-        await this.bootstrap(container);
+        await this.bootstrap(container, options?.force ?? false);
         if (options?.factoryTimeoutInMs) {
             container.setFactoryTimeout(options.factoryTimeoutInMs);
         }
         // Override new container with mock factories as instructed.
         for (const mock of subjects.mocks || []) {
-            container.unRegisterFactory(mock.type, { metadata: mock.metadata });
-            container.registerValue(mock.type, mock.value, { metadata: mock.metadata });
+            container.replaceValue(mock.type, mock.value, { metadata: mock.metadata });
         }
         return container;
     }
     /**
-     * The `TestContainer.reset()` method will completely destroy all factories from the Container.
-     * Because the entire Container is destroyed, and not just the mocks,
-     * it must always be called in your `afterAll()` block.
-     *
-     * @example
-     * ```ts
-     * afterAll(async () => {
-     *   await TestContainer.reset();
-     * });
-     * ```
+     * To destroy every factory in the Container. Because it destroys the whole Container and not only
+     * the mocks, it must always be called in your teardown block - otherwise the next test starts
+     * against a Container this test left behind.
      */
     static async reset() {
         Container.getInstance().reset();
     }
+    /**
+     * Bootstrap the Container with the necessary factories internal to Octo.
+     * Between test runs, when the container is reset, many of Octo's internal classes must be reset as well.
+     * Since these classes are not exposed outside of Octo, we must bootstrap them.
+     *
+     * Some factories defined in Octo using `@Factory` must be placed here,
+     * the exact criteria being any factory that needs to reset its state.
+     *
+     * Exceptions:
+     * - {@link ModelSerializationService}: We do not want to loose class mapping already instantiated via decorators.
+     * - {@link ResourceSerializationService}: We do not want to loose class mapping already instantiated via decorators.
+     * - {@link TransactionService}: We do not want to loose action mapping already instantiated via decorators.
+     */
+    static async bootstrap(container, force = false) {
+        const overlayDataRepository = await container.get(OverlayDataRepository, { args: [true, []] });
+        const resourceDataRepository = await container.get(ResourceDataRepository, { args: [true, [], [], []] });
+        const inputService = await container.get(InputService, { args: [true] });
+        const moduleContainer = await container.get(ModuleContainer, {
+            args: [true],
+        });
+        const terraformService = await container.get(TerraformService, {
+            args: [{}, true],
+        });
+        if (force) {
+            const eventService = await container.get(EventService);
+            const modelSerializationService = new ModelSerializationService(inputService, moduleContainer);
+            container.unRegisterFactory(ModelSerializationService);
+            container.registerValue(ModelSerializationService, modelSerializationService);
+            const resourceSerializationService = new ResourceSerializationService(resourceDataRepository, inputService);
+            container.unRegisterFactory(ResourceSerializationService);
+            container.registerValue(ResourceSerializationService, resourceSerializationService);
+            const transactionService = new TransactionService(eventService, inputService, moduleContainer, overlayDataRepository, resourceDataRepository, resourceSerializationService, terraformService);
+            container.unRegisterFactory(TransactionService);
+            container.registerValue(TransactionService, transactionService);
+        }
+    }
 }
 //# sourceMappingURL=test-container.js.map

package/dist/functions/container/test-container.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-container.js","sourceRoot":"","sources":["../../../src/functions/container/test-container.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAA+B,MAAM,mCAAmC,CAAC;AACjG,OAAO,EAAE,qBAAqB,EAAqC,MAAM,2CAA2C,CAAC;AACrH,OAAO,EACL,sBAAsB,GAEvB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,cAAc,EAA8B,MAAM,2CAA2C,CAAC;AACvG,OAAO,EAAE,YAAY,EAA4B,MAAM,uCAAuC,CAAC;AAC/F,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAa3C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAa;IAGhB,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,SAAoB;QACjD,MAAM,SAAS,CAAC,GAAG,CAA6D,qBAAqB,EAAE;YACrG,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;SACjB,CAAC,CAAC;QAEH,MAAM,SAAS,CAAC,GAAG,CAA+D,sBAAsB,EAAE;YACxG,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;SACzB,CAAC,CAAC;QAEH,MAAM,SAAS,CAAC,GAAG,CAA+C,cAAc,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEpG,MAAM,SAAS,CAAC,GAAG,CAA2C,YAAY,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAE9F,MAAM,SAAS,CAAC,GAAG,CAAiD,eAAe,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzG,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAA+B,EAAE,OAA8B;QACjF,IAAI,CAAC,aAAa,CAAC,iBAAiB,EAAE,CAAC;YACrC,aAAa,CAAC,iBAAiB,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,aAAa,EAAE,CAAC;QAC5E,CAAC;QACD,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;QAE1C,0CAA0C;QAC1C,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC/C,qCAAqC;QACrC,2FAA2F;QAC3F,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAEhC,IAAI,OAAO,EAAE,kBAAkB,EAAE,CAAC;YAChC,SAAS,CAAC,iBAAiB,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC1D,CAAC;QAED,4DAA4D;QAC5D,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YACxC,SAAS,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YACpE,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC9E,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK;QAChB,SAAS,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC;IAClC,CAAC;CACF"}
+{"version":3,"file":"test-container.js","sourceRoot":"","sources":["../../../src/functions/container/test-container.ts"],"names":[],"mappings":"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"}

package/dist/functions/dependency/dependency.d.ts

@@ -1,13 +1,8 @@
 import type { UnknownNode } from '../../app.type.js';
 import type { DiffAction } from '../diff/diff.js';
-declare class DependencyBehavior {
-    forAction: DiffAction;
-    onAction: DiffAction;
-    onField: string;
-    toField: string;
-    constructor(onField: string, onAction: DiffAction, toField: string, forAction: DiffAction);
-}
 /**
+ * How two nodes are related. A parent exists before its child, and outlives it.
+ *
  * @group Functions/Dependency
  */
 export declare enum DependencyRelationship {
@@ -15,47 +10,113 @@ export declare enum DependencyRelationship {
     PARENT = "parent"
 }
 /**
+ * The serialized form of a {@link Dependency}, as it is written to state. A behavior says that the
+ * `forAction` diff of `to`'s `toField` waits for the `onAction` diff of `from`'s `onField`.
+ *
  * @group Functions/Dependency
  */
 export interface IDependency {
     behaviors: {
-        forAction: DependencyBehavior['forAction'];
-        onAction: DependencyBehavior['onAction'];
-        onField: DependencyBehavior['onField'];
-        toField: DependencyBehavior['toField'];
+        forAction: `${DiffAction}`;
+        onAction: `${DiffAction}`;
+        onField: string;
+        toField: string;
     }[];
     from: string;
     relationship?: {
-        onField: DependencyBehavior['onField'];
-        toField: DependencyBehavior['toField'];
-        type: DependencyRelationship;
+        onField: string;
+        toField: string;
+        type: `${DependencyRelationship}`;
     };
     to: string;
 }
 /**
+ * The edge between two nodes in Octo's graph.
+ *
+ * A dependency is directed, and carries two things: an optional parent/child relationship, and a set
+ * of *behaviors*. A behavior states an ordering rule - "when this field of `from` is added, the
+ * matching action on `to` must have run first" - and it is those rules that let Octo order a
+ * transaction correctly instead of guessing.
+ *
+ * Models create dependencies through `addChild()` and `addRelationship()`; you rarely construct one.
+ *
  * @group Functions/Dependency
+ *
+ * @see Definition of [Dependencies](/docs/fundamentals/dependencies).
  */
 export declare class Dependency {
-    private readonly behaviors;
+    /**
+     * The node this dependency points from.
+     */
     readonly from: UnknownNode;
-    private relationship;
+    /**
+     * The node this dependency points to.
+     */
     readonly to: UnknownNode;
+    private readonly behaviors;
+    private relationship;
+    /**
+     * @param from The node this dependency points from.
+     * @param to The node this dependency points to.
+     */
     constructor(from: UnknownNode, to: UnknownNode);
-    private getBehaviorIndex;
+    /**
+     * @internal
+     */
+    static unSynth(from: UnknownNode, to: UnknownNode, dependency: IDependency): Dependency;
+    /**
+     * To declare an ordering rule: when `onAction` happens to `onField` of `from`, then `forAction`
+     * on `toField` of `to` must have been applied first. Adding the same behavior twice is a no-op.
+     */
     addBehavior(onField: string, onAction: DiffAction, toField: string, forAction: DiffAction): void;
+    /**
+     * To mark `to` as the child of `from`.
+     *
+     * @throws {@link DependencyError} If this dependency already has a relationship.
+     */
     addChildRelationship(onField: string, toField: string): void;
+    /**
+     * To mark `to` as the parent of `from`.
+     *
+     * @throws {@link DependencyError} If this dependency already has a relationship.
+     */
     addParentRelationship(onField: string, toField: string): void;
-    hasMatchingBehavior(onField?: string, onAction?: DiffAction, toField?: string, forAction?: DiffAction): boolean;
-    isChildRelationship(): boolean;
-    isEqual(dependency: Dependency): boolean;
-    isParentRelationship(): boolean;
+    /**
+     * The relationship between the two nodes, if one was declared.
+     */
     getRelationship(): {
         onField: string;
         toField: string;
         type: DependencyRelationship;
     } | undefined;
+    /**
+     * Whether any behavior matches every argument given. Arguments left out match anything.
+     */
+    hasMatchingBehavior(onField?: string, onAction?: DiffAction, toField?: string, forAction?: DiffAction): boolean;
+    /**
+     * Whether `to` is a child of `from`.
+     */
+    isChildRelationship(): boolean;
+    /**
+     * Whether both dependencies connect the same two nodes, in the same direction.
+     */
+    isEqual(dependency: Dependency): boolean;
+    /**
+     * Whether `to` is a parent of `from`.
+     */
+    isParentRelationship(): boolean;
+    /**
+     * To drop an ordering rule.
+     *
+     * @throws {@link DependencyError} If no such behavior exists.
+     */
     removeBehavior(onField: string, onAction: DiffAction, toField: string, forAction: DiffAction): void;
+    /**
+     * @internal
+     */
     synth(): IDependency;
-    static unSynth(from: UnknownNode, to: UnknownNode, dependency: IDependency): Dependency;
+    /**
+     * The position of a matching behavior, or `-1`.
+     */
+    private getBehaviorIndex;
 }
-export {};

package/dist/functions/dependency/dependency.js

@@ -1,5 +1,11 @@
 import { DependencyError } from '../../errors/index.js';
+/**
+ * @internal
+ */
 class DependencyBehavior {
+    /**
+     * @internal
+     */
     constructor(onField, onAction, toField, forAction) {
         this.onField = onField;
         this.onAction = onAction;
@@ -8,6 +14,8 @@ class DependencyBehavior {
     }
 }
 /**
+ * How two nodes are related. A parent exists before its child, and outlives it.
+ *
  * @group Functions/Dependency
  */
 export var DependencyRelationship;
@@ -16,34 +24,86 @@ export var DependencyRelationship;
     DependencyRelationship["PARENT"] = "parent";
 })(DependencyRelationship || (DependencyRelationship = {}));
 /**
+ * The edge between two nodes in Octo's graph.
+ *
+ * A dependency is directed, and carries two things: an optional parent/child relationship, and a set
+ * of *behaviors*. A behavior states an ordering rule - "when this field of `from` is added, the
+ * matching action on `to` must have run first" - and it is those rules that let Octo order a
+ * transaction correctly instead of guessing.
+ *
+ * Models create dependencies through `addChild()` and `addRelationship()`; you rarely construct one.
+ *
  * @group Functions/Dependency
+ *
+ * @see Definition of [Dependencies](/docs/fundamentals/dependencies).
  */
 export class Dependency {
+    /**
+     * @param from The node this dependency points from.
+     * @param to The node this dependency points to.
+     */
     constructor(from, to) {
         this.behaviors = [];
         this.from = from;
         this.to = to;
     }
-    getBehaviorIndex(onField, onAction, toField, forAction) {
-        return this.behaviors.findIndex((b) => b.onField === onField && b.onAction === onAction && b.toField === toField && b.forAction === forAction);
+    /**
+     * @internal
+     */
+    static unSynth(from, to, dependency) {
+        const newDependency = new Dependency(from, to);
+        // Read the actions and the relationship back as the values they were written from.
+        dependency.behaviors.forEach((b) => {
+            newDependency.addBehavior(b.onField, b.onAction, b.toField, b.forAction);
+        });
+        if (dependency.relationship) {
+            newDependency.relationship = {
+                ...dependency.relationship,
+                type: dependency.relationship.type,
+            };
+        }
+        return newDependency;
     }
+    /**
+     * To declare an ordering rule: when `onAction` happens to `onField` of `from`, then `forAction`
+     * on `toField` of `to` must have been applied first. Adding the same behavior twice is a no-op.
+     */
     addBehavior(onField, onAction, toField, forAction) {
         if (this.getBehaviorIndex(onField, onAction, toField, forAction) === -1) {
             this.behaviors.push(new DependencyBehavior(onField, onAction, toField, forAction));
         }
     }
+    /**
+     * To mark `to` as the child of `from`.
+     *
+     * @throws {@link DependencyError} If this dependency already has a relationship.
+     */
     addChildRelationship(onField, toField) {
         if (this.relationship) {
             throw new DependencyError('Dependency relationship already exists!', this);
         }
         this.relationship = { onField, toField, type: DependencyRelationship.CHILD };
     }
+    /**
+     * To mark `to` as the parent of `from`.
+     *
+     * @throws {@link DependencyError} If this dependency already has a relationship.
+     */
     addParentRelationship(onField, toField) {
         if (this.relationship) {
             throw new DependencyError('Dependency relationship already exists!', this);
         }
         this.relationship = { onField, toField, type: DependencyRelationship.PARENT };
     }
+    /**
+     * The relationship between the two nodes, if one was declared.
+     */
+    getRelationship() {
+        return this.relationship;
+    }
+    /**
+     * Whether any behavior matches every argument given. Arguments left out match anything.
+     */
     hasMatchingBehavior(onField, onAction, toField, forAction) {
         return this.behaviors.some((b) => {
             const onFieldCondition = onField ? b.onField === onField : true;
@@ -53,18 +113,29 @@ export class Dependency {
             return onFieldCondition && onActionCondition && toFieldCondition && forActionCondition;
         });
     }
+    /**
+     * Whether `to` is a child of `from`.
+     */
     isChildRelationship() {
         return this.relationship && this.relationship.type === DependencyRelationship.CHILD;
     }
+    /**
+     * Whether both dependencies connect the same two nodes, in the same direction.
+     */
     isEqual(dependency) {
         return (this.from.getContext() === dependency.from.getContext() && this.to.getContext() === dependency.to.getContext());
     }
+    /**
+     * Whether `to` is a parent of `from`.
+     */
     isParentRelationship() {
         return this.relationship && this.relationship.type === DependencyRelationship.PARENT;
     }
-    getRelationship() {
-        return this.relationship;
-    }
+    /**
+     * To drop an ordering rule.
+     *
+     * @throws {@link DependencyError} If no such behavior exists.
+     */
     removeBehavior(onField, onAction, toField, forAction) {
         const index = this.getBehaviorIndex(onField, onAction, toField, forAction);
         if (index === -1) {
@@ -72,6 +143,9 @@ export class Dependency {
         }
         this.behaviors.splice(index, 1);
     }
+    /**
+     * @internal
+     */
     synth() {
         const behaviors = [];
         this.behaviors.forEach((b) => {
@@ -95,15 +169,11 @@ export class Dependency {
             to: this.to.getContext(),
         };
     }
-    static unSynth(from, to, dependency) {
-        const newDependency = new Dependency(from, to);
-        dependency.behaviors.forEach((b) => {
-            newDependency.addBehavior(b.onField, b.onAction, b.toField, b.forAction);
-        });
-        if (dependency.relationship) {
-            newDependency.relationship = { ...dependency.relationship };
-        }
-        return newDependency;
+    /**
+     * The position of a matching behavior, or `-1`.
+     */
+    getBehaviorIndex(onField, onAction, toField, forAction) {
+        return this.behaviors.findIndex((b) => b.onField === onField && b.onAction === onAction && b.toField === toField && b.forAction === forAction);
     }
 }
 //# sourceMappingURL=dependency.js.map

package/dist/functions/dependency/dependency.js.map

@@ -1 +1 @@
-{"version":3,"file":"dependency.js","sourceRoot":"","sources":["../../../src/functions/dependency/dependency.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dependency.js","sourceRoot":"","sources":["../../../src/functions/dependency/dependency.ts"],"names":[],"mappings":"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"}

package/dist/functions/diff/aggregate-resource-actions.d.ts

@@ -0,0 +1,19 @@
+import type { DiffMetadata } from './diff-metadata.js';
+import { DiffAction } from './diff.js';
+/**
+ * One octo resource's diffs, collapsed to a single action.
+ */
+export interface AggregatedResourceAction {
+    action: DiffAction.ADD | DiffAction.DELETE | DiffAction.REPLACE | DiffAction.UPDATE;
+    reason?: string;
+    resourceId: string;
+}
+/**
+ * Collapses a resource's field-level diffs into one action per resource, keyed by resource context.
+ *
+ * Precedence: an add/delete of `resourceId` wins; a REPLACE beats an UPDATE; otherwise UPDATE.
+ * `reason` is taken from the winning diff.
+ *
+ * @internal
+ */
+export declare function aggregateResourceActions(diffs: DiffMetadata[]): Map<string, AggregatedResourceAction>;