@intentius/chant-lexicon-aws 0.45.0 → 0.49.0

package/src/composites/bucket-deployment.ts

@@ -0,0 +1,153 @@
+/**
+ * BucketDeployment — the seeded-bucket shape: an S3 bucket sized to receive
+ * deploy-time content, encrypted and access-blocked by default, its
+ * deletion behaviour and (optionally) its public-read policy declared up
+ * front rather than left to CloudFormation's own defaults.
+ *
+ * `s3deploy.BucketDeployment` is the most-used CDK pattern across the
+ * aws-bench corpus (37 instantiations across 8 apps, chant#1139) and it
+ * names two things CDK bundles together that chant keeps apart on purpose:
+ *
+ *  - The bucket itself: `AWS::S3::Bucket` plus its encryption, access-block
+ *    and (for the static-site shape) website/public-policy configuration.
+ *    That is a fixed set of CloudFormation resources, so it is what this
+ *    composite declares — the same shape `LambdaS3` (../composites) already
+ *    gives a bucket, minus the Lambda trigger wiring.
+ *  - Uploading local files into it at deploy time. CDK does this with a
+ *    Lambda-backed custom resource (`cr.AwsCustomResource`, the same family
+ *    the epic notes maps to chant Ops rather than composites — chant has no
+ *    CloudFormation custom-resource machinery, and inventing one just to
+ *    reproduce a `PutObject` loop would be new plumbing for a solved
+ *    problem). chant already ships this as a deploy-time **capability**,
+ *    `s3-sync` (`../components/apply.ts`'s `createS3SyncCapability`, backed
+ *    by the real `aws s3 sync`/`aws s3 cp` CLI through `CloudExecutor`, with
+ *    the typed step-builder `s3Sync` in `../components/builders.ts`) — it
+ *    was defined for exactly this and, before this composite, had no
+ *    composite pairing it with a bucket to sync into. A component composes
+ *    the two:
+ *
+ *      const seeded = BucketDeployment({ bucketName: Sub`${AWS.StackName}-site` });
+ *      // ...component `deploy` phase:
+ *      s3Sync({ from: "archive:site-build", to: Sub`s3://${seeded.bucket.Ref}` })
+ *
+ * That split — graph-time declaration here, deploy-time action in the
+ * component layer — is the existing precedent (`s3-sync` shipped in #566
+ * unused by any composite until this one), not a new one invented for this
+ * composite.
+ *
+ * "Cleanup" (the epic's third word) is `removalPolicy`, CloudFormation's own
+ * `DeletionPolicy` on the bucket resource. CDK's `autoDeleteObjects` — the
+ * Lambda-backed hook that empties a bucket before CloudFormation is allowed
+ * to delete it — has the same custom-resource shape as content upload and
+ * the same answer: out of scope here, and worth an `s3 rm --recursive`
+ * step ahead of a stack teardown in the component that owns the deploy.
+ */
+import { Composite, mergeDefaults, type Value } from "@intentius/chant";
+import {
+  Bucket,
+  Bucket_BucketEncryption,
+  Bucket_ServerSideEncryptionRule,
+  Bucket_ServerSideEncryptionByDefault,
+  Bucket_PublicAccessBlockConfiguration,
+  Bucket_VersioningConfiguration,
+  Bucket_WebsiteConfiguration,
+  S3BucketPolicy,
+} from "../generated";
+import { Sub } from "../intrinsics";
+
+export interface BucketDeploymentProps {
+  /** `Value<string>`: a name is routinely built with `Sub`/`Ref` (#1366). Omitted lets CloudFormation generate one. */
+  bucketName?: Value<string>;
+  /** Enable S3 object versioning. Default: false. */
+  versioned?: boolean;
+  /**
+   * Static-website hosting: sets `WebsiteConfiguration` and — since a
+   * website bucket is read by anonymous visitors, not IAM principals —
+   * opens the public-access block and attaches a public-read
+   * `S3BucketPolicy` scoped to `s3:GetObject`. Omitted, the bucket stays
+   * fully private, matching every other composite bucket's default
+   * (`LambdaS3`, ../composites).
+   */
+  website?: {
+    indexDocument: string;
+    errorDocument?: string;
+  };
+  /** What CloudFormation does to the bucket when the stack (or the resource) is removed. Default: "retain" — CloudFormation's own default, and the safe one for a bucket a deploy has just put content into. */
+  removalPolicy?: "retain" | "destroy";
+  tags?: Array<{ Key: string; Value: string }>;
+  defaults?: {
+    bucket?: Partial<ConstructorParameters<typeof Bucket>[0]>;
+    bucketPolicy?: Partial<ConstructorParameters<typeof S3BucketPolicy>[0]>;
+  };
+}
+
+export type BucketDeploymentResult =
+  | { bucket: InstanceType<typeof Bucket> }
+  | { bucket: InstanceType<typeof Bucket>; bucketPolicy: InstanceType<typeof S3BucketPolicy> };
+
+export const BucketDeployment = Composite<BucketDeploymentProps>((props) => {
+  const { defaults } = props;
+  const publicRead = props.website !== undefined;
+
+  const encryptionDefault = new Bucket_ServerSideEncryptionByDefault({ SSEAlgorithm: "AES256" });
+  const encryptionRule = new Bucket_ServerSideEncryptionRule({ ServerSideEncryptionByDefault: encryptionDefault });
+  const bucketEncryption = new Bucket_BucketEncryption({ ServerSideEncryptionConfiguration: [encryptionRule] });
+
+  // A ternary, not an `if`, so the block-scoped `new` stays an expression
+  // (EVL002) — the same reasoning eks-cluster.ts's addon slots document.
+  const publicAccessBlock = new Bucket_PublicAccessBlockConfiguration(
+    publicRead
+      ? { BlockPublicAcls: false, BlockPublicPolicy: false, IgnorePublicAcls: false, RestrictPublicBuckets: false }
+      : { BlockPublicAcls: true, BlockPublicPolicy: true, IgnorePublicAcls: true, RestrictPublicBuckets: true },
+  );
+
+  const versioningConfiguration = props.versioned
+    ? new Bucket_VersioningConfiguration({ Status: "Enabled" })
+    : undefined;
+
+  const websiteConfiguration = props.website
+    ? new Bucket_WebsiteConfiguration({
+        IndexDocument: props.website.indexDocument,
+        ...(props.website.errorDocument ? { ErrorDocument: props.website.errorDocument } : {}),
+      })
+    : undefined;
+
+  const bucket = new Bucket(
+    mergeDefaults(
+      {
+        BucketName: props.bucketName,
+        BucketEncryption: bucketEncryption,
+        PublicAccessBlockConfiguration: publicAccessBlock,
+        ...(versioningConfiguration ? { VersioningConfiguration: versioningConfiguration } : {}),
+        ...(websiteConfiguration ? { WebsiteConfiguration: websiteConfiguration } : {}),
+        Tags: props.tags,
+      },
+      defaults?.bucket,
+    ),
+    { DeletionPolicy: props.removalPolicy === "destroy" ? "Delete" : "Retain" },
+  );
+
+  const bucketPolicy = publicRead
+    ? new S3BucketPolicy(
+        mergeDefaults(
+          {
+            Bucket: bucket.Ref,
+            PolicyDocument: {
+              Version: "2012-10-17",
+              Statement: [
+                { Effect: "Allow", Principal: "*", Action: "s3:GetObject", Resource: Sub`${bucket.Arn}/*` },
+              ],
+            },
+          },
+          defaults?.bucketPolicy,
+        ),
+      )
+    : undefined;
+
+  // Spread rather than a ternary between two object shapes (EksCluster's
+  // addon slots, ../eks-cluster.ts, hit the same union-return typing wall):
+  // a key that is sometimes present, never a key whose value is sometimes
+  // `undefined` — `CompositeMembers`' index signature requires `Declarable`,
+  // not `Declarable | undefined`.
+  return { bucket, ...(bucketPolicy ? { bucketPolicy } : {}) };
+}, "BucketDeployment");

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);
+  });
+});