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

package/docs/reference/interfaces/IEntityStorageListResponse.md

@@ -4,7 +4,7 @@ Response to getting the list of entries from a query.
 
 ## Properties
 
-### body
+### body {#body}
 
 > **body**: `object`
 
@@ -18,6 +18,6 @@ The entities from the query.
 
 #### cursor?
 
-> `optional` **cursor**: `string`
+> `optional` **cursor?**: `string`
 
 The cursor for the next page.

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)\<`T`, `U`\>
+
+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)\<`T`, `U`\>
+
+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

@@ -4,7 +4,7 @@ Remove an entry from entity storage.
 
 ## Properties
 
-### pathParams
+### pathParams {#pathparams}
 
 > **pathParams**: `object`
 
@@ -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

@@ -4,8 +4,22 @@ Set an entry in entity storage.
 
 ## Properties
 
-### body
+### body {#body}
 
 > **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,119 @@
+# Interface: IMigrationOptions\<T, U\>
+
+Options controlling how a schema migration is executed.
+
+## Type Parameters
+
+### T
+
+`T`
+
+### U
+
+`U`
+
+## Properties
+
+### batchSize? {#batchsize}
+
+> `optional` **batchSize?**: `number`
+
+Number of entities to read and write per batch.
+
+#### Default
+
+```ts
+100
+```
+
+***
+
+### transformEntityProperty? {#transformentityproperty}
+
+> `optional` **transformEntityProperty?**: (`schema1Property`, `schemaProperty2`, `value`) => `unknown`
+
+Optional transformation for properties, usually only called for object and array types.
+
+#### Parameters
+
+##### schema1Property
+
+`IEntitySchemaProperty`\<`T`\>
+
+The property schema in the old schema.
+
+##### schemaProperty2
+
+`IEntitySchemaProperty`\<`U`\>
+
+The property schema in the new schema.
+
+##### value
+
+`unknown`
+
+The value of the property in the old schema.
+
+#### Returns
+
+`unknown`
+
+The transformed value to match the new schema.
+
+***
+
+### onPartitionProgress? {#onpartitionprogress}
+
+> `optional` **onPartitionProgress?**: (`rowTotal`, `rowIndex`) => `Promise`\<`void`\>
+
+Called for each partition for progress tracking.
+
+#### Parameters
+
+##### rowTotal
+
+`number`
+
+The total number of rows to migrate.
+
+##### rowIndex
+
+`number`
+
+The number of rows migrated so far.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### onStepProgress? {#onstepprogress}
+
+> `optional` **onStepProgress?**: (`stepKey`, `itemTotal`, `itemIndex`) => `Promise`\<`void`\>
+
+Called for overall progress tracking.
+
+#### Parameters
+
+##### stepKey
+
+`string`
+
+The key representing the current step in the migration.
+
+##### itemTotal
+
+`number`
+
+The total number of items in this progress.
+
+##### itemIndex
+
+`number`
+
+The number of items processed so far.
+
+#### Returns
+
+`Promise`\<`void`\>

package/locales/en.json

@@ -1,3 +1,9 @@
 {
-	"error": {}
+	"error": {
+		"migrationHelper": {
+			"migrationFailed": "Migration failed.",
+			"transformRequiredForProperty": "A transformation function is required to migrate property \"{from}\" to \"{to}\" of type \"{type}\"",
+			"coercionProducedUndefined": "Coercion of property \"{property}\" to type \"{type}\" produced undefined but the property is not optional"
+		}
+	}
 }

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/entity-storage-models",
-	"version": "0.0.3-next.2",
-	"description": "Models which define the structure of the entity storage contracts and connectors",
+	"version": "0.0.3-next.21",
+	"description": "Shared models for storage contracts, requests, responses and connector capabilities.",
 	"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-models"
 	},
 	"author": "martyn.janes@iota.org",
@@ -14,6 +14,7 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
+		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
 		"@twin.org/nameof": "next"
@@ -50,7 +51,7 @@
 		"schemas"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/entity-storage/issues"
+		"url": "git+https://github.com/iotaledger/twin-entity-storage/issues"
 	},
 	"homepage": "https://twindev.org"
 }