alchemy 0.2.2 → 0.2.4

package/src/internal/docs.ts

@@ -0,0 +1,369 @@
+import { type } from "arktype";
+import fs from "fs/promises";
+import path from "path";
+import { Document } from "../ai/document";
+import { Object } from "../ai/object";
+import { alchemy } from "../alchemy";
+import { Folder } from "../fs/folder";
+import { VitePressProject } from "../vitepress/vitepress";
+
+export interface DocsProps {
+  docs?: boolean | number;
+}
+
+export type AlchemyDocs = Awaited<ReturnType<typeof AlchemyDocs>>;
+
+export async function AlchemyDocs({ docs: isDocsEnabled }: DocsProps) {
+  const root = (await Folder("alchemy-web")).path;
+
+  const docs = (await Folder(path.join(root, "docs"))).path;
+
+  const providersDir = (await Folder(path.join(docs, "providers"))).path;
+
+  const exclude = ["util", "test", "vitepress", "vite", "shadcn", "internal"];
+
+  // Get all folders in the alchemy/src directory
+  let providers = (
+    await fs.readdir(path.resolve("alchemy", "src"), {
+      withFileTypes: true,
+    })
+  )
+    .filter((dirent) => dirent.isDirectory() && !exclude.includes(dirent.name))
+    .map((dirent) => path.join(dirent.parentPath, dirent.name));
+
+  // For each provider, list all files
+  if (isDocsEnabled === false) {
+    return;
+  } else if (typeof isDocsEnabled === "number") {
+    providers = providers.slice(0, isDocsEnabled);
+  }
+
+  await Promise.all([
+    ...providers.map(async (provider) => {
+      const providerName = path.basename(provider);
+      const files = (
+        await fs.readdir(path.resolve(provider), {
+          withFileTypes: true,
+        })
+      )
+        .filter((dirent) => dirent.isFile())
+        .map((dirent) =>
+          path.relative(process.cwd(), path.resolve(provider, dirent.name)),
+        )
+        .filter((file) => file.endsWith(".ts") && !file.endsWith("index.ts"));
+
+      const {
+        object: { groups },
+      } = await Object(`docs/${providerName}`, {
+        schema: type({
+          groups: type({
+            title: type("string").describe(
+              "The title of the group, should be the Resource Name exactly without spaces, e.g. Bucket or Static Site.",
+            ),
+            filename: type("string").describe(
+              "The filename of the Resource's Document, e.g. bucket.md or static-site.md",
+            ),
+            category: type("'Resource'|'Client'|'Utility'|'Types'").describe(
+              "The classification of the Resource's Document, one of: Resource, Client, Utility, or Types.",
+            ),
+          }).array(),
+        }),
+        system: await alchemy`
+          You are a technical writer tasked with identifying the distinct documents that need to be written for a document group (folder) in a documentation site.
+          You will be provided with a list of documents and instructions on how to classify them.
+          Each document has a title, file name, and category.
+        `,
+        prompt: await alchemy`
+          Identify and classify the documents that need to be written for the '${provider}' Service's Alchemy Resources.
+          For background knowledge on Alchemy, see ${alchemy.file("./README.md")}.
+          For background knowledge on the structure of an Alchemy Resource, see ${alchemy.file("./.cursorrules")}.
+
+          The ${provider} Service has the following resources:
+          ${alchemy.files(files)}
+
+          A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...).
+          A file is considered a "Client" if it exposes a wrapper around creating a SDK client or fetch.
+          A file is considered a "Utility" if it contains utility functions that are not resources or clients.
+          A file is considered a "Types" if it contains just type definitions and maybe helpers around working with those types.
+
+          The title should be simply the name of the resource, e.g. "Bucket" or "Function", except with spaces, e.g. "Static Site" instead of "StaticSite". Maintain all other casing.
+        `,
+      });
+
+      const providerDocsDir = (
+        await Folder(path.join(providersDir, providerName))
+      ).path;
+
+      await Promise.all(
+        groups
+          .filter((g) => g.category === "Resource")
+          .map(async (g) => {
+            await Document(`docs/${providerName}/${g.title}`, {
+              path: path.join(
+                providerDocsDir,
+                `${g.filename.replace(".ts", "").replace(".md", "")}.md`,
+              ),
+              prompt: await alchemy`
+                You are a technical writer writing API documentation for an Alchemy IaC Resource.
+                See ${alchemy.file("./README.md")} to understand the overview of Alchemy.
+                See ${alchemy.file("./.cursorrules")} to better understand the structure and convention of an Alchemy Resource.
+
+                Relevant files for the ${providerName} Service:
+                ${alchemy.files(files)}
+                
+                Write concise documentation for the "${g.title}" Resource.
+
+                > [!CAUTION]
+                > Avoid the temptation to over explain or over describe. Focus on concise, simple, high value snippets. One heading and 0-1 descriptions per snippet.
+                
+                > [!TIP]
+                > Make sure the examples follow a natural progression from the minimal example to logical next steps of how the Resource might be used.
+
+                Each document must follow the following format:
+                
+                # ${g.title}
+
+                (simple description with an external link to the provider's website)
+                e.g.
+                The Efs component lets you add [Amazon Elastic File System (EFS)](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) to your app.
+
+                # Minimal Example
+
+                \`\`\`ts
+                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                (example)
+                \`\`\`
+
+
+                # Create the ${g.title}
+
+                \`\`\`ts
+                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                (example)
+                \`\`\`
+
+                ${
+                  providerName === "cloudflare"
+                    ? await alchemy`# Bind to a Worker
+                (if it is a Cloudflare Resource)
+
+                \`\`\`ts
+                import { Worker, ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                const myResource = await ${g.title.replaceAll(" ", "")}("my-resource", {
+                  // ...
+                });
+
+                await Worker("my-worker", {
+                  name: "my-worker",
+                  script: "console.log('Hello, world!')",
+                  bindings: {
+                    myResource,
+                  },
+                });
+                \`\`\``
+                    : ""
+                }
+              `,
+            });
+            // Each code snippet should use twoslash syntax for proper highlighting.
+
+            //     E.g.
+            //     \`\`\`ts twoslash
+            //     import alchemy from "alchemy";
+
+            //     alchemy
+            //     //  ^?
+
+            //     // it needs to be placed under the symbol like so:
+            //     const foo = "string";
+            //     //     ^?
+
+            //     const basicBucket = await Bucket("my-app-storage", {
+            //       //  ^?
+            //       bucketName: "my-app-storage",
+            //       tags: {
+            //         Environment: "production",
+            //         Project: "my-app"
+            //       }
+            //     });
+
+            //     alchemy.ru
+            //         //  ^|
+            //     \`\`\`
+
+            //     The \`^?\` syntax is for displaying the type of an expression.
+            //     The \`^|\` syntax is for displaying auto-completions after a dot and (optional prefix)
+          }),
+      );
+    }),
+
+    VitePressProject("docs", {
+      name: "alchemy-web",
+      title: "Alchemy",
+      description: "Alchemy is an TypeScript-native, embeddable IaC library",
+      overwrite: true,
+      delete: false,
+      tsconfig: {
+        extends: "../tsconfig.base.json",
+        references: ["../alchemy/tsconfig.json"],
+      },
+      devDependencies: {
+        alchemy: "workspace:*",
+      },
+      theme: {
+        light: "light-plus",
+        dark: "dark-plus",
+      },
+      home: {
+        layout: "home",
+        hero: {
+          text: "Alchemy",
+          tagline: "Alchemy is a TypeScript-native, embeddable IaC library",
+          actions: [
+            {
+              text: "Get Started",
+              link: "/docs",
+              theme: "brand",
+            },
+          ],
+        },
+        features: [
+          {
+            title: "Easy to use",
+            details: "Alchemy is easy to use and understand",
+          },
+        ],
+      },
+      themeConfig: {
+        sidebar: {
+          "/blog/": [
+            { text: "Blog", items: [{ text: "Blog", link: "/blog/" }] },
+          ],
+          "/docs/": [
+            {
+              text: "Getting Started",
+              items: [
+                { text: "Install", link: "/docs/getting-started/install" },
+              ],
+            },
+            {
+              text: "Guides",
+              items: [
+                {
+                  text: "Custom Resource",
+                  link: "/docs/guides/custom-resource",
+                },
+                {
+                  text: "Automating with LLMs",
+                  link: "/docs/guides/llms",
+                },
+              ],
+            },
+            {
+              text: "Core",
+              collapsed: true,
+              items: [
+                { text: "App", link: "/docs/core/app" },
+                { text: "Resource", link: "/docs/core/resource" },
+                { text: "Scope", link: "/docs/core/scope" },
+                { text: "Phase", link: "/docs/core/phase" },
+                { text: "Finalize", link: "/docs/core/finalize" },
+                { text: "State", link: "/docs/core/state" },
+                { text: "Secret", link: "/docs/core/secret" },
+                { text: "Context", link: "/docs/core/context" },
+              ],
+            },
+            {
+              text: "Resources",
+              items: [
+                {
+                  text: "AWS",
+                  link: "/docs/aws",
+                  collapsed: true,
+                  items: [
+                    { text: "Bucket", link: "/docs/aws/bucket" },
+                    { text: "Function", link: "/docs/aws/function" },
+                    { text: "Policy", link: "/docs/aws/policy" },
+                    { text: "Queue", link: "/docs/aws/queue" },
+                    { text: "Table", link: "/docs/aws/table" },
+                    { text: "Simple Email Service", link: "/docs/aws/ses" },
+                  ].sort((a, b) => a.text.localeCompare(b.text)),
+                },
+                {
+                  text: "Cloudflare",
+                  link: "/docs/cloudflare",
+                  collapsed: true,
+                  items: [
+                    { text: "Bucket", link: "/docs/cloudflare/bucket" },
+                    {
+                      text: "Durable Object",
+                      link: "/docs/cloudflare/durable-object",
+                    },
+                    {
+                      text: "Static Site",
+                      link: "/docs/cloudflare/static-site",
+                    },
+                    {
+                      text: "KV Namespace",
+                      link: "/docs/cloudflare/kv-namespace",
+                    },
+                    { text: "Worker", link: "/docs/cloudflare/worker" },
+                    { text: "Zone", link: "/docs/cloudflare/zone" },
+                  ].sort((a, b) => a.text.localeCompare(b.text)),
+                },
+                {
+                  text: "Stripe",
+                  link: "/docs/stripe",
+                  collapsed: true,
+                  items: [
+                    { text: "Product", link: "/docs/stripe/product" },
+                    { text: "Price", link: "/docs/stripe/price" },
+                  ],
+                },
+                {
+                  text: "GitHub",
+                  link: "/docs/github",
+                  collapsed: true,
+                  items: [{ text: "Secret", link: "/docs/github/secret" }],
+                },
+                {
+                  text: "File System",
+                  link: "/docs/fs",
+                  collapsed: true,
+                  items: [
+                    { text: "File", link: "/docs/fs/file" },
+                    { text: "Folder", link: "/docs/fs/folder" },
+                  ],
+                },
+              ].sort((a, b) => a.text.localeCompare(b.text)),
+            },
+          ],
+          "/examples/": [
+            {
+              text: "Examples",
+              items: [{ text: "Foo", link: "/examples/foo" }],
+            },
+          ],
+          "/": [
+            {
+              text: "Home",
+              items: [
+                { text: "Markdown Examples", link: "/markdown-examples" },
+                { text: "Runtime API Examples", link: "/api-examples" },
+              ],
+            },
+          ],
+        },
+        socialLinks: [
+          {
+            icon: "github",
+            link: "https://github.com/sam-goodwin/alchemy",
+          },
+        ],
+      },
+    }),
+  ]);
+}

package/src/resource.ts

@@ -67,7 +67,7 @@ type IsClass = {
 };
 
 type ResourceLifecycleHandler = (
-  this: Context<any>,
+  this: Context<any, any>,
   id: string,
   props: any,
 ) => Promise<Resource<string>>;
@@ -75,7 +75,7 @@ type ResourceLifecycleHandler = (
 // see: https://x.com/samgoodwin89/status/1904640134097887653
 type Handler<F extends (...args: any[]) => any> =
   | F
-  | (((this: any, id: string, props: Parameters<F>[1]) => never) & IsClass);
+  | (((this: any, id: string, props?: {}) => never) & IsClass);
 
 export function Resource<
   const Type extends string,
@@ -104,6 +104,11 @@ export function Resource<
   ): Promise<Resource<string>> => {
     const scope = _Scope.current;
 
+    if (resourceID.includes(":")) {
+      // we want to use : as an internal separator for resources
+      throw new Error(`ID cannot include colons: ${resourceID}`);
+    }
+
     if (scope.resources.has(resourceID)) {
       // TODO(sam): do we want to throw?
       // it's kind of awesome that you can re-create a resource and call apply

package/src/scope.ts

@@ -98,6 +98,14 @@ export class Scope {
     return [...this.chain, resourceID].join("/");
   }
 
+  public async run<T>(fn: (scope: Scope) => Promise<T>): Promise<T> {
+    return scopeStorage.run(this, () => fn(this));
+  }
+
+  [Symbol.asyncDispose]() {
+    return this.finalize();
+  }
+
   public async finalize() {
     if (!this.isErrored) {
       // TODO: need to detect if it is in error
@@ -118,18 +126,10 @@ export class Scope {
     }
   }
 
-  public async run<T>(fn: (scope: Scope) => Promise<T>): Promise<T> {
-    return scopeStorage.run(this, () => fn(this));
-  }
-
-  [Symbol.asyncDispose]() {
-    return this.finalize();
-  }
-
   /**
    * Returns a string representation of the scope.
    */
-  toString() {
+  public toString() {
     return `Scope(
   chain=${this.chain.join("/")},
   resources=[${Array.from(this.resources.values())

package/src/secret.ts

@@ -1,8 +1,46 @@
+/**
+ * Internal wrapper for sensitive values like API keys and credentials.
+ * When stored in alchemy state files, the value is automatically encrypted
+ * using the application's password. The password can be provided either:
+ *
+ * 1. Globally when initializing the alchemy application:
+ * ```ts
+ * const app = alchemy("my-app", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ * ```
+ *
+ * 2. For a specific scope using alchemy.run:
+ * ```ts
+ * await alchemy.run("scope-name", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * }, async () => {
+ *   // Secrets in this scope will use this password
+ *   alchemy.secret(process.env.MY_SECRET)
+ * });
+ * ```
+ *
+ * Without a password, secrets cannot be encrypted or decrypted, and operations
+ * involving sensitive values will fail.
+ *
+ * @example
+ * // In state file (.alchemy/app/prod/resource.json):
+ * {
+ *   "props": {
+ *     "apiKey": {
+ *       "@secret": "encrypted-value-here..." // encrypted using app password
+ *     }
+ *   }
+ * }
+ */
 export class Secret {
   public readonly type = "secret";
   constructor(readonly unencrypted: string) {}
 }
 
+/**
+ * Type guard to check if a value is a Secret wrapper
+ */
 export function isSecret(binding: any): binding is Secret {
   return (
     binding instanceof Secret ||
@@ -10,6 +48,35 @@ export function isSecret(binding: any): binding is Secret {
   );
 }
 
+/**
+ * Wraps a sensitive value so it will be encrypted when stored in state files.
+ * Requires a password to be set either globally in the alchemy application options
+ * or locally in an alchemy.run scope.
+ *
+ * @example
+ * // Global password for all secrets
+ * const app = alchemy("my-app", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
+ *
+ * @example
+ * // Scoped password for specific secrets
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SCOPE_SECRET_PASSPHRASE
+ * }, async () => {
+ *   const resource = await Resource("my-resource", {
+ *     apiKey: alchemy.secret(process.env.API_KEY)
+ *   });
+ * });
+ *
+ * @param unencrypted The sensitive value to encrypt in state files
+ * @throws {Error} If the value is undefined
+ * @throws {Error} If no password is set in the alchemy application options or current scope
+ */
 export function secret<S extends string | undefined>(unencrypted: S): Secret {
   if (unencrypted === undefined) {
     throw new Error("Secret cannot be undefined");

package/src/state.ts

@@ -7,7 +7,7 @@ import { deserialize, serialize } from "./util/serde";
 
 export interface State<
   Kind extends string = string,
-  Props extends ResourceProps = ResourceProps,
+  Props extends ResourceProps | undefined = ResourceProps | undefined,
   Out extends Resource = Resource,
 > {
   status:
@@ -74,7 +74,8 @@ export class FileSystemStateStore implements StateStore {
       });
       return files
         .filter((dirent) => dirent.isFile() && dirent.name.endsWith(".json"))
-        .map((dirent) => dirent.name.replace(/\.json$/, ""));
+        .map((dirent) => dirent.name.replace(/\.json$/, ""))
+        .map((key) => key.replaceAll(":", "/"));
     } catch (error: any) {
       if (error.code === "ENOENT") {
         return [];
@@ -138,6 +139,12 @@ export class FileSystemStateStore implements StateStore {
   }
 
   private async getPath(key: string): Promise<string> {
+    if (key.includes(":")) {
+      throw new Error(`ID cannot include colons: ${key}`);
+    }
+    if (key.includes("/")) {
+      key = key.replaceAll("/", ":");
+    }
     const file = path.join(this.dir, `${key}.json`);
     const dir = path.dirname(file);
     await fs.promises.mkdir(dir, { recursive: true });

package/src/stripe/price.ts

@@ -125,6 +125,56 @@ export interface Price extends Resource<"stripe::Price">, PriceProps {
   lookupKey?: string;
 }
 
+/**
+ * Create and manage Stripe prices for products
+ *
+ * @example
+ * // Create a one-time fixed price for a product
+ * const oneTimePrice = await Price("basic-license", {
+ *   currency: "usd",
+ *   unitAmount: 2999, // $29.99
+ *   product: "prod_xyz"
+ * });
+ *
+ * @example
+ * // Create a recurring subscription price with fixed monthly billing
+ * const subscriptionPrice = await Price("pro-monthly", {
+ *   currency: "usd",
+ *   unitAmount: 1499, // $14.99/month
+ *   product: "prod_xyz",
+ *   recurring: {
+ *     interval: "month",
+ *     usageType: "licensed"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a metered price for usage-based billing
+ * const meteredPrice = await Price("storage", {
+ *   currency: "usd",
+ *   unitAmount: 25, // $0.25 per GB
+ *   product: "prod_xyz",
+ *   recurring: {
+ *     interval: "month",
+ *     usageType: "metered",
+ *     aggregateUsage: "sum"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a tiered price with tax behavior
+ * const tieredPrice = await Price("enterprise", {
+ *   currency: "usd",
+ *   unitAmount: 10000, // $100.00
+ *   product: "prod_xyz",
+ *   billingScheme: "tiered",
+ *   taxBehavior: "exclusive",
+ *   metadata: {
+ *     tier: "enterprise",
+ *     features: "all"
+ *   }
+ * });
+ */
 export const Price = Resource(
   "stripe::Price",
   async function (

package/src/stripe/product.ts

@@ -99,6 +99,44 @@ export interface Product extends Resource<"stripe::Product">, ProductProps {
   };
 }
 
+/**
+ * Create and manage Stripe products
+ *
+ * @example
+ * // Create a basic digital product
+ * const digitalProduct = await Product("basic-software", {
+ *   name: "Basic Software License",
+ *   description: "Single-user license for basic software package",
+ *   metadata: {
+ *     type: "digital",
+ *     features: "basic"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a physical product with shipping details
+ * const physicalProduct = await Product("premium-hardware", {
+ *   name: "Premium Hardware Kit",
+ *   description: "Complete hardware kit with premium components",
+ *   shippable: true,
+ *   images: ["https://example.com/hardware-kit.jpg"],
+ *   unitLabel: "kit",
+ *   statementDescriptor: "PREMIUM HW KIT"
+ * });
+ *
+ * @example
+ * // Create a service product with tax code
+ * const serviceProduct = await Product("consulting", {
+ *   name: "Professional Consulting",
+ *   description: "Expert consulting services",
+ *   type: "service",
+ *   taxCode: "txcd_10000000",
+ *   metadata: {
+ *     industry: "technology",
+ *     expertise: "cloud"
+ *   }
+ * });
+ */
 export const Product = Resource(
   "stripe::Product",
   async function (