alchemy 0.62.2 → 0.63.0

package/src/fs/static-json-file.ts

@@ -1,38 +0,0 @@
-import { File } from "./file.ts";
-
-/**
- * Creates a JSON file with formatted content
- *
- * @example
- * // Create a JSON configuration file
- * const config = await StaticJsonFile("config.json", {
- *   api: {
- *     endpoint: "https://api.example.com",
- *     version: "v1"
- *   },
- *   features: ["auth", "logging"]
- * });
- */
-export type StaticJsonFile = File;
-
-export async function StaticJsonFile(
-  id: string,
-  ...args: [content: any] | [path: string, content: any]
-): Promise<StaticJsonFile> {
-  const [path, content] = args.length === 1 ? [id, args[0]] : args;
-  return File(id, {
-    path,
-    content: await formatJson(content),
-  });
-}
-
-export async function formatJson(content: any) {
-  const prettier = await import("prettier");
-  return prettier.format(JSON.stringify(content), {
-    parser: "json",
-    editor: {
-      tabWidth: 2,
-      indentWidth: 2,
-    },
-  });
-}

package/src/fs/static-text-file.ts

@@ -1,23 +0,0 @@
-import { File } from "./file.ts";
-
-/**
- * Creates a plain text file
- *
- * @example
- * // Create a text file with content
- * const readme = await TextFile("README.md",
- *   "# Project Name\n\nProject description goes here."
- * );
- */
-export type StaticTextFile = File;
-
-export function StaticTextFile(
-  id: string,
-  ...args: [content: string] | [path: string, content: string]
-): Promise<StaticTextFile> {
-  const [path, content] = args.length === 1 ? [id, args[0]] : args;
-  return File(id, {
-    path,
-    content,
-  });
-}

package/src/fs/static-typescript-file.ts

@@ -1,37 +0,0 @@
-import { File } from "./file.ts";
-
-/**
- * Creates a TypeScript file with formatted content using prettier
- *
- * @example
- * // Create a TypeScript file
- * const component = await StaticTypeScriptFile("Component.ts", `
- *   interface Props {
- *     name: string;
- *     age: number;
- *   }
- *
- *   export function Component({ name, age }: Props) {
- *     return <div>Hello {name}, you are {age} years old</div>;
- *   }
- * `);
- */
-export type StaticTypeScriptFile = File;
-
-export async function StaticTypeScriptFile(
-  id: string,
-  ...args: [content: string] | [path: string, content: string]
-): Promise<StaticTypeScriptFile> {
-  const [path, content] = args.length === 1 ? [id, args[0]] : args;
-  const prettier = await import("prettier");
-  return File(id, {
-    path,
-    content: await prettier.format(content, {
-      parser: "typescript",
-      editor: {
-        tabWidth: 2,
-        indentWidth: 2,
-      },
-    }),
-  });
-}

package/src/fs/static-vue-file.ts

@@ -1,39 +0,0 @@
-import { File } from "./file.ts";
-
-export type StaticVueFile = File;
-
-/**
- * Creates a static Vue component file
- *
- * @example
- * // Create a Vue component file with content
- * const button = await StaticVueFile("Button.vue",
- *   `<template>
- *     <button class="btn">{{ text }}</button>
- *   </template>
- *
- *   <script>
- *   export default {
- *     props: {
- *       text: String
- *     }
- *   }
- *   </script>
- *
- *   <style>
- *   .btn {
- *     padding: 0.5rem 1rem;
- *   }
- *   </style>`
- * );
- */
-export function StaticVueFile(
-  id: string,
-  ...args: [content: string] | [path: string, content: string]
-): Promise<StaticVueFile> {
-  const [path, content] = args.length === 1 ? [id, args[0]] : args;
-  return File(id, {
-    path,
-    content,
-  });
-}

package/src/fs/static-yaml-file.ts

@@ -1,33 +0,0 @@
-import { File } from "./file.ts";
-/**
- * Creates a YAML file with formatted content
- *
- * @example
- * // Create a YAML configuration file
- * const config = await StaticYamlFile("config.yaml", {
- *   server: {
- *     host: "localhost",
- *     port: 3000
- *   },
- *   database: {
- *     url: "postgresql://localhost:5432/db",
- *     pool: {
- *       min: 1,
- *       max: 10
- *     }
- *   }
- * });
- */
-export type StaticYamlFile = File;
-
-export async function StaticYamlFile(
-  id: string,
-  ...args: [content: any] | [path: string, content: any]
-): Promise<StaticYamlFile> {
-  const [path, content] = args.length === 1 ? [id, args[0]] : args;
-  const yaml = await import("yaml");
-  return File(id, {
-    path,
-    content: yaml.stringify(content),
-  });
-}

package/src/internal/docs/providers.ts

