@quadnix/octo 0.0.29 → 0.1.0

package/dist/functions/container/container.js

@@ -12,11 +12,26 @@ import { DiffUtility } from '../diff/diff.utility.js';
  * @group Functions/Container
  */
 export class Container {
+    /**
+     * @internal
+     */
     constructor() {
-        this.FACTORY_TIMEOUT_IN_MS = 3000;
         this.factories = {};
+        this.FACTORY_TIMEOUT_IN_MS = 3000;
         this.startupUnhandledPromises = [];
     }
+    /**
+     * The Container is a singleton - this is how you reach it.
+     */
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = new Container();
+        }
+        return this.instance;
+    }
+    /**
+     * @internal
+     */
     copyFactories() {
         const newFactoriesCopy = {};
         for (const [type, factoryContainers] of Object.entries(this.factories)) {
@@ -31,8 +46,9 @@ export class Container {
         return newFactoriesCopy;
     }
     /**
-     * `container.get()` allows to get an instance of a class using its factory.
-     * If the factory is not yet registered, it places a blocking promise in the queue to wait for the registration.
+     * To get an instance of a class from its factory.
+     * If the factory is not registered yet, this waits for it, and times out - see
+     * {@link Container.setFactoryTimeout}.
      *
      * @param type The type or name of the class to get.
      * @param options Allows selection of a specific factory to use to get the instance.
@@ -76,12 +92,9 @@ export class Container {
         }
         return factory.create(...args);
     }
-    static getInstance() {
-        if (!this.instance) {
-            this.instance = new Container();
-        }
-        return this.instance;
-    }
+    /**
+     * Whether a factory is registered for the class.
+     */
     has(type, options) {
         const metadata = options?.metadata || {};
         const name = typeof type === 'string' ? type : type.name;
@@ -91,7 +104,8 @@ export class Container {
         return this.factories[name].some((f) => DiffUtility.isObjectDeepEquals(f.metadata, metadata));
     }
     /**
-     * `Container.registerFactory()` allows to register a factory for a class.
+     * To register a factory for a class. Prefer the {@link Factory} decorator; call this directly only
+     * when the factory is built at runtime.
      *
      * @param type The type or name of the class for which the factory is registered.
      * @param factory The factory class being registered.
@@ -118,18 +132,41 @@ export class Container {
         }
         this.factories[name].push({ factory, metadata });
     }
+    /**
+     * @internal
+     */
+    registerStartupUnhandledPromise(promise) {
+        this.startupUnhandledPromises.push(promise);
+    }
+    /**
+     * To register a ready-made instance, instead of a factory that builds one.
+     */
     registerValue(type, value, options) {
         this.registerFactory(type, class {
+            /**
+             * @internal
+             */
             static async create() {
                 return value;
             }
         }, options);
     }
-    registerStartupUnhandledPromise(promise) {
-        this.startupUnhandledPromises.push(promise);
+    /**
+     * To register a ready-made instance over whatever is already registered under the same type and
+     * metadata, rather than refusing as {@link Container.registerValue} does.
+     *
+     * Registering once is the right default - two factories for one type is usually a mistake. This is
+     * for the callers that legitimately register the same thing more than once: a module whose
+     * `onInit` runs on every `compose()`, and a test replacing a factory with a mock.
+     */
+    replaceValue(type, value, options) {
+        if (this.has(type, options)) {
+            this.unRegisterFactory(type, options);
+        }
+        this.registerValue(type, value, options);
     }
     /**
-     * `Container.reset()` clears all registered factories and empties the container. This is mostly used in testing.
+     * To clear every registered factory and empty the container. Mostly used in testing.
      */
     reset() {
         this.FACTORY_TIMEOUT_IN_MS = 3000;
@@ -138,6 +175,9 @@ export class Container {
         }
         this.startupUnhandledPromises.splice(0, this.startupUnhandledPromises.length);
     }
+    /**
+     * @internal
+     */
     setFactories(factories) {
         for (const [type, factoryContainers] of Object.entries(factories)) {
             this.factories[type] = [];
@@ -150,19 +190,21 @@ export class Container {
         }
     }
     /**
-     * The Container, by default, will wait a maximum of 5 seconds for a factory to resolve and provide an instance.
-     * This method allows to change that timeout.
+     * To change how long `get()` waits for a factory to be registered.
      *
+     * @defaultValue `3000`
      * @param timeoutInMs The timeout in milliseconds.
+     *
      */
     setFactoryTimeout(timeoutInMs) {
         this.FACTORY_TIMEOUT_IN_MS = timeoutInMs;
     }
     /**
-     * `Container.unRegisterFactory()` will unregister all factories of a class.
+     * To unregister a class's factories, so that your own can take their place.
      *
-     * @param type The type or name of the class for which all factory is unregistered.
-     * @param options
+     * @param type The type or name of the class whose factories are unregistered.
+     * @param options Pass `metadata` to unregister one specific factory. Without it, all of the
+     * class's factories are unregistered.
      */
     unRegisterFactory(type, options) {
         const name = typeof type === 'string' ? type : type.name;
@@ -176,6 +218,9 @@ export class Container {
             this.factories[name].splice(index, 1);
         }
     }
+    /**
+     * @internal
+     */
     async waitToResolveAllFactories() {
         const promiseToResolveAllFactories = [];
         for (const name of Object.keys(this.factories)) {

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

@@ -1 +1 @@
-{"version":3,"file":"container.js","sourceRoot":"","sources":["../../../src/functions/container/container.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAMtD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IASpB;QARQ,0BAAqB,GAAG,IAAI,CAAC;QAEpB,cAAS,GAAmD,EAAE,CAAC;QAI/D,6BAAwB,GAAuB,EAAE,CAAC;IAE5C,CAAC;IAExB,aAAa;QACX,MAAM,gBAAgB,GAAmD,EAAE,CAAC;QAE5E,KAAK,MAAM,CAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACvE,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC5B,KAAK,MAAM,gBAAgB,IAAI,iBAAiB,EAAE,CAAC;gBACjD,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;oBAC1B,OAAO,EAAE,gBAAgB,CAAC,OAAO;oBACjC,QAAQ,EAAE,EAAE,GAAG,gBAAgB,CAAC,QAAQ,EAAE;iBAC3C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,GAAG,CACP,IAA+B,EAC/B,OAGC;QAED,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,CAAC;QAED,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QAChH,IAAI,gBAAgB,EAAE,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7C,OAAQ,gBAAgB,CAAC,OAAsB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;YAClE,CAAC;iBAAM,CAAC;gBACN,MAAM,OAAO,GAAG,MAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAyB,CAAC;gBAC3E,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QAED,MAAM,mBAAmB,GAAwB;YAC/C,QAAQ;SACc,CAAC;QACzB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAE/C,IAAI,eAAuD,CAAC;QAC5D,IAAI,cAA0C,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1D,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC/B,MAAM,CAAC,IAAI,wBAAwB,CAAC,2CAA2C,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1F,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAC,CAAC;YAC/B,eAAe,GAAG,OAAO,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,mBAAmB,CAAC,OAAO,GAAG,CAAC,OAAO,EAAE,eAAgB,CAAC,CAAC;QAE1D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;QAC9B,IAAI,cAAc,EAAE,CAAC;YACnB,YAAY,CAAC,cAAc,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,SAAS,EAAE,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,GAAG,CACD,IAA+B,EAC/B,OAEC;QAED,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;;OAOG;IACH,eAAe,CACb,IAA+B,EAC/B,OAAmB,EACnB,OAEC;QAED,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,CAAC;QAED,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QAChH,IAAI,gBAAgB,EAAE,OAAO,EAAE,CAAC;YAC9B,kFAAkF;YAClF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7C,MAAM,IAAI,0BAA0B,CAAC,sCAAsC,EAAE,IAAI,CAAC,CAAC;YACrF,CAAC;YAED,gBAAgB,CAAC,QAAQ,GAAG,QAAQ,CAAC;YACrC,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAkC,CAAC;YAC7E,OAAO,CAAC,OAAO,CAAC,CAAC;YACjB,gBAAgB,CAAC,OAAO,GAAG,OAAO,CAAC;YAEnC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,aAAa,CACX,IAA+B,EAC/B,KAAQ,EACR,OAEC;QAED,IAAI,CAAC,eAAe,CAClB,IAAI,EACJ;YACE,MAAM,CAAC,KAAK,CAAC,MAAM;gBACjB,OAAO,KAAK,CAAC;YACf,CAAC;SACF,EACD,OAAO,CACR,CAAC;IACJ,CAAC;IAED,+BAA+B,CAAI,OAAmB;QACpD,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;QAElC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAChF,CAAC;IAED,YAAY,CAAC,SAAyD;QACpE,KAAK,MAAM,CAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC1B,KAAK,MAAM,gBAAgB,IAAI,iBAAiB,EAAE,CAAC;gBACjD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;oBACxB,OAAO,EAAE,gBAAgB,CAAC,OAAO;oBACjC,QAAQ,EAAE,EAAE,GAAG,gBAAgB,CAAC,QAAQ,EAAE;iBAC3C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,WAAmB;QACnC,IAAI,CAAC,qBAAqB,GAAG,WAAW,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAI,IAA+B,EAAE,OAAkD;QACtG,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC3G,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,yBAAyB;QAC7B,MAAM,4BAA4B,GAAgC,EAAE,CAAC;QAErE,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/C,KAAK,MAAM,gBAAgB,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpD,IAAI,gBAAgB,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;oBACzE,4BAA4B,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,4BAA4B,EAAE,GAAG,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACzF,CAAC;CACF"}
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../../../src/functions/container/container.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAMtD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IASpB;;OAEG;IACH;QATiB,cAAS,GAAmD,EAAE,CAAC;QAExE,0BAAqB,GAAG,IAAI,CAAC;QAEpB,6BAAwB,GAAuB,EAAE,CAAC;IAK5C,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,SAAS,EAAE,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,aAAa;QACX,MAAM,gBAAgB,GAAmD,EAAE,CAAC;QAE5E,KAAK,MAAM,CAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACvE,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC5B,KAAK,MAAM,gBAAgB,IAAI,iBAAiB,EAAE,CAAC;gBACjD,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;oBAC1B,OAAO,EAAE,gBAAgB,CAAC,OAAO;oBACjC,QAAQ,EAAE,EAAE,GAAG,gBAAgB,CAAC,QAAQ,EAAE;iBAC3C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,CACP,IAA+B,EAC/B,OAGC;QAED,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,CAAC;QAED,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QAChH,IAAI,gBAAgB,EAAE,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7C,OAAQ,gBAAgB,CAAC,OAAsB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;YAClE,CAAC;iBAAM,CAAC;gBACN,MAAM,OAAO,GAAG,MAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAyB,CAAC;gBAC3E,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QAED,MAAM,mBAAmB,GAAwB;YAC/C,QAAQ;SACc,CAAC;QACzB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAE/C,IAAI,eAAuD,CAAC;QAC5D,IAAI,cAA0C,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1D,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC/B,MAAM,CAAC,IAAI,wBAAwB,CAAC,2CAA2C,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1F,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAC,CAAC;YAC/B,eAAe,GAAG,OAAO,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,mBAAmB,CAAC,OAAO,GAAG,CAAC,OAAO,EAAE,eAAgB,CAAC,CAAC;QAE1D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;QAC9B,IAAI,cAAc,EAAE,CAAC;YACnB,YAAY,CAAC,cAAc,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,GAAG,CACD,IAA+B,EAC/B,OAEC;QAED,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CACb,IAA+B,EAC/B,OAAmB,EACnB,OAEC;QAED,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,CAAC;QAED,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QAChH,IAAI,gBAAgB,EAAE,OAAO,EAAE,CAAC;YAC9B,kFAAkF;YAClF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7C,MAAM,IAAI,0BAA0B,CAAC,sCAAsC,EAAE,IAAI,CAAC,CAAC;YACrF,CAAC;YAED,gBAAgB,CAAC,QAAQ,GAAG,QAAQ,CAAC;YACrC,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAkC,CAAC;YAC7E,OAAO,CAAC,OAAO,CAAC,CAAC;YACjB,gBAAgB,CAAC,OAAO,GAAG,OAAO,CAAC;YAEnC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,+BAA+B,CAAI,OAAmB;QACpD,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,aAAa,CACX,IAA+B,EAC/B,KAAQ,EACR,OAEC;QAED,IAAI,CAAC,eAAe,CAClB,IAAI,EACJ;YACE;;eAEG;YACH,MAAM,CAAC,KAAK,CAAC,MAAM;gBACjB,OAAO,KAAK,CAAC;YACf,CAAC;SACF,EACD,OAAO,CACR,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,YAAY,CACV,IAA+B,EAC/B,KAAQ,EACR,OAEC;QAED,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;QAElC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAChF,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,SAAyD;QACpE,KAAK,MAAM,CAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC1B,KAAK,MAAM,gBAAgB,IAAI,iBAAiB,EAAE,CAAC;gBACjD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;oBACxB,OAAO,EAAE,gBAAgB,CAAC,OAAO;oBACjC,QAAQ,EAAE,EAAE,GAAG,gBAAgB,CAAC,QAAQ,EAAE;iBAC3C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,iBAAiB,CAAC,WAAmB;QACnC,IAAI,CAAC,qBAAqB,GAAG,WAAW,CAAC;IAC3C,CAAC;IAED;;;;;;OAMG;IACH,iBAAiB,CAAI,IAA+B,EAAE,OAAkD;QACtG,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAEzD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC3G,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,yBAAyB;QAC7B,MAAM,4BAA4B,GAAgC,EAAE,CAAC;QAErE,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/C,KAAK,MAAM,gBAAgB,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpD,IAAI,gBAAgB,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;oBACzE,4BAA4B,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,4BAA4B,EAAE,GAAG,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACzF,CAAC;CACF"}

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);
+            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, 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,21 @@
 import type { UnknownNode } from '../../app.type.js';
 import type { DiffAction } from '../diff/diff.js';
+/**
+ * @internal
+ */
 declare class DependencyBehavior {
     forAction: DiffAction;
     onAction: DiffAction;
     onField: string;
     toField: string;
+    /**
+     * @internal
+     */
     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,6 +23,8 @@ export declare enum DependencyRelationship {
     PARENT = "parent"
 }
 /**
+ * The serialized form of a {@link Dependency}, as it is written to state.
+ *
  * @group Functions/Dependency
  */
 export interface IDependency {
@@ -33,29 +43,93 @@ export interface IDependency {
     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 {};