@twin.org/entity-storage-models 0.0.3-next.21 → 0.0.3-next.22

package/dist/es/factories/schemaMigrationFactory.js

@@ -0,0 +1,17 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Factory } from "@twin.org/core";
+/**
+ * Factory for optional per-step migration overrides.
+ *
+ * Only register an entry when a version step requires property renames or a custom
+ * transform hook. For purely structural changes (add/remove/type-change) the
+ * SchemaVersionService diffs the two versioned schema classes automatically
+ * without needing any factory entry.
+ *
+ * Keys follow the convention "<BaseSchemaName>_<fromVersion>_<toVersion>",
+ * for example "MyEntity_0_1" for the step that migrates MyEntity from version 0 to 1.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const SchemaMigrationFactory = Factory.createFactory("schema-migration");
+//# sourceMappingURL=schemaMigrationFactory.js.map

package/dist/es/factories/schemaMigrationFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaMigrationFactory.js","sourceRoot":"","sources":["../../../src/factories/schemaMigrationFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;;;;;;;;;GAUG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAmB,kBAAkB,CAAC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { ISchemaMigration } from \"../models/ISchemaMigration.js\";\n\n/**\n * Factory for optional per-step migration overrides.\n *\n * Only register an entry when a version step requires property renames or a custom\n * transform hook. For purely structural changes (add/remove/type-change) the\n * SchemaVersionService diffs the two versioned schema classes automatically\n * without needing any factory entry.\n *\n * Keys follow the convention \"<BaseSchemaName>_<fromVersion>_<toVersion>\",\n * for example \"MyEntity_0_1\" for the step that migrates MyEntity from version 0 to 1.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const SchemaMigrationFactory = Factory.createFactory<ISchemaMigration>(\"schema-migration\");\n"]}

package/dist/es/helpers/migrationHelper.js

@@ -4,7 +4,9 @@ import { ContextIdStore } from "@twin.org/context";
 import { Coerce, GeneralError, Is, ObjectHelper } from "@twin.org/core";
 import { EntitySchemaDiffHelper, EntitySchemaPropertyType } from "@twin.org/entity";
 /**
- * Helper class for performing schema migrations between two connectors.
+ * Helper class for performing entity schema migrations between two connectors.
+ * The chain-based API (migrateWithChain / applyEntityChain) is the single migration
+ * path: a chain of one step covers the same case as a traditional single-step migration.
  */
 export class MigrationHelper {
     /**
@@ -12,126 +14,16 @@ export class MigrationHelper {
      */
     static CLASS_NAME = "MigrationHelper";
     /**
-     * Performs a migration between two connectors, using the provided options and schema diff to control the migration behaviour.
-     * @param sourceConnector The connector to migrate from to allow the migration helper to create the new connector and finalize the migration.
-     * @param targetEntitySchemaName The name of the new entity schema.
-     * @param renames An optional list of property renames to apply during migration.
-     * @param options Options controlling migration behaviour.
-     * @param loggingComponentType An optional logging component type to use for bootstrapping and starting connectors if necessary.
-     * @returns The connector for the new schema and the number of entities successfully migrated, the sourceConnector will no longer be usable, finalConnector will be undefined if no migration was necessary.
-     */
-    static async migrate(sourceConnector, targetEntitySchemaName, renames, options, loggingComponentType) {
-        let targetConnector;
-        try {
-            // We use the migration method to create the new connector as it will use a temporary storage location if necessary
-            targetConnector = await sourceConnector.createTargetConnector(targetEntitySchemaName);
-            // Startup both connectors to ensure they are ready for the migration, this will call bootstrap and start if they are defined.
-            await MigrationHelper.startupConnector(sourceConnector, loggingComponentType);
-            await MigrationHelper.startupConnector(targetConnector, loggingComponentType);
-            // Get the unique partition context ids to run the migration for each partition.
-            let partitionContextIds = await sourceConnector.getPartitionContextIds();
-            // If there are no partitions, we still want to run the migration once to handle the schema changes,
-            // so we create a single empty context for the migration to run in.
-            if (!Is.arrayValue(partitionContextIds)) {
-                partitionContextIds ??= [];
-                partitionContextIds.push({});
-            }
-            // Get the schemas
-            const sourceSchema = sourceConnector.getSchema();
-            const targetSchema = targetConnector.getSchema();
-            // Get the schema diff between the source and target schemas.
-            const schemaDiff = EntitySchemaDiffHelper.diff(sourceSchema.properties ?? [], targetSchema.properties ?? [], renames);
-            // Only perform a migration if the schemas have changed
-            if (EntitySchemaDiffHelper.hasChanges(schemaDiff)) {
-                // Perform the migration, which will read from the current store and write to the target connector's store.
-                const migrated = await MigrationHelper.migrateEntities(sourceConnector, targetConnector, partitionContextIds, schemaDiff, options);
-                // The migration is now complete, finalize the migration which could entail
-                // renaming of resources etc, determined by the implementation of finalizeMigration.
-                // it also needs to stop and teardown any resources no longer in use after the migration,
-                // such as the old connector and its underlying storage.
-                const finalConnector = await sourceConnector.finalizeMigration(targetConnector, options, loggingComponentType);
-                return {
-                    finalConnector,
-                    migrated
-                };
-            }
-            return {
-                finalConnector: undefined,
-                migrated: 0
-            };
-        }
-        catch (error) {
-            await sourceConnector.cleanupMigration(targetConnector, options, loggingComponentType);
-            throw new GeneralError(MigrationHelper.CLASS_NAME, "migrationFailed", undefined, error);
-        }
-    }
-    /**
-     * Generic per-partition migration loop.
-     * @param source Connector to read from (current schema, already bootstrapped).
-     * @param target Connector to write to (new schema, already bootstrapped).
-     * @param partitionContextIds The context ids to use for the migration, used for partitioning and can be used in the transform function when `options.transformEntityProperty` is provided.
-     * @param schemaDiff The schema diff.
-     * @param options Optional migration controls (batchSize, transformEntity, onProgress).
-     * @returns The number of entities successfully migrated.
-     */
-    static async migrateEntities(source, target, partitionContextIds, schemaDiff, options) {
-        let migrated = 0;
-        await options?.onStepProgress?.("migrationStart", 0, 0);
-        const effectivePartitions = partitionContextIds.length > 0 ? partitionContextIds : [{}];
-        for (let i = 0; i < effectivePartitions.length; i++) {
-            await ContextIdStore.run(effectivePartitions[i], async () => {
-                await options?.onStepProgress?.("partitionStart", effectivePartitions.length, i);
-                migrated += await MigrationHelper.migratePartition(source, target, effectivePartitions.length, i, schemaDiff, options);
-                await options?.onStepProgress?.("partitionEnd", effectivePartitions.length, i);
-            });
-        }
-        await options?.onStepProgress?.("migrationEnd", 0, 0);
-        return migrated;
-    }
-    /**
-     * Generic per-partition migration loop.
-     * @param source Connector to read from (current schema, already bootstrapped).
-     * @param target Connector to write to (new schema, already bootstrapped).
-     * @param partitionTotal The total number of partitions to migrate, used for progress reporting.
-     * @param partitionIndex The index of the current partition being migrated, used for progress reporting.
-     * @param schemaDiff Schema diff used to add nullable defaults and drop removed fields when `options.transformEntity` is not provided.
-     * @param options Optional migration controls (batchSize, transformEntity, onProgress).
-     * @returns The number of entities successfully migrated.
-     */
-    static async migratePartition(source, target, partitionTotal, partitionIndex, schemaDiff, options) {
-        const batchSize = options?.batchSize ?? 100;
-        let migrated = 0;
-        let cursor;
-        const totalEntities = await source.count();
-        await options?.onPartitionProgress?.(totalEntities, 0);
-        if (totalEntities > 0) {
-            do {
-                const page = await source.query(undefined, undefined, undefined, cursor, batchSize);
-                cursor = page.cursor;
-                if (Is.arrayValue(page.entities)) {
-                    const transformedBatch = [];
-                    for (const entity of page.entities) {
-                        const transformedEntity = MigrationHelper.applyEntityTransform(entity, schemaDiff, options);
-                        transformedBatch.push(transformedEntity);
-                    }
-                    await target.setBatch(transformedBatch);
-                    migrated += transformedBatch.length;
-                }
-                await options?.onPartitionProgress?.(totalEntities, migrated);
-            } while (Is.stringValue(cursor));
-        }
-        return migrated;
-    }
-    /**
-     * Applies the entity transformation for migration, using the provided options and schema diff.
+     * Applies the entity transformation for a single diff, handling added, removed, and
+     * modified properties according to the provided schema diff and optional transform hook.
      * @param entity The entity to transform.
      * @param schemaDiff The schema diff between the old and new schemas.
-     * @param options The migration options.
+     * @param transformEntityProperty Optional per-property transform hook for object/array properties.
      * @returns The transformed entity ready to be written to the new schema.
-     * @throws GeneralError if a transformation is required for an object or array property but no `options.transformEntityProperty` function is provided.
+     * @throws GeneralError if a transformation is required for an object or array property but no transformEntityProperty function is provided.
      * @throws GeneralError if coercion of a modified property results in undefined for a non-optional target property.
      */
-    static applyEntityTransform(entity, schemaDiff, options) {
+    static applyEntityTransform(entity, schemaDiff, transformEntityProperty) {
         const newEntity = {};
         for (const property of schemaDiff.unchanged) {
             ObjectHelper.propertySet(newEntity, property.property, ObjectHelper.propertyGet(entity, property.property));
@@ -140,20 +32,20 @@ export class MigrationHelper {
             let defValue;
             if (!(change.optional ?? false)) {
                 if (change.type === EntitySchemaPropertyType.Boolean) {
-                    defValue = false;
+                    defValue = change.defaultValue ?? false;
                 }
                 else if (change.type === EntitySchemaPropertyType.Number ||
                     change.type === EntitySchemaPropertyType.Integer) {
-                    defValue = 0;
+                    defValue = change.defaultValue ?? 0;
                 }
                 else if (change.type === EntitySchemaPropertyType.String) {
-                    defValue = "";
+                    defValue = change.defaultValue ?? "";
                 }
                 else if (change.type === EntitySchemaPropertyType.Array) {
-                    defValue = [];
+                    defValue = change.defaultValue ?? [];
                 }
                 else if (change.type === EntitySchemaPropertyType.Object) {
-                    defValue = {};
+                    defValue = change.defaultValue ?? {};
                 }
             }
             if (Is.notEmpty(defValue)) {
@@ -175,14 +67,14 @@ export class MigrationHelper {
             }
             else if (change.to.type === EntitySchemaPropertyType.Array ||
                 change.to.type === EntitySchemaPropertyType.Object) {
-                if (!Is.function(options?.transformEntityProperty)) {
+                if (!Is.function(transformEntityProperty)) {
                     throw new GeneralError(MigrationHelper.CLASS_NAME, "transformRequiredForProperty", {
                         from: change.from.property,
                         to: change.to.property,
                         type: change.from.type
                     });
                 }
-                newValue = options.transformEntityProperty(change.from, change.to, currentValue);
+                newValue = transformEntityProperty(change.from, change.to, currentValue);
             }
             if (newValue === undefined && !(change.to.optional ?? false)) {
                 throw new GeneralError(MigrationHelper.CLASS_NAME, "coercionProducedUndefined", {
@@ -195,15 +87,96 @@ export class MigrationHelper {
             }
         }
         // Removed properties are simply dropped.
-        // for (const change of schemaDiff.removed) {
-        // }
         return newEntity;
     }
     /**
-     * Startup the connector by calling bootstrap and start if they are defined.
-     * @param connector The connector to startup.
-     * @param loggingComponentType An optional logging component type to use for bootstrapping and starting the connector.
-     * @returns Nothing.
+     * Transforms a single entity through an ordered chain of fully-resolved migration steps.
+     * For each step the method diffs fromProperties against toProperties, then applies
+     * applyEntityTransform. Each step's output feeds the next step's input so that
+     * per-step transformEntityProperty hooks are honoured throughout the chain.
+     * @param entity The entity to transform (at the shape described by steps[0].fromProperties).
+     * @param steps Ordered, fully-resolved migration steps from stored version to current version.
+     * Each step's fromProperties and toProperties are resolved by the caller before invocation.
+     * @returns The entity transformed to the shape described by steps[last].toProperties.
+     */
+    static applyEntityChain(entity, steps) {
+        let current = entity;
+        for (const step of steps) {
+            const diff = EntitySchemaDiffHelper.diff(step.fromProperties, step.toProperties, step.renames);
+            current = MigrationHelper.applyEntityTransform(current, diff, step.transformEntityProperty);
+        }
+        return current;
+    }
+    /**
+     * Performs a chain migration in a single connector swap, regardless of how many version
+     * steps the chain spans. Creates one target connector, reads all source entities, applies
+     * applyEntityChain to each, writes them to the target, then finalizes the migration.
+     * A chain of one step is equivalent to a traditional single-step migration.
+     * @param sourceConnector The connector holding data at the stored schema version.
+     * @param targetSchemaName The schema name for the current version (used to create the target connector).
+     * @param steps Ordered, fully-resolved migration steps from stored to current version.
+     * @param loggingComponentType An optional logging component type for connector startup.
+     * @param batchSize Number of entities to read and write per batch. Defaults to 100.
+     * @returns The finalized connector and the count of migrated entities.
+     */
+    static async migrateWithChain(sourceConnector, targetSchemaName, steps, loggingComponentType, batchSize = 100) {
+        let targetConnector;
+        try {
+            targetConnector = await sourceConnector.createTargetConnector(targetSchemaName);
+            await MigrationHelper.startupConnector(sourceConnector, loggingComponentType);
+            await MigrationHelper.startupConnector(targetConnector, loggingComponentType);
+            let partitionContextIds = await sourceConnector.getPartitionContextIds();
+            if (!Is.arrayValue(partitionContextIds)) {
+                partitionContextIds ??= [];
+                partitionContextIds.push({});
+            }
+            let migrated = 0;
+            const effectivePartitions = partitionContextIds.length > 0 ? partitionContextIds : [{}];
+            const resolvedTarget = targetConnector;
+            for (const contextIds of effectivePartitions) {
+                await ContextIdStore.run(contextIds, async () => {
+                    migrated += await MigrationHelper.migratePartitionWithChain(sourceConnector, resolvedTarget, steps, batchSize);
+                });
+            }
+            const finalConnector = await sourceConnector.finalizeMigration(targetConnector, undefined, loggingComponentType);
+            return { finalConnector, migrated };
+        }
+        catch (error) {
+            await sourceConnector.cleanupMigration(targetConnector, undefined, loggingComponentType);
+            throw new GeneralError(MigrationHelper.CLASS_NAME, "migrationFailed", undefined, error);
+        }
+    }
+    /**
+     * Reads all entities from one partition of the source connector, applies the migration
+     * chain to each entity, and writes the results to the target connector.
+     * @param source The connector to read from (already bootstrapped).
+     * @param target The connector to write to (already bootstrapped).
+     * @param steps Ordered, fully-resolved migration steps.
+     * @param batchSize Number of entities to read and write per batch.
+     * @returns The number of entities migrated.
+     * @internal
+     */
+    static async migratePartitionWithChain(source, target, steps, batchSize) {
+        let migrated = 0;
+        let cursor;
+        const totalEntities = await source.count();
+        if (totalEntities > 0) {
+            do {
+                const page = await source.query(undefined, undefined, undefined, cursor, batchSize);
+                cursor = page.cursor;
+                if (Is.arrayValue(page.entities)) {
+                    const transformedBatch = page.entities.map(entity => MigrationHelper.applyEntityChain(entity, steps));
+                    await target.setBatch(transformedBatch);
+                    migrated += transformedBatch.length;
+                }
+            } while (Is.stringValue(cursor));
+        }
+        return migrated;
+    }
+    /**
+     * Starts the connector by calling bootstrap and start if they are defined.
+     * @param connector The connector to start.
+     * @param loggingComponentType An optional logging component type.
      * @internal
      */
     static async startupConnector(connector, loggingComponentType) {

package/dist/es/helpers/migrationHelper.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrationHelper.js","sourceRoot":"","sources":["../../../src/helpers/migrationHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { ContextIdStore, type IContextIds } from \"@twin.org/context\";\nimport { Coerce, GeneralError, Is, ObjectHelper } from \"@twin.org/core\";\nimport {\n\tEntitySchemaDiffHelper,\n\tEntitySchemaPropertyType,\n\ttype IEntitySchemaDiff\n} from \"@twin.org/entity\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { IEntityStorageConnector } from \"../models/IEntityStorageConnector.js\";\nimport type { IEntityStorageMigrationConnector } from \"../models/IEntityStorageMigrationConnector.js\";\nimport type { IMigrationOptions } from \"../models/IMigrationOptions.js\";\n\n/**\n * Helper class for performing schema migrations between two connectors.\n */\nexport class MigrationHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<MigrationHelper>();\n\n\t/**\n\t * Performs a migration between two connectors, using the provided options and schema diff to control the migration behaviour.\n\t * @param sourceConnector The connector to migrate from to allow the migration helper to create the new connector and finalize the migration.\n\t * @param targetEntitySchemaName The name of the new entity schema.\n\t * @param renames An optional list of property renames to apply during migration.\n\t * @param options Options controlling migration behaviour.\n\t * @param loggingComponentType An optional logging component type to use for bootstrapping and starting connectors if necessary.\n\t * @returns The connector for the new schema and the number of entities successfully migrated, the sourceConnector will no longer be usable, finalConnector will be undefined if no migration was necessary.\n\t */\n\tpublic static async migrate<T, U>(\n\t\tsourceConnector: IEntityStorageMigrationConnector<T>,\n\t\ttargetEntitySchemaName: string,\n\t\trenames?: { from: string; to: string }[],\n\t\toptions?: IMigrationOptions<T, U>,\n\t\tloggingComponentType?: string\n\t): Promise<{\n\t\tfinalConnector?: IEntityStorageConnector<U>;\n\t\tmigrated: number;\n\t}> {\n\t\tlet targetConnector: IEntityStorageConnector<U> | undefined;\n\t\ttry {\n\t\t\t// We use the migration method to create the new connector as it will use a temporary storage location if necessary\n\t\t\ttargetConnector = await sourceConnector.createTargetConnector<U>(targetEntitySchemaName);\n\n\t\t\t// Startup both connectors to ensure they are ready for the migration, this will call bootstrap and start if they are defined.\n\t\t\tawait MigrationHelper.startupConnector<T>(sourceConnector, loggingComponentType);\n\t\t\tawait MigrationHelper.startupConnector<U>(targetConnector, loggingComponentType);\n\n\t\t\t// Get the unique partition context ids to run the migration for each partition.\n\t\t\tlet partitionContextIds = await sourceConnector.getPartitionContextIds();\n\n\t\t\t// If there are no partitions, we still want to run the migration once to handle the schema changes,\n\t\t\t// so we create a single empty context for the migration to run in.\n\t\t\tif (!Is.arrayValue(partitionContextIds)) {\n\t\t\t\tpartitionContextIds ??= [];\n\t\t\t\tpartitionContextIds.push({});\n\t\t\t}\n\n\t\t\t// Get the schemas\n\t\t\tconst sourceSchema = sourceConnector.getSchema();\n\t\t\tconst targetSchema = targetConnector.getSchema();\n\n\t\t\t// Get the schema diff between the source and target schemas.\n\t\t\tconst schemaDiff = EntitySchemaDiffHelper.diff<T, U>(\n\t\t\t\tsourceSchema.properties ?? [],\n\t\t\t\ttargetSchema.properties ?? [],\n\t\t\t\trenames\n\t\t\t);\n\n\t\t\t// Only perform a migration if the schemas have changed\n\t\t\tif (EntitySchemaDiffHelper.hasChanges(schemaDiff)) {\n\t\t\t\t// Perform the migration, which will read from the current store and write to the target connector's store.\n\t\t\t\tconst migrated = await MigrationHelper.migrateEntities<T, U>(\n\t\t\t\t\tsourceConnector,\n\t\t\t\t\ttargetConnector,\n\t\t\t\t\tpartitionContextIds,\n\t\t\t\t\tschemaDiff,\n\t\t\t\t\toptions\n\t\t\t\t);\n\n\t\t\t\t// The migration is now complete, finalize the migration which could entail\n\t\t\t\t// renaming of resources etc, determined by the implementation of finalizeMigration.\n\t\t\t\t// it also needs to stop and teardown any resources no longer in use after the migration,\n\t\t\t\t// such as the old connector and its underlying storage.\n\t\t\t\tconst finalConnector = await sourceConnector.finalizeMigration(\n\t\t\t\t\ttargetConnector,\n\t\t\t\t\toptions,\n\t\t\t\t\tloggingComponentType\n\t\t\t\t);\n\n\t\t\t\treturn {\n\t\t\t\t\tfinalConnector,\n\t\t\t\t\tmigrated\n\t\t\t\t};\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tfinalConnector: undefined,\n\t\t\t\tmigrated: 0\n\t\t\t};\n\t\t} catch (error) {\n\t\t\tawait sourceConnector.cleanupMigration(targetConnector, options, loggingComponentType);\n\n\t\t\tthrow new GeneralError(MigrationHelper.CLASS_NAME, \"migrationFailed\", undefined, error);\n\t\t}\n\t}\n\n\t/**\n\t * Generic per-partition migration loop.\n\t * @param source Connector to read from (current schema, already bootstrapped).\n\t * @param target Connector to write to (new schema, already bootstrapped).\n\t * @param partitionContextIds The context ids to use for the migration, used for partitioning and can be used in the transform function when `options.transformEntityProperty` is provided.\n\t * @param schemaDiff The schema diff.\n\t * @param options Optional migration controls (batchSize, transformEntity, onProgress).\n\t * @returns The number of entities successfully migrated.\n\t */\n\tpublic static async migrateEntities<T = unknown, U = T>(\n\t\tsource: IEntityStorageMigrationConnector<T>,\n\t\ttarget: IEntityStorageConnector<U>,\n\t\tpartitionContextIds: IContextIds[],\n\t\tschemaDiff: IEntitySchemaDiff<T, U>,\n\t\toptions?: IMigrationOptions<T, U>\n\t): Promise<number> {\n\t\tlet migrated = 0;\n\n\t\tawait options?.onStepProgress?.(\"migrationStart\", 0, 0);\n\n\t\tconst effectivePartitions: IContextIds[] =\n\t\t\tpartitionContextIds.length > 0 ? partitionContextIds : [{}];\n\n\t\tfor (let i = 0; i < effectivePartitions.length; i++) {\n\t\t\tawait ContextIdStore.run(effectivePartitions[i], async () => {\n\t\t\t\tawait options?.onStepProgress?.(\"partitionStart\", effectivePartitions.length, i);\n\n\t\t\t\tmigrated += await MigrationHelper.migratePartition(\n\t\t\t\t\tsource,\n\t\t\t\t\ttarget,\n\t\t\t\t\teffectivePartitions.length,\n\t\t\t\t\ti,\n\t\t\t\t\tschemaDiff,\n\t\t\t\t\toptions\n\t\t\t\t);\n\n\t\t\t\tawait options?.onStepProgress?.(\"partitionEnd\", effectivePartitions.length, i);\n\t\t\t});\n\t\t}\n\n\t\tawait options?.onStepProgress?.(\"migrationEnd\", 0, 0);\n\n\t\treturn migrated;\n\t}\n\n\t/**\n\t * Generic per-partition migration loop.\n\t * @param source Connector to read from (current schema, already bootstrapped).\n\t * @param target Connector to write to (new schema, already bootstrapped).\n\t * @param partitionTotal The total number of partitions to migrate, used for progress reporting.\n\t * @param partitionIndex The index of the current partition being migrated, used for progress reporting.\n\t * @param schemaDiff Schema diff used to add nullable defaults and drop removed fields when `options.transformEntity` is not provided.\n\t * @param options Optional migration controls (batchSize, transformEntity, onProgress).\n\t * @returns The number of entities successfully migrated.\n\t */\n\tpublic static async migratePartition<T = unknown, U = unknown>(\n\t\tsource: IEntityStorageConnector<T>,\n\t\ttarget: IEntityStorageConnector<U>,\n\t\tpartitionTotal: number,\n\t\tpartitionIndex: number,\n\t\tschemaDiff: IEntitySchemaDiff<T, U>,\n\t\toptions?: IMigrationOptions<T, U>\n\t): Promise<number> {\n\t\tconst batchSize = options?.batchSize ?? 100;\n\t\tlet migrated = 0;\n\t\tlet cursor: string | undefined;\n\n\t\tconst totalEntities = await source.count();\n\n\t\tawait options?.onPartitionProgress?.(totalEntities, 0);\n\n\t\tif (totalEntities > 0) {\n\t\t\tdo {\n\t\t\t\tconst page = await source.query(undefined, undefined, undefined, cursor, batchSize);\n\t\t\t\tcursor = page.cursor;\n\n\t\t\t\tif (Is.arrayValue(page.entities)) {\n\t\t\t\t\tconst transformedBatch: U[] = [];\n\n\t\t\t\t\tfor (const entity of page.entities) {\n\t\t\t\t\t\tconst transformedEntity = MigrationHelper.applyEntityTransform<T, U>(\n\t\t\t\t\t\t\tentity,\n\t\t\t\t\t\t\tschemaDiff,\n\t\t\t\t\t\t\toptions\n\t\t\t\t\t\t);\n\t\t\t\t\t\ttransformedBatch.push(transformedEntity);\n\t\t\t\t\t}\n\n\t\t\t\t\tawait target.setBatch(transformedBatch);\n\t\t\t\t\tmigrated += transformedBatch.length;\n\t\t\t\t}\n\n\t\t\t\tawait options?.onPartitionProgress?.(totalEntities, migrated);\n\t\t\t} while (Is.stringValue(cursor));\n\t\t}\n\n\t\treturn migrated;\n\t}\n\n\t/**\n\t * Applies the entity transformation for migration, using the provided options and schema diff.\n\t * @param entity The entity to transform.\n\t * @param schemaDiff The schema diff between the old and new schemas.\n\t * @param options The migration options.\n\t * @returns The transformed entity ready to be written to the new schema.\n\t * @throws GeneralError if a transformation is required for an object or array property but no `options.transformEntityProperty` function is provided.\n\t * @throws GeneralError if coercion of a modified property results in undefined for a non-optional target property.\n\t */\n\tpublic static applyEntityTransform<T = unknown, U = unknown>(\n\t\tentity: Partial<T>,\n\t\tschemaDiff: IEntitySchemaDiff<T, U>,\n\t\toptions?: IMigrationOptions<T, U>\n\t): U {\n\t\tconst newEntity = {} as U;\n\n\t\tfor (const property of schemaDiff.unchanged) {\n\t\t\tObjectHelper.propertySet(\n\t\t\t\tnewEntity,\n\t\t\t\tproperty.property as string,\n\t\t\t\tObjectHelper.propertyGet(entity, property.property as string)\n\t\t\t);\n\t\t}\n\n\t\tfor (const change of schemaDiff.added) {\n\t\t\tlet defValue;\n\n\t\t\tif (!(change.optional ?? false)) {\n\t\t\t\tif (change.type === EntitySchemaPropertyType.Boolean) {\n\t\t\t\t\tdefValue = false;\n\t\t\t\t} else if (\n\t\t\t\t\tchange.type === EntitySchemaPropertyType.Number ||\n\t\t\t\t\tchange.type === EntitySchemaPropertyType.Integer\n\t\t\t\t) {\n\t\t\t\t\tdefValue = 0;\n\t\t\t\t} else if (change.type === EntitySchemaPropertyType.String) {\n\t\t\t\t\tdefValue = \"\";\n\t\t\t\t} else if (change.type === EntitySchemaPropertyType.Array) {\n\t\t\t\t\tdefValue = [];\n\t\t\t\t} else if (change.type === EntitySchemaPropertyType.Object) {\n\t\t\t\t\tdefValue = {};\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (Is.notEmpty(defValue)) {\n\t\t\t\tObjectHelper.propertySet(newEntity, change.property as string, defValue);\n\t\t\t}\n\t\t}\n\n\t\tfor (const change of schemaDiff.modified) {\n\t\t\tconst currentValue = ObjectHelper.propertyGet(entity, change.from.property as string);\n\t\t\tlet newValue;\n\n\t\t\tif (change.to.type === EntitySchemaPropertyType.Boolean) {\n\t\t\t\tnewValue = Coerce.boolean(currentValue);\n\t\t\t} else if (\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Number ||\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Integer\n\t\t\t) {\n\t\t\t\tnewValue = Coerce.number(currentValue);\n\t\t\t} else if (change.to.type === EntitySchemaPropertyType.String) {\n\t\t\t\tnewValue = Coerce.string(currentValue);\n\t\t\t} else if (\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Array ||\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Object\n\t\t\t) {\n\t\t\t\tif (!Is.function(options?.transformEntityProperty)) {\n\t\t\t\t\tthrow new GeneralError(MigrationHelper.CLASS_NAME, \"transformRequiredForProperty\", {\n\t\t\t\t\t\tfrom: change.from.property,\n\t\t\t\t\t\tto: change.to.property,\n\t\t\t\t\t\ttype: change.from.type\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tnewValue = options.transformEntityProperty(change.from, change.to, currentValue);\n\t\t\t}\n\n\t\t\tif (newValue === undefined && !(change.to.optional ?? false)) {\n\t\t\t\tthrow new GeneralError(MigrationHelper.CLASS_NAME, \"coercionProducedUndefined\", {\n\t\t\t\t\tproperty: change.to.property,\n\t\t\t\t\ttype: change.to.type\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (Is.notEmpty(newValue)) {\n\t\t\t\tObjectHelper.propertySet(newEntity, change.to.property as string, newValue);\n\t\t\t}\n\t\t}\n\n\t\t// Removed properties are simply dropped.\n\t\t// for (const change of schemaDiff.removed) {\n\t\t// }\n\n\t\treturn newEntity;\n\t}\n\n\t/**\n\t * Startup the connector by calling bootstrap and start if they are defined.\n\t * @param connector The connector to startup.\n\t * @param loggingComponentType An optional logging component type to use for bootstrapping and starting the connector.\n\t * @returns Nothing.\n\t * @internal\n\t */\n\tprivate static async startupConnector<T>(\n\t\tconnector: IEntityStorageConnector<T>,\n\t\tloggingComponentType: string | undefined\n\t): Promise<void> {\n\t\tconst bootstrap = connector.bootstrap?.bind(connector);\n\t\tif (Is.function(bootstrap)) {\n\t\t\tawait bootstrap(loggingComponentType);\n\t\t}\n\t\tconst start = connector.start?.bind(connector);\n\t\tif (Is.function(start)) {\n\t\t\tawait start(loggingComponentType);\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"migrationHelper.js","sourceRoot":"","sources":["../../../src/helpers/migrationHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { ContextIdStore } from \"@twin.org/context\";\nimport { Coerce, GeneralError, Is, ObjectHelper } from \"@twin.org/core\";\nimport {\n\tEntitySchemaDiffHelper,\n\tEntitySchemaPropertyType,\n\ttype IEntitySchemaDiff\n} from \"@twin.org/entity\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { IEntityStorageConnector } from \"../models/IEntityStorageConnector.js\";\nimport type { IEntityStorageMigrationConnector } from \"../models/IEntityStorageMigrationConnector.js\";\nimport type { IMigrationOptions } from \"../models/IMigrationOptions.js\";\nimport type { IResolvedMigrationStep } from \"../models/IResolvedMigrationStep.js\";\n\n/**\n * Helper class for performing entity schema migrations between two connectors.\n * The chain-based API (migrateWithChain / applyEntityChain) is the single migration\n * path: a chain of one step covers the same case as a traditional single-step migration.\n */\nexport class MigrationHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<MigrationHelper>();\n\n\t/**\n\t * Applies the entity transformation for a single diff, handling added, removed, and\n\t * modified properties according to the provided schema diff and optional transform hook.\n\t * @param entity The entity to transform.\n\t * @param schemaDiff The schema diff between the old and new schemas.\n\t * @param transformEntityProperty Optional per-property transform hook for object/array properties.\n\t * @returns The transformed entity ready to be written to the new schema.\n\t * @throws GeneralError if a transformation is required for an object or array property but no transformEntityProperty function is provided.\n\t * @throws GeneralError if coercion of a modified property results in undefined for a non-optional target property.\n\t */\n\tpublic static applyEntityTransform<T = unknown, U = unknown>(\n\t\tentity: Partial<T>,\n\t\tschemaDiff: IEntitySchemaDiff<T, U>,\n\t\ttransformEntityProperty?: IMigrationOptions<T, U>[\"transformEntityProperty\"]\n\t): U {\n\t\tconst newEntity = {} as U;\n\n\t\tfor (const property of schemaDiff.unchanged) {\n\t\t\tObjectHelper.propertySet(\n\t\t\t\tnewEntity,\n\t\t\t\tproperty.property as string,\n\t\t\t\tObjectHelper.propertyGet(entity, property.property as string)\n\t\t\t);\n\t\t}\n\n\t\tfor (const change of schemaDiff.added) {\n\t\t\tlet defValue;\n\n\t\t\tif (!(change.optional ?? false)) {\n\t\t\t\tif (change.type === EntitySchemaPropertyType.Boolean) {\n\t\t\t\t\tdefValue = change.defaultValue ?? false;\n\t\t\t\t} else if (\n\t\t\t\t\tchange.type === EntitySchemaPropertyType.Number ||\n\t\t\t\t\tchange.type === EntitySchemaPropertyType.Integer\n\t\t\t\t) {\n\t\t\t\t\tdefValue = change.defaultValue ?? 0;\n\t\t\t\t} else if (change.type === EntitySchemaPropertyType.String) {\n\t\t\t\t\tdefValue = change.defaultValue ?? \"\";\n\t\t\t\t} else if (change.type === EntitySchemaPropertyType.Array) {\n\t\t\t\t\tdefValue = change.defaultValue ?? [];\n\t\t\t\t} else if (change.type === EntitySchemaPropertyType.Object) {\n\t\t\t\t\tdefValue = change.defaultValue ?? {};\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (Is.notEmpty(defValue)) {\n\t\t\t\tObjectHelper.propertySet(newEntity, change.property as string, defValue);\n\t\t\t}\n\t\t}\n\n\t\tfor (const change of schemaDiff.modified) {\n\t\t\tconst currentValue = ObjectHelper.propertyGet(entity, change.from.property as string);\n\t\t\tlet newValue;\n\n\t\t\tif (change.to.type === EntitySchemaPropertyType.Boolean) {\n\t\t\t\tnewValue = Coerce.boolean(currentValue);\n\t\t\t} else if (\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Number ||\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Integer\n\t\t\t) {\n\t\t\t\tnewValue = Coerce.number(currentValue);\n\t\t\t} else if (change.to.type === EntitySchemaPropertyType.String) {\n\t\t\t\tnewValue = Coerce.string(currentValue);\n\t\t\t} else if (\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Array ||\n\t\t\t\tchange.to.type === EntitySchemaPropertyType.Object\n\t\t\t) {\n\t\t\t\tif (!Is.function(transformEntityProperty)) {\n\t\t\t\t\tthrow new GeneralError(MigrationHelper.CLASS_NAME, \"transformRequiredForProperty\", {\n\t\t\t\t\t\tfrom: change.from.property,\n\t\t\t\t\t\tto: change.to.property,\n\t\t\t\t\t\ttype: change.from.type\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tnewValue = transformEntityProperty(change.from, change.to, currentValue);\n\t\t\t}\n\n\t\t\tif (newValue === undefined && !(change.to.optional ?? false)) {\n\t\t\t\tthrow new GeneralError(MigrationHelper.CLASS_NAME, \"coercionProducedUndefined\", {\n\t\t\t\t\tproperty: change.to.property,\n\t\t\t\t\ttype: change.to.type\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (Is.notEmpty(newValue)) {\n\t\t\t\tObjectHelper.propertySet(newEntity, change.to.property as string, newValue);\n\t\t\t}\n\t\t}\n\n\t\t// Removed properties are simply dropped.\n\n\t\treturn newEntity;\n\t}\n\n\t/**\n\t * Transforms a single entity through an ordered chain of fully-resolved migration steps.\n\t * For each step the method diffs fromProperties against toProperties, then applies\n\t * applyEntityTransform. Each step's output feeds the next step's input so that\n\t * per-step transformEntityProperty hooks are honoured throughout the chain.\n\t * @param entity The entity to transform (at the shape described by steps[0].fromProperties).\n\t * @param steps Ordered, fully-resolved migration steps from stored version to current version.\n\t * Each step's fromProperties and toProperties are resolved by the caller before invocation.\n\t * @returns The entity transformed to the shape described by steps[last].toProperties.\n\t */\n\tpublic static applyEntityChain(entity: unknown, steps: IResolvedMigrationStep[]): unknown {\n\t\tlet current: unknown = entity;\n\t\tfor (const step of steps) {\n\t\t\tconst diff = EntitySchemaDiffHelper.diff(\n\t\t\t\tstep.fromProperties,\n\t\t\t\tstep.toProperties,\n\t\t\t\tstep.renames\n\t\t\t);\n\t\t\tcurrent = MigrationHelper.applyEntityTransform(\n\t\t\t\tcurrent as Partial<unknown>,\n\t\t\t\tdiff,\n\t\t\t\tstep.transformEntityProperty\n\t\t\t);\n\t\t}\n\t\treturn current;\n\t}\n\n\t/**\n\t * Performs a chain migration in a single connector swap, regardless of how many version\n\t * steps the chain spans. Creates one target connector, reads all source entities, applies\n\t * applyEntityChain to each, writes them to the target, then finalizes the migration.\n\t * A chain of one step is equivalent to a traditional single-step migration.\n\t * @param sourceConnector The connector holding data at the stored schema version.\n\t * @param targetSchemaName The schema name for the current version (used to create the target connector).\n\t * @param steps Ordered, fully-resolved migration steps from stored to current version.\n\t * @param loggingComponentType An optional logging component type for connector startup.\n\t * @param batchSize Number of entities to read and write per batch. Defaults to 100.\n\t * @returns The finalized connector and the count of migrated entities.\n\t */\n\tpublic static async migrateWithChain(\n\t\tsourceConnector: IEntityStorageMigrationConnector,\n\t\ttargetSchemaName: string,\n\t\tsteps: IResolvedMigrationStep[],\n\t\tloggingComponentType?: string,\n\t\tbatchSize = 100\n\t): Promise<{\n\t\tfinalConnector: IEntityStorageConnector;\n\t\tmigrated: number;\n\t}> {\n\t\tlet targetConnector: IEntityStorageConnector | undefined;\n\t\ttry {\n\t\t\ttargetConnector = await sourceConnector.createTargetConnector(targetSchemaName);\n\n\t\t\tawait MigrationHelper.startupConnector(sourceConnector, loggingComponentType);\n\t\t\tawait MigrationHelper.startupConnector(targetConnector, loggingComponentType);\n\n\t\t\tlet partitionContextIds = await sourceConnector.getPartitionContextIds();\n\t\t\tif (!Is.arrayValue(partitionContextIds)) {\n\t\t\t\tpartitionContextIds ??= [];\n\t\t\t\tpartitionContextIds.push({});\n\t\t\t}\n\n\t\t\tlet migrated = 0;\n\t\t\tconst effectivePartitions = partitionContextIds.length > 0 ? partitionContextIds : [{}];\n\n\t\t\tconst resolvedTarget = targetConnector;\n\t\t\tfor (const contextIds of effectivePartitions) {\n\t\t\t\tawait ContextIdStore.run(contextIds, async () => {\n\t\t\t\t\tmigrated += await MigrationHelper.migratePartitionWithChain(\n\t\t\t\t\t\tsourceConnector,\n\t\t\t\t\t\tresolvedTarget,\n\t\t\t\t\t\tsteps,\n\t\t\t\t\t\tbatchSize\n\t\t\t\t\t);\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst finalConnector = await sourceConnector.finalizeMigration(\n\t\t\t\ttargetConnector,\n\t\t\t\tundefined,\n\t\t\t\tloggingComponentType\n\t\t\t);\n\n\t\t\treturn { finalConnector, migrated };\n\t\t} catch (error) {\n\t\t\tawait sourceConnector.cleanupMigration(targetConnector, undefined, loggingComponentType);\n\t\t\tthrow new GeneralError(MigrationHelper.CLASS_NAME, \"migrationFailed\", undefined, error);\n\t\t}\n\t}\n\n\t/**\n\t * Reads all entities from one partition of the source connector, applies the migration\n\t * chain to each entity, and writes the results to the target connector.\n\t * @param source The connector to read from (already bootstrapped).\n\t * @param target The connector to write to (already bootstrapped).\n\t * @param steps Ordered, fully-resolved migration steps.\n\t * @param batchSize Number of entities to read and write per batch.\n\t * @returns The number of entities migrated.\n\t * @internal\n\t */\n\tprivate static async migratePartitionWithChain(\n\t\tsource: IEntityStorageMigrationConnector,\n\t\ttarget: IEntityStorageConnector,\n\t\tsteps: IResolvedMigrationStep[],\n\t\tbatchSize: number\n\t): Promise<number> {\n\t\tlet migrated = 0;\n\t\tlet cursor: string | undefined;\n\t\tconst totalEntities = await source.count();\n\n\t\tif (totalEntities > 0) {\n\t\t\tdo {\n\t\t\t\tconst page = await source.query(undefined, undefined, undefined, cursor, batchSize);\n\t\t\t\tcursor = page.cursor;\n\n\t\t\t\tif (Is.arrayValue(page.entities)) {\n\t\t\t\t\tconst transformedBatch: unknown[] = page.entities.map(entity =>\n\t\t\t\t\t\tMigrationHelper.applyEntityChain(entity, steps)\n\t\t\t\t\t);\n\t\t\t\t\tawait target.setBatch(transformedBatch);\n\t\t\t\t\tmigrated += transformedBatch.length;\n\t\t\t\t}\n\t\t\t} while (Is.stringValue(cursor));\n\t\t}\n\n\t\treturn migrated;\n\t}\n\n\t/**\n\t * Starts the connector by calling bootstrap and start if they are defined.\n\t * @param connector The connector to start.\n\t * @param loggingComponentType An optional logging component type.\n\t * @internal\n\t */\n\tprivate static async startupConnector<T>(\n\t\tconnector: IEntityStorageConnector<T>,\n\t\tloggingComponentType: string | undefined\n\t): Promise<void> {\n\t\tconst bootstrap = connector.bootstrap?.bind(connector);\n\t\tif (Is.function(bootstrap)) {\n\t\t\tawait bootstrap(loggingComponentType);\n\t\t}\n\t\tconst start = connector.start?.bind(connector);\n\t\tif (Is.function(start)) {\n\t\t\tawait start(loggingComponentType);\n\t\t}\n\t}\n}\n"]}

package/dist/es/index.js

@@ -1,6 +1,7 @@
-// Copyright 2024 IOTA Stiftung.
+// Copyright 2026 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 export * from "./factories/entityStorageConnectorFactory.js";
+export * from "./factories/schemaMigrationFactory.js";
 export * from "./helpers/entityStorageHelper.js";
 export * from "./helpers/migrationHelper.js";
 export * from "./models/api/IEntityStorageCountRequest.js";
@@ -18,4 +19,6 @@ export * from "./models/IEntityStorageComponent.js";
 export * from "./models/IEntityStorageConnector.js";
 export * from "./models/IEntityStorageMigrationConnector.js";
 export * from "./models/IMigrationOptions.js";
+export * from "./models/IResolvedMigrationStep.js";
+export * from "./models/ISchemaMigration.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,8CAA8C,CAAC;AAC7D,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,0CAA0C,CAAC;AACzD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+BAA+B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/entityStorageConnectorFactory.js\";\nexport * from \"./helpers/entityStorageHelper.js\";\nexport * from \"./helpers/migrationHelper.js\";\nexport * from \"./models/api/IEntityStorageCountRequest.js\";\nexport * from \"./models/api/IEntityStorageCountResponse.js\";\nexport * from \"./models/api/IEntityStorageEmptyRequest.js\";\nexport * from \"./models/api/IEntityStorageGetRequest.js\";\nexport * from \"./models/api/IEntityStorageGetResponse.js\";\nexport * from \"./models/api/IEntityStorageListRequest.js\";\nexport * from \"./models/api/IEntityStorageListResponse.js\";\nexport * from \"./models/api/IEntityStorageRemoveBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageRemoveRequest.js\";\nexport * from \"./models/api/IEntityStorageSetBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageSetRequest.js\";\nexport * from \"./models/IEntityStorageComponent.js\";\nexport * from \"./models/IEntityStorageConnector.js\";\nexport * from \"./models/IEntityStorageMigrationConnector.js\";\nexport * from \"./models/IMigrationOptions.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,0CAA0C,CAAC;AACzD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/entityStorageConnectorFactory.js\";\nexport * from \"./factories/schemaMigrationFactory.js\";\nexport * from \"./helpers/entityStorageHelper.js\";\nexport * from \"./helpers/migrationHelper.js\";\nexport * from \"./models/api/IEntityStorageCountRequest.js\";\nexport * from \"./models/api/IEntityStorageCountResponse.js\";\nexport * from \"./models/api/IEntityStorageEmptyRequest.js\";\nexport * from \"./models/api/IEntityStorageGetRequest.js\";\nexport * from \"./models/api/IEntityStorageGetResponse.js\";\nexport * from \"./models/api/IEntityStorageListRequest.js\";\nexport * from \"./models/api/IEntityStorageListResponse.js\";\nexport * from \"./models/api/IEntityStorageRemoveBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageRemoveRequest.js\";\nexport * from \"./models/api/IEntityStorageSetBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageSetRequest.js\";\nexport * from \"./models/IEntityStorageComponent.js\";\nexport * from \"./models/IEntityStorageConnector.js\";\nexport * from \"./models/IEntityStorageMigrationConnector.js\";\nexport * from \"./models/IMigrationOptions.js\";\nexport * from \"./models/IResolvedMigrationStep.js\";\nexport * from \"./models/ISchemaMigration.js\";\n"]}

package/dist/es/models/IResolvedMigrationStep.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IResolvedMigrationStep.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IResolvedMigrationStep.js","sourceRoot":"","sources":["../../../src/models/IResolvedMigrationStep.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IEntitySchemaProperty } from \"@twin.org/entity\";\nimport type { IMigrationOptions } from \"./IMigrationOptions.js\";\n\n/**\n * A fully-resolved single migration step used by MigrationHelper.\n * The SchemaVersionService builds these by looking up versioned schema classes\n * from EntitySchemaFactory (e.g. MyEntityV0, MyEntityV1) before invoking the helper,\n * keeping factory knowledge out of the helper itself.\n * @template T The entity type. Defaults to `unknown`. Use a concrete entity type\n * when the step's source and target schemas are known at the call site.\n */\nexport interface IResolvedMigrationStep<T = unknown, U = unknown> {\n\t/**\n\t * The property list of the entity at the start of this step (the \"old\" shape).\n\t * Sourced from the versioned schema class registered in EntitySchemaFactory,\n\t * e.g. EntitySchemaFactory.get(\"MyEntityV0\").properties.\n\t */\n\tfromProperties: IEntitySchemaProperty<T>[];\n\n\t/**\n\t * The property list of the entity at the end of this step (the \"new\" shape).\n\t * For the final step this is the live current schema's properties.\n\t */\n\ttoProperties: IEntitySchemaProperty<U>[];\n\n\t/**\n\t * Optional property renames for this step, forwarded to EntitySchemaDiffHelper.diff.\n\t */\n\trenames?: { from: string; to: string }[];\n\n\t/**\n\t * Optional per-property transformer for object/array properties that the structural\n\t * diff cannot handle automatically. Sourced from an ISchemaMigration override when\n\t * one is registered in SchemaMigrationFactory for this step.\n\t */\n\ttransformEntityProperty?: IMigrationOptions<T, U>[\"transformEntityProperty\"];\n}\n"]}

package/dist/es/models/ISchemaMigration.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ISchemaMigration.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ISchemaMigration.js","sourceRoot":"","sources":["../../../src/models/ISchemaMigration.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMigrationOptions } from \"./IMigrationOptions.js\";\n\n/**\n * Optional per-step override for a single version-to-version migration.\n * Only register an entry in SchemaMigrationFactory when a step requires property\n * renames or a custom object/array transform. For purely structural changes\n * (add/remove/type-change fields) no entry is needed — the runner diffs the two\n * versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory\n * automatically.\n *\n * Register under the key \"<BaseSchemaName>_<fromVersion>_<toVersion>\"\n * e.g. \"MyEntity_0_1\" for the step that migrates from version 0 to version 1.\n * The key itself encodes the version pair; no version field is needed on the object.\n */\nexport interface ISchemaMigration<T = unknown, U = unknown> {\n\t/**\n\t * Optional property renames to apply during this step.\n\t */\n\trenames?: { from: string; to: string }[];\n\n\t/**\n\t * Optional per-property transformer for object/array properties that cannot be\n\t * automatically coerced. T is the source entity type, U is the target entity type.\n\t */\n\ttransformEntityProperty?: IMigrationOptions<T, U>[\"transformEntityProperty\"];\n}\n"]}

