alchemy 0.1.17 → 0.2.0

package/src/context.ts

@@ -0,0 +1,122 @@
+import { DestroyedSignal } from "./destroy";
+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 interface CreateContext<Out extends Resource> extends BaseContext<Out> {
+  phase: "create";
+  output?: undefined;
+}
+
+export interface UpdateContext<Out extends Resource> extends BaseContext<Out> {
+  phase: "update";
+  output: Out;
+}
+
+export interface DeleteContext<Out extends Resource> extends BaseContext<Out> {
+  phase: "delete";
+  output: Out;
+}
+
+export interface BaseContext<Out extends Resource> {
+  quiet: boolean;
+  stage: string;
+  id: ResourceID;
+  fqn: ResourceFQN;
+  scope: Scope;
+  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;
+
+  /**
+   * Terminate the resource lifecycle handler and destroy the resource.
+   *
+   * This is the final operation performed during a delete operation.
+   *
+   * It is so that the resource lifecycle handler can "return never" instead of
+   * "return undefined" so that `await MyResource()` always returns a value.
+   */
+  destroy(): never;
+  /**
+   * Create the Resource envelope (with Alchemy + User properties)
+   */
+  create(props: Omit<Out, keyof Resource>): Out;
+  /**
+   * Create the Resource envelope (with Alchemy + User properties)
+   */
+  (props: Omit<Out, keyof Resource>): Out;
+}
+
+export function context<
+  Kind extends string,
+  Props extends ResourceProps,
+  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;
+  state: State<Kind, Props, Out>;
+  replace: () => void;
+}): Context<Out> {
+  function create(props: Omit<Out, "Kind" | "ID" | "Scope">): Out {
+    return {
+      ...props,
+      Kind: kind,
+      ID: id,
+      FQN: fqn,
+      Scope: scope,
+      Seq: seq,
+    } as Out;
+  }
+  return Object.assign(create, {
+    stage: scope.stage,
+    scope,
+    id: id,
+    fqn: fqn,
+    phase,
+    output: state.output,
+    replace,
+    get: (key: string) => state.data[key],
+    set: async (key: string, value: any) => {
+      state.data[key] = value;
+    },
+    delete: async (key: string) => {
+      const value = state.data[key];
+      delete state.data[key];
+      return value;
+    },
+    quiet: scope.quiet,
+    destroy: () => {
+      throw new DestroyedSignal();
+    },
+    create,
+  }) as Context<Out>;
+}

package/src/destroy.ts

@@ -1,92 +1,143 @@
-import { defaultStage, defaultStateStore } from "./global";
-import type { Output } from "./output";
-import { Provider, ResourceID, isResource } from "./resource";
-import { type Scope, rootScope } from "./scope";
-import type { State, StateStore } from "./state";
+import { alchemy } from "./alchemy";
+import { context } from "./context";
+import { PROVIDERS, type Provider, type Resource } from "./resource";
+import { Scope } from "./scope";
+
+export class DestroyedSignal extends Error {}
 
 export interface DestroyOptions {
-  stage?: string;
-  stateStore?: StateStore;
-  scope?: Scope;
   quiet?: boolean;
+  strategy?: "sequential" | "parallel";
 }
 
-/**
- * Prune all resources from an Output and "down", i.e. that branches from it.
- */
-export async function destroy<T>(
-  output: Output<T>,
-  options?: DestroyOptions,
-): Promise<void>;
+function isScopeArgs(a: any): a is [scope: Scope, options?: DestroyOptions] {
+  return a[0] instanceof Scope;
+}
 
 /**
- * @internal
+ * Prune all resources from an Output and "down", i.e. that branches from it.
  */
