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

package/docs/examples.md

@@ -1 +1,96 @@
-# @twin.org/entity-storage-connector-cosmosdb - Examples
+# Entity Storage Connector CosmosDB Examples
+
+Use these snippets to configure a connector, work with common entity operations, and clean up storage resources when running integration tests.
+
+## CosmosDbEntityStorageConnector
+
+```typescript
+import {
+  CosmosDbEntityStorageConnector,
+  type ICosmosDbEntityStorageConnectorConstructorOptions
+} from '@twin.org/entity-storage-connector-cosmosdb';
+import {
+  ComparisonOperator,
+  LogicalOperator,
+  SortDirection,
+  type EntityCondition
+} from '@twin.org/entity';
+
+interface Profile {
+  id: string;
+  email: string;
+  status: 'active' | 'inactive';
+  createdAt: string;
+}
+
+const options: ICosmosDbEntityStorageConnectorConstructorOptions = {
+  entitySchema: 'Profile',
+  config: {
+    endpoint: 'https://example.documents.azure.com:443/',
+    key: 'cosmos-primary-key',
+    databaseId: 'entityStorage',
+    containerId: 'profiles',
+    offerThroughput: 400
+  }
+};
+
+const connector = new CosmosDbEntityStorageConnector<Profile>(options);
+await connector.bootstrap();
+
+const className = connector.className();
+const schema = connector.getSchema();
+
+await connector.set({
+  id: 'profile-1',
+  email: 'ada@example.com',
+  status: 'active',
+  createdAt: '2026-03-09T10:30:00.000Z'
+});
+
+const byPrimaryKey = await connector.get('profile-1');
+const bySecondaryIndex = await connector.get('ada@example.com', 'email');
+
+const activeCondition: EntityCondition<Profile> = {
+  logicalOperator: LogicalOperator.And,
+  conditions: [
+    {
+      property: 'status',
+      comparison: ComparisonOperator.Equals,
+      value: 'active'
+    }
+  ]
+};
+
+const result = await connector.query(
+  activeCondition,
+  [{ property: 'createdAt', sortDirection: SortDirection.Descending }],
+  ['id', 'email', 'status'],
+  undefined,
+  25
+);
+
+await connector.remove('profile-1');
+```
+
+```typescript
+import { CosmosDbEntityStorageConnector } from '@twin.org/entity-storage-connector-cosmosdb';
+
+interface Profile {
+  id: string;
+  email: string;
+  status: 'active' | 'inactive';
+  createdAt: string;
+}
+
+const connector = new CosmosDbEntityStorageConnector<Profile>({
+  entitySchema: 'Profile',
+  config: {
+    endpoint: 'https://example.documents.azure.com:443/',
+    key: 'cosmos-primary-key',
+    databaseId: 'entityStorage',
+    containerId: 'profiles'
+  }
+});
+
+await connector.containerDelete();
+```

package/docs/reference/classes/CosmosDbEntityStorageConnector.md

@@ -10,7 +10,7 @@ Class for performing entity storage operations using Cosmos DB.
 
 ## Implements
 
-- `IEntityStorageConnector`\<`T`\>
+- `IEntityStorageMigrationConnector`\<`T`\>
 
 ## Constructors
 
@@ -34,7 +34,7 @@ The options for the connector.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -42,7 +42,7 @@ Runtime name for the class.
 
 ## Methods
 
-### bootstrap()
+### bootstrap() {#bootstrap}
 
 > **bootstrap**(`nodeLoggingComponentType?`): `Promise`\<`boolean`\>
 
@@ -64,11 +64,11 @@ A promise that resolves to a boolean indicating success.
 
 #### Implementation of
 
-`IEntityStorageConnector.bootstrap`
+`IEntityStorageMigrationConnector.bootstrap`
 
 ***
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -82,11 +82,29 @@ The class name of the component.
 
 #### Implementation of
 
-`IEntityStorageConnector.className`
+`IEntityStorageMigrationConnector.className`
 
 ***
 
