alchemy 2.0.0-beta.84 → 2.0.0-beta.85

package/src/Test/Http.ts

@@ -1,201 +0,0 @@
-import * as Data from "effect/Data";
-import * as Effect from "effect/Effect";
-import * as FetchHttpClient from "effect/http/FetchHttpClient";
-import * as HttpClient from "effect/http/HttpClient";
-import { DecodeError, HttpClientError } from "effect/http/HttpClientError";
-import * as HttpClientRequest from "effect/http/HttpClientRequest";
-import type { HttpClientResponse } from "effect/http/HttpClientResponse";
-import * as Layer from "effect/Layer";
-import * as RpcClient from "effect/rpc/RpcClient";
-import * as RpcSerialization from "effect/rpc/RpcSerialization";
-import * as Schedule from "effect/Schedule";
-
-/**
- * A freshly-deployed Cloudflare Worker is not instantly reachable over HTTP.
- * Its `workers.dev` route, the script, and each binding (R2 / D1 / DO / Secrets
- * Store) propagate to the edge independently and asynchronously, so the first
- * requests to a new URL can transiently return:
- *
- *  - `404` while the `workers.dev` subdomain / route is still propagating
- *    (Cloudflare serves its "There is nothing here yet" placeholder), or
- *  - `5xx` while the script is up but a binding it depends on isn't ready yet.
- *
- * This is ordinary eventual consistency that belongs at the call site, not in
- * the resource provider — the provider returning before every edge PoP has
- * converged is correct. Consumers ride out the window by retrying the request.
- */
-export class WorkerNotReady extends Data.TaggedError("WorkerNotReady")<{ status: number }> {}
-
-/**
- * Status codes that indicate the edge hasn't finished converging on a fresh
- * deploy. Deliberate client errors (`401`, `403`, `400`, …) are NOT in this
- * set, so assertions on those statuses still observe them immediately rather
- * than being retried away.
- */
-const isColdStartStatus = (status: number): boolean => status === 404 || status >= 500;
-
-export interface WhenReadyOptions {
-  /** Max retry attempts before surfacing {@link WorkerNotReady}. Default `20`. */
-  times?: number;
-}
-
-/**
- * Execute an arbitrary {@link HttpClientRequest.HttpClientRequest}, retrying
- * through the Cloudflare cold-start window ({@link isColdStartStatus}) until the
- * Worker serves a non-transient response. The returned response can carry any
- * non-cold-start status (e.g. `200`, `202`, `401`) for the caller to assert on.
- */
-export const executeWhenReady = (
-  request: HttpClientRequest.HttpClientRequest,
-  options?: WhenReadyOptions,
-): Effect.Effect<HttpClientResponse, unknown, HttpClient.HttpClient> =>
-  Effect.gen(function* () {
-    const client = yield* HttpClient.HttpClient;
-    return yield* client.execute(request).pipe(
-      Effect.flatMap((response) =>
-        isColdStartStatus(response.status)
-          ? Effect.fail(new WorkerNotReady({ status: response.status }))
-          : Effect.succeed(response),
-      ),
-      Effect.retry({
-        while: (error) => error instanceof WorkerNotReady,
-        schedule: Schedule.max([
-          Schedule.exponential("500 millis"),
-          Schedule.recurs(options?.times ?? 20),
-        ]),
-      }),
-    );
-  });
-
-/**
- * Convenience wrapper over {@link executeWhenReady} for a plain `GET`.
- */
-export const getWhenReady = (
-  url: string,
-  options?: WhenReadyOptions,
-): Effect.Effect<HttpClientResponse, unknown, HttpClient.HttpClient> =>
-  executeWhenReady(HttpClientRequest.get(url), options);
-
-/**
- * Options for the edge-transient response guard applied by
- * {@link guardContentType} / {@link rpcClientLayer}. Pass per suite via
- * `Test.make({ http: { ... } })` or per call site.
- */
-export interface EdgeGuardOptions {
-  /**
-   * Retry schedule for edge-transient responses (and transport errors).
-   * Default: exponential from 500ms capped at 3s.
-   */
-  schedule?: Schedule.Schedule<unknown, unknown>;
-  /** Max transport-level retry attempts. Default `5`. */
-  times?: number;
-}
-
-const defaultGuardSchedule = Schedule.min([
-  Schedule.exponential("500 millis"),
-  Schedule.spaced("3 seconds"),
-]);
-
-/**
- * Guard an `HttpClient` against edge-generated bodies on a freshly deployed
- * Worker URL.
- *
- * Protocol clients like effect RPC's `layerProtocolHttp` never inspect the
- * response status or content-type — they pipe the raw body straight into the
- * serialization parser, so every edge-generated HTML page (the workers.dev
- * placeholder, which serves with HTTP **200**; 1101/1102 error pages;
- * 429/1015 rate limits) surfaces as an opaque decode defect (e.g.
- * `RpcClientDefect: Error decoding HTTP response`).
- *
- * This transform rejects any response whose `content-type` doesn't match the
- * expected one as a typed `HttpClientError` that records the status + a body
- * snippet — so a failure names its cause — and retries the request through a
- * bounded schedule so callers ride out the cold-start window
- * ({@link WorkerNotReady} documents why this belongs at the call site).
- */
-export const guardContentType =
-  (contentType: string, options?: EdgeGuardOptions) =>
-  (client: HttpClient.HttpClient): HttpClient.HttpClient =>
-    client.pipe(
-      HttpClient.transform((effect, request) =>
-        Effect.flatMap(effect, (response) => {
-          const observed = response.headers["content-type"] ?? "";
-          if (observed.includes(contentType)) {
-            return Effect.succeed(response);
-          }
-          return response.text.pipe(
-            Effect.orElseSucceed(() => "<unreadable body>"),
-            Effect.flatMap((body) =>
-              Effect.fail(
-                new HttpClientError({
-                  reason: new DecodeError({
-                    request,
-                    response,
-                    description: `expected "${contentType}", got "${observed}" (status ${response.status}): ${body.slice(0, 200)}`,
-                  }),
-                }),
-              ),
-            ),
-          );
-        }),
-      ),
-      HttpClient.retry({
-        schedule: options?.schedule ?? defaultGuardSchedule,
-        times: options?.times ?? 5,
-      }),
-    );
-
-/**
- * A fetch-backed `HttpClient` layer wrapped with {@link guardContentType}.
- *
- * Deliberately a standalone layer rather than a transform of the ambient
- * test `HttpClient`: the ambient client also serves the engine's own cloud
- * API calls during `deploy`/`destroy` and distilled SDK calls in
- * `test.provider` bodies, which must NOT be subjected to this guard.
- */
-export const guardedFetchLayer = (
-  contentType: string,
-  options?: EdgeGuardOptions,
-): Layer.Layer<HttpClient.HttpClient> =>
-  Layer.effect(HttpClient.HttpClient)(
-    Effect.gen(function* () {
-      const client = yield* HttpClient.HttpClient;
-      return guardContentType(contentType, options)(client);
-    }),
-  ).pipe(Layer.provide(FetchHttpClient.layer));
-
-/**
- * Complete RPC-over-HTTP client transport for driving a deployed Worker:
- * `RpcClient.layerProtocolHttp` + the given serialization (ndjson by
- * default) + a {@link guardedFetchLayer} expecting that serialization's
- * content-type.
- *
- * ```ts
- * const client = yield* RpcClient.make(WorkerRpcs);
- * // ...
- * }).pipe(Effect.scoped, Effect.provide(Test.Http.rpcClientLayer(url)));
- * ```
- */
-export const rpcClientLayer = (
-  url: string,
-  options?: EdgeGuardOptions & {
-    /** RPC wire serialization. Default {@link RpcSerialization.ndjson}. */
-    serialization?: RpcSerialization.RpcSerialization["Service"];
-    /**
-     * Set `false` to skip the edge guard entirely and use a plain fetch
-     * transport — e.g. for a test that asserts on the raw edge behavior
-     * itself. Default `true`.
-     */
-    guard?: boolean;
-  },
-): Layer.Layer<RpcClient.Protocol> => {
-  const serialization = options?.serialization ?? RpcSerialization.ndjson;
-  return RpcClient.layerProtocolHttp({ url }).pipe(
-    Layer.provide(
-      options?.guard === false
-        ? FetchHttpClient.layer
-        : guardedFetchLayer(serialization.contentType, options),
-    ),
-    Layer.provide(Layer.succeed(RpcSerialization.RpcSerialization, serialization)),
-  );
-};

