alchemy 0.0.8 → 0.1.1

package/src/resource.ts

@@ -0,0 +1,313 @@
+import { deletions, nodes, providers } from "./global";
+import type { Inputs } from "./input";
+import { Output } from "./output";
+import type { State, StateStore } from "./state";
+
+export type ResourceID = string;
+export type ResourceType = string;
+
+export const ResourceID = Symbol.for("ResourceID");
+export const Provider = Symbol.for("Provider");
+export const Input = Symbol.for("Input");
+export const Value = Symbol.for("Value");
+export const Apply = Symbol.for("Apply");
+export const Provide = Symbol.for("Provide");
+
+// properties that pierce through the Proxy
+const OrthogonalProperties = [
+  ResourceID,
+  Provider,
+  Input,
+  Value,
+  Apply,
+  Provide,
+] as const;
+
+export type Resource<In extends any[] = any[], Out = any> = {
+  [ResourceID]: string;
+  [Provider]: Provider<any, any[], any>;
+  [Input]: Inputs<In>;
+  [Value]?: Out;
+  [Apply]: <O>(value: Out) => O;
+  [Provide]: (value: Out) => void;
+} & Output<Out>;
+
+export type Context<Outputs> = {
+  stage: string;
+  resourceID: ResourceID;
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete<T>(key: string): Promise<T | undefined>;
+  /**
+   * Indicate that this resource is being replaced.
+   * This will cause the resource to be deleted at the end of the stack's CREATE phase.
+   */
+  replace(): void;
+} & (
+  | {
+      event: "create";
+    }
+  | {
+      event: "update" | "delete";
+      output: Outputs;
+    }
+);
+
+export type Provider<
+  Type extends ResourceType = ResourceType,
+  In extends any[] = any[],
+  Out = any,
+> = {
+  type: Type;
+  update(
+    stage: string,
+    resource: Resource,
+    deps: Set<ResourceID>,
+    inputs: Inputs<In>,
+    stateStore: StateStore,
+  ): Promise<Awaited<Out>>;
+  delete(
+    stage: string,
+    resourceID: ResourceID,
+    state: State,
+    inputs: Inputs<In>,
+  ): Promise<void>;
+} & (new (
+  id: string,
+  ...inputs: Inputs<In>
+) => Resource<In, Out>);
+
+export function isResource(value: any): value is Resource {
+  return value?.[ResourceID] !== undefined;
+}
+
+export function Resource<
+  const Type extends ResourceType,
+  Args extends any[],
+  Out,
+>(
+  type: Type,
+  func: (ctx: Context<Out>, ...args: Args) => Promise<Out | void> | Out | void,
+): Provider<Type, Args, Awaited<Out>> {
+  if (providers.has(type)) {
+    throw new Error(`Resource ${type} already exists`);
+  }
+
+  interface Resource {
+    [ResourceID]: ResourceID;
+    [Provider]: Provider<Type, Args, Out>;
+    [Input]: Inputs<Args>;
+    [Value]?: Out;
+  }
+
+  class Resource {
+    static readonly type = type;
+
+    constructor(id: ResourceID, ...input: Inputs<Args>) {
+      const node = {
+        provider: Resource,
+        resource: this,
+      } as const;
+      if (nodes.has(id)) {
+        // TODO(sam): do we want to throw?
+        // it's kind of awesome that you can re-create a resource and call apply
+        // console.warn(`Resource ${id} already exists in the stack: ${stack.id}`);
+      }
+      nodes.set(id, node as any);
+
+      this[ResourceID] = id;
+      this[Provider] = Resource as any;
+      this[Input] = input;
+      this[Value] = undefined;
+      this[Provide] = (value: Out) => {
+        this[Value] = value;
+      };
+
+      return new Proxy(this, {
+        // TODO(sam): this won't work for the sub-class (class Table extends Resource)
+        getPrototypeOf() {
+          return Resource.prototype;
+        },
+        get(target: any, prop) {
+          if (OrthogonalProperties.includes(prop as any)) {
+            return target[prop];
+          } else {
+            return target[Apply]((value: Out) => value[prop as keyof Out]);
+          }
+        },
+      });
+    }
+
+    public [Apply]<U>(fn: (value: Out) => U): Output<U> {
+      return new Output<Out, U>(this as any, fn);
+    }
+
+    private box?: {
+      value: Out;
+    } = undefined;
+
+    public [Provide](value: Out) {
+      if (this.box) {
+        throw new Error(`Output ${this[ResourceID]} already has a value`);
+      }
+      this.box = { value };
+      const subscribers = this.subscribers;
+      this.subscribers = [];
+      subscribers.forEach((fn) => fn(value));
+    }
+
+    private subscribers: ((value: Out) => void)[] = [];
+
+    /**
+     * @internal
+     */
+    public subscribe(fn: (value: Out) => Promise<void>) {
+      if (this.box) {
+        fn(this.box.value);
+      } else {
+        this.subscribers.push(fn);
+      }
+    }
+
+    static async update(
+      stage: string,
+      resource: Resource,
+      deps: Set<ResourceID>,
+      inputs: Args,
+      stateStore: StateStore,
+    ): Promise<Awaited<Out | void>> {
+      // const stack = resource[ResourceStack];
+      const resourceID = resource[ResourceID];
+
+      let resourceState: State | undefined = await stateStore.get(
+        stage,
+        resourceID,
+      );
+      if (resourceState === undefined) {
+        resourceState = {
+          provider: type,
+          status: "creating",
+          data: {},
+          output: undefined,
+          deps: [...deps],
+          inputs,
+        };
+        await stateStore.set(stage, resourceID, resourceState);
+      }
+
+      // Skip update if inputs haven't changed and resource is in a stable state
+      if (
+        (resourceState.status === "created" ||
+          resourceState.status === "updated") &&
+        JSON.stringify(resourceState.inputs) === JSON.stringify(inputs)
+      ) {
+        console.log(`Skip:    ${resourceID} (no changes)`);
+        if (resourceState.output !== undefined) {
+          resource[Provide](resourceState.output);
+        }
+        return resourceState.output;
+      }
+
+      const event = resourceState.status === "creating" ? "create" : "update";
+      resourceState.status = event === "create" ? "creating" : "updating";
+      resourceState.oldInputs = resourceState.inputs;
+      resourceState.inputs = inputs;
+
+      console.log(
+        `${event === "create" ? "Create" : "Update"}:  ${resourceID}`,
+      );
+
+      await stateStore.set(stage, resourceID, resourceState);
+
+      let isReplaced = false;
+
+      const result = await func(
+        {
+          stage,
+          resourceID,
+          event,
+          output: resourceState.output,
+          replace: () => {
+            if (isReplaced) {
+              console.warn(
+                `Resource ${type} ${resourceID} is already marked as REPLACE`,
+              );
+              return;
+            }
+            isReplaced = true;
+            deletions.push({
+              id: resourceID,
+              data: {
+                ...resourceState!.data,
+              },
+              inputs: inputs,
+            });
+          },
+          get: (key) => resourceState!.data[key],
+          set: async (key, value) => {
+            resourceState!.data[key] = value;
+            await stateStore.set(stage, resourceID, resourceState!);
+          },
+          delete: async (key) => {
+            const value = resourceState!.data[key];
+            delete resourceState!.data[key];
+            await stateStore.set(stage, resourceID, resourceState!);
+            return value;
+          },
+        },
+        ...inputs,
+      );
+
+      console.log(
+        `${event === "create" ? "Created" : "Updated"}: ${resourceID}`,
+      );
+      await stateStore.set(stage, resourceID, {
+        provider: type,
+        data: resourceState.data,
+        status: event === "create" ? "created" : "updated",
+        output: result,
+        inputs,
+        deps: [...deps],
+      });
+      if (result !== undefined) {
+        resource[Provide](result);
+      }
+      return result;
+    }
+
+    static async delete(
+      stage: string,
+      resourceID: ResourceID,
+      state: State,
+      inputs: Args,
+    ) {
+      console.log(`Delete:  ${resourceID}`);
+      await func(
+        {
+          stage,
+          resourceID: resourceID,
+          event: "delete",
+          output: state.output,
+          replace() {
+            throw new Error("Cannot replace a resource that is being deleted");
+          },
+          get: (key) => {
+            return state.data[key];
+          },
+          set: async (key, value) => {
+            state.data[key] = value;
+          },
+          delete: async (key) => {
+            const value = state.data[key];
+            delete state.data[key];
+            return value;
+          },
+        },
+        ...inputs,
+      );
+      console.log(`Deleted: ${resourceID}`);
+    }
+  }
+  providers.set(type, Resource as any);
+  return Resource as any;
+}

