alchemy 0.8.1 → 0.9.0

package/src/alchemy.ts

@@ -1,14 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { DestroyedSignal, destroy } from "./destroy";
+import { destroy, DestroyedSignal } from "./destroy";
+import type { PendingResource } from "./resource";
 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";
-
 /**
  * Type alias for semantic highlighting of `alchemy` as a type keyword
  */
@@ -37,7 +35,6 @@ export const alchemy: Alchemy = _alchemy as any;
  * await app.finalize();
  */
 export interface Alchemy {
-  scope: typeof scope;
   run: typeof run;
   destroy: typeof destroy;
 
@@ -63,7 +60,7 @@ export interface Alchemy {
    *   password: process.env.SECRET_PASSPHRASE
    * });
    */
-  (...parameters: Parameters<typeof scope>): Promise<Scope>;
+  (appName: string, options?: Omit<AlchemyOptions, "appName">): Promise<Scope>;
   /**
    * Template literal tag that supports file interpolation for documentation.
    * Automatically formats the content and appends file contents as code blocks.
@@ -95,11 +92,12 @@ async function _alchemy(
 ): Promise<Scope | string | never> {
   if (typeof args[0] === "string") {
     const [appName, options] = args as [string, AlchemyOptions?];
-    const root = scope(undefined, {
+    const root = new Scope({
       ...options,
       appName,
       stage: options?.stage,
     });
+    root.enter();
     if (options?.phase === "destroy") {
       await destroy(root);
       return process.exit(0);
@@ -215,7 +213,6 @@ async function _alchemy(
 }
 _alchemy.destroy = destroy;
 _alchemy.run = run;
-_alchemy.scope = scope;
 _alchemy.secret = secret;
 _alchemy.env = env;
 
@@ -256,7 +253,6 @@ export interface AlchemyOptions {
    * @default false
    */
   quiet?: boolean;
