alchemy 0.2.3 → 0.2.5

package/lib/aws/queue.js

@@ -1,5 +1,44 @@
 import { CreateQueueCommand, DeleteQueueCommand, GetQueueAttributesCommand, GetQueueUrlCommand, SQSClient, } from "@aws-sdk/client-sqs";
 import { Resource } from "../resource";
+/**
+ * AWS SQS Queue Resource
+ *
+ * Creates and manages Amazon SQS queues with support for both standard and FIFO queues.
+ * Handles queue creation, attribute configuration, and automatic cleanup of deleted queues.
+ *
+ * @example
+ * // Create a standard queue with custom visibility timeout
+ * const standardQueue = await Queue("my-queue", {
+ *   queueName: "my-queue",
+ *   visibilityTimeout: 30,
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a FIFO queue with content-based deduplication
+ * const fifoQueue = await Queue("orders-queue", {
+ *   queueName: "orders-queue.fifo",
+ *   fifo: true,
+ *   contentBasedDeduplication: true,
+ *   visibilityTimeout: 30,
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a queue with custom message retention and size
+ * const customQueue = await Queue("large-messages", {
+ *   queueName: "large-messages",
+ *   messageRetentionPeriod: 345600,  // 4 days
+ *   maximumMessageSize: 262144,      // 256 KB
+ *   visibilityTimeout: 60,
+ *   delaySeconds: 5,
+ *   receiveMessageWaitTimeSeconds: 20
+ * });
+ */
 export const Queue = Resource("sqs::Queue", async function (id, props) {
     const client = new SQSClient({});
     // Don't automatically add .fifo suffix - user must include it in queueName

package/lib/aws/role.d.ts

@@ -1,24 +1,185 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
 import type { PolicyDocument } from "./policy";
+/**
+ * Properties for creating or updating an IAM role
+ */
 export interface RoleProps {
+    /**
+     * Name of the IAM role
+     */
     roleName: string;
+    /**
+     * Policy that defines which entities can assume this role
+     */
     assumeRolePolicy: PolicyDocument;
+    /**
+     * Optional description of the role's purpose
+     */
     description?: string;
+    /**
+     * Optional path prefix for the role
+     */
     path?: string;
+    /**
+     * Maximum session duration in seconds when assumed
+     * Default: 3600 seconds (1 hour)
+     */
     maxSessionDuration?: number;
+    /**
+     * ARN of the policy used to set the permissions boundary
+     */
     permissionsBoundary?: string;
+    /**
+     * Inline policies to embed in the role
+     * Each policy must have a unique name and policy document
+     */
     policies?: Array<{
         policyName: string;
         policyDocument: PolicyDocument;
     }>;
+    /**
+     * List of managed policy ARNs to attach to the role
+     */
     managedPolicyArns?: string[];
+    /**
+     * Resource tags for the role
+     */
     tags?: Record<string, string>;
 }
+/**
+ * Output returned after IAM role creation/update
+ */
 export interface Role extends Resource<"iam::Role">, RoleProps {
+    /**
+     * ARN of the role
+     */
     arn: string;
+    /**
+     * Unique identifier for the role
+     */
     uniqueId: string;
+    /**
+     * The stable and unique string identifying the role
+     */
     roleId: string;
+    /**
+     * When the role was created
+     */
     createDate: Date;
 }
-export declare const Role: ((this: Context<Role>, id: string, props: RoleProps) => Promise<Role>) | (((this: any, id: string, props?: RoleProps | undefined) => never) & (new (_: never) => never));
+/**
+ * AWS IAM Role Resource
+ *
+ * Creates and manages IAM roles with support for inline policies, managed policies,
+ * and automatic cleanup of attached policies during deletion.
+ *
+ * @example
+ * // Create a basic Lambda execution role with inline policy
+ * const basicRole = await Role("lambda-role", {
+ *   roleName: "lambda-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Basic Lambda execution role",
+ *   tags: {
+ *     Environment: "production"
+ *   },
+ *   policies: [{
+ *     policyName: "logs",
+ *     policyDocument: {
+ *       Version: "2012-10-17",
+ *       Statement: [{
+ *         Effect: "Allow",
+ *         Action: [
+ *           "logs:CreateLogGroup",
+ *           "logs:CreateLogStream",
+ *           "logs:PutLogEvents"
+ *         ],
+ *         Resource: "*"
+ *       }]
+ *     }
+ *   }]
+ * });
+ *
+ * @example
+ * // Create a role with AWS managed policies
+ * const managedRole = await Role("readonly-role", {
+ *   roleName: "readonly-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Role with managed policies",
+ *   managedPolicyArns: [
+ *     "arn:aws:iam::aws:policy/ReadOnlyAccess"
+ *   ],
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a role with multiple inline policies and custom session duration
+ * const customRole = await Role("custom-role", {
+ *   roleName: "custom-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Role with multiple policies",
+ *   maxSessionDuration: 7200,
+ *   policies: [
+ *     {
+ *       policyName: "logs",
+ *       policyDocument: {
+ *         Version: "2012-10-17",
+ *         Statement: [{
+ *           Effect: "Allow",
+ *           Action: [
+ *             "logs:CreateLogGroup",
+ *             "logs:CreateLogStream",
+ *             "logs:PutLogEvents"
+ *           ],
+ *           Resource: "*"
+ *         }]
+ *       }
+ *     },
+ *     {
+ *       policyName: "s3",
+ *       policyDocument: {
+ *         Version: "2012-10-17",
+ *         Statement: [{
+ *           Effect: "Allow",
+ *           Action: "s3:ListBucket",
+ *           Resource: "*"
+ *         }]
+ *       }
+ *     }
+ *   ],
+ *   tags: {
+ *     Environment: "production",
+ *     Updated: "true"
+ *   }
+ * });
+ */
+export declare const Role: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Role>, id: string, props: RoleProps) => Promise<Role>);

