alchemy 0.8.1 → 0.9.0

package/lib/alchemy.d.ts

@@ -28,7 +28,6 @@ export declare const alchemy: Alchemy;
  * await app.finalize();
  */
 export interface Alchemy {
-    scope: typeof scope;
     run: typeof run;
     destroy: typeof destroy;
     /**
@@ -52,7 +51,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.
@@ -115,21 +114,15 @@ 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)
- * });
- */
-declare function scope(id: string | undefined, options?: AlchemyOptions): Scope;
+export interface ScopeOptions extends AlchemyOptions {
+    enter: boolean;
+}
+export interface RunOptions extends AlchemyOptions {
+    /**
+     * @default false
+     */
+    isResource?: boolean;
+}
 /**
  * Run a function in a new scope asynchronously.
  * Useful for isolating secret handling with a specific password.
@@ -147,7 +140,7 @@ declare function scope(id: string | undefined, options?: AlchemyOptions): Scope;
  */
 declare function run<T>(...args: [id: string, fn: (this: Scope, scope: Scope) => Promise<T>] | [
     id: string,
-    options: AlchemyOptions,
+    options: RunOptions,
     fn: (this: Scope, scope: Scope) => Promise<T>
 ]): Promise<T>;
 export declare function env<T = string>(name: string, value?: T | undefined, error?: string): Promise<T>;

package/lib/alchemy.js

@@ -1,10 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { DestroyedSignal, destroy } from "./destroy";
+import { destroy, DestroyedSignal } from "./destroy";
 import { Scope } from "./scope";
 import { secret } from "./secret";
-// TODO: support browser
-const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 export const alchemy = _alchemy;
 /**
  * Implementation of the alchemy function that handles both application scoping
@@ -13,11 +11,12 @@ export const alchemy = _alchemy;
 async function _alchemy(...args) {
     if (typeof args[0] === "string") {
         const [appName, options] = args;
-        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);
@@ -119,37 +118,8 @@ async function _alchemy(...args) {
 }
 _alchemy.destroy = destroy;
 _alchemy.run = run;
-_alchemy.scope = scope;
 _alchemy.secret = secret;
 _alchemy.env = env;
-/**
- * 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, options
-// TODO: maybe we want to allow using _ = await alchemy.scope(import.meta)
-// | [meta: ImportMeta]
-) {
-    const scope = new Scope({
-        ...options,
-        appName: options?.appName,
-        stage: options?.stage ?? DEFAULT_STAGE,
-        scopeName: id,
-        parent: options?.parent ?? Scope.get(),
-    });
-    scope.enter();
-    return scope;
-}
 /**
  * Run a function in a new scope asynchronously.
  * Useful for isolating secret handling with a specific password.
@@ -169,20 +139,45 @@ async function run(...args) {
     const [id, options, fn] = typeof args[1] === "function"
         ? [args[0], undefined, args[1]]
         : args;
-    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,
+            };
+            const resource = {
+                kind: "scope",
+                id,
+                seq,
+                data: {},
+                fqn: "",
+                props: {},
+                status: "created",
+                output,
+            };
+            await _scope.parent.state.set(id, resource);
+            _scope.parent.resources.set(id, Object.assign(Promise.resolve(resource), output));
+        }
+        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();
     }
 }
 export async function env(name, value, error) {

package/lib/apply.js

@@ -75,7 +75,9 @@ export async function apply(resource, props, options) {
                 isReplaced = true;
             },
         });
-        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(`${phase === "create" ? "Created" : "Updated"}: "${resource.FQN}"`);
         }

package/lib/cloudflare/index.d.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/lib/cloudflare/index.js

@@ -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/lib/cloudflare/pipeline.js

@@ -71,7 +71,6 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function (id, pro
     const api = await createCloudflareApi(props);
     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);
@@ -82,13 +81,11 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function (id, pro
     else {
         let pipelineData;
         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("Cannot update Pipeline name after creation. Pipeline name is immutable.");

package/lib/cloudflare/vite-site.d.ts

@@ -0,0 +1,39 @@
+import { Assets } from "./assets";
+import type { Bindings } from "./bindings";
+import { Worker } from "./worker";
+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<B extends {
+    ASSETS: any;
+} ? never : Worker<B & {
+    ASSETS: Assets;
+}>>;
+export declare function ViteSite<B extends Bindings>(id: string, props: ViteSiteProps<B>): ViteSite<B>;

package/lib/cloudflare/vite-site.js

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { alchemy } from "../alchemy";
+import { Exec } from "../os";
+import { Assets } from "./assets";
+import { Worker } from "./worker";
+import { WranglerJson } from "./wrangler.json";
+export async function ViteSite(id, props) {
+    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/lib/cloudflare/wrangler.json.js

@@ -5,7 +5,7 @@ import { Resource } from "../resource";
  */
 export const WranglerJson = Resource("cloudflare::WranglerJson", async function (id, props) {
     // 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/lib/destroy.js

@@ -33,6 +33,14 @@ export async function destroy(...args) {
     if (!instance) {
         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 = 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.`);
@@ -66,7 +74,11 @@ export async function destroy(...args) {
         let nestedScope;
         try {
             // BUG: this does not restore persisted scope
-            await alchemy.run(instance.ID, async (scope) => {
+            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);
             });
@@ -97,7 +109,7 @@ export async function destroy(...args) {
         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 {

package/lib/fs/file-system-state-store.d.ts

@@ -3,6 +3,7 @@ import type { State, StateStore } from "../state";
 export declare class FileSystemStateStore implements StateStore {
     readonly scope: Scope;
     readonly dir: string;
+    private initialized;
     constructor(scope: Scope);
     init(): Promise<void>;
     deinit(): Promise<void>;

package/lib/fs/file-system-state-store.js

@@ -1,4 +1,4 @@
-import fs from "node:fs/promises";
+import fs from "node:fs";
 import path from "node:path";
 import { deserialize, serialize } from "../serde";
 import { ignore } from "../util/ignore";
@@ -6,23 +6,27 @@ const stateRootDir = path.join(process.cwd(), ".alchemy");
 export class FileSystemStateStore {
     scope;
     dir;
+    initialized = false;
     constructor(scope) {
         this.scope = scope;
         this.dir = path.join(stateRootDir, ...scope.chain);
     }
     async init() {
-        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() {
-        await ignore("ENOENT", () => fs.rmdir(this.dir));
+        await ignore("ENOENT", () => fs.promises.rmdir(this.dir));
     }
     async count() {
         return Object.keys(await this.list()).length;
     }
     async list() {
         try {
-            const files = await fs.readdir(this.dir, {
+            const files = await fs.promises.readdir(this.dir, {
                 withFileTypes: true,
             });
             return files
@@ -39,7 +43,7 @@ export class FileSystemStateStore {
     }
     async get(key) {
         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)));
             if (state.output === undefined) {
                 state.output = {};
@@ -55,10 +59,19 @@ export class FileSystemStateStore {
         }
     }
     async set(key, value) {
-        return fs.writeFile(await this.getPath(key), JSON.stringify(await serialize(this.scope, value), null, 2));
+        await this.init();
+        await fs.promises.writeFile(this.getPath(key), JSON.stringify(await serialize(this.scope, value), null, 2));
     }
     async delete(key) {
-        return fs.unlink(await this.getPath(key));
+        try {
+            return await fs.promises.unlink(this.getPath(key));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
     }
     async all() {
         return this.getBatch(await this.list());
@@ -72,16 +85,13 @@ export class FileSystemStateStore {
             return [[id, s]];
         }))).flat());
     }
-    async getPath(key) {
+    getPath(key) {
         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/lib/scope.d.ts

@@ -2,7 +2,7 @@ import type { PendingResource, ResourceID } from "./resource";
 import type { StateStore, StateStoreType } from "./state";
 export type ScopeOptions = {
     appName?: string;
-    stage: string;
+    stage?: string;
     parent?: Scope;
     scopeName?: string;
     password?: string;

package/lib/scope.js

@@ -2,6 +2,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { destroy } from "./destroy";
 import { FileSystemStateStore } from "./fs/file-system-state-store";
 const scopeStorage = new AsyncLocalStorage();
+// TODO: support browser
+const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 export class Scope {
     static get() {
         return scopeStorage.getStore();
@@ -24,14 +26,14 @@ export class Scope {
     isErrored = false;
     constructor(options) {
         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);
@@ -65,6 +67,7 @@ export class Scope {
         await this.state.init?.();
     }
     async deinit() {
+        await this.parent?.state.delete(this.scopeName);
         await this.state.deinit?.();
     }
     fqn(resourceID) {

package/lib/state.d.ts

@@ -1,6 +1,6 @@
 import type { Resource, ResourceProps } from "./resource";
 import type { Scope } from "./scope";
-export interface State<Kind extends string = string, Props extends ResourceProps | undefined = ResourceProps | undefined, Out extends Resource = Resource> {
+export type State<Kind extends string = string, Props extends ResourceProps | undefined = ResourceProps | undefined, Out extends Resource = Resource> = {
     status: `creating` | `created` | `updating` | `updated` | `deleting` | `deleted`;
     kind: Kind;
     id: string;
@@ -10,7 +10,7 @@ export interface State<Kind extends string = string, Props extends ResourceProps
     props: Props;
     oldProps?: Props;
     output: Out;
-}
+};
 export type StateStoreType = (scope: Scope) => StateStore;
 export interface StateStore {
     /** Initialize the state container if one is required */

package/lib/test/bun.d.ts

@@ -1,4 +1,4 @@
-import type { Scope } from "../scope";
+import { Scope } from "../scope";
 import type { StateStoreType } from "../state";
 /**
  * Extend the Alchemy interface to include test functionality
@@ -12,11 +12,6 @@ declare module "../alchemy" {
  * Options for configuring test behavior
  */
 export interface TestOptions {
-    /**
-     * Whether to automatically destroy resources after test.
-     * @default true.
-     */
-    destroy?: boolean;
     /**
      * Whether to suppress logging output.
      * @default false.

package/lib/test/bun.js

@@ -3,7 +3,7 @@ import { afterAll, beforeAll, it } from "bun:test";
 import path from "node:path";
 import { alchemy } from "../alchemy";
 import { R2RestStateStore } from "../cloudflare";
-import { destroy } from "../destroy";
+import { Scope } from "../scope";
 /**
  * Add test functionality to alchemy instance
  */
@@ -32,7 +32,6 @@ alchemy.test = test;
  * ```
  */
 export function test(meta, defaultOptions) {
-    let isFailed = false;
     defaultOptions = defaultOptions ?? {};
     if (defaultOptions.stateStore === undefined &&
         // process.env.CI &&
@@ -52,29 +51,17 @@ export function test(meta, defaultOptions) {
         return test;
     };
     // Create local test scope based on filename
-    const localTestScope = alchemy.scope(`${defaultOptions.prefix ? `${defaultOptions.prefix}-` : ""}${path.basename(meta.filename)}`, {
+    const scope = new Scope({
+        scopeName: `${defaultOptions.prefix ? `${defaultOptions.prefix}-` : ""}${path.basename(meta.filename)}`,
         // parent: globalTestScope,
         stateStore: defaultOptions?.stateStore,
     });
-    test.scope = localTestScope;
     test.beforeAll = (fn) => {
-        return beforeAll(async () => {
-            test.scope.enter();
-            await fn(test.scope);
-        });
+        return beforeAll(() => scope.run(() => fn(scope)));
     };
     test.afterAll = (fn) => {
-        return afterAll(async () => {
-            test.scope.enter();
-            await fn(test.scope);
-        });
+        return afterAll(() => scope.run(() => fn(scope)));
     };
-    // Clean up test scope after all tests complete
-    afterAll(async () => {
-        if (defaultOptions?.destroy !== false && !isFailed) {
-            await alchemy.destroy(test.scope);
-        }
-    });
     return test;
     function test(...args) {
         const testName = args[0];
@@ -87,33 +74,24 @@ export function test(meta, defaultOptions) {
             : {};
         // Merge options with defaults
         const options = {
-            destroy: true,
             quiet: false,
             password: "test-password",
             ...spread(defaultOptions),
             ...spread(_options),
         };
         const fn = typeof args[1] === "function" ? args[1] : args[2];
-        return alchemy.run(testName, {
+        return it(testName, async () => alchemy.run(testName, {
             ...options,
-            parent: localTestScope,
+            parent: scope,
         }, async (scope) => {
-            return it(testName, async () => {
+            try {
                 // Enter test scope since bun calls from different scope
-                scope.enter();
-                try {
-                    await fn(scope);
-                }
-                catch (err) {
-                    console.error(err);
-                    throw err;
-                }
-                finally {
-                    if (options.destroy !== false) {
-                        await destroy(scope);
-                    }
-                }
-            }, timeout);
-        });
+                await scope.run(() => fn(scope));
+            }
+            catch (err) {
+                console.error(err);
+                throw err;
+            }
+        }), timeout);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {