@notation/resource 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -323,6 +323,56 @@ type ResourceBuilder<ApiSchema extends DefineResourceApiSchema> = {
 declare function defineResource<ApiSchema extends DefineResourceApiSchema>(meta: DefineResourceMeta): ResourceBuilder<ApiSchema>;
 declare const resource: typeof defineResource;
 
+/**
+ * Stands in for a param whose value is known only once a dependency has been
+ * applied. Compared structurally, so it survives a JSON round trip.
+ */
+declare const UNKNOWN_AFTER_APPLY: {
+    readonly $unknown: "after-apply";
+};
+type UnknownAfterApply = typeof UNKNOWN_AFTER_APPLY;
+declare function isUnknownAfterApply(value: unknown): value is UnknownAfterApply;
+/**
+ * A field that forces replacement. `known: false` means the desired value is
+ * unknown after apply, so the field may force replacement.
+ */
+type ReplaceField = {
+    name: string;
+    known: boolean;
+};
+type ParamsDiffDisplay = {
+    added: Record<string, unknown>;
+    deleted: Record<string, unknown>;
+    updated: Record<string, unknown>;
+};
+type ParamsDiff = {
+    /** Changed comparable params only. */
+    patch: Record<string, unknown>;
+    /** Names of changed fields. */
+    changed: string[];
+    /** Fields that force replacement. */
+    replaceFields: ReplaceField[];
+    /** For plan display. */
+    diff: ParamsDiffDisplay;
+};
+/**
+ * Keeps the params that take part in a comparison: `param` items that are
+ * neither volatile nor hidden. An `undefined` value counts as absent: state
+ * is stored as JSON, which drops it, so keeping it would make an unset
+ * optional param look changed on every deploy.
+ */
+declare function toComparableParams(schema: Schema, values: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Compares previous and desired params field by field, and reads the schema
+ * to decide which changes no update can apply: a change to an immutable or
+ * key param, or any change at all when the resource cannot update. Pure: it
+ * reads nothing but its arguments, so any engine planning a Notation resource
+ * reaches the same answer as the reconciler.
+ */
+declare function diffParams(schema: Schema, previous: Record<string, unknown>, desired: Record<string, unknown>, options: {
+    canUpdate: boolean;
+}): ParamsDiff;
+
 type ResourceGroupOptions = {
     /**
      * Optional pre-assigned ID. Used outside graph collection.
@@ -349,4 +399,4 @@ type ResourceGraph = {
 };
 declare function collectResourceGraph(evaluate: () => unknown | Promise<unknown>): Promise<ResourceGraph>;
 
-export { type BaseResource, type CompoundKey, type ComputedPrimaryKey, type DeepPartial, type DefineResourceApiSchema, type DefineResourceMeta, type Fallback, type IfAllPropertiesOptional, type InferResourceTypes, type MapSchema, type NoInfer, type OmitOptional, type OptionalIfAllPropertiesOptional, type Output, type Params, type PickOptional, type ResolveSchema, type ResolvedSchema, Resource, type ResourceBuilder, type ResourceClass, type ResourceDependenciesBuilder, type ResourceGraph, ResourceGroup, type ResourceGroupOptions, ResourceNotFoundError, type ResourceOperationContext, ResourceOperationPendingError, type ResourceOperationSignal, type ResourceOperationsOptions, type ResourceOpts, type ResourceSchemaBuilder, type ResourceType, type ResourceTypes, type Result, type Schema, type SchemaFromApi, type SchemaItem, type Simplify, type State, type TypedValue, collectResourceGraph, defineResource, resource, typed };
+export { type BaseResource, type CompoundKey, type ComputedPrimaryKey, type DeepPartial, type DefineResourceApiSchema, type DefineResourceMeta, type Fallback, type IfAllPropertiesOptional, type InferResourceTypes, type MapSchema, type NoInfer, type OmitOptional, type OptionalIfAllPropertiesOptional, type Output, type Params, type ParamsDiff, type ParamsDiffDisplay, type PickOptional, type ReplaceField, type ResolveSchema, type ResolvedSchema, Resource, type ResourceBuilder, type ResourceClass, type ResourceDependenciesBuilder, type ResourceGraph, ResourceGroup, type ResourceGroupOptions, ResourceNotFoundError, type ResourceOperationContext, ResourceOperationPendingError, type ResourceOperationSignal, type ResourceOperationsOptions, type ResourceOpts, type ResourceSchemaBuilder, type ResourceType, type ResourceTypes, type Result, type Schema, type SchemaFromApi, type SchemaItem, type Simplify, type State, type TypedValue, UNKNOWN_AFTER_APPLY, type UnknownAfterApply, collectResourceGraph, defineResource, diffParams, isUnknownAfterApply, resource, toComparableParams, typed };

package/dist/index.js

@@ -1,6 +1,69 @@
 // src/resource.schema.ts
 var typed = () => ({});
 
+// src/diff-params.ts
+import { detailedDiff, diff } from "deep-object-diff";
+var UNKNOWN_AFTER_APPLY = { $unknown: "after-apply" };
+function isUnknownAfterApply(value) {
+  return value !== null && typeof value === "object" && value.$unknown === UNKNOWN_AFTER_APPLY.$unknown;
+}
+function toComparableParams(schema, values) {
+  const comparable = {};
+  for (const [key, item] of Object.entries(schema)) {
+    if (!isComparable(item)) continue;
+    if (values[key] !== void 0) comparable[key] = values[key];
+  }
+  return comparable;
+}
+function diffParams(schema, previous, desired, options) {
+  const previousComparable = toComparableParams(schema, previous);
+  const desiredComparable = toComparableParams(schema, desired);
+  const patch = diff(previousComparable, desiredComparable);
+  const changed = [];
+  const replaceFields = [];
+  for (const [name, item] of Object.entries(schema)) {
+    if (!isComparable(item)) continue;
+    const unknown = isUnknownAfterApply(desiredComparable[name]);
+    if (!unknown && !(name in patch)) continue;
+    if (!(name in patch)) patch[name] = desiredComparable[name];
+    changed.push(name);
+    if (!options.canUpdate || forcesReplacement(item)) {
+      replaceFields.push({ name, known: !unknown });
+    }
+  }
+  return {
+    patch,
+    changed,
+    replaceFields,
+    diff: toDisplayDiff(detailedDiff(previousComparable, desiredComparable))
+  };
+}
+function isComparable(item) {
+  return item.propertyType === "param" && !item.volatile && !item.hidden;
+}
+function forcesReplacement(item) {
+  return item.propertyType === "param" && Boolean(item.immutable || item.primaryKey || item.secondaryKey);
+}
+function toDisplayDiff(diffResult) {
+  return {
+    added: toJsonSafe(diffResult.added),
+    deleted: toJsonSafe(diffResult.deleted),
+    updated: toJsonSafe(diffResult.updated)
+  };
+}
+function toJsonSafe(value) {
+  if (value === void 0) return null;
+  if (Array.isArray(value)) return value.map(toJsonSafe);
+  if (value !== null && typeof value === "object") {
+    const safe = {};
+    for (const [key, entry] of Object.entries(value)) {
+      safe[key] = toJsonSafe(entry);
+    }
+    return safe;
+  }
+  return value;
+}
+
 // src/resource.ts
 var Resource = class {
   config;
@@ -28,16 +91,7 @@ var Resource = class {
     this.output = output;
   }
   toComparable(output) {
-    const parsed = {};
-    for (const [k, v] of Object.entries(this.schema)) {
-      if (v.volatile) continue;
-      if (v.hidden) continue;
-      if (v.propertyType !== "param") continue;
-      if (k in output) {
-        parsed[k] = output[k];
-      }
-    }
-    return parsed;
+    return toComparableParams(this.schema, output);
   }
   toState(output) {
     const parsed = {};
@@ -209,8 +263,12 @@ export {
   ResourceGroup,
   ResourceNotFoundError,
   ResourceOperationPendingError,
+  UNKNOWN_AFTER_APPLY,
   collectResourceGraph,
   defineResource,
+  diffParams,
+  isUnknownAfterApply,
   resource,
+  toComparableParams,
   typed
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@notation/resource",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -13,6 +13,9 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "deep-object-diff": "^1.1.9"
+  },
   "scripts": {
     "build": "tsup --clean",
     "dev": "tsup --watch"