alchemy 0.1.17 → 0.2.0

package/src/alchemy.ts

@@ -0,0 +1,120 @@
+import { destroy } from "./destroy";
+import { Scope } from "./scope";
+import { secret } from "./secret";
+import type { StateStoreType } from "./state";
+
+// TODO: support browser
+const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
+
+function _alchemy(appName: string, options: Omit<AlchemyOptions, "appName">) {
+  return scope(undefined, {
+    ...options,
+    appName,
+    stage: options.stage,
+  });
+}
+_alchemy.destroy = destroy;
+_alchemy.run = run;
+_alchemy.scope = scope;
+_alchemy.secret = secret;
+
+// alchemy type is to semantically highlight `alchemy` as a type (keyword)
+export type alchemy = Alchemy;
+
+export const alchemy: Alchemy = _alchemy as any;
+
+// Alchemy is for module augmentation
+export interface Alchemy {
+  scope: typeof scope;
+  run: typeof run;
+  destroy: typeof destroy;
+  secret: typeof secret;
+  (...parameters: Parameters<typeof scope>): ReturnType<typeof scope>;
+}
+
+export interface AlchemyOptions {
+  /**
+   * The name of the application.
+   */
+  appName?: string;
+  /**
+   * Determines whether the resources will be created/updated or deleted.
+   *
+   * @default "up"
+   */
+  phase?: "up" | "destroy";
+  /**
+   * Name to scope the resource state under (e.g. `.alchemy/{stage}/..`).
+   *
+   * @default - your POSIX username
+   */
+  stage?: string;
+  /**
+   * If true, will not prune resources that were dropped from the root stack.
+   *
+   * @default true
+   */
+  destroyOrphans?: boolean;
+  /**
+   * A custom state store to use instead of the default file system store.
+   */
+  stateStore?: StateStoreType;
+  /**
+   * A custom scope to use as a parent.
+   */
+  parent?: Scope;
+  /**
+   * If true, will not print any Create/Update/Delete messages.
+   *
+   * @default false
+   */
+  quiet?: boolean;
+
+  /**
+   * A passphrase to use to encrypt/decrypt secrets.
+   */
+  password?: string;
+}
+
+/**
+ * Enter a new scope synchronously.
+ * @param options
+ * @returns
+ */
+function scope(
+  id: string | undefined,
+  options?: AlchemyOptions,
+  // TODO: maybe we want to allow using _ = await alchemy.scope(import.meta)
+  // | [meta: ImportMeta]
+): Scope {
+  const scope = new Scope({
+    ...options,
+    appName: options?.appName,
+    stage: options?.stage ?? DEFAULT_STAGE,
+    scopeName: id,
+    parent: options?.parent ?? Scope.get(),
+  });
+  scope.enter();
+  return scope;
+}
+
+async function run<T>(
+  ...args:
+    | [id: string, fn: (this: Scope, scope: Scope) => Promise<T>]
+    | [
+        id: string,
+        options: AlchemyOptions,
+        fn: (this: Scope, scope: Scope) => Promise<T>,
+      ]
+): Promise<T> {
+  const [id, options, fn] =
+    typeof args[1] === "function"
+      ? [args[0], undefined, args[1]]
+      : (args as [
+          string,
+          AlchemyOptions | undefined,
+          (this: Scope, scope: Scope) => Promise<T>,
+        ]);
+  await using scope = alchemy.scope(id, options);
+  return await fn.bind(scope)(scope);
+}

package/src/apply.ts

@@ -1,132 +1,130 @@
-import { defaultStage, defaultStateStore } from "./global";
-import { type Output, OutputChain, type Resolved } from "./output";
+import { alchemy } from "./alchemy";
+import { context } from "./context";
 import {
-  Input,
-  Provider,
+  PROVIDERS,
+  type PendingResource,
+  type Provider,
   type Resource,
-  ResourceID,
-  isResource,
+  type ResourceProps,
 } from "./resource";
-import { type Scope as IScope, getScope } from "./scope";
-import type { StateStore } from "./state";
+import type { State } from "./state";
+import { serialize } from "./util/serde";
 
 export interface ApplyOptions {
-  stage: string;
-  scope: IScope;
-  stateStore: StateStore;
   quiet?: boolean;
+  alwaysUpdate?: boolean;
 }
 
