alchemy 2.0.0-beta.4 → 2.0.0-beta.41

package/src/Neon/Providers.ts

@@ -0,0 +1,57 @@
+import * as Layer from "effect/Layer";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { CredentialsStoreLive } from "../Auth/Credentials.ts";
+import { ProfileLive } from "../Auth/Profile.ts";
+import * as Provider from "../Provider.ts";
+import { NeonAuth } from "./AuthProvider.ts";
+import { Branch, BranchProvider } from "./Branch.ts";
+import * as Credentials from "./Credentials.ts";
+import { NeonEnvironment, fromProfile } from "./NeonEnvironment.ts";
+import { Project, ProjectProvider } from "./Project.ts";
+
+export { NeonEnvironment } from "./NeonEnvironment.ts";
+
+export class Providers extends Provider.ProviderCollection<Providers>()(
+  "Neon",
+) {}
+
+export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
+
+/**
+ * Build a layer that registers all Neon resource providers, the Neon
+ * `AuthProvider`, the resolved `Credentials`, and an `HttpClient`. Include
+ * this from your stack alongside other cloud `providers()` layers.
+ *
+ * @example
+ * ```typescript
+ * import * as Alchemy from "alchemy";
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Neon from "alchemy/Neon";
+ * import * as Effect from "effect/Effect";
+ * import * as Layer from "effect/Layer";
+ *
+ * export default Alchemy.Stack(
+ *   "MyStack",
+ *   {
+ *     providers: Layer.mergeAll(Cloudflare.providers(), Neon.providers()),
+ *     state: Alchemy.localState(),
+ *   },
+ *   Effect.gen(function* () {
+ *     const project = yield* Neon.Project("app-db");
+ *     const branch = yield* Neon.Branch("app-branch", { project });
+ *     return { branchId: branch.branchId };
+ *   }),
+ * );
+ * ```
+ */
+export const providers = () =>
+  Layer.effect(Providers, Provider.collection([Project, Branch])).pipe(
+    Layer.provide(Layer.mergeAll(ProjectProvider(), BranchProvider())),
+    Layer.provideMerge(Credentials.fromAuthProvider()),
+    Layer.provideMerge(fromProfile()),
+    Layer.provideMerge(NeonAuth),
+    Layer.provideMerge(ProfileLive),
+    Layer.provideMerge(CredentialsStoreLive),
+    Layer.provideMerge(FetchHttpClient.layer),
+    Layer.orDie,
+  );

package/src/Neon/SqlFile.ts

@@ -0,0 +1,55 @@
+import crypto from "node:crypto";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+
+export interface SqlFile {
+  id: string;
+  sql: string;
+  hash: string;
+}
+
+/**
+ * Recursively list `.sql` files under `directory`, sorted by their numeric
+ * prefix (e.g. `0001_init.sql`) and then by name.
+ */
+export const listSqlFiles = (directory: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const entries = yield* fs.readDirectory(directory, { recursive: true });
+
+    const sqlFiles = entries
+      .filter((name) => name.endsWith(".sql"))
+      .sort((a, b) => {
+        const aNum = getPrefix(a);
+        const bNum = getPrefix(b);
+        if (aNum !== null && bNum !== null) return aNum - bNum;
+        if (aNum !== null) return -1;
+        if (bNum !== null) return 1;
+        return a.localeCompare(b);
+      });
+
+    return yield* Effect.all(sqlFiles.map((id) => readSqlFile(directory, id)));
+  });
+
+/**
+ * Read a single `.sql` file relative to `directory` and compute its content
+ * hash. The `sql` field is marked non-enumerable so it isn't serialized into
+ * resource state.
+ */
+export const readSqlFile = (directory: string, name: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const sql = yield* fs.readFileString(path.resolve(directory, name));
+    const hash = crypto.createHash("sha256").update(sql).digest("hex");
+    const file: SqlFile = { id: name, sql, hash };
+    Object.defineProperty(file, "sql", { enumerable: false });
+    return file;
+  });
+
+const getPrefix = (name: string): number | null => {
+  const prefix = name.split("_")[0];
+  const num = Number.parseInt(prefix, 10);
+  return Number.isNaN(num) ? null : num;
+};

