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

package/docs/reference/classes/MigrationHelper.md

@@ -0,0 +1,247 @@
+# Class: MigrationHelper
+
+Helper class for performing schema migrations between two connectors.
+
+## Constructors
+
+### Constructor
+
+> **new MigrationHelper**(): `MigrationHelper`
+
+#### Returns
+
+`MigrationHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+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}
+
+> `static` **migrateEntities**\<`T`, `U`\>(`source`, `target`, `partitionContextIds`, `schemaDiff`, `options?`): `Promise`\<`number`\>
+
+Generic per-partition migration loop.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+##### U
+
+`U` = `T`
+
+#### 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
+
+`IContextIds`[]
+
+The context ids to use for the migration, used for partitioning and can be used in the transform function when `options.transformEntityProperty` is provided.
+
+##### schemaDiff
+
+`IEntitySchemaDiff`\<`T`, `U`\>
+
+The schema diff.
+
+##### options?
+
+[`IMigrationOptions`](../interfaces/IMigrationOptions.md)\<`T`, `U`\>
+
+Optional migration controls (batchSize, transformEntity, onProgress).
+
+#### Returns
+
+`Promise`\<`number`\>
+
+The number of entities successfully migrated.
+
+***
+
+### migratePartition() {#migratepartition}
+
+> `static` **migratePartition**\<`T`, `U`\>(`source`, `target`, `partitionTotal`, `partitionIndex`, `schemaDiff`, `options?`): `Promise`\<`number`\>
+
+Generic per-partition migration loop.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+##### U
+
+`U` = `unknown`
+
+#### 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
+
+`IEntitySchemaDiff`\<`T`, `U`\>
+
+Schema diff used to add nullable defaults and drop removed fields when `options.transformEntity` is not provided.
+
+##### options?
+
+[`IMigrationOptions`](../interfaces/IMigrationOptions.md)\<`T`, `U`\>
+
+Optional migration controls (batchSize, transformEntity, onProgress).
+
+#### Returns
+
+`Promise`\<`number`\>
+
+The number of entities successfully migrated.
+
+***
+
+### applyEntityTransform() {#applyentitytransform}
+
+> `static` **applyEntityTransform**\<`T`, `U`\>(`entity`, `schemaDiff`, `options?`): `U`
+
+Applies the entity transformation for migration, using the provided options and schema diff.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+##### U
+
+`U` = `unknown`
+
+#### Parameters
+
+##### entity
+
+`Partial`\<`T`\>
+
+The entity to transform.
+
+##### schemaDiff
+
+`IEntitySchemaDiff`\<`T`, `U`\>
+
+The schema diff between the old and new schemas.
+
+##### options?
+
+[`IMigrationOptions`](../interfaces/IMigrationOptions.md)\<`T`, `U`\>
+
+The migration options.
+
+#### Returns
+
+`U`
+
+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 coercion of a modified property results in undefined for a non-optional target property.

package/docs/reference/index.md

@@ -1,14 +1,26 @@
 # @twin.org/entity-storage-models
 
+## Classes
+
+- [EntityStorageHelper](classes/EntityStorageHelper.md)
+- [MigrationHelper](classes/MigrationHelper.md)
+
 ## Interfaces
 
 - [IEntityStorageComponent](interfaces/IEntityStorageComponent.md)
 - [IEntityStorageConnector](interfaces/IEntityStorageConnector.md)
+- [IEntityStorageMigrationConnector](interfaces/IEntityStorageMigrationConnector.md)
+- [IMigrationOptions](interfaces/IMigrationOptions.md)
+- [IEntityStorageCountRequest](interfaces/IEntityStorageCountRequest.md)
+- [IEntityStorageCountResponse](interfaces/IEntityStorageCountResponse.md)
+- [IEntityStorageEmptyRequest](interfaces/IEntityStorageEmptyRequest.md)
 - [IEntityStorageGetRequest](interfaces/IEntityStorageGetRequest.md)
 - [IEntityStorageGetResponse](interfaces/IEntityStorageGetResponse.md)
 - [IEntityStorageListRequest](interfaces/IEntityStorageListRequest.md)
 - [IEntityStorageListResponse](interfaces/IEntityStorageListResponse.md)
+- [IEntityStorageRemoveBatchRequest](interfaces/IEntityStorageRemoveBatchRequest.md)
 - [IEntityStorageRemoveRequest](interfaces/IEntityStorageRemoveRequest.md)
+- [IEntityStorageSetBatchRequest](interfaces/IEntityStorageSetBatchRequest.md)
 - [IEntityStorageSetRequest](interfaces/IEntityStorageSetRequest.md)
 
 ## Variables

package/docs/reference/interfaces/IEntityStorageComponent.md

@@ -14,9 +14,9 @@ Interface describing an entity storage component.
 
 ## Methods
 
-### set()
+### set() {#set}
 
-> **set**(`entity`): `Promise`\<`void`\>
+> **set**(`entity`, `conditions?`): `Promise`\<`void`\>
 
 Set an entity.
 
@@ -28,6 +28,12 @@ Set an entity.
 
 The entity to set.
 
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -36,9 +42,31 @@ 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.
+
+***
+
+### get() {#get}
 
-> **get**(`id`, `secondaryIndex?`): `Promise`\<`T` \| `undefined`\>
+> **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`T` \| `undefined`\>
 
 Get an entity.
 
@@ -56,6 +84,12 @@ keyof `T`
 
 Get the item using a secondary index.
 
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
 #### Returns
 
 `Promise`\<`T` \| `undefined`\>
@@ -64,9 +98,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.
 
@@ -78,6 +112,12 @@ Remove the entity.
 
 The id of the entity to remove.
 
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -86,7 +126,29 @@ 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.
+
+***
+
+### query() {#query}
 
 > **query**(`conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 
