Stack class abstract base

User-extended IaC composition root.

User subclasses construct resources inside their own constructor and register them via add. synth() returns the in-memory SynthResult bundle (Terraform JSON map plus the generated Dart source for appExports); writeTo(outDir) persists that bundle to disk.

Coordination surface for synth and concrete providers:

  • addOutput(...) / outputs — output "<name>" { ... } blocks, and the getters of the generated <name>Outputs reader in the appExports file, which the app builds from terraform output -json (fromTerraformJson) or its environment (fromEnvironment).
  • addDartDefineOutput(...) / dartDefineOutputs — an output whose value is the --dart-define-from-file JSON a client app is built with, which the reader's fromDartDefine reads.
  • addConstant(...) / constants — static const values of the generated <name>Constants class, written to the appExports file.
  • variable<T>(...) / variables — variable "<name>" { ... } declarations, each returning the handle an argument takes. externalVariable<T>(...) / externalVariables covers names declared in a hand-written file instead.
  • addExternalBlock(...) / externalBlocks — resources, data sources and module calls a hand-written file declares, which this stack may reference without holding.
  • validate() — every SynthIssue that keeps the stack from synthesizing; synth() throws them as one SynthException.
  • addMoved(...) / moved — moved { from = ... to = ... } entries that carry existing state across a resource rename.
  • addModule(...) / modules — module "<name>" { ... } calls, whose outputs other resources read through ModuleCall.output.

Constructors

Stack({required List<StackProvider> providers, StackBackend? backend, String requiredVersion = '>= 1.11.0', AppExports? appExports, bool devMode = false})

Properties

appExports → AppExports?
The Dart file application code imports, holding the constants. null writes no file, and then addConstant throws.
final
backend → StackBackend?
The terraform { backend } the state lives in; null keeps the local default.
final
configurationAliases → List<StackProvider>
Aliases registered with addConfigurationAlias, in that order.
no setter
constants → Map<String, AppConstant<Object?>>
The constants registered with addConstant, by name, in registration order.
no setter
dartDefineOutputs → Map<String, DartDefineOutput>
The outputs registered with addDartDefineOutput, by name, in registration order. Synth emits them after outputs.
no setter
dataSources → List<Data>
no setter
devMode → bool
When true, synth-time injection flips deletion_protection to false on any registered resource whose Resource.supportsDeletionProtection is true and that did not explicitly set the field. Intended for dogfood / sample apps; production stacks leave this false (the provider default of true then applies).
final
externalBlocks → Set<String>
Read-only view of block addresses declared outside synth output. Synth accepts references to these but emits nothing for them.
no setter
externalVariables → Set<String>
Read-only view of variable names declared outside synth output. Synth accepts references to these but emits no block for them.
no setter
hashCode → int
The hash code for this object.
no setterinherited
modules → List<ModuleCall>
The module calls registered with addModule, in registration order.
no setter
moved → List<TfMoved>
The moved entries registered with addMoved, in registration order.
no setter
outputs → Map<String, TfOutput<Object?>>
The outputs registered with addOutput, by name, in registration order.
no setter
providers → List<StackProvider>
The configurations passed to the constructor, then those registered with addProvider, addConfigurationAlias and addExternalProvider, in that order.
no setter
requiredVersion → String
Terraform version constraint for terraform { required_version }. Defaults to '>= 1.11.0': Terraform 1.11 is the first with write-only arguments.
final
resources → List<Resource>
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
variables → Map<String, TfVariable>
Read-only map of declared Terraform variables, keyed by variable name. Insertion order is preserved for deterministic output.
no setter

Methods

add<T extends Resource>(T block) → T
Register a resource or data source. Returns the same instance for fluent assignment.
addConfigurationAlias<P extends StackProvider>(P provider) → P
Registers provider as a configuration_aliases entry this module expects its caller to pass, not a provider block this module owns.
addConstant<T>(String name, AppConstant<T> constant) → void
Declare static const <T> <name> in the generated <name>Constants class of the appExports file.
addDartDefineOutput({String name = 'dart_defines', Iterable<String>? only, String? description}) → void
Declare output "<name>" { value = { ORDERS_TOPIC_ID = ..., ... } }: the environment outputEnvironment would pass, as the file a client app is built with.
addExternalBlock(String address) → void
Accept references to a block declared in a hand-written file beside the generated main.tf.json — google_pubsub_topic.legacy, data.google_project.current or module.network — without emitting it.
addExternalProvider<P extends StackProvider>(P provider) → P
Registers provider so a resource can select it, without emitting a provider block.
addModule<T extends ModuleCall>(T call) → T
Register a module "<localName>" { ... } call. Returns the same instance, so the call site can read the module's outputs from it:
addMoved(String from, String to) → void
Record a moved { from = <from> to = <to> } block: the state object at from now belongs to the resource at to, so a rename (or a count / for_each instance unrolled into its own resource) keeps its state instead of being destroyed and re-created. Addresses are written as Terraform writes them (google_pubsub_topic.orders[0], module.events.google_pubsub_topic.orders).
addOutput<T>(String name, TfArg<T> value, {String? description, bool sensitive = false}) → void
Declare output "<name>" { value = <value> }.
addProvider<P extends StackProvider>(P provider) → P
Registers provider like an entry of Stack(providers: [...]) and returns it, so the constructor body holds the instance a resource selects with provider:.
externalVariable<T>(String name) → TfArgVariable<T>
The handle for a variable declared in a hand-written file beside the generated main.tf.json, accepted by the reference check without emitting a block for it.
isConfigurationAlias(StackProvider provider) → bool
Whether provider was registered with addConfigurationAlias.
isExternalProvider(StackProvider provider) → bool
Whether provider was registered with addExternalProvider.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
outputEnvironment({Iterable<String>? only}) → OutputEnvironment
The environment of an app that reads this Stack's outputs with the generated reader's fromEnvironment: the variable of each non-sensitive output registered so far (or of each output in only), in registration order, and its value — the output's value for a String output, its JSON for any other.
synth() → SynthResult
Synthesise this Stack into an in-memory SynthResult bundle.
toString() → String
A string representation of this object.
inherited
validate() → List<SynthIssue>
Every SynthIssue that keeps this Stack from synthesizing, in Stack order — empty when synth would succeed. synth and writeTo run the same checks and throw them as one SynthException; call this to inspect them without the throw, e.g. in a test.
variable<T>(String name, {TfType? type, String? description, T? defaultValue, bool? sensitive, bool? nullable}) → TfArgVariable<T>
Declare a variable "<name>" { ... } block and return the handle an argument takes: name: region reads var.region.
writeTo([String outDir = 'tf-out']) → Future<void>
Synthesise this Stack and write the result to outDir (tf-out by default).

Operators

operator ==(Object other) → bool
The equality operator.
inherited