@quadnix/octo 0.0.30 → 0.2.0

package/dist/errors/node.error.js

@@ -1,7 +1,13 @@
 /**
+ * Thrown when a {@link Dependency} is given a second relationship, or asked to drop a behavior it does not have.
+ *
  * @group Errors/Node
  */
 export class DependencyError extends Error {
+    /**
+     * @param message The error message.
+     * @param dependency The dependency that was being changed.
+     */
     constructor(message, dependency) {
         super(message);
         this.dependency = dependency.synth();
@@ -9,9 +15,15 @@ export class DependencyError extends Error {
     }
 }
 /**
+ * Thrown when state cannot be deserialized back into a node, e.g. because it references something no longer in the graph.
+ *
  * @group Errors/Node
  */
 export class NodeUnsynthError extends Error {
+    /**
+     * @param message The error message.
+     * @param subject The node, named by its ID, that could not be deserialized.
+     */
     constructor(message, subject) {
         super(message);
         this.subject = subject;
@@ -19,9 +31,15 @@ export class NodeUnsynthError extends Error {
     }
 }
 /**
+ * Parent error class for all node errors.
+ *
  * @group Errors/Node
  */
 export class NodeError extends Error {
+    /**
+     * @param message The error message.
+     * @param node The node the error is about.
+     */
     constructor(message, node) {
         super(message);
         this.node = node.NODE_NAME || node.constructor.NODE_NAME;
@@ -29,45 +47,76 @@ export class NodeError extends Error {
     }
 }
 /**
+ * Thrown when a node's context cannot be derived, which usually means it was never attached to a parent.
+ *
  * @group Errors/Node
  */
 export class ContextNodeError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param node The node whose context could not be derived.
+     */
     constructor(message, node) {
         super(message, node);
         Object.setPrototypeOf(this, ContextNodeError.prototype);
     }
 }
 /**
+ * Thrown when a model is used in a way its own rules forbid, e.g. adding a child that already exists.
+ *
  * @group Errors/Node
  */
 export class ModelError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param model The model the error is about.
+     */
     constructor(message, model) {
         super(message, model);
         Object.setPrototypeOf(this, ModelError.prototype);
     }
 }
 /**
+ * Thrown when an overlay is used in a way its own rules forbid.
+ *
  * @group Errors/Node
  */
 export class OverlayError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param overlay The overlay the error is about.
+     */
     constructor(message, overlay) {
         super(message, overlay);
         Object.setPrototypeOf(this, OverlayError.prototype);
     }
 }
 /**
+ * Thrown when a resource is used in a way its own rules forbid, e.g. an invalid resource ID.
+ *
  * @group Errors/Node
  */
 export class ResourceError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param resource The resource the error is about.