package/src/Neon/index.ts

@@ -0,0 +1,5 @@
+export * from "./Branch.ts";
+export * from "./NeonEnvironment.ts";
+export * from "./PostgresOrigin.ts";
+export * from "./Project.ts";
+export * from "./Providers.ts";

package/src/Output.ts

@@ -1,12 +1,12 @@
 import * as Data from "effect/Data";
-import type { Yieldable } from "effect/Effect";
 import * as Effect from "effect/Effect";
 import { pipe } from "effect/Function";
 import type { Pipeable } from "effect/Pipeable";
+import * as Redacted from "effect/Redacted";
 import { SingleShotGen } from "effect/Utils";
-import { ExecutionContext } from "./ExecutionContext.ts";
-import { getRefMetadata, isRef, ref as stageRef, type Ref } from "./Ref.ts";
+import { getRefMetadata, isRef, type Ref } from "./Ref.ts";
 import { isResource, type Resource, type ResourceLike } from "./Resource.ts";
+import { RuntimeContext } from "./RuntimeContext.ts";
 import { Stack } from "./Stack.ts";
 import { Stage } from "./Stage.ts";
 import * as State from "./State/State.ts";
@@ -47,11 +47,11 @@ export interface Output<A = any, Req = any> extends Pipeable {
   readonly req: Req;
   /** @internal phantom */
   [Symbol.iterator](): Iterator<
-    Yieldable<any, void, never, Req>,
+    Effect.Effect<void, never, Req>,
     Accessor<A>,
     void
   >;
-  bind(id: string): Effect.Effect<Effect.Effect<A>, never, ExecutionContext>;
+  bind(id: string): Effect.Effect<Effect.Effect<A>, never, RuntimeContext>;
   asEffect(): Effect.Effect<Accessor<A>, never, Req>;
   as<T>(): Output<T, Req>;
 }
@@ -81,9 +81,11 @@ export type Expr<A = any, Req = any> =
   | ApplyExpr<any, A, Req>
   | EffectExpr<any, A, Req>
   | LiteralExpr<A>
+  | NamedExpr<A, Req>
   | PropExpr<A, keyof A, Req>
   | ResourceExpr<A, Req>
