alchemy 0.1.17 → 0.2.0

package/src/scope.ts

@@ -1,51 +1,116 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import path from "node:path";
-import type { Output } from "./output";
-import type { Provider, Resource, ResourceID } from "./resource";
+import type { PendingResource, ResourceID } from "./resource";
+import {
+  FileSystemStateStore,
+  type StateStore,
+  type StateStoreType,
+} from "./state";
 
 const scopeStorage = new AsyncLocalStorage<Scope>();
 
+export type ScopeOptions = {
+  appName?: string;
+  stage: string;
+  parent?: Scope;
+  scopeName?: string;
+  password?: string;
+  stateStore?: StateStoreType;
+  quiet?: boolean;
+};
+
 export class Scope {
-  public readonly nodes = new Map<
-    ResourceID,
-    {
-      provider: Provider<any, any[], any>;
-      resource: Resource<any, any>;
+  public static get(): Scope | undefined {
+    return scopeStorage.getStore();
+  }
+
+  public static get current(): Scope {
+    const scope = Scope.get();
+    if (!scope) {
+      throw new Error("Not running within an Alchemy Scope");
     }
-  >();
+    return scope;
+  }
 
-  public readonly callbacks: Output<void>[] = [];
+  public readonly resources = new Map<ResourceID, PendingResource>();
+  public readonly appName: string | undefined;
+  public readonly stage: string;
+  public readonly scopeName: string | null;
+  public readonly parent: Scope | undefined;
+  public readonly password: string | undefined;
+  public readonly state: StateStore;
+  public readonly quiet: boolean;
 
-  constructor(
-    public readonly scopeName: string | null = null,
-    public readonly parent: Scope | undefined = undefined,
-  ) {}
+  constructor(options: ScopeOptions) {
+    this.appName = options.appName;
+    this.stage = options.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.state = new (options.stateStore ?? FileSystemStateStore)(this);
+  }
 
-  public getScopePath(root: string): string {
-    // First, compute the parent's scope path
-    const parentPath = this.parent ? this.parent.getScopePath(root) : root;
-    // Then join the current scope name (if any) onto the parent's path
-    return this.scopeName ? path.join(parentPath, this.scopeName) : parentPath;
+  public async delete(resourceID: ResourceID) {
+    await this.state.delete(resourceID);
+    this.resources.delete(resourceID);
   }
-}
 
-export const rootScope = new Scope(null);
+  private _seq = 0;
 
-export function getScope(): Scope {
-  return scopeStorage.getStore() ?? rootScope;
-}
+  public seq() {
+    return this._seq++;
+  }
 
-export function withScope<T>(
-  scope: Scope,
-  fn: () => T | Promise<T>,
-): Promise<T> {
-  return scopeStorage.run(scope, async () => fn());
-}
+  public get chain(): string[] {
+    const thisScope = this.scopeName ? [this.scopeName] : [];
+    const app = this.appName ? [this.appName] : [];
+    if (this.parent) {
+      return [...this.parent.chain, ...thisScope];
+    } else {
+      return [...app, this.stage, ...thisScope];
+    }
+  }
+
+  public enter() {
+    scopeStorage.enterWith(this);
+  }
 
-export function pushScope<T>(
-  parent: Scope,
-  scopeName: string,
-  fn: () => T | Promise<T>,
-): Promise<T> {
-  return scopeStorage.run(new Scope(scopeName, parent), async () => fn());
+  public async init() {
+    await this.state.init?.();
+  }
+
+  public async deinit() {
+    await this.state.deinit?.();
+  }
+
+  public fqn(resourceID: ResourceID): string {
+    return [...this.chain, resourceID].join("/");
+  }
+
+  public async finalize() {
+    // TODO
+  }
+
+  public async run<T>(fn: (scope: Scope) => Promise<T>): Promise<T> {
+    return scopeStorage.run(this, () => fn(this));
+  }
+
+  [Symbol.asyncDispose]() {
+    return this.finalize();
+  }
+
+  /**
+   * Returns a string representation of the scope.
+   */
+  toString() {
+    return `Scope(
+  chain=${this.chain.join("/")},
+  resources=[${Array.from(this.resources.values())
+    .map((r) => r.ID)
+    .join(",\n  ")}]
+)`;
+  }
 }

package/src/secret.ts

@@ -0,0 +1,18 @@
+export class Secret {
+  public readonly type = "secret";
+  constructor(readonly unencrypted: string) {}
+}
+
+export function isSecret(binding: any): binding is Secret {
+  return (
+    binding instanceof Secret ||
+    (typeof binding === "object" && binding.type === "secret_text")
+  );
+}
+
+export function secret<S extends string | undefined>(unencrypted: S): Secret {
+  if (unencrypted === undefined) {
+    throw new Error("Secret cannot be undefined");
+  }
+  return new Secret(unencrypted);
+}

package/src/state.ts

@@ -1,8 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
-import { ignore } from "./error";
+import type { Resource, ResourceProps } from "./resource";
+import type { Scope } from "./scope";
+import { ignore } from "./util/ignore";
+import { deserialize, serialize } from "./util/serde";
 
-export interface State {
+export interface State<
+  Kind extends string = string,
+  Props extends ResourceProps = ResourceProps,
+  Out extends Resource = Resource,
+> {
   status:
     | `creating`
     | `created`
@@ -10,14 +17,19 @@ export interface State {
     | `updated`
     | `deleting`
     | `deleted`;
-  provider: string;
+  kind: Kind;
+  id: string;
+  fqn: string;
+  seq: number;
   data: Record<string, any>;
-  deps: string[];
-  inputs: any[];
-  oldInputs?: any[];
-  output: any;
+  // deps: string[];
+  props: Props;
+  oldProps?: Props;
+  output: Out;
 }
 
+export type StateStoreType = new (scope: Scope) => StateStore;
+
 export interface StateStore {
   /** Initialize the state container if one is required */
   init?(): Promise<void>;
@@ -34,23 +46,21 @@ export interface StateStore {
   delete(key: string): Promise<void>;
 }
 
-const stateFile = path.join(process.cwd(), ".alchemy");
-
-export type StateStoreType = new (dir: string) => StateStore;
+const stateRootDir = path.join(process.cwd(), ".alchemy");
 
 export class FileSystemStateStore implements StateStore {
-  public readonly path: string;
-  constructor(dir: string) {
-    this.path = path.join(stateFile, dir);
+  public readonly dir: string;
+  constructor(public readonly scope: Scope) {
+    this.dir = path.join(stateRootDir, ...scope.chain);
   }
 
   async init(): Promise<void> {
-    await fs.promises.mkdir(stateFile, { recursive: true });
-    await fs.promises.mkdir(this.path, { recursive: true });
+    await fs.promises.mkdir(stateRootDir, { recursive: true });
+    await fs.promises.mkdir(this.dir, { recursive: true });
   }
 
   async deinit(): Promise<void> {
-    await ignore("ENOENT", () => fs.promises.rmdir(this.path));
+    await ignore("ENOENT", () => fs.promises.rmdir(this.dir));
   }
 
   async count(): Promise<number> {
@@ -59,7 +69,7 @@ export class FileSystemStateStore implements StateStore {
 
   async list(): Promise<string[]> {
     try {
-      const files = await fs.promises.readdir(this.path, {
+      const files = await fs.promises.readdir(this.dir, {
         withFileTypes: true,
       });
       return files
@@ -79,7 +89,7 @@ export class FileSystemStateStore implements StateStore {
         await this.getPath(key),
         "utf8",
       );
-      return JSON.parse(content) as State;
+      return (await deserialize(this.scope, JSON.parse(content))) as State;
     } catch (error: any) {
       if (error.code === "ENOENT") {
         return undefined;
@@ -91,7 +101,7 @@ export class FileSystemStateStore implements StateStore {
   async set(key: string, value: State): Promise<void> {
     return fs.promises.writeFile(
       await this.getPath(key),
-      JSON.stringify(value, null, 2),
+      JSON.stringify(await serialize(this.scope, value), null, 2),
     );
   }
 
@@ -120,7 +130,7 @@ export class FileSystemStateStore implements StateStore {
   }
 
   private async getPath(key: string): Promise<string> {
-    const file = path.join(this.path, `${key}.json`);
+    const file = path.join(this.dir, `${key}.json`);
     const dir = path.dirname(file);
     await fs.promises.mkdir(dir, { recursive: true });
     return file;

package/src/stripe/price.ts

@@ -1,5 +1,5 @@
 import Stripe from "stripe";
-import type { Context } from "../resource";
+import type { Context } from "../context";
 import { Resource } from "../resource";
 
 /**
@@ -98,7 +98,7 @@ export interface PriceProps {
 /**
  * Output from the Stripe price
  */
-export interface PriceOutput extends PriceProps {
+export interface Price extends Resource<"stripe::Price">, PriceProps {
   /**
    * The ID of the price
    */
@@ -125,9 +125,13 @@ export interface PriceOutput extends PriceProps {
   lookupKey?: string;
 }
 
-export class Price extends Resource(
+export const Price = Resource(
   "stripe::Price",
-  async (ctx: Context<PriceOutput>, props: PriceProps) => {
+  async function (
+    this: Context<Price>,
+    id: string,
+    props: PriceProps,
+  ): Promise<Price> {
     // Get Stripe API key from context or environment
     const apiKey = process.env.STRIPE_API_KEY;
     if (!apiKey) {
@@ -137,32 +141,25 @@ export class Price extends Resource(
     // Initialize Stripe client
     const stripe = new Stripe(apiKey);
 
-    if (ctx.event === "delete") {
+    if (this.phase === "delete") {
       try {
-        if (ctx.event === "delete" && ctx.output?.id) {
+        if (this.phase === "delete" && this.output?.id) {
           // Prices can't be deleted, only deactivated
-          await stripe.prices.update(ctx.output.id, { active: false });
+          await stripe.prices.update(this.output.id, { active: false });
         }
       } catch (error) {
         // Ignore if the price doesn't exist
         console.error("Error deactivating price:", error);
       }
 
-      // Return a minimal output for deleted state
-      return {
-        ...props,
-        id: "",
-        createdAt: 0,
-        livemode: false,
-        type: (props.recurring ? "recurring" : "one_time") as Stripe.Price.Type,
-      };
+      return this.destroy();
     } else {
       try {
         let price: Stripe.Price;
 
-        if (ctx.event === "update" && ctx.output?.id) {
+        if (this.phase === "update" && this.output?.id) {
           // Update existing price (limited properties can be updated)
-          price = await stripe.prices.update(ctx.output.id, {
+          price = await stripe.prices.update(this.output.id, {
             active: props.active,
             metadata: props.metadata,
             nickname: props.nickname,
@@ -213,7 +210,7 @@ export class Price extends Resource(
           : undefined;
 
         // Map Stripe API response to our output format
-        const output: PriceOutput = {
+        return this({
           id: price.id,
           product:
             typeof price.product === "string"
@@ -232,13 +229,11 @@ export class Price extends Resource(
           livemode: price.livemode,
           type: price.type as Stripe.Price.Type,
           lookupKey: price.lookup_key || undefined,
-        };
-
-        return output;
+        });
       } catch (error) {
         console.error("Error creating/updating price:", error);
         throw error;
       }
     }
   },
-) {}
+);

package/src/stripe/product.ts

@@ -1,5 +1,5 @@
 import Stripe from "stripe";
-import type { Context } from "../resource";
+import type { Context } from "../context";
 import { Resource } from "../resource";
 
 type ProductType = Stripe.Product.Type;
@@ -67,7 +67,7 @@ export interface ProductProps {
 /**
  * Output from the Stripe product
  */
-export interface ProductOutput extends ProductProps {
+export interface Product extends Resource<"stripe::Product">, ProductProps {
   /**
    * The ID of the product
    */
@@ -99,9 +99,13 @@ export interface ProductOutput extends ProductProps {
   };
 }
 
-export class Product extends Resource(
+export const Product = Resource(
   "stripe::Product",
-  async (ctx: Context<ProductOutput>, props: ProductProps) => {
+  async function (
+    this: Context<Product>,
+    id: string,
+    props: ProductProps,
+  ): Promise<Product> {
     // Get Stripe API key from context or environment
     const apiKey = process.env.STRIPE_API_KEY;
     if (!apiKey) {
@@ -111,10 +115,10 @@ export class Product extends Resource(
     // Initialize Stripe client
     const stripe = new Stripe(apiKey);
 
-    if (ctx.event === "delete") {
+    if (this.phase === "delete") {
       try {
-        if (ctx.event === "delete" && ctx.output?.id) {
-          await stripe.products.update(ctx.output.id, { active: false });
+        if (this.phase === "delete" && this.output?.id) {
+          await stripe.products.update(this.output.id, { active: false });
         }
       } catch (error) {
         // Ignore if the product doesn't exist
@@ -122,20 +126,14 @@ export class Product extends Resource(
       }
 
       // Return a minimal output for deleted state
-      return {
-        ...props,
-        id: "",
-        createdAt: 0,
-        updatedAt: 0,
-        livemode: false,
-      };
+      return this.destroy();
     } else {
       try {
         let product: Stripe.Product;
 
-        if (ctx.event === "update" && ctx.output?.id) {
+        if (this.phase === "update" && this.output?.id) {
           // Update existing product
-          product = await stripe.products.update(ctx.output.id, {
+          product = await stripe.products.update(this.output.id, {
             name: props.name,
             description: props.description,
             active: props.active,
@@ -162,8 +160,7 @@ export class Product extends Resource(
           });
         }
 
-        // Map Stripe API response to our output format
-        const output: ProductOutput = {
+        return this({
           id: product.id,
           name: product.name,
           description: product.description || undefined,
@@ -181,13 +178,11 @@ export class Product extends Resource(
           livemode: product.livemode,
           updatedAt: product.updated,
           packageDimensions: product.package_dimensions || undefined,
-        };
-
-        return output;
+        });
       } catch (error) {
         console.error("Error creating/updating product:", error);
         throw error;
       }
     }
   },
-) {}
+);

package/src/stripe/webhook.ts

@@ -1,5 +1,5 @@
 import Stripe from "stripe";
-import type { Context } from "../resource";
+import type { Context } from "../context";
 import { Resource } from "../resource";
 
 export type EnabledEvent = Stripe.WebhookEndpointUpdateParams.EnabledEvent;
@@ -47,7 +47,9 @@ export interface WebhookEndpointProps {
 /**
  * Output from the Stripe webhook endpoint
  */
-export interface WebhookEndpointOutput extends WebhookEndpointProps {
+export interface WebhookEndpoint
+  extends Resource<"stripe::WebhookEndpoint">,
+    WebhookEndpointProps {
   /**
    * The ID of the webhook
    */
@@ -84,9 +86,13 @@ export interface WebhookEndpointOutput extends WebhookEndpointProps {
   status: string;
 }
 
-export class WebhookEndpoint extends Resource(
+export const WebhookEndpoint = Resource(
   "stripe::WebhookEndpoint",
-  async (ctx: Context<WebhookEndpointOutput>, props: WebhookEndpointProps) => {
+  async function (
+    this: Context<WebhookEndpoint>,
+    id: string,
+    props: WebhookEndpointProps,
+  ) {
     // Get Stripe API key from context or environment
     const apiKey = process.env.STRIPE_API_KEY;
     if (!apiKey) {
@@ -96,34 +102,25 @@ export class WebhookEndpoint extends Resource(
     // Initialize Stripe client
     const stripe = new Stripe(apiKey);
 
-    if (ctx.event === "delete") {
+    if (this.phase === "delete") {
       try {
         // Get the webhook ID from the stored output
-        if (ctx.event === "delete" && ctx.output?.id) {
-          await stripe.webhookEndpoints.del(ctx.output.id);
+        if (this.phase === "delete" && this.output?.id) {
+          await stripe.webhookEndpoints.del(this.output.id);
         }
       } catch (error) {
         // Ignore if the webhook doesn't exist
         console.error("Error deleting webhook:", error);
       }
 
-      // Return a minimal output for deleted state
-      return {
-        ...props,
-        id: "",
-        secret: "",
-        createdAt: 0,
-        updatedAt: 0,
-        livemode: false,
-        status: "deleted",
-      };
+      return this.destroy();
     } else {
       try {
         let webhook: Stripe.WebhookEndpoint;
 
-        if (ctx.event === "update" && ctx.output?.id) {
+        if (this.phase === "update" && this.output?.id) {
           // Update existing webhook
-          webhook = await stripe.webhookEndpoints.update(ctx.output.id, {
+          webhook = await stripe.webhookEndpoints.update(this.output.id, {
             url: props.url,
             enabled_events: props.enabledEvents,
             description: props.description,
@@ -152,12 +149,11 @@ export class WebhookEndpoint extends Resource(
         let secret = "";
         if (webhook.secret) {
           secret = webhook.secret;
-        } else if (ctx.event === "update" && ctx.output?.secret) {
-          secret = ctx.output.secret;
+        } else if (this.phase === "update" && this.output?.secret) {
+          secret = this.output.secret;
         }
 
-        // Map Stripe API response to our output format
-        const output: WebhookEndpointOutput = {
+        return this({
           id: webhook.id,
           url: webhook.url,
           enabledEvents: webhook.enabled_events as EnabledEvent[],
@@ -172,13 +168,11 @@ export class WebhookEndpoint extends Resource(
           livemode: webhook.livemode,
           updatedAt: webhook.created, // Using created timestamp as updated
           status: webhook.status,
-        };
-
-        return output;
+        });
       } catch (error) {
         console.error("Error creating/updating webhook:", error);
         throw error;
       }
     }
   },
-) {}
+);

package/src/test/bun.ts

@@ -0,0 +1,105 @@
+/// <reference types="bun" />
+
+import { afterAll, it } from "bun:test";
+import path from "node:path";
+import { alchemy } from "../alchemy";
+import { destroy } from "../destroy";
+import type { Scope } from "../scope";
+
+declare module "../alchemy" {
+  interface Alchemy {
+    test: typeof test;
+  }
+}
+
+alchemy.test = test;
+
+export interface TestOptions {
+  destroy?: boolean;
+  quiet?: boolean;
+  password?: string;
+}
+
+const globalTestScope = alchemy.scope("test");
+
+type test = {
+  (name: string, fn: (scope: Scope) => Promise<any>, timeout?: number): void;
+  (
+    name: string,
+    options: TestOptions,
+    fn: (scope: Scope) => Promise<any>,
+    timeout?: number,
+  ): void;
+  skipIf(condition: boolean): test;
+  scope: Scope;
+};
+
+export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
+  test.skipIf = (condition: boolean) => {
+    if (condition) {
+      // TODO: proxy through to bun:test.skipIf
+      return (...args: any[]) => {};
+    }
+    return test;
+  };
+
+  const localTestScope = alchemy.scope(path.basename(meta.filename), {
+    parent: globalTestScope,
+  });
+  test.scope = localTestScope;
+
+  afterAll(() => alchemy.destroy(test.scope));
+
+  return test as any;
+
+  function test(
+    ...args:
+      | [
+          name: string,
+          options: TestOptions,
+          fn: (scope: Scope) => Promise<void>,
+        ]
+      | [name: string, fn: (scope: Scope) => Promise<void>]
+  ) {
+    const testName = args[0];
+    const _options = typeof args[1] === "object" ? args[1] : undefined;
+    const spread = (obj: any) =>
+      obj && typeof obj === "object"
+        ? Object.fromEntries(
+            Object.entries(obj).flatMap(([k, v]) =>
+              v !== undefined ? [[k, v]] : [],
+            ),
+          )
+        : {};
+    const options = {
+      destroy: false,
+      quiet: false,
+      password: "test-password",
+      ...spread(defaultOptions),
+      ...spread(_options),
+    };
+    const fn = typeof args[1] === "function" ? args[1] : args[2]!;
+
+    return alchemy.run(
+      testName,
+      {
+        ...options,
+        parent: localTestScope,
+      },
+      async (scope) => {
+        return it(testName, async () => {
+          // bun will call from a different scope, so we need to enter the test's scope manually
+          scope.enter();
+          try {
+            await fn(scope);
+          } finally {
+            if (options.destroy !== false) {
+              // TODO: auto-destroy resources
+              await destroy(scope);
+            }
+          }
+        });
+      },
+    );
+  }
+}