-### getSchema()
+### health() {#health}
+
+> **health**(): `Promise`\<`IHealth`[]\>
+
+Returns the health status of the component.
+
+#### Returns
+
+`Promise`\<`IHealth`[]\>
+
+The health status of the component.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.health`
+
+***
+
+### getSchema() {#getschema}
 
 > **getSchema**(): `IEntitySchema`
 
@@ -100,11 +118,11 @@ The schema for the entities.
 
 #### Implementation of
 
-`IEntityStorageConnector.getSchema`
+`IEntityStorageMigrationConnector.getSchema`
 
 ***
 
-### get()
+### get() {#get}
 
 > **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`T` \| `undefined`\>
 
@@ -138,11 +156,11 @@ The object if it can be found or undefined.
 
 #### Implementation of
 
-`IEntityStorageConnector.get`
+`IEntityStorageMigrationConnector.get`
 
 ***
 
-### set()
+### set() {#set}
 
 > **set**(`entity`, `conditions?`): `Promise`\<`void`\>
 
@@ -170,11 +188,55 @@ The id of the entity.
 
 #### Implementation of
 
-`IEntityStorageConnector.set`
+`IEntityStorageMigrationConnector.set`
+
+***
+
+### 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
+
+`IEntityStorageMigrationConnector.setBatch`
 
 ***
 
-### remove()
+### empty() {#empty}
+
+> **empty**(): `Promise`\<`void`\>
+
+Empty all entities from the storage.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.empty`
+
+***
+
+### remove() {#remove}
 
 > **remove**(`id`, `conditions?`): `Promise`\<`void`\>
 
@@ -202,11 +264,63 @@ Nothing.
 
 #### Implementation of
 
-`IEntityStorageConnector.remove`
+`IEntityStorageMigrationConnector.remove`
 
 ***
 
-### 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
+
+`IEntityStorageMigrationConnector.removeBatch`
+
+***
+
+### teardown() {#teardown}
+
+> **teardown**(`nodeLoggingComponentType?`): `Promise`\<`boolean`\>
+
+Teardown the storage by deleting the underlying container.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the teardown process was successful.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.teardown`
+
+***
+
+### query() {#query}
 
 > **query**(`conditions?`, `sortProperties?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 
@@ -253,18 +367,166 @@ and a cursor which can be used to request more entities.
 
 #### Implementation of
 
-`IEntityStorageConnector.query`
+`IEntityStorageMigrationConnector.query`
+
+***
+
+### 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
+
+`IEntityStorageMigrationConnector.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.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.getPartitionContextIds`
 
 ***
 
-### containerDelete()
+### createTargetConnector() {#createtargetconnector}
+
+> **createTargetConnector**\<`U`\>(`newEntitySchema`): `Promise`\<`IEntityStorageConnector`\<`U`\>\>
+
+Create the target connector for performing the migration using a temporary container.
+
+#### Type Parameters
+
+##### U
 
-> **containerDelete**(): `Promise`\<`void`\>
+`U`
 
-Delete the container.
+#### Parameters
+
+##### newEntitySchema
+
+`string`
+
+The name of the new entity schema to create the connector for.
+
+#### Returns
+
+`Promise`\<`IEntityStorageConnector`\<`U`\>\>
+
+Connector for performing the migration.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.createTargetConnector`
+
+***
+
+### finalizeMigration() {#finalizemigration}
+
+> **finalizeMigration**\<`U`\>(`targetConnector`, `options?`, `loggingComponentType?`): `Promise`\<`CosmosDbEntityStorageConnector`\<`U`\>\>
+
+Finalize the migration by tearing down the old container and replacing it with the target container.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### targetConnector
+
+`CosmosDbEntityStorageConnector`\<`U`\>
+
+The target connector to finalize the migration with.
+
+##### options?
+
+`IMigrationOptions`\<`T`, `U`\>
+
+The options to control how the migration is finalized.
+
+##### loggingComponentType?
+
+`string`
+
+The optional component type to use for logging.
+
+#### Returns
+
+`Promise`\<`CosmosDbEntityStorageConnector`\<`U`\>\>
+
+The final connector pointing at the original container id.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.finalizeMigration`
+
+***
+
+### 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`\<`U`\> \| `undefined`
+
+The target connector to cleanup.
+
+##### options?
+
+`IMigrationOptions`\<`T`, `U`\>
+
+The options to control how the migration is cleaned up.
+
+##### loggingComponentType?
+
+`string`
+
+The optional component type to use for logging.
 
 #### Returns
 
 `Promise`\<`void`\>
 
-Nothing.
+#### Implementation of
+
+`IEntityStorageMigrationConnector.cleanupMigration`

package/docs/reference/interfaces/ICosmosDbEntityStorageConnectorConfig.md

@@ -4,7 +4,7 @@ Configuration for the Cosmos DB Entity Storage Connector.
 
 ## Properties
 
-### endpoint
+### endpoint {#endpoint}
 
 > **endpoint**: `string`
 
@@ -12,7 +12,7 @@ The endpoint for the Cosmos DB instance.
 
 ***
 
-### key
+### key {#key}
 
 > **key**: `string`
 
@@ -20,7 +20,7 @@ The primary key for the Cosmos DB instance.
 
 ***
 
-### databaseId
+### databaseId {#databaseid}
 
 > **databaseId**: `string`
 
@@ -28,7 +28,7 @@ The ID of the database to be used.
 
 ***
 