-  | RefExpr<A>;
+  | RefExpr<A>
+  | StackRefExpr<A>;
 
 export abstract class BaseExpr<A = any, Req = any> implements Output<A, Req> {
   declare readonly kind: any;
@@ -97,12 +99,12 @@ export abstract class BaseExpr<A = any, Req = any> implements Output<A, Req> {
   }
 
   [Symbol.iterator](): Iterator<
-    Yieldable<any, void, never, Req>,
+    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);
+    return new SingleShotGen(this.asEffect());
   }
 
   asEffect(): any {
@@ -110,7 +112,7 @@ export abstract class BaseExpr<A = any, Req = any> implements Output<A, Req> {
   }
 
   public bind(id: string): any {
-    return ExecutionContext.asEffect().pipe(
+    return RuntimeContext.pipe(
       Effect.flatMap((ctx) =>
         Effect.map(ctx.set(id, this), (key) => ctx.get<A>(key)),
       ),
@@ -208,8 +210,6 @@ export const map: {
         new ApplyExpr(output as Expr<A, Req>, args[0]) as any
     : new ApplyExpr(args[0] as any, args[1])) as any;
 
-type _ = Parameters<typeof map>;
-
 //Output.ApplyExpr<any, any, ResourceLike, any>
 export const isApplyExpr = <In = any, Out = any, Req = any>(
   node: Output<Out, Req>,
@@ -256,6 +256,36 @@ export class EffectExpr<A, B, Req = never, Req2 = never> extends BaseExpr<
   }
 }
 
+export const isNamedExpr = <A = any, Req = any>(
+  node: any,
+): node is NamedExpr<A, Req> => node?.kind === "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";
+  constructor(
+    public readonly expr: Expr<A, Req>,
+    public readonly bindingName: string,
+  ) {
+    super();
+    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>;
 
@@ -310,6 +340,48 @@ export class RefExpr<A> extends BaseExpr<A, never> {
   }
 }
 
+export const isStackRefExpr = <A = any>(node: any): node is StackRefExpr<A> =>
+  node?.kind === "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";
+  constructor(
+    public readonly stack: string,
+    public readonly stage: string | undefined,
+  ) {
+    super();
+    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>;
 
@@ -354,7 +426,32 @@ function proxy(self: any): any {
       prop === ExprSymbol || prop === inspect ? true : prop in self,
     get: (target, prop) =>
       prop === Symbol.toPrimitive
-        ? (hint: string) => (hint === "string" ? self.toString() : self)
+        ? (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
@@ -446,6 +543,8 @@ export const evaluate: <A, Req = never>(
         );
       } 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 state = yield* State.State;
         const stack = expr.stack ?? (yield* Stack).name;
@@ -465,11 +564,32 @@ export const evaluate: <A, Req = never>(
             }),
           );
         }
-        return resource.attr;
+        // 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* State.State;
+        const stack = expr.stack;
+        const stage = expr.stage ?? (yield* Stage);
+        const output = yield* state.getOutput({ stack, stage });
+        if (output == null) {
+          return yield* Effect.fail(
+            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 (Array.isArray(expr)) {
       return yield* Effect.all(expr.map((item) => evaluate(item, upstream)));
+    } else if (Redacted.isRedacted(expr)) {
+      return expr;
     } else if (typeof expr === "object" && expr !== null) {
       return Object.fromEntries(
         yield* Effect.all(
@@ -482,14 +602,6 @@ export const evaluate: <A, Req = never>(
     return expr;
   }) as Effect.Effect<any>;
 
-export const ref = <R extends ResourceLike>(
-  resourceId: R["LogicalId"],
-  options?: {
-    stage?: string;
-    stack?: string;
-  },
-) => of(stageRef({ id: resourceId, ...options }));
-
 export const hasOutputs = (value: any): value is Output<any, any> =>
   Object.keys(upstreamAny(value)).length > 0;
 
@@ -498,7 +610,9 @@ export const upstreamAny = (
 ): {
   [ID in string]: Resource;
 } => {
-  if (isExpr(value)) {
+  if (isResource(value)) {
+    return { [value.FQN]: value as Resource };
+  } else if (isExpr(value)) {
     return upstream(value);
   } else if (Array.isArray(value)) {
     return Object.assign({}, ...value.map(resolveUpstream));
@@ -516,7 +630,11 @@ export const upstreamAny = (
 
 // TODO(sam): add a type
 export const upstream = <E extends Output<any, any>>(expr: E): any => {
-  if (isResourceExpr(expr)) {
+  if (isResource(expr)) {
+    return {
+      [(expr as unknown as Resource).FQN]: expr,
+    };
+  } else if (isResourceExpr(expr)) {
     return {
       [expr.src.FQN]: expr.src,
     };
@@ -524,7 +642,7 @@ export const upstream = <E extends Output<any, any>>(expr: E): any => {
     return upstream(expr.expr);
   } else if (isAllExpr(expr)) {
     return Object.assign({}, ...expr.outs.map((out) => upstream(out)));
-  } else if (isEffectExpr(expr) || isApplyExpr(expr)) {
+  } else if (isEffectExpr(expr) || isApplyExpr(expr) || isNamedExpr(expr)) {
     return upstream(expr.expr);
   } else if (Array.isArray(expr)) {
     return expr.map(upstream).reduce(toObject, {});
@@ -540,6 +658,8 @@ export const upstream = <E extends Output<any, any>>(expr: E): any => {
 export const resolveUpstream = <const A>(value: A): 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) as any;
   } else if (Array.isArray(value)) {