alchemy 2.0.0-beta.2 → 2.0.0-beta.4

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/Auth/AuthProvider.ts

@@ -0,0 +1,33 @@
+import type * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+export class AuthError extends Schema.TaggedErrorClass<AuthError>()(
+  "AuthError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {}
+
+export interface AuthProvider<Config extends { method: string }, Credentials> {
+  readonly name: string;
+
+  configure(profileName: string): Effect.Effect<Config, AuthError>;
+
+  login(
+    profileName: string,
+    config: Config,
+  ): Effect.Effect<void, AuthError, never>;
+
+  logout(
+    profileName: string,
+    config: Config,
+  ): Effect.Effect<void, AuthError, never>;
+
+  prettyPrint(profileName: string, config: Config): Effect.Effect<void>;
+
+  read(
+    profileName: string,
+    config: Config,
+  ): Effect.Effect<Credentials, AuthError, never>;
+}

package/src/Auth/Credentials.ts

@@ -0,0 +1,56 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Redacted from "effect/Redacted";
+import path from "pathe";
+import { rootDir } from "./Profile.ts";
+
+const credentialsDirPath = path.join(rootDir, "credentials");
+
+export const credentialsFilePath = (profile: string, provider: string) =>
+  path.join(credentialsDirPath, profile, `${provider}.json`);
+
+export const readCredentials = Effect.fnUntraced(function* <T>(
+  profile: string,
+  provider: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const data = yield* fs
+    .readFileString(credentialsFilePath(profile, provider))
+    .pipe(Effect.catch(() => Effect.succeed(undefined)));
+  if (data === undefined) return undefined as T | undefined;
+  try {
+    return JSON.parse(data) as T;
+  } catch {
+    return undefined as T | undefined;
+  }
+});
+
+export const writeCredentials = Effect.fnUntraced(function* <T>(
+  profile: string,
+  provider: string,
+  credentials: T,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const filePath = credentialsFilePath(profile, provider);
+  yield* fs.makeDirectory(path.dirname(filePath), { recursive: true });
+  yield* fs.writeFileString(filePath, JSON.stringify(credentials, null, 2));
+});
+
+export const deleteCredentials = Effect.fnUntraced(function* (
+  profile: string,
+  provider: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  yield* fs
+    .remove(credentialsFilePath(profile, provider))
+    .pipe(Effect.catch(() => Effect.void));
+});
+
+export function displayRedacted(
+  r: Redacted.Redacted<string>,
+  visibleChars = 4,
+): string {
+  const raw = Redacted.value(r);
+  if (raw.length <= visibleChars) return "****";
+  return `${raw.slice(0, visibleChars)}****`;
+}

package/src/Auth/Env.ts

@@ -0,0 +1,45 @@
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Clank from "../Util/Clank.ts";
+import { AuthError } from "./AuthProvider.ts";
+
+export const getEnv = (key: string) =>
+  Config.string(key)
+    .asEffect()
+    .pipe(Effect.orElseSucceed(() => undefined));
+
+export const getEnvRequired = (key: string) =>
+  Config.string(key)
+    .asEffect()
+    .pipe(
+      Effect.catch(() =>
+        Effect.fail(new AuthError({ message: `Missing required env: ${key}` })),
+      ),
+    );
+
+export const getEnvRedacted = (key: string) =>
+  Config.redacted(key)
+    .asEffect()
+    .pipe(Effect.orElseSucceed(() => undefined));
+
+export const getEnvRedactedRequired = (key: string) =>
+  Config.redacted(key)
+    .asEffect()
+    .pipe(
+      Effect.catch(() =>
+        Effect.fail(new AuthError({ message: `Missing required env: ${key}` })),
+      ),
+    );
+
+export const retryOnce = <A, R>(
+  self: Effect.Effect<A, Clank.PromptCancelled, R>,
+) =>
+  self.pipe(
+    Effect.retry({
+      times: 1,
+      while: (e) => e instanceof Clank.PromptCancelled,
+    }),
+    Effect.mapError(
+      (e) => new AuthError({ message: "User cancelled prompt", cause: e }),
+    ),
+  );

package/src/Auth/Profile.ts

@@ -0,0 +1,72 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import type { PlatformError } from "effect/PlatformError";
+import os from "node:os";
+import path from "pathe";
+
+export const rootDir = path.join(os.homedir(), ".alchemy");
+export const configFilePath = path.join(rootDir, "profiles.json");
+
+export const CONFIG_VERSION = 2;
+
+export interface AlchemyProfiles {
+  version: typeof CONFIG_VERSION;
+  profiles: Record<string, AlchemyProfile>;
+}
+
+export type AlchemyProfile = Record<string, { method: string }>;
+
+const emptyConfig = (): AlchemyProfiles => ({
+  version: CONFIG_VERSION,
+  profiles: {},
+});
+
+export const readConfig: Effect.Effect<
+  AlchemyProfiles,
+  never,
+  FileSystem.FileSystem
+> = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const data = yield* fs
+    .readFileString(configFilePath)
+    .pipe(Effect.orElseSucceed(() => undefined));
+  if (data === undefined) return emptyConfig();
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed?.version !== CONFIG_VERSION) {
+      return emptyConfig();
+    }
+    return parsed as AlchemyProfiles;
+  } catch {
+    return emptyConfig();
+  }
+});
+
+export const writeConfig = (
+  config: AlchemyProfiles,
+): Effect.Effect<void, PlatformError, FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.makeDirectory(path.dirname(configFilePath), {
+      recursive: true,
+    });
+    yield* fs.writeFileString(configFilePath, JSON.stringify(config, null, 2));
+  });
+
+export const getProfile = (
+  name: string,
+): Effect.Effect<AlchemyProfile | undefined, never, FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const config = yield* readConfig;
+    return config.profiles[name];
+  });
+
+export const setProfile = (
+  name: string,
+  profile: AlchemyProfile,
+): Effect.Effect<void, PlatformError, FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const config = yield* readConfig;
+    config.profiles[name] = profile;
+    yield* writeConfig(config);
+  });