alchemy 2.0.0-beta.2 → 2.0.0-beta.test-export-fix-3

package/src/AWS/Lambda/Function.ts

@@ -116,25 +116,233 @@ export type FunctionShape = Main<FunctionServices>;
  * An AWS Lambda host resource that combines code bundling, IAM role
  * provisioning, and runtime binding collection.
  *
- * `Function` is the canonical runtime host for AWS. Resource bindings attach
- * environment variables and IAM statements during deployment, while the runtime
- * execution context collects listeners and exports from the Effect program.
+ * `Function` is the canonical runtime host for AWS. Alchemy automatically
+ * bundles your TypeScript entry module with Rolldown, creates an IAM
+ * execution role, and uploads the zip artifact. On subsequent deploys, the
+ * function is only updated when the bundle hash changes.
  *
- * @section Creating Functions
- * @example Basic Function
+ * There are two ways to define a Lambda Function:
+ *
+ * - **Async** — plain handler export, no Effect runtime in the bundle.
+ * - **Effect** — Effect implementation with typed bindings and event sources.
+ *
+ * See the {@link https://alchemy.run/guides/async-lambda | Async Lambda Guide}
+ * for plain handler patterns, or the
+ * {@link https://alchemy.run/guides/lambda | Effect Lambda Guide}
+ * for the full Effect-based approach with bindings, event sources, and sinks.
+ *
+ * @section Async Functions
+ * Point `main` at a file that exports a standard Lambda handler. No
+ * Effect runtime is included in the bundle. Useful when migrating
+ * existing Lambda functions or when you don't need Effect.
+ *
+ * @example Defining an async Lambda in your stack
  * ```typescript
- * const func = yield* Function("OrdersFunction", {
- *   main: "./src/orders.ts",
+ * // alchemy.run.ts
+ * import * as AWS from "alchemy/AWS";
+ *
+ * const func = yield* AWS.Lambda.Function("ApiFunction", {
+ *   main: "./src/handler.ts",
+ *   url: true,
  * });
  * ```
  *
+ * @example Writing the async handler
+ * ```typescript
+ * // src/handler.ts
+ * export const handler = async (event: any) => {
+ *   return {
+ *     statusCode: 200,
+ *     body: JSON.stringify({ message: "Hello from Lambda!" }),
+ *   };
+ * };
+ * ```
+ *
+ * @section Effect Functions
+ * Pass the Effect implementation as the third argument. Bindings
+ * attach IAM permissions and environment variables at deploy time,
+ * while the runtime execution context collects listeners and exports.
+ *
+ * @example Effect Function with HTTP handler
+ * ```typescript
+ * export default class ApiFunction extends AWS.Lambda.Function<ApiFunction>()(
+ *   "ApiFunction",
+ *   { main: import.meta.filename, url: true },
+ *   Effect.gen(function* () {
+ *     // init: bind resources
+ *     const getItem = yield* DynamoDB.GetItem.bind(table);
+ *
+ *     return {
+ *       // runtime: use them
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const url = new URL(request.url);
+ *         const id = url.searchParams.get("id");
+ *         const result = yield* getItem({ Key: { pk: { S: id! } } });
+ *         return yield* HttpServerResponse.json(result.Item);
+ *       }),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * @section Configuration
  * @example Function with URL
  * ```typescript
- * const func = yield* Function("ApiFunction", {
- *   main: "./src/api.ts",
+ * const func = yield* AWS.Lambda.Function("ApiFunction", {
+ *   main: "./src/handler.ts",
  *   url: true,
  * });
  * ```
+ *
+ * @example Function in a VPC
+ * ```typescript
+ * const func = yield* AWS.Lambda.Function("VpcFunction", {
+ *   main: "./src/handler.ts",
+ *   vpc: {
+ *     subnetIds: ["subnet-abc123", "subnet-def456"],
+ *     securityGroupIds: ["sg-xyz789"],
+ *   },
+ * });
+ * ```
+ *
+ * @section S3 Bindings
+ * Bind S3 operations in the init phase to give the function IAM
+ * permissions and inject the bucket name as an environment variable.
+ *
+ * @example Read and write S3 objects
+ * ```typescript
+ * // init
+ * const getObject = yield* S3.GetObject.bind(bucket);
+ * const putObject = yield* S3.PutObject.bind(bucket);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* putObject({ Key: "hello.txt", Body: "Hello!" });
+ *     const obj = yield* getObject({ Key: "hello.txt" });
+ *     return HttpServerResponse.text("OK");
+ *   }),
+ * };
+ * ```
+ *
+ * @section DynamoDB Bindings
+ * Bind DynamoDB operations in the init phase to grant table-scoped
+ * IAM permissions.
+ *
+ * @example Get and put items
+ * ```typescript
+ * // init
+ * const getItem = yield* DynamoDB.GetItem.bind(table);
+ * const putItem = yield* DynamoDB.PutItem.bind(table);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* putItem({ Item: { pk: { S: "user#1" }, name: { S: "Alice" } } });
+ *     const result = yield* getItem({ Key: { pk: { S: "user#1" } } });
+ *     return yield* HttpServerResponse.json(result.Item);
+ *   }),
+ * };
+ * ```
+ *
+ * @section SQS Bindings
+ * Bind SQS operations in the init phase to send messages to a queue.
+ *
+ * @example Send a message
+ * ```typescript
+ * // init
+ * const sendMessage = yield* SQS.SendMessage.bind(queue);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* sendMessage({
+ *       MessageBody: JSON.stringify({ orderId: "123" }),
+ *     });
+ *     return HttpServerResponse.text("Queued");
+ *   }),
+ * };
+ * ```
+ *
+ * @section SNS Bindings
+ * Bind SNS operations in the init phase to publish messages to a
+ * topic.
+ *
+ * @example Publish a notification
+ * ```typescript
+ * // init
+ * const publish = yield* SNS.Publish.bind(topic);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* publish({
+ *       Message: JSON.stringify({ event: "order.created" }),
+ *       Subject: "OrderCreated",
+ *     });
+ *     return HttpServerResponse.text("Published");
+ *   }),
+ * };
+ * ```
+ *
+ * @section Kinesis Bindings
+ * Bind Kinesis operations in the init phase to put records into a
+ * stream.
+ *
+ * @example Put a record
+ * ```typescript
+ * // init
+ * const putRecord = yield* Kinesis.PutRecord.bind(stream);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* putRecord({
+ *       PartitionKey: "order-123",
+ *       Data: new TextEncoder().encode(JSON.stringify({ orderId: "123" })),
+ *     });
+ *     return HttpServerResponse.text("Sent");
+ *   }),
+ * };
+ * ```
+ *
+ * @section Event Sources
+ * Lambda functions can be triggered by event sources like SQS queues,
+ * DynamoDB streams, S3 notifications, SNS topics, and Kinesis streams.
+ *
+ * @example Process SQS messages
+ * ```typescript
+ * yield* SQS.messages(queue).process(
+ *   Effect.fn(function* (message) {
+ *     yield* Effect.log(`Received: ${message.body}`);
+ *   }),
+ * );
+ * ```
+ *
+ * @example Process DynamoDB stream changes
+ * ```typescript
+ * yield* DynamoDB.streams(table, {
+ *   StreamViewType: "NEW_AND_OLD_IMAGES",
+ * }).process(
+ *   Effect.fn(function* (record) {
+ *     yield* Effect.log(`Change: ${record.eventName}`);
+ *   }),
+ * );
+ * ```
+ *
+ * @example Process S3 notifications
+ * ```typescript
+ * yield* S3.notifications(bucket, {
+ *   events: ["s3:ObjectCreated:*"],
+ * }).subscribe((stream) =>
+ *   stream.pipe(
+ *     Stream.runForEach((event) =>
+ *       Effect.log(`New object: ${event.key}`),
+ *     ),
+ *   ),
+ * );
+ * ```
  */
 export const Function: Platform<
   Function,
@@ -433,7 +641,7 @@ export const FunctionProvider = () =>
               virtualEntryPlugin(
                 (importPath) => `
 import { NodeServices } from "@effect/platform-node";