package/src/state.ts

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export interface State {
+  status:
+    | `creating`
+    | `created`
+    | `updating`
+    | `updated`
+    | `deleting`
+    | `deleted`;
+  provider: string;
+  data: Record<string, any>;
+  deps: string[];
+  inputs: any[];
+  oldInputs?: any[];
+  output: any;
+}
+
+export interface StateStore {
+  init?(): Promise<void>;
+  /** List all resources in the given stage. */
+  list(stage: string): Promise<string[]>;
+  get(stage: string, key: string): Promise<State | undefined>;
+  getBatch(stage: string, ids: string[]): Promise<Record<string, State>>;
+  all(stage: string): Promise<Record<string, State>>;
+  set(stage: string, key: string, value: State): Promise<void>;
+  delete(stage: string, key: string): Promise<void>;
+}
+
+const stateFile = path.join(process.cwd(), ".alchemy");
+
+/**
+ * @internal
+ */
+export const defaultStore: StateStore = {
+  async init() {
+    await fs.promises.mkdir(stateFile, { recursive: true });
+  },
+  async list(stage) {
+    try {
+      return (await fs.promises.readdir(path.join(stateFile, stage))).map(
+        (file) => file.replace(/\.json$/, ""),
+      );
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return [];
+      }
+      throw error;
+    }
+  },
+  async get(stage, key) {
+    try {
+      const content = await fs.promises.readFile(
+        await getPath(stage, key),
+        "utf8",
+      );
+      return JSON.parse(content) as State;
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  },
+  async set(stage, key, value) {
+    return fs.promises.writeFile(
+      await getPath(stage, key),
+      JSON.stringify(value, null, 2),
+    );
+  },
+  async delete(stage, key) {
+    return fs.promises.unlink(await getPath(stage, key));
+  },
+  async all(stage: string): Promise<Record<string, State>> {
+    return this.getBatch(stage, await this.list(stage));
+  },
+  async getBatch(stage: string, ids: string[]): Promise<Record<string, State>> {
+    return Object.fromEntries(
+      (
+        await Promise.all(
+          Array.from(ids).flatMap(async (id) => {
+            const s = await this.get(stage, id);
+            if (s === undefined) {
+              return [] as const;
+            }
+            return [[id, s]] as const;
+          }),
+        )
+      ).flat(),
+    );
+  },
+};
+
+async function getPath(stage: string, key: string) {
+  const file = path.join(stateFile, stage, `${key}.json`);
+  const dir = path.dirname(file);
+  await fs.promises.mkdir(dir, { recursive: true });
+  return file;
+}

