@twin.org/entity 0.0.3-next.41 → 0.0.3-next.42

package/dist/es/index.js

@@ -18,7 +18,7 @@ export * from "./models/sortDirection.js";
 export * from "./utils/decoratorHelper.js";
 export * from "./utils/entityConditions.js";
 export * from "./utils/entitySchemaHelper.js";
-export * from "./utils/entitySchemaDiff.js";
+export * from "./utils/entitySchemaDiffHelper.js";
 export * from "./utils/entitySorter.js";
 export * from "./models/IEntitySchemaDiff.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AACrD,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./decorators/entityDecorator.js\";\nexport * from \"./decorators/propertyDecorator.js\";\nexport * from \"./factories/entitySchemaFactory.js\";\nexport * from \"./models/comparisonOperator.js\";\nexport * from \"./models/entityCondition.js\";\nexport * from \"./models/entitySchemaPropertyFormat.js\";\nexport * from \"./models/entitySchemaPropertyType.js\";\nexport * from \"./models/IComparator.js\";\nexport * from \"./models/IComparatorGroup.js\";\nexport * from \"./models/IEntitySchema.js\";\nexport * from \"./models/IEntitySchemaOptions.js\";\nexport * from \"./models/IEntitySchemaProperty.js\";\nexport * from \"./models/IEntitySort.js\";\nexport * from \"./models/logicalOperator.js\";\nexport * from \"./models/sortDirection.js\";\nexport * from \"./utils/decoratorHelper.js\";\nexport * from \"./utils/entityConditions.js\";\nexport * from \"./utils/entitySchemaHelper.js\";\nexport * from \"./utils/entitySchemaDiff.js\";\nexport * from \"./utils/entitySorter.js\";\nexport * from \"./models/IEntitySchemaDiff.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AACrD,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./decorators/entityDecorator.js\";\nexport * from \"./decorators/propertyDecorator.js\";\nexport * from \"./factories/entitySchemaFactory.js\";\nexport * from \"./models/comparisonOperator.js\";\nexport * from \"./models/entityCondition.js\";\nexport * from \"./models/entitySchemaPropertyFormat.js\";\nexport * from \"./models/entitySchemaPropertyType.js\";\nexport * from \"./models/IComparator.js\";\nexport * from \"./models/IComparatorGroup.js\";\nexport * from \"./models/IEntitySchema.js\";\nexport * from \"./models/IEntitySchemaOptions.js\";\nexport * from \"./models/IEntitySchemaProperty.js\";\nexport * from \"./models/IEntitySort.js\";\nexport * from \"./models/logicalOperator.js\";\nexport * from \"./models/sortDirection.js\";\nexport * from \"./utils/decoratorHelper.js\";\nexport * from \"./utils/entityConditions.js\";\nexport * from \"./utils/entitySchemaHelper.js\";\nexport * from \"./utils/entitySchemaDiffHelper.js\";\nexport * from \"./utils/entitySorter.js\";\nexport * from \"./models/IEntitySchemaDiff.js\";\n"]}

package/dist/es/models/IEntitySchemaDiff.js.map

@@ -1 +1 @@
-{"version":3,"file":"IEntitySchemaDiff.js","sourceRoot":"","sources":["../../../src/models/IEntitySchemaDiff.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IEntitySchemaProperty } from \"./IEntitySchemaProperty.js\";\n\n/**\n * The result of comparing two sets of entity schema properties.\n */\nexport interface IEntitySchemaDiff<T = unknown> {\n\t/**\n\t * Properties present in the new schema but absent from the old one.\n\t * Each entry is the full property descriptor from the new schema, so it can\n\t * be passed directly to bootstrap / table-creation logic.\n\t */\n\tadded: IEntitySchemaProperty<T>[];\n\n\t/**\n\t * Properties present in the old schema but absent from the new one.\n\t * Each entry is the full property descriptor from the old schema, allowing\n\t * connectors to drop the correct column, index, or field by name.\n\t */\n\tremoved: IEntitySchemaProperty<T>[];\n\n\t/**\n\t * Properties that exist in both schemas but differ in at least one structural\n\t * field (type, format, isSecondary, sortDirection, optional, itemType, itemTypeRef).\n\t * `from` is the old descriptor; `to` is the new one.\n\t * Both are full property objects so connectors can drop the old definition and\n\t * create the new one using the same bootstrap code path.\n\t */\n\tmodified: {\n\t\t/**\n\t\t * The old property descriptor.\n\t\t */\n\t\tfrom: IEntitySchemaProperty<T>;\n\t\t/**\n\t\t * The new property descriptor.\n\t\t */\n\t\tto: IEntitySchemaProperty<T>;\n\t}[];\n}\n"]}
+{"version":3,"file":"IEntitySchemaDiff.js","sourceRoot":"","sources":["../../../src/models/IEntitySchemaDiff.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IEntitySchemaProperty } from \"./IEntitySchemaProperty.js\";\n\n/**\n * The result of comparing two sets of entity schema properties.\n */\nexport interface IEntitySchemaDiff<T = unknown, U = unknown> {\n\t/**\n\t * Properties that are structurally identical between the old and new schemas.\n\t */\n\tunchanged: IEntitySchemaProperty<T | U>[];\n\n\t/**\n\t * Properties present in the new schema but absent from the old one.\n\t */\n\tadded: IEntitySchemaProperty<U>[];\n\n\t/**\n\t * Properties present in the old schema but absent from the new one.\n\t */\n\tremoved: IEntitySchemaProperty<T>[];\n\n\t/**\n\t * Properties that exist in both schemas but differ in at least one structural\n\t * field (property, type, format, isPrimary, isSecondary, sortDirection, optional, itemType, itemTypeRef).\n\t * `from` is the old descriptor; `to` is the new one.\n\t */\n\tmodified: {\n\t\t/**\n\t\t * The old property descriptor.\n\t\t */\n\t\tfrom: IEntitySchemaProperty<T>;\n\t\t/**\n\t\t * The new property descriptor.\n\t\t */\n\t\tto: IEntitySchemaProperty<U>;\n\t}[];\n}\n"]}

