alchemy 0.53.0 → 0.55.0

package/src/util/timeout.ts

@@ -0,0 +1,178 @@
+/**
+ * Timeout configuration interface
+ */
+export interface TimeoutConfig {
+  maxAttempts: number;
+  delayMs: number;
+}
+
+/**
+ * Resource timeout error class
+ */
+export class ResourceTimeoutError extends Error {
+  constructor(
+    resourceType: string,
+    resourceId: string,
+    timeoutMs: number,
+    operation: string,
+  ) {
+    super(
+      `${resourceType} ${resourceId} did not complete ${operation} within ${timeoutMs}ms`,
+    );
+    this.name = "ResourceTimeoutError";
+  }
+}
+
+/**
+ * Validate timeout configuration
+ */
+export function validateTimeoutConfig(config: TimeoutConfig): void {
+  if (config.maxAttempts <= 0) {
+    throw new Error("maxAttempts must be greater than 0");
+  }
+  if (config.delayMs <= 0) {
+    throw new Error("delayMs must be greater than 0");
+  }
+}
+
+/**
+ * Merge default timeout configuration with optional overrides
+ */
+export function mergeTimeoutConfig(
+  defaultConfig: TimeoutConfig,
+  override?: Partial<TimeoutConfig>,
+): TimeoutConfig {
+  if (!override) {
+    return defaultConfig;
+  }
+
+  const merged = {
+    maxAttempts: override.maxAttempts ?? defaultConfig.maxAttempts,
+    delayMs: override.delayMs ?? defaultConfig.delayMs,
+  };
+
+  validateTimeoutConfig(merged);
+  return merged;
+}
+
+/**
+ * Wait for a resource to reach a desired state with configurable timeout
+ */
+export async function waitForResourceState<T>(
+  checkFunction: () => Promise<T>,
+  isReady: (result: T) => boolean,
+  config: TimeoutConfig,
+  resourceId: string,
+  resourceType: string,
+  operation = "become ready",
+): Promise<void> {
+  validateTimeoutConfig(config);
+  const { maxAttempts, delayMs } = config;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const result = await checkFunction();
+      if (isReady(result)) {
+        return;
+      }
+
+      console.log(
+        `${resourceType} ${resourceId} not ready, waiting... (attempt ${attempt}/${maxAttempts})`,
+      );
+
+      if (attempt < maxAttempts) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    } catch (error) {
+      console.log(
+        `Error checking ${resourceType} status (attempt ${attempt}/${maxAttempts}):`,
+        error,
+      );
+
+      // Check if this is a non-retryable error (contains "NonRetryableError" in the name)
+      if (error instanceof Error && error.name.includes("NonRetryableError")) {
+        throw error;
+      }
+
+      if (attempt === maxAttempts) {
+        throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  const totalTimeMs = maxAttempts * delayMs;
+  throw new ResourceTimeoutError(
+    resourceType,
+    resourceId,
+    totalTimeMs,
+    operation,
+  );
+}
+/**
+ * Generic function to wait for an operation to complete
+ * This is the most flexible version that can handle any type of operation
+ */
+export async function waitForOperation<T>(
+  checkFunction: () => Promise<T>,
+  isComplete: (result: T) => boolean,
+  config: TimeoutConfig,
+  resourceId: string,
+  resourceType: string,
+  operation = "complete",
+  onError?: (error: any, attempt: number, maxAttempts: number) => boolean, // Return true to continue retrying
+): Promise<void> {
+  validateTimeoutConfig(config);
+  const { maxAttempts, delayMs } = config;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const result = await checkFunction();
+
+      if (isComplete(result)) {
+        console.log(`${resourceType} ${resourceId} ${operation} completed`);
+        return;
+      }
+
+      console.log(
+        `${resourceType} ${resourceId} ${operation} in progress... (attempt ${attempt}/${maxAttempts})`,
+      );
+
+      if (attempt < maxAttempts) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    } catch (error) {
+      // Allow custom error handling
+      if (onError) {
+        const shouldContinue = onError(error, attempt, maxAttempts);
+        if (!shouldContinue) {
+          // If onError returns false, it means the operation completed successfully
+          // (e.g., resource was deleted and not found)
+          console.log(
+            `${resourceType} ${resourceId} ${operation} completed (via error handling)`,
+          );
+          return;
+        }
+      } else {
+        console.log(
+          `Error checking ${resourceType} ${operation} status (attempt ${attempt}/${maxAttempts}):`,
+          error,
+        );
+      }
+
+      if (attempt === maxAttempts) {
+        throw error;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  const totalTimeMs = maxAttempts * delayMs;
+  throw new ResourceTimeoutError(
+    resourceType,
+    resourceId,
+    totalTimeMs,
+    operation,
+  );
+}

package/src/util/xml.ts

@@ -0,0 +1,7 @@
+/**
+ * Extract value from XML string
+ */
+export function extractXmlValue(xml: string, tagName: string): string {
+  const match = xml.match(new RegExp(`<${tagName}>(.*?)<\/${tagName}>`));
+  return match ? match[1] : "";
+}

package/templates/nuxt/package.json

@@ -12,7 +12,7 @@
     "preview": "nuxt preview"
   },
   "dependencies": {
-    "nuxt": "^3.17.5",
+    "nuxt": "^4.0.1",
     "vue": "^3.5.16",
     "vue-router": "^4.5.1"
   },

package/templates/nuxt/types/env.d.ts

@@ -14,3 +14,14 @@ declare module "cloudflare:workers" {
     export interface Env extends CloudflareEnv {}
   }
 }
