@terraforge/core 0.0.5 → 0.0.7

package/README.md

@@ -12,7 +12,7 @@ The most used IaC solutions are slow & don't effectively leverage diffing to spe
 Install with (NPM):
 
 ```
-npm i @terraforge/core @terraforge/aws
+npm i @terraforge/core @terraforge/terraform @terraforge/aws
 ```
 
 ## Example
@@ -52,12 +52,12 @@ This example illustrates how simple it is to define multi-stack resources withou
 ```ts
 const app = new App('todo-app')
 const storage = new Stack(app, 'storage')
-const list = new aws.s3.Bucket(storage, 'list', {
+const list = new aws.s3.Bucket(storage, 'todo-list', {
 	bucket: 'your-bucket-name'
 })
 
 const items = new Stack(app, 'items')
-const todo = new aws.s3.BucketObject(items, 'item', {
+const todo = new aws.s3.BucketObject(items, 'todo-item', {
 	bucket: list.bucket,
 	key: 'item-1',
 	content: JSON.stringify({

package/dist/index.d.ts

@@ -42,7 +42,7 @@ declare const interpolate: (literals: TemplateStringsArray, ...placeholders: Inp
 type URN = `urn:${string}`;
 
 declare const nodeMetaSymbol: unique symbol;
-type Node<T extends Tag = Tag, I extends State = State, O extends State = any, C extends Config = Config> = {
+type Node<T extends Tag = Tag, I extends State = State, O extends State = State, C extends Config = Config> = {
     readonly [nodeMetaSymbol]: Meta<T, I, O, C>;
     readonly urn: URN;
 } & O;
@@ -58,12 +58,13 @@ declare const isDataSource: (obj: object) => obj is DataSource;
 type ResourceConfig = Config & {
     /** Import an existing resource instead of creating a new resource. */
     import?: string;
-    /** If true the resource will be retained in the backing cloud provider during a Pulumi delete operation. */
+    /** If true the resource will be retained in the backing cloud provider during a delete operation. */
     retainOnDelete?: boolean;
-    /** Override the default create-after-delete behavior when replacing a resource. */
     /** If set, the provider’s Delete method will not be called for this resource if the specified resource is being deleted as well. */
     /** Declare that changes to certain properties should be treated as forcing a replacement. */
     replaceOnChanges?: string[];
+    /** If true, create the replacement before deleting the existing resource. */
+    createBeforeReplace?: boolean;
 };
 type ResourceMeta<I extends State = State, O extends State = State> = Meta<'resource', I, O, ResourceConfig>;
 type Resource<I extends State = State, O extends State = State> = O & {
@@ -187,6 +188,11 @@ type DeleteProps<T = State> = {
     state: T;
     idempotantToken?: string;
 };
+type PlanProps<T = State> = {
+    type: string;
+    priorState: T;
+    proposedState: T;
+};
 type GetProps<T = State> = {
     type: string;
     state: T;
@@ -210,12 +216,60 @@ interface Provider {
         state: State;
     }>;
     deleteResource(props: DeleteProps): Promise<void>;
+    planResourceChange?(props: PlanProps): Promise<{
+        version: number;
+        state: State;
+        requiresReplacement: boolean;
+    }>;
     getData?(props: GetDataProps): Promise<{
         state: State;
     }>;
     destroy?(): Promise<void>;
 }
 
+type ResourceEvent = {
+    urn: URN;
+    type: string;
+};
+type BeforeResourceCreateEvent = ResourceEvent & {
+    resource: Resource;
+    newInput: State;
+};
+type AfterResourceCreateEvent = ResourceEvent & {
+    resource: Resource;
+    newInput: State;
+    newOutput: State;
+};
+type BeforeResourceUpdateEvent = ResourceEvent & {
+    resource: Resource;
+    oldInput: State;
+    newInput: State;
+    oldOutput: State;
+};
+type AfterResourceUpdateEvent = ResourceEvent & {
+    resource: Resource;
+    oldInput: State;
+    newInput: State;
+    oldOutput: State;
+    newOutput: State;
+};
+type BeforeResourceDeleteEvent = ResourceEvent & {
+    oldInput: State;
+    oldOutput: State;
+};
+type AfterResourceDeleteEvent = ResourceEvent & {
+    oldInput: State;
+    oldOutput: State;
+};
+type Hooks = {
+    beforeResourceCreate?: (event: BeforeResourceCreateEvent) => Promise<void> | void;
+    beforeResourceUpdate?: (event: BeforeResourceUpdateEvent) => Promise<void> | void;
+    beforeResourceDelete?: (event: BeforeResourceDeleteEvent) => Promise<void> | void;
+    afterResourceCreate?: (event: AfterResourceCreateEvent) => Promise<void> | void;
+    afterResourceUpdate?: (event: AfterResourceUpdateEvent) => Promise<void> | void;
+    afterResourceDelete?: (event: AfterResourceDeleteEvent) => Promise<void> | void;
+};
+
 type ProcedureOptions = {
     filters?: string[];
     idempotentToken?: UUID;
@@ -227,6 +281,7 @@ type WorkSpaceOptions = {
         state: StateBackend;
         lock: LockBackend;
     };
+    hooks?: Hooks;
 };
 declare class WorkSpace {
     protected props: WorkSpaceOptions;
@@ -356,7 +411,11 @@ type CustomResourceProvider = Partial<{
     createResource?(props: Omit<CreateProps, 'type'>): Promise<State>;
     deleteResource?(props: Omit<DeleteProps, 'type'>): Promise<void>;
     getData?(props: Omit<GetDataProps, 'type'>): Promise<State>;
+    planResourceChange?(props: Omit<PlanProps, 'type'>): Promise<{
+        state: State;
+        requiresReplacement: boolean;
+    }>;
 }>;
 declare const createCustomProvider: (providerId: string, resourceProviders: Record<string, CustomResourceProvider>) => Provider;
 
-export { App, AppError, type Config, type CreateProps, type CustomResourceProvider, type DataSource, type DataSourceFunction, type DataSourceMeta, type DeleteProps, DynamoLockBackend, FileLockBackend, FileStateBackend, Future, type GetDataProps, type GetProps, Group, type Input, type LockBackend, MemoryLockBackend, MemoryStateBackend, type Meta, type Node, type OptionalInput, type OptionalOutput, Output, type ProcedureOptions, type Provider, type Resource, ResourceAlreadyExists, type ResourceClass, type ResourceConfig, ResourceError, type ResourceMeta, ResourceNotFound, S3StateBackend, Stack, type State, type StateBackend, type Tag, type URN, type UpdateProps, WorkSpace, type WorkSpaceOptions, createCustomProvider, createCustomResourceClass, createDebugger, createMeta, deferredOutput, enableDebug, findInputDeps, getMeta, isDataSource, isNode, isResource, nodeMetaSymbol, output, resolveInputs };
+export { App, AppError, type Config, type CreateProps, type CustomResourceProvider, type DataSource, type DataSourceFunction, type DataSourceMeta, type DeleteProps, DynamoLockBackend, FileLockBackend, FileStateBackend, Future, type GetDataProps, type GetProps, Group, type Input, type LockBackend, MemoryLockBackend, MemoryStateBackend, type Meta, type Node, type OptionalInput, type OptionalOutput, Output, type PlanProps, type ProcedureOptions, type Provider, type Resource, ResourceAlreadyExists, type ResourceClass, type ResourceConfig, ResourceError, type ResourceMeta, ResourceNotFound, S3StateBackend, Stack, type State, type StateBackend, type Tag, type URN, type UpdateProps, WorkSpace, type WorkSpaceOptions, createCustomProvider, createCustomResourceClass, createDebugger, createMeta, deferredOutput, enableDebug, findInputDeps, getMeta, isDataSource, isNode, isResource, nodeMetaSymbol, output, resolveInputs };

package/dist/index.js

@@ -420,6 +420,9 @@ var DependencyGraph = class {
     this.callbacks.set(urn, callback);
     this.graph.mergeNode(urn);
     for (const dep of deps) {
+      if (!dep) {
+        throw new Error(`Resource ${urn} has an undefined dependency.`);
+      }
       if (willCreateCycle(this.graph, dep, urn)) {
         throw new Error(`There is a circular dependency between ${urn} -> ${dep}`);
       }
@@ -610,11 +613,23 @@ var deleteResource = async (appToken, urn, state, opt) => {
   const idempotantToken = createIdempotantToken(appToken, urn, "delete");
   const provider = findProvider(opt.providers, state.provider);
   try {
+    await opt.hooks?.beforeResourceDelete?.({
+      urn,
+      type: state.type,
+      oldInput: state.input,
+      oldOutput: state.output
+    });
     await provider.deleteResource({
       type: state.type,
       state: state.output,
       idempotantToken
     });
+    await opt.hooks?.afterResourceDelete?.({
+      urn,
+      type: state.type,
+      oldInput: state.input,
+      oldOutput: state.output
+    });
   } catch (error) {
     if (error instanceof ResourceNotFound) {
       debug(state.type, "already deleted");
@@ -699,11 +714,24 @@ var createResource = async (resource, appToken, input, opt) => {
   debug2(input);
   let result;
   try {
+    await opt.hooks?.beforeResourceCreate?.({
+      urn: resource.urn,
+      type: meta.type,
+      resource,
+      newInput: input
+    });
     result = await provider.createResource({
       type: meta.type,
       state: input,
       idempotantToken
     });
+    await opt.hooks?.afterResourceCreate?.({
+      urn: resource.urn,
+      type: meta.type,
+      resource,
+      newInput: input,
+      newOutput: result.state
+    });
   } catch (error) {
     throw ResourceError.wrap(meta.urn, meta.type, "create", error);
   }
@@ -774,7 +802,7 @@ var importResource = async (resource, input, opt) => {
 
 // src/workspace/procedure/replace-resource.ts
 var debug5 = createDebugger("Replace");
-var replaceResource = async (resource, appToken, priorState, proposedState, opt) => {
+var replaceResource = async (resource, appToken, priorInputState, priorOutputState, proposedState, opt) => {
   const meta = getMeta(resource);
   const urn = meta.urn;
   const type = meta.type;
@@ -786,11 +814,23 @@ var replaceResource = async (resource, appToken, priorState, proposedState, opt)
     debug5("retain", type);
   } else {
     try {
+      await opt.hooks?.beforeResourceDelete?.({
+        urn,
+        type,
+        oldInput: priorInputState,
+        oldOutput: priorOutputState
+      });
       await provider.deleteResource({
         type,
-        state: priorState,
+        state: priorOutputState,
         idempotantToken
       });
+      await opt.hooks?.afterResourceDelete?.({
+        urn,
+        type,
+        oldInput: priorInputState,
+        oldOutput: priorOutputState
+      });
     } catch (error) {
       if (error instanceof ResourceNotFound) {
         debug5(type, "already deleted");
@@ -801,11 +841,24 @@ var replaceResource = async (resource, appToken, priorState, proposedState, opt)
   }
   let result;
   try {
+    await opt.hooks?.beforeResourceCreate?.({
+      urn,
+      type,
+      resource,
+      newInput: proposedState
+    });
     result = await provider.createResource({
       type,
       state: proposedState,
       idempotantToken
     });
+    await opt.hooks?.afterResourceCreate?.({
+      urn,
+      type,
+      resource,
+      newInput: proposedState,
+      newOutput: result.state
+    });
   } catch (error) {
     throw ResourceError.wrap(urn, type, "replace", error);
   }
@@ -817,7 +870,7 @@ var replaceResource = async (resource, appToken, priorState, proposedState, opt)
 
 // src/workspace/procedure/update-resource.ts
 var debug6 = createDebugger("Update");
-var updateResource = async (resource, appToken, priorState, proposedState, opt) => {
+var updateResource = async (resource, appToken, priorInputState, priorOutputState, proposedState, opt) => {
   const meta = getMeta(resource);
   const provider = findProvider(opt.providers, meta.provider);
   const idempotantToken = createIdempotantToken(appToken, meta.urn, "update");
@@ -825,12 +878,29 @@ var updateResource = async (resource, appToken, priorState, proposedState, opt)
   debug6(meta.type);
   debug6(proposedState);
   try {
+    await opt.hooks?.beforeResourceUpdate?.({
+      urn: resource.urn,
+      type: meta.type,
+      resource,
+      newInput: proposedState,
+      oldInput: priorInputState,
+      oldOutput: priorOutputState
+    });
     result = await provider.updateResource({
       type: meta.type,
-      priorState,
+      priorState: priorOutputState,
       proposedState,
       idempotantToken
     });
+    await opt.hooks?.afterResourceUpdate?.({
+      urn: resource.urn,
+      type: meta.type,
+      resource,
+      newInput: proposedState,
+      oldInput: priorInputState,
+      newOutput: result.state,
+      oldOutput: priorOutputState
+    });
   } catch (error) {
     throw ResourceError.wrap(meta.urn, meta.type, "update", error);
   }
@@ -842,6 +912,89 @@ var updateResource = async (resource, appToken, priorState, proposedState, opt)
 
 // src/workspace/procedure/deploy-app.ts
 var debug7 = createDebugger("Deploy App");
+var findDependencyPaths = (value, dependencyUrn, path = []) => {
+  const paths = [];
+  const visit = (current, currentPath) => {
+    if (current instanceof Output) {
+      for (const dep of current.dependencies) {
+        if (dep.urn === dependencyUrn) {
+          paths.push(currentPath);
+          return;
+        }
+      }
+      return;
+    }
+    if (Array.isArray(current)) {
+      current.forEach((item, index) => {
+        visit(item, [...currentPath, index]);
+      });
+      return;
+    }
+    if (current && typeof current === "object") {
+      for (const [key, item] of Object.entries(current)) {
+        visit(item, [...currentPath, key]);
+      }
+    }
+  };
+  visit(value, path);
+  return paths;
+};
+var cloneState = (value) => JSON.parse(JSON.stringify(value));
+var removeAtPath = (target, path) => {
+  if (path.length === 0) return;
+  let parent = target;
+  for (let i = 0; i < path.length - 1; i++) {
+    if (parent == null) return;
+    parent = parent[path[i]];
+  }
+  const last = path[path.length - 1];
+  if (Array.isArray(parent) && typeof last === "number") {
+    if (last >= 0 && last < parent.length) {
+      parent.splice(last, 1);
+    }
+    return;
+  }
+  if (parent && typeof parent === "object") {
+    delete parent[last];
+  }
+};
+var stripDependencyInputs = (input, metaInput, dependencyUrn) => {
+  const paths = findDependencyPaths(metaInput, dependencyUrn);
+  if (paths.length === 0) {
+    return input;
+  }
+  const detached = cloneState(input);
+  const sortedPaths = [...paths].sort((a, b) => {
+    if (a.length !== b.length) return b.length - a.length;
+    const aLast = a[a.length - 1];
+    const bLast = b[b.length - 1];
+    if (typeof aLast === "number" && typeof bLast === "number") {
+      return bLast - aLast;
+    }
+    return 0;
+  });
+  for (const path of sortedPaths) {
+    removeAtPath(detached, path);
+  }
+  return detached;
+};
+var allowsDependentReplace = (replaceOnChanges, dependencyPaths) => {
+  if (!replaceOnChanges || replaceOnChanges.length === 0) {
+    return false;
+  }
+  for (const path of dependencyPaths) {
+    const base = typeof path[0] === "string" ? path[0] : void 0;
+    if (!base) {
+      continue;
+    }
+    for (const replacePath of replaceOnChanges) {
+      if (replacePath === base || replacePath.startsWith(`${base}.`) || replacePath.startsWith(`${base}[`) || replacePath.startsWith(`${base}.*`)) {
+        return true;
+      }
+    }
+  }
+  return false;
+};
 var deployApp = async (app, opt) => {
   debug7(app.name, "start");
   const latestState = await opt.backend.state.get(app.urn);
@@ -864,8 +1017,23 @@ var deployApp = async (app, opt) => {
     stacks = app.stacks.filter((stack) => opt.filters.includes(stack.name));
     filteredOutStacks = app.stacks.filter((stack) => !opt.filters.includes(stack.name));
   }
+  const nodeByUrn = /* @__PURE__ */ new Map();
+  const stackStates = /* @__PURE__ */ new Map();
+  const plannedDependents = /* @__PURE__ */ new Set();
+  const forcedUpdateDependents = /* @__PURE__ */ new Set();
+  for (const stack of stacks) {
+    const stackState = appState.stacks[stack.urn] = appState.stacks[stack.urn] ?? {
+      name: stack.name,
+      nodes: {}
+    };
+    stackStates.set(stack.urn, stackState);
+    for (const node of stack.nodes) {
+      nodeByUrn.set(getMeta(node).urn, node);
+    }
+  }
   const queue = createConcurrencyQueue(opt.concurrency ?? 10);
   const graph = new DependencyGraph();
+  const replacementDeletes = /* @__PURE__ */ new Map();
   const allNodes = {};
   for (const stackState of Object.values(appState.stacks)) {
     for (const [urn, nodeState] of entries(stackState.nodes)) {
@@ -912,10 +1080,7 @@ var deployApp = async (app, opt) => {
     }
   }
   for (const stack of stacks) {
-    const stackState = appState.stacks[stack.urn] = appState.stacks[stack.urn] ?? {
-      name: stack.name,
-      nodes: {}
-    };
+    const stackState = stackStates.get(stack.urn);
     for (const [urn, nodeState] of entries(stackState.nodes)) {
       const resource = stack.nodes.find((r) => getMeta(r).urn === urn);
       if (!resource) {
@@ -986,6 +1151,7 @@ var deployApp = async (app, opt) => {
                 const newResourceState = await updateResource(
                   node,
                   appState.idempotentToken,
+                  importedState.input,
                   importedState.output,
                   input,
                   opt
@@ -1013,22 +1179,121 @@ var deployApp = async (app, opt) => {
               !compareState(nodeState.input, input)
             ) {
               let newResourceState;
-              if (requiresReplacement(nodeState.input, input, meta2.config?.replaceOnChanges ?? [])) {
-                newResourceState = await replaceResource(
-                  node,
-                  appState.idempotentToken,
-                  nodeState.output,
-                  input,
-                  opt
-                );
+              const ignoreReplace = forcedUpdateDependents.has(meta2.urn);
+              if (!ignoreReplace && requiresReplacement(nodeState.input, input, meta2.config?.replaceOnChanges ?? [])) {
+                if (meta2.config?.createBeforeReplace) {
+                  const priorState = { ...nodeState };
+                  newResourceState = await createResource(node, appState.idempotentToken, input, opt);
+                  if (!meta2.config?.retainOnDelete) {
+                    replacementDeletes.set(meta2.urn, priorState);
+                  }
+                } else {
+                  for (const [dependentUrn, dependentNode] of nodeByUrn.entries()) {
+                    if (!isResource(dependentNode)) {
+                      continue;
+                    }
+                    const dependentMeta = getMeta(dependentNode);
+                    if (!dependentMeta.dependencies.has(meta2.urn)) {
+                      continue;
+                    }
+                    if (plannedDependents.has(dependentUrn)) {
+                      continue;
+                    }
+                    const dependentStackState = stackStates.get(dependentMeta.stack.urn);
+                    const dependentState = dependentStackState?.nodes[dependentUrn];
+                    if (!dependentStackState || !dependentState) {
+                      continue;
+                    }
+                    const dependencyPaths = findDependencyPaths(dependentMeta.input, meta2.urn);
+                    if (dependencyPaths.length === 0) {
+                      continue;
+                    }
+                    const detachedInput = stripDependencyInputs(
+                      dependentState.input,
+                      dependentMeta.input,
+                      meta2.urn
+                    );
+                    if (compareState(dependentState.input, detachedInput)) {
+                      continue;
+                    }
+                    plannedDependents.add(dependentUrn);
+                    let dependentRequiresReplacement = false;
+                    const dependentProvider = findProvider(opt.providers, dependentMeta.provider);
+                    if (dependentProvider.planResourceChange) {
+                      try {
+                        const dependentPlan = await dependentProvider.planResourceChange({
+                          type: dependentMeta.type,
+                          priorState: dependentState.output,
+                          proposedState: detachedInput
+                        });
+                        dependentRequiresReplacement = dependentPlan.requiresReplacement;
+                      } catch (error) {
+                        throw ResourceError.wrap(
+                          dependentMeta.urn,
+                          dependentMeta.type,
+                          "update",
+                          error
+                        );
+                      }
+                    }
+                    if (dependentRequiresReplacement) {
+                      if (!allowsDependentReplace(
+                        dependentMeta.config?.replaceOnChanges,
+                        dependencyPaths
+                      )) {
+                        throw ResourceError.wrap(
+                          dependentMeta.urn,
+                          dependentMeta.type,
+                          "update",
+                          new Error(
+                            `Replacing ${meta2.urn} requires ${dependentMeta.urn} to set replaceOnChanges for its dependency fields.`
+                          )
+                        );
+                      }
+                      await deleteResource(
+                        appState.idempotentToken,
+                        dependentUrn,
+                        dependentState,
+                        opt
+                      );
+                      delete dependentStackState.nodes[dependentUrn];
+                    } else {
+                      const updated = await updateResource(
+                        dependentNode,
+                        appState.idempotentToken,
+                        dependentState.input,
+                        dependentState.output,
+                        detachedInput,
+                        opt
+                      );
+                      Object.assign(dependentState, {
+                        input: detachedInput,
+                        ...updated
+                      });
+                      forcedUpdateDependents.add(dependentUrn);
+                    }
+                  }
+                  newResourceState = await replaceResource(
+                    node,
+                    appState.idempotentToken,
+                    nodeState.input,
+                    nodeState.output,
+                    input,
+                    opt
+                  );
+                }
               } else {
                 newResourceState = await updateResource(
                   node,
                   appState.idempotentToken,
+                  nodeState.input,
                   nodeState.output,
                   input,
                   opt
                 );
+                if (ignoreReplace) {
+                  forcedUpdateDependents.delete(meta2.urn);
+                }
               }
               Object.assign(nodeState, {
                 input,
@@ -1047,6 +1312,19 @@ var deployApp = async (app, opt) => {
     }
   }
   const errors = await graph.run();
+  if (errors.length === 0 && replacementDeletes.size > 0) {
+    for (const [urn, nodeState] of replacementDeletes.entries()) {
+      try {
+        await deleteResource(appState.idempotentToken, urn, nodeState, opt);
+      } catch (error) {
+        if (error instanceof Error) {
+          errors.push(error);
+        } else {
+          errors.push(new Error(`${error}`));
+        }
+      }
+    }
+  }
   removeEmptyStackStates(appState);
   delete appState.idempotentToken;
   await opt.backend.state.update(app.urn, appState);
@@ -1514,6 +1792,21 @@ var createCustomProvider = (providerId, resourceProviders) => {
     async deleteResource({ type, ...props }) {
       await getProvider(type).deleteResource?.(props);
     },
+    async planResourceChange({ type, ...props }) {
+      const provider = getProvider(type);
+      if (!provider.planResourceChange) {
+        return {
+          version,
+          state: props.proposedState,
+          requiresReplacement: false
+        };
+      }
+      const result = await provider.planResourceChange(props);
+      return {
+        version,
+        ...result
+      };
+    },
     async getData({ type, ...props }) {
       return {
         version,

package/package.json

@@ -1,7 +1,14 @@
 {
 	"name": "@terraforge/core",
-	"version": "0.0.5",
+	"version": "0.0.7",
 	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/terraforge-js/terraforge.git"
+	},
+	"bugs": {
+		"url": "https://github.com/terraforge-js/terraforge/issues"
+	},
 	"module": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"exports": {
@@ -12,7 +19,7 @@
 	},
 	"scripts": {
 		"build": "tsup src/index.ts --format esm --dts --clean --out-dir ./dist",
-		"prepublishOnly": "bun run build",
+		"prepublishOnly": "if bun run test; then bun run build; else exit; fi",
 		"test": "bun test"
 	},
 	"dependencies": {