package/dist/es/utils/entitySchemaDiffHelper.js

@@ -0,0 +1,139 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { GeneralError, Guards } from "@twin.org/core";
+/**
+ * Helper class for comparing entity schemas and generating diffs.
+ */
+export class EntitySchemaDiffHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "EntitySchemaDiffHelper";
+    /**
+     * Compare two arrays of entity schema properties and return a structured diff.
+     *
+     * Properties are matched by their `property` key name. A property is considered modified when any structural field differs: `type`, `format`, `isPrimary`, `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.
+     * Documentation-only fields (`description`, `examples`) are intentionally excluded from the comparison to avoid spurious diffs.
+     *
+     * Because a pure name change cannot be detected automatically, callers may supply a `renames` list mapping old names to new names. Renamed properties appear in `modified` (never in `added` or `removed`) even when no other fields changed. Rename lookups take priority over direct same-name matches, which allows swap renames to work correctly and prevents a renamed source from silently disappearing when the target name already existed in the old schema. Self-renames (`from === to`) are ignored and the property is classified normally.
+     *
+     * When `renames` contains duplicate entries: if two entries share the same target, the last definition wins and the first source is treated as removed; if two entries share the same source, the first target wins and the second target is treated as added. Both cases are deterministic but callers should avoid them.
+     * @param oldProperties The property descriptors from the current (live) schema.
+     * @param newProperties The property descriptors from the target (new) schema.
+     * @param renames Optional list of property renames `{ from, to }` where `from` is the old name and `to` is the new name.
+     * @returns A diff object with `added`, `removed`, `modified`, and `unchanged` arrays, each containing full `IEntitySchemaProperty` descriptors.
+     * @throws `GeneralError` if either input array contains duplicate property keys.
+     */
+    static diff(oldProperties, newProperties, renames) {
+        Guards.array(EntitySchemaDiffHelper.CLASS_NAME, "oldProperties", oldProperties);
+        Guards.array(EntitySchemaDiffHelper.CLASS_NAME, "newProperties", newProperties);
+        const added = [];
+        const removed = [];
+        const modified = [];
+        const unchanged = [];
+        const oldMap = new Map();
+        for (const prop of oldProperties) {
+            const propKey = prop.property;
+            if (oldMap.has(propKey)) {
+                throw new GeneralError(EntitySchemaDiffHelper.CLASS_NAME, "duplicateOldProperty", {
+                    property: propKey
+                });
+            }
+            oldMap.set(propKey, prop);
+        }
+        const newMap = new Map();
+        for (const prop of newProperties) {
+            const propKey = prop.property;
+            if (newMap.has(propKey)) {
+                throw new GeneralError(EntitySchemaDiffHelper.CLASS_NAME, "duplicateNewProperty", {
+                    property: propKey
+                });
+            }
+            newMap.set(propKey, prop);
+        }
+        // new-name → old-name, used when iterating newProperties
+        const renameToFrom = new Map();
+        if (renames) {
+            for (const rename of renames) {
+                renameToFrom.set(rename.to, rename.from);
+            }
+        }
+        // Old names that were consumed by a rename (prevents double-use of the same source).
+        const consumedByRename = new Set();
+        // New names matched via rename path (their same-named old prop is not their direct match).
+        const newKeyMatchedViaRename = new Set();
+        for (const newProp of newProperties) {
+            const key = newProp.property;
+            // Rename lookup takes priority over a direct same-name match so that:
+            // - swap renames work (both names exist in old and new)
+            // - a renamed source does not vanish when the target name already existed in old
+            // Self-renames (fromKey === key) are skipped so the property is classified normally.
+            const fromKey = renameToFrom.get(key);
+            const renamedSource = fromKey !== undefined ? oldMap.get(fromKey) : undefined;
+            if (fromKey !== undefined &&
+                fromKey !== key &&
+                renamedSource !== undefined &&
+                !consumedByRename.has(fromKey)) {
+                modified.push({ from: renamedSource, to: newProp });
+                consumedByRename.add(fromKey);
+                newKeyMatchedViaRename.add(key);
+            }
+            else {
+                const oldProp = oldMap.get(key);
+                if (oldProp !== undefined) {
+                    if (!EntitySchemaDiffHelper.schemaPropertiesEqual(oldProp, newProp)) {
+                        modified.push({ from: oldProp, to: newProp });
+                    }
+                    else {
+                        unchanged.push(newProp);
+                    }
+                }
+                else {
+                    added.push(newProp);
+                }
+            }
+        }
+        for (const oldProp of oldProperties) {
+            const key = oldProp.property;
+            // Removed when absent from new, or when its same-named new prop was claimed by a rename
+            // (meaning this old prop was not the match for that new prop).
+            // Exception: skip if this old prop was itself consumed as a rename source.
+            if ((!newMap.has(key) || newKeyMatchedViaRename.has(key)) && !consumedByRename.has(key)) {
+                removed.push(oldProp);
+            }
+        }
+        return { added, removed, modified, unchanged };
+    }
+    /**
+     * Returns true when the diff contains at least one added, removed, or modified property.
+     * @param diff The diff to check.
+     * @returns True if the diff has any structural changes.
+     */
+    static hasChanges(diff) {
+        Guards.object(EntitySchemaDiffHelper.CLASS_NAME, "diff", diff);
+        Guards.array(EntitySchemaDiffHelper.CLASS_NAME, "diff.added", diff.added);
+        Guards.array(EntitySchemaDiffHelper.CLASS_NAME, "diff.removed", diff.removed);
+        Guards.array(EntitySchemaDiffHelper.CLASS_NAME, "diff.modified", diff.modified);
+        return diff.added.length > 0 || diff.removed.length > 0 || diff.modified.length > 0;
+    }
+    /**
+     * Compare two property descriptors for structural equality.
+     * The `property` name field and documentation fields (`description`, `examples`) are intentionally excluded — callers match by name before invoking this method.
+     * @param schema1 The first property descriptor.
+     * @param schema2 The second property descriptor.
+     * @returns True if all structural fields are equal.
+     */
+    static schemaPropertiesEqual(schema1, schema2) {
+        Guards.object(EntitySchemaDiffHelper.CLASS_NAME, "schema1", schema1);
+        Guards.object(EntitySchemaDiffHelper.CLASS_NAME, "schema2", schema2);
+        return (schema1.type === schema2.type &&
+            schema1.format === schema2.format &&
+            schema1.isPrimary === schema2.isPrimary &&
+            schema1.isSecondary === schema2.isSecondary &&
+            schema1.sortDirection === schema2.sortDirection &&
+            schema1.optional === schema2.optional &&
+            schema1.itemType === schema2.itemType &&
+            schema1.itemTypeRef === schema2.itemTypeRef);
+    }
+}
+//# sourceMappingURL=entitySchemaDiffHelper.js.map

