@quadnix/octo 0.0.19 → 0.0.21

package/dist/decorators/module.decorator.d.ts

@@ -3,6 +3,58 @@ import type { Octo } from '../main.js';
 import type { IModelAction } from '../models/model-action.interface.js';
 import { type IModule } from '../modules/module.interface.js';
 import type { IResourceAction } from '../resources/resource-action.interface.js';
+/**
+ * A `@Module` is a class decorator to be placed on top of a class that represents a module.
+ * - A Module class must implement the {@link IModule} interface.
+ * - A Module class constructor is injected with the outputs of the modules it imports.
+ * - The {@link IModule.onInit} method is called to initialize the module,
+ * and is where you will *define* your infrastructure.
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   args: [{ isArg: (app: App) => app instanceof App, name: 'app' }],
+ *   imports: [OtherModule],
+ *   postModelActionHooks: [{ ACTION_NAME: 'SomeAction', collectInput: () => { ... }, handle: () => { ... } }],
+ * })
+ * export class MyModule implements IModule<Region> {
+ *   constructor(app: App) { ... }
+ *
+ *   async onInit(): Promise<Region> { ... }
+ * }
+ * ```
+ * @group Decorators
+ * @param options - Options to the module.
+ * @param options.args - (optional) An array of arg validators to verify the args passed to the module's constructor.
+ * - The `isArg` method receives an argument, and you must do your own type checking and return a boolean.
+ * - The `name` property is the name of the argument.
+ * @param options.imports - (optional) An array of modules to import.
+ * @param options.postCommitHooks - (optional) An array of post-commit hooks.
+ * - The `callback` method will be called after the transaction is committed.
+ * This method receives the same arguments as {@link Octo.commitTransaction}.
+ * @param options.postModelActionHooks - (optional) An array of post-model action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `collectInput` method can be used to enrich the action inputs. It works the same as in {@link IModelAction}.
+ * - The `handle` method will be called after the action is executed.
+ * This method receives the same arguments as {@link IModelAction.handle}.
+ * @param options.postResourceActionHooks - (optional) An array of post-resource action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `handle` method will be called after the action is executed.
+ * This method receives the same arguments as {@link IResourceAction.handle}.
+ * @param options.preCommitHooks - (optional) An array of pre-commit hooks.
+ * - The `callback` method will be called before the transaction is committed.
+ * This method receives the same arguments as {@link Octo.commitTransaction}.
+ * @param options.preModelActionHooks - (optional) An array of pre-model action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `collectInput` method can be used to enrich the action inputs. It works the same as in {@link IModelAction}.
+ * - The `handle` method will be called before the action is executed.
+ * This method receives the same arguments as {@link IModelAction.handle}.
+ * @param options.preResourceActionHooks - (optional) An array of pre-resource action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `handle` method will be called before the action is executed.
+ * @returns The decorated class.
+ * @see Definition of [Modules](/docs/fundamentals/modules).
+ */
 export declare function Module({ args, imports, postCommitHooks, postModelActionHooks, postResourceActionHooks, preCommitHooks, preModelActionHooks, preResourceActionHooks, }: {
     args?: {
         isArg: (arg: unknown) => boolean;

package/dist/decorators/module.decorator.js

@@ -1,8 +1,64 @@
+import { RegistrationErrorEvent } from '../events/error.event.js';
 import { ModuleContainer } from '../modules/module.container.js';
+import { EventService } from '../services/event/event.service.js';
 import { Container } from './container.js';
+/**
+ * A `@Module` is a class decorator to be placed on top of a class that represents a module.
+ * - A Module class must implement the {@link IModule} interface.
+ * - A Module class constructor is injected with the outputs of the modules it imports.
+ * - The {@link IModule.onInit} method is called to initialize the module,
+ * and is where you will *define* your infrastructure.
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   args: [{ isArg: (app: App) => app instanceof App, name: 'app' }],
+ *   imports: [OtherModule],
+ *   postModelActionHooks: [{ ACTION_NAME: 'SomeAction', collectInput: () => { ... }, handle: () => { ... } }],
+ * })
+ * export class MyModule implements IModule<Region> {
+ *   constructor(app: App) { ... }
+ *
+ *   async onInit(): Promise<Region> { ... }
+ * }
+ * ```
+ * @group Decorators
+ * @param options - Options to the module.
+ * @param options.args - (optional) An array of arg validators to verify the args passed to the module's constructor.
+ * - The `isArg` method receives an argument, and you must do your own type checking and return a boolean.
+ * - The `name` property is the name of the argument.
+ * @param options.imports - (optional) An array of modules to import.
+ * @param options.postCommitHooks - (optional) An array of post-commit hooks.
+ * - The `callback` method will be called after the transaction is committed.
+ * This method receives the same arguments as {@link Octo.commitTransaction}.
+ * @param options.postModelActionHooks - (optional) An array of post-model action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `collectInput` method can be used to enrich the action inputs. It works the same as in {@link IModelAction}.
+ * - The `handle` method will be called after the action is executed.
+ * This method receives the same arguments as {@link IModelAction.handle}.
+ * @param options.postResourceActionHooks - (optional) An array of post-resource action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `handle` method will be called after the action is executed.
+ * This method receives the same arguments as {@link IResourceAction.handle}.
+ * @param options.preCommitHooks - (optional) An array of pre-commit hooks.
+ * - The `callback` method will be called before the transaction is committed.
+ * This method receives the same arguments as {@link Octo.commitTransaction}.
+ * @param options.preModelActionHooks - (optional) An array of pre-model action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `collectInput` method can be used to enrich the action inputs. It works the same as in {@link IModelAction}.
+ * - The `handle` method will be called before the action is executed.
+ * This method receives the same arguments as {@link IModelAction.handle}.
+ * @param options.preResourceActionHooks - (optional) An array of pre-resource action hooks.
+ * - The `ACTION_NAME` identifies the action on which this hook is registered.
+ * - The `handle` method will be called before the action is executed.
+ * @returns The decorated class.
+ * @see Definition of [Modules](/docs/fundamentals/modules).
+ */
 export function Module({ args = [], imports = [], postCommitHooks = [], postModelActionHooks = [], postResourceActionHooks = [], preCommitHooks = [], preModelActionHooks = [], preResourceActionHooks = [], }) {
     return function (constructor) {
-        Container.get(ModuleContainer).then((moduleContainer) => {
+        Container.get(ModuleContainer)
+            .then((moduleContainer) => {
+            // Verify classes with @Module implements IModule.
             if (!('onInit' in constructor.prototype)) {
                 throw new Error(`Class "${constructor.name}" does not implement IModule!`);
             }
@@ -16,6 +72,9 @@ export function Module({ args = [], imports = [], postCommitHooks = [], postMode
                 preModelActionHooks,
                 preResourceActionHooks,
             });
+        })
+            .catch((error) => {
+            EventService.getInstance().emit(new RegistrationErrorEvent(error));
         });
     };
 }

package/dist/decorators/module.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"module.decorator.js","sourceRoot":"","sources":["../../src/decorators/module.decorator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,UAAU,MAAM,CAAC,EACrB,IAAI,GAAG,EAAE,EACT,OAAO,GAAG,EAAE,EACZ,eAAe,GAAG,EAAE,EACpB,oBAAoB,GAAG,EAAE,EACzB,uBAAuB,GAAG,EAAE,EAC5B,cAAc,GAAG,EAAE,EACnB,mBAAmB,GAAG,EAAE,EACxB,sBAAsB,GAAG,EAAE,GAwB5B;IACC,OAAO,UAAU,WAA4C;QAC3D,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE;YAEtD,IAAI,CAAC,CAAC,QAAQ,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBACzC,MAAM,IAAI,KAAK,CAAC,UAAU,WAAW,CAAC,IAAI,+BAA+B,CAAC,CAAC;YAC7E,CAAC;YAED,eAAe,CAAC,QAAQ,CAAC,WAAW,EAAE;gBACpC,IAAI;gBACJ,OAAO;gBACP,eAAe;gBACf,oBAAoB;gBACpB,uBAAuB;gBACvB,cAAc;gBACd,mBAAmB;gBACnB,sBAAsB;aACvB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"module.decorator.js","sourceRoot":"","sources":["../../src/decorators/module.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,UAAU,MAAM,CAAC,EACrB,IAAI,GAAG,EAAE,EACT,OAAO,GAAG,EAAE,EACZ,eAAe,GAAG,EAAE,EACpB,oBAAoB,GAAG,EAAE,EACzB,uBAAuB,GAAG,EAAE,EAC5B,cAAc,GAAG,EAAE,EACnB,mBAAmB,GAAG,EAAE,EACxB,sBAAsB,GAAG,EAAE,GAwB5B;IACC,OAAO,UAAU,WAA4C;QAC3D,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC;aAC3B,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE;YACxB,kDAAkD;YAClD,IAAI,CAAC,CAAC,QAAQ,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBACzC,MAAM,IAAI,KAAK,CAAC,UAAU,WAAW,CAAC,IAAI,+BAA+B,CAAC,CAAC;YAC7E,CAAC;YAED,eAAe,CAAC,QAAQ,CAAC,WAAW,EAAE;gBACpC,IAAI;gBACJ,OAAO;gBACP,eAAe;gBACf,oBAAoB;gBACpB,uBAAuB;gBACvB,cAAc;gBACd,mBAAmB;gBACnB,sBAAsB;aACvB,CAAC,CAAC;QACL,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,YAAY,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/on-event.decorator.d.ts

@@ -0,0 +1,20 @@
+import type { Constructable } from '../app.type.js';
+import type { Event } from '../events/event.model.js';
+/**
+ * An `@OnEvent` is a method decorator to listen to an event.
+ *
+ * @example
+ * ```ts
+ * // Async handler.
+ * @OnEvent(MyEvent)
+ * async onEvent(event: MyEvent): Promise<void> { ... }
+ *
+ * // Sync handler.
+ * @OnEvent(MyEvent)
+ * onEvent(event: MyEvent): void { ... }
+ * ```
+ * @group Decorators
+ * @param ofType The type of event being listened to.
+ * @returns The decorated method.
+ */
+export declare function OnEvent(ofType: Constructable<Event<unknown>>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;

package/dist/decorators/on-event.decorator.js

@@ -0,0 +1,24 @@
+import { EventService } from '../services/event/event.service.js';
+/**
+ * An `@OnEvent` is a method decorator to listen to an event.
+ *
+ * @example
+ * ```ts
+ * // Async handler.
+ * @OnEvent(MyEvent)
+ * async onEvent(event: MyEvent): Promise<void> { ... }
+ *
+ * // Sync handler.
+ * @OnEvent(MyEvent)
+ * onEvent(event: MyEvent): void { ... }
+ * ```
+ * @group Decorators
+ * @param ofType The type of event being listened to.
+ * @returns The decorated method.
+ */
+export function OnEvent(ofType) {
+    return function (target, propertyKey, descriptor) {
+        EventService.getInstance().registerListeners(ofType, target, descriptor);
+    };
+}
+//# sourceMappingURL=on-event.decorator.js.map

package/dist/decorators/on-event.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-event.decorator.js","sourceRoot":"","sources":["../../src/decorators/on-event.decorator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,OAAO,CACrB,MAAqC;IAErC,OAAO,UAAU,MAAW,EAAE,WAAmB,EAAE,UAA8B;QAC/E,YAAY,CAAC,WAAW,EAAE,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/overlay.decorator.d.ts

@@ -1 +1,14 @@
+/**
+ * An `@Overlay` is a class decorator to be placed on top of a class that represents an overlay.
+ * - An overlay must extend the {@link AOverlay} class.
+ *
+ * @example
+ * ```ts
+ * @Overlay()
+ * export class MyOverlay extends AOverlay<MyOverlay> { ... }
+ * ```
+ * @group Decorators
+ * @returns The decorated class.
+ * @see Definition of [Overlays](/docs/fundamentals/overlay-and-anchor).
+ */
 export declare function Overlay(): (constructor: any) => void;

package/dist/decorators/overlay.decorator.js

@@ -1,5 +1,20 @@
+import { RegistrationErrorEvent } from '../events/error.event.js';
+import { EventService } from '../services/event/event.service.js';
 import { ModelSerializationService } from '../services/serialization/model/model-serialization.service.js';
 import { Container } from './container.js';
+/**
+ * An `@Overlay` is a class decorator to be placed on top of a class that represents an overlay.
+ * - An overlay must extend the {@link AOverlay} class.
+ *
+ * @example
+ * ```ts
+ * @Overlay()
+ * export class MyOverlay extends AOverlay<MyOverlay> { ... }
+ * ```
+ * @group Decorators
+ * @returns The decorated class.
+ * @see Definition of [Overlays](/docs/fundamentals/overlay-and-anchor).
+ */
 export function Overlay() {
     return function (constructor) {
         Container.get(ModelSerializationService)
@@ -7,7 +22,7 @@ export function Overlay() {
             modelSerializationService.registerClass(constructor.name, constructor);
         })
             .catch((error) => {
-            console.error(error);
+            EventService.getInstance().emit(new RegistrationErrorEvent(error));
         });
     };
 }

package/dist/decorators/overlay.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"overlay.decorator.js","sourceRoot":"","sources":["../../src/decorators/overlay.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,UAAU,OAAO;IACrB,OAAO,UAAU,WAAgB;QAC/B,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC;aACrC,IAAI,CAAC,CAAC,yBAAyB,EAAE,EAAE;YAClC,yBAAyB,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACzE,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"overlay.decorator.js","sourceRoot":"","sources":["../../src/decorators/overlay.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO;IACrB,OAAO,UAAU,WAAgB;QAC/B,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC;aACrC,IAAI,CAAC,CAAC,yBAAyB,EAAE,EAAE;YAClC,yBAAyB,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACzE,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,YAAY,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/resource.decorator.d.ts

@@ -1 +1,14 @@
+/**
+ * A `@Resource` is a class decorator to be placed on top of a class that represents a resource.
+ * - A resource must extend the {@link AResource} class.
+ *
+ * @example
+ * ```ts
+ * @Resource()
+ * export class MyResource extends AResource<MyResource> { ... }
+ * ```
+ * @group Decorators
+ * @returns The decorated class.
+ * @see Definition of [Resources](http://localhost:3000/docs/fundamentals/resources).
+ */
 export declare function Resource(): (constructor: any) => void;

package/dist/decorators/resource.decorator.js

@@ -1,5 +1,20 @@
+import { RegistrationErrorEvent } from '../events/error.event.js';
+import { EventService } from '../services/event/event.service.js';
 import { ResourceSerializationService } from '../services/serialization/resource/resource-serialization.service.js';
 import { Container } from './container.js';
+/**
+ * A `@Resource` is a class decorator to be placed on top of a class that represents a resource.
+ * - A resource must extend the {@link AResource} class.
+ *
+ * @example
+ * ```ts
+ * @Resource()
+ * export class MyResource extends AResource<MyResource> { ... }
+ * ```
+ * @group Decorators
+ * @returns The decorated class.
+ * @see Definition of [Resources](http://localhost:3000/docs/fundamentals/resources).
+ */
 export function Resource() {
     return function (constructor) {
         Container.get(ResourceSerializationService)
@@ -7,7 +22,7 @@ export function Resource() {
             resourceSerializationService.registerClass(constructor.name, constructor);
         })
             .catch((error) => {
-            console.error(error);
+            EventService.getInstance().emit(new RegistrationErrorEvent(error));
         });
     };
 }

package/dist/decorators/resource.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource.decorator.js","sourceRoot":"","sources":["../../src/decorators/resource.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,UAAU,QAAQ;IACtB,OAAO,UAAU,WAAgB;QAC/B,SAAS,CAAC,GAAG,CAAC,4BAA4B,CAAC;aACxC,IAAI,CAAC,CAAC,4BAA4B,EAAE,EAAE;YACrC,4BAA4B,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC5E,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"resource.decorator.js","sourceRoot":"","sources":["../../src/decorators/resource.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,UAAU,WAAgB;QAC/B,SAAS,CAAC,GAAG,CAAC,4BAA4B,CAAC;aACxC,IAAI,CAAC,CAAC,4BAA4B,EAAE,EAAE;YACrC,4BAA4B,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC5E,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,YAAY,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACJ,CAAC"}

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

@@ -18,10 +18,62 @@ export interface IPackageMock {
     getMocks: () => FactoryMock<unknown>[];
     init(): Promise<void>;
 }
+/**
+ * The TestContainer class is an isolated {@link Container} for tests.
+ *
+ * :::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.
+ * :::
+ *
+ * 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.
+ */
 export declare class TestContainer {
     private static packageMocks;
     private static createTestFactory;
+    /**
+     * The `TestContainer.create()` method allows you to mock factories.
+     *
+     * @example
+     * ```ts
+     * beforeAll(async () => {
+     *   await TestContainer.create({
+     *     importFrom: [OctoAwsCdkPackageMock],
+     *     mocks: [
+     *       { type: MyClass, value: jest.fn() },
+     *       { metadata: { key: 'value' }, type: AnotherClass, value: new AnotherClass() },
+     *     ],
+     *   }, { factoryTimeoutInMs: 500 });
+     * });
+     *
+     * ```
+     * @param subjects The subjects being mocked.
+     * - `importFrom` is an array of {@link IPackageMock} classes, to import custom mocks,
+     * such as from octo-aws-cdk package - [OctoAwsCdkPackageMock](/api/octo-aws-cdk/class/OctoAwsCdkPackageMock).
+     * - `mocks` is an array of objects, to override the default factories.
+     *   - Use `metadata?: { [key: string]: string }` to identify the factory being mocked.
+     *   - Use `type: Constructable<T> | string` to identify the class being mocked.
+     *   - Use `value: T` to provide the mocked value.
+     * @param options Options to configure TestContainer.
+     * - `factoryTimeoutInMs?: number` is to override the default container timeout.
+     */
     static create(subjects: TestContainerSubjects, options?: TestContainerOptions): Promise<void>;
+    /**
+     * 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();
+     * });
+     * ```
+     */
     static reset(): Promise<void>;
 }
 export {};

package/dist/decorators/test-container.js

@@ -1,15 +1,55 @@
 import { DiffUtility } from '../functions/diff/diff.utility.js';
 import { Container } from './container.js';
+/**
+ * The TestContainer class is an isolated {@link Container} for tests.
+ *
+ * :::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.
+ * :::
+ *
+ * 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.
+ */
 export class TestContainer {
-    static packageMocks = [];
+    static { this.packageMocks = []; }
     static createTestFactory(mock) {
         return class {
-            static mock = mock;
+            static { this.mock = mock; }
             static async create() {
                 return this.mock.value;
             }
         };
     }
+    /**
+     * The `TestContainer.create()` method allows you to mock factories.
+     *
+     * @example
+     * ```ts
+     * beforeAll(async () => {
+     *   await TestContainer.create({
+     *     importFrom: [OctoAwsCdkPackageMock],
+     *     mocks: [
+     *       { type: MyClass, value: jest.fn() },
+     *       { metadata: { key: 'value' }, type: AnotherClass, value: new AnotherClass() },
+     *     ],
+     *   }, { factoryTimeoutInMs: 500 });
+     * });
+     *
+     * ```
+     * @param subjects The subjects being mocked.
+     * - `importFrom` is an array of {@link IPackageMock} classes, to import custom mocks,
+     * such as from octo-aws-cdk package - [OctoAwsCdkPackageMock](/api/octo-aws-cdk/class/OctoAwsCdkPackageMock).
+     * - `mocks` is an array of objects, to override the default factories.
+     *   - Use `metadata?: { [key: string]: string }` to identify the factory being mocked.
+     *   - Use `type: Constructable<T> | string` to identify the class being mocked.
+     *   - Use `value: T` to provide the mocked value.
+     * @param options Options to configure TestContainer.
+     * - `factoryTimeoutInMs?: number` is to override the default container timeout.
+     */
     static async create(subjects, options) {
         const oldFactories = { ...Container['factories'] };
         Container.reset();
@@ -42,6 +82,18 @@ export class TestContainer {
             }
         }
     }
+    /**
+     * 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();
+     * });
+     * ```
+     */
     static async reset() {
         for (const mock of this.packageMocks) {
             await mock.destroy();

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

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

package/dist/decorators/validate.decorator.d.ts

@@ -0,0 +1,9 @@
+import type { ValidationType } from '../app.type.js';
+type ValidationOptions<T> = {
+    options: {
+        [key in ValidationType]?: any;
+    };
+    destruct?: (value: any) => T[];
+};
+export declare function Validate<T>(validators: ValidationOptions<T> | ValidationOptions<T>[]): (target: any, propertyKey: string) => void;
+export {};

package/dist/decorators/validate.decorator.js

@@ -0,0 +1,23 @@
+import { ValidationService } from '../services/validation/validation.service.js';
+export function Validate(validators) {
+    return function (target, propertyKey) {
+        const symbol = Symbol();
+        Object.defineProperty(target, propertyKey, {
+            get: function () {
+                return this[symbol];
+            },
+            set: function (newValue) {
+                if (!Array.isArray(validators)) {
+                    validators = [validators];
+                }
+                for (const validator of validators) {
+                    for (const [type, constraint] of Object.entries(validator.options)) {
+                        ValidationService.getInstance().addSubject(type, constraint, target, propertyKey, newValue, validator.destruct);
+                    }
+                }
+                this[symbol] = newValue;
+            },
+        });
+    };
+}
+//# sourceMappingURL=validate.decorator.js.map

package/dist/decorators/validate.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.decorator.js","sourceRoot":"","sources":["../../src/decorators/validate.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAOjF,MAAM,UAAU,QAAQ,CACtB,UAAyD;IAEzD,OAAO,UAAU,MAAW,EAAE,WAAmB;QAC/C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;QAExB,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE;YACzC,GAAG,EAAE;gBACH,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;YACD,GAAG,EAAE,UAAU,QAAa;gBAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC/B,UAAU,GAAG,CAAC,UAAU,CAAC,CAAC;gBAC5B,CAAC;gBAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;oBACnC,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;wBACnE,iBAAiB,CAAC,WAAW,EAAE,CAAC,UAAU,CACxC,IAAsB,EACtB,UAAU,EACV,MAAM,EACN,WAAW,EACX,QAAQ,EACR,SAAS,CAAC,QAAQ,CACnB,CAAC;oBACJ,CAAC;gBACH,CAAC;gBAED,IAAI,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;YAC1B,CAAC;SACF,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/events/error.event.d.ts

@@ -0,0 +1,35 @@
+import { Event } from './event.model.js';
+/**
+ * The ErrorEvent class is the superclass for all events emitting an error.
+ * An error event is generated when Octo encounters an error.
+ *
+ * :::warning Warning
+ * It is not a good practice to create an event from this class directly,
+ * but should rather create one from one of the subclasses.
+ * This promotes a more accurate classification of events.
+ * :::
+ *
+ * @example
+ * ```ts
+ * const myEvent = new ErrorEvent(new Error('e'));
+ * EventService.getInstance().emit(myEvent);
+ * ```
+ * @group Events
+ * @returns The Event instance.
+ */
+export declare class ErrorEvent extends Event<Error> {
+}
+/**
+ * This event is emitted at startup when a class fails to register.
+ * It emits the [Error](https://nodejs.org/api/errors.html) object.
+ *
+ * @example
+ * ```ts
+ * const myEvent = new RegistrationErrorEvent(new Error('e'));
+ * EventService.getInstance().emit(myEvent);
+ * ```
+ * @group Events
+ * @returns The Event instance.
+ */
+export declare class RegistrationErrorEvent extends ErrorEvent {
+}

package/dist/events/error.event.js

@@ -0,0 +1,36 @@
+import { Event } from './event.model.js';
+/**
+ * The ErrorEvent class is the superclass for all events emitting an error.
+ * An error event is generated when Octo encounters an error.
+ *
+ * :::warning Warning
+ * It is not a good practice to create an event from this class directly,
+ * but should rather create one from one of the subclasses.
+ * This promotes a more accurate classification of events.
+ * :::
+ *
+ * @example
+ * ```ts
+ * const myEvent = new ErrorEvent(new Error('e'));
+ * EventService.getInstance().emit(myEvent);
+ * ```
+ * @group Events
+ * @returns The Event instance.
+ */
+export class ErrorEvent extends Event {
+}
+/**
+ * This event is emitted at startup when a class fails to register.
+ * It emits the [Error](https://nodejs.org/api/errors.html) object.
+ *
+ * @example
+ * ```ts
+ * const myEvent = new RegistrationErrorEvent(new Error('e'));
+ * EventService.getInstance().emit(myEvent);
+ * ```
+ * @group Events
+ * @returns The Event instance.
+ */
+export class RegistrationErrorEvent extends ErrorEvent {
+}
+//# sourceMappingURL=error.event.js.map

package/dist/events/error.event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.event.js","sourceRoot":"","sources":["../../src/events/error.event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAY;CAAG;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,sBAAuB,SAAQ,UAAU;CAAG"}

package/dist/events/event.model.d.ts

@@ -0,0 +1,37 @@
+import type { EventService } from '../services/event/event.service.js';
+/**
+ * The Event class is the superclass for all events.
+ * An event is generated when something important happens in Octo.
+ * The body of the event contains a header, a payload, and an optional user data.
+ *
+ * :::warning Warning
+ * It is not a good practice to create an event from this class directly,
+ * but should rather create one from one of the subclasses.
+ * This promotes a more accurate classification of events.
+ * :::
+ *
+ * @example
+ * ```ts
+ * const myEvent = new Event<string>('my payload', { key: 'value' });
+ * EventService.getInstance().emit(myEvent);
+ * ```
+ * @group Events
+ * @returns The Event instance.
+ */
+export declare class Event<T> {
+    readonly header: {
+        timestamp: number;
+    };
+    readonly payload: T;
+    readonly userData: object;
+    constructor(payload: T, userData?: object);
+    /**
+     * The `registrar()` method is explicitly called by the {@link EventSource} decorator for a method
+     * to enhance the method to auto-emit events.
+     *
+     * @param args Arguments are spread out using the array spread operator.
+     * - args[0] - Instance of {@link EventService}.
+     * - args[1] - [PropertyDescriptor](https://www.typescriptlang.org/docs/handbook/decorators.html).
+     */
+    static registrar(...args: [EventService, PropertyDescriptor]): void;
+}

package/dist/events/event.model.js

@@ -0,0 +1,43 @@
+/**
+ * The Event class is the superclass for all events.
+ * An event is generated when something important happens in Octo.
+ * The body of the event contains a header, a payload, and an optional user data.
+ *
+ * :::warning Warning
+ * It is not a good practice to create an event from this class directly,
+ * but should rather create one from one of the subclasses.
+ * This promotes a more accurate classification of events.
+ * :::
+ *
+ * @example
+ * ```ts
+ * const myEvent = new Event<string>('my payload', { key: 'value' });
+ * EventService.getInstance().emit(myEvent);
+ * ```
+ * @group Events
+ * @returns The Event instance.
+ */
+export class Event {
+    constructor(payload, userData = {}) {
+        this.header = {
+            timestamp: Date.now(),
+        };
+        this.payload = payload;
+        this.userData = userData;
+    }
+    /**
+     * The `registrar()` method is explicitly called by the {@link EventSource} decorator for a method
+     * to enhance the method to auto-emit events.
+     *
+     * @param args Arguments are spread out using the array spread operator.
+     * - args[0] - Instance of {@link EventService}.
+     * - args[1] - [PropertyDescriptor](https://www.typescriptlang.org/docs/handbook/decorators.html).
+     */
+    static registrar(...args) {
+        if (args.length !== 2) {
+            throw new Error('Invalid number of args in event registrar!');
+        }
+        throw new Error('Method not implemented! Use derived class implementation');
+    }
+}
+//# sourceMappingURL=event.model.js.map

package/dist/events/event.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.model.js","sourceRoot":"","sources":["../../src/events/event.model.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,KAAK;IAShB,YAAY,OAAU,EAAE,WAAmB,EAAE;QAC3C,IAAI,CAAC,MAAM,GAAG;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,IAAwC;QAC1D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;CACF"}