@twin.org/entity-storage-service 0.0.3-next.9 → 0.9.0-next.1

package/docs/reference/classes/SchemaVersionService.md

@@ -0,0 +1,103 @@
+# Class: SchemaVersionService
+
+Service that checks and applies entity schema migrations at every node start-up.
+
+This service must be the first entry in coreTypeInitialisers.json. The engine iterates that
+array in order to determine start sequence — there is no engine-level priority mechanism, so
+registration position is the only guarantee that start() runs before any other service.
+By the time start() is called, all component bootstraps have completed (every table already
+exists) and EntitySchemaFactory / EntityStorageConnectorFactory are fully populated with every
+registered schema and connector.
+
+Migration mechanics: old schema versions are registered in EntitySchemaFactory by naming
+convention — current schema = "MyEntity", first history = "MyEntityV0", second = "MyEntityV1".
+The service groups schemas by base name (strips the trailing V number suffix) and resolves the
+migration chain automatically by diffing consecutive versioned schemas. For steps that require
+property renames or a custom transform hook, register an optional ISchemaMigration entry in
+SchemaMigrationFactory under the key "Base_from_to" (e.g. "MyEntity_0_1").
+
+Crash-window note: finalizeMigration and the subsequent version-record write are two
+separate operations. If the process dies between them the next boot re-runs the chain
+over already-migrated data. applyEntityTransform is NOT idempotent for structural changes
+(newly-added optional fields would be dropped on re-run). A transaction spanning both
+writes is a precondition for production; track this in the concurrency follow-up.
+
+## Implements
+
+- `IComponent`
+
+## Constructors
+
+### Constructor
+
+> **new SchemaVersionService**(`options?`): `SchemaVersionService`
+
+Create a new SchemaVersionService.
+
+#### Parameters
+
+##### options?
+
+[`ISchemaVersionServiceConstructorOptions`](../interfaces/ISchemaVersionServiceConstructorOptions.md)
+
+Optional constructor options.
+
+#### Returns
+
+`SchemaVersionService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name.
+
+#### Returns
+
+`string`
+
+The class name.
+
+#### Implementation of
+
+`IComponent.className`
+
+***
+
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+Reads all registered entity schemas, groups versioned schemas by base name, reads the
+full schemaVersion table in one pass, then orchestrates chain migrations for any schema
+whose stored version is behind the current version declared in EntitySchemaFactory.
+SchemaVersion itself is processed first so the version store is migrated before any
+version records are written for other schemas.
+
+Runs after all component bootstraps, so every managed table already exists.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+An optional logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+`IComponent.start`

package/docs/reference/functions/entityStorageCount.md

@@ -0,0 +1,31 @@
+# Function: entityStorageCount()
+
+> **entityStorageCount**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IEntityStorageCountResponse`\>
+
+Count the entries in entity storage.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IEntityStorageCountRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IEntityStorageCountResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/entityStorageEmpty.md

@@ -0,0 +1,31 @@
+# Function: entityStorageEmpty()
+
+> **entityStorageEmpty**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Remove all entries from entity storage.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IEntityStorageEmptyRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/entityStorageRemoveBatch.md

@@ -0,0 +1,31 @@
+# Function: entityStorageRemoveBatch()
+
+> **entityStorageRemoveBatch**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Remove multiple entries from entity storage by id.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IEntityStorageRemoveBatchRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/entityStorageSetBatch.md

@@ -0,0 +1,31 @@
+# Function: entityStorageSetBatch()
+
+> **entityStorageSetBatch**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Set multiple entries in entity storage.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IEntityStorageSetBatchRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/initSchema.md

@@ -0,0 +1,9 @@
+# Function: initSchema()
+
+> **initSchema**(): `void`
+
+Initialize the schema for the entity storage models.
+
+## Returns
+
+`void`

package/docs/reference/index.md

@@ -2,13 +2,17 @@
 
 ## Classes
 
+- [SchemaVersion](classes/SchemaVersion.md)
 - [EntityStorageService](classes/EntityStorageService.md)
+- [SchemaVersionService](classes/SchemaVersionService.md)
 
 ## Interfaces
 
 - [IEntityStorageRoutesExamples](interfaces/IEntityStorageRoutesExamples.md)
 - [IEntityStorageServiceConfig](interfaces/IEntityStorageServiceConfig.md)
 - [IEntityStorageServiceConstructorOptions](interfaces/IEntityStorageServiceConstructorOptions.md)
+- [ISchemaVersionServiceConfig](interfaces/ISchemaVersionServiceConfig.md)
+- [ISchemaVersionServiceConstructorOptions](interfaces/ISchemaVersionServiceConstructorOptions.md)
 
 ## Variables
 
