@intentius/chant-lexicon-aws 0.46.0 → 0.50.0

package/src/composites/composites.test.ts

@@ -13,9 +13,12 @@ import { VpcDefault } from "./vpc-default";
 import { FargateAlb } from "./fargate-alb";
 import { AlbShared } from "./alb-shared";
 import { FargateService } from "./fargate-service";
+import { NlbService } from "./nlb-service";
 import { RdsInstance } from "./rds-instance";
 import { Ec2InstanceRole } from "./ec2-instance-role";
+import { Ec2InstanceBundle } from "./ec2-instance-bundle";
 import { MinimalVpc } from "./minimal-vpc";
+import { StepFunctionsWorkflow } from "./step-functions-workflow";
 
 const baseProps = {
   name: "TestFunc",
@@ -639,6 +642,112 @@ describe("FargateService", () => {
   });
 });
 
+describe("NlbService", () => {
+  const nlbProps = {
+    vpcId: "vpc-123",
+    subnetIds: ["subnet-pub1", "subnet-pub2"],
+  };
+
+  test("returns 3 members with correct names", () => {
+    const instance = NlbService(nlbProps);
+    const names = Object.keys(instance.members);
+    expect(names).toEqual(["nlb", "targetGroup", "listener"]);
+  });
+
+  test("expandComposite produces correct logical names", () => {
+    const expanded = expandComposite("app", NlbService(nlbProps));
+    expect(expanded.has("appNlb")).toBe(true);
+    expect(expanded.has("appTargetGroup")).toBe(true);
+    expect(expanded.has("appListener")).toBe(true);
+    expect(expanded.size).toBe(3);
+  });
+
+  test("NLB has Type network and given subnets", () => {
+    const instance = NlbService(nlbProps);
+    const nlbResourceProps = (instance.nlb as any).props;
+    expect(nlbResourceProps.Type).toBe("network");
+    expect(nlbResourceProps.Scheme).toBe("internet-facing");
+    expect(nlbResourceProps.Subnets).toEqual(["subnet-pub1", "subnet-pub2"]);
+  });
+
+  test("no security group is created", () => {
+    const instance = NlbService(nlbProps);
+    expect(Object.keys(instance.members)).not.toContain("albSg");
+    expect(Object.keys(instance.members)).not.toContain("nlbSg");
+  });
+
+  test("defaults: TCP protocol, port 80, ip target type", () => {
+    const instance = NlbService(nlbProps);
+    const tgProps = (instance.targetGroup as any).props;
+    expect(tgProps.Protocol).toBe("TCP");
+    expect(tgProps.Port).toBe(80);
+    expect(tgProps.TargetType).toBe("ip");
+    expect(tgProps.HealthCheckProtocol).toBe("TCP");
+
+    const listenerProps = (instance.listener as any).props;
+    expect(listenerProps.Protocol).toBe("TCP");
+    expect(listenerProps.Port).toBe(80);
+  });
+
+  test("targetPort defaults to listenerPort but can be overridden", () => {
+    const instance = NlbService({ ...nlbProps, listenerPort: 443, targetPort: 8443 });
+    const tgProps = (instance.targetGroup as any).props;
+    expect(tgProps.Port).toBe(8443);
+    const listenerProps = (instance.listener as any).props;
+    expect(listenerProps.Port).toBe(443);
+  });
+
+  test("listener forwards to the target group", () => {
+    const instance = NlbService(nlbProps);
+    const listenerProps = (instance.listener as any).props;
+    expect(listenerProps.DefaultActions).toHaveLength(1);
+    const action = (listenerProps.DefaultActions[0] as any).props;
+    expect(action.Type).toBe("forward");
+  });
+
+  test("static targets are registered on the target group", () => {
+    const instance = NlbService({
+      ...nlbProps,
+      targetType: "instance",
+      targets: [{ id: "i-0123456789abcdef0", port: 8080 }],
+    });
+    const tgProps = (instance.targetGroup as any).props;
+    expect(tgProps.TargetType).toBe("instance");
+    expect(tgProps.Targets).toHaveLength(1);
+    const target = (tgProps.Targets[0] as any).props;
+    expect(target.Id).toBe("i-0123456789abcdef0");
+    expect(target.Port).toBe(8080);
+  });
+
+  test("internal scheme is respected", () => {
+    const instance = NlbService({ ...nlbProps, scheme: "internal" });
+    const nlbResourceProps = (instance.nlb as any).props;
+    expect(nlbResourceProps.Scheme).toBe("internal");
+  });
+
+  test("TLS protocol adds certificate to listener", () => {
+    const instance = NlbService({
+      ...nlbProps,
+      protocol: "TLS",
+      certificateArn: "arn:aws:acm:us-east-1:123:certificate/abc",
+    });
+    const listenerProps = (instance.listener as any).props;
+    expect(listenerProps.Protocol).toBe("TLS");
+    expect(listenerProps.Certificates).toHaveLength(1);
+    const cert = (listenerProps.Certificates[0] as any).props;
+    expect(cert.CertificateArn).toBe("arn:aws:acm:us-east-1:123:certificate/abc");
+
+    const tgProps = (instance.targetGroup as any).props;
+    expect(tgProps.Protocol).toBe("TLS");
+  });
+
+  test("throws when protocol is TLS without a certificateArn", () => {
+    expect(() =>
+      NlbService({ ...nlbProps, protocol: "TLS" }),
+    ).toThrow("NlbService requires certificateArn when protocol is TLS");
+  });
+});
+
 describe("RdsInstance", () => {
   const rdsProps = {
     vpcId: "vpc-123",
@@ -897,6 +1006,140 @@ describe("Ec2InstanceRole", () => {
   });
 });
 
+describe("Ec2InstanceBundle", () => {
+  const instanceProps = {
+    imageId: "ami-0abcdef1234567890",
+    vpcId: "vpc-123",
+    subnetId: "subnet-456",
+  };
+
+  test("returns role, instanceProfile, sg, instance members", () => {
+    const instance = Ec2InstanceBundle(instanceProps);
+    expect(Object.keys(instance.members)).toEqual(["role", "instanceProfile", "sg", "instance"]);
+  });
+
+  test("expandComposite produces correct logical names", () => {
+    const expanded = expandComposite("web", Ec2InstanceBundle(instanceProps));
+    expect(expanded.has("webRole")).toBe(true);
+    expect(expanded.has("webInstanceProfile")).toBe(true);
+    expect(expanded.has("webSg")).toBe(true);
+    expect(expanded.has("webInstance")).toBe(true);
+    expect(expanded.size).toBe(4);
+  });
+
+  test("role has EC2 trust policy", () => {
+    const instance = Ec2InstanceBundle(instanceProps);
+    const roleProps = (instance.role as any).props;
+    expect(roleProps.AssumeRolePolicyDocument.Statement[0].Principal.Service).toBe("ec2.amazonaws.com");
+  });
+
+  test("instanceProfile references the role", () => {
+    const instance = Ec2InstanceBundle(instanceProps);
+    const profileProps = (instance.instanceProfile as any).props;
+    expect(profileProps.Roles).toHaveLength(1);
+  });
+
+  test("ManagedPolicyArns and Policies pass through to the role", () => {
+    const arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore";
+    const instance = Ec2InstanceBundle({
+      ...instanceProps,
+      ManagedPolicyArns: [arn],
+      Policies: [{ PolicyName: "extra", PolicyDocument: { Version: "2012-10-17", Statement: [] } }],
+    });
+    const roleProps = (instance.role as any).props;
+    expect(roleProps.ManagedPolicyArns).toContain(arn);
+    expect(roleProps.Policies).toHaveLength(1);
+  });
+
+  test("instance wires ImageId, InstanceType default, subnet, SG, and instance profile", () => {
+    const instance = Ec2InstanceBundle(instanceProps);
+    const instanceProps_ = (instance.instance as any).props;
+    expect(instanceProps_.ImageId).toBe("ami-0abcdef1234567890");
+    expect(instanceProps_.InstanceType).toBe("t3.micro");
+    expect(instanceProps_.SubnetId).toBe("subnet-456");
+    expect(instanceProps_.SecurityGroupIds).toHaveLength(1);
+    expect(instanceProps_.IamInstanceProfile).toBeDefined();
+  });
+
+  test("custom instanceType is respected", () => {
+    const instance = Ec2InstanceBundle({ ...instanceProps, instanceType: "m5.large" });
+    expect((instance.instance as any).props.InstanceType).toBe("m5.large");
+  });
+
+  test("keyName is passed through when provided", () => {
+    const instance = Ec2InstanceBundle({ ...instanceProps, keyName: "my-key" });
+    expect((instance.instance as any).props.KeyName).toBe("my-key");
+  });
+
+  test("keyName is omitted by default", () => {
+    const instance = Ec2InstanceBundle(instanceProps);
+    expect((instance.instance as any).props.KeyName).toBeUndefined();
+  });
+
+  test("userData is wrapped in Fn::Base64", () => {
+    const instance = Ec2InstanceBundle({ ...instanceProps, userData: "#!/bin/bash\necho hi" });
+    const userData = (instance.instance as any).props.UserData;
+    expect(JSON.stringify(userData)).toContain("Fn::Base64");
+  });
+
+  test("no ingress rules by default", () => {
+    const instance = Ec2InstanceBundle(instanceProps);
+    expect((instance.sg as any).props.SecurityGroupIngress).toBeUndefined();
+  });
+
+  test("ingress with cidr produces a CidrIp rule", () => {
+    const instance = Ec2InstanceBundle({
+      ...instanceProps,
+      ingress: [{ fromPort: 22, cidr: "10.0.0.0/16", description: "ssh" }],
+    });
+    const rules = (instance.sg as any).props.SecurityGroupIngress;
+    expect(rules).toHaveLength(1);
+    const rule = (rules[0] as any).props;
+    expect(rule.CidrIp).toBe("10.0.0.0/16");
+    expect(rule.FromPort).toBe(22);
+    expect(rule.ToPort).toBe(22);
+    expect(rule.IpProtocol).toBe("tcp");
+    expect(rule.Description).toBe("ssh");
+  });
+
+  test("ingress with sourceSecurityGroupId produces a SG-sourced rule", () => {
+    const instance = Ec2InstanceBundle({
+      ...instanceProps,
+      ingress: [{ fromPort: 80, toPort: 8080, sourceSecurityGroupId: "sg-abc123" }],
+    });
+    const rule = ((instance.sg as any).props.SecurityGroupIngress[0] as any).props;
+    expect(rule.SourceSecurityGroupId).toBe("sg-abc123");
+    expect(rule.FromPort).toBe(80);
+    expect(rule.ToPort).toBe(8080);
+  });
+
+  test("ingress with cidrIpv6 produces an IPv6 rule", () => {
+    const instance = Ec2InstanceBundle({
+      ...instanceProps,
+      ingress: [{ fromPort: 443, cidrIpv6: "::/0" }],
+    });
+    const rule = ((instance.sg as any).props.SecurityGroupIngress[0] as any).props;
+    expect(rule.CidrIpv6).toBe("::/0");
+  });
+
+  test("ingress rule with no source throws", () => {
+    expect(() =>
+      Ec2InstanceBundle({ ...instanceProps, ingress: [{ fromPort: 22 }] }),
+    ).toThrow(/needs one of cidr, cidrIpv6, or sourceSecurityGroupId/);
+  });
+
+  test("multiple ingress rules are all applied", () => {
+    const instance = Ec2InstanceBundle({
+      ...instanceProps,
+      ingress: [
+        { fromPort: 22, cidr: "10.0.0.0/16" },
+        { fromPort: 443, cidr: "0.0.0.0/0" },
+      ],
+    });
+    expect((instance.sg as any).props.SecurityGroupIngress).toHaveLength(2);
+  });
+});
+
 describe("MinimalVpc", () => {
   test("returns 8 members", () => {
     const instance = MinimalVpc({});
@@ -930,3 +1173,85 @@ describe("MinimalVpc", () => {
     expect(expanded.size).toBe(8);
   });
 });
+
+describe("StepFunctionsWorkflow", () => {
+  const passDefinition = { StartAt: "Hello", States: { Hello: { Type: "Pass", End: true } } };
+
+  test("returns role, logGroup, stateMachine members", () => {
+    const instance = StepFunctionsWorkflow({ definition: passDefinition });
+    expect(Object.keys(instance.members)).toEqual(["role", "logGroup", "stateMachine"]);
+  });
+
+  test("role has states.amazonaws.com trust policy", () => {
+    const instance = StepFunctionsWorkflow({ definition: passDefinition });
+    const roleProps = (instance.role as any).props;
+    expect(roleProps.AssumeRolePolicyDocument.Statement[0].Principal.Service).toBe("states.amazonaws.com");
+  });
+
+  test("role always carries the log-delivery policy", () => {
+    const instance = StepFunctionsWorkflow({ definition: passDefinition });
+    const roleProps = (instance.role as any).props;
+    const names = roleProps.Policies.map((p: any) => p.props.PolicyName);
+    expect(names).toContain("StepFunctionsLogDelivery");
+  });
+
+  test("lambdaFunctionArns grants InvokeFunction on those ARNs", () => {
+    const instance = StepFunctionsWorkflow({
+      definition: passDefinition,
+      lambdaFunctionArns: ["arn:aws:lambda:us-east-1:123456789012:function:worker"],
+    });
+    const roleProps = (instance.role as any).props;
+    const invokePolicy = roleProps.Policies.find((p: any) => p.props.PolicyName === "InvokeLambdaTasks");
+    expect(invokePolicy).toBeDefined();
+    expect(invokePolicy.props.PolicyDocument.Statement[0].Resource).toEqual([
+      "arn:aws:lambda:us-east-1:123456789012:function:worker",
+    ]);
+  });
+
+  test("without lambdaFunctionArns, no InvokeLambdaTasks policy", () => {
+    const instance = StepFunctionsWorkflow({ definition: passDefinition });
+    const roleProps = (instance.role as any).props;
+    const names = roleProps.Policies.map((p: any) => p.props.PolicyName);
+    expect(names).not.toContain("InvokeLambdaTasks");
+  });
+
+  test("stateMachine carries the definition object as Definition (not a string)", () => {
+    const instance = StepFunctionsWorkflow({ definition: passDefinition });
+    const smProps = (instance.stateMachine as any).props;
+    expect(smProps.Definition).toEqual(passDefinition);
+    expect(smProps.DefinitionString).toBeUndefined();
+  });
+
+  test("stateMachine references role.Arn and defaults to STANDARD", () => {
+    const instance = StepFunctionsWorkflow({ definition: passDefinition });
+    const smProps = (instance.stateMachine as any).props;
+    expect(smProps.RoleArn).toBeInstanceOf(AttrRef);
+    expect(smProps.StateMachineType).toBe("STANDARD");
+  });
+
+  test("logGroup defaults to 14-day retention, overridable", () => {
+    const defaultInstance = StepFunctionsWorkflow({ definition: passDefinition });
+    expect((defaultInstance.logGroup as any).props.RetentionInDays).toBe(14);
+
+    const overridden = StepFunctionsWorkflow({ definition: passDefinition, logRetentionDays: 30 });
+    expect((overridden.logGroup as any).props.RetentionInDays).toBe(30);
+  });
+
+  test("LoggingConfiguration wires the log group and defaults level to ALL", () => {
+    const instance = StepFunctionsWorkflow({ definition: passDefinition });
+    const smProps = (instance.stateMachine as any).props;
+    const loggingProps = (smProps.LoggingConfiguration as any).props;
+    expect(loggingProps.Level).toBe("ALL");
+    const destProps = (loggingProps.Destinations[0] as any).props;
+    const cwProps = (destProps.CloudWatchLogsLogGroup as any).props;
+    expect(cwProps.LogGroupArn).toBeInstanceOf(AttrRef);
+  });
+
+  test("expandComposite produces 3 entries", () => {
+    const expanded = expandComposite("workflow", StepFunctionsWorkflow({ definition: passDefinition }));
+    expect(expanded.has("workflowRole")).toBe(true);
+    expect(expanded.has("workflowLogGroup")).toBe(true);
+    expect(expanded.has("workflowStateMachine")).toBe(true);
+    expect(expanded.size).toBe(3);
+  });
+});

package/src/composites/dynamodb-table.test.ts

@@ -0,0 +1,154 @@
+import { describe, test, expect } from "vitest";
+import { expandComposite } from "@intentius/chant";
+import { DynamoDBTable } from "./dynamodb-table";
+
+// Generated property-kind instances (Table_KeySchema, Table_Projection, ...) store
+// their data on a non-enumerable `.props`, so `toEqual` against a plain object
+// compares empty own-enumerable-property sets unless each instance is unwrapped
+// first. `p` unwraps one instance; `ps` maps an array of them.
+const p = (x: any) => x.props;
+const ps = (xs: any[]) => xs.map(p);
+
+describe("DynamoDBTable", () => {
+  test("partition-key-only: PAY_PER_REQUEST by default, single member", () => {
+    const instance = DynamoDBTable({ partitionKey: { name: "id" } });
+    expect(Object.keys(instance.members)).toEqual(["table"]);
+    const props = (instance.table as any).props;
+    expect(props.BillingMode).toBe("PAY_PER_REQUEST");
+    expect(ps(props.KeySchema)).toEqual([{ AttributeName: "id", KeyType: "HASH" }]);
+    expect(ps(props.AttributeDefinitions)).toEqual([{ AttributeName: "id", AttributeType: "S" }]);
+    expect(props.ProvisionedThroughput).toBeUndefined();
+  });
+
+  test("expandComposite produces the table's logical name", () => {
+    const expanded = expandComposite("orders", DynamoDBTable({ partitionKey: { name: "id" } }));
+    expect(expanded.has("ordersTable")).toBe(true);
+    expect(expanded.size).toBe(1);
+  });
+
+  test("partition + sort key, non-default types", () => {
+    const instance = DynamoDBTable({
+      partitionKey: { name: "pk", type: "S" },
+      sortKey: { name: "sk", type: "N" },
+    });
+    const props = (instance.table as any).props;
+    expect(ps(props.KeySchema)).toEqual([
+      { AttributeName: "pk", KeyType: "HASH" },
+      { AttributeName: "sk", KeyType: "RANGE" },
+    ]);
+    expect(ps(props.AttributeDefinitions)).toEqual([
+      { AttributeName: "pk", AttributeType: "S" },
+      { AttributeName: "sk", AttributeType: "N" },
+    ]);
+  });
+
+  test("no GSIs: GlobalSecondaryIndexes is omitted, not an empty array", () => {
+    const props = (DynamoDBTable({ partitionKey: { name: "id" } }).table as any).props;
+    expect(props.GlobalSecondaryIndexes).toBeUndefined();
+  });
+
+  test("a GSI defaults to ALL projection and, on-demand billing, carries no throughput", () => {
+    const instance = DynamoDBTable({
+      partitionKey: { name: "pk" },
+      globalSecondaryIndexes: [{ name: "byStatus", partitionKey: { name: "status" } }],
+    });
+    const props = (instance.table as any).props;
+    expect(props.GlobalSecondaryIndexes).toHaveLength(1);
+    const gsi = p(props.GlobalSecondaryIndexes[0]);
+    expect(gsi.IndexName).toBe("byStatus");
+    expect(ps(gsi.KeySchema)).toEqual([{ AttributeName: "status", KeyType: "HASH" }]);
+    expect(p(gsi.Projection)).toEqual({ ProjectionType: "ALL" });
+    expect(gsi.ProvisionedThroughput).toBeUndefined();
+  });
+
+  test("a GSI reusing the table's partition key does not duplicate its AttributeDefinition", () => {
+    const instance = DynamoDBTable({
+      partitionKey: { name: "pk" },
+      sortKey: { name: "sk" },
+      globalSecondaryIndexes: [{ name: "byPk", partitionKey: { name: "pk" }, sortKey: { name: "gsiSort" } }],
+    });
+    const props = (instance.table as any).props;
+    const names = ps(props.AttributeDefinitions).map((a: any) => a.AttributeName);
+    expect(names).toEqual(["pk", "sk", "gsiSort"]);
+  });
+
+  test("INCLUDE projection carries nonKeyAttributes through", () => {
+    const instance = DynamoDBTable({
+      partitionKey: { name: "pk" },
+      globalSecondaryIndexes: [{
+        name: "byStatus",
+        partitionKey: { name: "status" },
+        projectionType: "INCLUDE",
+        nonKeyAttributes: ["total", "updatedAt"],
+      }],
+    });
+    const gsi = p(((instance.table as any).props.GlobalSecondaryIndexes)[0]);
+    expect(p(gsi.Projection)).toEqual({ ProjectionType: "INCLUDE", NonKeyAttributes: ["total", "updatedAt"] });
+  });
+
+  test("ttlAttribute enables TimeToLiveSpecification; omitted, no TTL block at all", () => {
+    const withTtl = (DynamoDBTable({ partitionKey: { name: "id" }, ttlAttribute: "expiresAt" }).table as any).props;
+    expect(p(withTtl.TimeToLiveSpecification)).toEqual({ Enabled: true, AttributeName: "expiresAt" });
+
+    const withoutTtl = (DynamoDBTable({ partitionKey: { name: "id" } }).table as any).props;
+    expect(withoutTtl.TimeToLiveSpecification).toBeUndefined();
+  });
+
+  test("stream: true defaults to NEW_AND_OLD_IMAGES", () => {
+    const props = (DynamoDBTable({ partitionKey: { name: "id" }, stream: true }).table as any).props;
+    expect(p(props.StreamSpecification)).toEqual({ StreamViewType: "NEW_AND_OLD_IMAGES" });
+  });
+
+  test("stream view type is overridable; omitted, no stream block at all", () => {
+    const withView = (DynamoDBTable({
+      partitionKey: { name: "id" },
+      stream: { viewType: "KEYS_ONLY" },
+    }).table as any).props;
+    expect(p(withView.StreamSpecification)).toEqual({ StreamViewType: "KEYS_ONLY" });
+
+    const withoutStream = (DynamoDBTable({ partitionKey: { name: "id" } }).table as any).props;
+    expect(withoutStream.StreamSpecification).toBeUndefined();
+  });
+
+  test("PROVISIONED billing mode defaults capacity to 5/5 on both table and GSI", () => {
+    const instance = DynamoDBTable({
+      partitionKey: { name: "id" },
+      billingMode: "PROVISIONED",
+      globalSecondaryIndexes: [{ name: "byStatus", partitionKey: { name: "status" } }],
+    });
+    const props = (instance.table as any).props;
+    expect(p(props.ProvisionedThroughput)).toEqual({ ReadCapacityUnits: 5, WriteCapacityUnits: 5 });
+    const gsi = p(props.GlobalSecondaryIndexes[0]);
+    expect(p(gsi.ProvisionedThroughput)).toEqual({ ReadCapacityUnits: 5, WriteCapacityUnits: 5 });
+  });
+
+  test("PROVISIONED billing mode: explicit table capacity flows to a GSI that doesn't set its own", () => {
+    const instance = DynamoDBTable({
+      partitionKey: { name: "id" },
+      billingMode: "PROVISIONED",
+      provisionedThroughput: { readCapacity: 20, writeCapacity: 10 },
+      globalSecondaryIndexes: [
+        { name: "inherits", partitionKey: { name: "status" } },
+        { name: "overrides", partitionKey: { name: "kind" }, provisionedThroughput: { readCapacity: 1, writeCapacity: 1 } },
+      ],
+    });
+    const props = (instance.table as any).props;
+    expect(p(props.ProvisionedThroughput)).toEqual({ ReadCapacityUnits: 20, WriteCapacityUnits: 10 });
+    const [inherits, overrides] = ps(props.GlobalSecondaryIndexes);
+    expect(p(inherits.ProvisionedThroughput)).toEqual({ ReadCapacityUnits: 20, WriteCapacityUnits: 10 });
+    expect(p(overrides.ProvisionedThroughput)).toEqual({ ReadCapacityUnits: 1, WriteCapacityUnits: 1 });
+  });
+
+  test("tableName is threaded through when given", () => {
+    const props = (DynamoDBTable({ partitionKey: { name: "id" }, tableName: "orders-prod" }).table as any).props;
+    expect(props.TableName).toBe("orders-prod");
+  });
+
+  test("defaults escape hatch reaches the table (e.g. deletion protection)", () => {
+    const props = (DynamoDBTable({
+      partitionKey: { name: "id" },
+      defaults: { table: { DeletionProtectionEnabled: true } },
+    }).table as any).props;
+    expect(props.DeletionProtectionEnabled).toBe(true);
+  });
+});

package/src/composites/dynamodb-table.ts

@@ -0,0 +1,124 @@
+import { Composite, mergeDefaults, type Value } from "@intentius/chant";
+import {
+  Table,
+  Table_AttributeDefinition,
+  Table_KeySchema,
+  Table_GlobalSecondaryIndex,
+  Table_Projection,
+  Table_ProvisionedThroughput,
+  Table_StreamSpecification,
+  Table_TimeToLiveSpecification,
+} from "../generated";
+
+export interface DynamoDBKey {
+  name: string;
+  type?: "S" | "N" | "B";
+}
+
+export interface DynamoDBCapacity {
+  readCapacity: number;
+  writeCapacity: number;
+}
+
+export interface DynamoDBGlobalSecondaryIndex {
+  name: string;
+  partitionKey: DynamoDBKey;
+  sortKey?: DynamoDBKey;
+  /** Defaults to "ALL" — projecting the whole item is the common case; narrow it deliberately. */
+  projectionType?: "ALL" | "KEYS_ONLY" | "INCLUDE";
+  /** Only meaningful with projectionType "INCLUDE". */
+  nonKeyAttributes?: string[];
+  /** PROVISIONED tables only. Falls back to the table's own capacity when a GSI doesn't need its own. */
+  provisionedThroughput?: DynamoDBCapacity;
+}
+
+export interface DynamoDBTableProps {
+  /** `Value<string>`: a name is routinely built with `Sub`/`Ref` (#1366). */
+  tableName?: Value<string>;
+  partitionKey: DynamoDBKey;
+  sortKey?: DynamoDBKey;
+  /** Defaults to "PAY_PER_REQUEST" — the recommended default for most workloads (matches LambdaDynamoDB). */
+  billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
+  /** Required when billingMode is "PROVISIONED"; ignored otherwise. Falls back to 5/5 (the DynamoDB console default) if omitted. */
+  provisionedThroughput?: DynamoDBCapacity;
+  globalSecondaryIndexes?: DynamoDBGlobalSecondaryIndex[];
+  /** Attribute name that carries the expiry timestamp. Enables TimeToLiveSpecification when set. */
+  ttlAttribute?: string;
+  /** Enables StreamSpecification. `true` defaults to NEW_AND_OLD_IMAGES (the shape most stream consumers want). */
+  stream?: boolean | { viewType?: "NEW_IMAGE" | "OLD_IMAGE" | "NEW_AND_OLD_IMAGES" | "KEYS_ONLY" };
+  defaults?: {
+    table?: Partial<ConstructorParameters<typeof Table>[0]>;
+  };
+}
+
+const DEFAULT_CAPACITY: DynamoDBCapacity = { readCapacity: 5, writeCapacity: 5 };
+
+function toProvisionedThroughput(capacity: DynamoDBCapacity): InstanceType<typeof Table_ProvisionedThroughput> {
+  return new Table_ProvisionedThroughput({
+    ReadCapacityUnits: capacity.readCapacity,
+    WriteCapacityUnits: capacity.writeCapacity,
+  });
+}
+
+function toKeySchema(partitionKey: DynamoDBKey, sortKey?: DynamoDBKey): InstanceType<typeof Table_KeySchema>[] {
+  // A ternary (not an `if`) keeps the `new`s unconditional per EVL002, and
+  // returning array literals directly from each branch — no spread — sidesteps
+  // EVL004 (outside a Composite factory, EVL004 only traces a spread source to a
+  // module-top-level const or a literal, not a local variable).
+  const partitionEntry = new Table_KeySchema({ AttributeName: partitionKey.name, KeyType: "HASH" });
+  const sortEntry = sortKey ? new Table_KeySchema({ AttributeName: sortKey.name, KeyType: "RANGE" }) : undefined;
+  return sortEntry ? [partitionEntry, sortEntry] : [partitionEntry];
+}
+
+export const DynamoDBTable = Composite((props: DynamoDBTableProps) => {
+  const billingMode = props.billingMode ?? "PAY_PER_REQUEST";
+  const { defaults } = props;
+
+  // Every key attribute used anywhere (table keys + every GSI's keys) needs exactly
+  // one AttributeDefinition. A Map dedupes by name so a GSI reusing the table's
+  // partition key (a common pattern) doesn't produce a duplicate definition.
+  const attributeTypes = new Map<string, "S" | "N" | "B">();
+  attributeTypes.set(props.partitionKey.name, props.partitionKey.type ?? "S");
+  if (props.sortKey) attributeTypes.set(props.sortKey.name, props.sortKey.type ?? "S");
+  for (const gsi of props.globalSecondaryIndexes ?? []) {
+    attributeTypes.set(gsi.partitionKey.name, gsi.partitionKey.type ?? "S");
+    if (gsi.sortKey) attributeTypes.set(gsi.sortKey.name, gsi.sortKey.type ?? "S");
+  }
+  const attributeDefinitions = [...attributeTypes.entries()].map(
+    ([AttributeName, AttributeType]) => new Table_AttributeDefinition({ AttributeName, AttributeType }),
+  );
+
+  const globalSecondaryIndexes = (props.globalSecondaryIndexes ?? []).map((gsi) => new Table_GlobalSecondaryIndex({
+    IndexName: gsi.name,
+    KeySchema: toKeySchema(gsi.partitionKey, gsi.sortKey),
+    Projection: new Table_Projection({
+      ProjectionType: gsi.projectionType ?? "ALL",
+      ...(gsi.nonKeyAttributes ? { NonKeyAttributes: gsi.nonKeyAttributes } : {}),
+    }),
+    ...(billingMode === "PROVISIONED"
+      ? { ProvisionedThroughput: toProvisionedThroughput(gsi.provisionedThroughput ?? props.provisionedThroughput ?? DEFAULT_CAPACITY) }
+      : {}),
+  }));
+
+  const streamConfig = props.stream === true ? {} : props.stream || undefined;
+  const ttlEnabled = props.ttlAttribute !== undefined;
+
+  const table = new Table(mergeDefaults({
+    TableName: props.tableName,
+    BillingMode: billingMode,
+    AttributeDefinitions: attributeDefinitions,
+    KeySchema: toKeySchema(props.partitionKey, props.sortKey),
+    ...(globalSecondaryIndexes.length > 0 ? { GlobalSecondaryIndexes: globalSecondaryIndexes } : {}),
+    ...(billingMode === "PROVISIONED"
+      ? { ProvisionedThroughput: toProvisionedThroughput(props.provisionedThroughput ?? DEFAULT_CAPACITY) }
+      : {}),
+    ...(streamConfig
+      ? { StreamSpecification: new Table_StreamSpecification({ StreamViewType: streamConfig.viewType ?? "NEW_AND_OLD_IMAGES" }) }
+      : {}),
+    ...(ttlEnabled
+      ? { TimeToLiveSpecification: new Table_TimeToLiveSpecification({ Enabled: true, AttributeName: props.ttlAttribute }) }
+      : {}),
+  }, defaults?.table));
+
+  return { table };
+}, "DynamoDBTable");