package/test/aws/function.test.ts

@@ -0,0 +1,144 @@
+import {
+  GetFunctionCommand,
+  InvokeCommand,
+  LambdaClient,
+  ResourceNotFoundException,
+} from "@aws-sdk/client-lambda";
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { apply } from "../../src/apply";
+import { Function } from "../../src/components/aws/function";
+import type { PolicyDocument } from "../../src/components/aws/policy";
+import { Role } from "../../src/components/aws/role";
+import { Bundle } from "../../src/components/esbuild";
+import { destroy } from "../../src/destroy";
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+
+const lambda = new LambdaClient({});
+
+describe("AWS Resources", () => {
+  describe("Function", () => {
+    test("create function with bundled code", async () => {
+      // First create the execution role
+      const assumeRolePolicy: PolicyDocument = {
+        Version: "2012-10-17",
+        Statement: [
+          {
+            Effect: "Allow",
+            Principal: {
+              Service: "lambda.amazonaws.com",
+            },
+            Action: "sts:AssumeRole",
+          },
+        ],
+      };
+
+      const logsPolicy: PolicyDocument = {
+        Version: "2012-10-17",
+        Statement: [
+          {
+            Effect: "Allow",
+            Action: [
+              "logs:CreateLogGroup",
+              "logs:CreateLogStream",
+              "logs:PutLogEvents",
+            ],
+            Resource: "*",
+          },
+        ],
+      };
+
+      const role = new Role("alchemy-test-lambda-role", {
+        roleName: "alchemy-test-lambda-role",
+        assumeRolePolicy,
+        description: "Test role for Lambda function",
+        policies: [
+          {
+            policyName: "logs",
+            policyDocument: logsPolicy,
+          },
+        ],
+        tags: {
+          Environment: "test",
+        },
+      });
+
+      const roleOutput = await apply(role);
+
+      // Bundle the handler code
+      const bundle = new Bundle("test-lambda-bundle", {
+        entryPoint: path.join(__dirname, "..", "handler.ts"),
+        outdir: ".out",
+        format: "cjs",
+        platform: "node",
+        target: "node18",
+      });
+
+      const bundleOutput = await apply(bundle);
+
+      // Create the Lambda function
+      const func = new Function("alchemy-test-function", {
+        functionName: "alchemy-test-function",
+        zipPath: bundleOutput.path,
+        roleArn: roleOutput.arn,
+        handler: "handler.handler",
+        runtime: "nodejs20.x",
+        tags: {
+          Environment: "test",
+        },
+      });
+
+      const output = await apply(func);
+      expect(output.id).toBe("alchemy-test-function");
+      expect(output.arn).toMatch(
+        /^arn:aws:lambda:[a-z0-9-]+:\d+:function:alchemy-test-function$/,
+      );
+      expect(output.state).toBe("Active");
+      expect(output.lastUpdateStatus).toBe("Successful");
+      expect(output.invokeArn).toMatch(
+        /^arn:aws:apigateway:[a-z0-9-]+:lambda:path\/2015-03-31\/functions\/arn:aws:lambda:[a-z0-9-]+:\d+:function:alchemy-test-function\/invocations$/,
+      );
+
+      // Immediately apply again to test stabilization logic
+      const secondOutput = await apply(func);
+      expect(secondOutput.state).toBe("Active");
+      expect(secondOutput.lastUpdateStatus).toBe("Successful");
+
+      // Invoke the function
+      const testEvent = { test: "event" };
+      const invokeResponse = await lambda.send(
+        new InvokeCommand({
+          FunctionName: output.functionName,
+          Payload: JSON.stringify(testEvent),
+        }),
+      );
+
+      // Parse the response
+      const responsePayload = new TextDecoder().decode(invokeResponse.Payload);
+      const response = JSON.parse(responsePayload);
+      expect(response.statusCode).toBe(200);
+
+      const body = JSON.parse(response.body);
+      expect(body.message).toBe("Hello from bundled handler!");
+      expect(body.event).toEqual(testEvent);
+
+      // Clean up
+      await destroy(func);
+      await destroy(bundle);
+      await destroy(role);
+
+      await assertFunctionNotExists("alchemy-test-function");
+    });
+  });
+});
+
+async function assertFunctionNotExists(functionName: string) {
+  await expect(
+    lambda.send(
+      new GetFunctionCommand({
+        FunctionName: functionName,
+      }),
+    ),
+  ).rejects.toThrow(ResourceNotFoundException);
+}