package/dist/types/factories/schemaMigrationFactory.d.ts

@@ -0,0 +1,14 @@
+import { Factory } from "@twin.org/core";
+import type { ISchemaMigration } from "../models/ISchemaMigration.js";
+/**
+ * Factory for optional per-step migration overrides.
+ *
+ * Only register an entry when a version step requires property renames or a custom
+ * transform hook. For purely structural changes (add/remove/type-change) the
+ * SchemaVersionService diffs the two versioned schema classes automatically
+ * without needing any factory entry.
+ *
+ * Keys follow the convention "<BaseSchemaName>_<fromVersion>_<toVersion>",
+ * for example "MyEntity_0_1" for the step that migrates MyEntity from version 0 to 1.
+ */
+export declare const SchemaMigrationFactory: Factory<ISchemaMigration<unknown, unknown>>;

package/dist/types/helpers/migrationHelper.d.ts

@@ -1,10 +1,12 @@
-import { type IContextIds } from "@twin.org/context";
 import { type IEntitySchemaDiff } from "@twin.org/entity";
 import type { IEntityStorageConnector } from "../models/IEntityStorageConnector.js";
 import type { IEntityStorageMigrationConnector } from "../models/IEntityStorageMigrationConnector.js";
 import type { IMigrationOptions } from "../models/IMigrationOptions.js";
