@terraforge/core 0.0.5 → 0.0.6

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;
@@ -187,6 +187,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 +215,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 +280,7 @@ type WorkSpaceOptions = {
         state: StateBackend;
         lock: LockBackend;
     };
+    hooks?: Hooks;
 };
 declare class WorkSpace {
     protected props: WorkSpaceOptions;
@@ -356,7 +410,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

@@ -610,11 +610,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 +711,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 +799,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 +811,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 +838,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 +867,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 +875,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 +909,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,6 +1014,20 @@ 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 allNodes = {};
@@ -912,10 +1076,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 +1147,7 @@ var deployApp = async (app, opt) => {
                 const newResourceState = await updateResource(
                   node,
                   appState.idempotentToken,
+                  importedState.input,
                   importedState.output,
                   input,
                   opt
@@ -1013,10 +1175,97 @@ var deployApp = async (app, opt) => {
               !compareState(nodeState.input, input)
             ) {
               let newResourceState;
-              if (requiresReplacement(nodeState.input, input, meta2.config?.replaceOnChanges ?? [])) {
+              const ignoreReplace = forcedUpdateDependents.has(meta2.urn);
+              if (!ignoreReplace && requiresReplacement(nodeState.input, input, meta2.config?.replaceOnChanges ?? [])) {
+                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
@@ -1025,10 +1274,14 @@ var deployApp = async (app, opt) => {
                 newResourceState = await updateResource(
                   node,
                   appState.idempotentToken,
+                  nodeState.input,
                   nodeState.output,
                   input,
                   opt
                 );
+                if (ignoreReplace) {
+                  forcedUpdateDependents.delete(meta2.urn);
+                }
               }
               Object.assign(nodeState, {
                 input,
@@ -1514,6 +1767,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.6",
 	"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": {