alchemy 2.0.0-beta.2 → 2.0.0-beta.21

package/src/AWS/Lambda/Function.ts

@@ -23,16 +23,16 @@ import { Platform, type Main, type PlatformProps } from "../../Platform.ts";
 import type { LogLine, LogsInput } from "../../Provider.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource, type ResourceBinding } from "../../Resource.ts";
-import type { Providers } from "../Providers.ts";
 import * as Serverless from "../../Serverless/index.ts";
 import { Stack } from "../../Stack.ts";
 import { createInternalTags, createTagsList, hasTags } from "../../Tags.ts";
 import { sha256 } from "../../Util/sha256.ts";
 import { zipCode } from "../../Util/zip.ts";
-import { Account } from "../Account.ts";
 import { Assets } from "../Assets.ts";
+import { AWSEnvironment } from "../Environment.ts";
 import * as IAM from "../IAM/index.ts";
 import type { PolicyStatement } from "../IAM/Policy.ts";
+import type { Providers } from "../Providers.ts";
 import { makeFunctionHttpHandler } from "./HttpServer.ts";
 
 export const FunctionTypeId = "AWS.Lambda.Function" as const;
@@ -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.
+ *
+ * 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.
  *
- * @section Creating Functions
- * @example Basic Function
+ * 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,
@@ -195,7 +403,6 @@ export const Function: Platform<
           }),
           (handlers) =>
             async (event: any, context: lambda.Context): Promise<any> => {
-              console.log({ event, handlers });
               for (const handler of handlers) {
                 const eff = handler(event);
                 if (Effect.isEffect(eff)) {
@@ -220,7 +427,7 @@ export const FunctionProvider = () =>
     Function,
     Effect.gen(function* () {
       const stack = yield* Stack;
-      const accountId = yield* Account;
+      const { accountId } = yield* AWSEnvironment;
       const region = yield* Region;
       const fs = yield* FileSystem.FileSystem;
       const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
@@ -433,7 +640,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/Lambda/Permission.ts

@@ -90,7 +90,7 @@ export interface Permission extends Resource<
  *   functionName: yield* fn.functionArn(),
  *   principal: "s3.amazonaws.com",
  *   sourceArn: yield* bucket.bucketArn,
- *   sourceAccount: yield* Account,
+ *   sourceAccount: (yield* AWSEnvironment).accountId,
  * });
  * ```
  *

package/src/AWS/Logs/LogGroup.ts

@@ -7,8 +7,8 @@ import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import type { Providers } from "../Providers.ts";
 import { createInternalTags, diffTags } from "../../Tags.ts";
-import type { AccountID } from "../Account.ts";
-import { Account } from "../Account.ts";
+import type { AccountID } from "../Environment.ts";
+import { AWSEnvironment } from "../Environment.ts";
 import type { RegionID } from "../Region.ts";
 
 export type LogGroupName = string;
@@ -66,7 +66,7 @@ export const LogGroupProvider = () =>
     LogGroup,
     Effect.gen(function* () {
       const region = yield* Region;
-      const accountId = yield* Account;
+      const { accountId } = yield* AWSEnvironment;
 
       const toLogGroupName = (
         id: string,

package/src/AWS/Providers.ts

@@ -2,9 +2,9 @@ import * as Layer from "effect/Layer";
 import { Command, CommandProvider } from "../Build/Command.ts";
 import * as Provider from "../Provider.ts";
 import { Random, RandomProvider } from "../Random.ts";
-import * as Account from "./Account.ts";
 import * as ACM from "./ACM/index.ts";
 import * as Assets from "./Assets.ts";
+import { AwsAuth } from "./AuthProvider.ts";
 import * as AutoScaling from "./AutoScaling/index.ts";
 import * as CloudFront from "./CloudFront/index.ts";
 import * as CloudWatch from "./CloudWatch/index.ts";
@@ -32,7 +32,7 @@ import * as Scheduler from "./Scheduler/index.ts";
 import * as SecretsManager from "./SecretsManager/index.ts";
 import * as SNS from "./SNS/index.ts";
 import * as SQS from "./SQS/index.ts";
-import { DefaultStageConfig } from "./StageConfig.ts";
+import { Default as DefaultEnvironment } from "./Environment.ts";
 import * as Website from "./Website/index.ts";
 
 export class Providers extends Provider.ProviderCollection<Providers>()(
@@ -49,13 +49,18 @@ export const providers = () =>
       AutoScaling.AutoScalingGroup,
       AutoScaling.LaunchTemplate,
       AutoScaling.ScalingPolicy,
+      CloudFront.CachePolicy,
       CloudFront.Distribution,
       CloudFront.Function,
       CloudFront.Invalidation,
+      CloudFront.KeyGroup,
       CloudFront.KeyValueStore,
       CloudFront.KvEntries,
       CloudFront.KvRoutesUpdate,
       CloudFront.OriginAccessControl,
+      CloudFront.OriginRequestPolicy,
+      CloudFront.PublicKey,
+      CloudFront.ResponseHeadersPolicy,
       CloudWatch.Alarm,
       CloudWatch.AlarmMuteRule,
       CloudWatch.AnomalyDetector,
@@ -124,6 +129,7 @@ export const providers = () =>
       EC2.Vpc,
       EC2.VpcEndpoint,
       ECR.Repository,
+      ECS.CapacityProvider,
       ECS.Cluster,
       ECS.DescribeTasksPolicy,
       ECS.ListTasksPolicy,
@@ -282,13 +288,18 @@ export const providers = () =>
         AutoScaling.AutoScalingGroupProvider(),
         AutoScaling.LaunchTemplateProvider(),
         AutoScaling.ScalingPolicyProvider(),
+        CloudFront.CachePolicyProvider(),
         CloudFront.DistributionProvider(),
         CloudFront.FunctionProvider(),
         CloudFront.InvalidationProvider(),
+        CloudFront.KeyGroupProvider(),
         CloudFront.KeyValueStoreProvider(),
         CloudFront.KvEntriesProvider(),
         CloudFront.KvRoutesUpdateProvider(),
         CloudFront.OriginAccessControlProvider(),
+        CloudFront.OriginRequestPolicyProvider(),
+        CloudFront.PublicKeyProvider(),
+        CloudFront.ResponseHeadersPolicyProvider(),
         CloudWatch.AlarmMuteRuleProvider(),
         CloudWatch.AlarmProvider(),
         CloudWatch.AnomalyDetectorProvider(),
@@ -357,6 +368,7 @@ export const providers = () =>
         EC2.VpcEndpointProvider(),
         EC2.VpcProvider(),
         ECR.RepositoryProvider(),
+        ECS.CapacityProviderProvider(),
         ECS.ClusterProvider(),
         ECS.DescribeTasksPolicyLive,
         ECS.ListTasksPolicyLive,
@@ -516,10 +528,10 @@ export const providers = () =>
         Assets.AssetsProvider(),
       ),
     ),
-    Layer.provideMerge(Account.fromStageConfig()),
-    Layer.provideMerge(Region.fromStageConfig()),
-    Layer.provideMerge(Credentials.fromStageConfig()),
-    Layer.provideMerge(Endpoint.fromStageConfig()),
-    Layer.provideMerge(DefaultStageConfig),
+    Layer.provideMerge(Region.fromEnvironment),
+    Layer.provideMerge(Credentials.fromEnvironment),
+    Layer.provideMerge(Endpoint.fromEnvironment),
+    Layer.provideMerge(DefaultEnvironment),
+    Layer.provideMerge(AwsAuth),
     Layer.orDie,
   );

package/src/AWS/Region.ts

@@ -1,77 +1,20 @@
-import * as Auth from "@distilled.cloud/aws/Auth";
 import * as Region from "@distilled.cloud/aws/Region";
-import * as Config from "effect/Config";
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as Option from "effect/Option";
-import { StageConfig } from "./StageConfig.ts";
+import { AWSEnvironment } from "./Environment.ts";
 
 export { Region } from "@distilled.cloud/aws/Region";
-
-export const AWS_REGION = Config.string("AWS_REGION");
-
-export type RegionID = string;
+export { AWS_REGION, type RegionID } from "./Environment.ts";
 
 export const of = (region: string) => Layer.succeed(Region.Region, region);
 
 export const fromEnvOrElse = (region: string) =>
   Layer.succeed(Region.Region, process.env.AWS_REGION ?? region);
 
-export class EnvironmentVariableNotSet extends Data.TaggedError(
-  "EnvironmentVariableNotSet",
-)<{
-  message: string;
-  variable: string;
-}> {}
-
-const tryGetAWSRegion = () =>
-  Config.option(AWS_REGION).pipe(Config.map(Option.getOrUndefined));
-
-export const fromEnv = () =>
-  Layer.effect(
-    Region.Region,
-    Effect.gen(function* () {
-      const region = yield* tryGetAWSRegion();
-      if (!region) {
-        return yield* Effect.fail(
-          new EnvironmentVariableNotSet({
-            message: "AWS_REGION is not set",
-            variable: "AWS_REGION",
-          }),
-        );
-      }
-      return region;
-    }),
-  );
-
-export class AWSStageConfigRegionMissing extends Data.TaggedError(
-  "AWSStageConfigMissing",
-)<{
-  message: string;
-  stage: string;
-}> {}
-
-export const fromStageConfig = () =>
-  Layer.effect(
-    Region.Region,
-    Effect.gen(function* () {
-      const config = yield* StageConfig;
-      const auth = yield* Auth.Default;
-      if (config.region) {
-        return config.region;
-      } else if (config.profile) {
-        const profile = yield* auth.loadProfile(config.profile);
-        if (profile.region) {
-          return profile.region;
-        }
-      }
-      const region = yield* tryGetAWSRegion();
-      if (region) {
-        return region;
-      }
-      return yield* Effect.die(
-        "No AWS region found in stage config, SSO profile, or environment variable",
-      );
-    }),
-  );
+/**
+ * Derive the AWS region from the surrounding {@link AWSEnvironment}.
+ */
+export const fromEnvironment = Layer.effect(
+  Region.Region,
+  Effect.map(AWSEnvironment.asEffect(), (env) => env.region),
+);

package/src/AWS/S3/Bucket.ts

@@ -10,7 +10,7 @@ import * as Provider from "../../Provider.ts";
 import { Resource, type ResourceBinding } from "../../Resource.ts";
 import type { Providers } from "../Providers.ts";
 import { diffTags } from "../../Tags.ts";
-import { Account, type AccountID } from "../Account.ts";
+import { AWSEnvironment, type AccountID } from "../Environment.ts";
 import type { PolicyStatement } from "../IAM/Policy.ts";
 import type { RegionID } from "../Region.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) =>
@@ -250,7 +257,7 @@ export const BucketProvider = () =>
         news: BucketProps;
       }) {
         const region = yield* Region;
-        const accountId = yield* Account;
+        const { accountId } = yield* AWSEnvironment;
         const bucketName = yield* createBucketName(id, news);
 
         yield* Effect.logInfo(

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

@@ -6,7 +6,7 @@ import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import type { Providers } from "../Providers.ts";
 import { createInternalTags, createTagsList, diffTags } from "../../Tags.ts";
-import type { AccountID } from "../Account.ts";
+import type { AccountID } from "../Environment.ts";
 import type { RegionID } from "../Region.ts";
 
 export type TopicName = string;
@@ -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");