import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import type { Input } from "./Input.ts";
import * as Output from "./Output.ts";
import type { BindingNode } from "./Plan.ts";
import type { ResourceBinding } from "./Resource.ts";
import { bytesToBase64 } from "./Util/base64.ts";
import { isPlainData, isPrimitive, mapPlainData } from "./Util/data.ts";
export type Diff = NoopDiff | UpdateDiff | ReplaceDiff;
export interface NoopDiff {
action: "noop";
/**
* Properties that stay stable if `--force` upgrades this noop to an
* update. A plain noop exposes every persisted attribute downstream, so
* this only matters under `--force`, where the engine otherwise falls back
* to `provider.stables` and drops conditional stables (e.g. a
* rename-mutable `name` that is stable because the `name` prop is
* unchanged).
*/
stables?: string[];
}
export interface UpdateDiff {
action: "update";
/** properties that won't change as part of this update */
stables?: string[];
}
export interface ReplaceDiff {
action: "replace";
deleteFirst?: boolean;
stables?: undefined;
}
/**
* Returns true when `value` (or any nested leaf) is still an unresolved
* plan-time expression — i.e. an `Output`/`Expr` or an `Effect` that was
* not fully evaluated by `resolveInput` in Plan.ts.
*
* Use at the top of a provider `diff` to short-circuit before field access:
*
* ```ts
* if (!isResolved(news)) return undefined;
* const resolved = news as MyProps;
* ```
*/
export const hasUnresolvedInputs = <T>(value: Input<NoInfer<T>>): value is T =>
_hasUnresolved(value);
export const isResolved = <T>(value: Input<T>): value is T => !_hasUnresolved(value);
const _hasUnresolved = (value: unknown, seen: WeakSet<object> = new WeakSet()): boolean => {
if (value == null || isPrimitive(value)) return false;
if (Output.isExpr(value) || Effect.isEffect(value)) return true;
// Only plain data is traversed; any other class instance (Layer, Context,
// Date, SDK objects) is a resolved leaf — see isPlainData (#1082).
if (isPlainData(value)) {
if (seen.has(value)) return false;
seen.add(value);
return Object.values(value).some((v) => _hasUnresolved(v, seen));
}
return false;
};
/**
* Deeply replace every unresolved plan-time expression (an `Output`/`Expr`
* or an un-evaluated `Effect`) with `undefined`, leaving resolved values
* (including opaque `Redacted`/`Duration` instances) intact.
*
* Persisted resource state must only ever hold plain data. Durable (JSON)
* state stores already enforce this implicitly — Output proxies are
* function-typed, so `JSON.stringify` silently drops them — but the
* in-memory store used by tests retains live proxies, which would later be
* fed back into provider lifecycle operations as `olds` after an
* interrupted apply (e.g. `read` during a destroy plan) and blow up on
* first string coercion. Sanitizing at the commit boundary keeps both
* store kinds consistent with the provider contract that `olds` is
* resolved `Props`.
*/
export const stripUnresolved = <T>(value: T): T => _stripUnresolved(value) as T;
const _stripUnresolved = (
value: unknown,
// Ancestor-path cycle guard: a value on its own ancestor chain is cut to
// `undefined` (a cycle can never persist). Sync DFS, so add/delete around
// the recursion is race-free and keeps shared diamond references intact
// (#1082).
ancestors: WeakSet<object> = new WeakSet(),
): unknown => {
if (value == null || isPrimitive(value)) return value;
if (Output.isExpr(value) || Effect.isEffect(value)) return undefined;
// Serializable leaves — the only class instances persisted state may
// carry (StateEncoding knows Redacted/Duration/Date/bytes). Rebuilding
// them structurally would strip their prototype.
if (
Redacted.isRedacted(value) ||
Duration.isDuration(value) ||
value instanceof Date ||
value instanceof Uint8Array
) {
return value;
}
if (isPlainData(value)) {
return mapPlainData(value, ancestors, (child) => _stripUnresolved(child, ancestors));
}
// Any other class instance (Layer, Context, SDK objects) is runtime-only
// wiring that can't round-trip through JSON — a beta.103 Context is even
// cyclic (#1082). Persisted state holds plain data only.
return undefined;
};
/**
* Deeply replace Effect-valued entries with `undefined`, leaving resolved
* values AND unresolved `Output`/`Expr`s intact.
*
* Effect-valued props — e.g. a tagged Worker class in `env` (the
* circular-bindings pattern) — can never be evaluated inside lifecycle
* operations, and {@link stripUnresolved} drops them from persisted state at
* the commit boundary. A provider `diff` that wants its structural change
* detection to still run despite them strips them first, so `isResolved`
* gates only on genuinely-unresolved Outputs (#874). The Effects' deploy-time
* identity is carried by the resolved binding data instead.
*/
export const stripEffects = <T>(value: T): T => _stripEffects(value) as T;
const _stripEffects = (
value: unknown,
// Ancestor-path cycle guard — see _stripUnresolved (#1082).
ancestors: WeakSet<object> = new WeakSet(),
): unknown => {
if (value == null || isPrimitive(value)) return value;
// Output proxies are left intact (so `isResolved` still sees them); they
// must be tested BEFORE `Effect.isEffect` because Output exprs are
// yieldable and would otherwise be misclassified as plain Effects.
if (Output.isExpr(value)) return value;
if (Effect.isEffect(value)) return undefined;
if (
Redacted.isRedacted(value) ||
Duration.isDuration(value) ||
value instanceof Date ||
value instanceof Uint8Array
) {
return value;
}
if (isPlainData(value)) {
return mapPlainData(value, ancestors, (child) => _stripEffects(child, ancestors));
}
// Non-plain instances (Layer, Context, SDK objects) are dropped with
// Effects — same runtime-only rationale, and their internals may be
// cyclic (effect ≥4.0.0-beta.103's Context — #1082).
return undefined;
};
export const somePropsAreDifferent = <Props extends Record<string, any>>(
olds: Props,
news: Props,
props: (keyof Props)[],
) => {
for (const prop of props) {
if (olds[prop] !== news[prop]) {
return true;
}
}
return false;
};
export const anyPropsAreDifferent = <Props extends Record<string, any>>(
olds: Props,
news: Props,
) => {
for (const prop in olds) {
if (olds[prop] !== news[prop]) {
return true;
}
}
for (const prop in news) {
if (!(prop in olds)) {
return true;
}
}
return false;
};
export const havePropsChanged = <Props extends object>(
oldProps: Props | undefined,
newProps: Props,
) =>
Output.hasOutputs(newProps) ||
// Compare both sides through `stripUnresolved` so the comparison is
// symmetric with the commit boundary: persisted props can never hold an
// Effect or Output expr (stripped at commit / silently dropped by JSON
// serialization), while desired props may still carry them — e.g. a tagged
// Worker class in `env` serializes via its `toJSON` to
// `{"_id":"Effect",...}` and would otherwise report a phantom change on
// every plan, forever (#874). Unresolved Outputs in `newProps` are already
// caught by the `hasOutputs` guard above, so stripping here never hides a
// real difference.
JSON.stringify(canonicalize(stripUnresolved(oldProps ?? {}), false)) !==
JSON.stringify(canonicalize(stripUnresolved(newProps ?? {}), false));
export type DeepEqualOptions = {
/**
* When true, treat `null` and `undefined` as equivalent at any depth.
* Useful when comparing cloud-API responses (which often return `null`
* for unconfigured optional fields) against desired-state shapes built
* from `props?.x` (which leave the same fields `undefined`).
*
* @default false
*/
stripNullish?: boolean;
};
/**
* Sort-keys deep equality for plain data (objects, arrays, primitives).
* Use in provider `diff` handlers instead of ad-hoc `JSON.stringify` comparisons.
*
* By default, `null` and `undefined` are treated as distinct. Pass
* `{ stripNullish: true }` to opt into treating them as equivalent.
*/
export const deepEqual = (a: unknown, b: unknown, options?: DeepEqualOptions): boolean =>
JSON.stringify(canonicalize(a, options?.stripNullish ?? false)) ===
JSON.stringify(canonicalize(b, options?.stripNullish ?? false));
const canonicalize = (
value: unknown,
stripNullish: boolean,
// Ancestor-path cycle guard — see _stripUnresolved (#1082).
ancestors: WeakSet<object> = new WeakSet(),
): unknown => {
if (stripNullish && value == null) return undefined;
if (Redacted.isRedacted(value)) {
return {
_tag: "Redacted",
value: Redacted.value(value),
};
}
// JSON-safe leaves compare by their serialized form (Duration/Date have
// toJSON).
if (Duration.isDuration(value) || value instanceof Date) return value;
// Bytes compare by content.
if (value instanceof Uint8Array) return { __bytes__: bytesToBase64(value) };
if (isPlainData(value)) {
const rebuilt = mapPlainData(value, ancestors, (child) =>
canonicalize(child, stripNullish, ancestors),
);
if (rebuilt === undefined || Array.isArray(rebuilt)) return rebuilt;
// Deterministic key order for the JSON.stringify comparison. Filtering
// after the walk is JSON-equivalent to filtering before it —
// undefined-valued keys are dropped by JSON.stringify either way.
return Object.fromEntries(
Object.entries(rebuilt as Record<string, unknown>)
.filter(([, nested]) => !stripNullish || nested != null)
.sort(([a], [b]) => a.localeCompare(b)),
);
}
if (value && typeof value === "object") {
// Non-plain instances (Effect, Layer, Context, SDK objects) never
// canonicalize — walking them is unsafe (cyclic on effect
// ≥4.0.0-beta.103 — #1082) and comparing them is meaningless.
return undefined;
}
return value;
};
/**
* Deterministic ordering for binding rows.
*
* Bindings are registered by concurrently-built layers (a Function/Worker's
* capability layers run real IO — bundling, fs — before calling `host.bind`),
* so the registration order of `stack.bindings[fqn]` is not stable across
* deploys. `diffBindings` itself is sid-keyed and order-insensitive, but the
* row order flows into provider `diff`/`reconcile` inputs and persisted
* state — any consumer that hashes or deep-compares the binding array (e.g.
* a metadata hash over bindings) would churn on registration-order flips.
* Sorting by `sid` at every boundary makes binding rows stable.
*/
const bySid = (a: { sid: string }, b: { sid: string }): number =>
a.sid < b.sid ? -1 : a.sid > b.sid ? 1 : 0;
export const sortBindings = <B extends { sid: string }>(bindings: B[]): B[] =>
[...bindings].sort(bySid);
/**
* Collapse bindings that share the same `sid`, keeping the last occurrence,
* and return them in deterministic (sid-sorted) order.
*
* The same binding can be recorded more than once on a target resource — e.g.
* a KV namespace bound to both a Worker and a Workflow ends up pushed twice to
* `stack.bindings[fqn]`. `diffBindings` already collapses these implicitly via
* its `Map` keyed by `sid`, so the `reconcile` path never observes duplicates.
* Use this helper to give a provider's `diff` handler the same de-duplicated
* binding set, keeping plan-time hashing consistent with deploy-time.
*/
export const dedupeBindings = <B extends ResourceBinding>(bindings: B[]): B[] =>
sortBindings(Array.from(new Map(bindings.map((b) => [b.sid, b])).values()));
export const diffBindings = (
oldBindings: ResourceBinding[],
newBindings: ResourceBinding[],
): BindingNode[] => {
const oldMap = new Map(oldBindings.map((b) => [b.sid, b]));
const newMap = new Map(newBindings.map((b) => [b.sid, b]));
return sortBindings([
...Array.from(oldMap)
.filter(([sid]) => !newMap.has(sid))
.map(([sid, old]) => ({
sid,
action: "delete" as const,
data: old.data,
})),
...Array.from(newMap).map(([sid, binding]) => {
const old = oldMap.get(sid);
return {
sid,
action: (!old
? "create"
: havePropsChanged(old.data, binding.data)
? "update"
: "noop") as BindingNode["action"],
data: binding.data,
};
}),
]);
};