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

package/docs/reference/classes/EntityStorageService.md

@@ -34,7 +34,7 @@ The dependencies for the entity storage service.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -42,7 +42,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -60,9 +60,9 @@ The class name of the component.
 
 ***
 
-### set()
+### set() {#set}
 
-> **set**(`entity`): `Promise`\<`void`\>
+> **set**(`entity`, `conditions?`): `Promise`\<`void`\>
 
 Set an entity.
 
@@ -74,6 +74,12 @@ Set an entity.
 
 The entity to set.
 
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -86,9 +92,35 @@ The id of the entity.
 
 ***
 
-### get()
+### setBatch() {#setbatch}
+
+> **setBatch**(`entities`): `Promise`\<`void`\>
+
+Set multiple entities in a batch.
+
+#### Parameters
+
+##### entities
+
+`T`[]
+
+The entities to set.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageComponent.setBatch`
+
+***
+
+### get() {#get}
 
-> **get**(`id`, `secondaryIndex?`): `Promise`\<`T` \| `undefined`\>
+> **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`T` \| `undefined`\>
 
 Get an entity.
 
@@ -106,6 +138,12 @@ keyof `T`
 
 Get the item using a secondary index.
 
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
 #### Returns
 
 `Promise`\<`T` \| `undefined`\>
@@ -118,9 +156,9 @@ The object if it can be found or undefined.
 
 ***
 
-### remove()
+### remove() {#remove}
 
-> **remove**(`id`): `Promise`\<`void`\>
+> **remove**(`id`, `conditions?`): `Promise`\<`void`\>
 
 Remove the entity.
 
@@ -132,6 +170,12 @@ Remove the entity.
 
 The id of the entity to remove.
 
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -144,7 +188,77 @@ Nothing.
 
 ***
 
-### query()
+### removeBatch() {#removebatch}
+
+> **removeBatch**(`ids`): `Promise`\<`void`\>
+
+Remove multiple entities by id.
+
+#### Parameters
+
+##### ids
+
+`string`[]
+
+The ids of the entities to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageComponent.removeBatch`
+
+***
+
+### empty() {#empty}
+
+> **empty**(): `Promise`\<`void`\>
+
+Remove all entities from the storage.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageComponent.empty`
+
+***
+
+### count() {#count}
+
+> **count**(`conditions?`): `Promise`\<`number`\>
+
+Count all the entities which match the conditions.
+
+#### Parameters
+
+##### conditions?
+
+`EntityCondition`\<`T`\>
+
+The optional conditions to match for the entities.
+
+#### Returns
+
+`Promise`\<`number`\>
+
+The total count of entities in the storage.
+
+#### Implementation of
+
+`IEntityStorageComponent.count`
+
+***
+
+### query() {#query}
 
 > **query**(`conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 

package/docs/reference/classes/SchemaVersion.md

@@ -0,0 +1,39 @@
+# Class: SchemaVersion
+
+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.
+
+## Constructors
+
+### Constructor
+
+> **new SchemaVersion**(): `SchemaVersion`
+
+#### Returns
+
+`SchemaVersion`
+
+## Properties
+
+### schemaName {#schemaname}
+
+> **schemaName**: `string`
+
+The entity schema type name — primary key.
+
+***
+
+### version {#version}
+
+> **version**: `number`
+
+The currently deployed version of this schema.
+
+***
+
+### updatedAt {#updatedat}
+
+> **updatedAt**: `string`
+
+ISO 8601 timestamp of the last version write.

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

@@ -4,9 +4,9 @@ Examples for the entity storage routes.
 
 ## Properties
 
-### set?
+### set? {#set}
 
-> `optional` **set**: `object`
+> `optional` **set?**: `object`
 
 Examples for the set route.
 
@@ -16,9 +16,9 @@ Examples for the set route.
 
 ***
 
-### get?
+### get? {#get}
 
-> `optional` **get**: `object`
+> `optional` **get?**: `object`
 
 Examples for the get route.
 
@@ -32,9 +32,9 @@ Examples for the get route.
 
 ***
 
-### remove?
+### remove? {#remove}
 
-> `optional` **remove**: `object`
+> `optional` **remove?**: `object`
 
 Examples for the remove route.
 
@@ -44,9 +44,9 @@ Examples for the remove route.
 
 ***
 
-### list?
+### list? {#list}
 
-> `optional` **list**: `object`
+> `optional` **list?**: `object`
 
 Examples for the list route.
 
@@ -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/IEntityStorageServiceConstructorOptions.md

@@ -4,7 +4,7 @@ Options for the Entity Storage Service constructor.
 
 ## Properties
 
-### entityStorageType
+### entityStorageType {#entitystoragetype}
 
 > **entityStorageType**: `string`
 
@@ -12,8 +12,8 @@ The type of the entity storage.
 
 ***
 
-### config?
+### config? {#config}
 
-> `optional` **config**: [`IEntityStorageServiceConfig`](IEntityStorageServiceConfig.md)
+> `optional` **config?**: [`IEntityStorageServiceConfig`](IEntityStorageServiceConfig.md)
 
 The configuration for the service.

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.3",
-	"description": "Entity Storage contract implementation and REST endpoint definitions",
+	"version": "0.0.3-next.30",
+	"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",
@@ -17,7 +17,8 @@
 		"@twin.org/api-models": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.0.3-next.3",
+		"@twin.org/entity-storage-models": "0.0.3-next.30",
+		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/web": "next"
 	},
@@ -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"
 }