alchemy 2.0.0-beta.64 → 2.0.0-beta.66

package/src/Test/Alchemy.ts

@@ -3,7 +3,7 @@
 /**
  * Test adapter for the `alchemy-test` runner (see `packages/alchemy-test`).
  *
- * Same shape as {@link "./Bun.ts"}, but registers
+ * Same shape as {@link "./Vitest.ts"} / {@link "./Bun.ts"}, but registers
  * tests as raw Effects with the alchemy-test harness so the single-process
  * runner can inject a buffering Logger/Console per test and manage
  * concurrency + timeouts itself.
@@ -264,7 +264,9 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
   // closes it. We defer registration to a microtask so it runs AFTER any
   // user-registered `afterAll` (including `destroy(Stack)`); the runner
   // executes afterAll hooks in registration order, and file collection
-  // flushes microtasks before sealing the file's suite tree.
+  // flushes microtasks before sealing the file's suite tree. (Files are
+  // collected in parallel, but the microtask carries the AsyncLocalStorage
+  // context of this file's import, so the hook lands on the right suite.)
   queueMicrotask(() => {
     registerHook("afterAll", {
       body: () => closeScope,

package/src/Test/Core.ts

@@ -288,14 +288,7 @@ export const scratchStack = <ROut>(
     plan: ((effect: Effect.Effect<any, any, any>) =>
       buildPlan(effect)) as ScratchStack<ROut>["plan"],
     destroy: () =>
-      Plan.make({
-        name: stackName,
-        stage,
-        resources: {},
-        bindings: {},
-        actions: {},
-        output: {},
-      }).pipe(
+      Plan.destroy({ name: stackName, stage }).pipe(
         Effect.flatMap(apply),
         Effect.asVoid,
         Effect.provide(stateLayer),

package/src/Test/Vitest.ts

@@ -0,0 +1,244 @@
+/** @effect-diagnostics anyUnknownInErrorContext:off */
+import { it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import {
+  afterAll as vitestAfterAll,
+  afterEach as vitestAfterEach,
+  beforeAll as vitestBeforeAll,
+  beforeEach as vitestBeforeEach,
+} from "vitest";
+
+import type { AlchemyContext } from "../AlchemyContext.ts";
+import type { CompiledStack } from "../Stack.ts";
+import type { Stage } from "../Stage.ts";
+import * as Core from "./Core.ts";
+
+export {
+  executeWhenReady,
+  getWhenReady,
+  guardContentType,
+  guardedFetchLayer,
+  rpcClientLayer,
+  WorkerNotReady,
+  type EdgeGuardOptions,
+  type WhenReadyOptions,
+} from "./Http.ts";
+
+export type MakeOptions<ROut = any> = Core.MakeOptions<ROut>;
+export type ScratchStack = Core.ScratchStack;
+export type TestEffect<A, R = never> = Core.TestEffect<A, R>;
+
+type TestOptions = number | { timeout?: number };
+
+const timeoutOf = (opts: TestOptions | undefined): number | undefined =>
+  typeof opts === "number" ? opts : opts?.timeout;
+
+interface TestFn {
+  (name: string, eff: TestEffect<void>, options?: TestOptions): void;
+  skip: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  only: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  todo: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  provider: ProviderFn;
+}
+
+interface ProviderFn {
+  (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ): void;
+  skip: (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ) => void;
+}
+
+interface BeforeAllFn {
+  <A>(eff: TestEffect<A>, options?: TestOptions): Effect.Effect<A>;
+}
+
+interface BeforeEachFn {
+  (eff: TestEffect<void>, options?: TestOptions): void;
+}
+
+interface AfterAllFn {
+  (eff: TestEffect<any>, options?: TestOptions): void;
+  skipIf: (
+    predicate: boolean,
+  ) => (eff: TestEffect<any>, options?: TestOptions) => void;
+}
+
+interface AfterEachFn {
+  (eff: TestEffect<void>, options?: TestOptions): void;
+}
+
+export interface TestApi {
+  test: TestFn;
+  beforeAll: BeforeAllFn;
+  beforeEach: BeforeEachFn;
+  afterAll: AfterAllFn;
+  afterEach: AfterEachFn;
+  deploy: <A>(
+    stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
+    options?: { stage?: string },
+  ) => ReturnType<typeof Core.deploy<A>>;
+  destroy: (
+    stack: TestEffect<CompiledStack, Stage | AlchemyContext>,
+    options?: { stage?: string },
+  ) => ReturnType<typeof Core.destroy>;
+}
+
+const DEFAULT_TIMEOUT = 120_000;
+
+/**
+ * Build the per-file test API. See {@link "./Bun.ts"} for the same shape
+ * over `bun:test`. Vitest variant uses `@effect/vitest`'s `it.live` so
+ * Effect-aware tests stay first-class.
+ */
+export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
+  // See `Test/Bun.ts` for the rationale: the dev sidecar must outlive a
+  // single `runPromise` boundary, so all hooks share one scope that's only
+  // closed after `destroy(...)` runs.
+  const sharedScope = Scope.makeUnsafe("sequential");
+  const wrap = <A>(eff: TestEffect<A>) =>
+    Core.toEffect(eff, options, sharedScope);
+  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options, sharedScope);
+
+  const test = ((name, eff, opts) => {
+    it.live(name, () => wrap(eff), timeoutOf(opts));
+  }) as TestFn;
+
+  test.skip = (name, _eff, opts) => {
+    it.skip(name, () => {}, timeoutOf(opts));
+  };
+  test.skipIf = (condition) => (name, eff, opts) => {
+    if (condition) {
+      it.skip(name, () => {}, timeoutOf(opts));
+    } else {
+      it.live(name, () => wrap(eff), timeoutOf(opts));
+    }
+  };
+  test.only = (name, eff, opts) => {
+    it.only(name, () => wrap(eff) as Effect.Effect<any>, timeoutOf(opts));
+  };
+  test.todo = (name, _eff, _opts) => {
+    it.todo(name);
+  };
+
+  const wrapProvider = (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+  ) => {
+    const scratch = Core.scratchStack(options, name);
+    // Guarantee teardown. `test.provider` has no built-in cleanup, so a body
+    // that fails (assertion, API error like a 409/Unauthorized) or is
+    // interrupted (vitest timeout) BEFORE its trailing `stack.destroy()` would
+    // otherwise leak every cloud resource it deployed: the scratch's in-memory
+    // state is discarded with the process, so no later run can reclaim the
+    // orphan (only an account-wide `nuke` can). `scratch.destroy()` is
+    // idempotent (empty-plan apply against the shared scratch state) — a no-op
+    // when the body already destroyed, and it reclaims the orphans otherwise.
+    // `Effect.ensuring` runs the finalizer on success, failure, AND interruption.
+    const body = Core.withProviders(fn(scratch), options, scratch.name).pipe(
+      Effect.ensuring(scratch.destroy().pipe(Effect.ignore)),
+    );
+    return Core.toEffect(
+      body,
+      { ...options, state: scratch.state },
+      sharedScope,
+    );
+  };
+
+  const provider = ((name, fn, opts) => {
+    it.live(name, () => wrapProvider(name, fn), timeoutOf(opts));
+  }) as ProviderFn;
+  provider.skip = (name, _fn, opts) => {
+    it.skip(name, () => {}, timeoutOf(opts));
+  };
+  provider.skipIf = (condition) => (name, fn, opts) => {
+    if (condition) {
+      it.skip(name, () => {}, timeoutOf(opts));
+    } else {
+      it.live(name, () => wrapProvider(name, fn), timeoutOf(opts));
+    }
+  };
+  test.provider = provider;
+
+  const beforeAll: BeforeAllFn = <A>(
+    eff: TestEffect<A>,
+    hookOptions?: TestOptions,
+  ) => {
+    let result: A;
+    vitestBeforeAll(
+      () => runEff(eff).then((v) => (result = v)),
+      timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+    );
+    return Effect.sync(() => result);
+  };
+
+  const beforeEach: BeforeEachFn = (eff, hookOptions) => {
+    vitestBeforeEach(() => runEff(eff), timeoutOf(hookOptions));
+  };
+
+  const afterAll = ((eff, hookOptions) => {
+    vitestAfterAll(
+      () => runEff(eff),
+      timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+    );
+  }) as AfterAllFn;
+  afterAll.skipIf = (predicate) => (eff, hookOptions) => {
+    if (predicate) return;
+    vitestAfterAll(
+      () => runEff(eff),
+      timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+    );
+  };
+
+  const afterEach: AfterEachFn = (eff, hookOptions) => {
+    vitestAfterEach(() => runEff(eff), timeoutOf(hookOptions));
+  };
+
+  // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`.
+  // `Scope.close` on an already-closed scope is a no-op, so the destroy
+  // wrapper AND the fallback cleanup hook below can both call it safely.
+  const closeScope = Effect.suspend(() =>
+    Scope.close(sharedScope, Exit.void),
+  ).pipe(Effect.ignore);
+
+  // Fallback cleanup: if the user never calls `destroy(Stack)` (e.g.
+  // `NO_DESTROY=1`), nothing else closes the shared scope and the sidecar
+  // child process leaks past the test process. Register an `afterAll` that
+  // closes it. We defer registration to a microtask so it runs AFTER any
+  // user-registered `afterAll` (including `destroy(Stack)`); vitest runs
+  // afterAll hooks in registration order.
+  queueMicrotask(() => {
+    vitestAfterAll(() => Effect.runPromise(closeScope), DEFAULT_TIMEOUT);
+  });
+
+  return {
+    test,
+    beforeAll,
+    beforeEach,
+    afterAll,
+    afterEach,
+    deploy: (stack, callOpts) =>
+      Core.deploy(options, stack, { ...callOpts, scope: sharedScope }),
+    destroy: (stack, callOpts) =>
+      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
+        Effect.ensuring(closeScope),
+      ),
+  };
+};

