alchemy 0.2.3 → 0.2.5

package/src/aws/table.ts

@@ -13,28 +13,131 @@ import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 import { withExponentialBackoff } from "../util/retry";
 
+/**
+ * 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;
 }
 
+/**
+ * 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 (

package/src/cloudflare/bucket.ts

@@ -54,6 +54,42 @@ export interface R2Bucket
   creationDate: number;
 }
 
+/**
+ * Creates and manages Cloudflare R2 Buckets for object storage.
+ *
+ * R2 Buckets provide S3-compatible object storage with automatic data replication
+ * across multiple regions for high availability and durability.
+ *
+ * @example
+ * // Create a basic R2 bucket with default settings
+ * const basicBucket = await R2Bucket("my-app-data", {
+ *   name: "my-app-data"
+ * });
+ *
+ * @example
+ * // Create a bucket with location hint for optimal performance
+ * const euBucket = await R2Bucket("eu-user-data", {
+ *   name: "eu-user-data",
+ *   locationHint: "eu",
+ *   jurisdiction: "eu"
+ * });
+ *
+ * @example
+ * // Create a development bucket with public access enabled
+ * const publicBucket = await R2Bucket("public-assets", {
+ *   name: "public-assets",
+ *   allowPublicAccess: true
+ * });
+ *
+ * @example
+ * // Create a FedRAMP compliant bucket for government workloads
+ * const fedRampBucket = await R2Bucket("gov-data", {
+ *   name: "gov-data",
+ *   jurisdiction: "fedramp"
+ * });
+ *
+ * @see https://developers.cloudflare.com/r2/buckets/
+ */
 export const R2Bucket = Resource(
   "cloudflare::R2Bucket",
   async function (

package/src/cloudflare/durable-object-namespace.ts

@@ -1,3 +1,6 @@
+/**
+ * Properties for creating a Durable Object Namespace
+ */
 export interface DurableObjectNamespaceInput {
   className: string;
   scriptName?: string | undefined;
@@ -6,6 +9,28 @@ export interface DurableObjectNamespaceInput {
   namespaceId?: string | undefined;
 }
 
+/**
+ * @example
+ * // Create a basic Durable Object namespace for stateful chat rooms
+ * const rooms = new DurableObjectNamespace("chat-rooms", {
+ *   className: "ChatRoom"
+ * });
+ *
+ * @example
+ * // Create a Durable Object with SQLite storage for user data
+ * const users = new DurableObjectNamespace("user-store", {
+ *   className: "User",
+ *   sqlite: true
+ * });
+ *
+ * @example
+ * // Create a Durable Object in production for game state management
+ * const game = new DurableObjectNamespace("game-state", {
+ *   className: "GameState",
+ *   scriptName: "game-worker",
+ *   environment: "production"
+ * });
+ */
 export class DurableObjectNamespace implements DurableObjectNamespaceInput {
   public readonly type = "durable_object_namespace" as const;
   // alias for bindingName to be consistent with other bindings

package/src/cloudflare/kv-namespace.ts

@@ -78,6 +78,42 @@ export interface KVNamespace
   modifiedAt: number;
 }
 
+/**
+ * A Cloudflare KV Namespace is a key-value store that can be used to store data for your application.
+ *
+ * @see https://developers.cloudflare.com/kv/concepts/kv-namespaces/
+ *
+ * @example
+ * // Create a basic KV namespace for storing user data
+ * const users = await KVNamespace("users", {
+ *   title: "user-data"
+ * });
+ *
+ * @example
+ * // Create a KV namespace with initial values and TTL
+ * const sessions = await KVNamespace("sessions", {
+ *   title: "user-sessions",
+ *   values: [{
+ *     key: "session_123",
+ *     value: { userId: "user_456", role: "admin" },
+ *     expirationTtl: 3600 // Expires in 1 hour
+ *   }]
+ * });
+ *
+ * @example
+ * // Create a KV namespace with metadata for caching
+ * const assets = await KVNamespace("assets", {
+ *   title: "static-assets",
+ *   values: [{
+ *     key: "main.js",
+ *     value: "content...",
+ *     metadata: {
+ *       contentType: "application/javascript",
+ *       etag: "abc123"
+ *     }
+ *   }]
+ * });
+ */
 export const KVNamespace = Resource(
   "cloudflare::KVNamespace",
   async function (

package/src/cloudflare/static-site.ts

@@ -1,6 +1,6 @@
 import { exec } from "child_process";
 import { promises as fs } from "fs";
-import path from "path";
+import path from "node:path";
 import { promisify } from "util";
 import type { Context } from "../context";
 import type { BundleProps } from "../esbuild/bundle";
@@ -202,6 +202,58 @@ export interface StaticSite extends Resource<"cloudflare::StaticSite"> {
   routes?: Record<string, string>;
 }
 
+/**
+ * A StaticSite resource deploys static web content to Cloudflare Workers, using KV for asset storage.
+ * It provides an efficient way to serve static websites with global distribution and caching.
+ *
+ * @example
+ * // Create a basic static site with default settings
+ * const basicSite = await StaticSite("my-site", {
+ *   name: "my-site",
+ *   dir: "./dist",
+ *   url: true
+ * });
+ *
+ * @example
+ * // Create a static site with custom build command and minification disabled
+ * const devSite = await StaticSite("dev-site", {
+ *   name: "dev-site",
+ *   dir: "./public",
+ *   build: {
+ *     command: "npm run build"
+ *   },
+ *   bundle: {
+ *     minify: false
+ *   }
+ * });
+ *
+ * @example
+ * // Create a static site with a backend API worker
+ * const backend = await Worker("api-backend", {
+ *   name: "api-backend",
+ *   entrypoint: "./src/api.ts"
+ * });
+ *
+ * const fullSite = await StaticSite("full-site", {
+ *   name: "full-site",
+ *   dir: "./dist",
+ *   routes: {
+ *     "/api/*": backend
+ *   }
+ * });
+ *
+ * @example
+ * // Create a static site with custom error page and index
+ * const customSite = await StaticSite("custom-site", {
+ *   name: "custom-site",
+ *   dir: "./www",
+ *   errorPage: "404.html",
+ *   indexPage: "home.html",
+ *   domain: "www.example.com"
+ * });
+ *
+ * @see https://developers.cloudflare.com/workers/platform/sites
+ */
 export const StaticSite = Resource(
   "cloudflare::StaticSite",
   {

package/src/cloudflare/worker.ts

@@ -138,6 +138,69 @@ export interface Worker<B extends Bindings = Bindings>
   };
 }
 
+/**
+ * A Cloudflare Worker is a serverless function that can be deployed to the Cloudflare network.
+ *
+ * @example
+ * // Create a basic HTTP handler worker with custom domain routing
+ * // and workers.dev URL:
+ * const api = await Worker("api", {
+ *   name: "api-worker",
+ *   entrypoint: "./src/api.ts",
+ *   routes: ["api.example.com/*"],
+ *   url: true
+ * });
+ *
+ * @example
+ * // Create a real-time chat worker using Durable Objects
+ * // for state management:
+ * const chatRooms = new DurableObjectNamespace("chat-rooms");
+ * const userStore = new DurableObjectNamespace("user-store");
+ *
+ * const chat = await Worker("chat", {
+ *   name: "chat-worker",
+ *   entrypoint: "./src/chat.ts",
+ *   bindings: {
+ *     ROOMS: chatRooms,
+ *     USERS: userStore
+ *   },
+ * });
+ *
+ * @example
+ * // Create a worker with KV namespace for caching and data storage:
+ * const cache = await KVNamespace("cache-store");
+ * const settings = await KVNamespace("user-settings");
+ *
+ * const cacheWorker = await Worker("cache", {
+ *   name: "cache-worker",
+ *   entrypoint: "./src/cache.ts",
+ *   bindings: {
+ *     CACHE: cache,
+ *     SETTINGS: settings
+ *   }
+ * });
+ *
+ * @example
+ * // Create a worker with R2 bucket for object storage:
+ * const uploads = await R2Bucket("uploads", {
+ *   name: "user-uploads"
+ * });
+ * const assets = await R2Bucket("assets", {
+ *   name: "static-assets",
+ *   allowPublicAccess: true
+ * });
+ *
+ * const storageWorker = await Worker("storage", {
+ *   name: "storage-worker",
+ *   entrypoint: "./src/storage.ts",
+ *   bindings: {
+ *     UPLOADS: uploads,
+ *     ASSETS: assets
+ *   }
+ * });
+ *
+ * @see https://developers.cloudflare.com/workers/
+ */
 export const Worker = Resource(
   "cloudflare::Worker",
   {

package/src/cloudflare/zone.ts

@@ -245,6 +245,61 @@ export interface Zone extends Resource<"cloudflare::Zone"> {
   };
 }
 
+/**
+ * A Cloudflare Zone represents a domain and its configuration settings on Cloudflare.
+ * Zones allow you to manage DNS, SSL/TLS, caching, security and other settings for a domain.
+ *
+ * @example
+ * // Create a basic zone with default settings
+ * const basicZone = await Zone("example.com", {
+ *   name: "example.com",
+ *   type: "full",
+ *   jumpStart: true
+ * });
+ *
+ * @example
+ * // Create a zone with enhanced security settings
+ * const secureZone = await Zone("secure.example.com", {
+ *   name: "secure.example.com",
+ *   type: "full",
+ *   settings: {
+ *     ssl: "strict",
+ *     alwaysUseHttps: "on",
+ *     automaticHttpsRewrites: "on",
+ *     minTlsVersion: "1.3",
+ *     tls13: "zrt"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a zone with optimized performance settings
+ * const fastZone = await Zone("fast.example.com", {
+ *   name: "fast.example.com",
+ *   settings: {
+ *     browserCacheTtl: 7200,
+ *     brotli: "on",
+ *     zeroRtt: "on",
+ *     http2: "on",
+ *     http3: "on",
+ *     earlyHints: "on"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a development zone with specific features
+ * const devZone = await Zone("dev.example.com", {
+ *   name: "dev.example.com",
+ *   settings: {
+ *     developmentMode: "on",
+ *     emailObfuscation: "on",
+ *     hotlinkProtection: "on",
+ *     ipv6: "on",
+ *     websockets: "on"
+ *   }
+ * });
+ *
+ * @see https://developers.cloudflare.com/dns/zone-setups/
+ */
 export const Zone = Resource(
   "cloudflare::Zone",
   async function (

package/src/destroy.ts

@@ -55,7 +55,7 @@ export async function destroy<Type extends string>(
   const Provider: Provider<Type> | undefined = PROVIDERS.get(instance.Kind);
   if (!Provider) {
     throw new Error(
-      `Cannot destroy resource type ${instance.Kind} - no provider found. You may need to import the provider in your alchemy.config.ts.`,
+      `Cannot destroy resource "${instance.FQN}" type ${instance.Kind} - no provider found. You may need to import the provider in your alchemy.config.ts.`,
     );
   }
 

package/src/esbuild/bundle.ts

@@ -4,60 +4,110 @@ import fs from "node:fs";
 import path from "node:path";
 import type { Context } from "../context";
 import { Resource } from "../resource";
+
+/**
+ * Properties for creating or updating an esbuild bundle
+ */
 export interface BundleProps {
   /**
    * Entry point for the bundle
+   * Path to the source file to bundle (e.g., "src/handler.ts")
    */
   entryPoint: string;
+
   /**
    * Output directory for the bundle
+   * Directory where the bundled file will be written
    */
   outdir?: string;
+
   /**
    * Output filename for the bundle
+   * Full path to the output file, overrides outdir if specified
    */
   outfile?: string;
+
   /**
-   * Bundle format (iife, cjs, esm)
+   * Bundle format
+   * iife: Immediately Invoked Function Expression
+   * cjs: CommonJS
+   * esm: ECMAScript Modules
    */
   format?: "iife" | "cjs" | "esm";
+
   /**
-   * Target environment (e.g., 'node16', 'es2020')
+   * Target environment
+   * Examples: 'node16', 'node18', 'es2020'
    */
   target?: string | string[];
+
   /**
    * Whether to minify the output
    */
   minify?: boolean;
+
   /**
    * Whether to generate sourcemaps
+   * inline: Include sourcemap in bundle
+   * external: Generate separate .map file
+   * both: Generate both inline and external
    */
   sourcemap?: boolean | "inline" | "external" | "both";
+
   /**
    * External packages to exclude from bundle
+   * Array of package names to mark as external
    */
   external?: string[];
+
   /**
-   * Platform to target (browser, node, neutral)
+   * Platform to target
+   * browser: Browser environment
+   * node: Node.js environment
+   * neutral: Platform-agnostic
    */
   platform?: "browser" | "node" | "neutral";
+
   /**
    * Additional esbuild options
+   * Any other valid esbuild BuildOptions
    */
   options?: Partial<esbuild.BuildOptions>;
 }
 
+/**
+ * Output returned after bundle creation/update
+ */
 export interface Bundle extends Resource<"esbuild::Bundle"> {
   /**
    * Path to the bundled file
+   * Absolute or relative path to the generated bundle
    */
   path: string;
+
   /**
    * SHA-256 hash of the bundle contents
+   * Used for cache busting and content verification
    */
   hash: string;
 }
 
+/**
+ * esbuild Bundle Resource
+ *
+ * Creates and manages bundled JavaScript/TypeScript files using esbuild.
+ * Supports various output formats, sourcemaps, and platform targets.
+ *
+ * @example
+ * // Bundle a TypeScript file for Node.js
+ * const bundle = await Bundle("handler", {
+ *   entryPoint: "src/handler.ts",
+ *   outdir: ".alchemy/.out",
+ *   format: "esm",
+ *   platform: "node",
+ *   target: "node18"
+ * });
+ */
 export const Bundle = Resource(
   "esbuild::Bundle",
   {

package/src/fs/file-collection.ts

@@ -0,0 +1,24 @@
+/**
+ * Collection of files with their contents
+ */
+export type FileCollection = {
+  /**
+   * Type identifier for FileCollection
+   */
+  type: "fs::FileCollection";
+  /**
+   * Map of relative paths to file contents
+   */
+  files: {
+    [relativePath: string]: string;
+  };
+};
+
+export function isFileCollection(value: unknown): value is FileCollection {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    value.type === "fs::FileCollection"
+  );
+}

package/src/fs/file-ref.ts

@@ -0,0 +1,22 @@
+/**
+ * Reference to a file in the filesystem
+ */
+export type FileRef = {
+  /**
+   * Type identifier for FileRef
+   */
+  kind: "fs::FileRef";
+  /**
+   * Path to the file
+   */
+  path: string;
+};
+
+export function isFileRef(value: unknown): value is FileRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "fs::FileRef"
+  );
+}