+import type { IResolvedMigrationStep } from "../models/IResolvedMigrationStep.js";
 /**
- * Helper class for performing schema migrations between two connectors.
+ * Helper class for performing entity schema migrations between two connectors.
+ * The chain-based API (migrateWithChain / applyEntityChain) is the single migration
+ * path: a chain of one step covers the same case as a traditional single-step migration.
  */
 export declare class MigrationHelper {
     /**
@@ -12,50 +14,41 @@ export declare class MigrationHelper {
      */
     static readonly CLASS_NAME: string;
     /**
-     * Performs a migration between two connectors, using the provided options and schema diff to control the migration behaviour.
-     * @param sourceConnector The connector to migrate from to allow the migration helper to create the new connector and finalize the migration.
-     * @param targetEntitySchemaName The name of the new entity schema.
-     * @param renames An optional list of property renames to apply during migration.
-     * @param options Options controlling migration behaviour.
-     * @param loggingComponentType An optional logging component type to use for bootstrapping and starting connectors if necessary.
-     * @returns The connector for the new schema and the number of entities successfully migrated, the sourceConnector will no longer be usable, finalConnector will be undefined if no migration was necessary.
-     */
-    static migrate<T, U>(sourceConnector: IEntityStorageMigrationConnector<T>, targetEntitySchemaName: string, renames?: {
-        from: string;
-        to: string;
-    }[], options?: IMigrationOptions<T, U>, loggingComponentType?: string): Promise<{
-        finalConnector?: IEntityStorageConnector<U>;
-        migrated: number;
-    }>;
-    /**
-     * Generic per-partition migration loop.
-     * @param source Connector to read from (current schema, already bootstrapped).
-     * @param target Connector to write to (new schema, already bootstrapped).
-     * @param partitionContextIds The context ids to use for the migration, used for partitioning and can be used in the transform function when `options.transformEntityProperty` is provided.
-     * @param schemaDiff The schema diff.
-     * @param options Optional migration controls (batchSize, transformEntity, onProgress).
-     * @returns The number of entities successfully migrated.
-     */
-    static migrateEntities<T = unknown, U = T>(source: IEntityStorageMigrationConnector<T>, target: IEntityStorageConnector<U>, partitionContextIds: IContextIds[], schemaDiff: IEntitySchemaDiff<T, U>, options?: IMigrationOptions<T, U>): Promise<number>;
-    /**
-     * Generic per-partition migration loop.
-     * @param source Connector to read from (current schema, already bootstrapped).
-     * @param target Connector to write to (new schema, already bootstrapped).
-     * @param partitionTotal The total number of partitions to migrate, used for progress reporting.
-     * @param partitionIndex The index of the current partition being migrated, used for progress reporting.
-     * @param schemaDiff Schema diff used to add nullable defaults and drop removed fields when `options.transformEntity` is not provided.
-     * @param options Optional migration controls (batchSize, transformEntity, onProgress).
-     * @returns The number of entities successfully migrated.
-     */
-    static migratePartition<T = unknown, U = unknown>(source: IEntityStorageConnector<T>, target: IEntityStorageConnector<U>, partitionTotal: number, partitionIndex: number, schemaDiff: IEntitySchemaDiff<T, U>, options?: IMigrationOptions<T, U>): Promise<number>;
-    /**
-     * Applies the entity transformation for migration, using the provided options and schema diff.
+     * Applies the entity transformation for a single diff, handling added, removed, and
+     * modified properties according to the provided schema diff and optional transform hook.
      * @param entity The entity to transform.
      * @param schemaDiff The schema diff between the old and new schemas.
-     * @param options The migration options.
+     * @param transformEntityProperty Optional per-property transform hook for object/array properties.
      * @returns The transformed entity ready to be written to the new schema.
-     * @throws GeneralError if a transformation is required for an object or array property but no `options.transformEntityProperty` function is provided.
+     * @throws GeneralError if a transformation is required for an object or array property but no transformEntityProperty function is provided.
      * @throws GeneralError if coercion of a modified property results in undefined for a non-optional target property.
      */
-    static applyEntityTransform<T = unknown, U = unknown>(entity: Partial<T>, schemaDiff: IEntitySchemaDiff<T, U>, options?: IMigrationOptions<T, U>): U;
+    static applyEntityTransform<T = unknown, U = unknown>(entity: Partial<T>, schemaDiff: IEntitySchemaDiff<T, U>, transformEntityProperty?: IMigrationOptions<T, U>["transformEntityProperty"]): U;
+    /**
+     * Transforms a single entity through an ordered chain of fully-resolved migration steps.
+     * For each step the method diffs fromProperties against toProperties, then applies
+     * applyEntityTransform. Each step's output feeds the next step's input so that
+     * per-step transformEntityProperty hooks are honoured throughout the chain.
+     * @param entity The entity to transform (at the shape described by steps[0].fromProperties).
+     * @param steps Ordered, fully-resolved migration steps from stored version to current version.
+     * Each step's fromProperties and toProperties are resolved by the caller before invocation.
+     * @returns The entity transformed to the shape described by steps[last].toProperties.
+     */
+    static applyEntityChain(entity: unknown, steps: IResolvedMigrationStep[]): unknown;
+    /**
+     * Performs a chain migration in a single connector swap, regardless of how many version
+     * steps the chain spans. Creates one target connector, reads all source entities, applies
+     * applyEntityChain to each, writes them to the target, then finalizes the migration.
+     * A chain of one step is equivalent to a traditional single-step migration.
+     * @param sourceConnector The connector holding data at the stored schema version.
+     * @param targetSchemaName The schema name for the current version (used to create the target connector).
+     * @param steps Ordered, fully-resolved migration steps from stored to current version.
+     * @param loggingComponentType An optional logging component type for connector startup.
+     * @param batchSize Number of entities to read and write per batch. Defaults to 100.
+     * @returns The finalized connector and the count of migrated entities.
+     */
+    static migrateWithChain(sourceConnector: IEntityStorageMigrationConnector, targetSchemaName: string, steps: IResolvedMigrationStep[], loggingComponentType?: string, batchSize?: number): Promise<{
+        finalConnector: IEntityStorageConnector;
+        migrated: number;
+    }>;
 }

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./factories/entityStorageConnectorFactory.js";
+export * from "./factories/schemaMigrationFactory.js";
 export * from "./helpers/entityStorageHelper.js";
 export * from "./helpers/migrationHelper.js";
 export * from "./models/api/IEntityStorageCountRequest.js";
