alchemy 0.1.2 → 0.1.3

package/src/output.ts

@@ -1,5 +1,11 @@
 export type Eval<U> = U extends Output<infer V> ? Eval<V> : U;
 
+export function isOutput<T>(value: any): value is Output<T> {
+  return (
+    value && typeof value === "object" && typeof value.apply === "function"
+  );
+}
+
 export type Outputs<P extends readonly any[]> = P extends [
   infer First,
   ...infer Rest,

package/src/resource.ts

@@ -1,6 +1,10 @@
-import { deletions, nodes, providers } from "./global";
-import type { Inputs } from "./input";
+import { alchemize } from "./alchemize";
+import { type ApplyOptions, apply } from "./apply";
+import type { DestroyOptions } from "./destroy";
+import { defaultStateStore, deletions, providers } from "./global";
+import type { Inputs, Input as input } from "./input";
 import { Output } from "./output";
+import { Scope as IScope, getScope, pushScope } from "./scope";
 import type { State, StateStore } from "./state";
 
 export type ResourceID = string;
@@ -12,6 +16,8 @@ export const Input = Symbol.for("Input");
 export const Value = Symbol.for("Value");
 export const Apply = Symbol.for("Apply");
 export const Provide = Symbol.for("Provide");
+export const Scope = Symbol.for("Scope");
+export const Options = Symbol.for("Options");
 
 // properties that pierce through the Proxy
 const OrthogonalProperties = [
@@ -21,8 +27,17 @@ const OrthogonalProperties = [
   Value,
   Apply,
   Provide,
+  Scope,
+  Options,
 ] as const;
 
+export interface ProviderOptions {
+  /**
+   * If true, the resource will be updated even if the inputs have not changed.
+   */
+  alwaysUpdate: boolean;
+}
+
 export type Resource<In extends any[] = any[], Out = any> = {
   [ResourceID]: string;
   [Provider]: Provider<any, any[], any>;
@@ -30,11 +45,14 @@ export type Resource<In extends any[] = any[], Out = any> = {
   [Value]?: Out;
   [Apply]: <O>(value: Out) => O;
   [Provide]: (value: Out) => void;
+  [Options]: ProviderOptions;
 } & Output<Out>;
 
-export type Context<Outputs> = {
+export interface BaseContext {
+  quiet: boolean;
   stage: string;
   resourceID: ResourceID;
+  scope: IScope;
   get<T>(key: string): Promise<T | undefined>;
   set<T>(key: string, value: T): Promise<void>;
   delete<T>(key: string): Promise<T | undefined>;
@@ -43,15 +61,26 @@ export type Context<Outputs> = {
    * This will cause the resource to be deleted at the end of the stack's CREATE phase.
    */
   replace(): void;
-} & (
-  | {
-      event: "create";
-    }
-  | {
-      event: "update" | "delete";
-      output: Outputs;
-    }
-);
+}
+
+export interface CreateContext extends BaseContext {
+  event: "create";
+}
+
+export interface UpdateContext<Outputs> extends BaseContext {
+  event: "update";
+  output: Outputs;
+}
+
+export interface DeleteContext<Outputs> extends BaseContext {
+  event: "delete";
+  output: Outputs;
+}
+
+export type Context<Outputs> =
+  | CreateContext
+  | UpdateContext<Outputs>
+  | DeleteContext<Outputs>;
 
 export type Provider<
   Type extends ResourceType = ResourceType,
@@ -65,16 +94,19 @@ export type Provider<
     deps: Set<ResourceID>,
     inputs: Inputs<In>,
     stateStore: StateStore,
+    options: ApplyOptions,
   ): Promise<Awaited<Out>>;
   delete(
     stage: string,
+    scope: IScope | undefined,
     resourceID: ResourceID,
     state: State,
     inputs: Inputs<In>,
+    options: DestroyOptions,
   ): Promise<void>;
 } & (new (
   id: string,
-  ...inputs: Inputs<In>
+  ...inputs: [...Inputs<In>, ...any[]]
 ) => Resource<In, Out>);
 
 export function isResource(value: any): value is Resource {
@@ -87,41 +119,88 @@ export function Resource<
   Out,
 >(
   type: Type,
-  func: (ctx: Context<Out>, ...args: Args) => Promise<Out | void> | Out | void,
+  options: Partial<ProviderOptions>,
+  func: (
+    ctx: Context<Out>,
+    ...args: Args
+  ) => Promise<input<Out> | void> | input<Out> | void,
+): Provider<Type, Args, Awaited<Out>>;
+
+export function Resource<
+  const Type extends ResourceType,
+  Args extends any[],
+  Out,
+>(
+  type: Type,
+  func: (
+    ctx: Context<Out>,
+    ...args: Args
+  ) => Promise<input<Out> | void> | input<Out> | void,
+): Provider<Type, Args, Awaited<Out>>;
+
+export function Resource<
+  const Type extends ResourceType,
+  Args extends any[],
+  Out,
+>(
+  type: Type,
+  ...args:
+    | [
+        Partial<ProviderOptions>,
+        (
+          ctx: Context<Out>,
+          ...args: Args
+        ) => Promise<input<Out> | void> | input<Out> | void,
+      ]
+    | [
+        (
+          ctx: Context<Out>,
+          ...args: Args
+        ) => Promise<input<Out> | void> | input<Out> | void,
+      ]
 ): Provider<Type, Args, Awaited<Out>> {
   if (providers.has(type)) {
     throw new Error(`Resource ${type} already exists`);
   }
+  const [options, func] = args.length === 2 ? args : [undefined, args[0]];
 
   interface Resource {
     [ResourceID]: ResourceID;
     [Provider]: Provider<Type, Args, Out>;
     [Input]: Inputs<Args>;
     [Value]?: Out;
+    [Scope]: IScope;
+    [Options]: ProviderOptions;
   }
 
   class Resource {
     static readonly type = type;
 
     constructor(id: ResourceID, ...input: Inputs<Args>) {
+      const scope = getScope();
       const node = {
         provider: Resource,
         resource: this,
       } as const;
-      if (nodes.has(id)) {
+
+      if (scope.nodes.has(id)) {
         // TODO(sam): do we want to throw?
         // it's kind of awesome that you can re-create a resource and call apply
         // console.warn(`Resource ${id} already exists in the stack: ${stack.id}`);
       }
-      nodes.set(id, node as any);
+      scope.nodes.set(id, node as any);
 
       this[ResourceID] = id;
       this[Provider] = Resource as any;
       this[Input] = input;
       this[Value] = undefined;
+      this[Scope] = scope;
       this[Provide] = (value: Out) => {
         this[Value] = value;
       };
+      this[Options] = {
+        alwaysUpdate: options?.alwaysUpdate ?? false,
+      };
 
       return new Proxy(this, {
         // TODO(sam): this won't work for the sub-class (class Table extends Resource)
@@ -175,14 +254,12 @@ export function Resource<
       deps: Set<ResourceID>,
       inputs: Args,
       stateStore: StateStore,
+      options: ApplyOptions,
     ): Promise<Awaited<Out | void>> {
       // const stack = resource[ResourceStack];
       const resourceID = resource[ResourceID];
 
-      let resourceState: State | undefined = await stateStore.get(
-        stage,
-        resourceID,
-      );
+      let resourceState: State | undefined = await stateStore.get(resourceID);
       if (resourceState === undefined) {
         resourceState = {
           provider: type,
@@ -192,20 +269,28 @@ export function Resource<
           deps: [...deps],
           inputs,
         };
-        await stateStore.set(stage, resourceID, resourceState);
+        await stateStore.set(resourceID, resourceState);
       }
 
+      const resourceFQN = `${resource[Scope].getScopePath(stage)}/${resourceID}`;
+
       // Skip update if inputs haven't changed and resource is in a stable state
       if (
-        (resourceState.status === "created" ||
-          resourceState.status === "updated") &&
-        JSON.stringify(resourceState.inputs) === JSON.stringify(inputs)
+        resourceState.status === "created" ||
+        resourceState.status === "updated"
       ) {
-        console.log(`Skip:    ${resourceID} (no changes)`);
-        if (resourceState.output !== undefined) {
-          resource[Provide](resourceState.output);
+        if (
+          JSON.stringify(resourceState.inputs) === JSON.stringify(inputs) &&
+          !resource[Options].alwaysUpdate
+        ) {
+          if (!options?.quiet) {
+            console.log(`Skip:    ${resourceFQN} (no changes)`);
+          }
+          if (resourceState.output !== undefined) {
+            resource[Provide](resourceState.output);
+          }
+          return resourceState.output;
         }
-        return resourceState.output;
       }
 
       const event = resourceState.status === "creating" ? "create" : "update";
@@ -213,78 +298,122 @@ export function Resource<
       resourceState.oldInputs = resourceState.inputs;
       resourceState.inputs = inputs;
 
-      console.log(
-        `${event === "create" ? "Create" : "Update"}:  ${resourceID}`,
-      );
+      if (!options?.quiet) {
+        console.log(
+          `${event === "create" ? "Create" : "Update"}:  ${resourceFQN}`,
+        );
+      }
 
-      await stateStore.set(stage, resourceID, resourceState);
+      await stateStore.set(resourceID, resourceState);
 
       let isReplaced = false;
 
-      const result = await func(
-        {
-          stage,
-          resourceID,
-          event,
-          output: resourceState.output,
-          replace: () => {
-            if (isReplaced) {
-              console.warn(
-                `Resource ${type} ${resourceID} is already marked as REPLACE`,
-              );
-              return;
-            }
-            isReplaced = true;
-            deletions.push({
-              id: resourceID,
-              data: {
-                ...resourceState!.data,
+      const quiet = options.quiet ?? false;
+
+      const evaluated = await pushScope(
+        resource[Scope],
+        resourceID,
+        async () => {
+          const result = await func(
+            {
+              stage,
+              resourceID,
+              event,
+              scope: getScope(),
+              output: resourceState.output,
+              replace: () => {
+                if (isReplaced) {
+                  console.warn(
+                    `Resource ${type} ${resourceFQN} is already marked as REPLACE`,
+                  );
+                  return;
+                }
+                isReplaced = true;
+                deletions.push({
+                  id: resourceID,
+                  data: {
+                    ...resourceState!.data,
+                  },
+                  inputs: inputs,
+                });
               },
-              inputs: inputs,
-            });
-          },
-          get: (key) => resourceState!.data[key],
-          set: async (key, value) => {
-            resourceState!.data[key] = value;
-            await stateStore.set(stage, resourceID, resourceState!);
-          },
-          delete: async (key) => {
-            const value = resourceState!.data[key];
-            delete resourceState!.data[key];
-            await stateStore.set(stage, resourceID, resourceState!);
-            return value;
-          },
+              get: (key) => resourceState!.data[key],
+              set: async (key, value) => {
+                resourceState!.data[key] = value;
+                await stateStore.set(resourceID, resourceState!);
+              },
+              delete: async (key) => {
+                const value = resourceState!.data[key];
+                delete resourceState!.data[key];
+                await stateStore.set(resourceID, resourceState!);
+                return value;
+              },
+              quiet,
+            },
+            ...inputs,
+          );
+
+          if (result === undefined) {
+            return undefined;
+          }
+
+          const evaluated = await apply(result as Out, {
+            stage,
+            scope: getScope(),
+            quiet,
+          });
+
+          return evaluated;
         },
-        ...inputs,
       );
 
-      console.log(
-        `${event === "create" ? "Created" : "Updated"}: ${resourceID}`,
-      );
-      await stateStore.set(stage, resourceID, {
+      if (!options?.quiet) {
+        console.log(
+          `${event === "create" ? "Created" : "Updated"}: ${resourceFQN}`,
+        );
+      }
+      await stateStore.set(resourceID, {
         provider: type,
         data: resourceState.data,
         status: event === "create" ? "created" : "updated",
-        output: result,
+        output: evaluated,
         inputs,
         deps: [...deps],
       });
-      if (result !== undefined) {
-        resource[Provide](result);
+      if (evaluated !== undefined) {
+        resource[Provide](evaluated);
       }
-      return result;
+      return evaluated;
     }
 
     static async delete(
       stage: string,
+      scope: IScope,
       resourceID: ResourceID,
       state: State,
       inputs: Args,
+      options: DestroyOptions,
     ) {
-      console.log(`Delete:  ${resourceID}`);
+      const resourceFQN = `${scope.getScopePath(stage)}/${resourceID}`;
+      const nestedScope = new IScope(resourceID, scope);
+
+      await alchemize({
+        mode: "destroy",
+        stage,
+        scope: nestedScope,
+        // TODO(sam): should use the appropriate state store
+        stateStore: defaultStateStore,
+        quiet: options.quiet,
+      });
+
+      if (!options?.quiet) {
+        console.log(`Delete:  ${resourceFQN}`);
+      }
+
       await func(
         {
           stage,
+          scope,
           resourceID: resourceID,
           event: "delete",
           output: state.output,
@@ -302,10 +431,14 @@ export function Resource<
             delete state.data[key];
             return value;
           },
+          quiet: options.quiet ?? false,
         },
         ...inputs,
       );
-      console.log(`Deleted: ${resourceID}`);
+
+      if (!options?.quiet) {
+        console.log(`Deleted: ${resourceFQN}`);
+      }
     }
   }
   providers.set(type, Resource as any);

package/src/scope.ts

@@ -0,0 +1,56 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { rootScope } from "./global";
+import type { Provider, Resource, ResourceID } from "./resource";
+
+const scopeGlobal = new Map<string | null, Scope>();
+
+const scopeStorage = new AsyncLocalStorage<Scope>();
+
+export class Scope {
+  public readonly nodes = new Map<
+    ResourceID,
+    {
+      provider: Provider<any, any[], any>;
+      resource: Resource<any, any>;
+    }
+  >();
+
+  constructor(
+    public readonly scopeName: string | null = null,
+    public readonly parent: Scope | undefined = undefined,
+  ) {}
+
+  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;
+  }
+}
+
+export function getScope(): Scope {
+  return scopeStorage.getStore() ?? rootScope;
+}
+
+export function withScope<T>(
+  scope: Scope,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  return scopeStorage.run(scope, async () => {
+    try {
+      return await fn();
+    } catch (error) {
+      throw error;
+    }
+  });
+}
+
+export function pushScope<T>(
+  parent: Scope,
+  scopeName: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  const newScope = new Scope(scopeName, parent);
+  return withScope(newScope, fn);
+}

package/src/slug.ts

@@ -0,0 +1,3 @@
+export function slugify(str: string) {
+  return str.replaceAll("/", "_");
+}

package/src/state.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { ignore } from "./error";
 
 export interface State {
   status:
@@ -18,41 +19,64 @@ export interface State {
 }
 
 export interface StateStore {
+  /** Initialize the state container if one is required */
   init?(): Promise<void>;
+  /** Delete the state container if one exists */
+  deinit?(): Promise<void>;
   /** List all resources in the given stage. */
-  list(stage: string): Promise<string[]>;
-  get(stage: string, key: string): Promise<State | undefined>;
-  getBatch(stage: string, ids: string[]): Promise<Record<string, State>>;
-  all(stage: string): Promise<Record<string, State>>;
-  set(stage: string, key: string, value: State): Promise<void>;
-  delete(stage: string, key: string): Promise<void>;
+  list(): Promise<string[]>;
+  /** Return the number of items let in this store */
+  count(): Promise<number>;
+  get(key: string): Promise<State | undefined>;
+  getBatch(ids: string[]): Promise<Record<string, State>>;
+  all(): Promise<Record<string, State>>;
+  set(key: string, value: State): Promise<void>;
+  delete(key: string): Promise<void>;
 }
 
 const stateFile = path.join(process.cwd(), ".alchemy");
 
-/**
- * @internal
- */
-export const defaultStore: StateStore = {
-  async init() {
+export type StateStoreType = new (dir: string) => StateStore;
+
+export class FileSystemStateStore implements StateStore {
+  public readonly path: string;
+  constructor(dir: string) {
+    this.path = path.join(stateFile, dir);
+  }
+
+  async init(): Promise<void> {
     await fs.promises.mkdir(stateFile, { recursive: true });
-  },
-  async list(stage) {
+    await fs.promises.mkdir(this.path, { recursive: true });
+  }
+
+  async deinit(): Promise<void> {
+    await ignore("ENOENT", () => fs.promises.rmdir(this.path));
+  }
+
+  async count(): Promise<number> {
+    return Object.keys(await this.list()).length;
+  }
+
+  async list(): Promise<string[]> {
     try {
-      return (await fs.promises.readdir(path.join(stateFile, stage))).map(
-        (file) => file.replace(/\.json$/, ""),
-      );
+      const files = await fs.promises.readdir(this.path, {
+        withFileTypes: true,
+      });
+      return files
+        .filter((dirent) => dirent.isFile() && dirent.name.endsWith(".json"))
+        .map((dirent) => dirent.name.replace(/\.json$/, ""));
     } catch (error: any) {
       if (error.code === "ENOENT") {
         return [];
       }
       throw error;
     }
-  },
-  async get(stage, key) {
+  }
+
+  async get(key: string): Promise<State | undefined> {
     try {
       const content = await fs.promises.readFile(
-        await getPath(stage, key),
+        await this.getPath(key),
         "utf8",
       );
       return JSON.parse(content) as State;
@@ -62,25 +86,29 @@ export const defaultStore: StateStore = {
       }
       throw error;
     }
-  },
-  async set(stage, key, value) {
+  }
+
+  async set(key: string, value: State): Promise<void> {
     return fs.promises.writeFile(
-      await getPath(stage, key),
+      await this.getPath(key),
       JSON.stringify(value, null, 2),
     );
-  },
-  async delete(stage, key) {
-    return fs.promises.unlink(await getPath(stage, key));
-  },
-  async all(stage: string): Promise<Record<string, State>> {
-    return this.getBatch(stage, await this.list(stage));
-  },
-  async getBatch(stage: string, ids: string[]): Promise<Record<string, State>> {
+  }
+
+  async delete(key: string): Promise<void> {
+    return fs.promises.unlink(await this.getPath(key));
+  }
+
+  async all(): Promise<Record<string, State>> {
+    return this.getBatch(await this.list());
+  }
+
+  async getBatch(ids: string[]): Promise<Record<string, State>> {
     return Object.fromEntries(
       (
         await Promise.all(
           Array.from(ids).flatMap(async (id) => {
-            const s = await this.get(stage, id);
+            const s = await this.get(id);
             if (s === undefined) {
               return [] as const;
             }
@@ -89,12 +117,12 @@ export const defaultStore: StateStore = {
         )
       ).flat(),
     );
-  },
-};
+  }
 
-async function getPath(stage: string, key: string) {
-  const file = path.join(stateFile, stage, `${key}.json`);
-  const dir = path.dirname(file);
-  await fs.promises.mkdir(dir, { recursive: true });
-  return file;
+  private async getPath(key: string): Promise<string> {
+    const file = path.join(this.path, `${key}.json`);
+    const dir = path.dirname(file);
+    await fs.promises.mkdir(dir, { recursive: true });
+    return file;
+  }
 }