package/src/Test/TestState.ts

@@ -1,35 +0,0 @@
-import * as Layer from "effect/Layer";
-import { Stack } from "../Stack.ts";
-import * as State from "../State/index.ts";
-
-export const state = (resources: Record<string, State.ResourceState> = {}) =>
-  Layer.effect(
-    State.State,
-    Stack.useSync((stack) =>
-      State.InMemoryService({
-        [stack.name]: {
-          [stack.stage]: resources,
-        },
-      }),
-    ),
-  );
-
-export const defaultState = (
-  resources: Record<string, State.ResourceState> = {},
-  other?: {
-    [stack: string]: {
-      [stage: string]: {
-        [resourceId: string]: State.ResourceState;
-      };
-    };
-  },
-) =>
-  Layer.succeed(
-    State.State,
-    State.InMemoryService({
-      ["test-app"]: {
-        ["test-stage"]: resources,
-      },
-      ...other,
-    }),
-  );

package/src/Test/Vitest.ts

@@ -1,239 +0,0 @@
-/** @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>;
-export const defaultStage = Core.defaultStage;
-export const resolveStage = Core.resolveStage;
-
-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: Core.Deploy;
-  destroy: (
-    stack: TestEffect<CompiledStack, Stage | AlchemyContext>,
-    options?: { stage?: string; include?: never; exclude?: never },
-  ) => 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");
-  // In dev mode, run local providers behind one file-scoped RPC sidecar
-  // (the `alchemy dev` topology). Lives in its own scope — NOT sharedScope,
-  // which `destroy(Stack)` closes mid-file in self-contained tests — and is
-  // closed by the fallback afterAll below.
-  const sidecar = Core.makeSidecarHandle(options);
-  const wrap = <A>(eff: TestEffect<A>) => Core.toEffect(eff, options, sharedScope, sidecar);
-  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options, sharedScope, sidecar);
-
-  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.live.only(name, () => wrap(eff), 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, sidecar);
-  };
-
-  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. The RPC sidecar lives in its
-  // own scope so that mid-file `destroy(Stack)` calls can't kill it for later
-  // tests.
-  //
-  // The cleanup must run after every user `afterAll` (including
-  // `destroy(Stack)`, which needs the sidecar). Vitest's default
-  // `sequence.hooks: "stack"` runs `afterAll` hooks in reverse registration
-  // order and `"list"` runs them in registration order, so register the
-  // cleanup both before (now) and after (next microtask) the file's
-  // `afterAll` calls, and only close on the second invocation: whichever
-  // order is configured, that one runs last.
-  const closeAll = sidecar ? Effect.andThen(closeScope, sidecar.close) : closeScope;
-  let cleanupCalls = 0;
-  const cleanup = () => (++cleanupCalls === 2 ? Effect.runPromise(closeAll) : undefined);
-  vitestAfterAll(cleanup, DEFAULT_TIMEOUT);
-  queueMicrotask(() => {
-    vitestAfterAll(cleanup, DEFAULT_TIMEOUT);
-  });
-
-  return {
-    test,
-    beforeAll,
-    beforeEach,
-    afterAll,
-    afterEach,
-    deploy: Core.makeDeploy(options, sharedScope),
-    destroy: (stack, callOpts) =>
-      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
-        Effect.ensuring(closeScope),
-      ),
-  };
-};

package/src/Test/index.ts

@@ -1,2 +0,0 @@
-export * from "./TestState.ts";
-export { ALCHEMY_TEST_DEV, defaultStage, resolveDev, resolveStage } from "./Core.ts";

package/src/Util/FileLogger.ts

@@ -1,20 +0,0 @@
-import * as Effect from "effect/Effect";
-import * as FileSystem from "effect/FileSystem";
-import * as Logger from "effect/Logger";
-import { Path } from "effect/Path";
-import { AlchemyContext } from "../AlchemyContext.ts";
-
-export const fileLogger = Effect.fn(function* (...segments: ReadonlyArray<string>) {
-  const { dotAlchemy } = yield* AlchemyContext;
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path;
-  const logFile = path.join(dotAlchemy, "log", ...segments);
-
-  yield* fs.makeDirectory(path.dirname(logFile), { recursive: true });
-
-  return yield* Logger.formatLogFmt.pipe(
-    Logger.toFile(logFile, {
-      flag: "a",
-    }),
-  );
-});