-export async function destroy<T>(
-  stage: string,
-  scope: Scope,
-  resourceID: ResourceID,
-  resourceState: State,
-  resourceProvider: Provider,
-  stateStore: StateStore,
-  options: DestroyOptions,
-): Promise<void>;
-
-export async function destroy<T>(
+export async function destroy<Type extends string>(
   ...args:
-    | [Output<T>, DestroyOptions?]
-    | [string, Scope, ResourceID, State, Provider, StateStore, DestroyOptions]
+    | [scope: Scope, options?: DestroyOptions]
+    | [resource: Resource<Type> | undefined | null, options?: DestroyOptions]
 ): Promise<void> {
-  let resourceID: ResourceID;
-  let resourceState: State;
-  let resourceProvider: Provider;
-  let stage: string;
-  let stateStore: StateStore;
-  let scope: Scope | undefined = undefined;
-  let options: DestroyOptions | undefined = undefined;
-  if (args.length === 7) {
-    stage = args[0];
-    scope = args[1];
-    resourceID = args[2];
-    resourceState = args[3];
-    resourceProvider = args[4];
-    stateStore = args[5];
-    options = args[6];
-  } else if (isResource(args[0])) {
-    const resource = args[0];
-    // stage = args[1]?.stage ?? defaultStage;
-    resourceID = resource[ResourceID];
-    stage = args[1]?.stage ?? defaultStage;
-    scope = args[1]?.scope ?? rootScope;
-    const statePath = scope.getScopePath(stage);
-    stateStore = args[1]?.stateStore ?? new defaultStateStore(statePath);
-    // First destroy all dependencies
-    const _resourceState = await stateStore.get(resourceID);
-    if (_resourceState === undefined) {
-      // we have no record of this resource, we must assume it's already deleted
-      return;
-    }
-    resourceState = _resourceState;
-    resourceProvider = resource[Provider];
-    options = args[1];
-  } else {
-    console.log(args[0]);
-    throw new Error("Not implemented: must handle destroy a Output chain");
+  if (isScopeArgs(args)) {
+    const [scope, options] = args;
+    const strategy = options?.strategy ?? "sequential";
+    // destroy all active resources
+    await destroy.all(Array.from(scope.resources.values()), {
+      strategy,
+    });
+    // then detect orphans and destroy them
+    const orphans = await scope.state.all();
+    await destroy.all(
+      Object.values(orphans).map((orphan) => ({
+        ...orphan.output,
+        Scope: scope,
+      })),
+      options,
+    );
+    // finally, destroy the scope container
+    await scope.deinit();
+    return;
+  }
+
+  const [instance, options] = args;
+
+  if (!instance) {
+    return;
+  }
+
+  const Provider: Provider<Type> | undefined = 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.`,
+    );
   }
+
+  const scope = instance.Scope;
+  if (!scope) {
+    console.warn(`Resource "${instance.FQN}" has no scope`);
+  }
+  const quiet = options?.quiet ?? scope.quiet;
+
   try {
-    await resourceProvider.delete(
-      stage,
+    if (!quiet) {
+      console.log(`Delete:  "${instance.FQN}"`);
+    }
+
+    const state = (await scope.state.get(instance.ID))!;
+
+    if (state === undefined) {
+      console.warn(`Resource "${instance.FQN}" not found`);
+      return;
+    }
+
+    const ctx = context({
       scope,
-      resourceID,
-      resourceState,
-      resourceState.inputs as [],
-      options ?? {
-        quiet: false,
+      phase: "delete",
+      kind: instance.Kind,
+      id: instance.ID,
+      fqn: instance.FQN,
+      seq: instance.Seq,
+      state,
+      replace: () => {
+        throw new Error("Cannot replace a resource that is being deleted");
       },
-    );
+    });
+
+    let nestedScope: Scope | undefined;
+    try {
+      // BUG: this does not restore persisted scope
+      await alchemy.run(instance.ID, async (scope) => {
+        nestedScope = scope;
+        return Provider.handler.bind(ctx)(instance.ID, state.props);
+      });
+    } catch (err) {
+      if (err instanceof DestroyedSignal) {
+        // TODO: should we fail if the DestroyedSignal is not thrown?
+      } else {
+        throw err;
+      }
+    }
+
+    if (nestedScope) {
+      await destroy(nestedScope, options);
+    }
+
+    await scope.delete(instance.ID);
+
+    if (!quiet) {
+      console.log(`Deleted: "${instance.FQN}"`);
+    }
   } catch (error) {
     console.error(error);
     throw error;
   }
-  await stateStore.delete(resourceID);
+}
+
+export namespace destroy {
+  export async function all(resources: Resource[], options?: DestroyOptions) {
+    if (options?.strategy !== "parallel") {
+      const sorted = resources.sort((a, b) => b.Seq - a.Seq);
+      for (const resource of sorted) {
+        await destroy(resource);
+      }
+    } else {
+      await Promise.all(
+        resources.map((resource) => destroy(resource, options)),
+      );
+    }
+  }
+
+  export async function sequentially(
+    ...resources: (Resource<string> | undefined | null)[]
+  ) {
+    for (const resource of resources) {
+      if (resource) {
+        await destroy(resource);
+      }
+    }
+  }
 }

package/src/{esbuild.ts → esbuild/bundle.ts}

@@ -2,8 +2,8 @@ import * as esbuild from "esbuild";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { Resource } from "./resource";
-
+import type { Context } from "../context";
+import { Resource } from "../resource";
 export interface BundleProps {
   /**
    * Entry point for the bundle
@@ -47,7 +47,7 @@ export interface BundleProps {
   options?: Partial<esbuild.BuildOptions>;
 }
 
-export interface BundleOutput {
+export interface Bundle extends Resource<"esbuild::Bundle"> {
   /**
    * Path to the bundled file
    */
@@ -58,23 +58,27 @@ export interface BundleOutput {
   hash: string;
 }
 
-export class Bundle extends Resource(
+export const Bundle = Resource(
   "esbuild::Bundle",
   {
     alwaysUpdate: true,
   },
-  async (ctx, props: BundleProps): Promise<BundleOutput> => {
+  async function (
+    this: Context<Bundle>,
+    id: string,
+    props: BundleProps,
+  ): Promise<Bundle> {
     // Determine output path
     const outputPath = getOutputPath(props);
 
     // Ensure output directory exists
     await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
 
-    if (ctx.event === "delete") {
+    if (this.phase === "delete") {
       await fs.promises.unlink(outputPath).catch(() => {});
       // Also clean up sourcemap if it exists
       await fs.promises.unlink(outputPath + ".map").catch(() => {});
-      return { path: outputPath, hash: "" };
+      return this.destroy();
     }
 
     const result = await bundle(props);
@@ -83,32 +87,16 @@ export class Bundle extends Resource(
     const hash = crypto.createHash("sha256").update(contents).digest("hex");
 
     // Store metadata in context
-    await ctx.set("metafile", result.metafile);
-    await ctx.set("hash", hash);
+    await this.set("metafile", result.metafile);
+    await this.set("hash", hash);
 
     // Return output info
-    return {
+    return this({
       path: outputPath,
       hash,
-    };
+    });
   },
-) {
-  /**
-   * Get the metafile from the last build
-   */
-  public async getMetafile(ctx: {
-    get<T>(key: string): Promise<T | undefined>;
-  }) {
-    return ctx.get<esbuild.Metafile>("metafile");
-  }
-
-  /**
-   * Get the hash from the last build
-   */
-  public async getHash(ctx: { get<T>(key: string): Promise<T | undefined> }) {
-    return ctx.get<string>("hash");
-  }
-}
+);
 
 export async function bundle(props: BundleProps) {
   const outputPath = getOutputPath(props);

package/src/esbuild/index.ts

@@ -0,0 +1 @@
+export * from "./bundle";

package/src/fs/file.ts

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
+
+export interface File extends Resource<"fs::File"> {
+  path: string;
+  content: string;
+}
+
+export const File = Resource(
+  "fs::File",
+  async function (
+    this: Context<File>,
+    id: string,
+    {
+      path: filePath,
+      content,
+    }: {
+      path: string;
+      content: string;
+    },
+  ): Promise<File> {
+    if (this.phase === "delete") {
+      await ignore("ENOENT", async () => fs.promises.unlink(filePath));
+      return this.destroy();
+    } else {
+      await fs.promises.mkdir(path.dirname(filePath), {
+        recursive: true,
+      });
+      await fs.promises.writeFile(filePath, content);
+    }
+    return this({
+      path: filePath,
+      content,
+    });
+  },
+);

package/src/fs/folder.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
+
+export interface Folder extends Resource<"fs::Folder"> {
+  path: string;
+}
+
+export const Folder = Resource(
+  "fs::Folder",
+  async function (
+    this: Context<Folder>,
+    id: string,
+    { path: dirPath }: { path: string },
+  ): Promise<Folder> {
+    if (this.phase === "delete") {
+      // we just do a best effort attempt
+      await ignore(["ENOENT", "ENOTEMPTY"], async () =>
+        fs.promises.rmdir(dirPath),
+      );
+      return this.destroy();
+    } else {
+      await ignore("EEXIST", async () =>
+        fs.promises.mkdir(dirPath, { recursive: true }),
+      );
+    }
+    return this({
+      path: dirPath,
+    });
+  },
+);

package/src/fs/index.ts

@@ -0,0 +1,2 @@
+export * from "./file";
+export * from "./folder";

package/src/github/secret.ts

@@ -1,7 +1,8 @@
 import sodium from "libsodium-wrappers";
-import { type Context, Resource } from "../resource";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
 import { createGitHubClient, verifyGitHubAuth } from "./client";
-
 /**
  * Properties for creating or updating a GitHub Secret
  */
@@ -24,7 +25,7 @@ export interface GitHubSecretProps {
   /**
    * Secret value (will be stored securely on GitHub)
    */
-  value: string;
+  value: Secret;
 
   /**
    * Optional GitHub API token (overrides environment variable)
@@ -35,7 +36,9 @@ export interface GitHubSecretProps {
 /**
  * Output returned after Secret creation/update
  */
-export interface GitHubSecretOutput extends Omit<GitHubSecretProps, "value"> {
+export interface GitHubSecretOutput
+  extends Resource<"github::Secret">,
+    Omit<GitHubSecretProps, "value"> {
   /**
    * The ID of the resource
    */
@@ -47,50 +50,27 @@ export interface GitHubSecretOutput extends Omit<GitHubSecretProps, "value"> {
   updatedAt: string;
 }
 
-/**
- * Encrypt a value for GitHub using libsodium
- * Based on GitHub's documentation for encrypting secrets
- *
- * @param value - The secret value to encrypt
- * @param publicKey - The base64-encoded public key from GitHub
- * @returns The base64-encoded encrypted value
- */
-async function encryptValue(value: string, publicKey: string): Promise<string> {
-  // Initialize libsodium
-  await sodium.ready;
-
-  // Convert the public key from base64 to binary
-  const binKey = sodium.from_base64(publicKey, sodium.base64_variants.ORIGINAL);
-
-  // Convert the message to a Uint8Array
-  const binMessage = sodium.from_string(value);
-
-  // Encrypt the message with the public key using libsodium's sealed box
-  const encryptedBin = sodium.crypto_box_seal(binMessage, binKey);
-
-  // Convert the encrypted message to base64
-  return sodium.to_base64(encryptedBin, sodium.base64_variants.ORIGINAL);
-}
-
 /**
  * Resource for managing GitHub repository secrets
  */
-export class GitHubSecret extends Resource(
+export const GitHubSecret = Resource(
   "github::Secret",
-  async (
-    ctx: Context<GitHubSecretOutput>,
+  async function (
+    this: Context<GitHubSecretOutput>,
+    id: string,
     props: GitHubSecretProps,
-  ): Promise<GitHubSecretOutput | void> => {
+  ): Promise<GitHubSecretOutput> {
     // Create authenticated Octokit client - will automatically handle token resolution
+    /// TODO: use fetch
     const octokit = await createGitHubClient({ token: props.token });
 
     // Verify authentication and permissions
-    if (!ctx.quiet) {
+    if (!this.quiet) {
       await verifyGitHubAuth(octokit, props.owner, props.repository);
     }
 
-    if (ctx.event === "delete") {
-      if (ctx.output?.id) {
+    if (this.phase === "delete") {
+      if (this.output?.id) {
         try {
           // Delete the secret
           await octokit.rest.actions.deleteRepoSecret({
@@ -109,7 +89,7 @@ export class GitHubSecret extends Resource(
       }
 
       // Return void (a deleted resource has no content)
-      return undefined;
+      return this.destroy();
     } else {
       try {
         // Get the repository's public key for encrypting secrets
@@ -121,10 +101,13 @@ export class GitHubSecret extends Resource(
         );
 
         // Encrypt the secret value using libsodium
-        const encryptedValue = await encryptValue(props.value, publicKey.key);
+        const encryptedValue = await encryptString(
+          props.value.unencrypted,
+          publicKey.key,
+        );
 
         // Create or update the secret with the encrypted value and key_id
-        const response = await octokit.rest.actions.createOrUpdateRepoSecret({
+        await octokit.rest.actions.createOrUpdateRepoSecret({
           owner: props.owner,
           repo: props.repository,
           secret_name: props.name,
@@ -132,22 +115,15 @@ export class GitHubSecret extends Resource(
           key_id: publicKey.key_id,
         });
 
-        // Log success
-        if (!ctx.quiet) {
-          console.log(`Successfully created/updated secret: ${props.name}`);
-        }
-
         // GitHub doesn't return the secret details on create/update, so we need to construct it
-        const output: GitHubSecretOutput = {
+        return this({
           id: `${props.owner}/${props.repository}/${props.name}`,
           owner: props.owner,
           repository: props.repository,
           name: props.name,
           token: props.token,
           updatedAt: new Date().toISOString(),
-        };
-
-        return output;
+        });
       } catch (error: any) {
         if (
           error.status === 403 &&
@@ -169,4 +145,32 @@ export class GitHubSecret extends Resource(
       }
     }
   },
-) {}
+);
+
+/**
+ * Encrypt a value for GitHub using libsodium
+ * Based on GitHub's documentation for encrypting secrets
+ *
+ * @param value - The secret value to encrypt
+ * @param publicKey - The base64-encoded public key from GitHub
+ * @returns The base64-encoded encrypted value
+ */
+async function encryptString(
+  value: string,
+  publicKey: string,
+): Promise<string> {
+  // Initialize libsodium
+  await sodium.ready;
+
+  // Convert the public key from base64 to binary
+  const binKey = sodium.from_base64(publicKey, sodium.base64_variants.ORIGINAL);
+
+  // Convert the message to a Uint8Array
+  const binMessage = sodium.from_string(value);
+
+  // Encrypt the message with the public key using libsodium's sealed box
+  const encryptedBin = sodium.crypto_box_seal(binMessage, binKey);
+
+  // Convert the encrypted message to base64
+  return sodium.to_base64(encryptedBin, sodium.base64_variants.ORIGINAL);
+}