@@ -16,3 +17,5 @@ export * from "./models/IEntityStorageComponent.js";
 export * from "./models/IEntityStorageConnector.js";
 export * from "./models/IEntityStorageMigrationConnector.js";
 export * from "./models/IMigrationOptions.js";
+export * from "./models/IResolvedMigrationStep.js";
+export * from "./models/ISchemaMigration.js";

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

@@ -0,0 +1,36 @@
+import type { IEntitySchemaProperty } from "@twin.org/entity";
+import type { IMigrationOptions } from "./IMigrationOptions.js";
+/**
+ * A fully-resolved single migration step used by MigrationHelper.
+ * The SchemaVersionService builds these by looking up versioned schema classes
+ * from EntitySchemaFactory (e.g. MyEntityV0, MyEntityV1) before invoking the helper,
+ * keeping factory knowledge out of the helper itself.
+ * @template T The entity type. Defaults to `unknown`. Use a concrete entity type
+ * when the step's source and target schemas are known at the call site.
+ */
+export interface IResolvedMigrationStep<T = unknown, U = unknown> {
+    /**
+     * The property list of the entity at the start of this step (the "old" shape).
+     * Sourced from the versioned schema class registered in EntitySchemaFactory,
+     * e.g. EntitySchemaFactory.get("MyEntityV0").properties.
+     */
+    fromProperties: IEntitySchemaProperty<T>[];
+    /**
+     * The property list of the entity at the end of this step (the "new" shape).
+     * For the final step this is the live current schema's properties.
+     */
+    toProperties: IEntitySchemaProperty<U>[];
+    /**
+     * Optional property renames for this step, forwarded to EntitySchemaDiffHelper.diff.
+     */
+    renames?: {
+        from: string;
+        to: string;
+    }[];
+    /**
+     * Optional per-property transformer for object/array properties that the structural
+     * diff cannot handle automatically. Sourced from an ISchemaMigration override when
+     * one is registered in SchemaMigrationFactory for this step.
+     */
+    transformEntityProperty?: IMigrationOptions<T, U>["transformEntityProperty"];
+}

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

