alchemy 0.16.9 → 0.17.0

package/src/runtime/plugin.ts

@@ -0,0 +1,162 @@
+import type {
+  CallExpression,
+  Declaration,
+  Expression,
+  FunctionDeclaration,
+  TsType,
+  VariableDeclaration,
+} from "@swc/core";
+import type { Plugin } from "esbuild";
+import fs from "node:fs/promises";
+
+/**
+ * Bundles a single Worker function entrypoint by:
+ * 1. Evaluate the script and detect which resources are included in its bundle.
+ * 2. Create a static map of Resource ID -> State
+ * 3. Apply esbuild with {@link bootstrapPlugin} to erase Resource lifecycle operations
+ * 4. The final bundle should then tree-shake away all infrastructure-code, leaving only runtime code.
+ *
+ * TODO(sam): should we inline the state map in the bundle or bind to a Cloudflare Worker with a blob?
+ * TODO(sam): what should we do with secrets? Seems like we could auto-bind them and resolve without requiring encryption logic.
+ *
+ * @param file the `.ts` file containing an `export default function`
+ */
+export function bundleEntrypoint(_file: string) {}
+
+/**
+ * This is a plugin that bootstraps Alchemy Infrastructure into Runtime by replacing Resources
+ * with a stub that loads from a statically bundled state.
+ *
+ * Take the following table for example:
+ * ```ts
+ * const Table = Resource(
+ *   "dynamodb::Table",
+ *   async function(this, id, props) {
+ *     // lifecycle logic in here
+ *   }
+ * );
+ * ```
+ *
+ * The plugin replaces the Resource with a stub:
+ * ```ts
+ * const Table = (id, props) => STATE.get(id)
+ * ```
+ */
+export const bootstrapPlugin: Plugin = {
+  name: "alchemy-bootstrap",
+  async setup(build) {
+    const { parse, print } = await import("@swc/core");
+    const { Visitor } = await import("@swc/core/Visitor.js");
+
+    async function expr(expr: string) {
+      return (
+        (await parse(`const __temp__ = ${expr}`)).body[0] as VariableDeclaration
+      ).declarations[0].init!;
+    }
+    async function decl(decl: string) {
+      return (await parse(decl)).body[0] as Declaration;
+    }
+
+    const Provider = await decl("async function Resource() {}");
+    const Resource = await expr("(id) => STATE.get(id)");
+    // const alchemy = await expr("(async () => {})");
+
+    // Add a global STATE object to bundle for resource lookup
+    build.onLoad(
+      {
+        filter: /.*\.(ts|js)x?/,
+      },
+      async (args) => {
+        try {
+          const source = await fs.readFile(args.path, "utf-8");
+
+          function transformed(code: string) {
+            return {
+              contents: code,
+              loader: args.path.endsWith(".ts")
+                ? args.path.endsWith(".tsx")
+                  ? "tsx"
+                  : "ts"
+                : args.path.endsWith(".jsx")
+                  ? "jsx"
+                  : "js",
+            } as const;
+          }
+
+          // Parse the source code using SWC
+          const ast = await parse(source, {
+            syntax: "typescript",
+            tsx: args.path.endsWith(".tsx"),
+            decorators: true,
+            dynamicImport: true,
+          });
+
+          // function text({ span }: HasSpan) {
+          //   return source.slice(
+          //     span.start - ast.span.start,
+          //     span.end - ast.span.start,
+          //   );
+          // }
+
+          // Create visitor to transform Resource calls
+          class ResourceTransformer extends Visitor {
+            visitTsType(n: TsType): TsType {
+              return n;
+            }
+            visitFunctionDeclaration(decl: FunctionDeclaration): Declaration {
+              const param = decl.params[0];
+              if (
+                decl.identifier.value === "Resource" &&
+                param?.pat.type === "Identifier" &&
+                param.pat.value === "type" &&
+                decl.body
+              ) {
+                return Provider;
+              }
+              return decl;
+            }
+            visitCallExpression(expr: CallExpression): Expression {
+              // Check if this is a Resource call
+              if (
+                expr.callee.type === "Identifier" &&
+                expr.callee.value === "Resource" &&
+                expr.arguments.length >= 2
+              ) {
+                return Resource;
+                // } else if (
+                //   expr.callee.type === "Identifier" &&
+                //   expr.callee.value === "alchemy"
+                // ) {
+                //   return alchemy;
+              }
+
+              return super.visitCallExpression(expr);
+            }
+          }
+
+          // Apply the transformation
+          const visitor = new ResourceTransformer();
+          const program = visitor.visitProgram(ast);
+
+          // Print the transformed AST back to code
+          const { code } = await print(program, {
+            sourceMaps: true,
+            minify: false,
+          });
+
+          return transformed(code);
+        } catch (error: unknown) {
+          console.error(`Error transforming ${args.path}:`, error);
+          return {
+            errors: [
+              {
+                text: `Failed to transform: ${error instanceof Error ? error.message : String(error)}`,
+                location: { file: args.path },
+              },
+            ],
+          };
+        }
+      },
+    );
+  },
+};

