@quadnix/octo 0.0.30 → 0.2.0

package/dist/decorators/module.decorator.js

@@ -3,22 +3,28 @@ import { AModule } from '../modules/module.abstract.js';
 import { ModuleContainer } from '../modules/module.container.js';
 import { ValidationUtility } from '../utilities/validation/validation.utility.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.
- * - The {@link IModule.onInit} method is called to initialize the module,
- * and is where you will *define* your infrastructure.
+ * A `@Module` is a class decorator and must be placed on top of a class representing a module.
+ * - A module must also extend the {@link AModule} class.
+ * - For type safety, the type of module being decorated is passed to the decorator.
+ *
+ * Decorating a class registers it with Octo, which is what makes the module loadable by name
+ * with {@link Octo.loadModule}.
  *
  * @example
  * ```ts
- * @Module<MyInputInterface, OutputModel>('my-package', {})
- * export class MyModule implements IModule<Region> {
- *   constructor(inputs: IMyInputs) { ... }
- *
- *   async onInit(): Promise<Region> { ... }
- * }
+ * @Module<MyModule>('@example', MyModuleSchema)
+ * export class MyModule extends AModule<MyModuleSchema, MyRegion> { ... }
  * ```
+ *
  * @group Decorators
+ *
+ * @param packageName - The name of the package under which the module is registered.
+ * Selecting a unique package name helps avoid collisions between same module class names across different libraries.
+ * You will reuse the same package name throughout your library for different Octo components you create.
+ * @param schema - The schema of the module, describing the inputs it accepts.
+ *
  * @returns The decorated class.
