@twin.org/entity-storage-models 0.0.3-next.24 → 0.0.3-next.25

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

@@ -1,4 +1,4 @@
-import type { IMigrationOptions } from "./IMigrationOptions.js";
+import type { EntityPropertyTransformer } from "./entityPropertyTransformer.js";
 /**
  * Optional per-step override for a single version-to-version migration.
  * Only register an entry in SchemaMigrationFactory when a step requires property
@@ -20,8 +20,11 @@ export interface ISchemaMigration<T = unknown, U = unknown> {
         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.
+     * Optional transformation for properties, usually only called for object and array types.
+     * @param schema1Property The property schema in the old schema.
+     * @param schemaProperty2 The property schema in the new schema.
+     * @param value The value of the property in the old schema.
+     * @returns The transformed value to match the new schema.
      */
-    transformEntityProperty?: IMigrationOptions<T, U>["transformEntityProperty"];
+    transformEntityProperty?: EntityPropertyTransformer<T, U>;
 }

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

@@ -0,0 +1,6 @@
+import type { IEntitySchemaProperty } from "@twin.org/entity";
+/**
+ * Type for the optional transformEntityProperty function.
+ * Used in migration steps for custom property transformations.
+ */
+export type EntityPropertyTransformer<T = unknown, U = unknown> = (schema1Property: IEntitySchemaProperty<T>, schemaProperty2: IEntitySchemaProperty<U>, value: unknown) => unknown;

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.0.3-next.25](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-models-v0.0.3-next.24...entity-storage-models-v0.0.3-next.25) (2026-06-09)
+
+
+### Features
+
+* migration progress ([#121](https://github.com/iotaledger/twin-entity-storage/issues/121)) ([d032162](https://github.com/iotaledger/twin-entity-storage/commit/d032162768b6b7d4ccca7e39b80f8bc3ba46440e))
+
 ## [0.0.3-next.24](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-models-v0.0.3-next.23...entity-storage-models-v0.0.3-next.24) (2026-06-08)
 
 

package/docs/reference/classes/MigrationHelper.md

@@ -24,56 +24,93 @@ Runtime name for the class.
 
 ## Methods
 
-### applyEntityTransform() {#applyentitytransform}
+### migrateWithChain() {#migratewithchain}
 
-> `static` **applyEntityTransform**\<`T`, `U`\>(`entity`, `schemaDiff`, `transformEntityProperty?`): `U`
+> `static` **migrateWithChain**(`sourceConnector`, `targetSchemaName`, `steps`, `options?`, `loggingComponentType?`): `Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
 
-Applies the entity transformation for a single diff, handling added, removed, and
-modified properties according to the provided schema diff and optional transform hook.
+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
+#### Parameters
 
-##### T
+##### sourceConnector
 
-`T` = `unknown`
+[`IEntityStorageMigrationConnector`](../interfaces/IEntityStorageMigrationConnector.md)
 
-##### U
+The connector holding data at the stored schema version.
 
-`U` = `unknown`
+##### targetSchemaName
 
-#### Parameters
+`string`
 
-##### entity
+The schema name for the current version (used to create the target connector).
 
-`Partial`\<`T`\>
+##### steps
 
-The entity to transform.
+[`IResolvedMigrationStep`](../interfaces/IResolvedMigrationStep.md)\<`unknown`, `unknown`\>[]
 
-##### schemaDiff
+Ordered, fully-resolved migration steps from stored to current version.
 
-`IEntitySchemaDiff`\<`T`, `U`\>
+##### options?
 
-The schema diff between the old and new schemas.
+[`IMigrationOptions`](../interfaces/IMigrationOptions.md)
 
-##### transformEntityProperty?
+Optional migration options.
 
-(`schema1Property`, `schemaProperty2`, `value`) => `unknown`
+##### loggingComponentType?
 
-Optional per-property transform hook for object/array properties.
+`string`
+
+The optional component type to use for logging the migration progress.
 
 #### Returns
 
-`U`
+`Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
 
-The transformed entity ready to be written to the new schema.
+The finalized connector and the count of migrated entities.
 
-#### Throws
+***
 
-GeneralError if a transformation is required for an object or array property but no transformEntityProperty function is provided.
+### migratePartitionWithChain() {#migratepartitionwithchain}
 
-#### Throws
+> `static` **migratePartitionWithChain**(`source`, `target`, `steps`, `options?`): `Promise`\<`number`\>
 
-GeneralError if coercion of a modified property results in undefined for a non-optional target property.
+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.
+
+#### Parameters
+
+##### source
+
+[`IEntityStorageMigrationConnector`](../interfaces/IEntityStorageMigrationConnector.md)
+
+The connector to read from (already bootstrapped).
+
+##### target
+
+[`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md)
+
+The connector to write to (already bootstrapped).
+
+##### steps
+
+[`IResolvedMigrationStep`](../interfaces/IResolvedMigrationStep.md)\<`unknown`, `unknown`\>[]
+
+Ordered, fully-resolved migration steps.
+
+##### options?
+
+[`IMigrationOptions`](../interfaces/IMigrationOptions.md)
+
+Optional migration options (batchSize, progress callbacks, transformEntityProperty).
+
+#### Returns
+
+`Promise`\<`number`\>
+
+The number of entities migrated.
 
 ***
 
@@ -109,49 +146,53 @@ The entity transformed to the shape described by steps[last].toProperties.
 
 ***
 
-### migrateWithChain() {#migratewithchain}
-
-> `static` **migrateWithChain**(`sourceConnector`, `targetSchemaName`, `steps`, `loggingComponentType?`, `batchSize?`): `Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
+### applyEntityTransform() {#applyentitytransform}
 
-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.
+> `static` **applyEntityTransform**\<`T`, `U`\>(`entity`, `schemaDiff`, `transformEntityProperty?`): `U`
 
-#### Parameters
+Applies the entity transformation for a single diff, handling added, removed, and
+modified properties according to the provided schema diff and optional transform hook.
 
-##### sourceConnector
+#### Type Parameters
 
-[`IEntityStorageMigrationConnector`](../interfaces/IEntityStorageMigrationConnector.md)
+##### T
 
-The connector holding data at the stored schema version.
+`T` = `unknown`
 
-##### targetSchemaName
+##### U
 
-`string`
+`U` = `unknown`
 
-The schema name for the current version (used to create the target connector).
+#### Parameters
 
-##### steps
+##### entity
 
-[`IResolvedMigrationStep`](../interfaces/IResolvedMigrationStep.md)\<`unknown`, `unknown`\>[]
+`Partial`\<`T`\>
 
-Ordered, fully-resolved migration steps from stored to current version.
+The entity to transform.
 
-##### loggingComponentType?
+##### schemaDiff
 
-`string`
+`IEntitySchemaDiff`\<`T`, `U`\>
 
-An optional logging component type for connector startup.
+The schema diff between the old and new schemas.
 
-##### batchSize?
+##### transformEntityProperty?
 
-`number` = `100`
+[`EntityPropertyTransformer`](../type-aliases/EntityPropertyTransformer.md)\<`T`, `U`\>
 
-Number of entities to read and write per batch. Defaults to 100.
+Optional per-property transform hook for object/array properties.
 
 #### Returns
 
-`Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
+`U`
 
-The finalized connector and the count of migrated entities.
+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 transformEntityProperty function is provided.
+
+#### Throws
+
+GeneralError if coercion of a modified property results in undefined for a non-optional target property.

package/docs/reference/index.md

@@ -2,10 +2,8 @@
 
 ## Classes
 
-- [SchemaVersion](classes/SchemaVersion.md)
 - [EntityStorageHelper](classes/EntityStorageHelper.md)
 - [MigrationHelper](classes/MigrationHelper.md)
-- [SchemaVersionService](classes/SchemaVersionService.md)
 
 ## Interfaces
 
@@ -27,11 +25,11 @@
 - [IEntityStorageSetBatchRequest](interfaces/IEntityStorageSetBatchRequest.md)
 - [IEntityStorageSetRequest](interfaces/IEntityStorageSetRequest.md)
 
+## Type Aliases
+
+- [EntityPropertyTransformer](type-aliases/EntityPropertyTransformer.md)
+
 ## Variables
 
 - [EntityStorageConnectorFactory](variables/EntityStorageConnectorFactory.md)
 - [SchemaMigrationFactory](variables/SchemaMigrationFactory.md)
-
-## Functions
-
-- [initSchema](functions/initSchema.md)

package/docs/reference/interfaces/IEntityStorageMigrationConnector.md

@@ -345,7 +345,7 @@ The target connector to finalize the migration with.
 
 ##### options?
 
-[`IMigrationOptions`](IMigrationOptions.md)\<`T`, `U`\>
+[`IMigrationOptions`](IMigrationOptions.md)
 
 The options to control how the migration is finalized.
 
@@ -385,7 +385,7 @@ The target connector to cleanup the migration with.
 
 ##### options?
 
-[`IMigrationOptions`](IMigrationOptions.md)\<`T`, `U`\>
+[`IMigrationOptions`](IMigrationOptions.md)
 
 The options to control how the migration is cleaned up.
 

package/docs/reference/interfaces/IMigrationOptions.md

@@ -1,17 +1,7 @@
-# Interface: IMigrationOptions\<T, U\>
+# Interface: IMigrationOptions
 
 Options controlling how a schema migration is executed.
 
-## Type Parameters
-
-### T
-
-`T`
-
-### U
-
-`U`
-
 ## Properties
 
 ### batchSize? {#batchsize}
@@ -28,91 +18,31 @@ Number of entities to read and write per batch.
 
 ***
 
-### transformEntityProperty? {#transformentityproperty}
-
-> `optional` **transformEntityProperty?**: (`schema1Property`, `schemaProperty2`, `value`) => `unknown`
-
-Optional transformation for properties, usually only called for object and array types.
-
-#### Parameters
-
-##### schema1Property
-
-`IEntitySchemaProperty`\<`T`\>
-
-The property schema in the old schema.
-
-##### schemaProperty2
-
-`IEntitySchemaProperty`\<`U`\>
-
-The property schema in the new schema.
-
-##### value
-
-`unknown`
-
-The value of the property in the old schema.
-
-#### Returns
-
-`unknown`
-
-The transformed value to match the new schema.
-
-***
-
-### onPartitionProgress? {#onpartitionprogress}
-
-> `optional` **onPartitionProgress?**: (`rowTotal`, `rowIndex`) => `Promise`\<`void`\>
-
-Called for each partition for progress tracking.
-
-#### Parameters
-
-##### rowTotal
-
-`number`
-
-The total number of rows to migrate.
-
-##### rowIndex
-
-`number`
-
-The number of rows migrated so far.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### onStepProgress? {#onstepprogress}
+### onProgress? {#onprogress}
 
-> `optional` **onStepProgress?**: (`stepKey`, `itemTotal`, `itemIndex`) => `Promise`\<`void`\>
+> `optional` **onProgress?**: (`progressItem`, `itemTotal`, `itemIndex`) => `Promise`\<`void`\>
 
-Called for overall progress tracking.
+Called for progress tracking.
 
 #### Parameters
 
-##### stepKey
+##### progressItem
 
-`string`
+`"partitionStart"` \| `"partitionProgress"` \| `"partitionEnd"` \| `"partitionItemsStart"` \| `"partitionItemsProgress"` \| `"partitionItemsEnd"`
 
-The key representing the current step in the migration.
+The item progress being updated.
 
 ##### itemTotal
 
 `number`
 
-The total number of items in this progress.
+The total number of rows to migrate.
 
 ##### itemIndex
 
 `number`
 
-The number of items processed so far.
+The number of rows migrated so far.
 
 #### Returns
 

package/docs/reference/interfaces/IResolvedMigrationStep.md

@@ -57,26 +57,22 @@ Optional property renames for this step, forwarded to EntitySchemaDiffHelper.dif
 
 ### transformEntityProperty? {#transformentityproperty}
 
-> `optional` **transformEntityProperty?**: (`schema1Property`, `schemaProperty2`, `value`) => `unknown`
+> `optional` **transformEntityProperty?**: [`EntityPropertyTransformer`](../type-aliases/EntityPropertyTransformer.md)\<`T`, `U`\>
 
-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.
+Optional transformation for properties, usually only called for object and array types.
 
-#### Parameters
+#### Param
 
-##### schema1Property
+The property schema in the old schema.
 
-`IEntitySchemaProperty`\<`T`\>
+#### Param
 
-##### schemaProperty2
+The property schema in the new schema.
 
-`IEntitySchemaProperty`\<`U`\>
+#### Param
 
-##### value
-
-`unknown`
+The value of the property in the old schema.
 
 #### Returns
 
-`unknown`
+The transformed value to match the new schema.

package/docs/reference/interfaces/ISchemaMigration.md

@@ -41,25 +41,22 @@ Optional property renames to apply during this step.
 
 ### transformEntityProperty? {#transformentityproperty}
 
-> `optional` **transformEntityProperty?**: (`schema1Property`, `schemaProperty2`, `value`) => `unknown`
+> `optional` **transformEntityProperty?**: [`EntityPropertyTransformer`](../type-aliases/EntityPropertyTransformer.md)\<`T`, `U`\>
 
-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.
+Optional transformation for properties, usually only called for object and array types.
 
-#### Parameters
+#### Param
 
-##### schema1Property
+The property schema in the old schema.
 
-`IEntitySchemaProperty`\<`T`\>
+#### Param
 
-##### schemaProperty2
+The property schema in the new schema.
 
-`IEntitySchemaProperty`\<`U`\>
+#### Param
 
-##### value
-
-`unknown`
+The value of the property in the old schema.
 
 #### Returns
 
-`unknown`
+The transformed value to match the new schema.

package/docs/reference/type-aliases/EntityPropertyTransformer.md

@@ -0,0 +1,34 @@
+# Type Alias: EntityPropertyTransformer\<T, U\>
+
+> **EntityPropertyTransformer**\<`T`, `U`\> = (`schema1Property`, `schemaProperty2`, `value`) => `unknown`
+
+Type for the optional transformEntityProperty function.
+Used in migration steps for custom property transformations.
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+### U
+
+`U` = `unknown`
+
+## Parameters
+
+### schema1Property
+
+`IEntitySchemaProperty`\<`T`\>
+
+### schemaProperty2
+
+`IEntitySchemaProperty`\<`U`\>
+
+### value
+
+`unknown`
+
+## Returns
+
+`unknown`

package/locales/en.json

@@ -5,15 +5,16 @@
 			"propertyNotInSchema": "The property \"{property}\" does not exist in the schema and cannot be used for projection"
 		},
 		"migrationHelper": {
-			"migrationFailed": "Migration failed.",
+			"migrateSchemaFailed": "Migration failed for schema \"{schemaName}\".",
 			"transformRequiredForProperty": "A transformation function is required to migrate property \"{from}\" to \"{to}\" of type \"{type}\"",
 			"coercionProducedUndefined": "Coercion of property \"{property}\" to type \"{type}\" produced undefined but the property is not optional"
-		},
-		"schemaVersionService": {
-			"storedVersionNewer": "Stored schema version ({stored}) for \"{schemaName}\" is newer than the current version ({current}). Downgrade is not supported.",
-			"noMigrationStep": "No migration step from version {missingFromVersion} to {missingToVersion} found for \"{schemaName}\". Cannot complete migration from {stored} to {current}. Register the versioned schema class \"{schemaName}V{missingFromVersion}\" in EntitySchemaFactory.",
-			"noMigrationStepTarget": "No target schema for migration step {missingFromVersion} to {missingToVersion} found for \"{schemaName}\". Cannot complete migration from {stored} to {current}. Register the versioned schema class \"{schemaName}V{missingToVersion}\" in EntitySchemaFactory.",
-			"connectorNotMigrationCapable": "Schema \"{schemaName}\" needs migration from version {stored} to {current} but its connector does not support automatic migration. Please migrate the schema manually before starting the node."
+		}
+	},
+	"info": {
+		"migrationHelper": {
+			"migrateSchemaStarting": "Migrating schema \"{schemaName}\"",
+			"migrateSchemaFinalizing": "Finalizing migration of schema \"{schemaName}\"",
+			"migrateSchemaComplete": "Migration of schema \"{schemaName}\" complete"
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-models",
-	"version": "0.0.3-next.24",
+	"version": "0.0.3-next.25",
 	"description": "Shared models for storage contracts, requests, responses and connector capabilities.",
 	"repository": {
 		"type": "git",
@@ -17,6 +17,7 @@
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
+		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next"
 	},
 	"main": "./dist/es/index.js",

package/dist/es/entities/schemaVersion.js

@@ -1,39 +0,0 @@
-// Copyright 2026 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-import { entity, property } from "@twin.org/entity";
-/**
- * Tracks the currently applied schema version for each managed entity schema.
- * One record per schema name. Written once on first boot, then updated after
- * each successful migration.
- */
-let SchemaVersion = class SchemaVersion {
-    /**
-     * The entity schema type name — primary key.
-     */
-    schemaName;
-    /**
-     * The currently deployed version of this schema.
-     */
-    version;
-    /**
-     * ISO 8601 timestamp of the last version write.
-     */
-    updatedAt;
-};
-__decorate([
-    property({ type: "string", isPrimary: true }),
-    __metadata("design:type", String)
-], SchemaVersion.prototype, "schemaName", void 0);
-__decorate([
-    property({ type: "integer" }),
-    __metadata("design:type", Number)
-], SchemaVersion.prototype, "version", void 0);
-__decorate([
-    property({ type: "string", format: "date-time" }),
-    __metadata("design:type", String)
-], SchemaVersion.prototype, "updatedAt", void 0);
-SchemaVersion = __decorate([
-    entity()
-], SchemaVersion);
-export { SchemaVersion };
-//# sourceMappingURL=schemaVersion.js.map

package/dist/es/entities/schemaVersion.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"schemaVersion.js","sourceRoot":"","sources":["../../../src/entities/schemaVersion.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAa;IACzB;;OAEG;IAEI,UAAU,CAAU;IAE3B;;OAEG;IAEI,OAAO,CAAU;IAExB;;OAEG;IAEI,SAAS,CAAU;CAC1B,CAAA;AAbO;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;;iDACnB;AAMpB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;;8CACN;AAMjB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;;gDACxB;AAjBd,aAAa;IADzB,MAAM,EAAE;GACI,aAAa,CAkBzB","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { entity, property } from \"@twin.org/entity\";\n\n/**\n * Tracks the currently applied schema version for each managed entity schema.\n * One record per schema name. Written once on first boot, then updated after\n * each successful migration.\n */\n@entity()\nexport class SchemaVersion {\n\t/**\n\t * The entity schema type name — primary key.\n\t */\n\t@property({ type: \"string\", isPrimary: true })\n\tpublic schemaName!: string;\n\n\t/**\n\t * The currently deployed version of this schema.\n\t */\n\t@property({ type: \"integer\" })\n\tpublic version!: number;\n\n\t/**\n\t * ISO 8601 timestamp of the last version write.\n\t */\n\t@property({ type: \"string\", format: \"date-time\" })\n\tpublic updatedAt!: string;\n}\n"]}

package/dist/es/schema.js

@@ -1,11 +0,0 @@
-// Copyright 2026 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-import { EntitySchemaFactory, EntitySchemaHelper } from "@twin.org/entity";
-import { SchemaVersion } from "./entities/schemaVersion.js";
-/**
- * Initialize the schema for the entity storage models.
- */
-export function initSchema() {
-    EntitySchemaFactory.register("SchemaVersion", () => EntitySchemaHelper.getSchema(SchemaVersion));
-}
-//# sourceMappingURL=schema.js.map

package/dist/es/schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D;;GAEG;AACH,MAAM,UAAU,UAAU;IACzB,mBAAmB,CAAC,QAAQ,kBAA0B,GAAG,EAAE,CAC1D,kBAAkB,CAAC,SAAS,CAAC,aAAa,CAAC,CAC3C,CAAC;AACH,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { EntitySchemaFactory, EntitySchemaHelper } from \"@twin.org/entity\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { SchemaVersion } from \"./entities/schemaVersion.js\";\n\n/**\n * Initialize the schema for the entity storage models.\n */\nexport function initSchema(): void {\n\tEntitySchemaFactory.register(nameof<SchemaVersion>(), () =>\n\t\tEntitySchemaHelper.getSchema(SchemaVersion)\n\t);\n}\n"]}