alchemy 2.0.0-beta.56 → 2.0.0-beta.57

package/src/AWS/CloudWatch/ListAlarmMuteRules.ts

@@ -9,6 +9,7 @@ export interface ListAlarmMuteRulesRequest
 
 /**
  * Runtime binding for `cloudwatch:ListAlarmMuteRules`.
+ * @binding
  */
 export class ListAlarmMuteRules extends Binding.Service<
   ListAlarmMuteRules,

package/src/AWS/CloudWatch/ListDashboards.ts

@@ -8,6 +8,7 @@ export interface ListDashboardsRequest extends cloudwatch.ListDashboardsInput {}
 
 /**
  * Runtime binding for `cloudwatch:ListDashboards`.
+ * @binding
  */
 export class ListDashboards extends Binding.Service<
   ListDashboards,

package/src/AWS/CloudWatch/ListManagedInsightRules.ts

@@ -9,6 +9,7 @@ export interface ListManagedInsightRulesRequest
 
 /**
  * Runtime binding for `cloudwatch:ListManagedInsightRules`.
+ * @binding
  */
 export class ListManagedInsightRules extends Binding.Service<
   ListManagedInsightRules,

package/src/AWS/CloudWatch/ListMetricStreams.ts

@@ -9,6 +9,7 @@ export interface ListMetricStreamsRequest
 
 /**
  * Runtime binding for `cloudwatch:ListMetricStreams`.
+ * @binding
  */
 export class ListMetricStreams extends Binding.Service<
   ListMetricStreams,

package/src/AWS/CloudWatch/ListMetrics.ts

@@ -8,6 +8,7 @@ export interface ListMetricsRequest extends cloudwatch.ListMetricsInput {}
 
 /**
  * Runtime binding for `cloudwatch:ListMetrics`.
+ * @binding
  */
 export class ListMetrics extends Binding.Service<
   ListMetrics,

package/src/AWS/CloudWatch/ListTagsForResource.ts

@@ -15,6 +15,7 @@ export interface ListTagsForResourceRequest extends Omit<
 
 /**
  * Runtime binding for `cloudwatch:ListTagsForResource`.
+ * @binding
  */
 export class ListTagsForResource extends Binding.Service<
   ListTagsForResource,

package/src/AWS/CloudWatch/MetricStream.ts

@@ -56,7 +56,7 @@ export interface MetricStream extends Resource<
 
 /**
  * A CloudWatch metric stream.
- *
+ * @resource
  * @section Creating Metric Streams
  * @example Firehose Delivery Stream
  * ```typescript

package/src/AWS/CloudWatch/PutMetricData.ts

@@ -8,6 +8,7 @@ export interface PutMetricDataRequest extends cloudwatch.PutMetricDataInput {}
 
 /**
  * Runtime binding for `cloudwatch:PutMetricData`.
+ * @binding
  */
 export class PutMetricData extends Binding.Service<
   PutMetricData,

package/src/AWS/CloudWatch/SetAlarmState.ts

@@ -12,6 +12,7 @@ export interface SetAlarmStateRequest extends Omit<
 
 /**
  * Runtime binding for `cloudwatch:SetAlarmState`.
+ * @binding
  */
 export class SetAlarmState extends Binding.Service<
   SetAlarmState,

package/src/AWS/DynamoDB/BatchExecuteStatement.ts

@@ -25,7 +25,7 @@ export interface BatchExecuteStatementRequest
  *
  * The request is passed through unchanged, but IAM is scoped to the explicitly
  * bound tables and their indexes.
- *
+ * @binding
  * @section PartiQL
  * @example Execute a Batch of Statements
  * ```typescript

package/src/AWS/DynamoDB/BatchGetItem.ts

@@ -33,7 +33,7 @@ export interface BatchGetItemRequest extends Omit<
  * Bind this operation to one or more tables and key the request by each bound
  * table's `LogicalId`. The binding resolves those logical IDs to physical table
  * names at runtime.
- *
+ * @binding
  * @section Reading Data
  * @example Read Items Across Multiple Tables
  * ```typescript