-import { Stack } from "alchemy-effect/Stack";
+import { Stack } from "alchemy/Stack";
 import * as Config from "effect/Config";
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Credentials from "@distilled.cloud/aws/Credentials";

package/src/AWS/S3/Bucket.ts

@@ -91,7 +91,7 @@ export interface Bucket extends Resource<
  * @section Creating a Bucket
  * @example Basic Bucket
  * ```typescript
- * import * as S3 from "alchemy-effect/AWS/S3";
+ * import * as S3 from "alchemy/AWS/S3";
  *
  * const bucket = yield* S3.Bucket("my-bucket", {});
  * ```
@@ -110,37 +110,44 @@ export interface Bucket extends Resource<
  * });
  * ```
  *
- * @section Reading Objects
- * @example Get an object from a bucket
- * ```typescript
- * const getObject = yield* S3.GetObject.bind(bucket);
- *
- * const response = yield* getObject({ Key: "hello.txt" });
- * ```
+ * @section Runtime Operations
+ * Bind S3 operations in the init phase and use them in runtime
+ * handlers. Bindings inject the bucket name and grant scoped IAM
+ * permissions automatically.
  *
- * @section Writing Objects
- * @example Put an object into a bucket
+ * @example Read and write objects
  * ```typescript
+ * // init
+ * const getObject = yield* S3.GetObject.bind(bucket);
  * const putObject = yield* S3.PutObject.bind(bucket);
  *