+     */
     constructor(message, resource) {
         super(message, resource);
         Object.setPrototypeOf(this, ResourceError.prototype);
     }
 }
 /**
+ * Thrown when a diff cannot be applied back onto a resource, because its field or action is not one the resource knows how to handle.
+ *
  * @group Errors/Node
  */
 export class DiffInverseResourceError extends ResourceError {
+    /**
+     * @param message The error message.
+     * @param resource The resource the diff was being applied to.
+     * @param diff The diff that could not be applied.
+     */
     constructor(message, resource, diff) {
         super(message, resource);
         this.diff = diff.toJSON();
@@ -75,9 +124,16 @@ export class DiffInverseResourceError extends ResourceError {
     }
 }
 /**
+ * Thrown when a resource is removed while other resources still depend on it. Carries the children that blocked it.
+ *
  * @group Errors/Node
  */
 export class RemoveResourceError extends ResourceError {
+    /**
+     * @param message The error message.
+     * @param resource The resource that could not be removed.
+     * @param childrenResources The resources still depending on it.
+     */
     constructor(message, resource, childrenResources) {
         super(message, resource);
         this.childrenResources = childrenResources.map((r) => r.constructor.NODE_NAME);

package/dist/errors/node.error.js.map

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

package/dist/errors/schema.error.d.ts

@@ -1,7 +1,20 @@
 /**
+ * Thrown when a value does not satisfy the schema it is being read as - a property missing, or one that cannot be resolved.
+ *
  * @group Errors/Schema
  */
 export declare class SchemaError extends Error {
     readonly schemaClassName: string;
-    constructor(message: string, schemaClassName: string);
+    /**
+     * What a validator threw underneath, where this error is wrapping one. Carried as a property of
+     * its own rather than as the `Error` cause: without it a nested property's failure reads only as
+     * the name of the top-level input it arrived under, and which value failed is the whole question.
+     */
+    readonly validationError?: unknown;
+    /**
+     * @param message The error message.
+     * @param schemaClassName The schema the value was being read as.
+     * @param validationError What a validator threw underneath, where there is one.
+     */
+    constructor(message: string, schemaClassName: string, validationError?: unknown);
 }

package/dist/errors/schema.error.js

@@ -1,10 +1,20 @@
 /**
+ * Thrown when a value does not satisfy the schema it is being read as - a property missing, or one that cannot be resolved.
+ *
  * @group Errors/Schema
  */
 export class SchemaError extends Error {
-    constructor(message, schemaClassName) {
+    /**
+     * @param message The error message.
+     * @param schemaClassName The schema the value was being read as.
+     * @param validationError What a validator threw underneath, where there is one.
+     */
+    constructor(message, schemaClassName, validationError) {
         super(message);
         this.schemaClassName = schemaClassName;
+        if (validationError !== undefined) {
+            this.validationError = validationError;
+        }
         Object.setPrototypeOf(this, SchemaError.prototype);
     }
 }

package/dist/errors/schema.error.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.error.js","sourceRoot":"","sources":["../../src/errors/schema.error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGpC,YAAY,OAAe,EAAE,eAAuB;QAClD,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QAEvC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;CACF"}
+{"version":3,"file":"schema.error.js","sourceRoot":"","sources":["../../src/errors/schema.error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAUpC;;;;OAIG;IACH,YAAY,OAAe,EAAE,eAAuB,EAAE,eAAyB;QAC7E,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACzC,CAAC;QAED,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;CACF"}

package/dist/errors/terraform.error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Thrown when a terraform or terragrunt command exits non-zero. Carries the command's arguments, exit code,
+ * the stdout of a command asked for JSON, and the end of its stderr.
+ *
+ * @group Errors/Terraform
+ */
+export declare class TerraformCommandError extends Error {
+    readonly args: string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+    /**
+     * @param message The error message.
+     * @param args The arguments the command was invoked with.
+     * @param exitCode The command's exit code.
+     * @param stdout The command's standard output, kept only for a command asked for JSON.
+     * @param stderr The last 64 KB the command wrote to standard error.
+     */
+    constructor(message: string, args: string[], exitCode: number, stdout: string, stderr: string);
+}

package/dist/errors/terraform.error.js

@@ -0,0 +1,24 @@
+/**
+ * Thrown when a terraform or terragrunt command exits non-zero. Carries the command's arguments, exit code,
+ * the stdout of a command asked for JSON, and the end of its stderr.
+ *
+ * @group Errors/Terraform
+ */
+export class TerraformCommandError extends Error {
+    /**
+     * @param message The error message.
+     * @param args The arguments the command was invoked with.
+     * @param exitCode The command's exit code.
+     * @param stdout The command's standard output, kept only for a command asked for JSON.
+     * @param stderr The last 64 KB the command wrote to standard error.
+     */
+    constructor(message, args, exitCode, stdout, stderr) {
+        super(message);
+        this.args = args;
+        this.exitCode = exitCode;
+        this.stdout = stdout;
+        this.stderr = stderr;
+        Object.setPrototypeOf(this, TerraformCommandError.prototype);
+    }
+}
+//# sourceMappingURL=terraform.error.js.map

package/dist/errors/terraform.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terraform.error.js","sourceRoot":"","sources":["../../src/errors/terraform.error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAM9C;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,IAAc,EAAE,QAAgB,EAAE,MAAc,EAAE,MAAc;QAC3F,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/errors/transaction.error.d.ts

@@ -1,72 +1,163 @@
-import type { IUnknownModelAction, UnknownResource } from '../app.type.js';
+import type { IUnknownModelAction, ResourceSerializedSchema, UnknownResource } from '../app.type.js';
 import type { Diff } from '../functions/diff/diff.js';
 import type { ValidationService } from '../services/validation/validation.service.js';
 /**
+ * Parent error class for all transaction errors.
+ *
  * @group Errors/Transaction
  */
 export declare class TransactionError extends Error {
+    /**
+     * @param message The error message.
+     */
     constructor(message: string);
 }
 /**
+ * Thrown when the app lock is refused: another run holds it (`held`), the lock to resume is not the
+ * one held (`not-held`), the state moved since it was last refreshed (`state-moved`), or the state
+ * holds journal files of a run that was never archived (`unfinished`), named in `stateFileNames`.
+ *
+ * @group Errors/Transaction
+ */
+export declare class AppLockError extends TransactionError {
+    readonly holder?: {
+        commitId?: string;
+        context?: string;
+        lockId: string;
+        takenAt?: number;
+    };
+    readonly newestCommitId?: string;
+    readonly reason: 'held' | 'not-held' | 'state-moved' | 'unfinished';
+    readonly refreshedCommitId?: string;
+    readonly stateFileNames?: string[];
+    /**
+     * @param message The error message.
+     * @param details Why the lock was refused, and what the state provider knows about it.
+     */
+    constructor(message: string, details: {
+        holder?: AppLockError['holder'];
+        newestCommitId?: string;
+        reason: AppLockError['reason'];
+        refreshedCommitId?: string;
+        stateFileNames?: string[];
+    });
+}
+/**
+ * Thrown when a run tries to change resources that a previous run left in an unsettled state. Commit or resolve those first.
+ *
  * @group Errors/Transaction
  */
 export declare class DiffsOnDirtyResourcesTransactionError extends TransactionError {
     readonly diffs: ReturnType<Diff['toJSON']>[];
-    readonly dirtyResources: UnknownResource[];
+    readonly dirtyResources: ResourceSerializedSchema[];
+    /**
+     * @param message The error message.
+     * @param diffs The diffs the run was trying to apply.
+     * @param dirtyResources The resources left unsettled by an earlier run.
+     */
     constructor(message: string, diffs: Diff[], dirtyResources: UnknownResource[]);
 }
 /**
+ * Thrown when an action asks for an input its module never received.
+ *
  * @group Errors/Transaction
  */
 export declare class InputNotFoundTransactionError extends TransactionError {
     readonly action: string;
     readonly diff: ReturnType<Diff['toJSON']>;
     readonly key: string;
+    /**
+     * @param message The error message.
+     * @param action The action asking for the input.
+     * @param diff The diff it was handling.
+     * @param key The input key that was not found.
+     */
     constructor(message: string, action: IUnknownModelAction, diff: Diff, key: string);
 }
 /**
+ * Thrown when a model action itself throws. Carries the action and the diff it was handling.
+ *
  * @group Errors/Transaction
  */
 export declare class ModelActionExceptionTransactionError extends TransactionError {
     readonly actionClassName: string;
     readonly diff: ReturnType<Diff['toJSON']>;
+    /**
+     * @param message The error message.
+     * @param diff The diff the action was handling.
+     * @param actionClassName The action that failed.
+     */
     constructor(message: string, diff: Diff, actionClassName: string);
 }
 /**
+ * Thrown when a diff is produced that no registered action accepts - usually a missing `@Action`, or a `filter()` that is too narrow.
+ *
  * @group Errors/Transaction
  */
 export declare class NoMatchingActionFoundTransactionError extends TransactionError {
     readonly diff: ReturnType<Diff['toJSON']>;
+    /**
+     * @param message The error message.
+     * @param diff The diff no action accepted.
+     */
     constructor(message: string, diff: Diff);
 }
 /**
+ * Thrown when an overlay action itself throws. Carries the action and the diff it was handling.
+ *
  * @group Errors/Transaction
  */
 export declare class OverlayActionExceptionTransactionError extends TransactionError {
     readonly actionClassName: string;
     readonly diff: ReturnType<Diff['toJSON']>;
+    /**
+     * @param message The error message.
+     * @param diff The diff the action was handling.
+     * @param actionClassName The action that failed.
+     */
     constructor(message: string, diff: Diff, actionClassName: string);
 }
 /**
+ * Thrown when a resource action itself throws. Carries the action and the diff it was handling, and chains the original error's stack.
+ *
  * @group Errors/Transaction
  */
 export declare class ResourceActionExceptionTransactionError extends TransactionError {
     readonly actionClassName: string;
     readonly diff: ReturnType<Diff['toJSON']>;
+    /**
+     * @param message The error message.
+     * @param originalError The error the action threw, whose stack is chained onto this one.
+     * @param diff The diff it was handling.
+     * @param actionClassName The action that threw.
+     */
     constructor(message: string, originalError: Error, diff: Diff, actionClassName: string);
 }
 /**
+ * Thrown when a resource action outruns its {@link IResourceAction.actionTimeoutInMs}.
+ *
  * @group Errors/Transaction
  */
 export declare class ResourceActionTimeoutTransactionError extends TransactionError {
     readonly actionClassName: string;
     readonly diff: ReturnType<Diff['toJSON']>;
+    /**
+     * @param message The error message.
+     * @param diff The diff the action was handling.
+     * @param actionClassName The action that failed.
+     */
     constructor(message: string, diff: Diff, actionClassName: string);
 }
 /**
+ * Thrown when a value fails a {@link Validate} constraint. Carries every constraint that failed.
+ *
  * @group Errors/Transaction
  */
 export declare class ValidationTransactionError extends TransactionError {
     errors: ReturnType<ValidationService['validate']>;
+    /**
+     * @param message The error message.
+     * @param errors Every constraint that failed.
+     */
     constructor(message: string, errors: ReturnType<ValidationService['validate']>);
 }

package/dist/errors/transaction.error.js

@@ -1,16 +1,50 @@
 /**
+ * Parent error class for all transaction errors.
+ *
  * @group Errors/Transaction
  */
 export class TransactionError extends Error {
+    /**
+     * @param message The error message.
+     */
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, TransactionError.prototype);
     }
 }
 /**
+ * Thrown when the app lock is refused: another run holds it (`held`), the lock to resume is not the
+ * one held (`not-held`), the state moved since it was last refreshed (`state-moved`), or the state
+ * holds journal files of a run that was never archived (`unfinished`), named in `stateFileNames`.
+ *
+ * @group Errors/Transaction
+ */
+export class AppLockError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param details Why the lock was refused, and what the state provider knows about it.
+     */
+    constructor(message, details) {
+        super(message);
+        this.holder = details.holder;
+        this.newestCommitId = details.newestCommitId;
+        this.reason = details.reason;
+        this.refreshedCommitId = details.refreshedCommitId;
+        this.stateFileNames = details.stateFileNames;
+        Object.setPrototypeOf(this, AppLockError.prototype);
+    }
+}
+/**
+ * Thrown when a run tries to change resources that a previous run left in an unsettled state. Commit or resolve those first.
+ *
  * @group Errors/Transaction
  */
 export class DiffsOnDirtyResourcesTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param diffs The diffs the run was trying to apply.
+     * @param dirtyResources The resources left unsettled by an earlier run.
+     */
     constructor(message, diffs, dirtyResources) {
         super(message);
         this.diffs = diffs.map((d) => d.toJSON());
@@ -19,9 +53,17 @@ export class DiffsOnDirtyResourcesTransactionError extends TransactionError {
     }
 }
 /**
+ * Thrown when an action asks for an input its module never received.
+ *
  * @group Errors/Transaction
  */
 export class InputNotFoundTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param action The action asking for the input.
+     * @param diff The diff it was handling.
+     * @param key The input key that was not found.
+     */
     constructor(message, action, diff, key) {
         super(message);
         this.action = action.constructor.name;
@@ -31,9 +73,16 @@ export class InputNotFoundTransactionError extends TransactionError {
     }
 }
 /**
+ * Thrown when a model action itself throws. Carries the action and the diff it was handling.
+ *
  * @group Errors/Transaction
  */
 export class ModelActionExceptionTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param diff The diff the action was handling.
+     * @param actionClassName The action that failed.
+     */
     constructor(message, diff, actionClassName) {
         super(message);
         this.actionClassName = actionClassName;
@@ -42,9 +91,15 @@ export class ModelActionExceptionTransactionError extends TransactionError {
     }
 }
 /**
+ * Thrown when a diff is produced that no registered action accepts - usually a missing `@Action`, or a `filter()` that is too narrow.
+ *
  * @group Errors/Transaction
  */
 export class NoMatchingActionFoundTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param diff The diff no action accepted.
+     */
     constructor(message, diff) {
         super(message);
         this.diff = diff.toJSON();
@@ -52,9 +107,16 @@ export class NoMatchingActionFoundTransactionError extends TransactionError {
     }
 }
 /**
+ * Thrown when an overlay action itself throws. Carries the action and the diff it was handling.
+ *
  * @group Errors/Transaction
  */
 export class OverlayActionExceptionTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param diff The diff the action was handling.
+     * @param actionClassName The action that failed.
+     */
     constructor(message, diff, actionClassName) {
         super(message);
         this.actionClassName = actionClassName;
@@ -63,9 +125,17 @@ export class OverlayActionExceptionTransactionError extends TransactionError {
     }
 }
 /**
+ * Thrown when a resource action itself throws. Carries the action and the diff it was handling, and chains the original error's stack.
+ *
  * @group Errors/Transaction
  */
 export class ResourceActionExceptionTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param originalError The error the action threw, whose stack is chained onto this one.
+     * @param diff The diff it was handling.
+     * @param actionClassName The action that threw.
+     */
     constructor(message, originalError, diff, actionClassName) {
         super(message);
         this.actionClassName = actionClassName;
@@ -77,9 +147,16 @@ export class ResourceActionExceptionTransactionError extends TransactionError {
     }
 }
 /**
+ * Thrown when a resource action outruns its {@link IResourceAction.actionTimeoutInMs}.
+ *
  * @group Errors/Transaction
  */
 export class ResourceActionTimeoutTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param diff The diff the action was handling.
+     * @param actionClassName The action that failed.
+     */
     constructor(message, diff, actionClassName) {
         super(message);
         this.actionClassName = actionClassName;
@@ -88,9 +165,15 @@ export class ResourceActionTimeoutTransactionError extends TransactionError {
     }
 }
 /**
+ * Thrown when a value fails a {@link Validate} constraint. Carries every constraint that failed.
+ *
  * @group Errors/Transaction
  */
 export class ValidationTransactionError extends TransactionError {
+    /**
+     * @param message The error message.
+     * @param errors Every constraint that failed.
+     */
     constructor(message, errors) {
         super(message);
         this.errors = errors;

package/dist/errors/transaction.error.js.map

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

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

@@ -1,13 +1,17 @@
+import type { DiffAction } from '../functions/diff/diff.js';
 import { Event } from './event.model.js';
 /**
- * The ActionEvent class is the superclass for all events within actions.
- * This can be used to emit log events within actions.
+ * This event is emitted for each `log()` an action makes. `diff` names what the action was running
+ * for: the context of its model, overlay or resource, and the diff's action and field.
  *
  * @group Events/Action
- *
- * @returns The Event instance.
  */
 export declare class ActionEvent extends Event<{
+    diff: {
+        action: DiffAction;
+        field: string;
+        node: string;
+    };
     message: string;
     metadata: Record<string, unknown>;
 }> {

package/dist/events/action.event.js

@@ -1,11 +1,9 @@
 import { Event } from './event.model.js';
 /**
- * The ActionEvent class is the superclass for all events within actions.
- * This can be used to emit log events within actions.
+ * This event is emitted for each `log()` an action makes. `diff` names what the action was running
+ * for: the context of its model, overlay or resource, and the diff's action and field.
  *
  * @group Events/Action
- *
- * @returns The Event instance.
  */
 export class ActionEvent extends Event {
 }

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

@@ -1 +1 @@
-{"version":3,"file":"action.event.js","sourceRoot":"","sources":["../../src/events/action.event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,OAAO,WAAY,SAAQ,KAA6D;CAAG"}
+{"version":3,"file":"action.event.js","sourceRoot":"","sources":["../../src/events/action.event.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,KAI/B;CAAG"}