package/src/AWS/DynamoDB/BatchWriteItem.ts

@@ -32,7 +32,7 @@ export interface BatchWriteItemRequest extends Omit<
  *
  * Bind this operation to one or more tables and key the request by each bound
  * table's `LogicalId`.
- *
+ * @binding
  * @section Writing Data
  * @example Write Items Across Multiple Tables
  * ```typescript

package/src/AWS/DynamoDB/DeleteItem.ts

@@ -10,6 +10,7 @@ export interface DeleteItemRequest extends Omit<
   "TableName"
 > {}
 
+/** @binding */
 export class DeleteItem extends Binding.Service<
   DeleteItem,
   <T extends Table>(

package/src/AWS/DynamoDB/DescribeTable.ts

@@ -10,6 +10,7 @@ export interface DescribeTableRequest extends Omit<
   "TableName"
 > {}
 
+/** @binding */
 export class DescribeTable extends Binding.Service<
   DescribeTable,
   <T extends Table>(

package/src/AWS/DynamoDB/DescribeTimeToLive.ts

@@ -10,6 +10,7 @@ export interface DescribeTimeToLiveRequest extends Omit<
   "TableName"
 > {}
 
+/** @binding */
 export class DescribeTimeToLive extends Binding.Service<
   DescribeTimeToLive,
   <T extends Table>(

package/src/AWS/DynamoDB/ExecuteStatement.ts

@@ -14,7 +14,7 @@ export interface ExecuteStatementRequest
  *
  * This binding scopes IAM to a specific table, but the statement text is still
  * user-provided. Statements must only reference the bound table or its indexes.
- *
+ * @binding
  * @section PartiQL
  * @example Execute a Statement Against One Table
  * ```typescript

package/src/AWS/DynamoDB/ExecuteTransaction.ts

@@ -10,6 +10,7 @@ export interface ExecuteTransactionRequest
 
 type ExecuteTransactionTables = [Table, ...Table[]];
 
