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

package/docs/reference/classes/EntityStorageHelper.md

@@ -0,0 +1,209 @@
+# Class: EntityStorageHelper
+
+Helper class for performing schema migrations between two connectors.
+
+## Constructors
+
+### Constructor
+
+> **new EntityStorageHelper**(): `EntityStorageHelper`
+
+#### Returns
+
+`EntityStorageHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### prepareEntity() {#prepareentity}
+
+> `static` **prepareEntity**\<`T`\>(`entity`, `schema`, `additionalProperties?`, `options?`): `T`
+
+Prepare the entity by handling undefined and null values and validating it against the schema.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### entity
+
+`T`
+
+The entity to handle undefined and null values for.
+
+##### schema
+
+`IEntitySchema`\<`T`\>
+
+The schema to validate the entity against.
+
+##### additionalProperties?
+
+`object`[]
+
+Optional list of additional properties to set on the entity.
+
+##### options?
+
+Options controlling how null/undefined optional properties are stored.
+
+###### nullBehavior?
+
+`"omit"` \| `"nullify"`
+
+"omit" strips null/undefined optional properties before writing
+(NoSQL — avoids index-key type errors). "nullify" converts undefined to null (SQL — the default).
+
+#### Returns
+
+`T`
+
+The entity with undefined and null values handled.
+
+***
+
+### unPrepareEntity() {#unprepareentity}
+
+> `static` **unPrepareEntity**\<`T`\>(`entity`, `removeProperties?`): `T`
+
+Un-prepare the entity by removing null values.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### entity
+
+`Partial`\<`T`\> \| `undefined`
+
+The entity to handle undefined and null values for.
+
+##### removeProperties?
+
+`string`[]
+
+Optional list of properties to remove from the entity.
+
+#### Returns
+
+`T`
+
+The entity with undefined and null values handled.
+
+***
+
+### validateSortProperties() {#validatesortproperties}
+
+> `static` **validateSortProperties**\<`T`\>(`schema`, `sortProperties?`): `void`
+
+Validate that every sort property in the list is indexed in the schema (isPrimary, isSecondary,
+or has a default sortDirection), throwing sortNotIndexed for the first violation found.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### schema
+
+`IEntitySchema`\<`T`\>
+
+The entity schema to validate against.
+
+##### sortProperties?
+
+`object`[]
+
+The sort properties to check.
+
+#### Returns
+
+`void`
+
+#### Throws
+
+GeneralError If a sort property is not indexed in the schema.
+
+***
+
+### validateProperties() {#validateproperties}
+
+> `static` **validateProperties**\<`T`\>(`schema`, `properties?`): `void`
+
+Validate that every property in the list exists in the schema, throwing propertyNotInSchema
+for the first property that is not found.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### schema
+
+`IEntitySchema`\<`T`\>
+
+The entity schema to validate against.
+
+##### properties?
+
+keyof `T`[]
+
+The properties to check.
+
+#### Returns
+
+`void`
+
+#### Throws
+
+GeneralError If a property does not exist in the schema.
+
+***
+
+### normalizeConditionValues() {#normalizeconditionvalues}
+
+> `static` **normalizeConditionValues**\<`T`\>(`condition`): `EntityCondition`\<`T`\>
+
+Deep-clone condition tree and normalise null/undefined to undefined on Equals/NotEquals leaves
+so in-memory evaluation matches stored-absent semantics (optional absent props are omitted/undefined).
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### condition
+
+`EntityCondition`\<`T`\>
+
+The user-supplied condition (not mutated).
+
+#### Returns
+
+`EntityCondition`\<`T`\>
+
+A clone safe to pass to check.

package/docs/reference/classes/MigrationHelper.md

@@ -0,0 +1,198 @@
+# Class: MigrationHelper
+
+Helper class for performing entity schema migrations between two connectors.
+The chain-based API (migrateWithChain / applyEntityChain) is the single migration
+path: a chain of one step covers the same case as a traditional single-step migration.
+
+## Constructors
+
+### Constructor
+
+> **new MigrationHelper**(): `MigrationHelper`
+
+#### Returns
+
+`MigrationHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### migrateWithChain() {#migratewithchain}
+
+> `static` **migrateWithChain**(`sourceConnector`, `targetSchemaName`, `steps`, `options?`, `loggingComponentType?`): `Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
+
+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.
+
+#### Parameters
+
+##### sourceConnector
+
+[`IEntityStorageMigrationConnector`](../interfaces/IEntityStorageMigrationConnector.md)
+
+The connector holding data at the stored schema version.
+
+##### targetSchemaName
+
+`string`
+
+The schema name for the current version (used to create the target connector).
+
+##### steps
+
+[`IResolvedMigrationStep`](../interfaces/IResolvedMigrationStep.md)\<`unknown`, `unknown`\>[]
+
+Ordered, fully-resolved migration steps from stored to current version.
+
+##### options?
+
+[`IMigrationOptions`](../interfaces/IMigrationOptions.md)
+
+Optional migration options.
+
+##### loggingComponentType?
+
+`string`
+
+The optional component type to use for logging the migration progress.
+
+#### Returns
+
+`Promise`\<\{ `finalConnector`: [`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md); `migrated`: `number`; \}\>
+
+The finalized connector and the count of migrated entities.
+
+***
+
+### migratePartitionWithChain() {#migratepartitionwithchain}
+
+> `static` **migratePartitionWithChain**(`source`, `target`, `steps`, `options?`): `Promise`\<`number`\>
+
+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.
+
+***
+
+### applyEntityChain() {#applyentitychain}
+
+> `static` **applyEntityChain**(`entity`, `steps`): `unknown`
+
+Transforms a single entity through an ordered chain of fully-resolved migration steps.
+For each step the method diffs fromProperties against toProperties, then applies
+applyEntityTransform. Each step's output feeds the next step's input so that
+per-step transformEntityProperty hooks are honoured throughout the chain.
+
+#### Parameters
+
+##### entity
+
+`unknown`
+
+The entity to transform (at the shape described by steps[0].fromProperties).
+
+##### steps
+
+[`IResolvedMigrationStep`](../interfaces/IResolvedMigrationStep.md)\<`unknown`, `unknown`\>[]
+
+Ordered, fully-resolved migration steps from stored version to current version.
+Each step's fromProperties and toProperties are resolved by the caller before invocation.
+
+#### Returns
+
+`unknown`
+
+The entity transformed to the shape described by steps[last].toProperties.
+
+***
+
+### applyEntityTransform() {#applyentitytransform}
+
+> `static` **applyEntityTransform**\<`T`, `U`\>(`entity`, `schemaDiff`, `transformEntityProperty?`): `U`
+
+Applies the entity transformation for a single diff, handling added, removed, and
+modified properties according to the provided schema diff and optional transform hook.
+
+#### 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.
+
+##### transformEntityProperty?
+
+[`EntityPropertyTransformer`](../type-aliases/EntityPropertyTransformer.md)\<`T`, `U`\>
+
+Optional per-property transform hook for object/array properties.
+
+#### 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 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,16 +1,35 @@
 # @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)
+- [IResolvedMigrationStep](interfaces/IResolvedMigrationStep.md)
+- [ISchemaMigration](interfaces/ISchemaMigration.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)
 
+## Type Aliases
+
+- [EntityPropertyTransformer](type-aliases/EntityPropertyTransformer.md)
+
 ## Variables
 
 - [EntityStorageConnectorFactory](variables/EntityStorageConnectorFactory.md)
+- [SchemaMigrationFactory](variables/SchemaMigrationFactory.md)

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.