alchemy 0.2.3 → 0.2.5

package/lib/alchemy.js

@@ -6,6 +6,10 @@ import { secret } from "./secret";
 // TODO: support browser
 const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 export const alchemy = _alchemy;
+/**
+ * Implementation of the alchemy function that handles both application scoping
+ * and template string interpolation.
+ */
 function _alchemy(...args) {
     if (typeof args[0] === "string") {
         const [appName, options] = args;
@@ -23,7 +27,7 @@ function _alchemy(...args) {
             : 0;
         const indent = " ".repeat(leadingSpaces);
         return (async () => {
-            const { isFileCollection, isFileRef } = await import("./fs/file");
+            const { isFileCollection, isFileRef } = await import("./fs");
             const appendices = {};
             const stringValues = await Promise.all(values.map(async function resolve(value) {
                 if (typeof value === "string") {
@@ -88,8 +92,17 @@ _alchemy.scope = scope;
 _alchemy.secret = secret;
 /**
  * Enter a new scope synchronously.
- * @param options
- * @returns
+ *
+ * @example
+ * // Create a scope with a password for secret handling
+ * await using scope = alchemy.scope("my-scope", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * // Use secrets within the scope
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
  */
 function scope(id, options) {
     const scope = new Scope({
@@ -102,6 +115,21 @@ function scope(id, options) {
     scope.enter();
     return scope;
 }
+/**
+ * Run a function in a new scope asynchronously.
+ * Useful for isolating secret handling with a specific password.
+ *
+ * @example
+ * // Run operations in a scope with its own password
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SCOPE_PASSWORD
+ * }, async () => {
+ *   // Secrets in this scope will use this password
+ *   const resource = await Resource("my-resource", {
+ *     apiKey: alchemy.secret(process.env.API_KEY)
+ *   });
+ * });
+ */
 async function run(...args) {
     const [id, options, fn] = typeof args[1] === "function"
         ? [args[0], undefined, args[1]]

package/lib/aws/bucket.d.ts

@@ -1,18 +1,104 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * Properties for creating or updating an S3 bucket
+ */
 export interface BucketProps {
+    /**
+     * The name of the bucket. Must be globally unique across all AWS accounts.
+     * Should be lowercase alphanumeric characters or hyphens.
+     */
     bucketName: string;
+    /**
+     * Optional tags to apply to the bucket for organization and cost tracking.
+     * Each tag is a key-value pair.
+     */
     tags?: Record<string, string>;
 }
+/**
+ * Output returned after S3 bucket creation/update
+ */
 export interface Bucket extends Resource<"s3::Bucket">, BucketProps {
+    /**
+     * The ARN (Amazon Resource Name) of the bucket
+     * Format: arn:aws:s3:::bucket-name
+     */
     arn: string;
+    /**
+     * The global domain name for the bucket
+     * Format: bucket-name.s3.amazonaws.com
+     */
     bucketDomainName: string;
+    /**
+     * The regional domain name for the bucket
+     * Format: bucket-name.s3.region.amazonaws.com
+     */
     bucketRegionalDomainName?: string;
+    /**
+     * The S3 hosted zone ID for the region where the bucket resides
+     * Used for DNS configuration with Route 53
+     */
     hostedZoneId?: string;
+    /**
+     * The AWS region where the bucket is located
+     */
     region?: string;
+    /**
+     * The website endpoint URL if static website hosting is enabled
+     * Format: http://bucket-name.s3-website-region.amazonaws.com
+     */
     websiteEndpoint?: string;
+    /**
+     * The website domain if static website hosting is enabled
+     * Format: bucket-name.s3-website-region.amazonaws.com
+     */
     websiteDomain?: string;
+    /**
+     * Whether versioning is enabled for the bucket
+     */
     versioningEnabled?: boolean;
+    /**
+     * The canned ACL applied to the bucket
+     * Common values: private, public-read, public-read-write, authenticated-read
+     */
     acl?: string;
 }
-export declare const Bucket: ((this: Context<Bucket>, id: string, props: BucketProps) => Promise<Bucket>) | (((this: any, id: string, props?: BucketProps | undefined) => never) & (new (_: never) => never));
+/**
+ * AWS S3 Bucket Resource
+ *
+ * Creates and manages Amazon S3 buckets with support for versioning, tags, and regional configuration.
+ * S3 buckets provide scalable object storage for any type of data, with features like versioning,
+ * lifecycle policies, and fine-grained access control.
+ *
+ * @example
+ * // Create a basic S3 bucket with default settings
+ * const basicBucket = await Bucket("my-app-storage", {
+ *   bucketName: "my-app-storage",
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "my-app"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a bucket with versioning enabled and specific tags
+ * const versionedBucket = await Bucket("document-archive", {
+ *   bucketName: "document-archive",
+ *   tags: {
+ *     Environment: "production",
+ *     Purpose: "document-storage",
+ *     Versioning: "enabled"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a development bucket with minimal configuration
+ * const devBucket = await Bucket("dev-testing", {
+ *   bucketName: "dev-testing",
+ *   tags: {
+ *     Environment: "development",
+ *     Temporary: "true"
+ *   }
+ * });
+ */
+export declare const Bucket: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Bucket>, id: string, props: BucketProps) => Promise<Bucket>);

package/lib/aws/bucket.js

@@ -1,6 +1,44 @@
 import { CreateBucketCommand, DeleteBucketCommand, GetBucketAclCommand, GetBucketLocationCommand, GetBucketTaggingCommand, GetBucketVersioningCommand, HeadBucketCommand, NoSuchBucket, PutBucketTaggingCommand, S3Client, } from "@aws-sdk/client-s3";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
+/**
+ * AWS S3 Bucket Resource
+ *
+ * Creates and manages Amazon S3 buckets with support for versioning, tags, and regional configuration.
+ * S3 buckets provide scalable object storage for any type of data, with features like versioning,
+ * lifecycle policies, and fine-grained access control.
+ *
+ * @example
+ * // Create a basic S3 bucket with default settings
+ * const basicBucket = await Bucket("my-app-storage", {
+ *   bucketName: "my-app-storage",
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "my-app"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a bucket with versioning enabled and specific tags
+ * const versionedBucket = await Bucket("document-archive", {
+ *   bucketName: "document-archive",
+ *   tags: {
+ *     Environment: "production",
+ *     Purpose: "document-storage",
+ *     Versioning: "enabled"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a development bucket with minimal configuration
+ * const devBucket = await Bucket("dev-testing", {
+ *   bucketName: "dev-testing",
+ *   tags: {
+ *     Environment: "development",
+ *     Temporary: "true"
+ *   }
+ * });
+ */
 export const Bucket = Resource("s3::Bucket", async function (id, props) {
     const client = new S3Client({});
     if (this.phase === "delete") {
@@ -81,7 +119,16 @@ export const Bucket = Resource("s3::Bucket", async function (id, props) {
         });
     }
 });
-// Helper function to get S3 hosted zone IDs by region
+/**
+ * Helper function to get S3 hosted zone IDs by region
+ *
+ * Returns the S3 hosted zone ID for a given AWS region. These IDs are used when
+ * configuring Route 53 DNS records that point to S3 buckets. If the region is not
+ * found in the mapping, defaults to the us-east-1 hosted zone ID.
+ *
+ * @param region - The AWS region code (e.g., us-east-1, eu-west-1)
+ * @returns The S3 hosted zone ID for the region
+ */
 function getHostedZoneId(region) {
     const hostedZoneIds = {
         "us-east-1": "Z3AQBSTGFYJSTF",

package/lib/aws/function.d.ts

@@ -1,50 +1,235 @@
 import { Architecture, Runtime } from "@aws-sdk/client-lambda";
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * Properties for creating or updating a Lambda function
+ */
 export interface FunctionProps {
+    /**
+     * Name of the Lambda function
+     */
     functionName: string;
+    /**
+     * Path to the zip file containing the function code
+     */
     zipPath: string;
+    /**
+     * ARN of the IAM role that Lambda assumes when executing the function
+     */
     roleArn: string;
+    /**
+     * Function handler in the format 'file.function'
+     * For Node.js this is typically 'index.handler' or similar
+     */
     handler?: string;
+    /**
+     * Lambda runtime environment for the function
+     * @default nodejs20.x if not specified
+     */
     runtime?: Runtime;
+    /**
+     * CPU architecture for the function
+     * @default x86_64 if not specified
+     */
     architecture?: Architecture;
+    /**
+     * Description of the function's purpose
+     */
     description?: string;
+    /**
+     * Maximum execution time in seconds
+     * @default 3 seconds if not specified
+     */
     timeout?: number;
+    /**
+     * Amount of memory available to the function in MB
+     * @default 128 MB if not specified
+     */
     memorySize?: number;
+    /**
+     * Environment variables available to the function code
+     */
     environment?: Record<string, string>;
+    /**
+     * Resource tags for the function
+     */
     tags?: Record<string, string>;
+    /**
+     * Function URL configuration for direct HTTP(S) invocation
+     */
     url?: {
+        /**
+         * Authentication type for the function URL
+         */
         authType?: "AWS_IAM" | "NONE";
+        /**
+         * CORS configuration for the function URL
+         */
         cors?: {
+            /**
+             * Whether to allow credentials in CORS requests
+             */
             allowCredentials?: boolean;
+            /**
+             * Allowed headers in CORS requests
+             */
             allowHeaders?: string[];
+            /**
+             * Allowed HTTP methods in CORS requests
+             */
             allowMethods?: string[];
+            /**
+             * Allowed origins in CORS requests
+             */
             allowOrigins?: string[];
+            /**
+             * Headers exposed to the browser
+             */
             exposeHeaders?: string[];
+            /**
+             * CORS preflight cache time in seconds
+             */
             maxAge?: number;
         };
     };
 }
+/**
+ * Output returned after Lambda function creation/update
+ */
 export interface Function extends Resource<"lambda::Function">, FunctionProps {
+    /**
+     * ARN of the Lambda function
+     */
     arn: string;
+    /**
+     * Timestamp of the last function modification
+     */
     lastModified: string;
+    /**
+     * Function version
+     */
     version: string;
+    /**
+     * ARN with version suffix
+     */
     qualifiedArn: string;
+    /**
+     * ARN for invoking the function through API Gateway
+     */
     invokeArn: string;
+    /**
+     * SHA256 hash of the function code
+     */
     sourceCodeHash: string;
+    /**
+     * Size of the function code in bytes
+     */
     sourceCodeSize: number;
+    /**
+     * Size of ephemeral storage (/tmp) in MB
+     */
     ephemeralStorageSize?: number;
+    /**
+     * List of supported CPU architectures
+     */
     architectures: string[];
+    /**
+     * ARN of the master function (Lambda@Edge only)
+     */
     masterArn?: string;
+    /**
+     * Unique identifier for the current function code/config
+     */
     revisionId: string;
+    /**
+     * Current state of the function
+     */
     state?: string;
+    /**
+     * Reason for the current state
+     */
     stateReason?: string;
+    /**
+     * Code for the current state reason
+     */
     stateReasonCode?: string;
+    /**
+     * Status of the last update operation
+     */
     lastUpdateStatus?: string;
+    /**
+     * Reason for the last update status
+     */
     lastUpdateStatusReason?: string;
+    /**
+     * Code for the last update status reason
+     */
     lastUpdateStatusReasonCode?: string;
+    /**
+     * Function package type (Zip or Image)
+     */
     packageType: string;
+    /**
+     * ARN of the signing profile version
+     */
     signingProfileVersionArn?: string;
+    /**
+     * ARN of the signing job
+     */
     signingJobArn?: string;
 }
-export declare const Function: ((this: Context<Function>, id: string, props: FunctionProps) => Promise<Function>) | (((this: any, id: string, props?: FunctionProps | undefined) => never) & (new (_: never) => never));
+/**
+ * AWS Lambda Function Resource
+ *
+ * Creates and manages AWS Lambda functions with support for Node.js runtimes, custom handlers,
+ * environment variables, and function URLs. Handles deployment packaging, IAM role
+ * stabilization, and function updates.
+ *
+ * @example
+ * // Create a basic Lambda function with minimal configuration
+ * const basicFunction = await Function("api-handler", {
+ *   functionName: "api-handler",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "index.handler",
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with environment variables and custom memory/timeout
+ * const configuredFunction = await Function("worker", {
+ *   functionName: "worker",
+ *   zipPath: "./dist/worker.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "worker.process",
+ *   memorySize: 512,
+ *   timeout: 30,
+ *   environment: {
+ *     QUEUE_URL: queue.url,
+ *     LOG_LEVEL: "info"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with a public URL endpoint and CORS
+ * const apiFunction = await Function("public-api", {
+ *   functionName: "public-api",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   handler: "api.handler",
+ *   url: {
+ *     authType: "NONE",
+ *     cors: {
+ *       allowOrigins: ["*"],
+ *       allowMethods: ["GET", "POST"],
+ *       allowHeaders: ["content-type"],
+ *       maxAge: 86400
+ *     }
+ *   }
+ * });
+ */
+export declare const Function: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Function>, id: string, props: FunctionProps) => Promise<Function>);

package/lib/aws/function.js

@@ -3,14 +3,60 @@ import fs from "node:fs";
 import path from "node:path";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
-async function resolveRegion(client) {
-    const region = client.config.region;
-    if (typeof region === "string")
-        return region;
-    if (typeof region === "function")
-        return region();
-    throw new Error("Could not resolve AWS region");
-}
+/**
+ * AWS Lambda Function Resource
+ *
+ * Creates and manages AWS Lambda functions with support for Node.js runtimes, custom handlers,
+ * environment variables, and function URLs. Handles deployment packaging, IAM role
+ * stabilization, and function updates.
+ *
+ * @example
+ * // Create a basic Lambda function with minimal configuration
+ * const basicFunction = await Function("api-handler", {
+ *   functionName: "api-handler",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "index.handler",
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with environment variables and custom memory/timeout
+ * const configuredFunction = await Function("worker", {
+ *   functionName: "worker",
+ *   zipPath: "./dist/worker.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "worker.process",
+ *   memorySize: 512,
+ *   timeout: 30,
+ *   environment: {
+ *     QUEUE_URL: queue.url,
+ *     LOG_LEVEL: "info"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with a public URL endpoint and CORS
+ * const apiFunction = await Function("public-api", {
+ *   functionName: "public-api",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   handler: "api.handler",
+ *   url: {
+ *     authType: "NONE",
+ *     cors: {
+ *       allowOrigins: ["*"],
+ *       allowMethods: ["GET", "POST"],
+ *       allowHeaders: ["content-type"],
+ *       maxAge: 86400
+ *     }
+ *   }
+ * });
+ */
 export const Function = Resource("lambda::Function", async function (id, props) {
     const client = new LambdaClient({});
     const region = await resolveRegion(client);
@@ -172,3 +218,11 @@ async function zipCode(filePath) {
         platform: "UNIX",
     });
 }
+async function resolveRegion(client) {
+    const region = client.config.region;
+    if (typeof region === "string")
+        return region;
+    if (typeof region === "function")
+        return region();
+    throw new Error("Could not resolve AWS region");
+}

package/lib/aws/oidc/github-oidc-provider.d.ts

@@ -1,7 +1,88 @@
 import { OIDCProvider, type OIDCProviderProps } from "./oidc-provider";
+/**
+ * Properties for configuring GitHub-specific OIDC provider
+ * Simplified version of OIDCProviderProps that omits the thumbprint
+ * since it's automatically set to GitHub's known value
+ */
 export interface GitHubOIDCProviderProps extends Omit<OIDCProviderProps, "thumbprint"> {
+    /**
+     * The GitHub organization or user that owns the repository
+     * Example: "my-org" or "my-username"
+     */
     owner: string;
+    /**
+     * The name of the GitHub repository
+     * Example: "my-repo"
+     */
     repository: string;
 }
 export type GitHubOIDCProvider = ReturnType<typeof GitHubOIDCProvider>;
+/**
+ * GitHub-specific OIDC Provider Resource
+ *
+ * A simplified wrapper around OIDCProvider that automatically sets the correct
+ * thumbprint for GitHub Actions. This is the recommended way to set up OIDC
+ * authentication for GitHub Actions workflows.
+ *
+ * @example
+ * // Create a GitHub OIDC provider for all branches
+ * const provider = await GitHubOIDCProvider("github", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions"
+ * });
+ *
+ * @example
+ * // Create a GitHub OIDC provider with branch and environment restrictions
+ * const provider = await GitHubOIDCProvider("github-restricted", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   branches: ["main", "prod"],
+ *   environments: ["staging", "production"],
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions",
+ *   maxSessionDuration: 7200
+ * });
+ *
+ * @example
+ * // Complete setup with IAM role and OIDC provider
+ * import { Role, getAccountId } from "../aws";
+ *
+ * // Get the AWS account ID
+ * const accountId = await getAccountId();
+ *
+ * // Create the IAM role that GitHub Actions will assume
+ * const githubRole = await Role("github-oidc-role", {
+ *   roleName: "github-actions-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [
+ *       {
+ *         Sid: "GitHubOIDC",
+ *         Effect: "Allow",
+ *         Principal: {
+ *           Federated: `arn:aws:iam::${accountId}:oidc-provider/token.actions.githubusercontent.com`
+ *         },
+ *         Action: "sts:AssumeRoleWithWebIdentity",
+ *         Condition: {
+ *           StringEquals: {
+ *             "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+ *           },
+ *           StringLike: {
+ *             "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:*"
+ *           }
+ *         }
+ *       }
+ *     ]
+ *   },
+ *   // Add required managed policies or inline policies for your use case
+ *   managedPolicyArns: ["arn:aws:iam::aws:policy/ReadOnlyAccess"]
+ * });
+ *
+ * // Create the OIDC provider using the role
+ * const provider = await GitHubOIDCProvider("github-oidc", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: githubRole.arn
+ * });
+ */
 export declare const GitHubOIDCProvider: (id: string, props: GitHubOIDCProviderProps) => Promise<OIDCProvider>;