- * yield* putObject({
- *   Key: "hello.txt",
- *   Body: "Hello, World!",
- *   ContentType: "text/plain",
- * });
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* putObject({
+ *       Key: "hello.txt",
+ *       Body: "Hello, World!",
+ *       ContentType: "text/plain",
+ *     });
+ *     const response = yield* getObject({ Key: "hello.txt" });
+ *     return HttpServerResponse.text("OK");
+ *   }),
+ * };
  * ```
  *
- * @section Deleting Objects
- * @example Delete an object from a bucket
+ * @example Delete an object
  * ```typescript
+ * // init
  * const deleteObject = yield* S3.DeleteObject.bind(bucket);
- *
- * yield* deleteObject({ Key: "hello.txt" });
  * ```
  *
  * @section Event Notifications
+ * Subscribe to bucket events from the init phase. The subscription
+ * and Lambda invoke permissions are created automatically.
+ *
  * @example Process object creation events
  * ```typescript
+ * // init
  * yield* S3.notifications(bucket, {
  *   events: ["s3:ObjectCreated:*"],
  * }).subscribe((stream) =>

package/src/AWS/S3/BucketNotifications.ts

@@ -35,7 +35,7 @@ export interface NotificationsProps<Events extends S3EventType[]> {
  * @section Subscribing to Events
  * @example Process all object creation events
  * ```typescript
- * import * as S3 from "alchemy-effect/AWS/S3";
+ * import * as S3 from "alchemy/AWS/S3";
  *
  * yield* S3.notifications(bucket, {
  *   events: ["s3:ObjectCreated:*"],

package/src/AWS/SNS/Topic.ts

@@ -60,20 +60,30 @@ export interface Topic extends Resource<
  * An Amazon SNS topic for fan-out messaging and notifications.
  *
  * `Topic` owns the SNS topic lifecycle while raw AWS topic attributes remain
- * available through the `attributes` prop so the full core pub/sub surface can be
- * configured without waiting on additional typed wrappers.
+ * available through the `attributes` prop so the full core pub/sub surface can
+ * be configured without waiting on additional typed wrappers. A topic name is
+ * auto-generated unless you provide one explicitly.
  *
  * @section Creating Topics
  * @example Standard Topic
  * ```typescript
- * const topic = yield* Topic("OrdersTopic", {
- *   topicName: "orders-events",
+ * import * as SNS from "alchemy/AWS/SNS";
+ *
+ * const topic = yield* SNS.Topic("OrdersTopic");
+ * ```
+ *
+ * @example Topic with Display Name
+ * ```typescript
+ * const topic = yield* SNS.Topic("NotificationsTopic", {
+ *   attributes: {
+ *     DisplayName: "App Notifications",
+ *   },
  * });
  * ```
  *
  * @example FIFO Topic
  * ```typescript
- * const topic = yield* Topic("OrdersFifoTopic", {
+ * const topic = yield* SNS.Topic("OrdersFifoTopic", {
  *   fifo: true,
  *   attributes: {
  *     ContentBasedDeduplication: "true",
@@ -82,14 +92,41 @@ export interface Topic extends Resource<
  * ```
  *
  * @section Runtime Publishing
- * @example Publish from a Lambda Function
+ * Bind publish operations in the init phase and use them in runtime
+ * handlers.
+ *
+ * @example Publish from a handler
  * ```typescript
+ * // init
  * const publish = yield* SNS.Publish.bind(topic);
  *
- * yield* publish({
- *   Message: JSON.stringify({ orderId: "123" }),
- *   Subject: "OrderCreated",
- * });
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* publish({
+ *       Message: JSON.stringify({ orderId: "123" }),
+ *       Subject: "OrderCreated",
+ *     });
+ *     return HttpServerResponse.text("Published");
+ *   }),
+ * };
+ * ```
+ *
+ * @section Subscriptions
+ * Subscribe a Lambda function to process messages published to the
+ * topic. The subscription and invoke permissions are created
+ * automatically.
+ *
+ * @example Process topic notifications
+ * ```typescript
+ * // init
+ * yield* SNS.notifications(topic).subscribe((stream) =>
+ *   stream.pipe(
+ *     Stream.runForEach((message) =>
+ *       Effect.log(`Received: ${message.Message}`),
+ *     ),
+ *   ),
+ * );
  * ```
  */
 export const Topic = Resource<Topic>("AWS.SNS.Topic");

package/src/AWS/SQS/Queue.ts

@@ -87,6 +87,72 @@ export interface Queue extends Resource<
   Providers
 > {}
 
+/**
+ * An Amazon SQS queue for reliable, decoupled message processing.
+ *
+ * `Queue` owns the lifecycle of a standard or FIFO SQS queue. A queue name
+ * is auto-generated from the app, stage, and logical ID unless you provide
+ * one explicitly. FIFO queues automatically append the `.fifo` suffix.
+ *
+ * @section Creating Queues
+ * @example Standard Queue
+ * ```typescript
+ * import * as SQS from "alchemy/AWS/SQS";
+ *
+ * const queue = yield* SQS.Queue("OrdersQueue");
+ * ```
+ *
+ * @example FIFO Queue
+ * ```typescript
+ * const queue = yield* SQS.Queue("OrdersFifoQueue", {
+ *   fifo: true,
+ *   contentBasedDeduplication: true,
+ * });
+ * ```
+ *
+ * @example Queue with Custom Settings
+ * ```typescript
+ * const queue = yield* SQS.Queue("ProcessingQueue", {
+ *   visibilityTimeout: 120,
+ *   messageRetentionPeriod: 86400,
+ *   receiveMessageWaitTimeSeconds: 20,
+ * });
+ * ```
+ *
+ * @section Sending Messages
+ * Bind send operations in the init phase and use them in runtime
+ * handlers.
+ *
+ * @example Send a message from a handler
+ * ```typescript
+ * // init
+ * const sendMessage = yield* SQS.SendMessage.bind(queue);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* sendMessage({
+ *       MessageBody: JSON.stringify({ orderId: "123" }),
+ *     });
+ *     return HttpServerResponse.text("Queued");
+ *   }),
+ * };
+ * ```
+ *
+ * @section Event Sources
+ * Process messages from a queue using a Lambda event source mapping.
+ * Messages are automatically deleted after successful processing.
+ *
+ * @example Process queue messages
+ * ```typescript
+ * // init
+ * yield* SQS.messages(queue).process(
+ *   Effect.fn(function* (message) {
+ *     yield* Effect.log(`Received: ${message.body}`);
+ *   }),
+ * );
+ * ```
+ */
 export const Queue = Resource<Queue>("AWS.SQS.Queue");
 
 export const QueueProvider = () =>

package/src/Cloudflare/Container/Container.ts

@@ -48,6 +48,128 @@ export type Container = {
   interceptAllOutboundHttp(binding: Fetcher): Effect.Effect<void>;
 };
 
+/**
+ * A Cloudflare Container that runs a long-lived process alongside a
+ * Durable Object.
+ *
+ * Containers always use the **Container Layer** pattern — the class
+ * and `.make()` must live in separate files. A Container must be
+ * bound to a Durable Object, and the DO imports the class to get a
+ * typed handle. If the class and `.make()` lived in the same file,
+ * the DO's bundle would pull in all of the container's runtime
+ * dependencies (process spawners, Node APIs, SDKs, etc.), which
+ * would bloat the bundle and likely break the Cloudflare Workers
+ * runtime. Keeping them separate ensures the bundler only includes
+ * the tiny class in the DO's output.
+ *
+ * See the {@link https://alchemy.run/concepts/platform | Platform
+ * concept} page for how this fits into the async / effect / layer
+ * progression.
+ *
+ * @section Container Layer
+ * Define the class and `.make()` in separate files. The class
+ * declares the container's identity, configuration, and typed
+ * shape. `.make()` provides the runtime implementation as a
+ * default export. Use `Container.of` to construct the typed
+ * shape — it ensures your implementation matches the methods
+ * declared on the class.
+ *
+ * @example Container class
+ * ```typescript
+ * // src/Sandbox.ts
+ * export class Sandbox extends Cloudflare.Container<
+ *   Sandbox,
+ *   {
+ *     exec: (cmd: string) => Effect.Effect<{
+ *       exitCode: number;
+ *       stdout: string;
+ *       stderr: string;
+ *     }>;
+ *   }
+ * >()(
+ *   "Sandbox",
+ *   { main: import.meta.filename },
+ * ) {}
+ * ```
+ *
+ * @example Container .make()
+ * ```typescript
+ * // src/Sandbox.runtime.ts
+ * export default Sandbox.make(
+ *   Effect.gen(function* () {
+ *     const cp = yield* ChildProcessSpawner;
+ *
+ *     return Sandbox.of({
+ *       exec: (cmd) =>
+ *         cp.spawn(ChildProcess.make(cmd, { shell: true })).pipe(
+ *           Effect.map(({ exitCode, stdout, stderr }) => ({
+ *             exitCode, stdout, stderr,
+ *           })),
+ *           Effect.scoped,
+ *         ),
+ *       fetch: Effect.succeed(
+ *         HttpServerResponse.text("Hello from container!"),
+ *       ),
+ *     });
+ *   }),
+ * );
+ * ```
+ *
+ * @section Configuration
+ * The props object accepts `main` (entrypoint file), `instanceType`
+ * (compute size), `runtime` (`"bun"` or `"node"`), and
+ * `observability` settings. Use `Stack.useSync` to vary config by
+ * stage.
+ *
+ * @example Stage-dependent configuration
+ * ```typescript
+ * export class Sandbox extends Cloudflare.Container<Sandbox>()(
+ *   "Sandbox",
+ *   Stack.useSync((stack) => ({
+ *     main: import.meta.filename,
+ *     instanceType: stack.stage === "prod" ? "standard-1" : "dev",
+ *     observability: { logs: { enabled: true } },
+ *   })),
+ * ) {}
+ * ```
+ *
+ * @section Starting from a Durable Object
+ * Use `Cloudflare.Container.bind` in the outer init phase to bind
+ * the container class, then `Cloudflare.start` in the inner
+ * per-instance phase to start it. Because the DO only imports the
+ * class, the runtime implementation is completely excluded from the
+ * DO's bundle.
+ *
+ * @example Binding and starting a container
+ * ```typescript
+ * // init (outer Effect) — only imports the class
+ * const sandbox = yield* Cloudflare.Container.bind(Sandbox);
+ *
+ * // per-instance (inner Effect)
+ * return Effect.gen(function* () {
+ *   const container = yield* Cloudflare.start(sandbox);
+ *
+ *   return {
+ *     exec: (cmd: string) => container.exec(cmd),
+ *   };
+ * });
+ * ```
+ *
+ * @section HTTP Requests to Container Ports
+ * Use `getTcpPort` to get a `fetch` handle for a specific port on
+ * the running container. This lets you make HTTP requests to
+ * servers running inside the container process.
+ *
+ * @example Fetching from a container port
+ * ```typescript
+ * const container = yield* Cloudflare.start(sandbox);
+ * const { fetch } = yield* container.getTcpPort(3000);
+ *
+ * const response = yield* fetch(
+ *   HttpClientRequest.get("http://container/health"),
+ * );
+ * ```
+ */
 export const Container: Platform<
   ContainerApplication,
   ContainerServices,

package/src/Cloudflare/Container/ContainerApplication.ts

@@ -223,6 +223,9 @@ export type ContainerServices =
 
 export type ContainerShape = Main<ContainerServices>;
 
+/**
+ * @internal
+ */
 export interface ContainerApplication<Shape = unknown> extends Resource<
   ContainerTypeId,
   ContainerApplicationProps,
@@ -480,16 +483,16 @@ ${
   runtime === "bun"
     ? `
 import { BunServices } from "@effect/platform-bun";
-import { BunHttpServer } from "alchemy-effect/Http";
+import { BunHttpServer } from "alchemy/Http";
 const HttpServer = BunHttpServer;
 `
     : `
 import { NodeServices } from "@effect/platform-node";
-import { NodeHttpServer } from "alchemy-effect/Http";
+import { NodeHttpServer } from "alchemy/Http";
 const HttpServer = NodeHttpServer;
 `
 }
-import { Stack } from "alchemy-effect/Stack";
+import { Stack } from "alchemy/Stack";
 import * as Effect from "effect/Effect";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import * as Layer from "effect/Layer";

package/src/Cloudflare/Container/ContainerBinding.ts

@@ -5,10 +5,8 @@ import {
   toCloudflareFetcher,
   type Fetcher,
 } from "../Fetcher.ts";
-import {
-  DurableObjectNamespace,
-  DurableObjectState,
-} from "../Workers/DurableObject.ts";
+import { DurableObjectNamespace } from "../Workers/DurableObjectNamespace.ts";
+import { DurableObjectState } from "../Workers/DurableObjectState.ts";
 import { Worker } from "../Workers/Worker.ts";
 import type { Container } from "./Container.ts";
 import type { ContainerApplication } from "./ContainerApplication.ts";

package/src/Cloudflare/Container/StartContainer.ts

@@ -6,7 +6,7 @@ import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
 import { type Fetcher } from "../Fetcher.ts";
-import { DurableObjectState } from "../Workers/DurableObject.ts";
+import { DurableObjectState } from "../Workers/DurableObjectState.ts";
 import { type Container, ContainerError } from "./Container.ts";
 
 /**