@@ -0,0 +1,27 @@
+import type { IMigrationOptions } from "./IMigrationOptions.js";
+/**
+ * Optional per-step override for a single version-to-version migration.
+ * Only register an entry in SchemaMigrationFactory when a step requires property
+ * renames or a custom object/array transform. For purely structural changes
+ * (add/remove/type-change fields) no entry is needed — the runner diffs the two
+ * versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory
+ * automatically.
+ *
+ * Register under the key "<BaseSchemaName>_<fromVersion>_<toVersion>"
+ * e.g. "MyEntity_0_1" for the step that migrates from version 0 to version 1.
+ * The key itself encodes the version pair; no version field is needed on the object.
+ */
+export interface ISchemaMigration<T = unknown, U = unknown> {
+    /**
+     * Optional property renames to apply during this step.
+     */
+    renames?: {
+        from: string;
+        to: string;
+    }[];
+    /**
+     * Optional per-property transformer for object/array properties that cannot be
+     * automatically coerced. T is the source entity type, U is the target entity type.
+     */
+    transformEntityProperty?: IMigrationOptions<T, U>["transformEntityProperty"];
+}

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.0.3-next.22](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-models-v0.0.3-next.21...entity-storage-models-v0.0.3-next.22) (2026-06-08)
+
+
+### Features
+
+* add ISchemaMigration chain, SchemaVersionMigrator runner and version store ([#110](https://github.com/iotaledger/twin-entity-storage/issues/110)) ([2dac924](https://github.com/iotaledger/twin-entity-storage/commit/2dac9244a752cb58304d1649ff03c3a2469783dd))
+
 ## [0.0.3-next.21](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-models-v0.0.3-next.20...entity-storage-models-v0.0.3-next.21) (2026-06-01)
 
 

package/docs/reference/classes/MigrationHelper.md

@@ -1,6 +1,8 @@
 # Class: MigrationHelper
 
-Helper class for performing schema migrations between two connectors.
+Helper class for performing entity schema migrations between two connectors.
+The chain-based API (migrateWithChain / applyEntityChain) is the single migration
+path: a chain of one step covers the same case as a traditional single-step migration.
 
 ## Constructors
 
@@ -22,67 +24,12 @@ Runtime name for the class.
 
 ## Methods
 
-### migrate() {#migrate}
-
-> `static` **migrate**\<`T`, `U`\>(`sourceConnector`, `targetEntitySchemaName`, `renames?`, `options?`, `loggingComponentType?`): `Promise`\<\{ `finalConnector?`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md)\<`U`\>; `migrated`: `number`; \}\>
-
-Performs a migration between two connectors, using the provided options and schema diff to control the migration behaviour.
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-##### U
-
-`U`
-
-#### Parameters
-
-##### sourceConnector
-
-[`IEntityStorageMigrationConnector`](../interfaces/IEntityStorageMigrationConnector.md)\<`T`\>
-
-The connector to migrate from to allow the migration helper to create the new connector and finalize the migration.
-
-##### targetEntitySchemaName
-
-`string`
-
-The name of the new entity schema.
-
-##### renames?
-
-`object`[]
-
-An optional list of property renames to apply during migration.
-
-##### options?
-
-[`IMigrationOptions`](../interfaces/IMigrationOptions.md)\<`T`, `U`\>
-
-Options controlling migration behaviour.
-
-##### loggingComponentType?
-
-`string`
-
-An optional logging component type to use for bootstrapping and starting connectors if necessary.
-
-#### Returns
-
-`Promise`\<\{ `finalConnector?`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md)\<`U`\>; `migrated`: `number`; \}\>
-
-The connector for the new schema and the number of entities successfully migrated, the sourceConnector will no longer be usable, finalConnector will be undefined if no migration was necessary.
-
-***
-
-### migrateEntities() {#migrateentities}
+### applyEntityTransform() {#applyentitytransform}
 