-### containerId
+### containerId {#containerid}
 
 > **containerId**: `string`
 
@@ -36,8 +36,19 @@ The ID of the container for the storage.
 
 ***
 
-### offerThroughput?
+### offerThroughput? {#offerthroughput}
 
-> `optional` **offerThroughput**: `number`
+> `optional` **offerThroughput?**: `number`
 
 The offer throughput for the container.
+
+***
+
+### disableEndpointDiscovery? {#disableendpointdiscovery}
+
+> `optional` **disableEndpointDiscovery?**: `boolean`
+
+Disable endpoint discovery so the SDK always uses the configured endpoint.
+Required when using the CosmosDB emulator behind a port-mapped Docker container,
+because the emulator's account response advertises its internal container port
+instead of the mapped host port.

package/docs/reference/interfaces/ICosmosDbEntityStorageConnectorConstructorOptions.md

@@ -4,7 +4,7 @@ The options for the cosmos db entity storage connector constructor.
 
 ## Properties
 
-### entitySchema
+### entitySchema {#entityschema}
 
 > **entitySchema**: `string`
 
@@ -12,17 +12,17 @@ The schema for the entity.
 
 ***
 
-### partitionContextIds?
+### partitionContextIds? {#partitioncontextids}
 
-> `optional` **partitionContextIds**: `string`[]
+> `optional` **partitionContextIds?**: `string`[]
 
 The keys to use from the context ids to create partitions.
 
 ***
 
-### loggingComponentType?
+### loggingComponentType? {#loggingcomponenttype}
 
-> `optional` **loggingComponentType**: `string`
+> `optional` **loggingComponentType?**: `string`
 
 The type of logging component to use.
 
@@ -34,7 +34,7 @@ logging
 
 ***
 
-### config
+### config {#config}
 
 > **config**: [`ICosmosDbEntityStorageConnectorConfig`](ICosmosDbEntityStorageConnectorConfig.md)
 

package/locales/en.json

@@ -4,7 +4,9 @@
 			"databaseCreating": "Database \"{databaseId}\" creating",
 			"databaseExists": "Database \"{databaseId}\" created or it already exists",
 			"containerCreating": "Container \"{containerId}\" creating",
-			"containerExists": "Container \"{containerId}\" created or it already exists"
+			"containerExists": "Container \"{containerId}\" created or it already exists",
+			"containerDeleting": "Deleting container \"{containerId}\"",
+			"containerDeleted": "Container \"{containerId}\" deleted"
 		}
 	},
 	"error": {
@@ -19,7 +21,20 @@
 			"sortNotIndexed": "The property \"{property}\" is not indexed and cannot be used for sorting",
 			"containerCreateFailed": "The container couldn't be created \"{containerId}\"",
 			"databaseCreateFailed": "Unable to create database \"{databaseId}\"",
-			"containerDoesNotExist": "Container \"{containerId}\" does not exist"
+			"containerDoesNotExist": "Container \"{containerId}\" does not exist",
+			"getPartitionContextIdsFailed": "Unable to get partition context ids",
+			"setBatchFailed": "Unable to set batch of entities",
+			"countFailed": "Unable to count entities",
+			"emptyFailed": "Unable to empty entity storage",
+			"removeBatchFailed": "Unable to remove batch of entities",
+			"teardownFailed": "Unable to teardown entity storage",
+			"finalizeMigrationFailedBootstrap": "Finalizing migration failed during bootstrap phase"
+		}
+	},
+	"health": {
+		"cosmosDbEntityStorageConnector": {
+			"healthDescription": "Checks if the Cosmos DB container \"{containerId}\" in database \"{databaseId}\" is available",
+			"connectionFailed": "Failed to connect to Cosmos DB container \"{containerId}\" in database \"{databaseId}\""
 		}
 	}
 }

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/entity-storage-connector-cosmosdb",
-	"version": "0.0.3-next.2",
-	"description": "Entity Storage connector implementation using CosmosDB storage",
+	"version": "0.0.3-next.21",
+	"description": "Azure Cosmos DB connector for globally distributed persistence.",
 	"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-connector-cosmosdb"
 	},
 	"author": "adrian.sanchez.sequeira@iota.org",
@@ -14,12 +14,12 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@azure/cosmos": "4.7.0",
-		"@azure/identity": "4.13.0",
+		"@azure/cosmos": "4.9.3",
+		"@azure/identity": "4.13.1",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.0.3-next.2",
+		"@twin.org/entity-storage-models": "0.0.3-next.21",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next"
 	},
@@ -55,7 +55,7 @@
 		"integration"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/entity-storage/issues"
+		"url": "git+https://github.com/iotaledger/twin-entity-storage/issues"
 	},
 	"homepage": "https://twindev.org"
 }