@@ -19,6 +23,11 @@
 
 - [generateRestRoutesEntityStorage](functions/generateRestRoutesEntityStorage.md)
 - [entityStorageSet](functions/entityStorageSet.md)
+- [entityStorageSetBatch](functions/entityStorageSetBatch.md)
+- [entityStorageEmpty](functions/entityStorageEmpty.md)
 - [entityStorageGet](functions/entityStorageGet.md)
 - [entityStorageRemove](functions/entityStorageRemove.md)
 - [entityStorageList](functions/entityStorageList.md)
+- [entityStorageCount](functions/entityStorageCount.md)
+- [entityStorageRemoveBatch](functions/entityStorageRemoveBatch.md)
+- [initSchema](functions/initSchema.md)

package/docs/reference/interfaces/IEntityStorageRoutesExamples.md

@@ -57,3 +57,19 @@ Examples for the list route.
 #### responseExamples
 
 > **responseExamples**: `IRestRouteResponseExample`\<`IEntityStorageListResponse`\>[]
+
+***
+
+### count? {#count}
+
+> `optional` **count?**: `object`
+
+Examples for the count route.
+
+#### requestExamples
+
+> **requestExamples**: `IRestRouteRequestExample`\<`IEntityStorageCountRequest`\>[]
+
+#### responseExamples
+
+> **responseExamples**: `IRestRouteResponseExample`\<`IEntityStorageCountResponse`\>[]

package/docs/reference/interfaces/ISchemaVersionServiceConfig.md

@@ -0,0 +1,11 @@
+# Interface: ISchemaVersionServiceConfig
+
+Constructor options config for SchemaVersionService.
+
+## Properties
+
+### batchSize? {#batchsize}
+
+> `optional` **batchSize?**: `number`
+
+The batch size for processing schema versions.

package/docs/reference/interfaces/ISchemaVersionServiceConstructorOptions.md

@@ -0,0 +1,25 @@
+# Interface: ISchemaVersionServiceConstructorOptions
+
+Constructor options for SchemaVersionService.
+
+## Properties
+
+### schemaVersionStorageType? {#schemaversionstoragetype}
+
+> `optional` **schemaVersionStorageType?**: `string`
+
+The version storage type.
+
+#### Default
+
+```ts
+schema-version
+```
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: [`ISchemaVersionServiceConfig`](ISchemaVersionServiceConfig.md)
+
+Optional config.

package/locales/en.json

@@ -1,7 +1,22 @@
 {
 	"error": {
-		"entityStorageService": {
-			"entityNotFound": "Could not find entity with id \"{notFoundId}\""
+		"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": {
+		"schemaVersionService": {
+			"noMigrationRequired": "No migration required for schema \"{schemaName}\", version {version}.",
+			"migrationRequired": "Migration required for schema \"{schemaName}\" from version {from} to {to}.",
+			"partitionStart": "Starting migration of {itemTotal} partitions.",
+			"partitionProgress": "Migrating partition {itemIndex} of {itemTotal}.",
+			"partitionEnd": "Completed migration of {itemTotal} partitions.",
+			"partitionItemsStart": "Starting migration of {itemTotal} items in current partition.",
+			"partitionItemsProgress": "Migrating items in current partition: {itemIndex} of {itemTotal} processed.",
+			"partitionItemsEnd": "Completed migration of {itemTotal} items in current partition."
 		}
 	}
 }

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/entity-storage-service",
-	"version": "0.0.3-next.9",
+	"version": "0.9.0-next.1",
 	"description": "Service layer exposing storage contracts and REST endpoint definitions.",
 	"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-service"
 	},
 	"author": "martyn.janes@iota.org",
@@ -14,12 +14,13 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/api-models": "next",
-		"@twin.org/core": "next",
-		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.0.3-next.9",
-		"@twin.org/nameof": "next",
-		"@twin.org/web": "next"
+		"@twin.org/api-models": "0.9.0-next.1",
+		"@twin.org/core": "0.9.0-next.1",
+		"@twin.org/entity": "0.9.0-next.1",
+		"@twin.org/entity-storage-models": "0.9.0-next.1",
+		"@twin.org/logging-models": "0.9.0-next.1",
+		"@twin.org/nameof": "0.9.0-next.1",
+		"@twin.org/web": "0.9.0-next.1"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",
@@ -53,7 +54,7 @@
 		"business-logic"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/entity-storage/issues"
+		"url": "git+https://github.com/iotaledger/twin-entity-storage/issues"
 	},
 	"homepage": "https://twindev.org"
 }