-> `static` **migrateEntities**\<`T`, `U`\>(`source`, `target`, `partitionContextIds`, `schemaDiff`, `options?`): `Promise`\<`number`\>
+> `static` **applyEntityTransform**\<`T`, `U`\>(`entity`, `schemaDiff`, `transformEntityProperty?`): `U`
 
-Generic per-partition migration loop.
+Applies the entity transformation for a single diff, handling added, removed, and
+modified properties according to the provided schema diff and optional transform hook.
 
 #### Type Parameters
 
@@ -92,156 +39,119 @@ Generic per-partition migration loop.
 
 ##### U
 
-`U` = `T`
+`U` = `unknown`
 
 #### Parameters
 
-##### source
-
-[`IEntityStorageMigrationConnector`](../interfaces/IEntityStorageMigrationConnector.md)\<`T`\>
-
-Connector to read from (current schema, already bootstrapped).
-
-##### target
-
-[`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md)\<`U`\>
-
-Connector to write to (new schema, already bootstrapped).
-
-##### partitionContextIds
+##### entity
 
-`IContextIds`[]
+`Partial`\<`T`\>
 
-The context ids to use for the migration, used for partitioning and can be used in the transform function when `options.transformEntityProperty` is provided.
+The entity to transform.
 
 ##### schemaDiff
 
 `IEntitySchemaDiff`\<`T`, `U`\>
 
-The schema diff.
+The schema diff between the old and new schemas.
 
-##### options?
+##### transformEntityProperty?
 
-[`IMigrationOptions`](../interfaces/IMigrationOptions.md)\<`T`, `U`\>
+(`schema1Property`, `schemaProperty2`, `value`) => `unknown`
 
-Optional migration controls (batchSize, transformEntity, onProgress).
+Optional per-property transform hook for object/array properties.
 
 #### Returns
 
-`Promise`\<`number`\>
-
-The number of entities successfully migrated.
+`U`
 
-***
+The transformed entity ready to be written to the new schema.
 
-### migratePartition() {#migratepartition}
+#### Throws
 
-> `static` **migratePartition**\<`T`, `U`\>(`source`, `target`, `partitionTotal`, `partitionIndex`, `schemaDiff`, `options?`): `Promise`\<`number`\>
+GeneralError if a transformation is required for an object or array property but no transformEntityProperty function is provided.
 
-Generic per-partition migration loop.
+#### Throws
 
-#### Type Parameters
+GeneralError if coercion of a modified property results in undefined for a non-optional target property.
 
-##### T
+***
 
-`T` = `unknown`
+### applyEntityChain() {#applyentitychain}
 
-##### U
+> `static` **applyEntityChain**(`entity`, `steps`): `unknown`
 
-`U` = `unknown`
+Transforms a single entity through an ordered chain of fully-resolved migration steps.
+For each step the method diffs fromProperties against toProperties, then applies
+applyEntityTransform. Each step's output feeds the next step's input so that
+per-step transformEntityProperty hooks are honoured throughout the chain.
 
 #### Parameters
 
-##### source
-
-[`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md)\<`T`\>
-
-Connector to read from (current schema, already bootstrapped).
-
-##### target
-
-[`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md)\<`U`\>
-
-Connector to write to (new schema, already bootstrapped).
-
-##### partitionTotal
-
-`number`
-
-The total number of partitions to migrate, used for progress reporting.
-
-##### partitionIndex
-
-`number`
-
-The index of the current partition being migrated, used for progress reporting.
-
-##### schemaDiff
+##### entity
 
-`IEntitySchemaDiff`\<`T`, `U`\>
+`unknown`
 
-Schema diff used to add nullable defaults and drop removed fields when `options.transformEntity` is not provided.
+The entity to transform (at the shape described by steps[0].fromProperties).
 
-##### options?
+##### steps
 
-[`IMigrationOptions`](../interfaces/IMigrationOptions.md)\<`T`, `U`\>
+[`IResolvedMigrationStep`](../interfaces/IResolvedMigrationStep.md)\<`unknown`, `unknown`\>[]
 
-Optional migration controls (batchSize, transformEntity, onProgress).
+Ordered, fully-resolved migration steps from stored version to current version.
+Each step's fromProperties and toProperties are resolved by the caller before invocation.
 
 #### Returns
 
-`Promise`\<`number`\>
+`unknown`
 
-The number of entities successfully migrated.
+The entity transformed to the shape described by steps[last].toProperties.
 
 ***
 
-### applyEntityTransform() {#applyentitytransform}
+### migrateWithChain() {#migratewithchain}
 
-> `static` **applyEntityTransform**\<`T`, `U`\>(`entity`, `schemaDiff`, `options?`): `U`
+> `static` **migrateWithChain**(`sourceConnector`, `targetSchemaName`, `steps`, `loggingComponentType?`, `batchSize?`): `Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
 
-Applies the entity transformation for migration, using the provided options and schema diff.
+Performs a chain migration in a single connector swap, regardless of how many version
+steps the chain spans. Creates one target connector, reads all source entities, applies
+applyEntityChain to each, writes them to the target, then finalizes the migration.
+A chain of one step is equivalent to a traditional single-step migration.
 
-#### Type Parameters
-
-##### T
-
-`T` = `unknown`
-
-##### U
+#### Parameters
 
-`U` = `unknown`
+##### sourceConnector
 
-#### Parameters
+[`IEntityStorageMigrationConnector`](../interfaces/IEntityStorageMigrationConnector.md)
 
-##### entity
+The connector holding data at the stored schema version.
 
-`Partial`\<`T`\>
+##### targetSchemaName
 
-The entity to transform.
+`string`
 
-##### schemaDiff
+The schema name for the current version (used to create the target connector).
 
-`IEntitySchemaDiff`\<`T`, `U`\>
+##### steps
 
-The schema diff between the old and new schemas.
+[`IResolvedMigrationStep`](../interfaces/IResolvedMigrationStep.md)\<`unknown`, `unknown`\>[]
 
-##### options?
+Ordered, fully-resolved migration steps from stored to current version.
 
-[`IMigrationOptions`](../interfaces/IMigrationOptions.md)\<`T`, `U`\>
+##### loggingComponentType?
 
-The migration options.
+`string`
 
-#### Returns
+An optional logging component type for connector startup.
 
-`U`
+##### batchSize?
 
-The transformed entity ready to be written to the new schema.
+`number` = `100`
 
-#### Throws
+Number of entities to read and write per batch. Defaults to 100.
 
-GeneralError if a transformation is required for an object or array property but no `options.transformEntityProperty` function is provided.
+#### Returns
 
-#### Throws
+`Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
 
-GeneralError if coercion of a modified property results in undefined for a non-optional target property.
+The finalized connector and the count of migrated entities.

package/docs/reference/index.md

@@ -11,6 +11,8 @@
 - [IEntityStorageConnector](interfaces/IEntityStorageConnector.md)
 - [IEntityStorageMigrationConnector](interfaces/IEntityStorageMigrationConnector.md)
 - [IMigrationOptions](interfaces/IMigrationOptions.md)
+- [IResolvedMigrationStep](interfaces/IResolvedMigrationStep.md)
+- [ISchemaMigration](interfaces/ISchemaMigration.md)
 - [IEntityStorageCountRequest](interfaces/IEntityStorageCountRequest.md)
 - [IEntityStorageCountResponse](interfaces/IEntityStorageCountResponse.md)
 - [IEntityStorageEmptyRequest](interfaces/IEntityStorageEmptyRequest.md)
@@ -26,3 +28,4 @@
 ## Variables
 
 - [EntityStorageConnectorFactory](variables/EntityStorageConnectorFactory.md)
+- [SchemaMigrationFactory](variables/SchemaMigrationFactory.md)

package/docs/reference/interfaces/IResolvedMigrationStep.md

@@ -0,0 +1,82 @@
+# Interface: IResolvedMigrationStep\<T, U\>
+
+A fully-resolved single migration step used by MigrationHelper.
+The SchemaVersionService builds these by looking up versioned schema classes
+from EntitySchemaFactory (e.g. MyEntityV0, MyEntityV1) before invoking the helper,
+keeping factory knowledge out of the helper itself.
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+The entity type. Defaults to `unknown`. Use a concrete entity type
+when the step's source and target schemas are known at the call site.
+
+### U
+
+`U` = `unknown`
+
+## Properties
+
+### fromProperties {#fromproperties}
+
+> **fromProperties**: `IEntitySchemaProperty`\<`T`\>[]
+
+The property list of the entity at the start of this step (the "old" shape).
+Sourced from the versioned schema class registered in EntitySchemaFactory,
+e.g. EntitySchemaFactory.get("MyEntityV0").properties.
+
+***
+
+### toProperties {#toproperties}
+
+> **toProperties**: `IEntitySchemaProperty`\<`U`\>[]
+
+The property list of the entity at the end of this step (the "new" shape).
+For the final step this is the live current schema's properties.
+
+***
+
+### renames? {#renames}
+
+> `optional` **renames?**: `object`[]
+
+Optional property renames for this step, forwarded to EntitySchemaDiffHelper.diff.
+
+#### from
+
+> **from**: `string`
+
+#### to
+
+> **to**: `string`
+
+***
+
+### transformEntityProperty? {#transformentityproperty}
+
+> `optional` **transformEntityProperty?**: (`schema1Property`, `schemaProperty2`, `value`) => `unknown`
+
+Optional per-property transformer for object/array properties that the structural
+diff cannot handle automatically. Sourced from an ISchemaMigration override when
+one is registered in SchemaMigrationFactory for this step.
+
+#### Parameters
+
+##### schema1Property
+
+`IEntitySchemaProperty`\<`T`\>
+
+##### schemaProperty2
+
+`IEntitySchemaProperty`\<`U`\>
+
+##### value
+
+`unknown`
+
+#### Returns
+
+`unknown`

package/docs/reference/interfaces/ISchemaMigration.md

@@ -0,0 +1,65 @@
+# Interface: ISchemaMigration\<T, U\>
+
+Optional per-step override for a single version-to-version migration.
+Only register an entry in SchemaMigrationFactory when a step requires property
+renames or a custom object/array transform. For purely structural changes
+(add/remove/type-change fields) no entry is needed — the runner diffs the two
+versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory
+automatically.
+
+Register under the key "<BaseSchemaName>_<fromVersion>_<toVersion>"
+e.g. "MyEntity_0_1" for the step that migrates from version 0 to version 1.
+The key itself encodes the version pair; no version field is needed on the object.
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+### U
+
+`U` = `unknown`
+
+## Properties
+
+### renames? {#renames}
+
+> `optional` **renames?**: `object`[]
+
+Optional property renames to apply during this step.
+
+#### from
+
+> **from**: `string`
+
+#### to
+
+> **to**: `string`
+
+***
+
+### transformEntityProperty? {#transformentityproperty}
+
+> `optional` **transformEntityProperty?**: (`schema1Property`, `schemaProperty2`, `value`) => `unknown`
+
+Optional per-property transformer for object/array properties that cannot be
+automatically coerced. T is the source entity type, U is the target entity type.
+
+#### Parameters
+
+##### schema1Property
+
+`IEntitySchemaProperty`\<`T`\>
+
+##### schemaProperty2
+
+`IEntitySchemaProperty`\<`U`\>
+
+##### value
+
+`unknown`
+
+#### Returns
+
+`unknown`

package/docs/reference/variables/SchemaMigrationFactory.md

@@ -0,0 +1,13 @@
+# Variable: SchemaMigrationFactory
+
+> `const` **SchemaMigrationFactory**: `Factory`\<[`ISchemaMigration`](../interfaces/ISchemaMigration.md)\<`unknown`, `unknown`\>\>
+
+Factory for optional per-step migration overrides.
+
+Only register an entry when a version step requires property renames or a custom
+transform hook. For purely structural changes (add/remove/type-change) the
+SchemaVersionService diffs the two versioned schema classes automatically
+without needing any factory entry.
+
+Keys follow the convention "<BaseSchemaName>_<fromVersion>_<toVersion>",
+for example "MyEntity_0_1" for the step that migrates MyEntity from version 0 to 1.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-models",
-	"version": "0.0.3-next.21",
+	"version": "0.0.3-next.22",
 	"description": "Shared models for storage contracts, requests, responses and connector capabilities.",
 	"repository": {
 		"type": "git",