@@ -1,286 +0,0 @@
-import { type } from "arktype";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { Data } from "../../ai/data.ts";
-import { Document } from "../../ai/document.ts";
-import { alchemy } from "../../alchemy.ts";
-import { Folder } from "../../fs/folder.ts";
-
-function getArg(arg: string) {
-  const idx = process.argv.findIndex((a) => a === arg);
-  return idx > -1 ? process.argv[idx + 1] : undefined;
-}
-
-const onlyProviderName = getArg("--provider");
-const onlyResourceName = getArg("--resource");
-
-export interface DocsProps {
-  /**
-   * The output directory for the docs.
-   */
-  outDir: string | Folder;
-
-  /**
-   * The source directory for the docs.
-   */
-  srcDir: string;
-
-  /**
-   * Whether to filter the docs.
-   * If true, include all docs.
-   * If false, include none.
-   * If a number, include that many providers.
-   *
-   * @default true (all docs)
-   */
-  filter?: boolean | number;
-
-  /**
-   * Whether to run in parallel.
-   *
-   * @default true
-   */
-  parallel?: boolean;
-}
-
-export type Providers = {
-  dir: string;
-  provider: string;
-  documents: Document[];
-}[];
-
-export async function Providers({
-  srcDir,
-  outDir,
-  // filter,
-  parallel = true,
-}: DocsProps): Promise<Providers> {
-  outDir = typeof outDir === "string" ? outDir : outDir.path;
-
-  const exclude = [
-    "util",
-    "test",
-    "vitepress",
-    "vite",
-    "shadcn",
-    "internal",
-    "web",
-  ];
-
-  // Get all folders in the alchemy/src directory
-  const providers = (
-    await fs.readdir(srcDir, {
-      withFileTypes: true,
-    })
-  )
-    .filter((dirent) => dirent.isDirectory() && !exclude.includes(dirent.name))
-    .map((dirent) => path.join(dirent.parentPath, dirent.name));
-
-  if (parallel) {
-    return await Promise.all(
-      providers.map((provider) =>
-        generateProviderDocs({ provider, outDir, parallel }),
-      ),
-    );
-  }
-  const generatedProviders = [];
-  for (const provider of providers) {
-    generatedProviders.push(
-      await generateProviderDocs({ provider, outDir, parallel }),
-    );
-  }
-  return generatedProviders;
-}
-
-async function generateProviderDocs({
-  provider,
-  outDir,
-  parallel,
-}: {
-  provider: string;
-  outDir: string;
-  parallel: boolean;
-}) {
-  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"));
-
-  type Group = (typeof groups)[number];
-
-  const {
-    object: { groups },
-  } = await Data(`docs/${providerName}`, {
-    model: {
-      id: "o3-mini",
-      provider: "openai",
-      options: {
-        reasoningEffort: "high",
-      },
-    },
-    freeze: onlyProviderName === undefined || onlyProviderName !== providerName,
-    temperature: 0.1,
-    schema: type({
-      groups: type({
-        identifier: type("string").describe(
-          "The identifier of the file's primary exported Resource/Function/Type, e.g. Bucket or StaticSite, AstroFile, TypeScriptFile",
-        ),
-        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(...), or it is the Workflow or DurableObject classes.
-      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's const in code (with spaces added in between each word), e.g. "Bucket" or "Function", except with spaces, e.g. "StaticSite" for "const StaticSite". Maintain all other casing.
-
-      // "Resource Name"
-      const ResourceName = Resource(...)
-    `,
-  });
-
-  const providerDocsDir = (await Folder(path.join(outDir, providerName))).path;
-
-  let documents: Document[] = [];
-  if (parallel) {
-    documents = await Promise.all(
-      groups.filter((g) => g.category === "Resource").map(generateDocument),
-    );
-  } else {
-    for (const g of groups.filter((g) => g.category === "Resource")) {
-      documents.push(await generateDocument(g));
-    }
-  }
-
-  async function generateDocument(g: Group) {
-    return Document(`docs/${providerName}/${g.identifier}`, {
-      title: g.identifier,
-      path: path.join(
-        providerDocsDir,
-        `${g.filename.replace(".ts", "").replace(".md", "")}.md`,
-      ),
-      freeze:
-        onlyResourceName !== undefined && onlyResourceName !== g.identifier,
-      model: {
-        id: "claude-3-5-sonnet-latest",
-        provider: "anthropic",
-        // options: {
-        //   reasoningEffort: "high",
-        // },
-      },
-      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.
-
-        Documentation should be written in the mdx format for an Astro Starlight documentation site.
-
-        Relevant files for the ${providerName} Service:
-        ${alchemy.files(files)}
-        
-        Write concise documentation for the "${g.identifier}" 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.identifier}
-
-        (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
-
-        (brief 1-2 sentences of what it does)
-
-        \`\`\`ts
-        import { ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
-
-        (example)
-        \`\`\`
-
-        # (one heading per variation)
-
-        (brief 1-2 sentences of what it does)
-
-        \`\`\`ts
-        import { ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
-
-        (example)
-        \`\`\`
-
-        Before writing the document, think through:
-        1. What is the minimal, most common example use case for this resource?
-        2. What are the variations (e.g. combination of different options) that are also commonly used, e.g. specifying the memory size of a lambda function.
-        3. Make sure to draw from the examples and your understanding of Alchemy.
-
-        Refer to alchemy docs to understand the context of how this documentation is consumed:
-        - ${alchemy.file("./alchemy-web/docs/what-is-alchemy.md")}
-        - ${alchemy.file("./alchemy-web/docs/getting-started.md")}
-        - ${alchemy.folder("./alchemy-web/docs/concepts/")}
-        
-        ${
-          providerName === "cloudflare"
-            ? await alchemy`# Bind to a Worker
-        (if it is a Cloudflare Resource)
-
-        (brief 1-2 sentences of what it does)
-
-        \`\`\`ts
-        import { Worker, ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
-
-        const myResource = await ${g.identifier.replaceAll(" ", "")}("my-resource", {
-          // ...
-        });
-
-        await Worker("my-worker", {
-          name: "my-worker",
-          script: "console.log('Hello, world!')",
-          bindings: {
-            myResource,
-          },
-        });
-        \`\`\``
-            : ""
-        }
-      `,
-    });
-  }
-
-  return {
-    dir: providerDocsDir,
-    provider: providerName,
-    documents,
-  };
-}

package/src/runtime/bind.ts

@@ -1,95 +0,0 @@
-import { isPromise } from "node:util/types";
-import type { Binding as CloudflareBinding } from "../cloudflare/bindings.ts";
-import type { Bound as CloudflareBound } from "../cloudflare/bound.ts";
-import { isWorkerStub } from "../cloudflare/worker-stub.ts";
-import { isWorker } from "../cloudflare/worker.ts";
-import { env } from "../env.ts";
-import { ResourceFQN, ResourceScope, type Resource } from "../resource.ts";
-import { isRuntime } from "./global.ts";
-
-/**
- * Get a Resource's Binding from the Environment.
- */
-export function getBinding<T extends Resource>(resource: T): Bound<T> {
-  return env[getBindKey(resource)] as Bound<T>;
-}
-
-export function tryGetBinding<T extends Resource>(
-  resource: T,
-): Promise<Bound<T>> | undefined {
-  if (isRuntime) {
-    return getBinding(resource);
-  }
-  return undefined;
-}
-
-/**
- * Compute a unique key for where to store a Resource's Binding.
- */
-export function getBindKey(resource: Resource): string {
-  if (isWorker(resource) || isWorkerStub(resource)) {
-    return `worker:${resource.name}`;
-  }
-  const fqn = resource[ResourceFQN];
-  const scope = resource[ResourceScope];
-  const prefix = `${scope.appName}/${scope.stage}`;
-  const key = fqn.slice(prefix.length + 1).replace(/[^a-zA-Z0-9-_]/g, "_");
-  return key;
-}
-
-export type Bound<T> = T extends CloudflareBinding ? CloudflareBound<T> : T;
-
-/**
- * Create a lazy binding of a Resource to an environment that exposes the Resource's methods
- * throw a Proxy that delays initialization of the binding until the Resource's methods are accessed.
- *
- * This allows us to run the same code during build time and runtime.
- */
-export async function bind<T extends Resource>(
-  resource: T | Promise<T>,
-  options?: {
-    reify?: (value: T, key: string) => Promise<Bound<T>>;
-    /** @default true */
-    bindThis?: boolean;
-  },
-): Promise<Bound<T>> {
-  if (isPromise(resource)) {
-    return resource.then((r) => bind(r, options)) as Promise<Bound<T>>;
-  }
-  let _runtime: [Bound<T>] | undefined;
-  const runtime = async (): Promise<Bound<T>> =>
-    (_runtime ??= [
-      await (options?.reify
-        ? options.reify(resource, getBindKey(resource))
-        : getBinding(resource)),
-    ])[0];
-
-  return new Proxy(() => {}, {
-    get: (target: any, prop: string) => {
-      if (prop in target) {
-        return (resource as T)[prop as keyof T];
-      } else if (prop === "then" || prop === "catch" || prop === "finally") {
-        return target[prop];
-      }
-      return async (...args: any[]) => {
-        const rt: Bound<T> = await runtime();
-        if (rt === undefined) {
-          throw new Error(`Resource ${resource[ResourceFQN]} is not bound`);
-        }
-        const method = rt[prop as keyof Bound<T>];
-        if (typeof method !== "function") {
-          throw new Error(
-            `Method ${prop} on '${resource[ResourceFQN]}' is not a function`,
-          );
-        }
-        if (options?.bindThis !== false) {
-          return method.bind(rt)(...args);
-        }
-        return method(...args);
-      };
-    },
-    // apply: (target, thisArg, argArray) => {
-    //   return target(thisArg, ...argArray);
-    // },
-  }) as T & Bound<T>;
-}

package/src/runtime/global.ts

@@ -1,10 +0,0 @@
-import type { SerializedScope } from "../serde.ts";
-
-declare global {
-  const __ALCHEMY_WORKER_NAME__: string;
-  const __ALCHEMY_RUNTIME__: true;
-  const __ALCHEMY_SERIALIZED_SCOPE__: SerializedScope;
-}
-
-// __ALCHEMY_SERIALIZED_SCOPE__ is injected by esbuild when bundling a Worker
-export const isRuntime = typeof __ALCHEMY_RUNTIME__ !== "undefined";