+
+declare module "h3" {
+  interface H3EventContext {
+    cf: CfProperties;
+    cloudflare: {
+      request: Request;
+      env: CloudflareEnv;
+      context: ExecutionContext;
+    };
+  }
+}

package/templates/react-router/workers/app.ts

@@ -15,9 +15,9 @@ const requestHandler = createRequestHandler(
 );
 
 export default {
-  async fetch(request, env, ctx) {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     return requestHandler(request, {
       cloudflare: { env, ctx },
     });
   },
-} satisfies ExportedHandler<Env>;
+}

package/templates/rwsdk/.cursor/rules/alchemy_cloudflare.mdc

@@ -0,0 +1,385 @@
+---
+description: Core Alchemy development guidelines and patterns
+globs: *.ts
+alwaysApply: true
+---
+# Alchemy - TypeScript-native Infrastructure as Code
+
+Alchemy is a TypeScript-native Infrastructure-as-Code framework that allows you to define cloud resources using familiar TypeScript patterns. This guide focuses on Cloudflare integration.
+
+## Core Concepts
+
+**Resources**: Async functions that manage cloud infrastructure lifecycle (create, update, delete)
+**Bindings**: Type-safe connections between resources (workers, KV stores, databases)
+**State Management**: Tracks resource state for consistent deployments
+**Finalization**: Always call `app.finalize()` to clean up orphaned resources
+
+## Basic Setup
+
+### Project Structure
+```typescript
+// alchemy.run.ts - Your infrastructure definition
+import alchemy from "alchemy";
+import { Worker, KVNamespace } from "alchemy/cloudflare";
+
+const app = await alchemy("my-app");
+
+export const worker = await Worker("api", {
+  entrypoint: "./src/worker.ts",
+  bindings: {
+    CACHE: await KVNamespace("cache", { title: "cache-store" })
+  }
+});
+
+console.log({ url: worker.url });
+await app.finalize(); // ⚠️ ALWAYS call finalize()
+```
+
+### Environment Setup
+```bash
+# .env - Required for secret encryption
+ALCHEMY_PASSWORD=your-secure-password
+
+# Optional: Use Cloudflare state store in production
+ALCHEMY_STATE_STORE=cloudflare
+```
+
+### Commands
+```bash
+bun alchemy deploy            # Deploy
+bun alchemy dev               # Local development
+bun alchemy destroy           # Destroy all resources
+```
+
+## Workers
+
+### Basic Worker
+```typescript
+const worker = await Worker("api", {
+  entrypoint: "./src/worker.ts",
+  url: true, // Get public URL
+});
+```
+
+### Worker with Bindings
+```typescript
+const worker = await Worker("api", {
+  entrypoint: "./src/worker.ts",
+  bindings: {
+    // Resource bindings
+    CACHE: kvNamespace,
+    STORAGE: r2Bucket,
+    COUNTER: durableObjectNamespace,
+    QUEUE: queue,
+    API: otherWorker,
+    
+    // Environment variables
+    API_KEY: alchemy.secret(process.env.API_KEY),
+    DEBUG: "true"
+  }
+});
+```
+
+### Worker Implementation
+```typescript
+// src/worker.ts
+import type { worker } from "../alchemy.run";
+
+export default {
+  async fetch(request: Request, env: typeof worker.Env): Promise<Response> {
+    // Type-safe access to all bindings
+    const cached = await env.CACHE.get("key");
+    const apiKey = env.API_KEY;
+    
+    return new Response("Hello World");
+  }
+};
+```
+
+### Type Safety Setup
+```typescript
+// types/env.d.ts
+import type { worker } from "../alchemy.run";
+
+declare module "cloudflare:workers" {
+  namespace Cloudflare {
+    export interface Env extends typeof worker.Env {}
+  }
+}
+```
+
+## Durable Objects
+
+### Creating Durable Object Namespace
+```typescript
+// Use 'new' instead of 'await' for DurableObjectNamespace
+const counter = DurableObjectNamespace("counter", {
+  className: "Counter",
+  sqlite: true, // Enable SQLite storage
+});
+
+const worker = await Worker("api", {
+  entrypoint: "./src/worker.ts",
+  bindings: {
+    COUNTER: counter, // Bind to worker
+  }
+});
+```
+
+### Durable Object Implementation
+```typescript
+// src/counter.ts
+import { DurableObject } from "cloudflare:workers";
+
+export class Counter extends DurableObject {
+  async increment(): Promise<number> {
+    let count = (await this.ctx.storage.get("count")) || 0;
+    count++;
+    await this.ctx.storage.put("count", count);
+    return count;
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const count = await this.increment();
+    return new Response(JSON.stringify({ count }));
+  }
+}
+```
+
+### Using Durable Objects in Worker
+```typescript
+// src/worker.ts
+export default {
+  async fetch(request: Request, env: typeof worker.Env) {
+    // Get a Durable Object instance
+    const id = env.COUNTER.idFromName("global-counter");
+    const obj = env.COUNTER.get(id);
+    
+    // Call the Durable Object
+    return obj.fetch(request);
+  }
+};
+```
+
+### Cross-Script Durable Objects
+```typescript
+// Method 1: Re-export from provider worker
+const sharedCounter = host.bindings.SHARED_COUNTER;
+
+// Method 2: Reference by worker script name
+const counter = DurableObjectNamespace("counter", {
+  className: "Counter",
+  scriptName: "provider-worker"
+});
+```
+
+## Key Resources
+
+### KV Namespace
+```typescript
+const cache = await KVNamespace("cache", {
+  title: "my-cache-store"
+});
+
+// Usage in worker
+const value = await env.CACHE.get("key");
+await env.CACHE.put("key", "value", { expirationTtl: 3600 });
+```
+
+### R2 Bucket
+```typescript
+const storage = await R2Bucket("storage", {
+  allowPublicAccess: false
+});
+
+// Usage in worker
+const object = await env.STORAGE.get("file.txt");
+await env.STORAGE.put("file.txt", "content");
+```
+
+### Queue
+```typescript
+// Typed queue
+const queue = await Queue<{ name: string; email: string }>("notifications");
+
+// Producer worker
+const producer = await Worker("producer", {
+  bindings: { QUEUE: queue },
+  // Queue sending code
+});
+
+// Consumer worker
+const consumer = await Worker("consumer", {
+  eventSources: [queue], // Register as consumer
+  // Queue processing code
+});
+
+// Worker implementation for queue processing
+export default {
+  async queue(batch: typeof queue.Batch, env: Env) {
+    for (const message of batch.messages) {
+      console.log("Processing:", message.body);
+      message.ack(); // Acknowledge message
+    }
+  }
+};
+```
+
+### Custom Domains
+```typescript
+const worker = await Worker("api", {
+  entrypoint: "./src/worker.ts",
+  routes: [
+    { pattern: "api.example.com/*", zone: "example.com" },
+    { pattern: "example.com/api/*", zone: "example.com" }
+  ]
+});
+```
+
+## Converting Existing Cloudflare Projects
+
+### 1. Migrate wrangler.toml Configuration
+```toml
+# Old wrangler.toml
+name = "my-worker"
+main = "src/index.js"
+
+[env.production]
+kv_namespaces = [
+  { binding = "CACHE", id = "abc123" }
+]
+
+[[env.production.r2_buckets]]
+binding = "STORAGE"
+bucket_name = "my-bucket"
+```
+
+```typescript
+// New alchemy.run.ts
+const worker = await Worker("my-worker", {
+  entrypoint: "./src/index.js",
+  bindings: {
+    CACHE: await KVNamespace("cache", { 
+      title: "cache-store",
+      adopt: true // Use existing KV namespace
+    }),
+    STORAGE: await R2Bucket("storage", {
+      name: "my-bucket",
+      adopt: true // Use existing bucket
+    })
+  }
+});
+```
+
+### 2. Enable Development Compatibility
+```typescript
+// Generate wrangler.json for local development
+await WranglerJson("wrangler.json", {
+  worker,
+});
+```
+
+### 3. Adopt Existing Resources
+```typescript
+// Use adopt: true to use existing resources instead of failing
+const bucket = await R2Bucket("storage", {
+  name: "existing-bucket-name",
+  adopt: true // Won't fail if bucket already exists
+});
+```
+
+### 4. State Store Migration
+```typescript
+// Local development (default)
+const app = await alchemy("my-app");
+
+// Production with Cloudflare state store
+const app = await alchemy("my-app", {
+  stateStore: process.env.NODE_ENV === "production" 
+    ? (scope) => new DOStateStore(scope)
+    : undefined
+});
+```
+
+## Advanced Patterns
+
+### Framework Integration (Vite/React/etc.)
+```typescript
+const website = await Vite("website", {
+  main: "./src/worker.ts",
+  command: "bun run build", // Build command
+  bindings: {
+    API: await Worker("api", { entrypoint: "./api/worker.ts" }),
+    STORAGE: await R2Bucket("assets")
+  }
+});
+```
+
+### Resource Scoping
+```typescript
+// Organize resources into logical groups
+await alchemy.run("backend", async () => {
+  await Worker("api", { entrypoint: "./api.ts" });
+  await KVNamespace("cache", { title: "api-cache" });
+});
+
+await alchemy.run("frontend", async () => {
+  await Vite("website", { main: "./src/worker.ts" });
+});
+```
+
+### Testing Pattern
+```typescript
+import { alchemy } from "../../src/alchemy";
+const test = alchemy.test(import.meta, { prefix: "test" });
+
+describe("Worker Tests", () => {
+  test("creates worker", async (scope) => {
+    const worker = await Worker("test-worker", {
+      entrypoint: "./src/worker.ts"
+    });
+    
+    expect(worker.url).toBeTruthy();
+    // Resources auto-cleaned after test
+  });
+});
+```
+
+## Best Practices
+
+1. **Always call finalize()**: `await app.finalize()` at the end of your script
+2. **Use adoption for migrations**: `adopt: true` when converting existing projects  
+3. **Type-safe bindings**: Set up env.d.ts for full type safety
+4. **Resource naming**: Use consistent, descriptive names for resources
+5. **State store**: Use DOStateStore for production deployments
+6. **Secrets**: Use `alchemy.secret()` for sensitive values
+7. **Scoping**: Organize related resources using `alchemy.run()`
+8. **Testing**: Use `alchemy.test()` for integration tests
+
+## Common Issues
+
+- **Missing finalize()**: Resources won't be cleaned up properly
+- **Wrong DurableObject syntax**: Use `DurableObjectNamespace()` not `await`
+- **Type errors**: Set up env.d.ts file for binding types
+- **State conflicts**: Use different stages/prefixes for different environments
+- **Resource adoption**: Use `adopt: true` when migrating existing resources
+
+## Development Workflow
+
+```bash
+# Create new project
+bunx alchemy create my-app --template=vite
+cd my-app
+
+# Set up authentication (one-time)
+bun wrangler login
+
+# Deploy infrastructure
+bun run deploy
+
+# Local development
+bun run dev
+
+# Clean up
+bun run destroy
+```

