import * as Config from "effect/Config";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { pipe } from "effect/Function";
import type { Pipeable } from "effect/Pipeable";
import { SingleShotGen } from "effect/Utils";
import { getRefMetadata, isRef, type Ref } from "./Ref.ts";
import { isResource, type Resource, type ResourceLike } from "./Resource.ts";
import { RuntimeContext, sanitizeKey } from "./RuntimeContext.ts";
import { StackContext } from "./StackContext.ts";
import { Stage } from "./Stage.ts";
import * as State from "./State/State.ts";
import { isPlainData, isPrimitive, type Primitive } from "./Util/data.ts";
const inspect = Symbol.for("nodejs.util.inspect.custom");
export const of = <R extends ResourceLike>(
resource: Ref<R> | R,
): R extends ResourceLike ? ResourceExpr<R["Attributes"]> : RefExpr<R["Attributes"]> => {
if (isRef(resource)) {
const metadata = getRefMetadata(resource);
return new RefExpr(
metadata.stack,
metadata.stage,
metadata.id,
// Surface the target's resource type and logical id as
// statically-known properties so duck-typing classifiers (Worker
// env bindings) and label/bind templates (`${resource.LogicalId}`,
// `host.bind\`...\``) identify the ref exactly like a
// locally-declared resource.
{
LogicalId: metadata.id,
...(metadata.type !== undefined ? { Type: metadata.type } : {}),
},
) as any;
}
return new ResourceExpr(resource) as any;
};
export const asOutput = <T>(t: T | Output<T> | Effect.Effect<T>): Output<T> =>
isOutput(t) ? t : Effect.isEffect(t) ? new EffectExpr(VoidExpr, () => t) : new LiteralExpr(t);
/**
* Lift a plan-time Effect into an {@link Output}.
*
* The effect runs when the stack resolves the Output during plan/deploy —
* with the stack's services (cloud credentials, region, ...) provided — and
* never inside a deployed runtime: constructing the Output is inert, so
* helpers built on `fromEffect` (e.g. AMI lookups) are safe to call from
* composition code that is re-executed inside a Function/Worker/Instance
* bundle.
*
* The effect must not fail (`E = never`) — die with a descriptive error for
* unresolvable lookups.
*/
export const fromEffect = <A, Req = never>(
effect: Effect.Effect<A, never, Req>,
): ToOutput<A, Req> => new EffectExpr(VoidExpr, () => effect) as any;
export const isOutput = (value: any): value is Output<any> =>
value && (typeof value === "object" || typeof value === "function") && ExprSymbol in value;
export interface Output<A = any, Req = any> extends Pipeable {
/** @internal phantom */
readonly kind: string;
/** @internal phantom */
readonly A: A;
/** @internal phantom */
readonly req: Req;
/** @internal phantom */
[Symbol.iterator](): Iterator<Effect.Effect<void, never, Req>, Accessor<A>, void>;
bind(id: string): Effect.Effect<Effect.Effect<A>, never, RuntimeContext>;
asEffect(): Effect.Effect<Accessor<A>, never, Req>;
as<T>(): Output<T, Req>;
}
export interface Accessor<A> extends Effect.Effect<A> {}
export type ToOutput<A, Req = never> =
// Branded primitives (`string & Brand<"...">`) are assignable to `object`
// via the brand intersection, so they must short-circuit to a plain Output
// before the object check — otherwise they explode into an ObjectExpr
// mapped over every String/Number method. Date is opaque for the same
// reason (mirrors AttrOutput in Resource.ts).
[A] extends [Primitive | Date]
? Output<A, Req>
: [Extract<A, object>] extends [never]
? Output<A, Req>
: [Extract<A, any[]>] extends [never]
? ObjectExpr<
{
[attr in keyof A]: A[attr];
},
Req
>
: ArrayExpr<Extract<A, any[]>, Req>;
export const ExprSymbol = Symbol.for("alchemy/Expr");
const exprKind = (node: any): unknown => node?.[ExprSymbol]?.kind ?? node?.kind;
export const isExpr = (value: any): value is Expr<any> =>
value && (typeof value === "object" || typeof value === "function") && ExprSymbol in value;
export type Expr<A = any, Req = any> =
| AllExpr<Expr<A, Req>[]>
| ApplyExpr<any, A, Req>
| EffectExpr<any, A, Req>
| FlatMapExpr<any, A, Req>
| LiteralExpr<A>
| NamedExpr<A, Req>
| PropExpr<A, keyof A, Req>
| ResourceExpr<A, Req>
| RefExpr<A>
| StackRefExpr<A>;
export abstract class BaseExpr<A = any, Req = any> implements Output<A, Req> {
declare readonly kind: any;
declare readonly A: A;
declare readonly src: ResourceLike;
declare readonly req: Req;
// we use a kind tag instead of instanceof to protect ourselves from duplicate alchemy module imports
constructor() {}
as<T>(): Output<T, Req> {
return this as any;
}
[Symbol.iterator](): Iterator<Effect.Effect<void, never, Req>, Accessor<A>, void> {
// @ts-expect-error - TODO(sam): fix this (works at runtime, but maybe indicates a bad assumption)
return new SingleShotGen(this.asEffect());
}
asEffect(): any {
return this.bind(this.toString());
}
public bind(id: string): any {
// `set`/`get` store keys verbatim, so canonicalize here (the caller's job).
const key = sanitizeKey(id);
return RuntimeContext.pipe(
Effect.flatMap((ctx) => Effect.map(ctx.set(key, this), (k) => ctx.get<A>(k))),
);
}
public pipe(...fns: any[]): any {
// @ts-expect-error
return pipe(this, ...fns);
}
public abstract [inspect](): string;
public toString(): string {
return this[inspect]();
}
}
export type ObjectExpr<A, Req = any> = Output<A, Req> & {
[Prop in keyof Exclude<A, undefined>]-?: ToOutput<
Exclude<A, undefined>[Prop] | Extract<A, undefined>,
Req
>;
};
export type ArrayExpr<A extends any[], Req = any> = Output<A, Req> & {
[i in Extract<keyof A, number>]: ToOutput<A[i], Req>;
};
export const isResourceExpr = <Value = any, Req = any>(
node: any,
): node is ResourceExpr<Value, Req> => exprKind(node) === "ResourceExpr";
export class ResourceExpr<Value, Req = never> extends BaseExpr<Value, Req> {
readonly kind = "ResourceExpr";
readonly src: ResourceLike;
readonly stables?: Record<string, any>;
constructor(src: ResourceLike, stables?: Record<string, any>) {
super();
this.src = src;
this.stables = stables;
return proxy(this);
}
[inspect](): string {
return this.src.LogicalId;
}
}
export const isPropExpr = <A = any, Prop extends keyof A = keyof A, Req = any>(
node: any,
): node is PropExpr<A, Prop, Req> => exprKind(node) === "PropExpr";
export class PropExpr<A = any, Id extends keyof A = keyof A, Req = any> extends BaseExpr<
A[Id],
Req
> {
readonly kind = "PropExpr";
readonly expr: Expr<A, Req>;
readonly identifier: Id;
constructor(expr: Expr<A, Req>, identifier: Id) {
super();
this.expr = expr;
this.identifier = identifier;
return proxy(this);
}
[inspect](): string {
return `${this.expr[inspect]()}.${this.identifier.toString()}`;
}
}
export const literal = <A>(value: A) => new LiteralExpr(value);
export const isLiteralExpr = <A = any>(node: any): node is LiteralExpr<A> =>
exprKind(node) === "LiteralExpr";
export class LiteralExpr<A> extends BaseExpr<A, never> {
readonly kind = "LiteralExpr";
readonly value: A;
constructor(value: A) {
super();
this.value = value;
return proxy(this);
}
[inspect](): string {
return String(this.value);
}
}
export const VoidExpr = new LiteralExpr(void 0);
export const map: {
<A, B>(fn: (value: A) => B): <Req>(output: Output<A, Req>) => ToOutput<B, Req>;
<A, B, Req>(output: Output<A, Req>, fn: (value: A) => B): ToOutput<B, Req>;
} = (<A, B, Req>(...args: [fn: (value: A) => B] | [output: Output<A, Req>, fn: (value: A) => B]) =>
args.length === 1
? <Req>(output: Output<A, Req>): ToOutput<B, Req> =>
new ApplyExpr(output as Expr<A, Req>, args[0]) as any
: new ApplyExpr(args[0] as any, args[1])) as any;
//Output.ApplyExpr<any, any, ResourceLike, any>
export const isApplyExpr = <In = any, Out = any, Req = any>(
node: Output<Out, Req>,
): node is ApplyExpr<In, Out, Req> => exprKind(node) === "ApplyExpr";
export class ApplyExpr<A, B, Req = never> extends BaseExpr<B, Req> {
readonly kind = "ApplyExpr";
readonly expr: Expr<A, Req>;
readonly f: (value: A) => B;
constructor(expr: Expr<A, Req>, f: (value: A) => B) {
super();
this.expr = expr;
this.f = f;
return proxy(this);
}
[inspect](): string {
return `${this.expr[inspect]()}.map(${this.f.toString()})`;
}
// Bind the upstream and apply `f` where it is read. A binding keyed by this
// expression would embed `f.toString()`, which differs between the deploy
// and a minified runtime bundle, so the runtime would find nothing.
override asEffect(): any {
return Effect.map(this.expr.asEffect() as Effect.Effect<Accessor<A>>, (accessor) =>
Effect.map(accessor, this.f),
);
}
}
export const mapEffect =
<A, B, Req2>(fn: (value: A) => Effect.Effect<B, never, Req2>) =>
<Req>(output: Output<A, Req>): ToOutput<B, Req | Req2> =>
new EffectExpr(output as Expr<A, Req>, fn) as any;
export const flatMap: {
<A, B, Req2>(
fn: (value: A) => Output<B, Req2>,
): <Req>(output: Output<A, Req>) => ToOutput<B, Req | Req2>;
<A, B, Req, Req2>(
output: Output<A, Req>,
fn: (value: A) => Output<B, Req2>,
): ToOutput<B, Req | Req2>;
} = (<A, B, Req, Req2>(
...args:
| [fn: (value: A) => Output<B, Req2>]
| [output: Output<A, Req>, fn: (value: A) => Output<B, Req2>]
) =>
args.length === 1
? <Req>(output: Output<A, Req>): ToOutput<B, Req | Req2> =>
new FlatMapExpr(output as Expr<A, Req>, args[0]) as any
: new FlatMapExpr(args[0] as any, args[1])) as any;
export const isFlatMapExpr = <In = any, Out = any, Req = any, Req2 = any>(
node: any,
): node is FlatMapExpr<In, Out, Req, Req2> => exprKind(node) === "FlatMapExpr";
export class FlatMapExpr<A, B, Req = never, Req2 = never> extends BaseExpr<B, Req | Req2> {
readonly kind = "FlatMapExpr";
readonly expr: Expr<A, Req>;
readonly f: (value: A) => Output<B, Req2>;
constructor(expr: Expr<A, Req>, f: (value: A) => Output<B, Req2>) {
super();
this.expr = expr;
this.f = f;
return proxy(this);
}
[inspect](): string {
return `${this.expr[inspect]()}.flatMap(${this.f.toString()})`;
}
}
export const isEffectExpr = <In = any, Out = any, Req = any, Req2 = any>(
node: any,
): node is EffectExpr<In, Out, Req, Req2> => exprKind(node) === "EffectExpr";
export class EffectExpr<A, B, Req = never, Req2 = never> extends BaseExpr<B, Req> {
readonly kind = "EffectExpr";
readonly expr: Expr<A, Req>;
readonly f: (value: A) => Effect.Effect<B, never, Req2>;
constructor(expr: Expr<A, Req>, f: (value: A) => Effect.Effect<B, never, Req2>) {
super();
this.expr = expr;
this.f = f;
return proxy(this);
}
[inspect](): string {
return `${this.expr[inspect]()}.mapEffect(${this.f.toString()})`;
}
}
export const isNamedExpr = <A = any, Req = any>(node: any): node is NamedExpr<A, Req> =>
exprKind(node) === "NamedExpr";
/**
* Wraps another `Expr` and overrides its `toString()` / inspect output.
*
* `BaseExpr` derives the binding id from `this.toString()`, so
* wrapping an expression in `NamedExpr` makes that derived id stable and
* caller-controlled (e.g. an env var name like `"API_KEY"`).
*/
export class NamedExpr<A, Req = never> extends BaseExpr<A, Req> {
readonly kind = "NamedExpr";
readonly expr: Expr<A, Req>;
readonly bindingName: string;
constructor(expr: Expr<A, Req>, bindingName: string) {
super();
this.expr = expr;
this.bindingName = bindingName;
return proxy(this);
}
[inspect](): string {
return this.bindingName;
}
}
export const named = <A, Req>(expr: Output<A, Req>, name: string): Output<A, Req> =>
new NamedExpr(expr as Expr<A, Req>, name) as any;
export const all = <Outs extends (Output | Expr)[]>(...outs: Outs) =>
new AllExpr(outs as any) as unknown as All<Outs>;
export type All<Outs extends (Output | Expr)[]> = number extends Outs["length"]
? [Outs[number]] extends [Output<infer V, infer Req> | Expr<infer V, infer Req>]
? Output<V, Req>
: never
: Tuple<Outs>;
type Tuple<Outs extends (Output | Expr)[], Values extends any[] = [], Req = never> = Outs extends [
infer H,
...infer Tail extends (Output | Expr)[],
]
? H extends Output<infer V, infer Req2>
? Tuple<Tail, [...Values, V], Req | Req2>
: never
: Output<Values, Req>;
export const isAllExpr = <Outs extends Expr[] = Expr[]>(node: any): node is AllExpr<Outs> =>
exprKind(node) === "AllExpr";
export class AllExpr<Outs extends Expr[]> extends BaseExpr<Outs> {
readonly kind = "AllExpr";
readonly outs: Outs;
constructor(outs: Outs) {
super();
this.outs = outs;
return proxy(this);
}
[inspect](): string {
return `all(${this.outs.map((out) => out[inspect]()).join(", ")})`;
}
// Bind each member on its own (see `ApplyExpr.asEffect`).
override asEffect(): any {
return Effect.map(
Effect.all(this.outs.map((out) => out.asEffect() as Effect.Effect<Accessor<unknown>>)),
(accessors) => Effect.all(accessors),
);
}
}
export const isRefExpr = <A = any>(node: any): node is RefExpr<A> => exprKind(node) === "RefExpr";
export class RefExpr<A> extends BaseExpr<A, never> {
readonly kind = "RefExpr";
readonly stack: string | undefined;
readonly stage: string | undefined;
readonly resourceId: string;
/**
* Statically-known properties of the ref's target (currently its
* resource `Type`), served as literals by the proxy instead of
* `PropExpr`s — mirrors {@link ResourceExpr}'s `stables`.
*/
readonly stables?: Record<string, any>;
constructor(
stack: string | undefined,
stage: string | undefined,
resourceId: string,
stables?: Record<string, any>,
) {
super();
this.stack = stack;
this.stage = stage;
this.resourceId = resourceId;
this.stables = stables;
return proxy(this);
}
[inspect](): string {
return `ref(${this.resourceId}, { stack: ${this.stack}, stage: ${this.stage} })`;
}
}
/**
* Refs the plan bound to a resource declared in the same program. A ref names
* a resource by stack, stage and id; when those are the current stack and
* stage and the program also declares that resource, the ref is a dependency
* on it, exactly like a direct reference: {@link upstream} reports the edge
* (create waits for the target, delete runs the dependent first) and
* {@link evaluate} reads the target's fresh attributes from the apply-time
* outputs. Unbound refs (other stacks or stages, or resources only in state)
* keep reading persisted state and carry no edge.
*/
const boundRefs = new WeakMap<object, ResourceLike>();
// Keyed by the raw expression, so a ref reached through its proxy or
// unwrapped through `ExprSymbol` finds the same binding.
const rawExpr = (ref: object): object => (ref as any)[ExprSymbol] ?? ref;
/** Bind `ref` to the declared resource it names (see {@link boundRefs}). */
export const bindRef = (ref: RefExpr<any>, target: ResourceLike): void => {
boundRefs.set(rawExpr(ref), target);
};
/** The declared resource a ref was bound to, if any. */
export const refTarget = (ref: RefExpr<any>): ResourceLike | undefined =>
boundRefs.get(rawExpr(ref));
/**
* Every {@link RefExpr} reachable from `value` through the same expression and
* plain-data structure {@link upstream} walks. Refs a `flatMap` produces at
* evaluation time are not reachable, as for any upstream.
*/
export const collectRefs = (value: any, seen: WeakSet<object> = new WeakSet()): RefExpr<any>[] => {
if (isPrimitive(value) || isResource(value)) {
return [];
} else if (isExpr(value)) {
if (isRefExpr(value)) return [value];
if (isPropExpr(value)) return collectRefs(value.expr, seen);
if (isAllExpr(value)) return value.outs.flatMap((out: any) => collectRefs(out, seen));
if (isEffectExpr(value) || isApplyExpr(value) || isFlatMapExpr(value) || isNamedExpr(value)) {
return collectRefs(value.expr, seen);
}
return [];
} else if (isPlainData(value)) {
if (alreadySeen(value, seen)) return [];
return Object.values(value).flatMap((child) => collectRefs(child, seen));
}
return [];
};
export const isStackRefExpr = <A = any>(node: any): node is StackRefExpr<A> =>
exprKind(node) === "StackRefExpr";
/**
* A reference to the persisted output of a Stack at `(stack, stage)`.
*
* Resolved at evaluation time by reading `state.getOutput({ stack,
* stage })`. Distinct from {@link RefExpr}, which references a
* single resource's attributes within a stack/stage. `stage` may be
* `undefined`, in which case it falls back to the current stage.
*/
export class StackRefExpr<A> extends BaseExpr<A, never> {
readonly kind = "StackRefExpr";
readonly stack: string;
readonly stage: string | undefined;
constructor(stack: string, stage: string | undefined) {
super();
this.stack = stack;
this.stage = stage;
return proxy(this);
}
[inspect](): string {
return `stackRef(${this.stack}${this.stage ? `, { stage: ${this.stage} }` : ""})`;
}
}
/**
* Build an `Output<A>` referencing the persisted output of another
* Stack. The returned Effect resolves to a lazy `Output<A>` whose
* value is read from the state store at plan/apply time.
*
* Returns `Effect<Output<A>>` (not `Output<A>` directly) so that
* `yield* Output.stackRef(...)` reads ergonomically inside an Effect
* generator and lines up with `Resource.ref` and `Stack.stage.<name>`.
*/
export const stackRef = <A>(
stack: string,
options: { stage?: string } = {},
): Effect.Effect<Output<A, never>> =>
Effect.succeed(new StackRefExpr<A>(stack, options.stage) as any);
export const filter = <Outs extends any[]>(...outs: Outs) =>
outs.filter(isOutput) as unknown as Filter<Outs>;
export type Filter<Outs extends any[]> = number extends Outs["length"]
? Output<Extract<Outs[number], Output>["value"], Extract<Outs[number], Output>["req"]>
: FilterTuple<Outs>;
export type FilterTuple<Outs extends (Output | Expr)[], Values extends any[] = []> = Outs extends [
infer H,
...infer Tail extends (Output | Expr)[],
]
? H extends Output<infer V>
? FilterTuple<Tail, [...Values, V]>
: FilterTuple<Tail, Values>
: Output<Values>;
export const interpolate = <Args extends any[]>(
template: TemplateStringsArray,
...args: Args
): All<Args> extends Output<any, infer Req> ? Output<string, Req> : never => {
const outs = args.map((arg) => (isOutput(arg) ? arg : literal(arg)));
const expr = all(...outs).pipe(
map((args) =>
template.map((str, i) => str + (args[i] == null ? "" : String(args[i]))).join(""),
),
);
// The binding id of a mapped Output embeds the mapper's source, which the
// runtime bundler reprints differently from the deploying process, so the
// two sides would derive different keys. Name it from the template and its
// arguments instead, which are identical on both sides.
const name = template
.map((str, i) => (i < outs.length ? `${str}\${${(outs[i] as any)[inspect]()}}` : str))
.join("");
return named(expr as Output<string, any>, `interpolate(${name})`) as any;
};
function proxy(self: any): any {
const target = Object.assign(() => {}, self);
if (inspect in self) {
Object.defineProperty(target, inspect, {
value: self[inspect].bind(self),
configurable: true,
});
}
const proxy = new Proxy(target, {
has: (_, prop) =>
prop === ExprSymbol || prop === inspect
? true
: // Statically-known literal props (`Type`, `LogicalId` on
// resource/ref exprs) are visible to `in` checks so duck-typing
// code paths (e.g. `"LogicalId" in arg`) treat them like real
// properties, matching what `get` serves.
((isResourceExpr(self) || isRefExpr(self)) &&
self.stables !== undefined &&
prop in self.stables) ||
prop in self,
get: (target, prop) =>
prop === Symbol.toPrimitive
? (hint: string) => {
// Any JS-level coercion of an unresolved Output produces a
// placeholder that *looks* like a real value but isn't:
//
// - `string` / `default` hints (`${output}`, `output + ""`,
// `==` against a primitive) previously fell through to
// `self.toString()` and returned the inspect form
// (e.g. "tunnel.tunnelId"). The bogus string flowed
// into resource props and into the cloud — only
// surfacing as an opaque downstream error (see PR
// description for a real Cloudflare DNS landing).
//
// - `number` hint (`+output`, `output * 2`,
// `Math.max(0, output)`) previously returned NaN, which
// propagates silently through arithmetic and lands as
// "the API rejected a NaN field" much later.
//
// All three hints fail loud at the coercion site with a
// pointer to the right composition API.
throw new Error(
`Cannot coerce Output<${self[inspect]()}> to a ` +
`${hint === "number" ? "number" : "string"} via JS coercion. ` +
`Use Output.interpolate\`...\` or Output.map(output, fn) ` +
`to compose Outputs — the value isn't known until deploy time.`,
);
}
: prop === ExprSymbol
? self
: prop === inspect
? target[inspect]
: (isResourceExpr(self) || isRefExpr(self)) && self.stables && prop in self.stables
? self.stables[prop as keyof typeof self.stables]
: prop in self
? typeof self[prop as keyof typeof self] === "function" && !("kind" in self)
? new PropExpr(proxy, prop as never)
: self[prop as keyof typeof self]
: new PropExpr(proxy, prop as never),
apply: (_, thisArg, args) => {
if (isPropExpr(self)) {
// Method-style combinators on an Output proxy. `map`/`apply` and
// `mapEffect`/`effect` are aliases that mirror the standalone
// `Output.map` / `Output.mapEffect` / `Output.flatMap` functions.
if (self.identifier === "map" || self.identifier === "apply") {
return new ApplyExpr(self.expr, args[0]);
} else if (self.identifier === "mapEffect" || self.identifier === "effect") {
return new EffectExpr(self.expr, args[0]);
} else if (self.identifier === "flatMap") {
return new FlatMapExpr(self.expr, args[0]);
}
}
return undefined;
},
});
return proxy;
}
/// Evaluation
export class MissingSourceError extends Data.TaggedError("MissingSourceError")<{
message: string;
srcId: string;
}> {}
export class InvalidReferenceError extends Data.TaggedError("InvalidReferenceError")<{
message: string;
stack: string;
stage: string;
resourceId: string;
}> {}
export const evaluate: <A, Req = never>(
expr: Output<A, Req> | A,
upstream: {
[Id in string]: any;
},
// Ancestor-path cycle guard — a plain-data value that appears on its own
// ancestor chain is cut to `undefined` (it could never serialize anyway).
// Immutable per-level so legitimately-shared diamond references survive
// (#1082).
ancestors?: ReadonlySet<object>,
) => Effect.Effect<
A,
InvalidReferenceError | MissingSourceError | Config.ConfigError,
State.State | Req
> = (expr, upstream, ancestors = new Set()) =>
// oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the declared signature above carries the real error/requirement types
Effect.gen(function* () {
if (isResource(expr)) {
const srcId = expr.FQN;
const src = upstream[srcId as keyof typeof upstream];
if (!Object.hasOwn(upstream, srcId)) {
// type-safety should prevent this but let the caller decide how to handle it
return yield* new MissingSourceError({
message: `Source ${srcId} not found`,
srcId,
});
}
return src;
} else if (isOutput(expr)) {
if (isResourceExpr(expr)) {
const srcId = expr.src.FQN;
const src = upstream[srcId as keyof typeof upstream];
if (!Object.hasOwn(upstream, srcId)) {
// type-safety should prevent this but let the caller decide how to handle it
return yield* new MissingSourceError({
message: `Source ${srcId} not found`,
srcId,
});
}
return src;
} else if (isLiteralExpr(expr)) {
return expr.value;
} else if (isApplyExpr(expr)) {
return expr.f(yield* evaluate(expr.expr, upstream));
} else if (isEffectExpr(expr)) {
// TODO(sam): the same effect shoudl be memoized so that it's not run multiple times
return yield* expr.f(yield* evaluate(expr.expr, upstream));
} else if (isFlatMapExpr(expr)) {
// Resolve the source, hand it to `f` to produce a new Output, then
// recursively evaluate that Output (flattening one level).
const value = yield* evaluate(expr.expr, upstream);
return yield* evaluate(expr.f(value), upstream);
} else if (isAllExpr(expr)) {
return yield* Effect.forEach(expr.outs, (out) => evaluate(out, upstream));
} else if (isPropExpr(expr)) {
return (yield* evaluate(expr.expr, upstream))?.[expr.identifier];
} else if (isNamedExpr(expr)) {
return yield* evaluate(expr.expr, upstream);
} else if (isRefExpr(expr)) {
const target = refTarget(expr);
if (target !== undefined && Object.hasOwn(upstream, target.FQN)) {
return upstream[target.FQN as keyof typeof upstream];
}
const state = yield* yield* State.State;
const stack = expr.stack ?? (yield* StackContext).name;
const stage = expr.stage ?? (yield* Stage);
const resource = yield* state.get({
stack,
stage,
fqn: expr.resourceId,
});
if (!resource) {
return yield* new InvalidReferenceError({
message: `Reference to '${expr.resourceId}' in stack '${stack}' and stage '${stage}' not found. Have you deployed '${stage}' or '${stack}'?`,
stack,
stage,
resourceId: expr.resourceId,
});
}
// RefExpr targets persisted resources; tasks aren't cross-stack
// referenceable. Return the resource's output attrs, otherwise the
// task's output value, otherwise undefined.
return (resource as any).attr ?? (resource as any).output;
} else if (isStackRefExpr(expr)) {
const state = yield* yield* State.State;
const stack = expr.stack;
const stage = expr.stage ?? (yield* Stage);
const output = yield* state.getOutput({ stack, stage });
if (output == null) {
return yield* new InvalidReferenceError({
message: `Reference to stack '${stack}' at stage '${stage}' not found. Have you deployed stage '${stage}' of '${stack}'?`,
stack,
stage,
resourceId: stack,
});
}
return output;
}
}
if (Config.isConfig(expr)) {
// Resolve Config against the deploy environment — see resolveInput in
// Plan.ts for rationale. `Config.Redacted` resolves to a `Redacted`,
// which stays opaque via the leaf fallthrough below.
return yield* evaluate(yield* expr, upstream, ancestors);
} else if (isPlainData(expr)) {
if (ancestors.has(expr)) {
return undefined;
}
const nested = new Set(ancestors).add(expr);
if (Array.isArray(expr)) {
return yield* Effect.forEach(expr, (item) => evaluate(item, upstream, nested));
}
return Object.fromEntries(
yield* Effect.forEach(Object.entries(expr), ([key, value]) =>
evaluate(value, upstream, nested).pipe(Effect.map((value) => [key, value])),
),
);
}
// Everything else is a leaf returned by identity: Duration, Redacted,
// Date, and effect runtime values (a Worker's `exports` carries each
// DO's `constructor` Effect and captured `services` Context). Rebuilding
// a class instance entry-by-entry strips its prototype, and effect
// ≥4.0.0-beta.103's Context is cyclic (#1082). This sits after
// `Config.isConfig` on purpose — Configs are Effects but must resolve.
return expr;
}) as Effect.Effect<any>;
/**
* Evaluate the parts of `expr` that `upstream` can resolve. An Output whose
* sources are all in `upstream` is evaluated, plain data is walked, and an
* Output with any other source is returned unevaluated.
*/
export const evaluateAvailable = (
expr: any,
upstream: {
[Id in string]: any;
},
ancestors: ReadonlySet<object> = new Set(),
): Effect.Effect<
any,
InvalidReferenceError | MissingSourceError | Config.ConfigError,
State.State
> =>
Effect.gen(function* () {
if (isResource(expr) || isOutput(expr)) {
const sources = Object.keys(upstreamAny(expr));
return sources.every((fqn) => Object.hasOwn(upstream, fqn))
? yield* evaluate(expr, upstream)
: expr;
}
if (Config.isConfig(expr)) {
return yield* evaluate(expr, upstream);
}
if (isPlainData(expr)) {
if (ancestors.has(expr)) {
return undefined;
}
const nested = new Set(ancestors).add(expr);
if (Array.isArray(expr)) {
return yield* Effect.forEach(expr, (item) => evaluateAvailable(item, upstream, nested));
}
return Object.fromEntries(
yield* Effect.forEach(Object.entries(expr), ([key, value]) =>
evaluateAvailable(value, upstream, nested).pipe(Effect.map((value) => [key, value])),
),
);
}
return expr;
});
export const hasOutputs = (value: any): value is Output<any, any> =>
Object.keys(upstreamAny(value)).length > 0;
/**
* Cycle guard shared by the upstream walkers. Marks `value` as visited in
* `seen`; returns true when it was already visited (the caller returns `{}`
* — the first visit already contributed the subtree's resources to the
* FQN-keyed union, so skipping repeats is lossless).
*/
const alreadySeen = (value: object, seen: WeakSet<object>): boolean => {
if (seen.has(value)) {
return true;
}
seen.add(value);
return false;
};
// The dependency rule (#1082): a Resource or Output IS a dependency; plain
// data (arrays, plain objects) is traversed to find them; every other value
// — class instances like effect's Effect/Layer/Context, Dates, SDK objects,
// functions — is a leaf. See `isPlainData` in Util/data.ts for why leaves
// must never be walked.
export const upstreamAny = (
value: any,
seen: WeakSet<object> = new WeakSet(),
): {
[ID in string]: Resource;
} => {
if (isResource(value)) {
return { [value.FQN]: value as Resource };
} else if (isExpr(value)) {
return upstream(value, seen);
} else if (isPlainData(value)) {
if (alreadySeen(value, seen)) {
return {};
}
return Object.assign({}, ...Object.values(value).map((value) => resolveUpstream(value, seen)));
}
return {};
};
// TODO(sam): add a type
export const upstream = <E extends Output<any, any>>(
expr: E,
seen: WeakSet<object> = new WeakSet(),
): any => {
if (isResource(expr)) {
return {
[(expr as unknown as Resource).FQN]: expr,
};
} else if (isResourceExpr(expr)) {
return {
[expr.src.FQN]: expr.src,
};
} else if (isRefExpr(expr)) {
const target = refTarget(expr);
return target === undefined ? {} : { [target.FQN]: target };
} else if (isPropExpr(expr)) {
return upstream(expr.expr, seen);
} else if (isAllExpr(expr)) {
return Object.assign({}, ...expr.outs.map((out) => upstream(out, seen)));
} else if (isEffectExpr(expr) || isApplyExpr(expr) || isFlatMapExpr(expr) || isNamedExpr(expr)) {
return upstream(expr.expr, seen);
} else if (isPlainData(expr)) {
if (alreadySeen(expr, seen)) {
return {};
}
return Object.values(expr)
.map((v) => upstream(v as any, seen))
.reduce(toObject, {});
}
return {};
};
// TODO(sam): add a type
export const resolveUpstream = <const A>(value: A, seen: WeakSet<object> = new WeakSet()): any => {
if (isPrimitive(value)) {
return {} as any;
} else if (isResource(value)) {
return { [(value as unknown as Resource).FQN]: value } as any;
} else if (isOutput(value)) {
return upstream(value, seen) as any;
} else if (isPlainData(value)) {
if (alreadySeen(value, seen)) {
return {} as any;
}
return Object.fromEntries(
Object.values(value)
.map((v) => resolveUpstream(v, seen))
.flatMap(Object.entries),
) as any;
}
return {} as any;
};
const toObject = <A, B>(acc: B, v: A) => ({
...acc,
...v,
});
export const log = <A>(_value: A) =>
Effect.gen(function* () {
// TODO(sam): implement a log effect
});
export const toEnvKey = <const ID extends string, const Suffix extends string>(
id: ID,
suffix: Suffix,
) => `${replace(toUpper(id))}_${replace(toUpper(suffix))}` as const;
export const toUpper = <const S extends string>(str: S) =>
str.toUpperCase() as string extends S ? S : Uppercase<S>;
const replace = <const S extends string>(str: S) => str.replace(/-/g, "_") as Replace<S>;
type Replace<S extends string, Accum extends string = ""> = string extends S
? S
: S extends ""
? Accum
: S extends `${infer S}${infer Rest}`
? S extends "-"
? Replace<Rest, `${Accum}_`>
: Replace<Rest, `${Accum}${S}`>
: Accum;