alchemy 0.1.2 → 0.1.4

package/README.md

@@ -1,10 +1,8 @@
 # Alchemy
 
-Alchemy is a JS-native, embeddable Infrastructure as Code (IaC) library designed to run in any JavaScript runtime, including the browser.
+Alchemy is a JS-native, embeddable library for the materialization of resource graphs. From Infrastructure-as-Code (IaC) to code generation, Alchemy provides the fundamental building blocks for modeling resources that are Created, Updated and Deleted automatically.
 
-Alchemy fully embraces AI code generation at its core, even going so far as to encourage you to fork this repo and include it in your project as a Git submodule (instead of installing as a dependency) so that you can modify the core resources to fit your needs. Contribute 'em back if you want, or not - that's fine too!
-
-AI is so damn good at CRUD, so good that we no longer need to shackle ourselves to heavy toolchains like Pulumi and Terraform. All of the pre-built components in [src/components](./alchemy/src/components) were generated in less than a few minutes. Use them if you want, or create your own. It's that easy.
+Unlike similar tools like Pulumi, Terraform, and CloudFormation, Alchemy is implemented in pure ESM-native TypeScript with zero dependencies. It can run in any JavaScript runtime, including the browser.
 
 [![Demo](./alchemy.gif)](./alchemy.gif)
 
@@ -19,10 +17,13 @@ AI is so damn good at CRUD, so good that we no longer need to shackle ourselves
 - **No service** - state files are stored locally in your project and can be easily inspected, modified, checked into your repo, etc.
 - **No strong opinions** - structure your codebase however you want, store state anywhere - we don't care!
 
-# Getting Started
+# Examples
 
-> [!NOTE]
-> You can see a comprehensive example involving a DynamoDB Table, IAM Role, Bundling and AWS Lambda [here](./examples/app.ts).
+- LLM-based code generation of all 200+ AWS CloudFormation resources: [examples/generate-aws-cfn/gen.ts](./examples/generate-aws-cfn/gen.ts)
+- Deploy an AWS Lambda Function with a DynamoDB Table and IAM Role: [examples/deploy-aws/app.ts](./examples/deploy-aws/)
+- Generate a TODO application from a Markdown document: [examples/markdown-program/index.md](./examples/markdown-program/)
+
+# Getting Started
 
 An alchemy "app" (if you want to call it that) is just an ordinary TypeScript or JavaScript script. Once you've installed the `alchemy` package, you can start using it however you want.
 