-
   /**
    * A passphrase to use to encrypt/decrypt secrets.
    * Required if using alchemy.secret() in this scope.
@@ -264,35 +260,16 @@ export interface AlchemyOptions {
   password?: string;
 }
 
-/**
- * Enter a new scope synchronously.
- *
- * @example
- * // Create a scope with a password for secret handling
- * await using scope = alchemy.scope("my-scope", {
- *   password: process.env.SECRET_PASSPHRASE
- * });
- *
- * // Use secrets within the scope
- * const resource = await Resource("my-resource", {
- *   apiKey: alchemy.secret(process.env.API_KEY)
- * });
- */
-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;
+export interface ScopeOptions extends AlchemyOptions {
+  enter: boolean;
+}
+
+export interface RunOptions extends AlchemyOptions {
+  /**
+   * @default false
+   */
+  // TODO(sam): this is an awful hack to differentiate between naked scopes and resources
+  isResource?: boolean;
 }
 
 /**
@@ -315,7 +292,7 @@ async function run<T>(
     | [id: string, fn: (this: Scope, scope: Scope) => Promise<T>]
     | [
         id: string,
-        options: AlchemyOptions,
+        options: RunOptions,
         fn: (this: Scope, scope: Scope) => Promise<T>,
       ]
 ): Promise<T> {
@@ -324,20 +301,49 @@ async function run<T>(
       ? [args[0], undefined, args[1]]
       : (args as [
           string,
-          AlchemyOptions | undefined,
+          RunOptions,
           (this: Scope, scope: Scope) => Promise<T>,
         ]);
-  const scope = alchemy.scope(id, options);
+  const _scope = new Scope({
+    ...options,
+    scopeName: id,
+  });
   try {
-    return await fn.bind(scope)(scope);
+    if (options?.isResource !== true && _scope.parent) {
+      // 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: "alchemy::Scope",
+        Scope: _scope,
+        Seq: seq,
+      } as const;
+      const resource = {
+        kind: "scope",
+        id,
+        seq,
+        data: {},
+        fqn: "",
+        props: {},
+        status: "created",
+        output,
+      } as const;
+      await _scope.parent!.state.set(id, resource);
+      _scope.parent!.resources.set(
+        id,
+        Object.assign(Promise.resolve(resource), output) as PendingResource
+      );
+    }
+    return await _scope.run(async () => fn.bind(_scope)(_scope));
   } catch (error) {
     if (!(error instanceof DestroyedSignal)) {
-      scope.fail();
-    } else {
+      console.log(error);
+      _scope.fail();
     }
     throw error;
   } finally {
-    await scope.finalize();
+    await _scope.finalize();
   }
 }
 

package/src/apply.ts

@@ -107,8 +107,12 @@ export async function apply<Out extends Resource>(
       },
     });
 
-    const output = await alchemy.run(resource.ID, async () =>
-      provider.handler.bind(ctx)(resource.ID, props)
+    const output = await alchemy.run(
+      resource.ID,
+      {
+        isResource: true,
+      },
+      async () => provider.handler.bind(ctx)(resource.ID, props)
     );
     if (!quiet) {
       console.log(

package/src/cloudflare/index.ts

@@ -15,6 +15,7 @@ export * from "./queue";
 export * from "./r2-rest-state-store";
 export * from "./vectorize-index";
 export * from "./vectorize-metadata-index";
+export * from "./vite-site";
 export * from "./worker";
 export { Workflow } from "./workflow";
 export * from "./wrangler.json";

package/src/cloudflare/pipeline.ts

@@ -318,7 +318,6 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function <
   const pipelineName = props.name || id;
 
   if (this.phase === "delete") {
-    console.log("Deleting Cloudflare Pipeline:", pipelineName);
     if (props.delete !== false) {
       // Delete Pipeline
       await deletePipeline(api, pipelineName);
@@ -330,13 +329,10 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function <
     let pipelineData: CloudflarePipelineResponse;
 
     if (this.phase === "create") {
-      console.log("Creating Cloudflare Pipeline:", pipelineName);
       pipelineData = await createPipeline(api, pipelineName, props);
     } else {
       // Update operation
       if (this.output?.id) {
-        console.log("Updating Cloudflare Pipeline:", pipelineName);
-
         // Check if name is being changed, which is not allowed
         if (props.name !== this.output.name) {
           throw new Error(

package/src/cloudflare/vite-site.ts

@@ -0,0 +1,111 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { alchemy } from "../alchemy";
+import { Exec } from "../os";
+import { Assets } from "./assets";
+import type { Bindings } from "./bindings";
+import { Worker } from "./worker";
+import { WranglerJson } from "./wrangler.json";
+
+export interface ViteSiteProps<B extends Bindings> {
+  /**
+   * The command to run to build the site
+   */
+  command: string;
+  /**
+   * The name of the worker
+   *
+   * @default id
+   */
+  name?: string;
+  /**
+   * The entrypoint to your server
+   *
+   * @default - a simple server that serves static assets is generated
+   */
+  main?: string;
+  /**
+   * The directory containing your static assets
+   */
+  assets: string;
+  /**
+   * The bindings to pass to the worker
+   */
+  bindings?: B;
+  /**
+   * @default process.cwd()
+   */
+  cwd?: string;
+}
+
+export type ViteSite<B extends Bindings> = Promise<
+  // don't allow the ASSETS to be overriden
+  B extends { ASSETS: any } ? never : Worker<B & { ASSETS: Assets }>
+>;
+
+export async function ViteSite<B extends Bindings>(
+  id: string,
+  props: ViteSiteProps<B>
+): ViteSite<B> {
+  if (props.bindings?.ASSETS) {
+    throw new Error("ASSETS binding is reserved for internal use");
+  }
+
+  // @ts-ignore - we know the types are correct
+  return await alchemy.run(id, async () => {
+    // Create minimal wrangler.jsonc if it doesn't exist
+
+    // `building the site requires a wrangler.jsonc file to start - so initialize an empty one if it doesn't exist`
+    const cwd = props.cwd || process.cwd();
+    const wranglerPath = path.join(cwd, "wrangler.jsonc");
+    try {
+      await fs.access(wranglerPath);
+    } catch {
+      await fs.writeFile(
+        wranglerPath,
+        JSON.stringify(
+          {
+            name: id,
+            main: props.main,
+            compatibility_date: new Date().toISOString().split("T")[0],
+          },
+          null,
+          2
+        )
+      );
+    }
+
+    await Exec("build", {
+      command: props.command,
+    });
+
+    const staticAssets = await Assets("assets", {
+      path: "./dist",
+    });
+
+    const worker = await Worker("worker", {
+      name: props.name ?? id,
+      entrypoint: props.main,
+      script: props.main
+        ? undefined
+        : `
+export default {
+  async fetch(request, env) {
+    return env.ASSETS.fetch(request);
+  },
+};`,
+      url: true,
+      adopt: true,
+      bindings: {
+        ...props.bindings,
+        ASSETS: staticAssets,
+      },
+    });
+
+    await WranglerJson("wrangler.jsonc", {
+      worker,
+    });
+
+    return worker;
+  });
+}