package/lib/aws/role.js

@@ -1,6 +1,120 @@
 import { AttachRolePolicyCommand, CreateRoleCommand, DeleteRoleCommand, DeleteRolePolicyCommand, DetachRolePolicyCommand, EntityAlreadyExistsException, GetRoleCommand, IAMClient, ListAttachedRolePoliciesCommand, NoSuchEntityException, PutRolePolicyCommand, TagRoleCommand, UpdateAssumeRolePolicyCommand, UpdateRoleCommand, } from "@aws-sdk/client-iam";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
+/**
+ * AWS IAM Role Resource
+ *
+ * Creates and manages IAM roles with support for inline policies, managed policies,
+ * and automatic cleanup of attached policies during deletion.
+ *
+ * @example
+ * // Create a basic Lambda execution role with inline policy
+ * const basicRole = await Role("lambda-role", {
+ *   roleName: "lambda-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Basic Lambda execution role",
+ *   tags: {
+ *     Environment: "production"
+ *   },
+ *   policies: [{
+ *     policyName: "logs",
+ *     policyDocument: {
+ *       Version: "2012-10-17",
+ *       Statement: [{
+ *         Effect: "Allow",
+ *         Action: [
+ *           "logs:CreateLogGroup",
+ *           "logs:CreateLogStream",
+ *           "logs:PutLogEvents"
+ *         ],
+ *         Resource: "*"
+ *       }]
+ *     }
+ *   }]
+ * });
+ *
+ * @example
+ * // Create a role with AWS managed policies
+ * const managedRole = await Role("readonly-role", {
+ *   roleName: "readonly-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Role with managed policies",
+ *   managedPolicyArns: [
+ *     "arn:aws:iam::aws:policy/ReadOnlyAccess"
+ *   ],
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a role with multiple inline policies and custom session duration
+ * const customRole = await Role("custom-role", {
+ *   roleName: "custom-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Role with multiple policies",
+ *   maxSessionDuration: 7200,
+ *   policies: [
+ *     {
+ *       policyName: "logs",
+ *       policyDocument: {
+ *         Version: "2012-10-17",
+ *         Statement: [{
+ *           Effect: "Allow",
+ *           Action: [
+ *             "logs:CreateLogGroup",
+ *             "logs:CreateLogStream",
+ *             "logs:PutLogEvents"
+ *           ],
+ *           Resource: "*"
+ *         }]
+ *       }
+ *     },
+ *     {
+ *       policyName: "s3",
+ *       policyDocument: {
+ *         Version: "2012-10-17",
+ *         Statement: [{
+ *           Effect: "Allow",
+ *           Action: "s3:ListBucket",
+ *           Resource: "*"
+ *         }]
+ *       }
+ *     }
+ *   ],
+ *   tags: {
+ *     Environment: "production",
+ *     Updated: "true"
+ *   }
+ * });
+ */
 export const Role = Resource("iam::Role", async function (id, props) {
     const client = new IAMClient({});
     if (this.phase === "delete") {

package/lib/aws/ses.d.ts

@@ -7,38 +7,48 @@ import { Resource } from "../resource";
 export interface SESProps {
     /**
      * Name of the configuration set
+     * Used to group email sending and tracking settings
      */
     configurationSetName?: string;
     /**
      * Email identity to verify (email address or domain)
+     * For domains, use the format "example.com"
+     * For email addresses, use the format "user@example.com"
      */
     emailIdentity?: string;
     /**
      * Whether to enable DKIM signing for the email identity
+     * DKIM helps prevent email spoofing by verifying sender authenticity
      */
     enableDkim?: boolean;
     /**
      * Sending options for the configuration set
+     * Controls whether email sending is enabled and related settings
      */
     sendingOptions?: SendingOptions;
     /**
      * Reputation options for the configuration set
+     * Controls reputation tracking and metrics collection
      */
     reputationOptions?: ReputationOptions;
     /**
      * Tracking options for the configuration set
+     * Controls open and click tracking with optional custom domains
      */
     trackingOptions?: TrackingOptions;
     /**
      * Suppression options for the configuration set
+     * Controls how bounces and complaints are handled
      */
     suppressionOptions?: SuppressionOptions;
     /**
      * Delivery options for the configuration set
+     * Controls TLS settings and sending pool configuration
      */
     deliveryOptions?: DeliveryOptions;
     /**
      * Tags to apply to the SES resources
+     * Key-value pairs for resource organization
      */
     tags?: Record<string, string>;
 }
@@ -48,22 +58,67 @@ export interface SESProps {
 export interface SES extends Resource<"aws::SES">, SESProps {
     /**
      * ARN of the configuration set if created
+     * Format: arn:aws:ses:region:account-id:configuration-set/name
      */
     configurationSetArn?: string;
     /**
      * Email identity verification status if an identity was created
+     * Can be "PENDING" or "VERIFIED"
      */
     emailIdentityVerificationStatus?: string;
     /**
      * DKIM verification status if DKIM was enabled
+     * Can be "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE", or "NOT_STARTED"
      */
     dkimVerificationStatus?: string;
     /**
      * Email identity ARN if an identity was created
+     * Format: arn:aws:ses:region:account-id:identity/name
      */
     emailIdentityArn?: string;
 }
 /**
- * AWS SES resource for creating and configuring Simple Email Service
+ * AWS SES Resource
+ *
+ * Creates and manages Amazon Simple Email Service (SES) configuration sets and email identities.
+ * Supports email sending configuration, DKIM signing, and identity verification.
+ *
+ * @example
+ * // Create a configuration set with sending options
+ * const configSet = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: true
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications"
+ *   }
+ * });
+ *
+ * @example
+ * // Create and verify a domain identity with DKIM
+ * const domainIdentity = await SES("domain-identity", {
+ *   emailIdentity: "example.com",
+ *   enableDkim: true,
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "transactional-emails"
+ *   }
+ * });
+ *
+ * @example
+ * // Update configuration set sending options
+ * const updatedConfig = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: false
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications",
+ *     Updated: "true"
+ *   }
+ * });
  */
-export declare const SES: ((this: Context<SES>, id: string, props: SESProps) => Promise<SES>) | (((this: any, id: string, props?: SESProps | undefined) => never) & (new (_: never) => never));
+export declare const SES: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<SES>, id: string, props: SESProps) => Promise<SES>);

package/lib/aws/ses.js

@@ -2,7 +2,48 @@ import { CreateConfigurationSetCommand, CreateEmailIdentityCommand, DeleteConfig
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 /**
- * AWS SES resource for creating and configuring Simple Email Service
+ * AWS SES Resource
+ *
+ * Creates and manages Amazon Simple Email Service (SES) configuration sets and email identities.
+ * Supports email sending configuration, DKIM signing, and identity verification.
+ *
+ * @example
+ * // Create a configuration set with sending options
+ * const configSet = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: true
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications"
+ *   }
+ * });
+ *
+ * @example
+ * // Create and verify a domain identity with DKIM
+ * const domainIdentity = await SES("domain-identity", {
+ *   emailIdentity: "example.com",
+ *   enableDkim: true,
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "transactional-emails"
+ *   }
+ * });
+ *
+ * @example
+ * // Update configuration set sending options
+ * const updatedConfig = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: false
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications",
+ *     Updated: "true"
+ *   }
+ * });
  */
 export const SES = Resource("aws::SES", async function (id, props) {
     // Create SES client

package/lib/aws/table.d.ts

@@ -1,23 +1,118 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * Properties for creating or updating a DynamoDB table
+ */
 export interface TableProps {
+    /**
+     * Name of the DynamoDB table
+     */
     tableName: string;
+    /**
+     * Primary partition key (hash key) configuration
+     * Defines the main identifier for items in the table
+     */
     partitionKey: {
+        /**
+         * Name of the partition key attribute
+         */
         name: string;
+        /**
+         * Data type of the partition key
+         * S: String, N: Number, B: Binary
+         */
         type: "S" | "N" | "B";
     };
+    /**
+     * Optional sort key (range key) configuration
+     * Used to sort items with the same partition key
+     */
     sortKey?: {
+        /**
+         * Name of the sort key attribute
+         */
         name: string;
+        /**
+         * Data type of the sort key
+         * S: String, N: Number, B: Binary
+         */
         type: "S" | "N" | "B";
     };
+    /**
+     * Billing mode for the table
+     * PROVISIONED: Set read/write capacity units
+     * PAY_PER_REQUEST: Pay per request pricing
+     */
     billingMode?: "PROVISIONED" | "PAY_PER_REQUEST";
+    /**
+     * Read capacity units when using PROVISIONED billing mode
+     * Default: 5
+     */
     readCapacity?: number;
+    /**
+     * Write capacity units when using PROVISIONED billing mode
+     * Default: 5
+     */
     writeCapacity?: number;
+    /**
+     * Tags to apply to the table
+     * Key-value pairs for resource organization
+     */
     tags?: Record<string, string>;
 }
+/**
+ * Output returned after DynamoDB table creation/update
+ */
 export interface Table extends Resource<"dynamo::Table">, TableProps {
+    /**
+     * ARN of the table
+     * Format: arn:aws:dynamodb:region:account-id:table/table-name
+     */
     arn: string;
+    /**
+     * ARN of the table's stream if enabled
+     * Format: arn:aws:dynamodb:region:account-id:table/table-name/stream/timestamp
+     */
     streamArn?: string;
+    /**
+     * Unique identifier for the table
+     */
     tableId: string;
 }
-export declare const Table: ((this: Context<Table>, id: string, props: TableProps) => Promise<Table>) | (((this: any, id: string, props?: TableProps | undefined) => never) & (new (_: never) => never));
+/**
+ * AWS DynamoDB Table Resource
+ *
+ * Creates and manages DynamoDB tables with support for partition and sort keys,
+ * flexible billing modes, and automatic table status monitoring.
+ *
+ * @example
+ * // Create a table with partition and sort key
+ * const table = await Table("user-events", {
+ *   tableName: "user-events",
+ *   partitionKey: {
+ *     name: "id",
+ *     type: "S"
+ *   },
+ *   sortKey: {
+ *     name: "timestamp",
+ *     type: "N"
+ *   },
+ *   tags: {
+ *     Environment: "test"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a table with provisioned capacity
+ * const table = await Table("high-throughput", {
+ *   tableName: "high-throughput",
+ *   partitionKey: {
+ *     name: "userId",
+ *     type: "S"
+ *   },
+ *   billingMode: "PROVISIONED",
+ *   readCapacity: 100,
+ *   writeCapacity: 50
+ * });
+ */
+export declare const Table: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Table>, id: string, props: TableProps) => Promise<Table>);

package/lib/aws/table.js

@@ -2,6 +2,42 @@ import { CreateTableCommand, DeleteTableCommand, DescribeTableCommand, DynamoDBC
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 import { withExponentialBackoff } from "../util/retry";
+/**
+ * AWS DynamoDB Table Resource
+ *
+ * Creates and manages DynamoDB tables with support for partition and sort keys,
+ * flexible billing modes, and automatic table status monitoring.
+ *
+ * @example
+ * // Create a table with partition and sort key
+ * const table = await Table("user-events", {
+ *   tableName: "user-events",
+ *   partitionKey: {
+ *     name: "id",
+ *     type: "S"
+ *   },
+ *   sortKey: {
+ *     name: "timestamp",
+ *     type: "N"
+ *   },
+ *   tags: {
+ *     Environment: "test"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a table with provisioned capacity
+ * const table = await Table("high-throughput", {
+ *   tableName: "high-throughput",
+ *   partitionKey: {
+ *     name: "userId",
+ *     type: "S"
+ *   },
+ *   billingMode: "PROVISIONED",
+ *   readCapacity: 100,
+ *   writeCapacity: 50
+ * });
+ */
 export const Table = Resource("dynamo::Table", async function (id, props) {
     const client = new DynamoDBClient({});
     if (this.phase === "delete") {

package/lib/cloudflare/asset-manifest.js

@@ -1 +0,0 @@
-export {};

package/lib/cloudflare/bound.js

@@ -1 +0,0 @@
-export {};