@quadnix/octo 0.0.20 → 0.0.22

package/dist/app.type.d.ts

@@ -1,4 +1,5 @@
 import type { IDependency } from './functions/dependency/dependency.js';
+import type { ANode } from './functions/node/node.abstract.js';
 import type { IAnchor } from './overlays/anchor.interface.js';
 import type { AOverlay } from './overlays/overlay.abstract.js';
 import type { AModel } from './models/model.abstract.js';
@@ -7,12 +8,17 @@ import type { IOverlay } from './overlays/overlay.interface.js';
 import type { AResource } from './resources/resource.abstract.js';
 import type { IResource } from './resources/resource.interface.js';
 import type { ASharedResource } from './resources/shared-resource.abstract.js';
-export declare enum ModelType {
+export declare enum NodeType {
     MODEL = "model",
     OVERLAY = "overlay",
     RESOURCE = "resource",
     SHARED_RESOURCE = "shared-resource"
 }
+export declare enum ValidationType {
+    MAX_LENGTH = "maxLength",
+    MIN_LENGTH = "minLength",
+    REGEX = "regex"
+}
 export type ActionInputs = {
     [key: string]: string | UnknownResource;
 };
@@ -63,6 +69,7 @@ export type TransactionOptions = {
 };
 export type IUnknownModel = IModel<unknown, unknown>;
 export type UnknownModel = AModel<unknown, unknown>;
+export type UnknownNode = ANode<unknown, unknown>;
 export type UnknownOverlay = AOverlay<unknown>;
 export type UnknownResource = AResource<unknown>;
 export type UnknownSharedResource = ASharedResource<unknown>;

package/dist/app.type.js

@@ -1,8 +1,14 @@
-export var ModelType;
-(function (ModelType) {
-    ModelType["MODEL"] = "model";
-    ModelType["OVERLAY"] = "overlay";
-    ModelType["RESOURCE"] = "resource";
-    ModelType["SHARED_RESOURCE"] = "shared-resource";
-})(ModelType || (ModelType = {}));
+export var NodeType;
+(function (NodeType) {
+    NodeType["MODEL"] = "model";
+    NodeType["OVERLAY"] = "overlay";
+    NodeType["RESOURCE"] = "resource";
+    NodeType["SHARED_RESOURCE"] = "shared-resource";
+})(NodeType || (NodeType = {}));
+export var ValidationType;
+(function (ValidationType) {
+    ValidationType["MAX_LENGTH"] = "maxLength";
+    ValidationType["MIN_LENGTH"] = "minLength";
+    ValidationType["REGEX"] = "regex";
+})(ValidationType || (ValidationType = {}));
 //# sourceMappingURL=app.type.js.map

package/dist/app.type.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.type.js","sourceRoot":"","sources":["../src/app.type.ts"],"names":[],"mappings":"AAUA,MAAM,CAAN,IAAY,SAKX;AALD,WAAY,SAAS;IACnB,4BAAe,CAAA;IACf,gCAAmB,CAAA;IACnB,kCAAqB,CAAA;IACrB,gDAAmC,CAAA;AACrC,CAAC,EALW,SAAS,KAAT,SAAS,QAKpB"}
+{"version":3,"file":"app.type.js","sourceRoot":"","sources":["../src/app.type.ts"],"names":[],"mappings":"AAWA,MAAM,CAAN,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,+BAAmB,CAAA;IACnB,iCAAqB,CAAA;IACrB,+CAAmC,CAAA;AACrC,CAAC,EALW,QAAQ,KAAR,QAAQ,QAKnB;AAED,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,0CAAwB,CAAA;IACxB,0CAAwB,CAAA;IACxB,iCAAe,CAAA;AACjB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB"}

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

@@ -1,2 +1,19 @@
-import { ModelType } from '../app.type.js';
-export declare function Action(type: ModelType): (constructor: any) => void;
+import { NodeType } from '../app.type.js';
+/**
+ * An `@Action` is a class decorator to be placed on top of a class that represents an action of one of ModelType.
+ * - A NodeType.MODEL action must implement the {@link IModelAction} interface.
+ * - A NodeType.OVERLAY action must implement the {@link IModelAction} interface.
+ * - A NodeType.RESOURCE action must implement the {@link IResourceAction} interface.
+ * - A NodeType.SHARED_RESOURCE action must implement the {@link IResourceAction} interface.
+ *
+ * @example
+ * ```ts
+ * @Action(ModelType.MODEL)
+ * export class MyModelAction implements IModelAction { ... }
+ * ```
+ * @group Decorators
+ * @param type The type of Model being decorated.
+ * @returns The decorated class.
+ * @see Definition of [Actions](/docs/fundamentals/actions).
+ */
+export declare function Action(type: NodeType): (constructor: any) => void;

package/dist/decorators/action.decorator.js

@@ -1,30 +1,53 @@
-import { ModelType } from '../app.type.js';
+import { NodeType } from '../app.type.js';
 import { RegistrationErrorEvent } from '../events/error.event.js';
 import { ModelActionHook } from '../functions/hook/model-action.hook.js';
 import { ResourceActionHook } from '../functions/hook/resource-action.hook.js';
 import { EventService } from '../services/event/event.service.js';
 import { TransactionService } from '../services/transaction/transaction.service.js';
-import { Container } from './container.js';
+import { Container } from '../functions/container/container.js';
+/**
+ * An `@Action` is a class decorator to be placed on top of a class that represents an action of one of ModelType.
+ * - A NodeType.MODEL action must implement the {@link IModelAction} interface.
+ * - A NodeType.OVERLAY action must implement the {@link IModelAction} interface.
+ * - A NodeType.RESOURCE action must implement the {@link IResourceAction} interface.
+ * - A NodeType.SHARED_RESOURCE action must implement the {@link IResourceAction} interface.
+ *
+ * @example
+ * ```ts
+ * @Action(ModelType.MODEL)
+ * export class MyModelAction implements IModelAction { ... }
+ * ```
+ * @group Decorators
+ * @param type The type of Model being decorated.
+ * @returns The decorated class.
+ * @see Definition of [Actions](/docs/fundamentals/actions).
+ */
 export function Action(type) {
     return function (constructor) {
         Container.get(TransactionService)
             .then(async (transactionService) => {
             switch (type) {
-                case ModelType.MODEL: {
+                case NodeType.MODEL: {
+                    // Register model action.
                     const modelAction = await Container.get(constructor.name);
                     transactionService.registerModelActions([modelAction]);
+                    // Wrap model action with hooks.
                     ModelActionHook.getInstance().registrar(modelAction);
                     break;
                 }
-                case ModelType.OVERLAY: {
+                case NodeType.OVERLAY: {
+                    // Register overlay action.
                     const modelAction = await Container.get(constructor.name);
                     transactionService.registerOverlayActions([modelAction]);
+                    // Wrap overlay action with hooks.
                     ModelActionHook.getInstance().registrar(modelAction);
                     break;
                 }
-                case ModelType.RESOURCE: {
+                case NodeType.RESOURCE: {
+                    // Register resource action.
                     const resourceAction = await Container.get(constructor.name);
                     transactionService.registerResourceActions([resourceAction]);
+                    // Wrap resource action with hooks.
                     ResourceActionHook.getInstance().registrar(resourceAction);
                     break;
                 }

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

@@ -1 +1 @@
-{"version":3,"file":"action.decorator.js","sourceRoot":"","sources":["../../src/decorators/action.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAG/E,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,UAAU,MAAM,CAAC,IAAe;IACpC,OAAO,UAAU,WAAgB;QAC/B,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC;aAC9B,IAAI,CAAC,KAAK,EAAE,kBAAkB,EAAE,EAAE;YACjC,QAAQ,IAAI,EAAE,CAAC;gBACb,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;oBAErB,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAe,WAAW,CAAC,IAAI,CAAC,CAAC;oBACxE,kBAAkB,CAAC,oBAAoB,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;oBAGvD,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;oBACrD,MAAM;gBACR,CAAC;gBACD,KAAK,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;oBAEvB,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAe,WAAW,CAAC,IAAI,CAAC,CAAC;oBACxE,kBAAkB,CAAC,sBAAsB,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;oBAGzD,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;oBACrD,MAAM;gBACR,CAAC;gBACD,KAAK,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;oBAExB,MAAM,cAAc,GAAG,MAAM,SAAS,CAAC,GAAG,CAAkB,WAAW,CAAC,IAAI,CAAC,CAAC;oBAC9E,kBAAkB,CAAC,uBAAuB,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;oBAG7D,kBAAkB,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;oBAC3D,MAAM;gBACR,CAAC;gBACD,OAAO,CAAC,CAAC,CAAC;oBACR,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;gBACpE,CAAC;YACH,CAAC;QACH,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"}
+{"version":3,"file":"action.decorator.js","sourceRoot":"","sources":["../../src/decorators/action.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAG/E,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAEhE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,MAAM,CAAC,IAAc;IACnC,OAAO,UAAU,WAAgB;QAC/B,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC;aAC9B,IAAI,CAAC,KAAK,EAAE,kBAAkB,EAAE,EAAE;YACjC,QAAQ,IAAI,EAAE,CAAC;gBACb,KAAK,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;oBACpB,yBAAyB;oBACzB,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAe,WAAW,CAAC,IAAI,CAAC,CAAC;oBACxE,kBAAkB,CAAC,oBAAoB,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;oBAEvD,gCAAgC;oBAChC,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;oBACrD,MAAM;gBACR,CAAC;gBACD,KAAK,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;oBACtB,2BAA2B;oBAC3B,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAe,WAAW,CAAC,IAAI,CAAC,CAAC;oBACxE,kBAAkB,CAAC,sBAAsB,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;oBAEzD,kCAAkC;oBAClC,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;oBACrD,MAAM;gBACR,CAAC;gBACD,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;oBACvB,4BAA4B;oBAC5B,MAAM,cAAc,GAAG,MAAM,SAAS,CAAC,GAAG,CAAkB,WAAW,CAAC,IAAI,CAAC,CAAC;oBAC9E,kBAAkB,CAAC,uBAAuB,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;oBAE7D,mCAAmC;oBACnC,kBAAkB,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;oBAC3D,MAAM;gBACR,CAAC;gBACD,OAAO,CAAC,CAAC,CAAC;oBACR,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;gBACpE,CAAC;YACH,CAAC;QACH,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/anchor.decorator.d.ts

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

package/dist/decorators/anchor.decorator.js

@@ -1,7 +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';
+import { Container } from '../functions/container/container.js';
+/**
+ * An `@Anchor` is a class decorator to be placed on top of a class that represents an anchor.
+ * - An anchor must extend the {@link AAnchor} class.
+ *
+ * @example
+ * ```ts
+ * @Anchor()
+ * export class MyAnchor extends AAnchor { ... }
+ * ```
+ * @group Decorators
+ * @returns The decorated class.
+ * @see Definition of [Anchors](/docs/fundamentals/overlay-and-anchor).
+ */
 export function Anchor() {
     return function (constructor) {
         Container.get(ModelSerializationService)

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

@@ -1 +1 @@
-{"version":3,"file":"anchor.decorator.js","sourceRoot":"","sources":["../../src/decorators/anchor.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,MAAM,UAAU,MAAM;IACpB,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"}
+{"version":3,"file":"anchor.decorator.js","sourceRoot":"","sources":["../../src/decorators/anchor.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,qCAAqC,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM;IACpB,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/enable-hook.decorator.d.ts

@@ -1,3 +1,17 @@
 type Hook = 'CommitHook';
+/**
+ * A `@EnableHook` is a method decorator to enable registration of hooks.
+ *
+ * @example
+ * ```ts
+ * @EnableHook('CommitHook')
+ * async commitTransaction(): Promise<void> { ... }
+ * ```
+ * @group Decorators
+ * @internal
+ * @param hook The only values supported are `CommitHook`.
+ * @returns The decorated method.
+ * @see Definition of [Hooks](/docs/fundamentals/modules#hooks).
+ */
 export declare function EnableHook(hook: Hook): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export {};

package/dist/decorators/enable-hook.decorator.js

@@ -1,4 +1,18 @@
 import { CommitHook } from '../functions/hook/commit.hook.js';
+/**
+ * A `@EnableHook` is a method decorator to enable registration of hooks.
+ *
+ * @example
+ * ```ts
+ * @EnableHook('CommitHook')
+ * async commitTransaction(): Promise<void> { ... }
+ * ```
+ * @group Decorators
+ * @internal
+ * @param hook The only values supported are `CommitHook`.
+ * @returns The decorated method.
+ * @see Definition of [Hooks](/docs/fundamentals/modules#hooks).
+ */
 export function EnableHook(hook) {
     return function (target, propertyKey, descriptor) {
         switch (hook) {

package/dist/decorators/enable-hook.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"enable-hook.decorator.js","sourceRoot":"","sources":["../../src/decorators/enable-hook.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAI9D,MAAM,UAAU,UAAU,CAAC,IAAU;IACnC,OAAO,UAAU,MAAW,EAAE,WAAmB,EAAE,UAA8B;QAC/E,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,YAAY;gBACf,UAAU,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;gBAC/C,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"enable-hook.decorator.js","sourceRoot":"","sources":["../../src/decorators/enable-hook.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAI9D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAC,IAAU;IACnC,OAAO,UAAU,MAAW,EAAE,WAAmB,EAAE,UAA8B;QAC/E,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,YAAY;gBACf,UAAU,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;gBAC/C,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

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

@@ -1,3 +1,18 @@
 import type { Constructable } from '../app.type.js';
 import type { Event } from '../events/event.model.js';
+/**
+ * An `@EventSource` is a method decorator to enable automatic event emission.
+ * The `registrar()` method of the Event class is used to decorate the method to auto-emit events.
+ * - All event types must extend the {@link Event} class.
+ *
+ * @example
+ * ```ts
+ * @EventSource(MyEvent)
+ * myMethod(): void { ... }
+ * ```
+ * @group Decorators
+ * @internal
+ * @param ofType The type of event being emitted.
+ * @returns The decorated method.
+ */
 export declare function EventSource(ofType: Constructable<Event<unknown>>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;

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

@@ -1,4 +1,19 @@
 import { EventService } from '../services/event/event.service.js';
+/**
+ * An `@EventSource` is a method decorator to enable automatic event emission.
+ * The `registrar()` method of the Event class is used to decorate the method to auto-emit events.
+ * - All event types must extend the {@link Event} class.
+ *
+ * @example
+ * ```ts
+ * @EventSource(MyEvent)
+ * myMethod(): void { ... }
+ * ```
+ * @group Decorators
+ * @internal
+ * @param ofType The type of event being emitted.
+ * @returns The decorated method.
+ */
 export function EventSource(ofType) {
     return function (target, propertyKey, descriptor) {
         ofType.registrar(EventService.getInstance(), descriptor);

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

@@ -1 +1 @@
-{"version":3,"file":"event-source.decorator.js","sourceRoot":"","sources":["../../src/decorators/event-source.decorator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAElE,MAAM,UAAU,WAAW,CACzB,MAAqC;IAErC,OAAO,UAAU,MAAW,EAAE,WAAmB,EAAE,UAA8B;QAC9E,MAAc,CAAC,SAAS,CAAC,YAAY,CAAC,WAAW,EAAE,EAAE,UAAU,CAAC,CAAC;IACpE,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"event-source.decorator.js","sourceRoot":"","sources":["../../src/decorators/event-source.decorator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAElE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CACzB,MAAqC;IAErC,OAAO,UAAU,MAAW,EAAE,WAAmB,EAAE,UAA8B;QAC9E,MAAc,CAAC,SAAS,CAAC,YAAY,CAAC,WAAW,EAAE,EAAE,UAAU,CAAC,CAAC;IACpE,CAAC,CAAC;AACJ,CAAC"}

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

@@ -1,8 +1,57 @@
 import type { Constructable } from '../app.type.js';
-export declare function Factory<T>(type: Constructable<T> | string, options?: {
-    metadata?: {
-        [key: string]: string;
-    };
-}): (constructor: {
+/**
+ * A `@Factory` is a class decorator to be placed on top of a class that represents a factory.
+ * A factory is responsible for creating instances of a class.
+ *
+ * @example
+ * ```ts
+ * // Factory definition.
+ * @Factory<MyService>(MyService)
+ * export class MyServiceFactory {
+ *   static async create(arg1, arg2, ...): Promise<MyService> { ... }
+ * }
+ *
+ * // Get instance using default factory.
+ * const myService = await Container.get(MyService);
+ *
+ * // Pass args to factory.
+ * const myService = await Container.get(MyService, { args: [arg1, arg2, ...] });
+ * ```
+ * @group Decorators
+ * @param type The type of class that the factory creates.
+ * @remarks
+ * If the factory is dependent on other factories, it should not block creation of its instance.
+ * ```ts
+ * // Correct, since creation of instance is not blocked.
+ * // In this case, when multiple code paths are trying to get Container.get(MyService) at the same time,
+ * // each of them will `await` for OtherService to get resolved,
+ * // and the first to resolve will be able to create the instance, that the rest will re-use.
+ * export class MyServiceFactory {
+ *   private static instance: MyService;
+ *   static async create(): Promise<MyService> {
+ *     const otherInstance = await Container.get(OtherService);
+ *     if (!this.instance) {
+ *       this.instance = new MyService(otherInstance);
+ *     }
+ *   }
+ * }
+ * ```
+ * ```ts
+ * // Wrong, since creation of instance is blocked.
+ * // In this case, when multiple code paths are trying to get Container.get(MyService) at the same time,
+ * // each of them will get a new instance since during `await` there is race condition.
+ * export class MyServiceFactory {
+ *   private static instance: MyService;
+ *   static async create(): Promise<MyService> {
+ *     if (!this.instance) {
+ *       const otherInstance = await Container.get(OtherService);
+ *       this.instance = new MyService(otherInstance);
+ *     }
+ *   }
+ * }
+ * ```
+ * @returns The decorated class.
+ */
+export declare function Factory<T>(type: Constructable<T> | string): (constructor: {
     create: (...args: unknown[]) => Promise<T>;
 }) => void;

package/dist/decorators/factory.decorator.js

@@ -1,7 +1,60 @@
-import { Container } from './container.js';
-export function Factory(type, options) {
+import { Container } from '../functions/container/container.js';
+/**
+ * A `@Factory` is a class decorator to be placed on top of a class that represents a factory.
+ * A factory is responsible for creating instances of a class.
+ *
+ * @example
+ * ```ts
+ * // Factory definition.
+ * @Factory<MyService>(MyService)
+ * export class MyServiceFactory {
+ *   static async create(arg1, arg2, ...): Promise<MyService> { ... }
+ * }
+ *
+ * // Get instance using default factory.
+ * const myService = await Container.get(MyService);
+ *
+ * // Pass args to factory.
+ * const myService = await Container.get(MyService, { args: [arg1, arg2, ...] });
+ * ```
+ * @group Decorators
+ * @param type The type of class that the factory creates.
+ * @remarks
+ * If the factory is dependent on other factories, it should not block creation of its instance.
+ * ```ts
+ * // Correct, since creation of instance is not blocked.
+ * // In this case, when multiple code paths are trying to get Container.get(MyService) at the same time,
+ * // each of them will `await` for OtherService to get resolved,
+ * // and the first to resolve will be able to create the instance, that the rest will re-use.
+ * export class MyServiceFactory {
+ *   private static instance: MyService;
+ *   static async create(): Promise<MyService> {
+ *     const otherInstance = await Container.get(OtherService);
+ *     if (!this.instance) {
+ *       this.instance = new MyService(otherInstance);
+ *     }
+ *   }
+ * }
+ * ```
+ * ```ts
+ * // Wrong, since creation of instance is blocked.
+ * // In this case, when multiple code paths are trying to get Container.get(MyService) at the same time,
+ * // each of them will get a new instance since during `await` there is race condition.
+ * export class MyServiceFactory {
+ *   private static instance: MyService;
+ *   static async create(): Promise<MyService> {
+ *     if (!this.instance) {
+ *       const otherInstance = await Container.get(OtherService);
+ *       this.instance = new MyService(otherInstance);
+ *     }
+ *   }
+ * }
+ * ```
+ * @returns The decorated class.
+ */
+export function Factory(type) {
     return function (constructor) {
-        Container.registerFactory(type, constructor, options);
+        Container.registerFactory(type, constructor);
     };
 }
 //# sourceMappingURL=factory.decorator.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"factory.decorator.js","sourceRoot":"","sources":["../../src/decorators/factory.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,UAAU,OAAO,CACrB,IAA+B,EAC/B,OAEC;IAED,OAAO,UAAU,WAA2D;QAC1E,SAAS,CAAC,eAAe,CAAI,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"factory.decorator.js","sourceRoot":"","sources":["../../src/decorators/factory.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,UAAU,OAAO,CACrB,IAA+B;IAE/B,OAAO,UAAU,WAA2D;QAC1E,SAAS,CAAC,eAAe,CAAI,IAAI,EAAE,WAAW,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

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

@@ -1 +1,14 @@
+/**
+ * A `@Model` is a class decorator to be placed on top of a class that represents a model.
+ * - A model must extend the {@link AModel} class.
+ *
+ * @example
+ * ```ts
+ * @Model()
+ * export class MyModel extends AModel<IMyModel, MyModel> { ... }
+ * ```
+ * @group Decorators
+ * @returns The decorated class.
+ * @see Definition of [Models](/docs/fundamentals/models).
+ */
 export declare function Model(): (constructor: any) => void;

package/dist/decorators/model.decorator.js

@@ -1,7 +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';
+import { Container } from '../functions/container/container.js';
+/**
+ * A `@Model` is a class decorator to be placed on top of a class that represents a model.
+ * - A model must extend the {@link AModel} class.
+ *
+ * @example
+ * ```ts
+ * @Model()
+ * export class MyModel extends AModel<IMyModel, MyModel> { ... }
+ * ```
+ * @group Decorators
+ * @returns The decorated class.
+ * @see Definition of [Models](/docs/fundamentals/models).
+ */
 export function Model() {
     return function (constructor) {
         Container.get(ModelSerializationService)

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

@@ -1 +1 @@
-{"version":3,"file":"model.decorator.js","sourceRoot":"","sources":["../../src/decorators/model.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,MAAM,UAAU,KAAK;IACnB,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"}
+{"version":3,"file":"model.decorator.js","sourceRoot":"","sources":["../../src/decorators/model.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,qCAAqC,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,KAAK;IACnB,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/module.decorator.d.ts

@@ -1,16 +1,18 @@
 import type { Constructable } from '../app.type.js';
-import type { Octo } from '../main.js';
+import type { DiffMetadata } from '../functions/diff/diff-metadata.js';
+import type { App } from '../models/app/app.model.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';
-export declare function Module({ args, imports, postCommitHooks, postModelActionHooks, postResourceActionHooks, preCommitHooks, preModelActionHooks, preResourceActionHooks, }: {
+type CommitHooksCallback = (app: App, modelTransaction: DiffMetadata[][], resourceTransaction: DiffMetadata[][]) => Promise<void>;
+export interface IModuleOptions {
     args?: {
         isArg: (arg: unknown) => boolean;
         name: string;
     }[];
     imports?: (Constructable<IModule<unknown>> | string)[];
     postCommitHooks?: {
-        callback: Octo['commitTransaction'];
+        callback: CommitHooksCallback;
     }[];
     postModelActionHooks?: {
         ACTION_NAME: string;
@@ -22,7 +24,7 @@ export declare function Module({ args, imports, postCommitHooks, postModelAction
         handle: IResourceAction['handle'];
     }[];
     preCommitHooks?: {
-        callback: Octo['commitTransaction'];
+        callback: CommitHooksCallback;
     }[];
     preModelActionHooks?: {
         ACTION_NAME: string;
@@ -33,4 +35,58 @@ export declare function Module({ args, imports, postCommitHooks, postModelAction
         ACTION_NAME: string;
         handle: IResourceAction['handle'];
     }[];
-}): (constructor: any) => void;
+}
+/**
+ * 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, }?: IModuleOptions): (constructor: any) => void;
+export {};

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 { Container } from './container.js';
-export function Module({ args = [], imports = [], postCommitHooks = [], postModelActionHooks = [], postResourceActionHooks = [], preCommitHooks = [], preModelActionHooks = [], preResourceActionHooks = [], }) {
+import { EventService } from '../services/event/event.service.js';
+import { Container } from '../functions/container/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));
         });
     };
 }