alchemy 0.2.2 → 0.2.4

package/lib/aws/ses.js

@@ -2,7 +2,48 @@ import { CreateConfigurationSetCommand, CreateEmailIdentityCommand, DeleteConfig
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 /**
- * AWS SES resource for creating and configuring Simple Email Service
+ * AWS SES Resource
+ *
+ * Creates and manages Amazon Simple Email Service (SES) configuration sets and email identities.
+ * Supports email sending configuration, DKIM signing, and identity verification.
+ *
+ * @example
+ * // Create a configuration set with sending options
+ * const configSet = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: true
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications"
+ *   }
+ * });
+ *
+ * @example
+ * // Create and verify a domain identity with DKIM
+ * const domainIdentity = await SES("domain-identity", {
+ *   emailIdentity: "example.com",
+ *   enableDkim: true,
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "transactional-emails"
+ *   }
+ * });
+ *
+ * @example
+ * // Update configuration set sending options
+ * const updatedConfig = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: false
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications",
+ *     Updated: "true"
+ *   }
+ * });
  */
 export const SES = Resource("aws::SES", async function (id, props) {
     // Create SES client

package/lib/aws/table.d.ts

@@ -1,23 +1,118 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * 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;
 }
-export declare const Table: ((this: Context<Table>, id: string, props: TableProps) => Promise<Table>) | (((this: any, id: string, props: TableProps) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Table: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Table>, id: string, props: TableProps) => Promise<Table>);

package/lib/aws/table.js

@@ -2,6 +2,42 @@ import { CreateTableCommand, DeleteTableCommand, DescribeTableCommand, DynamoDBC
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 import { withExponentialBackoff } from "../util/retry";
+/**
+ * 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 (id, props) {
     const client = new DynamoDBClient({});
     if (this.phase === "delete") {

package/lib/cloudflare/asset-manifest.js

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

package/lib/cloudflare/bound.js

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

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