alchemy 0.2.2 → 0.2.4

package/lib/alchemy.js

@@ -1,24 +1,108 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 import { DestroyedSignal, destroy } from "./destroy";
 import { Scope } from "./scope";
 import { secret } from "./secret";
 // TODO: support browser
 const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
-function _alchemy(appName, options) {
-    return scope(undefined, {
-        ...options,
-        appName,
-        stage: options.stage,
-    });
+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;
+        return scope(undefined, {
+            ...options,
+            appName,
+            stage: options?.stage,
+        });
+    }
+    else {
+        const [template, ...values] = args;
+        const [, secondLine] = template[0].split("\n");
+        const leadingSpaces = secondLine
+            ? secondLine.match(/^(\s*)/)?.[1]?.length || 0
+            : 0;
+        const indent = " ".repeat(leadingSpaces);
+        return (async () => {
+            const { isFileCollection, isFileRef } = await import("./fs");
+            const appendices = {};
+            const stringValues = await Promise.all(values.map(async function resolve(value) {
+                if (typeof value === "string") {
+                    return indent + value;
+                }
+                else if (value instanceof Promise) {
+                    return resolve(await value);
+                }
+                else if (isFileRef(value)) {
+                    if (!(value.path in appendices)) {
+                        appendices[value.path] = await fs.readFile(value.path, "utf-8");
+                    }
+                    return `[${path.basename(value.path)}](${value.path})`;
+                }
+                else if (isFileCollection(value)) {
+                    return Object.entries(value.files)
+                        .map(([filePath, content]) => {
+                        appendices[filePath] = content;
+                        return `[${path.basename(filePath)}](${filePath})`;
+                    })
+                        .join("\n\n");
+                }
+                else if (Array.isArray(value)) {
+                    return (await Promise.all(value.map(async (value, i) => `${i}. ${await resolve(value)}`))).join("\n");
+                }
+                else {
+                    // TODO: support other types
+                    throw new Error(`Unsupported value type: ${JSON.stringify(value)}`);
+                }
+            }));
+            // Construct the string template by joining template parts with interpolated values
+            const lines = template
+                .map((part) => part
+                .split("\n")
+                .map((line) => line.startsWith(indent) ? line.slice(indent.length) : line)
+                .join("\n"))
+                .flatMap((part, i) => i < stringValues.length ? [part, stringValues[i] ?? ""] : [part])
+                .join("")
+                .split("\n");
+            // Collect and sort appendices by file path
+            return [
+                // format the user prompt and trim the first line if it's empty
+                lines.length > 1 && lines[0].replaceAll(" ", "").length === 0
+                    ? lines.slice(1).join("\n")
+                    : lines.join("\n"),
+                // sort appendices by path and include at the end of the prompt
+                Object.entries(appendices)
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([filePath, content]) => {
+                    const extension = path.extname(filePath).slice(1);
+                    const codeTag = extension ? extension : "";
+                    return `// ${filePath}\n\`\`\`${codeTag}\n${content}\n\`\`\``;
+                })
+                    .join("\n\n"),
+            ].join("\n");
+        })();
+    }
 }
 _alchemy.destroy = destroy;
 _alchemy.run = run;
 _alchemy.scope = scope;
 _alchemy.secret = secret;
-export const alchemy = _alchemy;
 /**
  * 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({
@@ -31,11 +115,26 @@ 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]]
         : args;
-    await using scope = alchemy.scope(id, options);
+    const scope = alchemy.scope(id, options);
     try {
         return await fn.bind(scope)(scope);
     }
@@ -43,6 +142,11 @@ async function run(...args) {
         if (!(error instanceof DestroyedSignal)) {
             scope.fail();
         }
+        else {
+        }
         throw error;
     }
+    finally {
+        await scope.finalize();
+    }
 }

package/lib/apply.d.ts

@@ -3,4 +3,4 @@ export interface ApplyOptions {
     quiet?: boolean;
     alwaysUpdate?: boolean;
 }
-export declare function apply<Out extends Resource>(resource: PendingResource<Out>, props: ResourceProps, options?: ApplyOptions): Promise<Awaited<Out>>;
+export declare function apply<Out extends Resource>(resource: PendingResource<Out>, props: ResourceProps | undefined, options?: ApplyOptions): Promise<Awaited<Out>>;

package/lib/apply.js

@@ -1,11 +1,12 @@
 import { alchemy } from "./alchemy";
 import { context } from "./context";
 import { PROVIDERS, } from "./resource";
+import { Secret } from "./secret";
 import { serialize } from "./util/serde";
 export async function apply(resource, props, options) {
     const scope = resource.Scope;
     try {
-        const quiet = props.quiet ?? scope.quiet;
+        const quiet = props?.quiet ?? scope.quiet;
         await scope.init();
         let state = (await scope.state.get(resource.ID));
         const provider = PROVIDERS.get(resource.Kind);
@@ -35,15 +36,18 @@ export async function apply(resource, props, options) {
         const alwaysUpdate = options?.alwaysUpdate ?? provider.options?.alwaysUpdate ?? false;
         // Skip update if inputs haven't changed and resource is in a stable state
         if (state.status === "created" || state.status === "updated") {
-            if (JSON.stringify(state.props) ===
-                JSON.stringify(await serialize(scope, props)) &&
-                alwaysUpdate !== true) {
+            const oldProps = JSON.stringify(state.props, (_, value) => value instanceof Secret
+                ? {
+                    "@secret": value.unencrypted,
+                }
+                : value, 2);
+            const newProps = JSON.stringify(await serialize(scope, props, {
+                encrypt: false,
+            }), null, 2);
+            if (oldProps === newProps && alwaysUpdate !== true) {
                 if (!quiet) {
                     console.log(`Skip:    "${resource.FQN}" (no changes)`);
                 }
-                // if (resourceState.output !== undefined) {
-                //   resource[Provide](resourceState.output);
-                // }
                 return state.output;
             }
         }
@@ -63,6 +67,7 @@ export async function apply(resource, props, options) {
             id: resource.ID,
             fqn: resource.FQN,
             seq: resource.Seq,
+            props: state.oldProps,
             state,
             replace: () => {
                 if (isReplaced) {
@@ -72,9 +77,7 @@ export async function apply(resource, props, options) {
                 isReplaced = true;
             },
         });
-        const output = await alchemy.run(resource.ID, async () => {
-            return provider.handler.bind(ctx)(resource.ID, props);
-        });
+        const output = await alchemy.run(resource.ID, async () => provider.handler.bind(ctx)(resource.ID, props));
         if (!quiet) {
             console.log(`${phase === "create" ? "Created" : "Updated"}: "${resource.FQN}"`);
         }

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) => 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) => 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>);