package/src/runtime/shims.js

@@ -0,0 +1,34 @@
+import { env } from "cloudflare:workers";
+import { Scope } from "../scope.js";
+import { Secret } from "../secret.js";
+import { deserialize } from "../serde.js";
+
+globalThis.process.env = env;
+
+export const __ALCHEMY_RUNTIME__ = true;
+
+export var __ALCHEMY_SERIALIZED_SCOPE__ = JSON.parse(
+  env.__ALCHEMY_SERIALIZED_SCOPE__,
+);
+
+export const STATE = {
+  async get(id) {
+    const fqn = globalThis.__ALCHEMY_SCOPE__.current.fqn(id);
+    const state = __ALCHEMY_SERIALIZED_SCOPE__[fqn];
+    if (!state) {
+      throw new Error(
+        `Resource ${fqn} not found in __ALCHEMY_SERIALIZED_SCOPE__\n${JSON.stringify(__ALCHEMY_SERIALIZED_SCOPE__, null, 2)}`,
+      );
+    }
+    return await deserialize(Scope.current, state, {
+      transform: (value) => {
+        if (value && typeof value === "object" && value["@secret-env"]) {
+          return {
+            value: new Secret(env[value["@secret-env"]]),
+          };
+        }
+      },
+    });
+  },
+};
+// export const process = { env };

package/src/runtime/state.ts

@@ -0,0 +1,9 @@
+import type { Resource } from "../resource.js";
+
+export interface RuntimeState {
+  get(id: string): Resource;
+}
+
+// /**
+//  * Runtime state injected into the environment.
+//  */

package/src/scope.ts

@@ -1,12 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Phase } from "./alchemy.js";
-import { destroy } from "./destroy.js";
+import { destroyAll } from "./destroy.js";
 import { FileSystemStateStore } from "./fs/file-system-state-store.js";
 import { ResourceID, type PendingResource } from "./resource.js";
 import type { StateStore, StateStoreType } from "./state.js";
 
