alchemy 0.2.2 → 0.2.4

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/context.ts

@@ -9,24 +9,33 @@ import type {
 import type { Scope } from "./scope";
 import type { State } from "./state";
 
-export type Context<Out extends Resource> =
-  | CreateContext<Out>
-  | UpdateContext<Out>
-  | DeleteContext<Out>;
+export type Context<
+  Out extends Resource,
+  Props extends ResourceProps = ResourceProps,
+> = CreateContext<Out> | UpdateContext<Out, Props> | DeleteContext<Out, Props>;
 
 export interface CreateContext<Out extends Resource> extends BaseContext<Out> {
   phase: "create";
   output?: undefined;
+  props?: undefined;
 }
 
-export interface UpdateContext<Out extends Resource> extends BaseContext<Out> {
+export interface UpdateContext<
+  Out extends Resource,
+  Props extends ResourceProps = ResourceProps,
+> extends BaseContext<Out> {
   phase: "update";
   output: Out;
+  props: Props;
 }
 
-export interface DeleteContext<Out extends Resource> extends BaseContext<Out> {
+export interface DeleteContext<
+  Out extends Resource,
+  Props extends ResourceProps = ResourceProps,
+> extends BaseContext<Out> {
   phase: "delete";
   output: Out;
+  props: Props;
 }
 
 export interface BaseContext<Out extends Resource> {
@@ -43,7 +52,6 @@ export interface BaseContext<Out extends Resource> {
    * This will cause the resource to be deleted at the end of the stack's CREATE phase.
    */
   replace(): void;
-
   /**
    * Terminate the resource lifecycle handler and destroy the resource.
    *
@@ -60,12 +68,13 @@ export interface BaseContext<Out extends Resource> {
   /**
    * Create the Resource envelope (with Alchemy + User properties)
    */
+  (id: string, props: Omit<Out, keyof Resource>): Out;
   (props: Omit<Out, keyof Resource>): Out;
 }
 
 export function context<
   Kind extends string,
-  Props extends ResourceProps,
+  Props extends ResourceProps | undefined,
   Out extends Resource,
 >({
   scope,
@@ -83,14 +92,24 @@ export function context<
   id: ResourceID;
   fqn: ResourceFQN;
   seq: number;
+  props: Props;
   state: State<Kind, Props, Out>;
   replace: () => void;
 }): Context<Out> {
-  function create(props: Omit<Out, "Kind" | "ID" | "Scope">): Out {
+  function create(props: Omit<Out, "Kind" | "ID" | "Scope">): Out;
+  function create(id: string, props: Omit<Out, "Kind" | "ID" | "Scope">): Out;
+  function create(
+    ...args:
+      | [props: Omit<Out, "Kind" | "ID" | "Scope">]
+      | [id: string, props: Omit<Out, "Kind" | "ID" | "Scope">]
+  ): Out {
+    const [ID, props] =
+      typeof args[0] === "string" ? (args as [string, any]) : [id, args[0]];
+
     return {
       ...props,
       Kind: kind,
-      ID: id,
+      ID,
       FQN: fqn,
       Scope: scope,
       Seq: seq,
@@ -103,6 +122,7 @@ export function context<
     fqn: fqn,
     phase,
     output: state.output,
+    props: state.props,
     replace,
     get: (key: string) => state.data[key],
     set: async (key: string, value: any) => {

package/src/destroy.ts

@@ -23,12 +23,15 @@ export async function destroy<Type extends string>(
     | [resource: Resource<Type> | undefined | null, options?: DestroyOptions]
 ): Promise<void> {
   if (isScopeArgs(args)) {
-    const [scope, options] = args;
-    const strategy = options?.strategy ?? "sequential";
+    const [scope] = args;
+    const options = {
+      strategy: "sequential",
+      ...(args[1] ?? {}),
+    } satisfies DestroyOptions;
+
     // destroy all active resources
-    await destroy.all(Array.from(scope.resources.values()), {
-      strategy,
-    });
+    await destroy.all(Array.from(scope.resources.values()), options);
+
     // then detect orphans and destroy them
     const orphans = await scope.state.all();
     await destroy.all(
@@ -52,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.`,
     );
   }
 
@@ -67,10 +70,9 @@ export async function destroy<Type extends string>(
       console.log(`Delete:  "${instance.FQN}"`);
     }
 
-    const state = (await scope.state.get(instance.ID))!;
+    const state = await scope.state.get(instance.ID);
 
     if (state === undefined) {
-      console.warn(`Resource "${instance.FQN}" not found`);
       return;
     }
 
@@ -81,6 +83,7 @@ export async function destroy<Type extends string>(
       id: instance.ID,
       fqn: instance.FQN,
       seq: instance.Seq,
+      props: state.props,
       state,
       replace: () => {
         throw new Error("Cannot replace a resource that is being deleted");