-/**
- * Apply a sub-graph to produce a resource.
- * @param output A sub-graph that produces a resource.
- * @returns The resource properties.
- */
-export async function apply<T>(
-  output: T,
-  options?: Partial<ApplyOptions>,
-): Promise<Resolved<T>> {
-  const stage = options?.stage ?? defaultStage;
-  const scope = options?.scope ?? getScope();
-  const statePath = scope.getScopePath(stage);
-  const stateStore = options?.stateStore ?? new defaultStateStore(statePath);
+export async function apply<Out extends Resource>(
+  resource: PendingResource<Out>,
+  props: ResourceProps,
+  options?: ApplyOptions,
+): Promise<Awaited<Out>> {
+  const scope = resource.Scope;
+  const quiet = props.quiet ?? scope.quiet;
+  await scope.init();
+  let state: State | undefined = (await scope.state.get(resource.ID))!;
+  const provider: Provider = PROVIDERS.get(resource.Kind);
+  if (provider === undefined) {
+    throw new Error(`Provider "${resource.Kind}" not found`);
+  }
+  if (state === undefined) {
+    state = {
+      kind: resource.Kind,
+      id: resource.ID,
+      fqn: resource.FQN,
+      seq: resource.Seq,
+      status: "creating",
+      data: {},
+      output: {
+        ID: resource.ID,
+        FQN: resource.FQN,
+        Kind: resource.Kind,
+        Scope: scope,
+        Seq: resource.Seq,
+      },
+      // deps: [...deps],
+      props,
+    };
+    await scope.state.set(resource.ID, state);
+  }
 
-  return (
-    await evaluate(output, { stage, scope, stateStore, quiet: options?.quiet })
-  ).value as Resolved<T>;
-}
+  const alwaysUpdate =
+    options?.alwaysUpdate ?? provider.options?.alwaysUpdate ?? false;
 
-class Evaluated<T> {
-  constructor(
-    public readonly value: T,
-    public readonly deps: string[] = [],
-  ) {}
-}
+  // Skip update if inputs haven't changed and resource is in a stable state
+  if (state.status === "created" || state.status === "updated") {
+    if (
+      JSON.stringify(state.props) === JSON.stringify(serialize(scope, props)) &&
+      alwaysUpdate !== true
+    ) {
+      if (!quiet) {
+        console.log(`Skip:    "${resource.FQN}" (no changes)`);
+      }
+      // if (resourceState.output !== undefined) {
+      //   resource[Provide](resourceState.output);
+      // }
+      return state.output as Awaited<Out>;
+    }
+  }
 
-const cache = new WeakMap<Resource, Promise<Evaluated<any>>>();
+  const phase = state.status === "creating" ? "create" : "update";
+  state.status = phase === "create" ? "creating" : "updating";
+  state.oldProps = state.props;
+  state.props = props;
 
-export async function evaluate<T>(
-  output: T | Output<T>,
-  options: ApplyOptions,
-): Promise<Evaluated<T>> {
-  const stage = options.stage;
-  const stateStore = options.stateStore;
-  if (isResource(output)) {
-    const resource = output;
-    const resourceID = resource[ResourceID];
-    const evaluated = await Promise.all(
-      resource[Input].map((r) => evaluate<any>(r, options)),
+  if (!quiet) {
+    console.log(
+      `${phase === "create" ? "Create" : "Update"}:  "${resource.FQN}"`,
     );
+  }
 
-    if (cache.has(resource)) {
-      return await cache.get(resource)!;
-    }
-    let resolve: (value: Evaluated<any>) => void;
-    let reject: (reason?: any) => void;
-    const promise = new Promise<Evaluated<any>>((res, rej) => {
-      resolve = res;
-      reject = rej;
-    });
-    // set this eagerly to avoid double-apply (caused by recursive applies to inputs)
-    cache.set(resource, promise);
+  await scope.state.set(resource.ID, state);
 
-    const deps = new Set(evaluated.flatMap((input) => input.deps));
-    const inputs = evaluated.map((input) => input.value);
-    try {
-      const result: T = await resource[Provider].update(
-        stage,
-        resource,
-        deps,
-        inputs as [],
-        stateStore,
-        options,
-      );
-      resolve!(new Evaluated(result, [resourceID, ...deps]));
-    } catch (error) {
-      console.error(error);
-      reject!(error);
-    }
-    return promise;
-  } else if (output instanceof OutputChain) {
-    const inside = output as unknown as {
-      parent: Output<any>;
-      fn: (value: any) => T;
-    };
-    const parent = await evaluate(inside.parent, options);
-    const ret = inside.fn(parent.value);
-    // the ret may be an Output (e.g. in the flatMap case), so we need to evaluate it and include its deps
-    const evaluated = await evaluate(ret, options);
-    return new Evaluated<T>(evaluated.value, [
-      ...parent.deps,
-      ...evaluated.deps,
-    ]);
-  } else if (Array.isArray(output)) {
-    const evaluatedItems = await Promise.all(
-      output.map((item) => evaluate(item, options)),
-    );
-    return new Evaluated(
-      evaluatedItems.map((e) => e.value) as unknown as T,
-      evaluatedItems.flatMap((e) => e.deps),
-    );
-  } else if (output instanceof Date) {
-    return new Evaluated(output as T);
-  } else if (output && typeof output === "object") {
-    const entries = Object.entries(output);
-    const evaluatedEntries = await Promise.all(
-      entries.map(
-        async ([key, value]) => [key, await evaluate(value, options)] as const,
-      ),
-    );
+  let isReplaced = false;
 
-    const result = Object.fromEntries(
-      evaluatedEntries.map(([key, evaluated]) => [key, evaluated.value]),
-    ) as unknown as T;
+  const ctx = context({
+    scope,
+    phase,
+    kind: resource.Kind,
+    id: resource.ID,
+    fqn: resource.FQN,
+    seq: resource.Seq,
+    state,
+    replace: () => {
+      if (isReplaced) {
+        console.warn(
+          `Resource ${resource.Kind} ${resource.FQN} is already marked as REPLACE`,
+        );
+        return;
+      }
+      isReplaced = true;
+    },
+  });
 
-    const deps = evaluatedEntries.flatMap(([_, evaluated]) => evaluated.deps);
+  const output = await alchemy.run(resource.ID, async () =>
+    provider.handler.bind(ctx)(resource.ID, props),
+  );
 
-    return new Evaluated(result, deps);
+  if (!quiet) {
+    console.log(
+      `${phase === "create" ? "Created" : "Updated"}: "${resource.FQN}"`,
+    );
   }
 
-  // Base case: primitive value
-  return new Evaluated<T>(output as T);
+  await scope.state.set(resource.ID, {
+    kind: resource.Kind,
+    id: resource.ID,
+    fqn: resource.FQN,
+    seq: resource.Seq,
+    data: state.data,
+    status: phase === "create" ? "created" : "updated",
+    output,
+    props,
+    // deps: [...deps],
+  });
+  // if (output !== undefined) {
+  //   resource[Provide](output as Out);
+  // }
+  return output as any;
 }

package/src/aws/bucket.ts

@@ -10,16 +10,16 @@ import {
   PutBucketTaggingCommand,
   S3Client,
 } from "@aws-sdk/client-s3";
-import { ignore } from "../error";
+import type { Context } from "../context";
 import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
 
 export interface BucketProps {
   bucketName: string;
   tags?: Record<string, string>;
 }
 
-export interface BucketOutput extends BucketProps {
-  id: string; // Same as bucketName for AWS
+export interface Bucket extends Resource<"s3::Bucket">, BucketProps {
   arn: string;
   bucketDomainName: string; // Format: bucket-name.s3.amazonaws.com
   bucketRegionalDomainName?: string; // Format: bucket-name.s3.region.amazonaws.com
@@ -31,12 +31,12 @@ export interface BucketOutput extends BucketProps {
   acl?: string;
 }
 
-export class Bucket extends Resource(
+export const Bucket = Resource(
   "s3::Bucket",
-  async (ctx, props: BucketProps) => {
+  async function (this: Context<Bucket>, id: string, props: BucketProps) {
     const client = new S3Client({});
 
-    if (ctx.event === "delete") {
+    if (this.phase === "delete") {
       await ignore(NoSuchBucket.name, () =>
         client.send(
           new DeleteBucketCommand({
@@ -44,7 +44,7 @@ export class Bucket extends Resource(
           }),
         ),
       );
-      return props;
+      return this.destroy();
     } else {
       try {
         // Check if bucket exists
@@ -55,7 +55,7 @@ export class Bucket extends Resource(
         );
 
         // Update tags if they changed and bucket exists
-        if (ctx.event === "update" && props.tags) {
+        if (this.phase === "update" && props.tags) {
           await client.send(
             new PutBucketTaggingCommand({
               Bucket: props.bucketName,
@@ -121,9 +121,8 @@ export class Bucket extends Resource(
         }
       }
 
-      const output: BucketOutput = {
+      return this({
         bucketName: props.bucketName,
-        id: props.bucketName,
         arn: `arn:aws:s3:::${props.bucketName}`,
         bucketDomainName: `${props.bucketName}.s3.amazonaws.com`,
         bucketRegionalDomainName: `${props.bucketName}.s3.${region}.amazonaws.com`,
@@ -132,12 +131,10 @@ export class Bucket extends Resource(
         versioningEnabled: versioningResponse.Status === "Enabled",
         acl: aclResponse.Grants?.[0]?.Permission?.toLowerCase(),
         ...(tags && { tags }),
-      };
-
-      return output;
+      });
     }
   },
-) {}
+);
 
 // Helper function to get S3 hosted zone IDs by region
 function getHostedZoneId(region: string): string {

package/src/aws/function.ts

@@ -12,8 +12,9 @@ import {
 } from "@aws-sdk/client-lambda";
 import fs from "node:fs";
 import path from "node:path";
-import { ignore } from "../error";
-import { type Context, Resource } from "../resource";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
 
 async function resolveRegion(client: LambdaClient): Promise<string> {
   const region = client.config.region;
@@ -47,8 +48,7 @@ export interface FunctionProps {
   };
 }
 
-export interface FunctionOutput extends FunctionProps {
-  id: string; // Same as functionName
+export interface Function extends Resource<"lambda::Function">, FunctionProps {
   arn: string;
   lastModified: string;
   version: string;
@@ -71,15 +71,15 @@ export interface FunctionOutput extends FunctionProps {
   signingJobArn?: string;
 }
 
-export class Function extends Resource(
+export const Function = Resource(
   "lambda::Function",
-  async (ctx: Context<FunctionOutput>, props: FunctionProps) => {
+  async function (this: Context<Function>, id: string, props: FunctionProps) {
     const client = new LambdaClient({});
     const region = await resolveRegion(client);
 
     const code = await zipCode(props.zipPath);
 
-    if (ctx.event === "delete") {
+    if (this.phase === "delete") {
       await ignore(ResourceNotFoundException.name, () =>
         client.send(
           new DeleteFunctionCommand({
@@ -88,34 +88,17 @@ export class Function extends Resource(
         ),
       );
 
-      // Return a minimal FunctionOutput for deleted state
-      return {
-        ...props,
-        id: props.functionName,
-        arn: `arn:aws:lambda:${region}:${process.env.AWS_ACCOUNT_ID}:function:${props.functionName}`,
-        lastModified: new Date().toISOString(),
-        version: "$LATEST",
-        qualifiedArn: `arn:aws:lambda:${region}:${process.env.AWS_ACCOUNT_ID}:function:${props.functionName}:$LATEST`,
-        invokeArn: `arn:aws:apigateway:${region}:lambda:path/2015-03-31/functions/arn:aws:lambda:${region}:${process.env.AWS_ACCOUNT_ID}:function:${props.functionName}/invocations`,
-        sourceCodeHash: "",
-        sourceCodeSize: 0,
-        architectures: props.architecture
-          ? [props.architecture]
-          : [Architecture.x86_64],
-        revisionId: "",
-        state: "Inactive",
-        packageType: "Zip",
-      };
+      return this.destroy();
     } else {
       try {
         // Check if function exists
-        const func = await client.send(
+        await client.send(
           new GetFunctionCommand({
             FunctionName: props.functionName,
           }),
         );
 
-        if (ctx.event === "update") {
+        if (this.phase === "update") {
           // Wait for function to stabilize
           await waitForFunctionStabilization(client, props.functionName);
 
@@ -228,9 +211,8 @@ export class Function extends Resource(
         ),
       ]);
 
-      const output: FunctionOutput = {
+      return this({
         ...props,
-        id: props.functionName,
         arn: config.FunctionArn!,
         lastModified: config.LastModified!,
         version: config.Version!,
@@ -251,12 +233,10 @@ export class Function extends Resource(
         packageType: config.PackageType!,
         signingProfileVersionArn: config.SigningProfileVersionArn,
         signingJobArn: config.SigningJobArn,
-      };
-
-      return output;
+      });
     }
   },
-) {}
+);
 
 // Helper to wait for function to stabilize
 async function waitForFunctionStabilization(

package/src/aws/index.ts

@@ -2,6 +2,7 @@ export * from "./account-id";
 export * from "./bucket";
 export * from "./function";
 export * from "./policy";
+export * from "./policy-attachment";
 export * from "./queue";
 export * from "./role";
 export * from "./ses";

package/src/aws/oidc/github-oidc-provider.ts

@@ -1,5 +1,3 @@
-import type { Input } from "../../input";
-import { isOutput } from "../../output";
 import { OIDCProvider, type OIDCProviderProps } from "./oidc-provider";
 
 /**
@@ -13,22 +11,19 @@ export interface GitHubOIDCProviderProps
   extends Omit<OIDCProviderProps, "thumbprint"> {
   owner: string;
   repository: string;
-  thumbprint?: string;
 }
+export type GitHubOIDCProvider = ReturnType<typeof GitHubOIDCProvider>;
 
-export class GitHubOIDCProvider extends OIDCProvider {
-  constructor(id: string, props: Input<GitHubOIDCProviderProps>) {
-    super(
-      id,
-      isOutput<GitHubOIDCProviderProps>(props)
-        ? props.apply((props) => ({
-            ...props,
-            thumbprint: props.thumbprint ?? DEFAULT_GITHUB_THUMBPRINT,
-          }))
-        : ({
-            ...props,
-            thumbprint: props.thumbprint ?? DEFAULT_GITHUB_THUMBPRINT,
-          } as Input<OIDCProviderProps>),
-    );
-  }
-}
+export const GitHubOIDCProvider = async (
+  id: string,
+  props: GitHubOIDCProviderProps,
+) => {
+  return OIDCProvider(id, {
+    owner: props.owner,
+    repository: props.repository,
+    roleArn: props.roleArn,
+    branches: props.branches,
+    environments: props.environments,
+    thumbprint: DEFAULT_GITHUB_THUMBPRINT,
+  });
+};

package/src/aws/oidc/oidc-provider.ts

@@ -7,7 +7,8 @@ import {
   type Tag,
   UpdateAssumeRolePolicyCommand,
 } from "@aws-sdk/client-iam";
-import { type Context, Resource } from "../../resource";
+import type { Context } from "../../context";
+import { Resource } from "../../resource";
 import { getAccountId } from "../account-id";
 
 /**
@@ -60,7 +61,9 @@ export interface OIDCProviderProps {
 /**
  * Output returned after OIDC provider configuration
  */
-export interface OIDCProviderOutput extends OIDCProviderProps {
+export interface OIDCProvider
+  extends Resource<"aws::OIDCProvider">,
+    OIDCProviderProps {
   /**
    * The ARN of the OIDC provider
    */
@@ -81,16 +84,20 @@ const TRUST_POLICY_SID = "GitHubOIDCTrust";
 /**
  * Resource for configuring AWS OIDC provider for GitHub Actions
  */
-export class OIDCProvider extends Resource(
+export const OIDCProvider = Resource(
   "aws::OIDCProvider",
-  async (ctx: Context<OIDCProviderOutput>, props: OIDCProviderProps) => {
+  async function (
+    this: Context<OIDCProvider>,
+    id: string,
+    props: OIDCProviderProps,
+  ) {
     // Initialize AWS SDK client
     const client = new IAMClient({
       region: props.region,
     });
 
-    if (ctx.event === "delete") {
-      if (ctx.output?.providerArn) {
+    if (this.phase === "delete") {
+      if (this.output?.providerArn) {
         try {
           // First, remove our trust policy statement from the role
           const getRole = await client.send(
@@ -120,7 +127,7 @@ export class OIDCProvider extends Resource(
           // Then delete the OIDC provider if we're the last user
           const provider = await client.send(
             new GetOpenIDConnectProviderCommand({
-              OpenIDConnectProviderArn: ctx.output.providerArn,
+              OpenIDConnectProviderArn: this.output.providerArn,
             }),
           );
 
@@ -128,7 +135,7 @@ export class OIDCProvider extends Resource(
           if (provider && (!provider.Tags || provider.Tags.length === 0)) {
             await client.send(
               new DeleteOpenIDConnectProviderCommand({
-                OpenIDConnectProviderArn: ctx.output.providerArn,
+                OpenIDConnectProviderArn: this.output.providerArn,
               }),
             );
           }
@@ -137,7 +144,7 @@ export class OIDCProvider extends Resource(
           console.error("Error during cleanup:", error);
         }
       }
-      return;
+      return this.destroy();
     }
 
     try {
@@ -240,14 +247,14 @@ export class OIDCProvider extends Resource(
         }),
       );
 
-      return {
+      return this({
         ...props,
         providerArn,
         createdAt: Date.now(),
-      };
+      });
     } catch (error) {
       console.error("Error configuring OIDC provider:", error);
       throw error;
     }
   },
-) {}
+);