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

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

@@ -29,3 +29,9 @@ The query parameters.
 > `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/IEntityStorageMigrationConnector.md

@@ -0,0 +1,402 @@
+# Interface: IEntityStorageMigrationConnector\<T\>
+
+Interface describing an entity storage migration connector.
+
+## Extends
+
+- [`IEntityStorageConnector`](IEntityStorageConnector.md)\<`T`\>
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+## Methods
+
+### getSchema() {#getschema}
+
+> **getSchema**(): `IEntitySchema`
+
+Get the schema for the entities.
+
+#### Returns
+
+`IEntitySchema`
+
+The schema for the entities.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`getSchema`](IEntityStorageConnector.md#getschema)
+
+***
+
+### set() {#set}
+
+> **set**(`entity`, `conditions?`): `Promise`\<`void`\>
+
+Set an entity.
+
+#### Parameters
+
+##### entity
+
+`T`
+
+The entity to set.
+
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+The id of the entity.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`set`](IEntityStorageConnector.md#set)
+
+***
+
+### setBatch() {#setbatch}
+
+> **setBatch**(`entities`): `Promise`\<`void`\>
+
+Set multiple entities in a batch.
+
+#### Parameters
+
+##### entities
+
+`T`[]
+
+The entities to set.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`setBatch`](IEntityStorageConnector.md#setbatch)
+
+***
+
+### get() {#get}
+
+> **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`T` \| `undefined`\>
+
+Get an entity.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the entity to get, or the index value if secondaryIndex is set.
+
+##### secondaryIndex?
+
+keyof `T`
+
+Get the item using a secondary index.
+
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
+#### Returns
+
+`Promise`\<`T` \| `undefined`\>
+
+The object if it can be found or undefined.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`get`](IEntityStorageConnector.md#get)
+
+***
+
+### remove() {#remove}
+
+> **remove**(`id`, `conditions?`): `Promise`\<`void`\>
+
+Remove the entity.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the entity to remove.
+
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`remove`](IEntityStorageConnector.md#remove)
+
+***
+
+### 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.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`removeBatch`](IEntityStorageConnector.md#removebatch)
+
+***
+
+### query() {#query}
+
+> **query**(`conditions?`, `sortProperties?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
+
+Query all the entities which match the conditions.
+
+#### Parameters
+
+##### conditions?
+
+`EntityCondition`\<`T`\>
+
+The conditions to match for the entities.
+
+##### sortProperties?
+
+`object`[]
+
+The optional sort order.
+
+##### properties?
+
+keyof `T`[]
+
+The optional properties to return, defaults to all.
+
+##### cursor?
+
+`string`
+
+The cursor to request the next chunk of entities.
+
+##### limit?
+
+`number`
+
+The suggested number of entities to return in each chunk, in some scenarios can return a different amount.
+
+#### Returns
+
+`Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`query`](IEntityStorageConnector.md#query)
+
+***
+
+### empty() {#empty}
+
+> **empty**(): `Promise`\<`void`\>
+
+Remove all entities from the storage.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`empty`](IEntityStorageConnector.md#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.
+
+#### Inherited from
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md).[`count`](IEntityStorageConnector.md#count)
+
+***
+
+### getPartitionContextIds() {#getpartitioncontextids}
+
+> **getPartitionContextIds**(): `Promise`\<`IContextIds`[]\>
+
+Get a unique list of all the context ids from the storage.
+
+#### Returns
+
+`Promise`\<`IContextIds`[]\>
+
+The list of unique context ids.
+
+***
+
+### createTargetConnector() {#createtargetconnector}
+
+> **createTargetConnector**\<`U`\>(`newEntitySchema`): `Promise`\<[`IEntityStorageConnector`](IEntityStorageConnector.md)\<`U`\>\>
+
+Create the target connector for performing the migration it will use a temporary storage location.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### newEntitySchema
+
+`string`
+
+The name of the new entity schema to create the connector for.
+
+#### Returns
+
+`Promise`\<[`IEntityStorageConnector`](IEntityStorageConnector.md)\<`U`\>\>
+
+Connector for performing the migration.
+
+***
+
+### finalizeMigration() {#finalizemigration}
+
+> **finalizeMigration**\<`U`\>(`targetConnector`, `options?`, `loggingComponentType?`): `Promise`\<[`IEntityStorageConnector`](IEntityStorageConnector.md)\<`U`\>\>
+
+Finalize the migration by tearing down the old connector and replacing it with the target connector.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### targetConnector
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md)\<`U`\>
+
+The target connector to finalize the migration with.
+
+##### options?
+
+[`IMigrationOptions`](IMigrationOptions.md)
+
+The options to control how the migration is finalized.
+
+##### loggingComponentType?
+
+`string`
+
+The optional component type to use for logging the migration progress.
+
+#### Returns
+
+`Promise`\<[`IEntityStorageConnector`](IEntityStorageConnector.md)\<`U`\>\>
+
+A promise that resolves when the migration is finalized and returns the final connector.
+
+***
+
+### cleanupMigration() {#cleanupmigration}
+
+> **cleanupMigration**\<`U`\>(`targetConnector`, `options?`, `loggingComponentType?`): `Promise`\<`void`\>
+
+Cleanup the migration if a migration fails or needs to be aborted.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### targetConnector
+
+[`IEntityStorageConnector`](IEntityStorageConnector.md)\<`U`\> \| `undefined`
+
+The target connector to cleanup the migration with.
+
+##### options?
+
+[`IMigrationOptions`](IMigrationOptions.md)
+
+The options to control how the migration is cleaned up.
+
+##### loggingComponentType?
+
+`string`
+
+The optional component type to use for logging the migration progress.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the migration is cleaned up.

package/docs/reference/interfaces/IEntityStorageRemoveBatchRequest.md

@@ -0,0 +1,11 @@
+# Interface: IEntityStorageRemoveBatchRequest
+
+Remove multiple entries from entity storage by id.
+
+## Properties
+
+### body {#body}
+
+> **body**: `string`[]
+
+The ids of the entities to remove.

package/docs/reference/interfaces/IEntityStorageRemoveRequest.md

@@ -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

@@ -9,3 +9,17 @@ Set an entry in entity storage.
 > **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,84 @@
+# 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
+
+**schema1Property**
+
+The property schema in the old schema.
+
+#### Param
+
+**schemaProperty2**
+
+The property schema in the new schema.
+
+#### Param
+
+**value**
+
+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,68 @@
+# 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
+
+**schema1Property**
+
+The property schema in the old schema.
+
+#### Param
+
+**schemaProperty2**
+
+The property schema in the new schema.
+
+#### Param
+
+**value**
+
+The value of the property in the old schema.
+
+#### Returns
+
+The transformed value to match the new schema.