package/templates/rwsdk/wrangler.jsonc

@@ -6,8 +6,11 @@
   "assets": { "binding": "ASSETS", "directory": "dist/client" },
   "durable_objects": {
     "bindings": [
-      { "name": "SESSION_DURABLE_OBJECT", "class_name": "SessionDurableObject" }
-    ]
+      {
+        "name": "SESSION_DURABLE_OBJECT",
+        "class_name": "SessionDurableObject",
+      },
+    ],
   },
   "d1_databases": [
     {
@@ -15,14 +18,14 @@
       "database_id": "33c4fe7d-fbfe-4cef-959c-bb54292af712",
       "database_name": "my-alchemy-app-db",
       "migrations_dir": "migrations",
-      "preview_database_id": "33c4fe7d-fbfe-4cef-959c-bb54292af712"
-    }
+      "preview_database_id": "33c4fe7d-fbfe-4cef-959c-bb54292af712",
+    },
   ],
   "migrations": [
     {
       "tag": "v1",
       "new_sqlite_classes": [],
-      "new_classes": ["SessionDurableObject"]
-    }
-  ]
+      "new_classes": ["SessionDurableObject"],
+    },
+  ],
 }

package/templates/typescript/tsconfig.json

@@ -10,8 +10,7 @@
     "rewriteRelativeImportExtensions": true,
     "noEmit": true,
     "types": [
-      "@cloudflare/workers-types",
-      "@types/node"
+      "@cloudflare/workers-types"
     ]
   },
   "include": [