alchemy 0.16.0 → 0.16.2

package/src/alchemy.ts

@@ -3,7 +3,14 @@ import path from "node:path";
 
 import { destroy, DestroyedSignal } from "./destroy.js";
 import { env } from "./env.js";
-import type { PendingResource } from "./resource.js";
+import {
+  ResourceFQN,
+  ResourceID,
+  ResourceKind,
+  ResourceScope,
+  ResourceSeq,
+  type PendingResource,
+} from "./resource.js";
 import { Scope } from "./scope.js";
 import { secret } from "./secret.js";
 import type { StateStoreType } from "./state.js";
@@ -325,11 +332,11 @@ async function run<T>(
       // TODO(sam): this is an awful hack to differentiate between naked scopes and resources
       const seq = _scope.parent.seq();
       const output = {
-        ID: id,
-        FQN: "",
-        Kind: Scope.KIND,
-        Scope: _scope,
-        Seq: seq,
+        [ResourceID]: id,
+        [ResourceFQN]: "",
+        [ResourceKind]: Scope.KIND,
+        [ResourceScope]: _scope,
+        [ResourceSeq]: seq,
       } as const;
       const resource = {
         kind: Scope.KIND,

package/src/apply.ts

@@ -2,6 +2,11 @@ import { alchemy } from "./alchemy.js";
 import { context } from "./context.js";
 import {
   PROVIDERS,
+  ResourceFQN,
+  ResourceID,
+  ResourceKind,
+  ResourceScope,
+  ResourceSeq,
   type PendingResource,
   type Provider,
   type Resource,
@@ -20,42 +25,44 @@ export async function apply<Out extends Resource>(
   props: ResourceProps | undefined,
   options?: ApplyOptions,
 ): Promise<Awaited<Out>> {
-  const scope = resource.Scope;
+  const scope = resource[ResourceScope];
   try {
     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);
+    let state: State | undefined = (await scope.state.get(
+      resource[ResourceID],
+    ))!;
+    const provider: Provider = PROVIDERS.get(resource[ResourceKind]);
     if (provider === undefined) {
-      throw new Error(`Provider "${resource.Kind}" not found`);
+      throw new Error(`Provider "${resource[ResourceKind]}" not found`);
     }
     if (scope.phase === "read") {
       if (state === undefined) {
         throw new Error(
-          `Resource "${resource.FQN}" not found and running in 'read' phase.`,
+          `Resource "${resource[ResourceFQN]}" not found and running in 'read' phase.`,
         );
       }
       return state.output as Awaited<Out>;
     }
     if (state === undefined) {
       state = {
-        kind: resource.Kind,
-        id: resource.ID,
-        fqn: resource.FQN,
-        seq: resource.Seq,
+        kind: resource[ResourceKind],
+        id: resource[ResourceID],
+        fqn: resource[ResourceFQN],
+        seq: resource[ResourceSeq],
         status: "creating",
         data: {},
         output: {
-          ID: resource.ID,
-          FQN: resource.FQN,
-          Kind: resource.Kind,
-          Scope: scope,
-          Seq: resource.Seq,
+          [ResourceID]: resource[ResourceID],
+          [ResourceFQN]: resource[ResourceFQN],
+          [ResourceKind]: resource[ResourceKind],
+          [ResourceScope]: scope,
+          [ResourceSeq]: resource[ResourceSeq],
         },
         // deps: [...deps],
         props,
       };
-      await scope.state.set(resource.ID, state);
+      await scope.state.set(resource[ResourceID], state);
     }
 
     const alwaysUpdate =
@@ -87,27 +94,27 @@ export async function apply<Out extends Resource>(
 
     if (!quiet) {
       console.log(
-        `${phase === "create" ? "Create" : "Update"}:  "${resource.FQN}"`,
+        `${phase === "create" ? "Create" : "Update"}:  "${resource[ResourceFQN]}"`,
       );
     }
 
-    await scope.state.set(resource.ID, state);
+    await scope.state.set(resource[ResourceID], state);
 
     let isReplaced = false;
 
     const ctx = context({
       scope,
       phase,
-      kind: resource.Kind,
-      id: resource.ID,
-      fqn: resource.FQN,
-      seq: resource.Seq,
+      kind: resource[ResourceKind],
+      id: resource[ResourceID],
+      fqn: resource[ResourceFQN],
+      seq: resource[ResourceSeq],
       props: state.oldProps,
       state,
       replace: () => {
         if (isReplaced) {
           console.warn(
-            `Resource ${resource.Kind} ${resource.FQN} is already marked as REPLACE`,
+            `Resource ${resource[ResourceKind]} ${resource[ResourceFQN]} is already marked as REPLACE`,
           );
           return;
         }
@@ -116,23 +123,23 @@ export async function apply<Out extends Resource>(
     });
 
     const output = await alchemy.run(
-      resource.ID,
+      resource[ResourceID],
       {
         isResource: true,
       },
-      async () => provider.handler.bind(ctx)(resource.ID, props),
+      async () => provider.handler.bind(ctx)(resource[ResourceID], props),
     );
     if (!quiet) {
       console.log(
-        `${phase === "create" ? "Created" : "Updated"}: "${resource.FQN}"`,
+        `${phase === "create" ? "Created" : "Updated"}: "${resource[ResourceFQN]}"`,
       );
     }
 
-    await scope.state.set(resource.ID, {
-      kind: resource.Kind,
-      id: resource.ID,
-      fqn: resource.FQN,
-      seq: resource.Seq,
+    await scope.state.set(resource[ResourceID], {
+      kind: resource[ResourceKind],
+      id: resource[ResourceID],
+      fqn: resource[ResourceFQN],
+      seq: resource[ResourceSeq],
       data: state.data,
       status: phase === "create" ? "created" : "updated",
       output,

package/src/cloudflare/queue.ts

@@ -1,9 +1,9 @@
 import type { Context } from "../context.js";
-import { Resource } from "../resource.js";
+import { Resource, ResourceKind } from "../resource.js";
 import { CloudflareApiError, handleApiError } from "./api-error.js";
 import {
-  type CloudflareApi,
   createCloudflareApi,
+  type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.js";
 
@@ -59,7 +59,10 @@ export interface QueueProps extends CloudflareApiOptions {
 }
 
 export function isQueue(eventSource: any): eventSource is Queue {
-  return "Kind" in eventSource && eventSource.Kind === "cloudflare::Queue";
+  return (
+    ResourceKind in eventSource &&
+    eventSource[ResourceKind] === "cloudflare::Queue"
+  );
 }
 
 /**

package/src/cloudflare/r2-rest-state-store.ts

@@ -1,6 +1,7 @@
+import { ResourceScope } from "../resource.js";
 import type { Scope } from "../scope.js";
-import { deserialize, serialize } from "../serde.js";
-import type { State, StateStore } from "../state.js";
+import { serialize } from "../serde.js";
+import { deserializeState, type State, type StateStore } from "../state.js";
 import { withExponentialBackoff } from "../util/retry.js";
 import { CloudflareApiError, handleApiError } from "./api-error.js";
 import {
@@ -211,15 +212,14 @@ export class R2RestStateStore implements StateStore {
       }
 
       // Parse and deserialize the state data
-      const rawData = await response.json();
-      const state = (await deserialize(this.scope, rawData)) as State;
+      const state = await deserializeState(this.scope, await response.text());
 
       // Create a new state object with proper output
       return {
         ...state,
         output: {
           ...(state.output || {}),
-          Scope: this.scope,
+          [ResourceScope]: this.scope,
         },
       };
     } catch (error: any) {

package/src/cloudflare/worker.ts

@@ -814,7 +814,7 @@ async function prepareWorkerMetadata<B extends Bindings>(
       meta.bindings.push({
         type: "service",
         name: bindingName,
-        service: binding.id,
+        service: binding.name,
       });
     } else if (binding.type === "durable_object_namespace") {
       meta.bindings.push({

package/src/context.ts

@@ -1,10 +1,12 @@
 import { DestroyedSignal } from "./destroy.js";
-import type {
-  Resource,
+import {
   ResourceFQN,
   ResourceID,
   ResourceKind,
-  ResourceProps,
+  ResourceScope,
+  ResourceSeq,
+  type Resource,
+  type ResourceProps,
 } from "./resource.js";
 import type { Scope } from "./scope.js";
 import type { State } from "./state.js";
@@ -96,23 +98,29 @@ export function context<
   state: State<Kind, Props, Out>;
   replace: () => void;
 }): Context<Out> {
-  function create(props: Omit<Out, "Kind" | "ID" | "Scope">): Out;
-  function create(id: string, props: Omit<Out, "Kind" | "ID" | "Scope">): Out;
+  type InternalSymbols =
+    | typeof ResourceID
+    | typeof ResourceKind
+    | typeof ResourceFQN
+    | typeof ResourceSeq
+    | typeof ResourceScope;
+  function create(props: Omit<Out, InternalSymbols>): Out;
+  function create(id: string, props: Omit<Out, InternalSymbols>): Out;
   function create(
     ...args:
-      | [props: Omit<Out, "Kind" | "ID" | "Scope">]
-      | [id: string, props: Omit<Out, "Kind" | "ID" | "Scope">]
+      | [props: Omit<Out, InternalSymbols>]
+      | [id: string, props: Omit<Out, InternalSymbols>]
   ): Out {
     const [ID, props] =
       typeof args[0] === "string" ? (args as [string, any]) : [id, args[0]];
 
     return {
       ...props,
-      Kind: kind,
-      ID,
-      FQN: fqn,
-      Scope: scope,
-      Seq: seq,
+      [ResourceKind]: kind,
+      [ResourceID]: ID,
+      [ResourceFQN]: fqn,
+      [ResourceScope]: scope,
+      [ResourceSeq]: seq,
     } as Out;
   }
   return Object.assign(create, {
@@ -138,5 +146,5 @@ export function context<
       throw new DestroyedSignal();
     },
     create,
-  }) as Context<Out>;
+  }) as unknown as Context<Out>;
 }

package/src/destroy.ts

@@ -1,6 +1,15 @@
 import { alchemy } from "./alchemy.js";
 import { context } from "./context.js";
-import { PROVIDERS, type Provider, type Resource } from "./resource.js";
+import {
+  PROVIDERS,
+  ResourceFQN,
+  ResourceID,
+  ResourceKind,
+  ResourceScope,
+  ResourceSeq,
+  type Provider,
+  type Resource,
+} from "./resource.js";
 import { Scope } from "./scope.js";
 
 export class DestroyedSignal extends Error {}
@@ -52,34 +61,36 @@ export async function destroy<Type extends string>(
     return;
   }
 
-  if (instance.Kind === Scope.KIND) {
+  if (instance[ResourceKind] === Scope.KIND) {
     const scope = new Scope({
-      parent: instance.Scope,
-      scopeName: instance.ID,
+      parent: instance[ResourceScope],
+      scopeName: instance[ResourceID],
     });
     console.log("Destroying scope", scope.chain.join("/"));
     return await destroy(scope, options);
   }
 
-  const Provider: Provider<Type> | undefined = PROVIDERS.get(instance.Kind);
+  const Provider: Provider<Type> | undefined = PROVIDERS.get(
+    instance[ResourceKind],
+  );
   if (!Provider) {
     throw new Error(
-      `Cannot destroy resource "${instance.FQN}" type ${instance.Kind} - no provider found. You may need to import the provider in your alchemy.config.ts.`,
+      `Cannot destroy resource "${instance[ResourceFQN]}" type ${instance[ResourceKind]} - no provider found. You may need to import the provider in your alchemy.config.ts.`,
     );
   }
 
-  const scope = instance.Scope;
+  const scope = instance[ResourceScope];
   if (!scope) {
-    console.warn(`Resource "${instance.FQN}" has no scope`);
+    console.warn(`Resource "${instance[ResourceFQN]}" has no scope`);
   }
   const quiet = options?.quiet ?? scope.quiet;
 
   try {
     if (!quiet) {
-      console.log(`Delete:  "${instance.FQN}"`);
+      console.log(`Delete:  "${instance[ResourceFQN]}"`);
     }
 
-    const state = await scope.state.get(instance.ID);
+    const state = await scope.state.get(instance[ResourceID]);
 
     if (state === undefined) {
       return;
@@ -88,10 +99,10 @@ export async function destroy<Type extends string>(
     const ctx = context({
       scope,
       phase: "delete",
-      kind: instance.Kind,
-      id: instance.ID,
-      fqn: instance.FQN,
-      seq: instance.Seq,
+      kind: instance[ResourceKind],
+      id: instance[ResourceID],
+      fqn: instance[ResourceFQN],
+      seq: instance[ResourceSeq],
       props: state.props,
       state,
       replace: () => {
@@ -103,15 +114,18 @@ export async function destroy<Type extends string>(
     try {
       // BUG: this does not restore persisted scope
       await alchemy.run(
-        instance.ID,
+        instance[ResourceID],
         {
           // TODO(sam): this is an awful hack to differentiate between naked scopes and resources
-          isResource: instance.Kind !== "alchemy::Scope",
+          isResource: instance[ResourceKind] !== "alchemy::Scope",
           parent: scope,
         },
         async (scope) => {
           nestedScope = scope;
-          return await Provider.handler.bind(ctx)(instance.ID, state.props);
+          return await Provider.handler.bind(ctx)(
+            instance[ResourceID],
+            state.props,
+          );
         },
       );
     } catch (err) {
@@ -126,10 +140,10 @@ export async function destroy<Type extends string>(
       await destroy(nestedScope, options);
     }
 
-    await scope.delete(instance.ID);
+    await scope.delete(instance[ResourceID]);
 
     if (!quiet) {
-      console.log(`Deleted: "${instance.FQN}"`);
+      console.log(`Deleted: "${instance[ResourceFQN]}"`);
     }
   } catch (error) {
     console.error(error);
@@ -140,7 +154,7 @@ export async function destroy<Type extends string>(
 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);
+      const sorted = resources.sort((a, b) => b[ResourceSeq] - a[ResourceSeq]);
       for (const resource of sorted) {
         await destroy(resource, options);
       }

package/src/fs/file-system-state-store.ts

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
+import { ResourceScope } from "../resource.js";
 import type { Scope } from "../scope.js";
-import { deserialize, serialize } from "../serde.js";
-import type { State, StateStore } from "../state.js";
+import { serialize } from "../serde.js";
+import { deserializeState, type State, type StateStore } from "../state.js";
 import { ignore } from "../util/ignore.js";
 
 const stateRootDir = path.join(process.cwd(), ".alchemy");
@@ -50,14 +51,11 @@ export class FileSystemStateStore implements StateStore {
   async get(key: string): Promise<State | undefined> {
     try {
       const content = await fs.promises.readFile(this.getPath(key), "utf8");
-      const state = (await deserialize(
-        this.scope,
-        JSON.parse(content),
-      )) as State;
+      const state = await deserializeState(this.scope, content);
       if (state.output === undefined) {
         state.output = {} as any;
       }
-      state.output.Scope = this.scope;
+      state.output[ResourceScope] = this.scope;
       return state;
     } catch (error: any) {
       if (error.code === "ENOENT") {

package/src/os/exec.ts

@@ -1,4 +1,6 @@
 import { spawn, type SpawnOptions } from "node:child_process";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
 import type { Context } from "../context.js";
 import { Resource } from "../resource.js";
 
@@ -14,9 +16,28 @@ export interface ExecProps {
   /**
    * Whether to memoize the command (only re-run if the command changes)
    *
+   * When set to `true`, the command will only be re-executed if the command string changes.
+   *
+   * When set to an object with `patterns`, the command will be re-executed if either:
+   * 1. The command string changes, or
+   * 2. The contents of any files matching the glob patterns change
+   *
+   * ⚠️ **Important Note**: When using memoization with build commands, the build outputs
+   * will not be produced if the command is memoized. This is because the command is not
+   * actually executed when memoized. Consider disabling memoization in CI environments:
+   *
+   * @example
+   * // Disable memoization in CI to ensure build outputs are always produced
+   * await Exec("build", {
+   *   command: "vite build",
+   *   memoize: process.env.CI ? false : {
+   *     patterns: ["./src/**"]
+   *   }
+   * });
+   *
    * @default false
    */
-  memoize?: boolean;
+  memoize?: boolean | { patterns: string[] };
 
   /**
    * Working directory for the command
@@ -68,6 +89,11 @@ export interface Exec extends Resource<"os::Exec">, ExecProps {
    * Whether the command has completed execution
    */
   completed: boolean;
+
+  /**
+   * Hash of the command inputs
+   */
+  hash?: string;
 }
 
 /**
@@ -108,6 +134,26 @@ export interface Exec extends Resource<"os::Exec">, ExecProps {
  *   command: "git status",
  *   memoize: true
  * });
+ *
+ * @example
+ * // Memoize a build command with file patterns, but disable in CI
+ * // This ensures build outputs are always produced in CI
+ * const build = await Exec("build", {
+ *   command: "vite build",
+ *   memoize: process.env.CI ? false : {
+ *     patterns: ["./src/**"]
+ *   }
+ * });
+ *
+ * @example
+ * // Memoize a database migration command based on schema files
+ * // This is safe to memoize since it's idempotent
+ * const migrate = await Exec("db-migrate", {
+ *   command: "drizzle-kit push:pg",
+ *   memoize: {
+ *     patterns: ["./src/db/schema/**"]
+ *   }
+ * });
  */
 export const Exec = Resource(
   "os::Exec",
@@ -123,14 +169,23 @@ export const Exec = Resource(
       // Nothing to actually delete for an exec command
       return this.destroy();
     }
+
+    const hash =
+      typeof props.memoize === "object"
+        ? await hashInputs(props.cwd ?? process.cwd(), props.memoize.patterns)
+        : undefined;
+
     if (
       this.phase === "update" &&
       props.memoize &&
-      this.output?.command === props.command
+      this.output?.command === props.command &&
+      (typeof props.memoize === "boolean" ||
+        (hash && this.output?.hash === hash))
     ) {
       // If memoize is enabled and the command hasn't changed, return the existing output
       return this.output;
     }
+
     // Default values
     let stdout = "";
     let stderr = "";
@@ -198,6 +253,7 @@ export const Exec = Resource(
       stderr,
       executedAt: Date.now(),
       completed: true,
+      hash,
     });
   },
 );
@@ -242,3 +298,32 @@ export async function exec(
     });
   });
 }
+
+async function hashInputs(cwd: string, patterns: string[]) {
+  const { glob, readFile } = await import("node:fs/promises");
+
+  const hashes = new Map<string, string>();
+
+  await Promise.all(
+    patterns.flatMap(async (pattern) => {
+      const files = await Array.fromAsync(glob(pattern, { cwd }));
+      return Promise.all(
+        files.map(async (file: string) => {
+          const path = join(cwd, file);
+          const content = await readFile(path);
+          hashes.set(path, createHash("sha256").update(content).digest("hex"));
+        }),
+      );
+    }),
+  );
+
+  const sortedHashes = Array.from(hashes.entries()).sort((a, b) =>
+    a[0].localeCompare(b[0]),
+  );
+
+  const finalHash = createHash("sha256");
+  for (const [, hash] of sortedHashes) {
+    finalHash.update(hash);
+  }
+  return finalHash.digest("hex");
+}

package/src/resource.ts

@@ -5,8 +5,13 @@ import { Scope as _Scope } from "./scope.js";
 export const PROVIDERS = new Map<ResourceKind, Provider<string, any>>();
 
 export type ResourceID = string;
+export const ResourceID = Symbol.for("alchemy::ResourceID");
 export type ResourceFQN = string;
+export const ResourceFQN = Symbol.for("alchemy::ResourceFQN");
 export type ResourceKind = string;
+export const ResourceKind = Symbol.for("alchemy::ResourceKind");
+export const ResourceScope = Symbol.for("alchemy::ResourceScope");
+export const ResourceSeq = Symbol.for("alchemy::ResourceSeq");
 
 export interface ProviderOptions {
   /**
@@ -37,12 +42,11 @@ export type PendingResource<
   Scope extends _Scope = _Scope,
   Seq extends number = number,
 > = Promise<Out> & {
-  Kind: Kind;
-  ID: ID;
-  FQN: FQN;
-  Seq: Seq;
-  Scope: Scope;
-  signal: () => void;
+  [ResourceKind]: Kind;
+  [ResourceID]: ID;
+  [ResourceFQN]: FQN;
+  [ResourceScope]: Scope;
+  [ResourceSeq]: Seq;
 };
 
 export interface Resource<
@@ -54,11 +58,11 @@ export interface Resource<
   Seq extends number = number,
 > {
   // use capital letters to avoid collision with conventional camelCase typescript properties
-  Kind: Kind;
-  ID: ID;
-  FQN: FQN;
-  Scope: Scope;
-  Seq: Seq;
+  [ResourceKind]: Kind;
+  [ResourceID]: ID;
+  [ResourceFQN]: FQN;
+  [ResourceScope]: Scope;
+  [ResourceSeq]: Seq;
 }
 
 // helper for semantic syntax highlighting (color as a type/class instead of function/value)
@@ -113,10 +117,10 @@ export function Resource<
       // TODO(sam): do we want to throw?
       // it's kind of awesome that you can re-create a resource and call apply
       const otherResource = scope.resources.get(resourceID);
-      if (otherResource?.Kind !== type) {
+      if (otherResource?.[ResourceKind] !== type) {
         scope.fail();
         throw new Error(
-          `Resource ${resourceID} already exists in the stack and is of a different type: '${otherResource?.Kind}' !== '${type}'`,
+          `Resource ${resourceID} already exists in the stack and is of a different type: '${otherResource?.[ResourceKind]}' !== '${type}'`,
         );
       }
       // console.warn(
@@ -127,11 +131,11 @@ export function Resource<
     // get a sequence number (unique within the scope) for the resource
     const seq = scope.seq();
     const meta = {
-      Kind: type,
-      ID: resourceID,
-      FQN: scope.fqn(resourceID),
-      Seq: seq,
-      Scope: scope,
+      [ResourceKind]: type,
+      [ResourceID]: resourceID,
+      [ResourceFQN]: scope.fqn(resourceID),
+      [ResourceSeq]: seq,
+      [ResourceScope]: scope,
     } as any as PendingResource<Out>;
     const promise = apply(meta, props, options);
     const resource = Object.assign(promise, meta);

package/src/scope.ts

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { Phase } from "./alchemy.js";
 import { destroy } from "./destroy.js";
 import { FileSystemStateStore } from "./fs/file-system-state-store.js";
-import type { PendingResource, ResourceID } from "./resource.js";
+import { ResourceID, type PendingResource } from "./resource.js";
 import type { StateStore, StateStoreType } from "./state.js";
 
 const scopeStorage = new AsyncLocalStorage<Scope>();
@@ -157,7 +157,7 @@ export class Scope {
     return `Scope(
   chain=${this.chain.join("/")},
   resources=[${Array.from(this.resources.values())
-    .map((r) => r.ID)
+    .map((r) => r[ResourceID])
     .join(",\n  ")}]
 )`;
   }