@twin.org/entity-storage-models 0.0.3-next.3 → 0.0.3-next.30

package/docs/reference/interfaces/IEntityStorageRemoveRequest.md

@@ -4,7 +4,7 @@ Remove an entry from entity storage.
 
 ## Properties
 
-### pathParams
+### pathParams {#pathparams}
 
 > **pathParams**: `object`
 
@@ -15,3 +15,17 @@ The parameters from the path.
 > **id**: `string`
 
 The id of the entity to remove.
+
+***
+
+### query? {#query}
+
+> `optional` **query?**: `object`
+
+The query parameters.
+
+#### conditions?
+
+> `optional` **conditions?**: `string`
+
+The optional conditions to match for the entity, JSON encoded array of property/value pairs.

package/docs/reference/interfaces/IEntityStorageSetBatchRequest.md

@@ -0,0 +1,11 @@
+# Interface: IEntityStorageSetBatchRequest
+
+Set multiple entries in entity storage.
+
+## Properties
+
+### body {#body}
+
+> **body**: `unknown`[]
+
+The entities to set.

package/docs/reference/interfaces/IEntityStorageSetRequest.md

@@ -4,8 +4,22 @@ Set an entry in entity storage.
 
 ## Properties
 
-### body
+### body {#body}
 
 > **body**: `unknown`
 
 The data to be used in the entity.
+
+***
+
+### query? {#query}
+
+> `optional` **query?**: `object`
+
+The query parameters.
+
+#### conditions?
+
+> `optional` **conditions?**: `string`
+
+The optional conditions to match for the entity, JSON encoded array of property/value pairs.

package/docs/reference/interfaces/IMigrationOptions.md

@@ -0,0 +1,49 @@
+# Interface: IMigrationOptions
+
+Options controlling how a schema migration is executed.
+
+## Properties
+
+### batchSize? {#batchsize}
+
+> `optional` **batchSize?**: `number`
+
+Number of entities to read and write per batch.
+
+#### Default
+
+```ts
+100
+```
+
+***
+
+### onProgress? {#onprogress}
+
+> `optional` **onProgress?**: (`progressItem`, `itemTotal`, `itemIndex`) => `Promise`\<`void`\>
+
+Called for progress tracking.
+
+#### Parameters
+
+##### progressItem
+
+`"partitionStart"` \| `"partitionProgress"` \| `"partitionEnd"` \| `"partitionItemsStart"` \| `"partitionItemsProgress"` \| `"partitionItemsEnd"`
+
+The item progress being updated.
+
+##### itemTotal
+
+`number`
+
+The total number of rows to migrate.
+
+##### itemIndex
+
+`number`
+
+The number of rows migrated so far.
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/reference/interfaces/IResolvedMigrationStep.md

@@ -0,0 +1,78 @@
+# 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?**: [`EntityPropertyTransformer`](../type-aliases/EntityPropertyTransformer.md)\<`T`, `U`\>
+
+Optional transformation for properties, usually only called for object and array types.
+
+#### Param
+
+The property schema in the old schema.
+
+#### Param
+
+The property schema in the new schema.
+
+#### Param
+
+The value of the property in the old schema.
+
+#### Returns
+
+The transformed value to match the new schema.

package/docs/reference/interfaces/ISchemaMigration.md

@@ -0,0 +1,62 @@
+# 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?**: [`EntityPropertyTransformer`](../type-aliases/EntityPropertyTransformer.md)\<`T`, `U`\>
+
+Optional transformation for properties, usually only called for object and array types.
+
+#### Param
+
+The property schema in the old schema.
+
+#### Param
+
+The property schema in the new schema.
+
+#### Param
+
+The value of the property in the old schema.
+
+#### Returns
+
+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/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/locales/en.json

@@ -1,3 +1,20 @@
 {
-	"error": {}
+	"error": {
+		"entityStorageHelper": {
+			"sortNotIndexed": "The property \"{property}\" is not indexed and cannot be used for sorting",
+			"propertyNotInSchema": "The property \"{property}\" does not exist in the schema and cannot be used for projection"
+		},
+		"migrationHelper": {
+			"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"
+		}
+	},
+	"info": {
+		"migrationHelper": {
+			"migrateSchemaStarting": "Migrating schema \"{schemaName}\"",
+			"migrateSchemaFinalizing": "Finalizing migration of schema \"{schemaName}\"",
+			"migrateSchemaComplete": "Migration of schema \"{schemaName}\" complete"
+		}
+	}
 }

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/entity-storage-models",
-	"version": "0.0.3-next.3",
-	"description": "Models which define the structure of the entity storage contracts and connectors",
+	"version": "0.0.3-next.30",
+	"description": "Shared models for storage contracts, requests, responses and connector capabilities.",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/twinfoundation/entity-storage.git",
+		"url": "git+https://github.com/iotaledger/twin-entity-storage.git",
 		"directory": "packages/entity-storage-models"
 	},
 	"author": "martyn.janes@iota.org",
@@ -14,8 +14,10 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
+		"@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",
@@ -50,7 +52,7 @@
 		"schemas"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/entity-storage/issues"
+		"url": "git+https://github.com/iotaledger/twin-entity-storage/issues"
 	},
 	"homepage": "https://twindev.org"
 }