package/dist/es/utils/entitySchemaDiffHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitySchemaDiffHelper.js","sourceRoot":"","sources":["../../../src/utils/entitySchemaDiffHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { GeneralError, Guards } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { IEntitySchemaDiff } from \"../models/IEntitySchemaDiff.js\";\nimport type { IEntitySchemaProperty } from \"../models/IEntitySchemaProperty.js\";\n\n/**\n * Helper class for comparing entity schemas and generating diffs.\n */\nexport class EntitySchemaDiffHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<EntitySchemaDiffHelper>();\n\n\t/**\n\t * Compare two arrays of entity schema properties and return a structured diff.\n\t *\n\t * Properties are matched by their `property` key name. A property is considered modified when any structural field differs: `type`, `format`, `isPrimary`, `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.\n\t * Documentation-only fields (`description`, `examples`) are intentionally excluded from the comparison to avoid spurious diffs.\n\t *\n\t * Because a pure name change cannot be detected automatically, callers may supply a `renames` list mapping old names to new names. Renamed properties appear in `modified` (never in `added` or `removed`) even when no other fields changed. Rename lookups take priority over direct same-name matches, which allows swap renames to work correctly and prevents a renamed source from silently disappearing when the target name already existed in the old schema. Self-renames (`from === to`) are ignored and the property is classified normally.\n\t *\n\t * When `renames` contains duplicate entries: if two entries share the same target, the last definition wins and the first source is treated as removed; if two entries share the same source, the first target wins and the second target is treated as added. Both cases are deterministic but callers should avoid them.\n\t * @param oldProperties The property descriptors from the current (live) schema.\n\t * @param newProperties The property descriptors from the target (new) schema.\n\t * @param renames Optional list of property renames `{ from, to }` where `from` is the old name and `to` is the new name.\n\t * @returns A diff object with `added`, `removed`, `modified`, and `unchanged` arrays, each containing full `IEntitySchemaProperty` descriptors.\n\t * @throws `GeneralError` if either input array contains duplicate property keys.\n\t */\n\tpublic static diff<T, U = T>(\n\t\toldProperties: IEntitySchemaProperty<T>[],\n\t\tnewProperties: IEntitySchemaProperty<U>[],\n\t\trenames?: { from: string; to: string }[]\n\t): IEntitySchemaDiff<T, U> {\n\t\tGuards.array(EntitySchemaDiffHelper.CLASS_NAME, nameof(oldProperties), oldProperties);\n\t\tGuards.array(EntitySchemaDiffHelper.CLASS_NAME, nameof(newProperties), newProperties);\n\n\t\tconst added: IEntitySchemaProperty<U>[] = [];\n\t\tconst removed: IEntitySchemaProperty<T>[] = [];\n\t\tconst modified: IEntitySchemaDiff<T, U>[\"modified\"] = [];\n\t\tconst unchanged: IEntitySchemaProperty<T | U>[] = [];\n\n\t\tconst oldMap = new Map<string, IEntitySchemaProperty<T>>();\n\t\tfor (const prop of oldProperties) {\n\t\t\tconst propKey = prop.property as string;\n\t\t\tif (oldMap.has(propKey)) {\n\t\t\t\tthrow new GeneralError(EntitySchemaDiffHelper.CLASS_NAME, \"duplicateOldProperty\", {\n\t\t\t\t\tproperty: propKey\n\t\t\t\t});\n\t\t\t}\n\t\t\toldMap.set(propKey, prop);\n\t\t}\n\n\t\tconst newMap = new Map<string, IEntitySchemaProperty<U>>();\n\t\tfor (const prop of newProperties) {\n\t\t\tconst propKey = prop.property as string;\n\t\t\tif (newMap.has(propKey)) {\n\t\t\t\tthrow new GeneralError(EntitySchemaDiffHelper.CLASS_NAME, \"duplicateNewProperty\", {\n\t\t\t\t\tproperty: propKey\n\t\t\t\t});\n\t\t\t}\n\t\t\tnewMap.set(propKey, prop);\n\t\t}\n\n\t\t// new-name → old-name, used when iterating newProperties\n\t\tconst renameToFrom = new Map<string, string>();\n\t\tif (renames) {\n\t\t\tfor (const rename of renames) {\n\t\t\t\trenameToFrom.set(rename.to, rename.from);\n\t\t\t}\n\t\t}\n\n\t\t// Old names that were consumed by a rename (prevents double-use of the same source).\n\t\tconst consumedByRename = new Set<string>();\n\t\t// New names matched via rename path (their same-named old prop is not their direct match).\n\t\tconst newKeyMatchedViaRename = new Set<string>();\n\n\t\tfor (const newProp of newProperties) {\n\t\t\tconst key = newProp.property as string;\n\n\t\t\t// Rename lookup takes priority over a direct same-name match so that:\n\t\t\t// - swap renames work (both names exist in old and new)\n\t\t\t// - a renamed source does not vanish when the target name already existed in old\n\t\t\t// Self-renames (fromKey === key) are skipped so the property is classified normally.\n\t\t\tconst fromKey = renameToFrom.get(key);\n\t\t\tconst renamedSource = fromKey !== undefined ? oldMap.get(fromKey) : undefined;\n\n\t\t\tif (\n\t\t\t\tfromKey !== undefined &&\n\t\t\t\tfromKey !== key &&\n\t\t\t\trenamedSource !== undefined &&\n\t\t\t\t!consumedByRename.has(fromKey)\n\t\t\t) {\n\t\t\t\tmodified.push({ from: renamedSource, to: newProp });\n\t\t\t\tconsumedByRename.add(fromKey);\n\t\t\t\tnewKeyMatchedViaRename.add(key);\n\t\t\t} else {\n\t\t\t\tconst oldProp = oldMap.get(key);\n\t\t\t\tif (oldProp !== undefined) {\n\t\t\t\t\tif (!EntitySchemaDiffHelper.schemaPropertiesEqual(oldProp, newProp)) {\n\t\t\t\t\t\tmodified.push({ from: oldProp, to: newProp });\n\t\t\t\t\t} else {\n\t\t\t\t\t\tunchanged.push(newProp as IEntitySchemaProperty<T | U>);\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tadded.push(newProp);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tfor (const oldProp of oldProperties) {\n\t\t\tconst key = oldProp.property as string;\n\t\t\t// Removed when absent from new, or when its same-named new prop was claimed by a rename\n\t\t\t// (meaning this old prop was not the match for that new prop).\n\t\t\t// Exception: skip if this old prop was itself consumed as a rename source.\n\t\t\tif ((!newMap.has(key) || newKeyMatchedViaRename.has(key)) && !consumedByRename.has(key)) {\n\t\t\t\tremoved.push(oldProp);\n\t\t\t}\n\t\t}\n\n\t\treturn { added, removed, modified, unchanged };\n\t}\n\n\t/**\n\t * Returns true when the diff contains at least one added, removed, or modified property.\n\t * @param diff The diff to check.\n\t * @returns True if the diff has any structural changes.\n\t */\n\tpublic static hasChanges<T, U>(diff: IEntitySchemaDiff<T, U>): boolean {\n\t\tGuards.object(EntitySchemaDiffHelper.CLASS_NAME, nameof(diff), diff);\n\t\tGuards.array(EntitySchemaDiffHelper.CLASS_NAME, nameof(diff.added), diff.added);\n\t\tGuards.array(EntitySchemaDiffHelper.CLASS_NAME, nameof(diff.removed), diff.removed);\n\t\tGuards.array(EntitySchemaDiffHelper.CLASS_NAME, nameof(diff.modified), diff.modified);\n\t\treturn diff.added.length > 0 || diff.removed.length > 0 || diff.modified.length > 0;\n\t}\n\n\t/**\n\t * Compare two property descriptors for structural equality.\n\t * The `property` name field and documentation fields (`description`, `examples`) are intentionally excluded — callers match by name before invoking this method.\n\t * @param schema1 The first property descriptor.\n\t * @param schema2 The second property descriptor.\n\t * @returns True if all structural fields are equal.\n\t */\n\tpublic static schemaPropertiesEqual<T, U>(\n\t\tschema1: IEntitySchemaProperty<T>,\n\t\tschema2: IEntitySchemaProperty<U>\n\t): boolean {\n\t\tGuards.object(EntitySchemaDiffHelper.CLASS_NAME, nameof(schema1), schema1);\n\t\tGuards.object(EntitySchemaDiffHelper.CLASS_NAME, nameof(schema2), schema2);\n\t\treturn (\n\t\t\tschema1.type === schema2.type &&\n\t\t\tschema1.format === schema2.format &&\n\t\t\tschema1.isPrimary === schema2.isPrimary &&\n\t\t\tschema1.isSecondary === schema2.isSecondary &&\n\t\t\tschema1.sortDirection === schema2.sortDirection &&\n\t\t\tschema1.optional === schema2.optional &&\n\t\t\tschema1.itemType === schema2.itemType &&\n\t\t\tschema1.itemTypeRef === schema2.itemTypeRef\n\t\t);\n\t}\n}\n"]}