-const scopeStorage = new AsyncLocalStorage<Scope>();
-
 export type ScopeOptions = {
   appName?: string;
   stage?: string;
@@ -24,19 +22,30 @@ const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 export class Scope {
   public static readonly KIND = "alchemy::Scope" as const;
 
+  public static storage = new AsyncLocalStorage<Scope>();
+  public static globals: Scope[] = [];
+
   public static get(): Scope | undefined {
-    return scopeStorage.getStore();
+    return Scope.storage.getStore();
+  }
+
+  public static get root(): Scope {
+    return Scope.current.root;
   }
 
   public static get current(): Scope {
     const scope = Scope.get();
     if (!scope) {
+      if (Scope.globals.length > 0) {
+        return Scope.globals[Scope.globals.length - 1];
+      }
       throw new Error("Not running within an Alchemy Scope");
     }
     return scope;
   }
 
   public readonly resources = new Map<ResourceID, PendingResource>();
+  public readonly children: Map<ResourceID, Scope> = new Map();
   public readonly appName: string | undefined;
   public readonly stage: string;
   public readonly scopeName: string | null;
@@ -48,10 +57,12 @@ export class Scope {
   public readonly phase: Phase;
 
   private isErrored = false;
+  private finalized = false;
+
+  private deferred: (() => Promise<any>)[] = [];
 
   constructor(options: ScopeOptions) {
     this.appName = options.appName;
-    this.stage = options?.stage ?? DEFAULT_STAGE;
     this.scopeName = options.scopeName ?? null;
     if (this.scopeName?.includes(":")) {
       throw new Error(
@@ -59,6 +70,8 @@ export class Scope {
       );
     }
     this.parent = options.parent ?? Scope.get();
+    this.stage = options?.stage ?? this.parent?.stage ?? DEFAULT_STAGE;
+    this.parent?.children.set(this.scopeName!, this);
     this.quiet = options.quiet ?? this.parent?.quiet ?? false;
     if (this.parent && !this.scopeName) {
       throw new Error("Scope name is required when creating a child scope");
@@ -77,6 +90,14 @@ export class Scope {
     this.state = this.stateStore(this);
   }
 
+  public get root(): Scope {
+    let root: Scope = this;
+    while (root.parent) {
+      root = root.parent;
+    }
+    return root;
+  }
+
   public async delete(resourceID: ResourceID) {
     await this.state.delete(resourceID);
     this.resources.delete(resourceID);
@@ -102,10 +123,6 @@ export class Scope {
     this.isErrored = true;
   }
 
-  public enter() {
-    scopeStorage.enterWith(this);
-  }
-
   public async init() {
     await this.state.init?.();
   }
@@ -120,7 +137,7 @@ export class Scope {
   }
 
   public async run<T>(fn: (scope: Scope) => Promise<T>): Promise<T> {
-    return scopeStorage.run(this, () => fn(this));
+    return Scope.storage.run(this, () => fn(this));
   }
 
   [Symbol.asyncDispose]() {
@@ -131,6 +148,20 @@ export class Scope {
     if (this.phase === "read") {
       return;
     }
+    if (this.finalized) {
+      return;
+    }
+    if (this.parent === undefined && Scope.globals.length > 0) {
+      const last = Scope.globals.pop();
+      if (last !== this) {
+        throw new Error(
+          "Running in AsyncLocaStorage.enterWith emultation mode and attempted to finalize a global Scope that wasn't top of the stack",
+        );
+      }
+    }
+    this.finalized = true;
+    // trigger and await all deferred promises
+    await Promise.all(this.deferred.map((fn) => fn()));
     if (!this.isErrored) {
       // TODO: need to detect if it is in error
       const resourceIds = await this.state.list();
@@ -141,7 +172,7 @@ export class Scope {
       const orphans = await Promise.all(
         orphanIds.map(async (id) => (await this.state.get(id))!.output),
       );
-      await destroy.all(orphans, {
+      await destroyAll(orphans, {
         quiet: this.quiet,
         strategy: "sequential",
       });
@@ -150,6 +181,28 @@ export class Scope {
     }
   }
 
+  /**
+   * Defers execution of a function until the Alchemy application finalizes.
+   */
+  public defer<T>(fn: () => Promise<T>): Promise<T> {
+    let _resolve: (value: T) => void;
+    let _reject: (reason?: any) => void;
+    const promise = new Promise<T>((resolve, reject) => {
+      _resolve = resolve;
+      _reject = reject;
+    });
+    this.deferred.push(() => {
+      if (!this.finalized) {
+        throw new Error(
+          "Attempted to await a deferred Promise before finalization",
+        );
+      }
+      // lazily trigger the worker on first await
+      return this.run(() => fn()).then(_resolve, _reject);
+    });
+    return promise;
+  }
+
   /**
    * Returns a string representation of the scope.
    */
@@ -162,3 +215,11 @@ export class Scope {
 )`;
   }
 }
+
+declare global {
+  // for runtime
+  // TODO(sam): maybe inject is a better way to achieve this
+  var __ALCHEMY_SCOPE__: typeof Scope;
+}
+
+globalThis.__ALCHEMY_SCOPE__ = Scope;

package/src/secret.ts

@@ -1,5 +1,15 @@
 import { alchemy } from "./alchemy.js";
 
+// a global registry of all secrets that we will use when serializing an application
+const globalSecrets: {
+  [name: string]: Secret;
+} = {};
+
+let i = 0;
+function nextName() {
+  return `alchemy:anonymous-secret-${i++}`;
+}
+
 /**
  * Internal wrapper for sensitive values like API keys and credentials.
  * When stored in alchemy state files, the value is automatically encrypted
@@ -36,8 +46,20 @@ import { alchemy } from "./alchemy.js";
  * }
  */
 export class Secret {
+  /**
+   * @internal
+   */
+  public static all(): Secret[] {
+    return Object.values(globalSecrets);
+  }
+
   public readonly type = "secret";
-  constructor(readonly unencrypted: string) {}
+  constructor(
+    readonly unencrypted: string,
+    readonly name: string = nextName(),
+  ) {
+    globalSecrets[name] = this;
+  }
 }
 
 /**
@@ -79,11 +101,14 @@ export function isSecret(binding: any): binding is Secret {
  * @throws {Error} If the value is undefined
  * @throws {Error} If no password is set in the alchemy application options or current scope
  */
-export function secret<S extends string | undefined>(unencrypted: S): Secret {
+export function secret<S extends string | undefined>(
+  unencrypted: S,
+  name?: string,
+): Secret {
   if (unencrypted === undefined) {
     throw new Error("Secret cannot be undefined");
   }
-  return new Secret(unencrypted);
+  return new Secret(unencrypted, name);
 }
 
 export namespace secret {
@@ -104,7 +129,7 @@ export namespace secret {
   ): Promise<Secret> {
     const result = await alchemy.env(name, value, error);
     if (typeof result === "string") {
-      return secret(result);
+      return secret(result, name);
     }
     throw new Error(`Secret environment variable ${name} is not a string`);
   }

package/src/sentry/client-key.ts

@@ -179,7 +179,7 @@ export const ClientKey = Resource(
   "sentry::ClientKey",
   async function (
     this: Context<ClientKey>,
-    id: string,
+    _id: string,
     props: ClientKeyProps,
   ): Promise<ClientKey> {
     const api = new SentryApi({ authToken: props.authToken });

package/src/sentry/project.ts

@@ -281,7 +281,7 @@ export const Project = Resource(
   "sentry::Project",
   async function (
     this: Context<Project>,
-    id: string,
+    _id: string,
     props: ProjectProps,
   ): Promise<Project> {
     const api = new SentryApi({ authToken: props.authToken });

package/src/sentry/team.ts

@@ -126,7 +126,7 @@ export const Team = Resource(
   "sentry::Team",
   async function (
     this: Context<Team>,
-    id: string,
+    _id: string,
     props: TeamProps,
   ): Promise<Team> {
     const api = new SentryApi({ authToken: props.authToken });

package/src/serde.ts

@@ -1,4 +1,10 @@
 import { decryptWithKey, encrypt } from "./encrypt.js";
+import {
+  InnerResourceScope,
+  ResourceFQN,
+  ResourceKind,
+  type Resource,
+} from "./resource.js";
 import { Scope } from "./scope.js";
 import { Secret } from "./secret.js";
 
@@ -13,13 +19,96 @@ function isType(value: any): value is Type<any, any> {
   );
 }
 
+export type Serialized<T> = T extends
+  | undefined
+  | null
+  | boolean
+  | number
+  | string
+  | bigint
+  ? T
+  : T extends Type<any, any>
+    ? {
+        "@schema": string;
+      }
+    : T extends Secret
+      ? {
+          "@secret": string;
+        }
+      : T extends Date
+        ? {
+            "@date": string;
+          }
+        : T extends Symbol
+          ? {
+              "@symbol": string;
+            }
+          : T extends Scope
+            ? {
+                "@scope": null;
+              }
+            : T extends Function
+              ? undefined
+              : T extends Array<infer U>
+                ? Array<Serialized<U>>
+                : T extends object
+                  ? {
+                      [K in keyof T as K extends symbol
+                        ? string
+                        : K]: Serialized<T[K]>;
+                    }
+                  : T;
+
+export type SerializedScope = {
+  [fqn: ResourceFQN]: Serialized<Resource>;
+};
+
+export async function serializeScope(scope: Scope): Promise<SerializedScope> {
+  const map: SerializedScope = {};
+
+  return serializeScope(scope);
+
+  async function serializeScope(scope: Scope): Promise<SerializedScope> {
+    await Promise.all(
+      Array.from(scope.resources.values()).map(async (resource) => {
+        if (resource[ResourceKind] === Scope.KIND) {
+          return;
+        }
+        map[resource[ResourceFQN]] = await serialize(scope, await resource, {
+          transform: (value) => {
+            if (value instanceof Secret) {
+              return {
+                "@secret-env": value.name,
+              };
+            }
+            return value;
+          },
+        });
+        const innerScope = await resource[InnerResourceScope];
+        if (innerScope) {
+          await serializeScope(innerScope);
+        }
+      }),
+    );
+    await Promise.all(
+      Array.from(scope.children.values()).map((scope) => serializeScope(scope)),
+    );
+    return map;
+  }
+}
+
 export async function serialize(
   scope: Scope,
   value: any,
   options?: {
     encrypt?: boolean;
+    transform?: (value: any) => any;
   },
 ): Promise<any> {
+  if (options?.transform) {
+    value = options.transform(value);
+  }
+
   if (Array.isArray(value)) {
     return Promise.all(value.map((value) => serialize(scope, value, options)));
   } else if (value instanceof Secret) {
@@ -49,17 +138,19 @@ export async function serialize(
     return {
       "@scope": null,
     };
+  } else if (isImportMeta(value)) {
+    // ImportMeta serialized as {}, so we are mapping it
+    // TODO(sam):
+    return Object.fromEntries(
+      Object.keys(Object.getPrototypeOf(value))
+        // exlcude import.meta.env
+        .filter((prop) => prop === "env")
+        .map((prop) => [prop, (value as any)[prop]]),
+    );
   } else if (value && typeof value === "object") {
     for (const symbol of Object.getOwnPropertySymbols(value)) {
       assertNotUniqueSymbol(symbol);
     }
-    for (const key of Object.keys(value)) {
-      if (parseSymbol(key)) {
-        throw new Error(
-          `Cannot serialize property '${key}' because it looks like a stringified symbol.`,
-        );
-      }
-    }
     return Object.fromEntries(
       await Promise.all(
         [...Object.getOwnPropertySymbols(value), ...Object.keys(value)].map(
@@ -77,10 +168,35 @@ export async function serialize(
   return value;
 }
 
-export async function deserialize(scope: Scope, value: any): Promise<any> {
+function isImportMeta(value: any): value is ImportMeta {
+  return (
+    value &&
+    typeof value === "object" &&
+    typeof value.dirname === "string" &&
+    typeof value.filename === "string" &&
+    typeof value.url === "string"
+  );
+}
+
+export async function deserialize(
+  scope: Scope,
+  value: any,
+  options?: {
+    transform?: (value: any) =>
+      | undefined
+      | {
+          value: any;
+        };
+  },
+): Promise<any> {
+  const replacement = options?.transform?.(value);
+  if (replacement) {
+    return replacement.value;
+  }
+
   if (Array.isArray(value)) {
     return await Promise.all(
-      value.map(async (item) => await deserialize(scope, item)),
+      value.map(async (item) => await deserialize(scope, item, options)),
     );
   }
   if (value && typeof value === "object") {
@@ -103,7 +219,7 @@ export async function deserialize(scope: Scope, value: any): Promise<any> {
       await Promise.all(
         Object.entries(value).map(async ([key, value]) => [
           parseSymbol(key) ?? key,
-          await deserialize(scope, value),
+          await deserialize(scope, value, options),
         ]),
       ),
     );

package/src/stripe/meter.ts

@@ -141,7 +141,7 @@ export const Meter = Resource(
   "stripe::Meter",
   async function (
     this: Context<Meter>,
-    logicalId: string,
+    _logicalId: string,
     props: MeterProps,
   ): Promise<Meter> {
     const apiKey = process.env.STRIPE_API_KEY;

package/src/stripe/price.ts

@@ -192,7 +192,7 @@ export const Price = Resource(
   "stripe::Price",
   async function (
     this: Context<Price>,
-    id: string,
+    _id: string,
     props: PriceProps,
   ): Promise<Price> {
     // Get Stripe API key from context or environment

package/src/stripe/product.ts

@@ -141,7 +141,7 @@ export const Product = Resource(
   "stripe::Product",
   async function (
     this: Context<Product>,
-    id: string,
+    _id: string,
     props: ProductProps,
   ): Promise<Product> {
     // Get Stripe API key from context or environment

package/src/stripe/webhook.ts

@@ -135,7 +135,7 @@ export const WebhookEndpoint = Resource(
   "stripe::WebhookEndpoint",
   async function (
     this: Context<WebhookEndpoint>,
-    id: string,
+    _id: string,
     props: WebhookEndpointProps,
   ) {
     // Get Stripe API key from context or environment