@@ -136,3 +198,39 @@ The suggested number of entities to return in each chunk, in some scenarios can
 
 All the entities for the storage matching the conditions,
 and a cursor which can be used to request more entities.
+
+***
+
+### empty() {#empty}
+
+> **empty**(): `Promise`\<`void`\>
+
+Remove all entities from the storage.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+***
+
+### 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.

package/docs/reference/interfaces/IEntityStorageConnector.md

@@ -6,6 +6,10 @@ Interface describing an entity storage connector.
 
 - `IComponent`
 
+## Extended by
+
+- [`IEntityStorageMigrationConnector`](IEntityStorageMigrationConnector.md)
+
 ## Type Parameters
 
 ### T
@@ -14,7 +18,7 @@ Interface describing an entity storage connector.
 
 ## Methods
 
-### getSchema()
+### getSchema() {#getschema}
 
 > **getSchema**(): `IEntitySchema`
 
@@ -28,7 +32,7 @@ The schema for the entities.
 
 ***
 
-### set()
+### set() {#set}
 
 > **set**(`entity`, `conditions?`): `Promise`\<`void`\>
 
@@ -56,7 +60,29 @@ 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.
+
+***
+
+### get() {#get}
 
 > **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`T` \| `undefined`\>
 
@@ -90,7 +116,7 @@ The object if it can be found or undefined.
 
 ***
 
-### remove()
+### remove() {#remove}
 
 > **remove**(`id`, `conditions?`): `Promise`\<`void`\>
 
@@ -118,7 +144,29 @@ 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.
+
+***
+
+### query() {#query}
 
 > **query**(`conditions?`, `sortProperties?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 
@@ -162,3 +210,39 @@ The suggested number of entities to return in each chunk, in some scenarios can
 
 All the entities for the storage matching the conditions,
 and a cursor which can be used to request more entities.
+
+***
+
+### empty() {#empty}
+
+> **empty**(): `Promise`\<`void`\>
+
+Remove all entities from the storage.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+***
+
+### 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.

package/docs/reference/interfaces/IEntityStorageCountRequest.md

@@ -0,0 +1,17 @@
+# Interface: IEntityStorageCountRequest
+
+Count the entries in entity storage.
+
+## Properties
+
+### query? {#query}
+
+> `optional` **query?**: `object`
+
+The query parameters.
+
+#### conditions?
+
+> `optional` **conditions?**: `string`
+
+The optional conditions to filter the count, JSON encoded EntityCondition.

package/docs/reference/interfaces/IEntityStorageCountResponse.md

@@ -0,0 +1,17 @@
+# Interface: IEntityStorageCountResponse
+
+The response for counting entries in entity storage.
+
+## Properties
+
+### body {#body}
+
+> **body**: `object`
+
+The body of the response.
+
+#### count
+
+> **count**: `number`
+
+The total count of entities.

package/docs/reference/interfaces/IEntityStorageEmptyRequest.md

@@ -0,0 +1,3 @@
+# Interface: IEntityStorageEmptyRequest
+
+Remove all entries from entity storage.

package/docs/reference/interfaces/IEntityStorageGetRequest.md

@@ -4,7 +4,7 @@ Get an entry from entity storage.
 
 ## Properties
 
-### pathParams
+### pathParams {#pathparams}
 
 > **pathParams**: `object`
 
@@ -18,14 +18,20 @@ The id of the entity to get.
 
 ***
 
-### query?
+### query? {#query}
 
-> `optional` **query**: `object`
+> `optional` **query?**: `object`
 
 The query parameters.
 
 #### secondaryIndex?
 
-> `optional` **secondaryIndex**: `string`
+> `optional` **secondaryIndex?**: `string`
 
 The secondary index to query with the id.
+
+#### conditions?
+
+> `optional` **conditions?**: `string`
+
+The optional conditions to match for the entity, JSON encoded array of property/value pairs.

package/docs/reference/interfaces/IEntityStorageGetResponse.md

@@ -4,7 +4,7 @@ Get an entry from entity storage.
 
 ## Properties
 
-### body
+### body {#body}
 
 > **body**: `unknown`
 

package/docs/reference/interfaces/IEntityStorageListRequest.md

@@ -4,44 +4,44 @@ Query the entries from entity storage.
 
 ## Properties
 
-### query?
+### query? {#query}
 
-> `optional` **query**: `object`
+> `optional` **query?**: `object`
 
 The parameters from the query.
 
 #### conditions?
 
-> `optional` **conditions**: `string`
+> `optional` **conditions?**: `string`
 
 The condition for the query as JSON version of EntityCondition type.
 
 #### orderBy?
 
-> `optional` **orderBy**: `string`
+> `optional` **orderBy?**: `string`
 
 The order property for the results.
 
 #### orderByDirection?
 
-> `optional` **orderByDirection**: `SortDirection`
+> `optional` **orderByDirection?**: `SortDirection`
 
 The direction for the order, defaults to desc.
 
 #### properties?
 
-> `optional` **properties**: `string`
+> `optional` **properties?**: `string`
 
 The properties to return in the response as a comma separated list, by default returns all properties.
 
 #### limit?
 
-> `optional` **limit**: `string`
+> `optional` **limit?**: `string`
 
 Limit the number of entities to return.
 
 #### cursor?
 
-> `optional` **cursor**: `string`
+> `optional` **cursor?**: `string`
 
 The cursor to get next chunk of data, returned in previous response.