+ *
  * @see Definition of [Modules](/docs/fundamentals/modules).
  */
 export function Module(packageName, schema) {

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

@@ -1 +1 @@
-{"version":3,"file":"module.decorator.js","sourceRoot":"","sources":["../../src/decorators/module.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AAElF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,MAAM,CAAI,WAAmB,EAAE,MAAsC;IACnF,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,cAAc,GAAG,WAAW,CAAC;QACzC,WAAW,CAAC,aAAa,GAAG,MAAM,CAAC;QAEnC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE;YACtE,eAAe,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"module.decorator.js","sourceRoot":"","sources":["../../src/decorators/module.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,MAAM,CAAI,WAAmB,EAAE,MAAsC;IACnF,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,cAAc,GAAG,WAAW,CAAC;QACzC,WAAW,CAAC,aAAa,GAAG,MAAM,CAAC;QAEnC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE;YACtE,eAAe,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}

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

@@ -1,8 +1,13 @@
-import type { Constructable } from '../app.type.js';
+import type { AbstractConstructable } from '../app.type.js';
 import type { Event } from '../events/index.js';
 /**
  * An `@OnEvent` is a method decorator to listen to an event.
  *
+ * Octo narrates everything it does as {@link Event}s. Subscribing is how you add logging, reporting,
+ * or notifications without changing the framework. A handler receives every event that is an instance
+ * of the given type, so listening to a base class such as {@link TransactionEvent} catches all of its
+ * subclasses.
+ *
  * @example
  * ```ts
  * // Async handler.
@@ -17,4 +22,4 @@ import type { Event } from '../events/index.js';
  * @param ofType The type of event being listened to.
  * @returns The decorated method.
  */
-export declare function OnEvent(ofType: Constructable<Event<unknown>>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function OnEvent(ofType: AbstractConstructable<Event<unknown>>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;

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

@@ -2,6 +2,11 @@ import { EventService } from '../services/event/event.service.js';
 /**
  * An `@OnEvent` is a method decorator to listen to an event.
  *
+ * Octo narrates everything it does as {@link Event}s. Subscribing is how you add logging, reporting,
+ * or notifications without changing the framework. A handler receives every event that is an instance
+ * of the given type, so listening to a base class such as {@link TransactionEvent} catches all of its
+ * subclasses.
+ *
  * @example
  * ```ts
  * // Async handler.

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

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

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

@@ -1,4 +1,11 @@
 import { type Constructable, type ResourceSchema, type UnknownResource } from '../app.type.js';
+/**
+ * Every dot path through `T` that ends at a string, with `[]` after a key holding an array. Below a key
+ * typed `unknown` any path is accepted.
+ */
+type NamePath<T, Depth extends unknown[] = []> = Depth['length'] extends 6 ? never : {
+    [K in keyof T & string]-?: unknown extends T[K] ? K | `${K}.${string}` | `${K}[]` | `${K}[].${string}` : NonNullable<T[K]> extends readonly (infer E)[] ? (NonNullable<E> extends string ? `${K}[]` : never) | (NonNullable<E> extends object ? `${K}[].${NamePath<NonNullable<E>, [...Depth, unknown]>}` : never) : NonNullable<T[K]> extends string ? K : NonNullable<T[K]> extends object ? `${K}.${NamePath<NonNullable<T[K]>, [...Depth, unknown]>}` : never;
+}[keyof T & string];
 /**
  * A `@Resource` is a class decorator and must be placed on top of a class representing a resource.
  * - A resource must also extend the {@link AResource} class.
@@ -10,6 +17,30 @@ import { type Constructable, type ResourceSchema, type UnknownResource } from '.
  * export class MyResource extends AResource<MyResourceSchema, MyResource> { ... }
  * ```
  *
+ * A resource whose properties hold a name the cloud requires unique declares it in `options.uniqueProperties`, and
+ * generate refuses two values of `path` that share the values of `within`, whether they come from two
+ * resources of the class or from one.
+ *
+ * @example
+ * ```ts
+ * @Resource<MyTable>('@example', 'my-table', MyTableSchema, {
+ *   uniqueProperties: [
+ *     { path: 'tableName', within: ['accountId', 'regionId'] },
+ *     { path: 'indexes[].name', within: ['accountId', 'regionId'] },
+ *   ],
+ * })
+ * export class MyTable extends AResource<MyTableSchema, MyTable> { ... }
+ * ```
+ *
+ * A resource holding data octo cannot put back from its inputs - a table's rows, a filesystem's files -
+ * sets `options.destroyLosesData`, and every destroy terraform plans of it is reported as losing data.
+ *
+ * @example
+ * ```ts
+ * @Resource<MyTable>('@example', 'my-table', MyTableSchema, { destroyLosesData: true })
+ * export class MyTable extends AResource<MyTableSchema, MyTable> { ... }
+ * ```
+ *
  * @group Decorators
  *
  * @param packageName - The name of the package under which the resource is registered.
@@ -17,9 +48,27 @@ import { type Constructable, type ResourceSchema, type UnknownResource } from '.
  * You will reuse the same package name throughout your library for different Octo components you create.
  * @param resourceName - a string that uniquely represents the name of the resource.
  * @param schema - The schema of the resource.
+ * @param options - Optional settings of the resource.
+ * `destroyLosesData` marks the resource as holding data that is lost when it is destroyed. Validate,
+ * and apply's check for destroys, add a message to each destroy of it, whatever the cause.
+ *
+ * `uniqueProperties` lists the names the cloud requires unique, one entry per name.
+ * - `path` is a dot path through the resource's properties, with `[]` after a key holding an array.
+ *   A resource with no value at `path` is not checked.
+ * - `within` names the properties whose values form the name's domain. A resource missing one is refused.
+ *   An empty `within` makes the name unique across the app.
+ *
+ * Only resources of one class are compared with each other, and a class declaring no names is not checked.
  *
  * @returns The decorated class.
  *
  * @see Definition of [Resources](/docs/fundamentals/resources).
  */
-export declare function Resource<T extends UnknownResource>(packageName: string, resourceName: string, schema: Constructable<ResourceSchema<T>>): (constructor: any) => void;
+export declare function Resource<T extends UnknownResource>(packageName: string, resourceName: string, schema: Constructable<ResourceSchema<T>>, { destroyLosesData, uniqueProperties, }?: {
+    destroyLosesData?: boolean;
+    uniqueProperties?: {
+        path: NamePath<ResourceSchema<T>['properties']>;
+        within: (keyof ResourceSchema<T>['properties'] & string)[];
+    }[];
+}): (constructor: any) => void;
+export {};

package/dist/decorators/resource.decorator.js

@@ -14,6 +14,30 @@ import { ValidationUtility } from '../utilities/validation/validation.utility.js
  * export class MyResource extends AResource<MyResourceSchema, MyResource> { ... }
  * ```
  *
+ * A resource whose properties hold a name the cloud requires unique declares it in `options.uniqueProperties`, and
+ * generate refuses two values of `path` that share the values of `within`, whether they come from two
+ * resources of the class or from one.
+ *
+ * @example
+ * ```ts
+ * @Resource<MyTable>('@example', 'my-table', MyTableSchema, {
+ *   uniqueProperties: [
+ *     { path: 'tableName', within: ['accountId', 'regionId'] },
+ *     { path: 'indexes[].name', within: ['accountId', 'regionId'] },
+ *   ],
+ * })
+ * export class MyTable extends AResource<MyTableSchema, MyTable> { ... }
+ * ```
+ *
+ * A resource holding data octo cannot put back from its inputs - a table's rows, a filesystem's files -
+ * sets `options.destroyLosesData`, and every destroy terraform plans of it is reported as losing data.
+ *
+ * @example
+ * ```ts
+ * @Resource<MyTable>('@example', 'my-table', MyTableSchema, { destroyLosesData: true })
+ * export class MyTable extends AResource<MyTableSchema, MyTable> { ... }
+ * ```
+ *
  * @group Decorators
  *
  * @param packageName - The name of the package under which the resource is registered.
@@ -21,12 +45,23 @@ import { ValidationUtility } from '../utilities/validation/validation.utility.js
  * You will reuse the same package name throughout your library for different Octo components you create.
  * @param resourceName - a string that uniquely represents the name of the resource.
  * @param schema - The schema of the resource.
+ * @param options - Optional settings of the resource.
+ * `destroyLosesData` marks the resource as holding data that is lost when it is destroyed. Validate,
+ * and apply's check for destroys, add a message to each destroy of it, whatever the cause.
+ *
+ * `uniqueProperties` lists the names the cloud requires unique, one entry per name.
+ * - `path` is a dot path through the resource's properties, with `[]` after a key holding an array.
+ *   A resource with no value at `path` is not checked.
+ * - `within` names the properties whose values form the name's domain. A resource missing one is refused.
+ *   An empty `within` makes the name unique across the app.
+ *
+ * Only resources of one class are compared with each other, and a class declaring no names is not checked.
  *
  * @returns The decorated class.
  *
  * @see Definition of [Resources](/docs/fundamentals/resources).
  */
-export function Resource(packageName, resourceName, schema) {
+export function Resource(packageName, resourceName, schema, { destroyLosesData = false, uniqueProperties = [], } = {}) {
     const container = Container.getInstance();
     return function (constructor) {
         if (!ValidationUtility.validateRegex(packageName, /^[@A-Za-z][\w-]+[A-Za-z]$/)) {
@@ -38,10 +73,12 @@ export function Resource(packageName, resourceName, schema) {
         if (!(constructor.prototype instanceof AResource)) {
             throw new Error(`Class "${constructor.name}" must extend the AResource class!`);
         }
+        constructor.DESTROY_LOSES_DATA = destroyLosesData;
         constructor.NODE_NAME = resourceName;
         constructor.NODE_PACKAGE = packageName;
         constructor.NODE_SCHEMA = schema;
         constructor.NODE_TYPE = NodeType.RESOURCE;
+        constructor.UNIQUE_PROPERTIES = uniqueProperties.map(({ path, within }) => ({ path, within: [...within] }));
         const promise = container.get(ResourceSerializationService).then((resourceSerializationService) => {
             resourceSerializationService.registerClass(`${packageName}/${constructor.name}`, constructor);
         });

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

@@ -1 +1 @@
-{"version":3,"file":"resource.decorator.js","sourceRoot":"","sources":["../../src/decorators/resource.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,QAAQ,EAA6C,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,QAAQ,CACtB,WAAmB,EACnB,YAAoB,EACpB,MAAwC;IAExC,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,iBAAiB,CAAC,aAAa,CAAC,YAAY,EAAE,0BAA0B,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CAAC,0BAA0B,YAAY,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,CAAC,WAAW,CAAC,SAAS,YAAY,SAAS,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,UAAU,WAAW,CAAC,IAAI,oCAAoC,CAAC,CAAC;QAClF,CAAC;QAED,WAAW,CAAC,SAAS,GAAG,YAAY,CAAC;QACrC,WAAW,CAAC,YAAY,GAAG,WAAW,CAAC;QACvC,WAAW,CAAC,WAAW,GAAG,MAAM,CAAC;QACjC,WAAW,CAAC,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAE1C,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,IAAI,CAAC,CAAC,4BAA4B,EAAE,EAAE;YAChG,4BAA4B,CAAC,aAAa,CAAC,GAAG,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC,CAAC;QAChG,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"resource.decorator.js","sourceRoot":"","sources":["../../src/decorators/resource.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,QAAQ,EAA6C,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AAsBlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,UAAU,QAAQ,CACtB,WAAmB,EACnB,YAAoB,EACpB,MAAwC,EACxC,EACE,gBAAgB,GAAG,KAAK,EACxB,gBAAgB,GAAG,EAAE,MAOnB,EAAE;IAEN,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,iBAAiB,CAAC,aAAa,CAAC,YAAY,EAAE,0BAA0B,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CAAC,0BAA0B,YAAY,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,CAAC,WAAW,CAAC,SAAS,YAAY,SAAS,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,UAAU,WAAW,CAAC,IAAI,oCAAoC,CAAC,CAAC;QAClF,CAAC;QAED,WAAW,CAAC,kBAAkB,GAAG,gBAAgB,CAAC;QAClD,WAAW,CAAC,SAAS,GAAG,YAAY,CAAC;QACrC,WAAW,CAAC,YAAY,GAAG,WAAW,CAAC;QACvC,WAAW,CAAC,WAAW,GAAG,MAAM,CAAC;QACjC,WAAW,CAAC,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAC1C,WAAW,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QAE5G,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,IAAI,CAAC,CAAC,4BAA4B,EAAE,EAAE;YAChG,4BAA4B,CAAC,aAAa,CAAC,GAAG,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC,CAAC;QAChG,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}

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

@@ -9,9 +9,23 @@ type ValidationOptions<T> = {
  * A `@Validate` is a property decorator to validate a property.
  * It is typically used in {@link Schema} to validate schema properties.
  *
+ * Validation runs on assignment, and a failure throws a {@link ValidationTransactionError}.
+ * Declaring constraints here is what lets a module reject bad inputs before any infrastructure is touched.
+ *
+ * @example
+ * ```ts
+ * @Validate({ options: { maxLength: 65535, minLength: 1 } })
+ * containerPort = Schema<number>();
+ * ```
+ *
  * @group Decorators
  *
- * @see Techniques for [Validation](/docs/techniques/validation).
+ * @param validators One constraint, or an array of them. Each constraint carries the `options` to apply,
+ * and an optional `destruct` to reduce the property into the list of values the constraints run against.
+ * Without `destruct`, the property value is validated as-is.
+ * @param transform Runs before validation, and **replaces** the stored value with what it returns.
+ *
+ * @see Techniques for [Validation](/docs/techniques/validation) for the full list of constraints.
  */
 export declare function Validate<T>(validators: ValidationOptions<T> | ValidationOptions<T>[], transform?: (value: any) => any): (target: any, propertyKey: string) => void;
 export {};

package/dist/decorators/validate.decorator.js

@@ -4,9 +4,23 @@ import { ValidationService } from '../services/validation/validation.service.js'
  * A `@Validate` is a property decorator to validate a property.
  * It is typically used in {@link Schema} to validate schema properties.
  *
+ * Validation runs on assignment, and a failure throws a {@link ValidationTransactionError}.
+ * Declaring constraints here is what lets a module reject bad inputs before any infrastructure is touched.
+ *
+ * @example
+ * ```ts
+ * @Validate({ options: { maxLength: 65535, minLength: 1 } })
+ * containerPort = Schema<number>();
+ * ```
+ *
  * @group Decorators
  *
- * @see Techniques for [Validation](/docs/techniques/validation).
+ * @param validators One constraint, or an array of them. Each constraint carries the `options` to apply,
+ * and an optional `destruct` to reduce the property into the list of values the constraints run against.
+ * Without `destruct`, the property value is validated as-is.
+ * @param transform Runs before validation, and **replaces** the stored value with what it returns.
+ *
+ * @see Techniques for [Validation](/docs/techniques/validation) for the full list of constraints.
  */
 export function Validate(validators, transform) {
     return function (target, propertyKey) {

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

@@ -1 +1 @@
-{"version":3,"file":"validate.decorator.js","sourceRoot":"","sources":["../../src/decorators/validate.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAOjF;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CACtB,UAAyD,EACzD,SAA+B;IAE/B,OAAO,UAAU,MAAW,EAAE,WAAmB;QAC/C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;QAExB,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE;YACzC,UAAU,EAAE,IAAI;YAChB,GAAG,EAAE;gBACH,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;YACD,GAAG,EAAE,UAAU,QAAa;gBAC1B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,IAAI,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;oBACzB,OAAO;gBACT,CAAC;gBAED,IAAI,SAAS,EAAE,CAAC;oBACd,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;gBACjC,CAAC;gBAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC/B,UAAU,GAAG,CAAC,UAAU,CAAC,CAAC;gBAC5B,CAAC;gBAED,MAAM,iBAAiB,GAAG,IAAI,iBAAiB,EAAE,CAAC;gBAClD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;oBACnC,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;wBACnE,iBAAiB,CAAC,UAAU,CAC1B,IAAsB,EACtB,UAAU,EACV,MAAM,EACN,WAAW,EACX,QAAQ,EACR,SAAS,CAAC,QAAQ,CACnB,CAAC;oBACJ,CAAC;gBACH,CAAC;gBAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,EAAE,CAAC;gBAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;oBACjB,MAAM,IAAI,0BAA0B,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;gBACpE,CAAC;gBAED,IAAI,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;YAC1B,CAAC;SACF,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"validate.decorator.js","sourceRoot":"","sources":["../../src/decorators/validate.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAOjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,QAAQ,CACtB,UAAyD,EACzD,SAA+B;IAE/B,OAAO,UAAU,MAAW,EAAE,WAAmB;QAC/C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;QAExB,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE;YACzC,UAAU,EAAE,IAAI;YAChB,GAAG,EAAE;gBACH,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;YACD,GAAG,EAAE,UAAU,QAAa;gBAC1B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,IAAI,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;oBACzB,OAAO;gBACT,CAAC;gBAED,IAAI,SAAS,EAAE,CAAC;oBACd,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;gBACjC,CAAC;gBAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC/B,UAAU,GAAG,CAAC,UAAU,CAAC,CAAC;gBAC5B,CAAC;gBAED,MAAM,iBAAiB,GAAG,IAAI,iBAAiB,EAAE,CAAC;gBAClD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;oBACnC,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;wBACnE,iBAAiB,CAAC,UAAU,CAC1B,IAAsB,EACtB,UAAU,EACV,MAAM,EACN,WAAW,EACX,QAAQ,EACR,SAAS,CAAC,QAAQ,CACnB,CAAC;oBACJ,CAAC;gBACH,CAAC;gBAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,EAAE,CAAC;gBAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;oBACjB,MAAM,IAAI,0BAA0B,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;gBACpE,CAAC;gBAED,IAAI,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;YAC1B,CAAC;SACF,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

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

@@ -1,20 +1,38 @@
 import type { Constructable } from '../app.type.js';
 /**
+ * Parent error class for all {@link Container} errors.
+ *
  * @group Errors/Container
  */
 export declare class ContainerError extends Error {
     readonly type: string;
+    /**
+     * @param message The error message.
+     * @param type The class the container was resolving or registering.
+     */
     constructor(message: string, type: Constructable<unknown> | string);
 }
 /**
+ * Thrown when a factory is registered for a class that already has one with the same metadata.
+ *
  * @group Errors/Container
  */
 export declare class ContainerRegistrationError extends ContainerError {
+    /**
+     * @param message The error message.
+     * @param type The class whose factory was being registered.
+     */
     constructor(message: string, type: Constructable<unknown> | string);
 }
 /**
+ * Thrown when a class is requested and no factory registers for it before the timeout - see {@link Container.setFactoryTimeout}.
+ *
  * @group Errors/Container
  */
 export declare class ContainerResolutionError extends ContainerError {
+    /**
+     * @param message The error message.
+     * @param type The class that could not be resolved.
+     */
     constructor(message: string, type: Constructable<unknown> | string);
 }

package/dist/errors/container.error.js

@@ -1,7 +1,13 @@
 /**
+ * Parent error class for all {@link Container} errors.
+ *
  * @group Errors/Container
  */
 export class ContainerError extends Error {
+    /**
+     * @param message The error message.
+     * @param type The class the container was resolving or registering.
+     */
     constructor(message, type) {
         super(message);
         this.type = typeof type === 'string' ? type : type.name;
@@ -9,18 +15,30 @@ export class ContainerError extends Error {
     }
 }
 /**
+ * Thrown when a factory is registered for a class that already has one with the same metadata.
+ *
  * @group Errors/Container
  */
 export class ContainerRegistrationError extends ContainerError {
+    /**
+     * @param message The error message.
+     * @param type The class whose factory was being registered.
+     */
     constructor(message, type) {
         super(message, type);
         Object.setPrototypeOf(this, ContainerRegistrationError.prototype);
     }
 }
 /**
+ * Thrown when a class is requested and no factory registers for it before the timeout - see {@link Container.setFactoryTimeout}.
+ *
  * @group Errors/Container
  */
 export class ContainerResolutionError extends ContainerError {
+    /**
+     * @param message The error message.
+     * @param type The class that could not be resolved.
+     */
     constructor(message, type) {
         super(message, type);
         Object.setPrototypeOf(this, ContainerResolutionError.prototype);

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

@@ -1 +1 @@
-{"version":3,"file":"container.error.js","sourceRoot":"","sources":["../../src/errors/container.error.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGvC,YAAY,OAAe,EAAE,IAAqC;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAExD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,OAAe,EAAE,IAAqC;QAChE,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAErB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,0BAA0B,CAAC,SAAS,CAAC,CAAC;IACpE,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,wBAAyB,SAAQ,cAAc;IAC1D,YAAY,OAAe,EAAE,IAAqC;QAChE,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAErB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,wBAAwB,CAAC,SAAS,CAAC,CAAC;IAClE,CAAC;CACF"}
+{"version":3,"file":"container.error.js","sourceRoot":"","sources":["../../src/errors/container.error.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGvC;;;OAGG;IACH,YAAY,OAAe,EAAE,IAAqC;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAExD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D;;;OAGG;IACH,YAAY,OAAe,EAAE,IAAqC;QAChE,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAErB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,0BAA0B,CAAC,SAAS,CAAC,CAAC;IACpE,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,wBAAyB,SAAQ,cAAc;IAC1D;;;OAGG;IACH,YAAY,OAAe,EAAE,IAAqC;QAChE,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAErB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,wBAAwB,CAAC,SAAS,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/errors/index.d.ts

@@ -3,4 +3,5 @@ export * from './input.error.js';
 export * from './module.error.js';
 export * from './node.error.js';
 export * from './schema.error.js';
+export * from './terraform.error.js';
 export * from './transaction.error.js';

package/dist/errors/index.js

@@ -3,5 +3,6 @@ export * from './input.error.js';
 export * from './module.error.js';
 export * from './node.error.js';
 export * from './schema.error.js';
+export * from './terraform.error.js';
 export * from './transaction.error.js';
 //# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

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

@@ -1,7 +1,13 @@
 /**
+ * Thrown by a module that cannot satisfy its inputs. Raise it from {@link AModule.onInit} to fail a run before anything is built.
+ *
  * @group Errors/Module
  */
 export declare class ModuleError extends Error {
     readonly module: string;
+    /**
+     * @param message The error message.
+     * @param moduleName The module that raised it.
+     */
     constructor(message: string, moduleName: string);
 }

package/dist/errors/module.error.js

@@ -1,7 +1,13 @@
 /**
+ * Thrown by a module that cannot satisfy its inputs. Raise it from {@link AModule.onInit} to fail a run before anything is built.
+ *
  * @group Errors/Module
  */
 export class ModuleError extends Error {
+    /**
+     * @param message The error message.
+     * @param moduleName The module that raised it.
+     */
     constructor(message, moduleName) {
         super(message);
         this.module = moduleName;

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

@@ -1 +1 @@
-{"version":3,"file":"module.error.js","sourceRoot":"","sources":["../../src/errors/module.error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGpC,YAAY,OAAe,EAAE,UAAkB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC;QAEzB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;CACF"}
+{"version":3,"file":"module.error.js","sourceRoot":"","sources":["../../src/errors/module.error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGpC;;;OAGG;IACH,YAAY,OAAe,EAAE,UAAkB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC;QAEzB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;CACF"}

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

@@ -3,61 +3,117 @@ import type { Dependency, IDependency } from '../functions/dependency/dependency
 import type { Diff } from '../functions/diff/diff.js';
 import type { AResource } from '../resources/resource.abstract.js';
 /**
+ * Thrown when a {@link Dependency} is given a second relationship, or asked to drop a behavior it does not have.
+ *
  * @group Errors/Node
  */
 export declare class DependencyError extends Error {
     readonly dependency: IDependency;
+    /**
+     * @param message The error message.
+     * @param dependency The dependency that was being changed.
+     */
     constructor(message: string, dependency: Dependency);
 }
 /**
+ * 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 declare class NodeUnsynthError extends Error {
     readonly subject: string;
+    /**
+     * @param message The error message.
+     * @param subject The node, named by its ID, that could not be deserialized.
+     */
     constructor(message: string, subject: string);
 }
 /**
+ * Parent error class for all node errors.
+ *
  * @group Errors/Node
  */
 export declare class NodeError extends Error {
     readonly node: string;
+    /**
+     * @param message The error message.
+     * @param node The node the error is about.
+     */
     constructor(message: string, node: typeof AResource | UnknownNode);
 }
 /**
+ * Thrown when a node's context cannot be derived, which usually means it was never attached to a parent.
+ *
  * @group Errors/Node
  */
 export declare class ContextNodeError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param node The node whose context could not be derived.
+     */
     constructor(message: string, node: UnknownNode);
 }
 /**
+ * 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 declare class ModelError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param model The model the error is about.
+     */
     constructor(message: string, model: UnknownModel);
 }
 /**
+ * Thrown when an overlay is used in a way its own rules forbid.
+ *
  * @group Errors/Node
  */
 export declare class OverlayError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param overlay The overlay the error is about.
+     */
     constructor(message: string, overlay: UnknownOverlay);
 }
 /**
+ * Thrown when a resource is used in a way its own rules forbid, e.g. an invalid resource ID.
+ *
  * @group Errors/Node
  */
 export declare class ResourceError extends NodeError {
+    /**
+     * @param message The error message.
+     * @param resource The resource the error is about.
+     */
     constructor(message: string, resource: typeof AResource | UnknownResource);
 }
 /**
+ * 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 declare class DiffInverseResourceError extends ResourceError {
     readonly diff: ReturnType<Diff['toJSON']>;
+    /**
+     * @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: string, resource: UnknownResource, diff: Diff);
 }
 /**
+ * Thrown when a resource is removed while other resources still depend on it. Carries the children that blocked it.
+ *
  * @group Errors/Node
  */
 export declare class RemoveResourceError extends ResourceError {
     readonly childrenResources: string[];
+    /**
+     * @param message The error message.
+     * @param resource The resource that could not be removed.
+     * @param childrenResources The resources still depending on it.
+     */
     constructor(message: string, resource: UnknownResource, childrenResources: UnknownResource[]);
 }