@@ -321,35 +322,3 @@ export default {
 
 > [!NOTE]
 > See [global.ts](./alchemy/src/global.ts).
-
-## Philosophy and comparison with existing IaC frameworks
-
-I built alchemy after years of working with every other option. IaC is non-negotiable in my opinion, and has been one of my favorite technologies as a developer.
-
-I started with CloudFormation (since I worked at Amazon) and hated that. Fuck deploying JSON to a slow service, am I right? The CDK was a huge upgrade on that (yay for TypeScript) but it is limited by the CloudFormation service, which is slow to _change_ and slow to _use_, and has very strong opinions on how and where it should be used.
-
-For example, the CDK is written in a "meta" language called JSII. Which is a subset of TypeScript designed to be compiled to Java, Python, etc. This means you're not free to use all TypeScript features (which are ideal for configuration as code). It's also coupled to synchronous I/O. It is damn near impossible to do anything async, making it slow and clunky. Finally, the CDK is still CJS and doesn't emit ESM. Taking a dependency on the CDK will 10x the size of your bundle and destroy your DX.
-
-Later, I moved on to Pulumi, which was a nice change of pace since it runs locally and is much faster. You can cancel a deployment by hitting Ctrl+C (hallelujah!). It also supported more than just AWS, which is useful for managing all your resources, such as Stripe, GitHub or another provider like Cloudflare.
-
-However, Pulumi is largely a wrapper around Terraform and relies on complicated "providers" implemented with Go, running in a separate process. It can't run anywhere (like the browser). Different languages work better/worse than others and always have "sharp edge" limitations and gotchas. Custom Resources are possible but more of an afterthought and a PITA to implement.
-
-I've used Terraform when I've been forced into it. It's ... ok ... but I don't love it. It's a custom DSL and a heavy toolchain for what, calling a few CRUD APIs? Way overkill. Every time I think about implementing a custom resource for Terraform, I just can't bring myself to do it. Let me just write a function, please!
-
-Lately, I've been using SST because I've been doing a ton of web development. At first, I really liked SST, especially because of its local development experience. `sst dev` gives you live deploy, a TUI multiplexer and a proxy from the cloud to your local code. This is great for building web apps in AWS.
-
-But, as my app grew, SST's bugs ate away at me. I got blocked by broken resources that have race conditions and it was impossible to workaround. I also wanted to deploy a nested app (another `sst.config.ts`) which didn't gel well with the generated `sst-env.d.ts` files.
-
-Again, I was let down by the complexity and opinions of my chosen IaC framework. And for what? To help me call a few CRUD APIs? Honestly, it just seems insane how far we've drifted away from simplicity in this area. This became even more apparent as I started using Cursor more and more to write code.
-
-You see, I've found myself doing more frontend than I've ever done before, and I'm not a good frontend developer. So, I relied on Cursor to write most of the code for me and (as many others have experienced) it totally blew my mind 🤯. Cursor is just really, really, really good at TypeScript, React and Tailwind. I've built a functioning and (if i don't say so myself) good looking SPA. It's been a blast.
-
-But, this got me thinking ... you know what else Cursor is really great at? Perhaps even better at? Interacting with CRUD APIs, that's what! While there's a ton of frontend training data for LLMs, there's just as much (if not more) training data for CRUD lifecycle operations. There's also all of Terraform, Pulumi, SST and the AWS CDK's training data. All. Of. It.
-
-Long story short, I discovered that Cursor can pretty much one-shot the implementation of Resources. All of the resources in [src/components](./alchemy/src/components) are entirely generated on-demand (1 minute time investment, tops). When I run into a bug, I just explained it to Cursor who fixed it immediately.
-
-This is a game changer. It means we don't need tools like Terraform to build suites of "provider" libraries for us. We just need the engine - the bit that tracks state and decides what to create/update/delete. The rest can be generated at near zero cost.
-
-This story is ultimately why I built Alchemy - I just wanted total control and freedom over how I deploy my resources. And, I wanted it to be in TypeScript, so I can use its amazing type system. Annnnd, I wanted it to be embeddable, so I can use it anywhere, maybe even in a React app.
-
-"Reactive IaC", anyone?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "module": "index.ts",
   "type": "module",
   "scripts": {
@@ -8,22 +8,26 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./agent": "./src/components/agent/index.ts",
-    "./fs": "./src/components/fs/index.ts",
-    "./aws": "./src/components/aws/index.ts",
-    "./esbuild": "./src/components/esbuild.ts"
+    "./agent": "./src/agent/index.ts",
+    "./aws": "./src/aws/index.ts",
+    "./esbuild": "./src/esbuild.ts",
+    "./markdown": "./src/markdown/index.ts",
+    "./fs": "./src/fs.ts",
+    "./typescript": "./src/typescript/index.ts"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@types/diff": "^5.0.0"
   },
   "peerDependencies": {
-    "@ai-sdk/openai": "^1.0.0",
+    "@ai-sdk/openai": "^1.1.9",
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@aws-sdk/client-iam": "^3.0.0",
     "@aws-sdk/client-lambda": "^3.0.0",
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/client-sqs": "^3.0.1",
-    "ai": "^4.0.0",
+    "ai": "^4.1.16",
+    "diff": "^7.0.0",
     "jszip": "^3.0.0",
     "esbuild": "^0.24.2",
     "turndown": "^7.2.0",

package/src/$.ts

@@ -0,0 +1,36 @@
+import type { Input } from "./input";
+import { type Output, isOutput } from "./output";
+
+type Primitive = string | number | boolean;
+type _Input = Primitive | Output<Primitive>;
+
+export function $(
+  template: TemplateStringsArray,
+  ...args: _Input[]
+): Input<string> {
+  const inputs = args.reduce<Output<Primitive[]> | Primitive[]>((acc, arg) => {
+    if (isOutput(arg)) {
+      if (arg === null) {
+        return acc;
+      } else {
+        return arg.apply((arg) => [...acc, arg]);
+      }
+    } else if (isOutput(acc)) {
+      return acc.apply((acc) => [...acc, arg]);
+    } else {
+      return [...acc, arg];
+    }
+  }, null as any);
+
+  function interpolate(inputs: Primitive[]) {
+    return template.reduce((acc, str, i) => {
+      return acc + str + (inputs[i] ?? "");
+    }, "");
+  }
+
+  if (isOutput(inputs)) {
+    return inputs.apply(interpolate);
+  } else {
+    return interpolate(inputs);
+  }
+}

package/src/agent/ai.ts

@@ -0,0 +1,215 @@
+import {
+  type GenerateObjectResult,
+  type LanguageModelV1,
+  generateObject as _generateObject,
+  generateText as _generateText,
+} from "ai";
+import type { z } from "zod";
+import { isOpenAIModel } from "./openai";
+
+// OpenAI error types
+interface OpenAIError extends Error {
+  status?: number;
+  code?: string;
+  type?: string;
+}
+
+/**
+ * Rate-limited wrapper around generateText
+ */
+export const generateText: typeof _generateText = async (options) => {
+  return withRateLimit(() => _generateText(options), options);
+};
+
+/**
+ * Rate-limited wrapper around generateObject
+ */
+export const generateObject: typeof _generateObject = (async <OBJECT>(
+  options: Parameters<typeof _generateObject>[0] & {
+    schema: z.Schema<OBJECT>;
+  },
+): Promise<GenerateObjectResult<OBJECT>> => {
+  return withRateLimit(() => _generateObject<OBJECT>(options as any), options);
+}) as any;
+
+/**
+ * A simple async semaphore implementation for rate limiting
+ */
+class AsyncSemaphore {
+  private permits: number;
+  private queue: Array<() => void> = [];
+
+  constructor(permits: number) {
+    this.permits = permits;
+  }
+
+  async acquire(): Promise<void> {
+    if (this.permits > 0) {
+      this.permits--;
+      return;
+    }
+
+    return new Promise<void>((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+
+  release(): void {
+    if (this.queue.length > 0) {
+      const next = this.queue.shift();
+      next?.();
+    } else {
+      this.permits++;
+    }
+  }
+}
+
+/**
+ * Configuration for rate limiting and retries
+ */
+export interface RateLimitConfig {
+  /**
+   * Maximum number of concurrent requests
+   * @default 3
+   */
+  maxConcurrent?: number;
+
+  /**
+   * Base delay for exponential backoff (in milliseconds)
+   * @default 1000
+   */
+  baseDelay?: number;
+
+  /**
+   * Maximum number of retries
+   * @default 3
+   */
+  maxRetries?: number;
+
+  /**
+   * Maximum delay for exponential backoff (in milliseconds)
+   * @default 30000
+   */
+  maxDelay?: number;
+
+  /**
+   * Jitter factor for randomizing delays (between 0 and 1)
+   * @default 0.1
+   */
+  jitter?: number;
+}
+
+// Global semaphore instances per client configuration
+const defaultConfig: Required<RateLimitConfig> = {
+  maxConcurrent: 3,
+  baseDelay: 1000,
+  maxRetries: 10,
+  maxDelay: 30000,
+  jitter: 0.1,
+};
+
+// WeakMap to store semaphores per client
+const clientSemaphores = new Map<"openai" | "anthropic", AsyncSemaphore>();
+
+/**
+ * Gets or creates a semaphore for a specific client
+ */
+function getSemaphore(client: "openai" | "anthropic"): AsyncSemaphore {
+  let semaphore = clientSemaphores.get(client);
+  if (!semaphore) {
+    semaphore = new AsyncSemaphore(defaultConfig.maxConcurrent);
+    clientSemaphores.set(client, semaphore);
+  }
+  return semaphore;
+}
+
+/**
+ * Calculates the delay for exponential backoff with jitter
+ */
+function calculateBackoffDelay(
+  attempt: number,
+  { baseDelay, maxDelay, jitter }: Required<RateLimitConfig>,
+): number {
+  const exponentialDelay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+  const jitterAmount = exponentialDelay * jitter;
+  return exponentialDelay + (Math.random() * 2 - 1) * jitterAmount;
+}
+
+/**
+ * Checks if an error is a rate limit related error
+ */
+function isRateLimitError(error: any): boolean {
+  if (error.url === "https://api.anthropic.com/v1/messages") {
+    return error.status === 429;
+  }
+
+  const openAIError = error as OpenAIError;
+
+  // Check for specific OpenAI rate limit error codes
+  if (openAIError.code) {
+    return [
+      "rate_limit_exceeded",
+      "insufficient_quota",
+      "tokens_quota_exceeded",
+      "requests_quota_exceeded",
+    ].includes(openAIError.code);
+  }
+
+  // Check for HTTP 429 status
+  if (openAIError.status === 429) return true;
+
+  // Check error types
+  if (openAIError.type) {
+    return ["tokens", "requests", "rate_limit", "capacity"].includes(
+      openAIError.type.toLowerCase(),
+    );
+  }
+
+  // Fallback to message content check
+  return (
+    openAIError.message.toLowerCase().includes("rate") ||
+    openAIError.message.toLowerCase().includes("quota") ||
+    openAIError.message.toLowerCase().includes("capacity") ||
+    openAIError.message.toLowerCase().includes("throttle")
+  );
+}
+
+/**
+ * Wraps an async function with rate limiting and exponential backoff
+ */
+async function withRateLimit<T>(
+  fn: () => Promise<T>,
+  options: { model: LanguageModelV1 },
+  config: RateLimitConfig = {},
+): Promise<T> {
+  const finalConfig = { ...defaultConfig, ...config };
+  const client = options.model;
+  const semaphore = getSemaphore(
+    isOpenAIModel(client.modelId) ? "openai" : "anthropic",
+  );
+  for (let attempt = 0; attempt <= finalConfig.maxRetries; attempt++) {
+    try {
+      await semaphore.acquire();
+      const result = await fn();
+      return result;
+    } catch (error) {
+      if (attempt === finalConfig.maxRetries) {
+        throw error;
+      }
+
+      if (!isRateLimitError(error)) {
+        throw error;
+      }
+
+      const delay = calculateBackoffDelay(attempt, finalConfig);
+      console.log(
+        `Rate limit error, retrying... (attempt ${attempt + 1}/${finalConfig.maxRetries + 1}, waiting ${Math.round(delay)}ms)`,
+      );
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    } finally {
+      semaphore.release();
+    }
+  }
+
+  throw new Error("Unexpected: Should not reach this point");
+}

package/src/{components/agent → agent}/anthropic.ts

@@ -1,14 +1,16 @@
+import { z } from "zod";
+
 /**
  * @see https://docs.anthropic.com/en/docs/about-claude/models#model-comparison-table
  */
 export const AnthropicModels = [
   // Claude 3.5 Sonnet models
-  "claude-3-5-sonnet",
+  "claude-3-5-sonnet-latest",
   "claude-3-5-sonnet-20241022",
   "claude-3-5-sonnet-20240620",
 
   // Claude 3.5 Haiku models
-  "claude-3-5-haiku",
+  "claude-3-5-haiku-latest",
   "claude-3-5-haiku-20241022",
 
   // Claude 3 models
@@ -20,6 +22,8 @@ export const AnthropicModels = [
   "claude-3-haiku-20240307",
 ] as const;
 
+export const AnthropicModel = z.enum(AnthropicModels);
+
 export type AnthropicModelId = (typeof AnthropicModels)[number] | (string & {});
 
 export function isAnthropicModel(model: string): model is AnthropicModelId {

package/src/agent/dependencies.ts

@@ -0,0 +1,62 @@
+import type { CoreMessage } from "ai";
+import type { FileContext } from "./file-context";
+
+export function dependenciesAsMessages(
+  dependencies: FileContext[] | undefined,
+): CoreMessage[] {
+  if (!dependencies?.length) return [];
+
+  const fileTree = generateFileTree(dependencies);
+
+  return [
+    {
+      role: "user" as const,
+      content: [
+        `Here are some relevant upstream files that you may need to reference.`,
+        `Existing file structure:`,
+        fileTree,
+        `File contents:`,
+        dependencies
+          .flatMap((dep) =>
+            dep.content ? [`// ${dep.path}\n${dep.content}`] : [],
+          )
+          .join("\n\n"),
+      ].join("\n"),
+    },
+    {
+      role: "assistant" as const,
+      content: "Thanks, I'll refer to those where relevant.",
+    },
+  ];
+}
+
+function generateFileTree(dependencies: FileContext[]): string {
+  const tree: { [key: string]: boolean } = {};
+
+  // Sort dependencies by path for consistent ordering
+  dependencies.sort((a, b) => a.path.localeCompare(b.path));
+
+  for (const dep of dependencies) {
+    const parts = dep.path.split("/");
+    let currentPath = "";
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const newPath = currentPath ? `${currentPath}/${part}` : part;
+      tree[newPath] = true;
+      currentPath = newPath;
+    }
+  }
+
+  const paths = Object.keys(tree);
+  let result = "";
+
+  for (const path of paths) {
+    const depth = path.split("/").length - 1;
+    const prefix = "  ".repeat(depth);
+    const name = path.split("/").pop()!;
+    result += `${prefix}${depth > 0 ? "└─ " : ""}${name}\n`;
+  }
+
+  return result;
+}

package/src/agent/file-context.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export type FileContext = z.infer<typeof FileContext>;
+
+export const FileContext = z.object({
+  path: z.string(),
+  content: z.string().optional(),
+});

package/src/agent/index.ts

@@ -0,0 +1,9 @@
+export * from "./ai";
+export * from "./anthropic";
+export * from "./dependencies";
+export * from "./file-context";
+export * from "./model";
+export * from "./module";
+export * from "./openai";
+export * from "./program";
+export * from "./scrape";

package/src/agent/model.ts

@@ -0,0 +1,39 @@
+import type { LanguageModelV1 } from "ai";
+import { z } from "zod";
+import {
+  AnthropicModel,
+  type AnthropicModelId,
+  isAnthropicModel,
+} from "./anthropic";
+import { type OpenAIChatModelId, OpenAIModel, isOpenAIModel } from "./openai";
+
+export type ModelId = OpenAIChatModelId | AnthropicModelId;
+
+export const ModelId = z.union([OpenAIModel, AnthropicModel]);
+
+const modelCache = new Map<ModelId, Promise<LanguageModelV1>>();
+
+export async function resolveModel(modelId: ModelId): Promise<LanguageModelV1> {
+  const cached = modelCache.get(modelId);
+  if (cached) {
+    return await cached;
+  }
+
+  const client = (async () => {
+    let client: LanguageModelV1;
+    if (isOpenAIModel(modelId)) {
+      const { openai } = await import("@ai-sdk/openai");
+      client = openai(modelId as OpenAIChatModelId);
+    } else if (isAnthropicModel(modelId)) {
+      const { anthropic } = await import("@ai-sdk/anthropic");
+      client = anthropic(modelId as AnthropicModelId);
+    } else {
+      throw new Error(`Unsupported model ID: ${modelId}`);
+    }
+
+    return client;
+  })();
+
+  modelCache.set(modelId, client);
+  return client;
+}