package/src/Util/Clank.ts

@@ -14,16 +14,15 @@ export const retryIfCancelled = Effect.retry({
  *
  * Returns `undefined` if the user cancels (Ctrl+C / Escape).
  *
- * Uses `Effect.callback` so fiber interruption propagates via the abort
- * signal to any async resources we own; the clack prompt itself is left
- * to resolve — its result is ignored after interruption.
+ * Uses `Effect.callback` so fiber interruption propagates to the clack
+ * prompt through its abort signal, releasing stdin and restoring the cursor.
  */
 export const prompt = <T>(
-  fn: () => Promise<T | symbol>,
+  fn: (signal: AbortSignal) => Promise<T | symbol>,
 ): Effect.Effect<T, PromptCancelled> =>
   Effect.callback<T, PromptCancelled>((resume, signal) => {
     let settled = false;
-    fn().then(
+    fn(signal).then(
       (result) => {
         if (settled || signal.aborted) return;
         settled = true;
@@ -45,15 +44,42 @@ export const success = (str: string) => Effect.sync(() => p.log.success(str));
 export const warn = (str: string) => Effect.sync(() => p.log.warn(str));
 export const error = (str: string) => Effect.sync(() => p.log.error(str));
 export const info = (str: string) => Effect.sync(() => p.log.info(str));
-export const text = (opts: p.TextOptions) => prompt(() => p.text(opts));
-export const password = (opts: p.PasswordOptions) =>
-  prompt(() => p.password(opts));
+type TextOptions = Omit<p.TextOptions, "validate"> & {
+  validate?: (value: string) => string | Error | undefined;
+};
+
+type PasswordOptions = Omit<p.PasswordOptions, "validate"> & {
+  validate?: (value: string) => string | Error | undefined;
+};
+
+export const text = (opts: TextOptions) => {
+  const validate = opts.validate;
+  return prompt<string>((signal) =>
+    p.text({
+      ...opts,
+      signal,
+      validate:
+        validate === undefined ? undefined : (value) => validate(value ?? ""),
+    }),
+  );
+};
+export const password = (opts: PasswordOptions) => {
+  const validate = opts.validate;
+  return prompt<string>((signal) =>
+    p.password({
+      ...opts,
+      signal,
+      validate:
+        validate === undefined ? undefined : (value) => validate(value ?? ""),
+    }),
+  );
+};
 export const select = <Value>(opts: p.SelectOptions<Value>) =>
-  prompt(() => p.select<Value>(opts));
+  prompt((signal) => p.select<Value>({ ...opts, signal }));
 export const confirm = (opts: p.ConfirmOptions) =>
-  prompt(() => p.confirm(opts));
+  prompt((signal) => p.confirm({ ...opts, signal }));
 export const multiselect = <Value>(opts: p.MultiSelectOptions<Value>) =>
-  prompt(() => p.multiselect<Value>(opts));
+  prompt((signal) => p.multiselect<Value>({ ...opts, signal }));
 
 /**
  * Open a URL in the user's default browser.

package/src/Util/proxy-chain.ts

@@ -5,13 +5,31 @@ type Op =
   | { kind: "get"; prop: PropertyKey }
   | { kind: "call"; args: unknown[] };
 
+interface ChainState {
+  readonly cached: Effect.Effect<unknown, any, any>;
+  readonly ops: ReadonlyArray<Op>;
+}
+
+/**
+ * Every proxy produced by {@link chain} is registered here so that a chain
+ * passed as an *argument* to another chain over the same `cached` effect
+ * (e.g. `` sql`... ${sql.insert(row)}` `` — the nested `sql.insert(row)` is
+ * itself a proxy) can be recognized and replayed against the same resolved
+ * root instead of being handed to the real client as an opaque proxy.
+ */
+const chainStates = new WeakMap<object, ChainState>();
+
 /**
  * Replay an op chain against a real value. `get` reads a property,
  * `call` invokes — bound to the previous receiver so `this` resolves
  * to the object the method was read from (drizzle's `select()` etc.
  * read `this._.session`, so dropping `this` would throw).
  */
-const replay = (root: unknown, ops: ReadonlyArray<Op>): unknown => {
+const replay = (
+  root: unknown,
+  ops: ReadonlyArray<Op>,
+  cached: Effect.Effect<unknown, any, any>,
+): unknown => {
   let cur: any = root;
   let receiver: any = root;
   for (const op of ops) {
@@ -19,13 +37,56 @@ const replay = (root: unknown, ops: ReadonlyArray<Op>): unknown => {
       receiver = cur;
       cur = cur[op.prop];
     } else {
-      cur = cur.apply(receiver, op.args);
+      cur = cur.apply(receiver, replayArgs(root, op.args, cached));
       receiver = cur;
     }
   }
   return cur;
 };
 
+/**
+ * Resolve nested chain proxies inside a call's arguments. Only proxies over
+ * the *same* `cached` effect can be replayed synchronously (the root is
+ * already resolved); proxies over a different effect pass through untouched.
+ * Returns the original array when nothing needed resolving, so identity-
+ * sensitive values (e.g. a `TemplateStringsArray` with its `raw` property)
+ * are preserved.
+ */
+const replayArgs = (
+  root: unknown,
+  args: ReadonlyArray<unknown>,
+  cached: Effect.Effect<unknown, any, any>,
+): ReadonlyArray<unknown> => {
+  let out: unknown[] | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const resolved = replayArg(root, args[i], cached);
+    if (resolved !== args[i]) {
+      out ??= [...args];
+      out[i] = resolved;
+    }
+  }
+  return out ?? args;
+};
+
+const replayArg = (
+  root: unknown,
+  arg: unknown,
+  cached: Effect.Effect<unknown, any, any>,
+): unknown => {
+  if (arg === null || (typeof arg !== "object" && typeof arg !== "function")) {
+    return arg;
+  }
+  const state = chainStates.get(arg);
+  if (state?.cached === cached) {
+    return replay(root, state.ops, cached);
+  }
+  // Fragments may arrive wrapped in arrays (e.g. `sql.and([a, b])`).
+  if (Array.isArray(arg)) {
+    return replayArgs(root, arg, cached);
+  }
+  return arg;
+};
+
 /**
  * Wrap a cached `Effect<T>` in a chainable Proxy so callers can use the
  * returned value as if it were `T` itself — every property read and call
@@ -52,6 +113,11 @@ const replay = (root: unknown, ops: ReadonlyArray<Op>): unknown => {
  * The chain ends when the proxy is yielded as an Effect — the resolved
  * value at that point must be a `Yieldable` (an Effect, drizzle query
  * builder, etc). Anything before that is recorded as ops.
+ *
+ * A chain passed as an *argument* to another chain over the same effect —
+ * e.g. `` sql`INSERT INTO users ${sql.insert(row)}` ``, where `sql.insert(row)`
+ * is itself a deferred proxy — is replayed against the same resolved root
+ * before the outer call runs, so synchronous fragment helpers compose.
  */
 export const proxyChain = <T>(cached: Effect.Effect<T, any, any>): T =>
   chain(cached) as T;
@@ -62,9 +128,10 @@ const chain = (
 ): unknown => {
   const effect = Effect.flatMap(
     cached,
-    (root) => replay(root, ops) as Effect.Effect<unknown, unknown, unknown>,
+    (root) =>
+      replay(root, ops, cached) as Effect.Effect<unknown, unknown, unknown>,
   );
-  return new Proxy(function () {}, {
+  const proxy = new Proxy(function () {}, {
     get(_, prop) {
       if (Reflect.has(effect, prop)) {
         return Reflect.get(effect, prop);
@@ -78,4 +145,6 @@ const chain = (
       return chain(cached, [...ops, { kind: "call", args }]);
     },
   });
+  chainStates.set(proxy, { cached, ops });
+  return proxy;
 };

package/src/Util/zip.ts

@@ -3,6 +3,11 @@ import * as Effect from "effect/Effect";
 export interface ZipFile {
   path: string;
   content: string | Uint8Array<ArrayBufferLike>;
+  /**
+   * Unix file mode to record in the archive entry (e.g. `0o755` to keep an
+   * executable bit). Omit to use the archiver's default.
+   */
+  mode?: number;
 }
 
 export const zipCode = Effect.fn(function* (
@@ -25,3 +30,37 @@ export const zipCode = Effect.fn(function* (
     }),
   );
 });
+
+/**
+ * Package `files` into a deterministic zip archive: entries are sorted by
+ * path and stamped with a fixed timestamp so identical inputs always produce
+ * identical bytes.
+ */
+export const zipFiles = Effect.fn(function* (files: ReadonlyArray<ZipFile>) {
+  // Create a zip buffer in memory
+  const zip = new (yield* Effect.promise(() => import("jszip"))).default();
+  const date = new Date("1980-01-01T00:00:00.000Z");
+  for (const file of [...files].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+    zip.file(file.path, file.content, {
+      date,
+      unixPermissions: file.mode,
+    });
+  }
+  // Nested paths make JSZip synthesize the intermediate folder entries, and
+  // those are stamped with `new Date()` rather than the per-file `date`
+  // above. Left alone, two archives built from identical bytes seconds apart
+  // differ — which reads downstream as a content change.
+  yield* Effect.sync(() => {
+    for (const entry of Object.values(zip.files)) {
+      entry.date = date;
+    }
+  });
+
+  return yield* Effect.promise(() =>
+    zip.generateAsync({
+      type: "nodebuffer",
+      compression: "DEFLATE",
+      platform: "UNIX",
+    }),
+  );
+});

package/src/index.ts

@@ -25,6 +25,8 @@ export { ALCHEMY_DEV, ALCHEMY_PHASE, type AlchemyPhase } from "./Phase.ts";
 export * from "./PhysicalName.ts";
 export * as Plan from "./Plan.ts";
 export { Provider, ProviderCollection } from "./Provider.ts";
+export * as ProviderMode from "./ProviderMode.ts";
+export { remote } from "./ProviderMode.ts";
 export * from "./Random.ts";
 export * from "./Ref.ts";
 export * as RemovalPolicy from "./RemovalPolicy.ts";
@@ -36,6 +38,7 @@ export { Stack } from "./Stack.ts";
 export * from "./Stage.ts";
 export { inMemoryState, localState } from "./State/index.ts";
 export * as Sync from "./Sync.ts";
+export * as Telemetry from "./Telemetry.ts";
 
 // Re-export internal types so they can be portably named in
 // downstream `.d.ts` emissions (fixes TS2883 in user files).

package/lib/SQL/index.d.ts

@@ -1,4 +0,0 @@
-export * from "./D1.ts";
-export * from "./Postgres.ts";
-export * from "./SqlFile.ts";
-//# sourceMappingURL=index.d.ts.map

package/lib/SQL/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/SQL/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/lib/SQL/index.js

@@ -1,4 +0,0 @@
-export * from "./D1.js";
-export * from "./Postgres.js";
-export * from "./SqlFile.js";
-//# sourceMappingURL=index.js.map

package/lib/SQL/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/SQL/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/src/SQL/index.ts

@@ -1,3 +0,0 @@
-export * from "./D1.ts";
-export * from "./Postgres.ts";
-export * from "./SqlFile.ts";