package/src/cloudflare/wrangler.json.ts

@@ -55,7 +55,7 @@ export const WranglerJson = Resource(
     props: WranglerJsonProps
   ): Promise<WranglerJson> {
     // Default path is wrangler.json in current directory
-    const filePath = props.path || "wrangler.json";
+    const filePath = props.path || "wrangler.jsonc";
 
     if (this.phase === "delete") {
       return this.destroy();

package/src/destroy.ts

@@ -39,7 +39,7 @@ export async function destroy<Type extends string>(
         ...orphan.output,
         Scope: scope,
       })),
-      options,
+      options
     );
     // finally, destroy the scope container
     await scope.deinit();
@@ -52,10 +52,19 @@ export async function destroy<Type extends string>(
     return;
   }
 
+  if (instance.Kind === "alchemy::Scope") {
+    const scope = new Scope({
+      parent: instance.Scope,
+      scopeName: instance.ID,
+    });
+    console.log("Destroying scope", scope.chain.join("/"));
+    return await destroy(scope, options);
+  }
+
   const Provider: Provider<Type> | undefined = PROVIDERS.get(instance.Kind);
   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.FQN}" type ${instance.Kind} - no provider found. You may need to import the provider in your alchemy.config.ts.`
     );
   }
 
@@ -93,10 +102,18 @@ export async function destroy<Type extends string>(
     let nestedScope: Scope | undefined;
     try {
       // BUG: this does not restore persisted scope
-      await alchemy.run(instance.ID, async (scope) => {
-        nestedScope = scope;
-        return await Provider.handler.bind(ctx)(instance.ID, state.props);
-      });
+      await alchemy.run(
+        instance.ID,
+        {
+          // TODO(sam): this is an awful hack to differentiate between naked scopes and resources
+          isResource: instance.Kind !== "alchemy::Scope",
+          parent: scope,
+        },
+        async (scope) => {
+          nestedScope = scope;
+          return await Provider.handler.bind(ctx)(instance.ID, state.props);
+        }
+      );
     } catch (err) {
       if (err instanceof DestroyedSignal) {
         // TODO: should we fail if the DestroyedSignal is not thrown?
@@ -125,11 +142,11 @@ export namespace destroy {
     if (options?.strategy !== "parallel") {
       const sorted = resources.sort((a, b) => b.Seq - a.Seq);
       for (const resource of sorted) {
-        await destroy(resource);
+        await destroy(resource, options);
       }
     } else {
       await Promise.all(
-        resources.map((resource) => destroy(resource, options)),
+        resources.map((resource) => destroy(resource, options))
       );
     }
   }

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

@@ -1,4 +1,4 @@
-import fs from "node:fs/promises";
+import fs from "node:fs";
 import path from "node:path";
 import type { Scope } from "../scope";
 import { deserialize, serialize } from "../serde";
@@ -9,17 +9,21 @@ const stateRootDir = path.join(process.cwd(), ".alchemy");
 
 export class FileSystemStateStore implements StateStore {
   public readonly dir: string;
+  private initialized = false;
   constructor(public readonly scope: Scope) {
     this.dir = path.join(stateRootDir, ...scope.chain);
   }
 
   async init(): Promise<void> {
-    await fs.mkdir(stateRootDir, { recursive: true });
-    await fs.mkdir(this.dir, { recursive: true });
+    if (this.initialized) {
+      return;
+    }
+    this.initialized = true;
+    await fs.promises.mkdir(this.dir, { recursive: true });
   }
 
   async deinit(): Promise<void> {
-    await ignore("ENOENT", () => fs.rmdir(this.dir));
+    await ignore("ENOENT", () => fs.promises.rmdir(this.dir));
   }
 
   async count(): Promise<number> {
@@ -28,7 +32,7 @@ export class FileSystemStateStore implements StateStore {
 
   async list(): Promise<string[]> {
     try {
-      const files = await fs.readdir(this.dir, {
+      const files = await fs.promises.readdir(this.dir, {
         withFileTypes: true,
       });
       return files
@@ -45,7 +49,7 @@ export class FileSystemStateStore implements StateStore {
 
   async get(key: string): Promise<State | undefined> {
     try {
-      const content = await fs.readFile(await this.getPath(key), "utf8");
+      const content = await fs.promises.readFile(this.getPath(key), "utf8");
       const state = (await deserialize(
         this.scope,
         JSON.parse(content)
@@ -64,14 +68,22 @@ export class FileSystemStateStore implements StateStore {
   }
 
   async set(key: string, value: State): Promise<void> {
-    return fs.writeFile(
-      await this.getPath(key),
+    await this.init();
+    await fs.promises.writeFile(
+      this.getPath(key),
       JSON.stringify(await serialize(this.scope, value), null, 2)
     );
   }
 
   async delete(key: string): Promise<void> {
-    return fs.unlink(await this.getPath(key));
+    try {
+      return await fs.promises.unlink(this.getPath(key));
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
   }
 
   async all(): Promise<Record<string, State>> {
@@ -94,16 +106,13 @@ export class FileSystemStateStore implements StateStore {
     );
   }
 
-  private async getPath(key: string): Promise<string> {
+  private getPath(key: string): string {
     if (key.includes(":")) {
       throw new Error(`ID cannot include colons: ${key}`);
     }
     if (key.includes("/")) {
       key = key.replaceAll("/", ":");
     }
-    const file = path.join(this.dir, `${key}.json`);
-    const dir = path.dirname(file);
-    await fs.mkdir(dir, { recursive: true });
-    return file;
+    return path.join(this.dir, `${key}.json`);
   }
 }

package/src/scope.ts

@@ -8,7 +8,7 @@ const scopeStorage = new AsyncLocalStorage<Scope>();
 
 export type ScopeOptions = {
   appName?: string;
-  stage: string;
+  stage?: string;
   parent?: Scope;
   scopeName?: string;
   password?: string;
@@ -16,6 +16,9 @@ export type ScopeOptions = {
   quiet?: boolean;
 };
 
+// TODO: support browser
+const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
+
 export class Scope {
   public static get(): Scope | undefined {
     return scopeStorage.getStore();
@@ -42,14 +45,14 @@ export class Scope {
 
   constructor(options: ScopeOptions) {
     this.appName = options.appName;
-    this.stage = options.stage;
+    this.stage = options?.stage ?? DEFAULT_STAGE;
     this.scopeName = options.scopeName ?? null;
     this.parent = options.parent ?? Scope.get();
     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");
     }
-    this.password = options.password;
+    this.password = options.password ?? this.parent?.password;
     this.state = options.stateStore
       ? options.stateStore(this)
       : new FileSystemStateStore(this);
@@ -90,6 +93,7 @@ export class Scope {
   }
 
   public async deinit() {
+    await this.parent?.state.delete(this.scopeName!);
     await this.state.deinit?.();
   }
 
@@ -111,10 +115,10 @@ export class Scope {
       const resourceIds = await this.state.list();
       const aliveIds = new Set(this.resources.keys());
       const orphanIds = Array.from(
-        resourceIds.filter((id) => !aliveIds.has(id)),
+        resourceIds.filter((id) => !aliveIds.has(id))
       );
       const orphans = await Promise.all(
-        orphanIds.map(async (id) => (await this.state.get(id))!.output),
+        orphanIds.map(async (id) => (await this.state.get(id))!.output)
       );
       await destroy.all(orphans, {
         quiet: this.quiet,

package/src/state.ts

@@ -1,11 +1,11 @@
 import type { Resource, ResourceProps } from "./resource";
 import type { Scope } from "./scope";
 
-export interface State<
+export type State<
   Kind extends string = string,
   Props extends ResourceProps | undefined = ResourceProps | undefined,
   Out extends Resource = Resource,
-> {
+> = {
   status:
     | `creating`
     | `created`
@@ -22,7 +22,7 @@ export interface State<
   props: Props;
   oldProps?: Props;
   output: Out;
-}
+};
 
 export type StateStoreType = (scope: Scope) => StateStore;