package/test/aws/queue.test.ts

@@ -0,0 +1,85 @@
+import {
+  GetQueueUrlCommand,
+  SQSClient,
+  SendMessageCommand,
+} from "@aws-sdk/client-sqs";
+import { describe, expect, test } from "bun:test";
+import { apply } from "../../src/apply";
+import { Queue } from "../../src/components/aws/queue";
+import { destroy } from "../../src/destroy";
+
+const sqs = new SQSClient({});
+
+describe("AWS Resources", () => {
+  describe("Queue", () => {
+    const queueName = "alchemy-test-queue";
+
+    test("create queue, send message, delete, and recreate", async () => {
+      // Create initial queue
+      const queue = new Queue(queueName, {
+        queueName,
+        visibilityTimeout: 30,
+        messageRetentionPeriod: 345600, // 4 days
+        tags: {
+          Environment: "test",
+        },
+      });
+
+      const output = await apply(queue);
+      expect(output.id).toBe(queueName);
+      expect(output.arn).toMatch(
+        new RegExp(`^arn:aws:sqs:[a-z0-9-]+:\\d+:${queueName}$`),
+      );
+      expect(output.url).toMatch(
+        new RegExp(
+          `^https:\\/\\/sqs\\.[a-z0-9-]+\\.amazonaws\\.com\\/\\d+\\/${queueName}$`,
+        ),
+      );
+
+      // Send a test message
+      const messageResponse = await sqs.send(
+        new SendMessageCommand({
+          QueueUrl: output.url,
+          MessageBody: "Hello from test!",
+        }),
+      );
+      expect(messageResponse.MessageId).toBeTruthy();
+
+      // Delete the queue
+      await destroy(queue);
+
+      // Verify queue is fully deleted by checking if GetQueueUrl throws
+      await expect(
+        sqs.send(
+          new GetQueueUrlCommand({
+            QueueName: queueName,
+          }),
+        ),
+      ).rejects.toThrow("The specified queue does not exist");
+
+      // Immediately try to recreate the queue - this should handle the QueueDeletedRecently error
+      const recreatedQueue = new Queue(queueName, {
+        queueName,
+        visibilityTimeout: 30,
+        messageRetentionPeriod: 345600,
+        tags: {
+          Environment: "test",
+        },
+      });
+
+      const recreatedOutput = await apply(recreatedQueue);
+      expect(recreatedOutput.id).toBe(queueName);
+      expect(recreatedOutput.arn).toMatch(
+        new RegExp(`^arn:aws:sqs:[a-z0-9-]+:\\d+:${queueName}$`),
+      );
+      expect(recreatedOutput.url).toMatch(
+        new RegExp(
+          `^https:\\/\\/sqs\\.[a-z0-9-]+\\.amazonaws\\.com\\/\\d+\\/${queueName}$`,
+        ),
+      );
+
+      // Clean up
+      await destroy(recreatedQueue);
+    });
+  });
+});