@quadnix/octo 0.0.30 → 0.1.0

package/README.md

@@ -1,5 +1,6 @@
 # Octo
-http://octo.quadnix.com/
+
+https://octo.quadnix.com/
 
 The open-source infrastructure management and CICD tool.
 
@@ -8,6 +9,27 @@ The open-source infrastructure management and CICD tool.
 > We plan to release version `1.x.x` when it is deemed ready for production use.
 
 # Local Setup
-> npm install
 
-> npm run prepare
+## Prerequisites
+
+- [Node.js](https://nodejs.org) 22 (LTS). This ships with Corepack, which provisions the
+  exact package manager the project expects — you do **not** need to install pnpm yourself.
+
+## Install
+
+This repository is a [pnpm](https://pnpm.io) workspace. Corepack reads the `packageManager`
+field in the root `package.json` and uses the pnpm version pinned there, so everyone (and CI)
+runs the same version.
+
+```sh
+# One-time per machine: activate Corepack so the `pnpm` command uses the pinned version.
+corepack enable
+
+# Install all workspace dependencies (packages/*).
+pnpm install
+```
+
+> **Note:** The documentation site under `apps/octo-docs` is an intentionally separate
+> project — it consumes the published `@quadnix/*` packages from the registry rather than the
+> local source. It is not part of the root workspace and is only installed (with its own
+> `pnpm install`, run from inside that directory) when you are working on the docs.

package/dist/app.type.d.ts

@@ -13,38 +13,89 @@ import type { AResource } from './resources/resource.abstract.js';
 import type { BaseResourceSchema } from './resources/resource.schema.js';
 import type { ValidationUtility } from './utilities/validation/validation.utility.js';
 /**
+ * An anchor found by schema, paired with the translation needed to read it as that schema.
+ *
+ * {@link AModel.getAnchorsMatchingSchema} returns these rather than raw anchors: the anchor you
+ * matched may have been declared against a different version of the schema, and this is what keeps
+ * that difference out of your module. Read it with `getSchemaInstance()`.
+ *
  * @group Types
  */
 export declare class MatchingAnchor<S extends BaseAnchorSchema> {
     private readonly actual;
     private readonly schemaTranslator?;
+    /**
+     * @param actual The anchor that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual: AAnchor<S, any>, schemaTranslator?: ((synth: any) => S) | undefined);
-    hasSchemaTranslator(): boolean;
+    /**
+     * The anchor itself, with its properties hidden - read those through
+     * {@link MatchingAnchor.getSchemaInstance}.
+     */
     getActual(): AAnchor<Omit<S, 'properties'> & {
         properties: Record<never, never>;
     }, any>;
+    /**
+     * The anchor read as the schema you matched on.
+     */
     getSchemaInstance(): S;
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator(): boolean;
 }
 /**
+ * A model found by schema. See {@link MatchingAnchor}.
+ *
  * @group Types
  */
 export declare class MatchingModel<S extends object> {
     private readonly actual;
     private readonly schemaTranslator?;
+    /**
+     * @param actual The model that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual: AModel<S, any>, schemaTranslator?: ((synth: any) => S) | undefined);
-    hasSchemaTranslator(): boolean;
+    /**
+     * The model itself, with its schema hidden - read it through
+     * {@link MatchingModel.getSchemaInstance}.
+     */
     getActual(): AModel<Record<never, never>, any>;
+    /**
+     * The model read as the schema you matched on.
+     */
     getSchemaInstance(): S;
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator(): boolean;
 }
 /**
+ * A resource found by schema. See {@link MatchingAnchor}.
+ *
+ * Pass one wherever a resource parent is expected, and the translation is carried into the graph, so
+ * the child keeps reading its parent through the schema it was written against.
+ *
  * @group Types
  */
 export declare class MatchingResource<S extends BaseResourceSchema> {
     private readonly actual;
     readonly schemaTranslator?: ((synth: BaseResourceSchema) => S) | undefined;
+    /**
+     * @param actual The resource that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual: AResource<S, any>, schemaTranslator?: ((synth: BaseResourceSchema) => S) | undefined);
+    /**
+     * @internal
+     */
     addChild(...args: Parameters<AResource<BaseResourceSchema, any>['addChild']>): ReturnType<AResource<BaseResourceSchema, any>['addChild']>;
-    hasSchemaTranslator(): boolean;
+    /**
+     * The resource itself, with its schema hidden - read it through
+     * {@link MatchingResource.getSchemaInstance}.
+     */
     getActual(): AResource<Omit<S, 'properties' | 'response' | 'tags'> & {
         properties: Record<never, never>;
     } & {
@@ -52,10 +103,21 @@ export declare class MatchingResource<S extends BaseResourceSchema> {
     } & {
         tags: Record<never, never>;
     }, any>;
+    /**
+     * The resource read as the schema you matched on.
+     */
     getSchemaInstance(): S;
+    /**
+     * The resource read as the schema you matched on, with its `response` typed as fully populated.
+     * Only call it from a resource action, where the parent is guaranteed to already exist.
+     */
     getSchemaInstanceInResourceAction(): Omit<S, 'response'> & {
         response: Required<S['response']>;
     };
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator(): boolean;
 }
 /**
  * @internal
@@ -92,10 +154,19 @@ export type ValidationTypeOptions = {
     [ValidationType.REGEX]: Parameters<typeof ValidationUtility.validateRegex>[1];
 };
 /**
+ * Whether a node was registered under the given name, e.g. `region`.
+ *
+ * Use it to identify a base model without importing the subclass that implements it.
+ *
  * @group Types
  */
 export declare function hasNodeName(node: UnknownNode, nodeName: string): boolean;
 /**
+ * Marks a placeholder value that a later step fills in - typically a resource property whose real
+ * value is only known once the infrastructure exists.
+ *
+ * It is a type assertion and nothing more; it emits the string you give it.
+ *
  * @group Types
  */
 export declare function stub<T>(value: string): T;
@@ -104,6 +175,8 @@ export declare function stub<T>(value: string): T;
  */
 export type ActionInputs = EnhancedModuleSchema<UnknownModule>;
 /**
+ * The resources an action declared, keyed by an ID of your choosing.
+ *
  * @group Types
  */
 export type ActionOutputs = {
@@ -119,6 +192,8 @@ export type ClassOptionalProperties<T> = {
     [K in keyof T]: undefined extends T[K] ? K : never;
 }[keyof T];
 /**
+ * The `value` of a {@link Diff} on a `properties` field: which property changed, and to what.
+ *
  * @group Types
  */
 export type DiffValueTypePropertyUpdate = {
@@ -126,6 +201,8 @@ export type DiffValueTypePropertyUpdate = {
     value: unknown;
 };
 /**
+ * The `value` of a {@link Diff} on a `tags` field, split by what happened to each tag.
+ *
  * @group Types
  */
 export type DiffValueTypeTagUpdate = {
@@ -147,10 +224,14 @@ export type ObjectKeyValue<T> = {
     };
 }[keyof T];
 /**
+ * The class of `T`, i.e. what you pass when an API wants a type rather than an instance.
+ *
  * @group Types
  */
 export type Constructable<T> = new (...args: any[]) => T;
 /**
+ * The model graph as written to state.
+ *
  * @group Types
  */
 export type ModelSerializedOutput = {
@@ -165,6 +246,7 @@ export type ModelSerializedOutput = {
         [p: string]: {
             className: string;
             model: IUnknownModel;
+            moduleId?: string;
         };
     };
     overlays: {
@@ -173,6 +255,8 @@ export type ModelSerializedOutput = {
     }[];
 };
 /**
+ * The resource graph as written to state.
+ *
  * @group Types
  */
 export type ResourceSerializedOutput = {
@@ -180,16 +264,51 @@ export type ResourceSerializedOutput = {
     resources: {
         [p: string]: {
             className: string;
+            moduleId?: string;
             resource: BaseResourceSchema;
         };
     };
 };
+/**
+ * A record of one generated terraform module folder, kept in state so that a later run can tell
+ * which folders it owns.
+ *
+ * @group Types
+ */
+export type TerraformFolderOutput = {
+    hasExternalResources: boolean;
+    moduleId: string;
+    providers: {
+        accountId: string;
+        blockHcl: string;
+        providerType: string;
+        regionId: string;
+        requiredProvider: {
+            minVersion?: string;
+            source: string;
+        };
+    }[];
+};
+/**
+ * A record of where one octo resource ended up in terraform, kept in state so that a plan entry can
+ * be traced back to the resource that produced it.
+ *
+ * @group Types
+ */
+export type TerraformResourceOutput = {
+    moduleId: string;
+    resourceContext: string;
+    resourceId: string;
+    terraformAddresses: string[];
+};
 /**
  * @internal
  */
 export type TransactionOptions = {
-    enableResourceCapture?: boolean;
     enableResourceValidation?: boolean;
+    filterResourceDiffsByResourceId?: string;
+    generateTerraform?: boolean;
+    skipActualResourceUpdate?: boolean;
     yieldModelDiffs?: boolean;
     yieldModelTransaction?: boolean;
     yieldResourceDiffs?: boolean;
@@ -200,10 +319,17 @@ export type TransactionOptions = {
  */
 export type ModifyInterface<T, R> = Omit<T, keyof R> & R;
 /**
+ * The schema of an anchor class.
+ *
  * @group Types
  */
 export type AnchorSchema<T> = T extends AAnchor<infer S, any> ? S : never;
 /**
+ * Everything an action knows about the module it belongs to: the inputs it was loaded with, whatever
+ * {@link AModule.registerMetadata} derived, and the nodes the module produced.
+ *
+ * This is the second argument of {@link IModelAction.handle}.
+ *
  * @group Types
  */
 export type EnhancedModuleSchema<T extends UnknownModule> = {
@@ -215,6 +341,10 @@ export type EnhancedModuleSchema<T extends UnknownModule> = {
     overlays: Record<string, UnknownOverlay>;
     resources: Record<string, UnknownResource>;
 };
+/**
+ * @internal
+ */
+export type GeneratorYieldType<T extends (...args: any) => AsyncGenerator<any, any, any>> = ReturnType<T> extends AsyncGenerator<infer Y, any, any> ? Y : never;
 /**
  * @internal
  */
@@ -224,10 +354,15 @@ export type ModelSchema<T> = T extends AModel<infer S, any> ? S : never;
  */
 export type ModuleOutput<M> = M extends AModule<any, infer T> ? T : never;
 /**
+ * The schema of a module class.
+ *
  * @group Types
  */
 export type ModuleSchema<T> = T extends AModule<infer S, any> ? S : never;
 /**
+ * A module's schema as the caller supplies it - properties with a default become optional.
+ * This is the shape {@link Octo.loadModule} accepts.
+ *
  * @group Types
  */
 export type ModuleSchemaInputs<T> = {
@@ -240,10 +375,14 @@ export type ModuleSchemaInputs<T> = {
  */
 export type NodeSchema<T> = T extends ANode<infer S, any> ? S : never;
 /**
+ * The schema of an overlay class.
+ *
  * @group Types
  */
 export type OverlaySchema<T> = T extends AOverlay<infer S, any> ? S : never;
 /**
+ * The schema of a resource class.
+ *
  * @group Types
  */
 export type ResourceSchema<T> = T extends AResource<infer S, any> ? S : never;

package/dist/app.type.js

@@ -1,48 +1,96 @@
 /* Classes */
 /**
+ * An anchor found by schema, paired with the translation needed to read it as that schema.
+ *
+ * {@link AModel.getAnchorsMatchingSchema} returns these rather than raw anchors: the anchor you
+ * matched may have been declared against a different version of the schema, and this is what keeps
+ * that difference out of your module. Read it with `getSchemaInstance()`.
+ *
  * @group Types
  */
 export class MatchingAnchor {
+    /**
+     * @param actual The anchor that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual, schemaTranslator) {
         this.actual = actual;
         this.schemaTranslator = schemaTranslator;
     }
-    hasSchemaTranslator() {
-        return !!this.schemaTranslator;
-    }
+    /**
+     * The anchor itself, with its properties hidden - read those through
+     * {@link MatchingAnchor.getSchemaInstance}.
+     */
     getActual() {
         return this.actual;
     }
+    /**
+     * The anchor read as the schema you matched on.
+     */
     getSchemaInstance() {
         return this.hasSchemaTranslator() ? this.schemaTranslator(this.actual.synth()) : this.actual.synth();
     }
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator() {
+        return !!this.schemaTranslator;
+    }
 }
 /**
+ * A model found by schema. See {@link MatchingAnchor}.
+ *
  * @group Types
  */
 export class MatchingModel {
+    /**
+     * @param actual The model that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual, schemaTranslator) {
         this.actual = actual;
         this.schemaTranslator = schemaTranslator;
     }
-    hasSchemaTranslator() {
-        return !!this.schemaTranslator;
-    }
+    /**
+     * The model itself, with its schema hidden - read it through
+     * {@link MatchingModel.getSchemaInstance}.
+     */
     getActual() {
         return this.actual;
     }
+    /**
+     * The model read as the schema you matched on.
+     */
     getSchemaInstance() {
         return this.hasSchemaTranslator() ? this.schemaTranslator(this.actual.synth()) : this.actual.synth();
     }
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator() {
+        return !!this.schemaTranslator;
+    }
 }
 /**
+ * A resource found by schema. See {@link MatchingAnchor}.
+ *
+ * Pass one wherever a resource parent is expected, and the translation is carried into the graph, so
+ * the child keeps reading its parent through the schema it was written against.
+ *
  * @group Types
  */
 export class MatchingResource {
+    /**
+     * @param actual The resource that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual, schemaTranslator) {
         this.actual = actual;
         this.schemaTranslator = schemaTranslator;
     }
+    /**
+     * @internal
+     */
     addChild(...args) {
         const results = this.actual.addChild(...args);
         if (!(args[1].parents[args[1].parents.length - 1] instanceof MatchingResource) &&
@@ -52,18 +100,32 @@ export class MatchingResource {
         }
         return results;
     }
-    hasSchemaTranslator() {
-        return !!this.schemaTranslator;
-    }
+    /**
+     * The resource itself, with its schema hidden - read it through
+     * {@link MatchingResource.getSchemaInstance}.
+     */
     getActual() {
         return this.actual;
     }
+    /**
+     * The resource read as the schema you matched on.
+     */
     getSchemaInstance() {
         return this.hasSchemaTranslator() ? this.schemaTranslator(this.actual.synth()) : this.actual.synth();
     }
+    /**
+     * The resource read as the schema you matched on, with its `response` typed as fully populated.
+     * Only call it from a resource action, where the parent is guaranteed to already exist.
+     */
     getSchemaInstanceInResourceAction() {
         return this.getSchemaInstance();
     }
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator() {
+        return !!this.schemaTranslator;
+    }
 }
 /* Enumerations */
 /**
@@ -91,12 +153,21 @@ export var ValidationType;
 })(ValidationType || (ValidationType = {}));
 /* Functions */
 /**
+ * Whether a node was registered under the given name, e.g. `region`.
+ *
+ * Use it to identify a base model without importing the subclass that implements it.
+ *
  * @group Types
  */
 export function hasNodeName(node, nodeName) {
     return node.constructor.NODE_NAME === nodeName;
 }
 /**
+ * Marks a placeholder value that a later step fills in - typically a resource property whose real
+ * value is only known once the infrastructure exists.
+ *
+ * It is a type assertion and nothing more; it emits the string you give it.
+ *
  * @group Types
  */
 export function stub(value) {

package/dist/app.type.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.type.js","sourceRoot":"","sources":["../src/app.type.ts"],"names":[],"mappings":"AAeA,aAAa;AAEb;;GAEG;AACH,MAAM,OAAO,cAAc;IACzB,YACmB,MAAuB,EACvB,gBAAoC;QADpC,WAAM,GAAN,MAAM,CAAiB;QACvB,qBAAgB,GAAhB,gBAAgB,CAAoB;IACpD,CAAC;IAEJ,mBAAmB;QACjB,OAAO,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC;IACjC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAQ,CAAC;IAC/G,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB,YACmB,MAAsB,EACtB,gBAAoC;QADpC,WAAM,GAAN,MAAM,CAAgB;QACtB,qBAAgB,GAAhB,gBAAgB,CAAoB;IACpD,CAAC;IAEJ,mBAAmB;QACjB,OAAO,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC;IACjC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAQ,CAAC;IAC/G,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAC3B,YACmB,MAAyB,EACjC,gBAAmD;QAD3C,WAAM,GAAN,MAAM,CAAmB;QACjC,qBAAgB,GAAhB,gBAAgB,CAAmC;IAC3D,CAAC;IAEJ,QAAQ,CACN,GAAG,IAAgE;QAEnE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;QAE9C,IACE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,YAAY,gBAAgB,CAAC;YACzE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAqB,CAAC,UAAU,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC,UAAU,EAC3G,CAAC;YACD,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,mBAAmB;QACjB,OAAO,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC;IACjC,CAAC;IAED,SAAS;QAMP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAQ,CAAC;IAC/G,CAAC;IAED,iCAAiC;QAC/B,OAAO,IAAI,CAAC,iBAAiB,EAA4E,CAAC;IAC5G,CAAC;CACF;AAED,kBAAkB;AAElB;;GAEG;AACH,MAAM,CAAN,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,+BAAmB,CAAA;IACnB,iCAAqB,CAAA;AACvB,CAAC,EAJW,QAAQ,KAAR,QAAQ,QAInB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,cASX;AATD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,sCAAoB,CAAA;IACpB,0CAAwB,CAAA;IACxB,4CAA0B,CAAA;IAC1B,wCAAsB,CAAA;IACtB,0CAAwB,CAAA;IACxB,0CAAwB,CAAA;IACxB,iCAAe,CAAA;AACjB,CAAC,EATW,cAAc,KAAd,cAAc,QASzB;AAgBD,eAAe;AAEf;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAiB,EAAE,QAAgB;IAC7D,OAAQ,IAAI,CAAC,WAA4B,CAAC,SAAS,KAAK,QAAQ,CAAC;AACnE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,IAAI,CAAI,KAAa;IACnC,OAAO,KAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"app.type.js","sourceRoot":"","sources":["../src/app.type.ts"],"names":[],"mappings":"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"}

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

@@ -1,14 +1,18 @@
 import type { Constructable, UnknownNode } 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.
+ * An `@Action` is a class decorator to be placed on top of a class that reacts to a change in the node it is
+ * declared for. Octo diffs your infrastructure on every run, and invokes the actions whose node changed.
+ *
+ * The interface the action implements is determined by the node it is declared for.
+ * - An action for a model or an overlay implements {@link IModelAction}, and produces resources.
+ * - An action for a resource implements {@link IResourceAction}, and talks to the cloud provider.
+ *
+ * The decorated class is resolved through the {@link Container}, so it must have a registered {@link Factory}.
  *
  * @example
  * ```ts
- * @Action(MyModelClass)
- * export class MyModelAction implements IModelAction { ... }
+ * @Action(MyModel)
+ * export class AddMyModelAction implements IModelAction<MyModule> { ... }
  * ```
  * @group Decorators
  * @param forNode The class of node for which this action is being declared.

package/dist/decorators/action.decorator.js

@@ -5,25 +5,38 @@ import { AModel } from '../models/model.abstract.js';
 import { AOverlay } from '../overlays/overlay.abstract.js';
 import { AResource } from '../resources/resource.abstract.js';
 import { TransactionService } from '../services/transaction/transaction.service.js';
+/**
+ * @internal
+ */
 function isModel(nodeClass) {
     return nodeClass.prototype instanceof AModel;
 }
+/**
+ * @internal
+ */
 function isOverlay(nodeClass) {
     return nodeClass.prototype instanceof AOverlay;
 }
+/**
+ * @internal
+ */
 function isResource(nodeClass) {
     return nodeClass.prototype instanceof AResource;
 }
 /**
- * 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.
+ * An `@Action` is a class decorator to be placed on top of a class that reacts to a change in the node it is
+ * declared for. Octo diffs your infrastructure on every run, and invokes the actions whose node changed.
+ *
+ * The interface the action implements is determined by the node it is declared for.
+ * - An action for a model or an overlay implements {@link IModelAction}, and produces resources.
+ * - An action for a resource implements {@link IResourceAction}, and talks to the cloud provider.
+ *
+ * The decorated class is resolved through the {@link Container}, so it must have a registered {@link Factory}.
  *
  * @example
  * ```ts
- * @Action(MyModelClass)
- * export class MyModelAction implements IModelAction { ... }
+ * @Action(MyModel)
+ * export class AddMyModelAction implements IModelAction<MyModule> { ... }
  * ```
  * @group Decorators
  * @param forNode The class of node for which this action is being declared.

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

@@ -1 +1 @@
-{"version":3,"file":"action.decorator.js","sourceRoot":"","sources":["../../src/decorators/action.decorator.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAEpF,SAAS,OAAO,CAAC,SAAqC;IACpD,OAAO,SAAS,CAAC,SAAS,YAAY,MAAM,CAAC;AAC/C,CAAC;AAED,SAAS,SAAS,CAAC,SAAqC;IACtD,OAAO,SAAS,CAAC,SAAS,YAAY,QAAQ,CAAC;AACjD,CAAC;AAED,SAAS,UAAU,CAAC,SAAqC;IACvD,OAAO,SAAS,CAAC,SAAS,YAAY,SAAS,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,MAAM,CAAwB,OAAyB;IACrE,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IAE1C,OAAO,UAAU,WAAgB;QAC/B,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,kBAAkB,EAAE,EAAE;YAClF,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5C,yBAAyB;gBACzB,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAsB,WAAW,CAAC,IAAI,CAAC,CAAC;gBAC/E,kBAAkB,CAAC,oBAAoB,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;gBAEhE,gCAAgC;gBAChC,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;YACvD,CAAC;iBAAM,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC9B,2BAA2B;gBAC3B,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAsB,WAAW,CAAC,IAAI,CAAC,CAAC;gBAC/E,kBAAkB,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;gBAElE,kCAAkC;gBAClC,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;YACvD,CAAC;iBAAM,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC/B,4BAA4B;gBAC5B,MAAM,cAAc,GAAG,MAAM,SAAS,CAAC,GAAG,CAAyB,WAAW,CAAC,IAAI,CAAC,CAAC;gBACrF,kBAAkB,CAAC,uBAAuB,CAAC,OAAO,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;gBAEtE,mCAAmC;gBACnC,kBAAkB,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;YAC7D,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,CAAC,IAAI,2CAA2C,CAAC,CAAC;YACrF,CAAC;QACH,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"action.decorator.js","sourceRoot":"","sources":["../../src/decorators/action.decorator.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAEpF;;GAEG;AACH,SAAS,OAAO,CAAC,SAAqC;IACpD,OAAO,SAAS,CAAC,SAAS,YAAY,MAAM,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,SAAqC;IACtD,OAAO,SAAS,CAAC,SAAS,YAAY,QAAQ,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,SAAqC;IACvD,OAAO,SAAS,CAAC,SAAS,YAAY,SAAS,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CAAwB,OAAyB;IACrE,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IAE1C,OAAO,UAAU,WAAgB;QAC/B,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,kBAAkB,EAAE,EAAE;YAClF,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5C,yBAAyB;gBACzB,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAsB,WAAW,CAAC,IAAI,CAAC,CAAC;gBAC/E,kBAAkB,CAAC,oBAAoB,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;gBAEhE,gCAAgC;gBAChC,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;YACvD,CAAC;iBAAM,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC9B,2BAA2B;gBAC3B,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,GAAG,CAAsB,WAAW,CAAC,IAAI,CAAC,CAAC;gBAC/E,kBAAkB,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;gBAElE,kCAAkC;gBAClC,eAAe,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;YACvD,CAAC;iBAAM,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC/B,4BAA4B;gBAC5B,MAAM,cAAc,GAAG,MAAM,SAAS,CAAC,GAAG,CAAyB,WAAW,CAAC,IAAI,CAAC,CAAC;gBACrF,kBAAkB,CAAC,uBAAuB,CAAC,OAAO,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;gBAEtE,mCAAmC;gBACnC,kBAAkB,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;YAC7D,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,CAAC,IAAI,2CAA2C,CAAC,CAAC;YACrF,CAAC;QACH,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}

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

@@ -1,14 +1,21 @@
 /**
- * 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.
+ * An `@Anchor` is a class decorator and must be placed on top of a class representing an anchor.
+ * - An anchor must also extend the {@link AAnchor} class.
  *
  * @example
  * ```ts
- * @Anchor('my-package')
- * export class MyAnchor extends AAnchor { ... }
+ * @Anchor('@example')
+ * export class MyAnchor extends AAnchor<MyAnchorSchema, MyModel> { ... }
  * ```
+ *
  * @group Decorators
+ *
+ * @param packageName - The name of the package under which the anchor is registered.
+ * Selecting a unique package name helps avoid collisions between same anchor class names across different libraries.
+ * You will reuse the same package name throughout your library for different Octo components you create.
+ *
  * @returns The decorated class.
- * @see Definition of [Anchors](/docs/fundamentals/overlays).
+ *
+ * @see Definition of [Anchors](/docs/fundamentals/anchors).
  */
 export declare function Anchor(packageName: string): (constructor: any) => void;

package/dist/decorators/anchor.decorator.js

@@ -3,17 +3,24 @@ import { AAnchor } from '../overlays/anchor.abstract.js';
 import { ModelSerializationService } from '../services/serialization/model/model-serialization.service.js';
 import { ValidationUtility } from '../utilities/validation/validation.utility.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.
+ * An `@Anchor` is a class decorator and must be placed on top of a class representing an anchor.
+ * - An anchor must also extend the {@link AAnchor} class.
  *
  * @example
  * ```ts
- * @Anchor('my-package')
- * export class MyAnchor extends AAnchor { ... }
+ * @Anchor('@example')
+ * export class MyAnchor extends AAnchor<MyAnchorSchema, MyModel> { ... }
  * ```
+ *
  * @group Decorators
+ *
+ * @param packageName - The name of the package under which the anchor is registered.
+ * Selecting a unique package name helps avoid collisions between same anchor class names across different libraries.
+ * You will reuse the same package name throughout your library for different Octo components you create.
+ *
  * @returns The decorated class.
- * @see Definition of [Anchors](/docs/fundamentals/overlays).
+ *
+ * @see Definition of [Anchors](/docs/fundamentals/anchors).
  */
 export function Anchor(packageName) {
     const container = Container.getInstance();

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,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AAElF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CAAC,WAAmB;IACxC,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IAE1C,OAAO,UAAU,WAAgB;QAC/B,IAAI,CAAC,iBAAiB,CAAC,aAAa,CAAC,WAAW,EAAE,2BAA2B,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CAAC,yBAAyB,WAAW,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,CAAC,WAAW,CAAC,SAAS,YAAY,OAAO,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,UAAU,WAAW,CAAC,IAAI,kCAAkC,CAAC,CAAC;QAChF,CAAC;QAED,WAAW,CAAC,YAAY,GAAG,WAAW,CAAC;QAEvC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC,IAAI,CAAC,CAAC,yBAAyB,EAAE,EAAE;YAC1F,yBAAyB,CAAC,aAAa,CAAC,GAAG,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC,CAAC;QAC7F,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"anchor.decorator.js","sourceRoot":"","sources":["../../src/decorators/anchor.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AAElF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CAAC,WAAmB;IACxC,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IAE1C,OAAO,UAAU,WAAgB;QAC/B,IAAI,CAAC,iBAAiB,CAAC,aAAa,CAAC,WAAW,EAAE,2BAA2B,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CAAC,yBAAyB,WAAW,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,CAAC,WAAW,CAAC,SAAS,YAAY,OAAO,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,UAAU,WAAW,CAAC,IAAI,kCAAkC,CAAC,CAAC;QAChF,CAAC;QAED,WAAW,CAAC,YAAY,GAAG,WAAW,CAAC;QAEvC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC,IAAI,CAAC,CAAC,yBAAyB,EAAE,EAAE;YAC1F,yBAAyB,CAAC,aAAa,CAAC,GAAG,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC,CAAC;QAC7F,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/enable-hook.decorator.d.ts

@@ -16,7 +16,7 @@ type Hook = 'CommitHook';
  *
  * @returns The decorated method.
  *
- * @see Definition of [Hooks](/docs/fundamentals/modules#hooks).
+ * @see Definition of [Hooks](/docs/techniques/hooks).
  */
 export declare function EnableHook(hook: Hook): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export {};