alchemy 0.2.2 → 0.2.4

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

@@ -1,18 +1,21 @@
 import type { Resource, ResourceFQN, ResourceID, ResourceKind, ResourceProps } from "./resource";
 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> {
     quiet: boolean;
@@ -44,15 +47,17 @@ 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 declare function context<Kind extends string, Props extends ResourceProps, Out extends Resource>({ scope, phase, kind, id, fqn, seq, state, replace, }: {
+export declare function context<Kind extends string, Props extends ResourceProps | undefined, Out extends Resource>({ scope, phase, kind, id, fqn, seq, state, replace, }: {
     scope: Scope;
     phase: "create" | "update" | "delete";
     kind: ResourceKind;
     id: ResourceID;
     fqn: ResourceFQN;
     seq: number;
+    props: Props;
     state: State<Kind, Props, Out>;
     replace: () => void;
 }): Context<Out>;

package/lib/context.js

@@ -1,10 +1,11 @@
 import { DestroyedSignal } from "./destroy";
 export function context({ scope, phase, kind, id, fqn, seq, state, replace, }) {
-    function create(props) {
+    function create(...args) {
+        const [ID, props] = typeof args[0] === "string" ? args : [id, args[0]];
         return {
             ...props,
             Kind: kind,
-            ID: id,
+            ID,
             FQN: fqn,
             Scope: scope,
             Seq: seq,
@@ -17,6 +18,7 @@ export function context({ scope, phase, kind, id, fqn, seq, state, replace, }) {
         fqn: fqn,
         phase,
         output: state.output,
+        props: state.props,
         replace,
         get: (key) => state.data[key],
         set: async (key, value) => {

package/lib/destroy.js

@@ -12,12 +12,13 @@ function isScopeArgs(a) {
  */
 export async function destroy(...args) {
     if (isScopeArgs(args)) {
-        const [scope, options] = args;
-        const strategy = options?.strategy ?? "sequential";
+        const [scope] = args;
+        const options = {
+            strategy: "sequential",
+            ...(args[1] ?? {}),
+        };
         // 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(Object.values(orphans).map((orphan) => ({
@@ -34,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) {
@@ -45,9 +46,8 @@ export async function destroy(...args) {
         if (!quiet) {
             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;
         }
         const ctx = context({
@@ -57,6 +57,7 @@ export async function destroy(...args) {
             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");

package/lib/esbuild/bundle.d.ts

@@ -1,25 +1,35 @@
 import * as esbuild from "esbuild";
 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[];
     /**
@@ -28,32 +38,61 @@ export interface BundleProps {
     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;
 }
-export declare const Bundle: ((this: Context<Bundle>, id: string, props: BundleProps) => Promise<Bundle>) | (((this: any, id: string, props: BundleProps) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Bundle: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Bundle>, id: string, props: BundleProps) => Promise<Bundle>);
 export declare function bundle(props: BundleProps): Promise<esbuild.BuildResult<{
     bundle: boolean;
     splitting?: boolean;

package/lib/esbuild/bundle.js

@@ -3,6 +3,22 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { Resource } from "../resource";
+/**
+ * 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", {
     alwaysUpdate: true,
 }, async function (id, props) {

package/lib/fs/file-collection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function isFileCollection(value: unknown): value is FileCollection;

package/lib/fs/file-collection.js

@@ -0,0 +1,6 @@
+export function isFileCollection(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        value.type === "fs::FileCollection");
+}

package/lib/fs/file-ref.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reference to a file in the filesystem
+ */
+export type FileRef = {
+    /**
+     * Type identifier for FileRef
+     */
+    kind: "fs::FileRef";
+    /**
+     * Path to the file
+     */
+    path: string;
+};
+export declare function isFileRef(value: unknown): value is FileRef;

package/lib/fs/file-ref.js

@@ -0,0 +1,6 @@
+export function isFileRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "kind" in value &&
+        value.kind === "fs::FileRef");
+}

package/lib/fs/file.d.ts

@@ -1,13 +1,86 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+import type { FileCollection } from "./file-collection";
+import type { FileRef } from "./file-ref";
+declare module "../alchemy" {
+    interface Alchemy {
+        /**
+         * Creates a reference to a file in the filesystem.
+         * Used in template string interpolation to include file contents,
+         * commonly for documentation generation.
+         *
+         * @param path Path to the file
+         * @returns Promise resolving to a FileRef
+         *
+         * @example
+         * // Include a file in documentation generation
+         * await Document("api-docs", {
+         *   prompt: await alchemy`
+         *     Generate docs using the contents of:
+         *     ${alchemy.file("./README.md")}
+         *   `
+         * });
+         */
+        file(path: string): Promise<FileRef>;
+        /**
+         * Creates a collection of files with their contents.
+         * Used in template string interpolation to include multiple file contents,
+         * commonly for bulk documentation generation.
+         *
+         * @param paths Array of file paths to include in collection
+         * @returns Promise resolving to a FileCollection
+         *
+         * @example
+         * // Include multiple source files in documentation generation
+         * await Document("provider-docs", {
+         *   prompt: await alchemy`
+         *     Generate comprehensive docs for these files:
+         *     ${alchemy.files([
+         *       "src/types.ts",
+         *       "src/resource.ts",
+         *       "src/provider.ts"
+         *     ])}
+         *   `
+         * });
+         */
+        files(paths: string[]): Promise<FileCollection>;
+        files(path: string, ...paths: string[]): Promise<FileCollection>;
+    }
+}
+/**
+ * Base file resource type
+ */
 export interface File extends Resource<"fs::File"> {
+    /**
+     * Path to the file
+     */
     path: string;
+    /**
+     * Content of the file
+     */
     content: string;
 }
-export declare const File: ((this: Context<File>, id: string, { path: filePath, content, }: {
-    path: string;
-    content: string;
-}) => Promise<File>) | (((this: any, id: string, props: {
+/**
+ * File Resource
+ *
+ * Creates and manages files in the filesystem with automatic directory creation
+ * and proper cleanup on deletion.
+ *
+ * @example
+ * // Create a simple text file
+ * const config = await File("config.txt", {
+ *   path: "config.txt",
+ *   content: "some configuration data"
+ * });
+ *
+ * @example
+ * // Create a file in a nested directory
+ * const log = await File("logs/app.log", {
+ *   path: "logs/app.log",
+ *   content: "application log entry"
+ * });
+ */
+export declare const File: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<File>, id: string, props: {
     path: string;
     content: string;
-}) => never) & (new (_: never) => never));
+}) => Promise<File>);

package/lib/fs/file.js

@@ -2,7 +2,43 @@ import fs from "node:fs";
 import path from "node:path";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
-export const File = Resource("fs::File", async function (id, { path: filePath, content, }) {
+import { alchemy } from "../alchemy";
+alchemy.file = async (path) => ({
+    kind: "fs::FileRef",
+    path,
+});
+alchemy.files = async (...args) => {
+    const paths = typeof args[0] === "string" ? args : args[0];
+    return {
+        type: "fs::FileCollection",
+        files: Object.fromEntries(await Promise.all(paths.map(async (path) => [
+            path,
+            await fs.promises.readFile(path, "utf-8"),
+        ]))),
+    };
+};
+/**
+ * File Resource
+ *
+ * Creates and manages files in the filesystem with automatic directory creation
+ * and proper cleanup on deletion.
+ *
+ * @example
+ * // Create a simple text file
+ * const config = await File("config.txt", {
+ *   path: "config.txt",
+ *   content: "some configuration data"
+ * });
+ *
+ * @example
+ * // Create a file in a nested directory
+ * const log = await File("logs/app.log", {
+ *   path: "logs/app.log",
+ *   content: "application log entry"
+ * });
+ */
+export const File = Resource("fs::File", async function (id, props) {
+    const filePath = props?.path ?? id;
     if (this.phase === "delete") {
         await ignore("ENOENT", async () => fs.promises.unlink(filePath));
         return this.destroy();
@@ -11,10 +47,10 @@ export const File = Resource("fs::File", async function (id, { path: filePath, c
         await fs.promises.mkdir(path.dirname(filePath), {
             recursive: true,
         });
-        await fs.promises.writeFile(filePath, content);
+        await fs.promises.writeFile(filePath, props.content);
     }
     return this({
         path: filePath,
-        content,
+        content: props.content,
     });
 });