@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 348 lines 11.3 KB
Raw
1 ---
2 title: Inputs & Outputs
3 description: Output<T> is alchemy's lazy reference type — the lazy values that flow between resources, get composed with .pipe, mapped, interpolated, and resolved during deploy.
4 ---
5
6 A [Resource](/infrastructure-as-code/resource)'s **inputs** are the props you pass
7 in. Its **outputs** are the attributes the cloud returns after
8 creation. The catch: outputs don't exist when you write the code.
9 They only exist after the resource is deployed.
10
11 Alchemy bridges this with **`Output<T>`** — a lazy, typed reference
12 that resolves once the upstream resource has run. You can read
13 properties off it, transform it with `pipe`, combine it with other
14 outputs, and feed it as input to the next resource. The resource
15 graph is built from these dependencies.
16
17 This page is a reference for every operator. For the bigger picture
18 of how the graph deploys, see
19 [Resource Lifecycle](/infrastructure-as-code/resource-lifecycle).
20
21 ## What an Output is
22
23 ```typescript
24 const bucket = yield* Cloudflare.R2.Bucket("Bucket");
25
26 bucket.bucketName;
27 // ^? Output<string>
28 ```
29
30 Three things to know:
31
32 1. **Lazy** — `bucket.bucketName` doesn't have a value yet. It's a
33 description of "the bucket's name once it's created."
34 2. **Typed** — TypeScript still knows it's `string`, even though
35 you can't `console.log` it directly.
36 3. **Tracked** — passing it as input to another resource registers
37 a dependency edge. Alchemy uses these edges to deploy in the
38 right order.
39
40 You almost never construct an `Output` yourself — they fall out of
41 resource declarations and the operators below.
42
43 ## Property access
44
45 Reading a property off a resource (or any `Output`) returns another
46 `Output`:
47
48 ```typescript
49 const bucket = yield* Cloudflare.R2.Bucket("Bucket");
50
51 bucket.bucketName; // Output<string>
52 bucket.bucketArn; // Output<string>
53 bucket.tags?.environment; // Output<string | undefined>
54 ```
55
56 Nested access works too — `expr.nested.deep` walks down the object
57 without forcing the value.
58
59 ## `literal`
60
61 When you need an `Output` shape but the value is already known:
62
63 ```typescript
64 import * as Output from "alchemy/Output";
65
66 Output.literal("hello"); // Output<string>
67 Output.literal(42); // Output<number>
68 Output.literal({ a: 1 }); // Output<{ a: number }>
69 ```
70
71 Useful as a default for an optional output, or as a placeholder in
72 templates and `Output.all` calls.
73
74 ## `asOutput`
75
76 Lifts a plain value, an `Effect`, or an existing `Output` into an
77 `Output`:
78
79 ```typescript
80 Output.asOutput("foo"); // wraps as a literal
81 Output.asOutput(Effect.succeed(123)); // wraps as an EffectExpr
82 Output.asOutput(existingOutput); // returns it unchanged
83 ```
84
85 Use this when writing helpers that should accept "anything output-y."
86
87 ## `fromEffect`
88
89 Lifts a plan-time Effect into an `Output`. The effect runs when the
90 stack resolves the Output during plan/deploy — with the stack's
91 services (cloud credentials, region, ...) provided — and never inside
92 a deployed runtime:
93
94 ```typescript
95 Output.fromEffect(lookupLatestAmi()); // Output<string>
96 ```
97
98 This is the low-level seam for lookup helpers that read cloud state to
99 produce a prop value. Because constructing the Output is inert, such
100 helpers are safe to call from composition code that is re-executed
101 inside a deployed Function, Worker, or Instance bundle — no
102 `__ALCHEMY_RUNTIME__` guard needed. The higher-level form is
103 [`Capability.execute`](/infrastructure-as-effects/binding#plan-time-invokes)
104 — invoking a binding as a plan-time data source — which the AMI
105 finders (`AWS.EC2.getAmi`, `AWS.EC2.amazonLinux2023()`,
106 `AWS.EC2.ubuntu2404()`, ...) are built on:
107
108 ```typescript
109 const instance = yield* AWS.EC2.Instance("web", {
110 imageId: AWS.EC2.amazonLinux2023(),
111 instanceType: "t3.micro",
112 subnetId: subnet.subnetId,
113 });
114 ```
115
116 The effect must not fail (`E = never`) — die with a descriptive error
117 for unresolvable lookups.
118
119 ## `map`
120
121 `Output.map` transforms an `Output<A>` into an `Output<B>` without
122 forcing it. The function runs once, after the upstream resource
123 resolves:
124
125 ```typescript
126 import * as Output from "alchemy/Output";
127
128 const upper = bucket.bucketName.pipe(
129 Output.map((name) => name.toUpperCase()),
130 );
131 // Output<string>
132 ```
133
134 It also supports a data-first form when you don't want to use
135 `pipe`:
136
137 ```typescript
138 Output.map(bucket.bucketName, (name) => name.toUpperCase());
139 ```
140
141 `map` composes — pipe several together to build up a chain:
142
143 ```typescript
144 const slug = bucket.bucketName.pipe(
145 Output.map((s) => s.toLowerCase()),
146 Output.map((s) => s.replaceAll("_", "-")),
147 );
148 ```
149
150 The function only runs once (per evaluation) and only after every
151 upstream `Output` is ready. There is no risk of "the function ran
152 before the resource existed."
153
154 ## `mapEffect`
155
156 `Output.mapEffect` is the same idea but the transform returns an
157 `Effect`. Use this when the transformation needs to do real work —
158 read a file, hit an API, decode a JWT — and you want it to live in
159 the Effect graph.
160
161 ```typescript
162 const decoded = secret.value.pipe(
163 Output.mapEffect((s) =>
164 Effect.gen(function* () {
165 const result = yield* JwtDecoder.decode(s);
166 return result.payload;
167 }),
168 ),
169 );
170 // Output<Payload>
171 ```
172
173 Chain them just like `map`:
174
175 ```typescript
176 "a".pipe(
177 Output.mapEffect((s) => Effect.succeed(s + "b")),
178 Output.mapEffect((s) => Effect.succeed(s + "c")),
179 );
180 // resolves to "abc"
181 ```
182
183 Requirements (the `R` channel of the inner Effects) are tracked in
184 the resulting `Output`'s requirements, so anything those Effects
185 need must be provided wherever the Output is finally evaluated.
186
187 ## `all`
188
189 `Output.all` zips several `Output`s into one. The result resolves
190 to a tuple (preserving the input shape and types):
191
192 ```typescript
193 const both = Output.all(bucket.bucketName, queue.queueUrl);
194 // Output<[string, string]>
195
196 const url = both.pipe(
197 Output.map(([name, queue]) => `s3://${name}?dlq=${queue}`),
198 );
199 ```
200
201 If you pass an array of `Output<T>` of unknown length, the result
202 is `Output<T[]>` instead of a fixed tuple.
203
204 ## `interpolate`
205
206 The most common combination of `all` + `map` is "build a string
207 from outputs." `Output.interpolate` is a tagged template literal
208 for exactly that:
209
210 ```typescript
211 const arn = Output.interpolate`arn:aws:s3:::${bucket.bucketName}/objects/*`;
212 // Output<string>
213
214 const dsn = Output.interpolate`postgres://${db.host}:${db.port}/${db.name}`;
215 ```
216
217 Nullish interpolated values render as the empty string.
218
219 Behind the scenes this is `Output.all(...args).pipe(Output.map(...))` —
220 so the dependency graph is wired up automatically.
221
222 ## `of`
223
224 You rarely call this directly because resources already act like
225 `Output`s, but it's how the conversion happens internally:
226
227 ```typescript
228 const bucketOut = Output.of(bucket); // Output<Bucket>
229 const refOut = Output.of(Ref({ id: "B" })); // for cross-stack refs
230 ```
231
232 Use `Output.of(Ref(...))` (or [`Output.ref`](#ref))
233 to read a resource's attributes from another stack — see below.
234
235 ## `ref`
236
237 `Output.ref` produces an `Output` referencing a deployed
238 resource's attributes in another stack or stage:
239
240 ```typescript
241 Output.ref<typeof Bucket>("Bucket", { stack: "shared-infra", stage: "prod" });
242 ```
243
244 See [References](/infrastructure-as-code/references) for the full reference
245 surface (`Output.ref`, `Resource.ref`, `Output.stackRef`,
246 `Stack.stage`) and how each is resolved.
247
248 ## How Outputs compose in props
249
250 You can pass an `Output` (or any structure containing Outputs) as
251 the input prop of another resource. Alchemy walks the structure,
252 collects upstream dependencies, and waits for them to resolve
253 before calling the provider.
254
255 ```typescript
256 const queue = yield* AWS.SQS.Queue("Jobs", {
257 name: Output.interpolate`${bucket.bucketName}-events`,
258 tags: {
259 bucket: bucket.bucketName,
260 region: Output.literal("us-west-2"),
261 },
262 deadLetter: {
263 queueUrl: dlq.queueUrl,
264 },
265 });
266 ```
267
268 Plain values, Outputs, nested objects, and arrays are all valid —
269 the engine evaluates them recursively.
270
271 ## Helpers
272
273 | Helper | Returns |
274 | ---------------------- | --------------------------------------------- |
275 | `Output.isOutput(v)` | `true` if `v` is an `Output<T>` |
276 | `Output.isExpr(v)` | `true` for any internal expression node |
277 | `Output.upstream(o)` | Map of upstream resources `o` depends on |
278 | `Output.hasOutputs(v)` | `true` if `v` (or anything inside) is lazy |
279 | `Output.toEnvKey(id, suffix)` | `"my-bucket" + "name"` → `"MY_BUCKET_NAME"` |
280
281 `upstream` and `hasOutputs` power the dependency graph — most code
282 won't call them directly, but they're useful when writing custom
283 providers.
284
285 ## Redacted values
286
287 Alchemy preserves `Redacted<T>` (Effect's secret wrapper) through
288 evaluation. Logs and console output show `<redacted>` instead of
289 the underlying value:
290
291 ```typescript
292 import * as Redacted from "effect/Redacted";
293
294 const apiKey = Redacted.make(env.API_KEY);
295
296 yield* MyService("svc", {
297 apiKey, // stays Redacted in state and logs
298 });
299 ```
300
301 ## Evaluation semantics
302
303 When alchemy needs the actual value of an `Output` (to call a
304 provider, to print outputs at the end of a deploy, to satisfy a
305 binding), it runs `Output.evaluate(expr, upstream)`:
306
307 1. **Resource expressions** look up the resolved attributes of
308 their upstream resource.
309 2. **Property expressions** evaluate their parent and read the
310 property.
311 3. **Apply / EffectExpr** evaluate the parent first, then run the
312 user function.
313 4. **All** evaluates its children in parallel.
314 5. **Ref** reads from the state store using `{ stack, stage, id }`.
315 6. **Plain values** (objects, arrays, primitives) are walked
316 recursively so Outputs inside them get evaluated too.
317 7. **`Redacted`** values are preserved as-is.
318
319 You normally never call `Output.evaluate` yourself — alchemy invokes
320 it during plan and apply. But understanding the ordering helps:
321 **every Output is lazy until alchemy decides to resolve it**, and
322 the deploy graph is exactly the set of dependencies your Outputs
323 declared.
324
325 ## Cheat sheet
326
327 | You want to… | Use |
328 | ------------------------------------------- | -------------------------------------------- |
329 | Reference an attribute that doesn't exist yet | `resource.attr` |
330 | Wrap a constant as an Output | `Output.literal(value)` |
331 | Coerce a value / Effect / Output to Output | `Output.asOutput(x)` |
332 | Transform an Output | `output.pipe(Output.map(fn))` |
333 | Transform with an Effect | `output.pipe(Output.mapEffect(fn))` |
334 | Combine several Outputs | `Output.all(a, b, c)` |
335 | Build a string from Outputs | `` Output.interpolate`a/${b}/c` `` |
336 | Read a resource from another stack | `Output.ref<typeof X>("id", { stack, stage })` |
337 | Inspect dependencies | `Output.upstream(output)` |
338
339 ## Where next
340
341 - [References](/infrastructure-as-code/references) — read Outputs across
342 stacks and stages. Next page.
343 - [Resource lifecycle](/infrastructure-as-code/resource-lifecycle) — how
344 the graph deploys.
345 - [Resources](/infrastructure-as-code/resource) — what an Output actually
346 flows into.
347 - [Layers](/infrastructure-as-effects/layers) — hide resources and their
348 Outputs behind a service interface.