alchemy 0.2.3 → 0.2.5

package/lib/cloudflare/bucket.d.ts

@@ -43,4 +43,40 @@ export interface R2Bucket extends Resource<"cloudflare::R2Bucket">, BucketProps
      */
     creationDate: number;
 }
-export declare const R2Bucket: ((this: Context<R2Bucket>, id: string, props: BucketProps) => Promise<R2Bucket>) | (((this: any, id: string, props?: BucketProps | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const R2Bucket: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<R2Bucket>, id: string, props: BucketProps) => Promise<R2Bucket>);

package/lib/cloudflare/bucket.js

@@ -1,5 +1,41 @@
 import { Resource } from "../resource";
 import { createCloudflareApi } from "./api";
+/**
+ * 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 (id, props) {
     // Create Cloudflare API client with automatic account discovery
     const api = await createCloudflareApi();

package/lib/cloudflare/durable-object-namespace.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Properties for creating a Durable Object Namespace
+ */
 export interface DurableObjectNamespaceInput {
     className: string;
     scriptName?: string | undefined;
@@ -5,6 +8,28 @@ export interface DurableObjectNamespaceInput {
     sqlite?: boolean | undefined;
     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 declare class DurableObjectNamespace implements DurableObjectNamespaceInput {
     readonly id: string;
     readonly type: "durable_object_namespace";

package/lib/cloudflare/durable-object-namespace.js

@@ -1,3 +1,25 @@
+/**
+ * @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 {
     id;
     type = "durable_object_namespace";

package/lib/cloudflare/kv-namespace.d.ts

@@ -58,4 +58,40 @@ export interface KVNamespace extends Resource<"cloudflare::KVNamespace">, KVName
      */
     modifiedAt: number;
 }
-export declare const KVNamespace: ((this: Context<KVNamespace>, id: string, props: KVNamespaceProps) => Promise<KVNamespace>) | (((this: any, id: string, props?: KVNamespaceProps | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const KVNamespace: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<KVNamespace>, id: string, props: KVNamespaceProps) => Promise<KVNamespace>);

package/lib/cloudflare/kv-namespace.js

@@ -4,6 +4,42 @@ import { createCloudflareApi } from "./api";
 export function isKVNamespace(resource) {
     return (resource && typeof resource === "object" && resource.type === "kv_namespace");
 }
+/**
+ * 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 (id, props) {
     // Create Cloudflare API client with automatic account discovery
     const api = await createCloudflareApi();

package/lib/cloudflare/static-site.d.ts

@@ -157,4 +157,56 @@ export interface StaticSite extends Resource<"cloudflare::StaticSite"> {
      */
     routes?: Record<string, string>;
 }
-export declare const StaticSite: ((this: Context<StaticSite>, id: string, props: StaticSiteProps) => Promise<StaticSite>) | (((this: any, id: string, props?: StaticSiteProps | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const StaticSite: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<StaticSite>, id: string, props: StaticSiteProps) => Promise<StaticSite>);

package/lib/cloudflare/static-site.js

@@ -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 { Resource } from "../resource";
 import { createCloudflareApi } from "./api";
@@ -9,6 +9,58 @@ import { KVNamespace } from "./kv-namespace";
 import { uploadAssetManifest } from "./upload-asset-manifest";
 import { Worker } from "./worker";
 const __dirname = import.meta.dirname;
+/**
+ * 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", {
     alwaysUpdate: true,
 }, async function (id, props) {

package/lib/cloudflare/worker-metadata.js

@@ -1 +0,0 @@
-export {};

package/lib/cloudflare/worker.d.ts

@@ -105,4 +105,67 @@ export interface Worker<B extends Bindings = Bindings> extends Resource<"cloudfl
         [bindingName in keyof B]: Bound<B[bindingName]>;
     };
 }
-export declare const Worker: (<const B extends Bindings>(this: Context<Worker<NoInfer<B>>>, id: string, props: WorkerProps<B>) => Promise<Worker<B>>) | (((this: any, id: string, props?: WorkerProps<Bindings> | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Worker: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | (<const B extends Bindings>(this: Context<Worker<NoInfer<B>>>, id: string, props: WorkerProps<B>) => Promise<Worker<B>>);

package/lib/cloudflare/worker.js

@@ -7,6 +7,69 @@ import { slugify } from "../util/slugify";
 import { createCloudflareApi } from "./api";
 import { isDurableObjectNamespace, } from "./bindings";
 import { isKVNamespace } from "./kv-namespace";
+/**
+ * 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", {
     alwaysUpdate: true,
 }, async function (id, props) {

package/lib/cloudflare/wrangler.json.d.ts

@@ -240,4 +240,4 @@ export interface WranglerJson extends Resource<"cloudflare::WranglerJson">, Wran
 /**
  * Resource for managing wrangler.json configuration files
  */
-export declare const WranglerJson: ((this: Context<WranglerJson>, id: string, props: WranglerJsonProps) => Promise<WranglerJson>) | (((this: any, id: string, props?: WranglerJsonProps | undefined) => never) & (new (_: never) => never));
+export declare const WranglerJson: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<WranglerJson>, id: string, props: WranglerJsonProps) => Promise<WranglerJson>);

package/lib/cloudflare/zone-settings.js

@@ -1 +0,0 @@
-export {};

package/lib/cloudflare/zone.d.ts

@@ -193,4 +193,59 @@ export interface Zone extends Resource<"cloudflare::Zone"> {
         minTlsVersion: MinTLSVersionValue;
     };
 }
-export declare const Zone: ((this: Context<Zone>, id: string, props: ZoneProps) => Promise<Zone>) | (((this: any, id: string, props?: ZoneProps | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Zone: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Zone>, id: string, props: ZoneProps) => Promise<Zone>);

package/lib/cloudflare/zone.js

@@ -1,5 +1,60 @@
 import { Resource } from "../resource";
 import { createCloudflareApi } from "./api";
+/**
+ * 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 (id, props) {
     // Create Cloudflare API client with automatic account discovery
     const api = await createCloudflareApi({

package/lib/destroy.js

@@ -35,7 +35,7 @@ export async function destroy(...args) {
     }
     const Provider = 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.`);
+        throw new Error(`Cannot destroy resource "${instance.FQN}" type ${instance.Kind} - no provider found. You may need to import the provider in your alchemy.config.ts.`);
     }
     const scope = instance.Scope;
     if (!scope) {