package/dist/types/index.d.ts

@@ -16,6 +16,6 @@ export * from "./models/sortDirection.js";
 export * from "./utils/decoratorHelper.js";
 export * from "./utils/entityConditions.js";
 export * from "./utils/entitySchemaHelper.js";
-export * from "./utils/entitySchemaDiff.js";
+export * from "./utils/entitySchemaDiffHelper.js";
 export * from "./utils/entitySorter.js";
 export * from "./models/IEntitySchemaDiff.js";

package/dist/types/models/IEntitySchemaDiff.d.ts

@@ -2,25 +2,23 @@ import type { IEntitySchemaProperty } from "./IEntitySchemaProperty.js";
 /**
  * The result of comparing two sets of entity schema properties.
  */
-export interface IEntitySchemaDiff<T = unknown> {
+export interface IEntitySchemaDiff<T = unknown, U = unknown> {
+    /**
+     * Properties that are structurally identical between the old and new schemas.
+     */
+    unchanged: IEntitySchemaProperty<T | U>[];
     /**
      * Properties present in the new schema but absent from the old one.
-     * Each entry is the full property descriptor from the new schema, so it can
-     * be passed directly to bootstrap / table-creation logic.
      */
-    added: IEntitySchemaProperty<T>[];
+    added: IEntitySchemaProperty<U>[];
     /**
      * Properties present in the old schema but absent from the new one.
-     * Each entry is the full property descriptor from the old schema, allowing
-     * connectors to drop the correct column, index, or field by name.
      */
     removed: IEntitySchemaProperty<T>[];
     /**
      * Properties that exist in both schemas but differ in at least one structural
-     * field (type, format, isSecondary, sortDirection, optional, itemType, itemTypeRef).
+     * field (property, type, format, isPrimary, isSecondary, sortDirection, optional, itemType, itemTypeRef).
      * `from` is the old descriptor; `to` is the new one.
-     * Both are full property objects so connectors can drop the old definition and
-     * create the new one using the same bootstrap code path.
      */
     modified: {
         /**
@@ -30,6 +28,6 @@ export interface IEntitySchemaDiff<T = unknown> {
         /**
          * The new property descriptor.
          */
-        to: IEntitySchemaProperty<T>;
+        to: IEntitySchemaProperty<U>;
     }[];
 }

package/dist/types/utils/entitySchemaDiffHelper.d.ts

@@ -0,0 +1,44 @@
+import type { IEntitySchemaDiff } from "../models/IEntitySchemaDiff.js";
+import type { IEntitySchemaProperty } from "../models/IEntitySchemaProperty.js";
+/**
+ * Helper class for comparing entity schemas and generating diffs.
+ */
+export declare class EntitySchemaDiffHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Compare two arrays of entity schema properties and return a structured diff.
+     *
+     * Properties are matched by their `property` key name. A property is considered modified when any structural field differs: `type`, `format`, `isPrimary`, `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.
+     * Documentation-only fields (`description`, `examples`) are intentionally excluded from the comparison to avoid spurious diffs.
+     *
+     * Because a pure name change cannot be detected automatically, callers may supply a `renames` list mapping old names to new names. Renamed properties appear in `modified` (never in `added` or `removed`) even when no other fields changed. Rename lookups take priority over direct same-name matches, which allows swap renames to work correctly and prevents a renamed source from silently disappearing when the target name already existed in the old schema. Self-renames (`from === to`) are ignored and the property is classified normally.
+     *
+     * When `renames` contains duplicate entries: if two entries share the same target, the last definition wins and the first source is treated as removed; if two entries share the same source, the first target wins and the second target is treated as added. Both cases are deterministic but callers should avoid them.
+     * @param oldProperties The property descriptors from the current (live) schema.
+     * @param newProperties The property descriptors from the target (new) schema.
+     * @param renames Optional list of property renames `{ from, to }` where `from` is the old name and `to` is the new name.
+     * @returns A diff object with `added`, `removed`, `modified`, and `unchanged` arrays, each containing full `IEntitySchemaProperty` descriptors.
+     * @throws `GeneralError` if either input array contains duplicate property keys.
+     */
+    static diff<T, U = T>(oldProperties: IEntitySchemaProperty<T>[], newProperties: IEntitySchemaProperty<U>[], renames?: {
+        from: string;
+        to: string;
+    }[]): IEntitySchemaDiff<T, U>;
+    /**
+     * Returns true when the diff contains at least one added, removed, or modified property.
+     * @param diff The diff to check.
+     * @returns True if the diff has any structural changes.
+     */
+    static hasChanges<T, U>(diff: IEntitySchemaDiff<T, U>): boolean;
+    /**
+     * Compare two property descriptors for structural equality.
+     * The `property` name field and documentation fields (`description`, `examples`) are intentionally excluded — callers match by name before invoking this method.
+     * @param schema1 The first property descriptor.
+     * @param schema2 The second property descriptor.
+     * @returns True if all structural fields are equal.
+     */
+    static schemaPropertiesEqual<T, U>(schema1: IEntitySchemaProperty<T>, schema2: IEntitySchemaProperty<U>): boolean;
+}

package/docs/changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.0.3-next.42](https://github.com/iotaledger/twin-framework/compare/entity-v0.0.3-next.41...entity-v0.0.3-next.42) (2026-05-15)
+
+
+### Features
+
+* entity schema diff updates ([#294](https://github.com/iotaledger/twin-framework/issues/294)) ([7a7a94d](https://github.com/iotaledger/twin-framework/commit/7a7a94d14ea5e785dd68fd6de1c5a84941721d28))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.0.3-next.41 to 0.0.3-next.42
+    * @twin.org/core bumped from 0.0.3-next.41 to 0.0.3-next.42
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.41 to 0.0.3-next.42
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.41 to 0.0.3-next.42
+    * @twin.org/validate-locales bumped from 0.0.3-next.41 to 0.0.3-next.42
+
 ## [0.0.3-next.41](https://github.com/iotaledger/twin-framework/compare/entity-v0.0.3-next.40...entity-v0.0.3-next.41) (2026-05-13)
 
 

package/docs/reference/classes/EntitySchemaDiffHelper.md

@@ -0,0 +1,147 @@
+# Class: EntitySchemaDiffHelper
+
+Helper class for comparing entity schemas and generating diffs.
+
+## Constructors
+
+### Constructor
+
+> **new EntitySchemaDiffHelper**(): `EntitySchemaDiffHelper`
+
+#### Returns
+
+`EntitySchemaDiffHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### diff() {#diff}
+
+> `static` **diff**\<`T`, `U`\>(`oldProperties`, `newProperties`, `renames?`): [`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`, `U`\>
+
+Compare two arrays of entity schema properties and return a structured diff.
+
+Properties are matched by their `property` key name. A property is considered modified when any structural field differs: `type`, `format`, `isPrimary`, `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.
+Documentation-only fields (`description`, `examples`) are intentionally excluded from the comparison to avoid spurious diffs.
+
+Because a pure name change cannot be detected automatically, callers may supply a `renames` list mapping old names to new names. Renamed properties appear in `modified` (never in `added` or `removed`) even when no other fields changed. Rename lookups take priority over direct same-name matches, which allows swap renames to work correctly and prevents a renamed source from silently disappearing when the target name already existed in the old schema. Self-renames (`from === to`) are ignored and the property is classified normally.
+
+When `renames` contains duplicate entries: if two entries share the same target, the last definition wins and the first source is treated as removed; if two entries share the same source, the first target wins and the second target is treated as added. Both cases are deterministic but callers should avoid them.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U` = `T`
+
+#### Parameters
+
+##### oldProperties
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>[]
+
+The property descriptors from the current (live) schema.
+
+##### newProperties
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`U`\>[]
+
+The property descriptors from the target (new) schema.
+
+##### renames?
+
+`object`[]
+
+Optional list of property renames `{ from, to }` where `from` is the old name and `to` is the new name.
+
+#### Returns
+
+[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`, `U`\>
+
+A diff object with `added`, `removed`, `modified`, and `unchanged` arrays, each containing full `IEntitySchemaProperty` descriptors.
+
+#### Throws
+
+`GeneralError` if either input array contains duplicate property keys.
+
+***
+
+### hasChanges() {#haschanges}
+
+> `static` **hasChanges**\<`T`, `U`\>(`diff`): `boolean`
+
+Returns true when the diff contains at least one added, removed, or modified property.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### diff
+
+[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`, `U`\>
+
+The diff to check.
+
+#### Returns
+
+`boolean`
+
+True if the diff has any structural changes.
+
+***
+
+### schemaPropertiesEqual() {#schemapropertiesequal}
+
+> `static` **schemaPropertiesEqual**\<`T`, `U`\>(`schema1`, `schema2`): `boolean`
+
+Compare two property descriptors for structural equality.
+The `property` name field and documentation fields (`description`, `examples`) are intentionally excluded — callers match by name before invoking this method.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### schema1
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>
+
+The first property descriptor.
+
+##### schema2
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`U`\>
+
+The second property descriptor.
+
+#### Returns
+
+`boolean`
+
+True if all structural fields are equal.

package/docs/reference/index.md

@@ -4,6 +4,7 @@
 
 - [DecoratorHelper](classes/DecoratorHelper.md)
 - [EntityConditions](classes/EntityConditions.md)
+- [EntitySchemaDiffHelper](classes/EntitySchemaDiffHelper.md)
 - [EntitySchemaHelper](classes/EntitySchemaHelper.md)
 - [EntitySorter](classes/EntitySorter.md)
 
@@ -39,5 +40,3 @@
 
 - [entity](functions/entity.md)
 - [property](functions/property.md)
-- [entitySchemaDiff](functions/entitySchemaDiff.md)
-- [isEmptyDiff](functions/isEmptyDiff.md)

package/docs/reference/interfaces/IEntitySchemaDiff.md

@@ -1,4 +1,4 @@
-# Interface: IEntitySchemaDiff\<T\>
+# Interface: IEntitySchemaDiff\<T, U\>
 
 The result of comparing two sets of entity schema properties.
 
@@ -8,15 +8,25 @@ The result of comparing two sets of entity schema properties.
 
 `T` = `unknown`
 
+### U
+
+`U` = `unknown`
+
 ## Properties
 
+### unchanged {#unchanged}
+
+> **unchanged**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T` \| `U`\>[]
+
+Properties that are structurally identical between the old and new schemas.
+
+***
+
 ### added {#added}
 
-> **added**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>[]
+> **added**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`U`\>[]
 
 Properties present in the new schema but absent from the old one.
-Each entry is the full property descriptor from the new schema, so it can
-be passed directly to bootstrap / table-creation logic.
 
 ***
 
@@ -25,8 +35,6 @@ be passed directly to bootstrap / table-creation logic.
 > **removed**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>[]
 
 Properties present in the old schema but absent from the new one.
-Each entry is the full property descriptor from the old schema, allowing
-connectors to drop the correct column, index, or field by name.
 
 ***
 
@@ -35,10 +43,8 @@ connectors to drop the correct column, index, or field by name.
 > **modified**: `object`[]
 
 Properties that exist in both schemas but differ in at least one structural
-field (type, format, isSecondary, sortDirection, optional, itemType, itemTypeRef).
+field (property, type, format, isPrimary, isSecondary, sortDirection, optional, itemType, itemTypeRef).
 `from` is the old descriptor; `to` is the new one.
-Both are full property objects so connectors can drop the old definition and
-create the new one using the same bootstrap code path.
 
 #### from
 
@@ -48,6 +54,6 @@ The old property descriptor.
 
 #### to
 
-> **to**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>
+> **to**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`U`\>
 
 The new property descriptor.

package/locales/en.json

@@ -1,5 +1,9 @@
 {
 	"error": {
+		"entitySchemaDiffHelper": {
+			"duplicateOldProperty": "The oldProperties array contains a duplicate property key \"{property}\"",
+			"duplicateNewProperty": "The newProperties array contains a duplicate property key \"{property}\""
+		},
 		"entitySchemaHelper": {
 			"noIsPrimary": "Property \"entitySchema.properties\" must contain a value with isPrimary set",
 			"multipleIsPrimary": "Property \"entitySchema.properties\" contains more than one property with isPrimary set",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity",
-	"version": "0.0.3-next.41",
+	"version": "0.0.3-next.42",
 	"description": "Helpers for defining and working with entities",
 	"repository": {
 		"type": "git",
@@ -14,8 +14,8 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/core": "0.0.3-next.41",
-		"@twin.org/nameof": "0.0.3-next.41",
+		"@twin.org/core": "0.0.3-next.42",
+		"@twin.org/nameof": "0.0.3-next.42",
 		"reflect-metadata": "0.2.2",
 		"tslib": "2.8.1"
 	},

package/dist/es/utils/entitySchemaDiff.js

@@ -1,67 +0,0 @@
-/**
- * Compare two arrays of entity schema properties and return a structured diff.
- *
- * Properties are matched by their `property` key name. A property is considered
- * modified when any structural field differs: `type`, `format`, `isPrimary`,
- * `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.
- * Documentation-only fields (`description`, `examples`) are intentionally
- * excluded from the comparison to avoid spurious diffs.
- * @param oldProperties The property descriptors from the current (live) schema.
- * @param newProperties The property descriptors from the target (new) schema.
- * @returns A diff object with `added`, `removed`, and `modified` arrays, each
- * containing full `IEntitySchemaProperty` descriptors.
- */
-export function entitySchemaDiff(oldProperties, newProperties) {
-    const added = [];
-    const removed = [];
-    const modified = [];
-    const oldMap = new Map();
-    for (const prop of oldProperties) {
-        oldMap.set(prop.property, prop);
-    }
-    const newMap = new Map();
-    for (const prop of newProperties) {
-        newMap.set(prop.property, prop);
-    }
-    for (const newProp of newProperties) {
-        const oldProp = oldMap.get(newProp.property);
-        if (!oldProp) {
-            added.push(newProp);
-        }
-        else if (!schemaPropertiesEqual(oldProp, newProp)) {
-            modified.push({ from: oldProp, to: newProp });
-        }
-    }
-    for (const oldProp of oldProperties) {
-        if (!newMap.has(oldProp.property)) {
-            removed.push(oldProp);
-        }
-    }
-    return { added, removed, modified };
-}
-/**
- * Returns true when the diff contains no changes (nothing added, removed, or modified).
- * @param diff The diff to check.
- * @returns True if the diff is empty.
- */
-export function isEmptyDiff(diff) {
-    return diff.added.length === 0 && diff.removed.length === 0 && diff.modified.length === 0;
-}
-/**
- * Compare two property descriptors for structural equality.
- * Documentation fields (description, examples) are excluded.
- * @param a The first property descriptor.
- * @param b The second property descriptor.
- * @returns True if all structural fields are equal.
- */
-function schemaPropertiesEqual(a, b) {
-    return (a.type === b.type &&
-        a.format === b.format &&
-        a.isPrimary === b.isPrimary &&
-        a.isSecondary === b.isSecondary &&
-        a.sortDirection === b.sortDirection &&
-        a.optional === b.optional &&
-        a.itemType === b.itemType &&
-        a.itemTypeRef === b.itemTypeRef);
-}
-//# sourceMappingURL=entitySchemaDiff.js.map

package/dist/es/utils/entitySchemaDiff.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"entitySchemaDiff.js","sourceRoot":"","sources":["../../../src/utils/entitySchemaDiff.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC/B,aAAyC,EACzC,aAAyC;IAEzC,MAAM,KAAK,GAA+B,EAAE,CAAC;IAC7C,MAAM,OAAO,GAA+B,EAAE,CAAC;IAC/C,MAAM,QAAQ,GAAqC,EAAE,CAAC;IAEtD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoC,CAAC;IAC3D,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAkB,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoC,CAAC;IAC3D,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAkB,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,QAAkB,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC;aAAM,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC/C,CAAC;IACF,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,QAAkB,CAAC,EAAE,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAI,IAA0B;IACxD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;GAMG;AACH,SAAS,qBAAqB,CAC7B,CAA2B,EAC3B,CAA2B;IAE3B,OAAO,CACN,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QACrB,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS;QAC3B,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,aAAa;QACnC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QACzB,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QACzB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,CAC/B,CAAC;AACH,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IEntitySchemaDiff } from \"../models/IEntitySchemaDiff.js\";\nimport type { IEntitySchemaProperty } from \"../models/IEntitySchemaProperty.js\";\n\n/**\n * Compare two arrays of entity schema properties and return a structured diff.\n *\n * Properties are matched by their `property` key name. A property is considered\n * modified when any structural field differs: `type`, `format`, `isPrimary`,\n * `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.\n * Documentation-only fields (`description`, `examples`) are intentionally\n * excluded from the comparison to avoid spurious diffs.\n * @param oldProperties The property descriptors from the current (live) schema.\n * @param newProperties The property descriptors from the target (new) schema.\n * @returns A diff object with `added`, `removed`, and `modified` arrays, each\n * containing full `IEntitySchemaProperty` descriptors.\n */\nexport function entitySchemaDiff<T>(\n\toldProperties: IEntitySchemaProperty<T>[],\n\tnewProperties: IEntitySchemaProperty<T>[]\n): IEntitySchemaDiff<T> {\n\tconst added: IEntitySchemaProperty<T>[] = [];\n\tconst removed: IEntitySchemaProperty<T>[] = [];\n\tconst modified: IEntitySchemaDiff<T>[\"modified\"] = [];\n\n\tconst oldMap = new Map<string, IEntitySchemaProperty<T>>();\n\tfor (const prop of oldProperties) {\n\t\toldMap.set(prop.property as string, prop);\n\t}\n\n\tconst newMap = new Map<string, IEntitySchemaProperty<T>>();\n\tfor (const prop of newProperties) {\n\t\tnewMap.set(prop.property as string, prop);\n\t}\n\n\tfor (const newProp of newProperties) {\n\t\tconst oldProp = oldMap.get(newProp.property as string);\n\t\tif (!oldProp) {\n\t\t\tadded.push(newProp);\n\t\t} else if (!schemaPropertiesEqual(oldProp, newProp)) {\n\t\t\tmodified.push({ from: oldProp, to: newProp });\n\t\t}\n\t}\n\n\tfor (const oldProp of oldProperties) {\n\t\tif (!newMap.has(oldProp.property as string)) {\n\t\t\tremoved.push(oldProp);\n\t\t}\n\t}\n\n\treturn { added, removed, modified };\n}\n\n/**\n * Returns true when the diff contains no changes (nothing added, removed, or modified).\n * @param diff The diff to check.\n * @returns True if the diff is empty.\n */\nexport function isEmptyDiff<T>(diff: IEntitySchemaDiff<T>): boolean {\n\treturn diff.added.length === 0 && diff.removed.length === 0 && diff.modified.length === 0;\n}\n\n/**\n * Compare two property descriptors for structural equality.\n * Documentation fields (description, examples) are excluded.\n * @param a The first property descriptor.\n * @param b The second property descriptor.\n * @returns True if all structural fields are equal.\n */\nfunction schemaPropertiesEqual<T>(\n\ta: IEntitySchemaProperty<T>,\n\tb: IEntitySchemaProperty<T>\n): boolean {\n\treturn (\n\t\ta.type === b.type &&\n\t\ta.format === b.format &&\n\t\ta.isPrimary === b.isPrimary &&\n\t\ta.isSecondary === b.isSecondary &&\n\t\ta.sortDirection === b.sortDirection &&\n\t\ta.optional === b.optional &&\n\t\ta.itemType === b.itemType &&\n\t\ta.itemTypeRef === b.itemTypeRef\n\t);\n}\n"]}

package/dist/types/utils/entitySchemaDiff.d.ts

@@ -1,22 +0,0 @@
-import type { IEntitySchemaDiff } from "../models/IEntitySchemaDiff.js";
-import type { IEntitySchemaProperty } from "../models/IEntitySchemaProperty.js";
-/**
- * Compare two arrays of entity schema properties and return a structured diff.
- *
- * Properties are matched by their `property` key name. A property is considered
- * modified when any structural field differs: `type`, `format`, `isPrimary`,
- * `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.
- * Documentation-only fields (`description`, `examples`) are intentionally
- * excluded from the comparison to avoid spurious diffs.
- * @param oldProperties The property descriptors from the current (live) schema.
- * @param newProperties The property descriptors from the target (new) schema.
- * @returns A diff object with `added`, `removed`, and `modified` arrays, each
- * containing full `IEntitySchemaProperty` descriptors.
- */
-export declare function entitySchemaDiff<T>(oldProperties: IEntitySchemaProperty<T>[], newProperties: IEntitySchemaProperty<T>[]): IEntitySchemaDiff<T>;
-/**
- * Returns true when the diff contains no changes (nothing added, removed, or modified).
- * @param diff The diff to check.
- * @returns True if the diff is empty.
- */
-export declare function isEmptyDiff<T>(diff: IEntitySchemaDiff<T>): boolean;

package/docs/reference/functions/entitySchemaDiff.md

@@ -1,38 +0,0 @@
-# Function: entitySchemaDiff()
-
-> **entitySchemaDiff**\<`T`\>(`oldProperties`, `newProperties`): [`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`\>
-
-Compare two arrays of entity schema properties and return a structured diff.
-
-Properties are matched by their `property` key name. A property is considered
-modified when any structural field differs: `type`, `format`, `isPrimary`,
-`isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.
-Documentation-only fields (`description`, `examples`) are intentionally
-excluded from the comparison to avoid spurious diffs.
-
-## Type Parameters
-
-### T
-
-`T`
-
-## Parameters
-
-### oldProperties
-
-[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>[]
-
-The property descriptors from the current (live) schema.
-
-### newProperties
-
-[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>[]
-
-The property descriptors from the target (new) schema.
-
-## Returns
-
-[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`\>
-
-A diff object with `added`, `removed`, and `modified` arrays, each
-containing full `IEntitySchemaProperty` descriptors.

package/docs/reference/functions/isEmptyDiff.md

@@ -1,25 +0,0 @@
-# Function: isEmptyDiff()
-
-> **isEmptyDiff**\<`T`\>(`diff`): `boolean`
-
-Returns true when the diff contains no changes (nothing added, removed, or modified).
-
-## Type Parameters
-
-### T
-
-`T`
-
-## Parameters
-
-### diff
-
-[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`\>
-
-The diff to check.
-
-## Returns
-
-`boolean`
-
-True if the diff is empty.