+/** @binding */
 export class ExecuteTransaction extends Binding.Service<
   ExecuteTransaction,
   (

package/src/AWS/DynamoDB/GetItem.ts

@@ -15,7 +15,7 @@ export interface GetItemRequest extends Omit<
  *
  * Bind this operation to a `Table` inside a function runtime to get a callable
  * that automatically injects the table name.
- *
+ * @binding
  * @section Reading Data
  * @example Read a Single Item
  * ```typescript

package/src/AWS/DynamoDB/ListTables.ts

@@ -6,6 +6,7 @@ import { isFunction } from "../Lambda/Function.ts";
 
 export interface ListTablesRequest extends DynamoDB.ListTablesInput {}
 
+/** @binding */
 export class ListTables extends Binding.Service<
   ListTables,
   () => Effect.Effect<

package/src/AWS/DynamoDB/ListTagsOfResource.ts

@@ -10,6 +10,7 @@ export interface ListTagsOfResourceRequest extends Omit<
   "ResourceArn"
 > {}
 
+/** @binding */
 export class ListTagsOfResource extends Binding.Service<
   ListTagsOfResource,
   <T extends Table>(

package/src/AWS/DynamoDB/PutItem.ts

@@ -10,6 +10,7 @@ export interface PutItemRequest extends Omit<
   "TableName"
 > {}
 
+/** @binding */
 export class PutItem extends Binding.Service<
   PutItem,
   <T extends Table>(

package/src/AWS/DynamoDB/Query.ts

@@ -8,6 +8,7 @@ import type { Table } from "./Table.ts";
 
 export interface QueryRequest extends Omit<DynamoDB.QueryInput, "TableName"> {}
 
+/** @binding */
 export class Query extends Binding.Service<
   Query,
   <T extends Table>(

package/src/AWS/DynamoDB/RestoreTableToPointInTime.ts

@@ -10,6 +10,7 @@ export interface RestoreTableToPointInTimeRequest extends Omit<
   "SourceTableArn" | "SourceTableName" | "TargetTableName"
 > {}
 
+/** @binding */
 export class RestoreTableToPointInTime extends Binding.Service<
   RestoreTableToPointInTime,
   <From extends Table, To extends Table>(

package/src/AWS/DynamoDB/Scan.ts

@@ -8,6 +8,7 @@ import type { Table } from "./Table.ts";
 
 export interface ScanRequest extends Omit<DynamoDB.ScanInput, "TableName"> {}
 
+/** @binding */
 export class Scan extends Binding.Service<
   Scan,
   <T extends Table>(

package/src/AWS/DynamoDB/Stream.ts

@@ -8,6 +8,7 @@ export type StreamRecord<Data> = TableRecord<Data>;
 
 export type StreamEvent<Data> = TableEvent<Data>;
 
+/** @binding */
 export class TableEventSource extends Binding.Service<
   TableEventSource,
   TableEventSourceService

package/src/AWS/DynamoDB/Table.ts

@@ -113,7 +113,7 @@ export interface Table extends Resource<
  * `Table` owns the lifecycle of the physical table while the binding contract
  * allows runtime-specific integrations such as Lambda table event sources to
  * request stream configuration without forcing a circular input prop.
- *
+ * @resource
  * @section Creating Tables
  * @example Basic Table
  * ```typescript
@@ -333,7 +333,14 @@ export const TableProvider = () =>
         error._tag === "InternalServerError" ||
         error._tag === "LimitExceededException" ||
         error._tag === "ResourceInUseException" ||
-        error._tag === "ResourceNotFoundException";
+        error._tag === "ResourceNotFoundException" ||
+        // Throttling: DynamoDB's control-plane API limits are low and the
+        // blanket SDK retry (10 attempts) is easily exhausted when the whole
+        // suite hammers create/update/describe concurrently. Give it the
+        // provider's much larger budget too.
+        error._tag === "ThrottlingException" ||
+        error._tag === "ProvisionedThroughputExceededException" ||
+        error._tag === "RequestLimitExceeded";
 
       const waitForControlPlaneConvergence = Schedule.fixed("1 second").pipe(
         Schedule.both(Schedule.recurs(120)),
@@ -649,7 +656,12 @@ export const TableProvider = () =>
       // resource" signal). Only retry on transient control-plane errors.
       const isRetryableReadError = (error: { _tag?: string }) =>
         error._tag === "InternalServerError" ||
-        error._tag === "LimitExceededException";
+        error._tag === "LimitExceededException" ||
+        // See `isRetryableControlPlaneError`: read-path describes throttle too
+        // under full-suite concurrency, so ride them out generously.
+        error._tag === "ThrottlingException" ||
+        error._tag === "ProvisionedThroughputExceededException" ||
+        error._tag === "RequestLimitExceeded";
 
       const readTableState = (tableName: string) =>
         Effect.gen(function* () {
@@ -947,15 +959,29 @@ export const TableProvider = () =>
               names,
               (tableName) =>
                 readTableState(tableName).pipe(
-                  // Hydrating every table fires four describe calls each;
-                  // across a busy account that trips DynamoDB's read throttle.
+                  // Hydrating every table fires four describe calls each.
+                  // Across a busy account this trips DynamoDB's read throttle,
+                  // and a table that isn't ACTIVE yet (a peer mid-create)
+                  // transiently rejects the continuous-backups/TTL describes
+                  // with ValidationException. Both are transient — retry to
+                  // converge so a table that *is* ours still hydrates fully.
                   Effect.retry({
-                    while: (e) => e._tag === "ThrottlingException",
+                    while: (e) =>
+                      e._tag === "ThrottlingException" ||
+                      e._tag === "ValidationException",
                     schedule: Schedule.exponential(250).pipe(
                       Schedule.jittered,
                       Schedule.both(Schedule.recurs(12)),
                     ),
                   }),
+                  // Last resort: if a foreign table never settles within the
+                  // retry budget (e.g. a peer is still mid-create/delete when
+                  // we give up), skip it rather than failing the whole
+                  // enumeration. Our own table is ACTIVE by the time list()
+                  // runs, so it always hydrates via the retry above.
+                  Effect.catchTag("ValidationException", () =>
+                    Effect.succeed(undefined),
+                  ),
                 ),
               { concurrency: 8 },
             );

package/src/AWS/DynamoDB/TransactGetItems.ts

@@ -38,7 +38,7 @@ export interface TransactGetItemsRequest extends Omit<
  *
  * Bind this operation to one or more tables and identify each table in the
  * request with the bound table's `LogicalId`.
- *
+ * @binding
  * @section Reading Data
  * @example Read Items Transactionally
  * ```typescript

package/src/AWS/DynamoDB/TransactWriteItems.ts

@@ -65,7 +65,7 @@ export interface TransactWriteItemsRequest extends Omit<
  *
  * Bind this operation to one or more tables and identify each item's target
  * table by the bound table's `LogicalId`.
- *
+ * @binding
  * @section Writing Data
  * @example Write Items Transactionally
  * ```typescript

package/src/AWS/DynamoDB/UpdateItem.ts

@@ -10,6 +10,7 @@ export interface UpdateItemRequest extends Omit<
   "TableName"
 > {}
 
+/** @binding */
 export class UpdateItem extends Binding.Service<
   UpdateItem,
   <T extends Table>(

package/src/AWS/DynamoDB/UpdateTimeToLive.ts

@@ -10,6 +10,7 @@ export interface UpdateTimeToLiveRequest extends Omit<
   "TableName"
 > {}
 
+/** @binding */
 export class UpdateTimeToLive extends Binding.Service<
   UpdateTimeToLive,
   <T extends Table>(

package/src/AWS/EC2/EIP.ts

@@ -102,6 +102,70 @@ export interface EIP extends Resource<
   never,
   Providers
 > {}
+/**
+ * An Elastic IP address — a static, public IPv4 address allocated to your AWS
+ * account that you can attach to instances, network interfaces, or NAT
+ * gateways.
+ *
+ * Allocating an `EIP` reserves the address; you then reference its
+ * `allocationId` from the resource that should use it (for example a public
+ * `NatGateway`). The address is released back to AWS when the resource is
+ * destroyed. The pool-related properties (`publicIpv4Pool`,
+ * `networkBorderGroup`, `customerOwnedIpv4Pool`) are immutable and replace the
+ * address when changed.
+ *
+ * @resource
+ * @section Allocating Elastic IPs
+ * By default an Elastic IP is allocated for use within a VPC (`domain: "vpc"`),
+ * which is the only domain available to modern accounts.
+ * @example VPC-Scoped Elastic IP
+ * ```typescript
+ * const eip = yield* AWS.EC2.EIP("MyEip", {
+ *   domain: "vpc",
+ *   tags: { Name: "app-eip" },
+ * });
+ * ```
+ * This reserves a standard, Amazon-owned public IPv4 address scoped to your VPC;
+ * `domain` defaults to `"vpc"`, so it can be omitted, and `tags` help you find
+ * the address in the console and on the bill.
+ *
+ * @section Bring-Your-Own-IP and Address Pools
+ * If you have onboarded an address range to AWS (BYOIP) or use Outposts, you can
+ * draw the address from a specific pool instead of Amazon's general pool.
+ * @example Allocate from a Public IPv4 (BYOIP) Pool
+ * ```typescript
+ * const eip = yield* AWS.EC2.EIP("ByoipEip", {
+ *   publicIpv4Pool: "ipv4pool-ec2-0abcdef1234567890",
+ *   networkBorderGroup: "us-east-1",
+ * });
+ * ```
+ * `publicIpv4Pool` selects an address from a pool you own rather than a random
+ * Amazon address, and `networkBorderGroup` restricts which zone group AWS
+ * advertises it from (useful for Local and Wavelength Zones).
+ *
+ * @example Allocate from a Customer-Owned Pool (Outposts)
+ * ```typescript
+ * const eip = yield* AWS.EC2.EIP("CoIpEip", {
+ *   customerOwnedIpv4Pool: "ipv4pool-coip-0abcdef1234567890",
+ * });
+ * ```
+ * `customerOwnedIpv4Pool` pulls a customer-owned IP (CoIP) from an
+ * Outposts-associated pool, for workloads that must use your own on-premises
+ * address space.
+ *
+ * @section Using an Elastic IP
+ * @example Attach to a NAT Gateway
+ * ```typescript
+ * const eip = yield* AWS.EC2.EIP("NatEip", {});
+ *
+ * const natGateway = yield* AWS.EC2.NatGateway("NatGateway", {
+ *   subnetId: publicSubnet.subnetId,
+ *   allocationId: eip.allocationId,
+ * });
+ * ```
+ * Downstream resources consume the reserved address through its `allocationId`;
+ * here the EIP becomes the fixed public IP of a NAT gateway.
+ */
 export const EIP = Resource<EIP>("AWS.EC2.EIP");
 
 export const EIPProvider = () =>

package/src/AWS/EC2/EgressOnlyInternetGateway.ts

@@ -66,6 +66,64 @@ export interface EgressOnlyInternetGateway extends Resource<
   never,
   Providers
 > {}
+/**
+ * An egress-only internet gateway is the IPv6 counterpart to a NAT gateway: it
+ * lets instances in a VPC initiate outbound IPv6 traffic to the internet while
+ * preventing the internet from initiating inbound connections to them. Use it
+ * to give private, IPv6-addressed resources outbound-only internet access.
+ *
+ * Unlike a NAT gateway it is free, has no bandwidth charges, and does not
+ * require an Elastic IP — but it works for IPv6 only. It always belongs to a
+ * VPC (`vpcId` is required); the gateway must be paired with an IPv6
+ * {@link Route} to actually carry traffic.
+ *
+ * @resource
+ * @section Creating an Egress-Only Internet Gateway
+ * The gateway is created and attached to `vpcId` in a single step. Because the
+ * attachment is intrinsic, changing `vpcId` replaces the gateway rather than
+ * moving it.
+ *
+ * @example Basic Egress-Only Internet Gateway
+ * ```typescript
+ * const egressOnlyIgw = yield* AWS.EC2.EgressOnlyInternetGateway("EgressOnlyIgw", {
+ *   vpcId: myVpc.vpcId,
+ * });
+ * ```
+ * Creates the gateway in the VPC. The resulting
+ * `egressOnlyInternetGatewayId` (prefixed `eigw-`) is referenced from a
+ * route's `egressOnlyInternetGatewayId` target.
+ *
+ * @example Egress-Only Internet Gateway with Tags
+ * ```typescript
+ * const egressOnlyIgw = yield* AWS.EC2.EgressOnlyInternetGateway("EgressOnlyIgw", {
+ *   vpcId: myVpc.vpcId,
+ *   tags: { Name: "production-eigw" },
+ * });
+ * ```
+ * The `tags` map is merged with the alchemy auto-tags and can be updated in
+ * place without replacing the gateway.
+ *
+ * @section Routing IPv6 Egress Traffic
+ * A gateway alone does nothing until a private route table sends IPv6 traffic
+ * to it. Pair it with a `::/0` {@link Route} so private, IPv6-addressed
+ * instances can reach the internet outbound-only.
+ *
+ * @example IPv6 Default Route to the Egress-Only Gateway
+ * ```typescript
+ * const egressOnlyIgw = yield* AWS.EC2.EgressOnlyInternetGateway("EgressOnlyIgw", {
+ *   vpcId: myVpc.vpcId,
+ * });
+ *
+ * const ipv6EgressRoute = yield* AWS.EC2.Route("Ipv6EgressRoute", {
+ *   routeTableId: privateRouteTable.routeTableId,
+ *   destinationIpv6CidrBlock: "::/0",
+ *   egressOnlyInternetGatewayId: egressOnlyIgw.egressOnlyInternetGatewayId,
+ * });
+ * ```
+ * Instances in subnets associated with `privateRouteTable` can now make
+ * outbound IPv6 connections (updates, API calls) while remaining unreachable
+ * from the public internet.
+ */
 export const EgressOnlyInternetGateway = Resource<EgressOnlyInternetGateway>(
   "AWS.EC2.EgressOnlyInternetGateway",
 );

package/src/AWS/EC2/Instance.ts

@@ -270,7 +270,7 @@ export type InstanceRuntimeContext = Ec2HostRuntimeContext;
 /**
  * An EC2 instance that can either act as a low-level compute primitive or run
  * a bundled long-lived Effect program directly on the machine.
- *
+ * @resource
  * @section Launching Instances
  * @example Basic Instance
  * ```typescript

package/src/AWS/EC2/InternetGateway.ts

@@ -62,6 +62,77 @@ export interface InternetGateway extends Resource<
   never,
   Providers
 > {}
+/**
+ * An internet gateway provides a target for internet-routable traffic in a
+ * VPC, enabling bidirectional IPv4 and IPv6 connectivity between resources in
+ * your VPC and the public internet. A VPC can have at most one internet
+ * gateway attached at a time.
+ *
+ * The only inputs are the optional `vpcId` to attach to and `tags`. Attaching a
+ * gateway is not enough on its own to make a subnet public — you also need a
+ * `0.0.0.0/0` {@link Route} pointing at the gateway and a
+ * {@link RouteTableAssociation} binding the subnet to that route table.
+ *
+ * @resource
+ * @section Creating an Internet Gateway
+ * Pass `vpcId` to create and attach the gateway in one step, or omit it to
+ * create a standalone gateway and attach it later by setting the prop. Updating
+ * `vpcId` moves the gateway between VPCs (detach then attach) without
+ * recreating it.
+ *
+ * @example Internet Gateway Attached to a VPC
+ * ```typescript
+ * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {
+ *   vpcId: myVpc.vpcId,
+ * });
+ * ```
+ * Creates the gateway and attaches it to the VPC immediately. The resulting
+ * `internetGatewayId` (prefixed `igw-`) is what you reference from a route's
+ * `gatewayId`.
+ *
+ * @example Detached Internet Gateway
+ * ```typescript
+ * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {});
+ * ```
+ * Omitting `vpcId` creates an unattached gateway. This is occasionally useful
+ * when the VPC is provisioned separately; add the `vpcId` prop later to attach
+ * it.
+ *
+ * @example Internet Gateway with Tags
+ * ```typescript
+ * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {
+ *   vpcId: myVpc.vpcId,
+ *   tags: { Name: "production-igw" },
+ * });
+ * ```
+ * The `tags` map is merged with the alchemy auto-tags and can be changed in
+ * place. A `Name` tag makes the gateway easy to identify in the AWS console.
+ *
+ * @section Enabling Public Internet Access
+ * An internet gateway only carries traffic once a route table sends traffic to
+ * it and a subnet is associated with that table. The full pattern below makes a
+ * subnet public.
+ *
+ * @example Internet Gateway with a Default Route
+ * ```typescript
+ * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {
+ *   vpcId: myVpc.vpcId,
+ * });
+ *
+ * const publicRouteTable = yield* AWS.EC2.RouteTable("PublicRouteTable", {
+ *   vpcId: myVpc.vpcId,
+ * });
+ *
+ * const internetRoute = yield* AWS.EC2.Route("InternetRoute", {
+ *   routeTableId: publicRouteTable.routeTableId,
+ *   destinationCidrBlock: "0.0.0.0/0",
+ *   gatewayId: internetGateway.internetGatewayId,
+ * });
+ * ```
+ * With the default route in place, any subnet associated with
+ * `publicRouteTable` can send and receive internet traffic. Add an analogous
+ * route with `destinationIpv6CidrBlock: "::/0"` to enable IPv6.
+ */
 export const InternetGateway = Resource<InternetGateway>(
   "AWS.EC2.InternetGateway",
 );

package/src/AWS/EC2/NatGateway.ts

@@ -159,6 +159,81 @@ export interface NatGateway extends Resource<
   never,
   Providers
 > {}
+/**
+ * A NAT gateway that lets instances in a private subnet reach the internet
+ * (and other AWS services) while preventing unsolicited inbound connections.
+ *
+ * The gateway lives in the subnet given by `subnetId`, and its
+ * `connectivityType` decides how it connects: a `"public"` gateway must sit in a
+ * *public* subnet and requires an Elastic IP via `allocationId`, while a
+ * `"private"` gateway has no public address and is used for VPC-to-VPC routing.
+ * A NAT gateway only carries traffic once a `Route` sends `0.0.0.0/0` from the
+ * private subnet's route table to it. Core properties (`subnetId`,
+ * `connectivityType`, `allocationId`) are immutable, so changing them replaces
+ * the gateway.
+ *
+ * @resource
+ * @section Public NAT Gateways
+ * Public gateways translate private addresses to a stable public IP, so they
+ * must be placed in a public subnet (one with a route to an internet gateway)
+ * and given an Elastic IP allocation.
+ * @example Public NAT Gateway with an Elastic IP
+ * ```typescript
+ * const eip = yield* AWS.EC2.EIP("NatEip", {});
+ *
+ * const natGateway = yield* AWS.EC2.NatGateway("NatGateway", {
+ *   subnetId: publicSubnet.subnetId,
+ *   allocationId: eip.allocationId,
+ *   connectivityType: "public",
+ *   tags: { Name: "production-nat" },
+ * });
+ * ```
+ * Allocating the EIP first and passing its `allocationId` gives the gateway a
+ * fixed public IP. `connectivityType` defaults to `"public"`, so it can be
+ * omitted; this is the standard way to give private instances outbound internet
+ * access.
+ *
+ * @section Private NAT Gateways
+ * Private gateways have no public IP and route traffic between VPCs or to
+ * on-premises networks without exposing it to the internet.
+ * @example Private NAT Gateway with a Fixed Private IP
+ * ```typescript
+ * const natGateway = yield* AWS.EC2.NatGateway("PrivateNat", {
+ *   subnetId: privateSubnet.subnetId,
+ *   connectivityType: "private",
+ *   privateIpAddress: "10.0.10.10",
+ * });
+ * ```
+ * Omitting `allocationId` and setting `connectivityType: "private"` creates a
+ * gateway with no public address; `privateIpAddress` pins it to a specific
+ * address in the subnet instead of letting AWS choose one automatically.
+ *
+ * @example Private NAT Gateway with Secondary Addresses
+ * ```typescript
+ * const natGateway = yield* AWS.EC2.NatGateway("ScaledNat", {
+ *   subnetId: privateSubnet.subnetId,
+ *   connectivityType: "private",
+ *   secondaryPrivateIpAddressCount: 3,
+ * });
+ * ```
+ * Secondary private addresses — via `secondaryPrivateIpAddressCount`,
+ * `secondaryPrivateIpAddresses`, or `secondaryAllocationIds` — raise the number
+ * of simultaneous connections a private gateway can sustain to busy
+ * destinations, which is only valid for private gateways.
+ *
+ * @section Routing Private Traffic
+ * @example Default Route Through the NAT Gateway
+ * ```typescript
+ * const natRoute = yield* AWS.EC2.Route("NatRoute", {
+ *   routeTableId: privateRouteTable.routeTableId,
+ *   destinationCidrBlock: "0.0.0.0/0",
+ *   natGatewayId: natGateway.natGatewayId,
+ * });
+ * ```
+ * Without a route the gateway is inert; this entry sends all outbound traffic
+ * from the private subnet's route table through the gateway so private instances
+ * can reach the internet.
+ */
 export const NatGateway = Resource<NatGateway>("AWS.EC2.NatGateway");
 
 export const NatGatewayProvider = () =>

package/src/AWS/EC2/Network.ts

@@ -102,7 +102,7 @@ export type Network = Effect.Success<ReturnType<typeof Network>>;
  *
  * The helper still returns the underlying canonical resources so callers can
  * keep composing with raw `AWS.EC2.*` APIs when they need more control.
- *
+ * @resource
  * @example Minimal network
  * ```typescript
  * const network = yield* AWS.EC2.Network("AppNetwork", {