@twin.org/entity-storage-connector-cosmosdb 0.0.3-next.6 → 0.0.3-next.7

package/README.md

@@ -1,6 +1,6 @@
-# TWIN Entity Storage Connector Cosmos DB
+# Entity Storage Connector Cosmos DB
 
-Entity Storage connector implementation using Cosmos DB storage.
+This package provides an Azure Cosmos DB backend for globally distributed persistence across regions. It is designed to work with the wider storage ecosystem so applications can keep behaviour consistent across connectors and environments.
 
 ## Installation
 
@@ -8,24 +8,13 @@ Entity Storage connector implementation using Cosmos DB storage.
 npm install @twin.org/entity-storage-connector-cosmosdb
 ```
 
-## Testing
+## Docker
 
-The tests developed are functional tests and need an instance of CosmosDB up and running. To run CosmosDB locally there are two possibilities:
+To perform testing of this component it may be necessary to launch a local instance to communicate with.
 
-To run a Docker image of Azure CosmosDB:
-
-```sh
-docker run -d --platform=linux/amd64 -p 8081:8081 -m 3g --name twin-entity-storage-cosmos -e AZURE_COSMOS_EMULATOR_PARTITION_COUNT=10 -e AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE=true -e AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE='127.0.0.1' mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator
-```
-
-Or
-
-To install and run the Azure CosmosDB Emulator [Azure CosmosDB Emulator](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-develop-emulator)
-
-Afterwards you can run the tests as follows:
-
-```sh
-npm run test
+```shell
+docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
+docker run --publish 8081:8081 --name twin-entity-storage-cosmos --detach --platform=linux/amd64 --memory=3g --cpus=2.0 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
 ```
 
 ## Examples

package/docs/changelog.md

@@ -1,4 +1,22 @@
-# @twin.org/entity-storage-connector-cosmosdb - Changelog
+# Changelog
+
+## [0.0.3-next.7](https://github.com/twinfoundation/entity-storage/compare/entity-storage-connector-cosmosdb-v0.0.3-next.6...entity-storage-connector-cosmosdb-v0.0.3-next.7) (2026-03-13)
+
+
+### Bug Fixes
+
+* adding tests and fixes for dot notation ([#76](https://github.com/twinfoundation/entity-storage/issues/76)) ([3879337](https://github.com/twinfoundation/entity-storage/commit/387933797e33543e4d8b2d49b8beeb792512a4ff))
+* improve cosmodb tests ([d1a23c7](https://github.com/twinfoundation/entity-storage/commit/d1a23c79a59250351ad71ca7074b4bda79004e2e))
+* improve cosmodb tests ([4819d70](https://github.com/twinfoundation/entity-storage/commit/4819d706500822e8093314b72d8f7923fc903f0c))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.0.3-next.6 to 0.0.3-next.7
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.0.3-next.6 to 0.0.3-next.7
 
 ## [0.0.3-next.6](https://github.com/twinfoundation/entity-storage/compare/entity-storage-connector-cosmosdb-v0.0.3-next.5...entity-storage-connector-cosmosdb-v0.0.3-next.6) (2026-01-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

@@ -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`\>
 
@@ -68,7 +68,7 @@ A promise that resolves to a boolean indicating success.
 
 ***
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -86,7 +86,7 @@ The class name of the component.
 
 ***
 
-### getSchema()
+### getSchema() {#getschema}
 
 > **getSchema**(): `IEntitySchema`
 
@@ -104,7 +104,7 @@ The schema for the entities.
 
 ***
 
-### get()
+### get() {#get}
 
 > **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`T` \| `undefined`\>
 
@@ -142,7 +142,7 @@ The object if it can be found or undefined.
 
 ***
 
-### set()
+### set() {#set}
 
 > **set**(`entity`, `conditions?`): `Promise`\<`void`\>
 
@@ -174,7 +174,7 @@ The id of the entity.
 
 ***
 
-### remove()
+### remove() {#remove}
 
 > **remove**(`id`, `conditions?`): `Promise`\<`void`\>
 
@@ -206,7 +206,7 @@ Nothing.
 
 ***
 
-### query()
+### query() {#query}
 
 > **query**(`conditions?`, `sortProperties?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 
@@ -257,7 +257,7 @@ and a cursor which can be used to request more entities.
 
 ***
 
-### containerDelete()
+### containerDelete() {#containerdelete}
 
 > **containerDelete**(): `Promise`\<`void`\>
 

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,7 +36,7 @@ The ID of the container for the storage.
 
 ***
 
-### offerThroughput?
+### offerThroughput? {#offerthroughput}
 
 > `optional` **offerThroughput**: `number`
 

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,7 +12,7 @@ The schema for the entity.
 
 ***
 
-### partitionContextIds?
+### partitionContextIds? {#partitioncontextids}
 
 > `optional` **partitionContextIds**: `string`[]
 
@@ -20,21 +20,15 @@ The keys to use from the context ids to create partitions.
 
 ***
 
-### loggingComponentType?
+### loggingComponentType? {#loggingcomponenttype}
 
 > `optional` **loggingComponentType**: `string`
 
 The type of logging component to use.
 
-#### Default
-
-```ts
-logging
-```
-
 ***
 
-### config
+### config {#config}
 
 > **config**: [`ICosmosDbEntityStorageConnectorConfig`](ICosmosDbEntityStorageConnectorConfig.md)
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/entity-storage-connector-cosmosdb",
-	"version": "0.0.3-next.6",
-	"description": "Entity Storage connector implementation using CosmosDB storage",
+	"version": "0.0.3-next.7",
+	"description": "Azure Cosmos DB connector for globally distributed persistence.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/entity-storage.git",
@@ -14,12 +14,12 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@azure/cosmos": "4.7.0",
+		"@azure/cosmos": "4.9.1",
 		"@azure/identity": "4.13.0",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.0.3-next.6",
+		"@twin.org/entity-storage-models": "0.0.3-next.7",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next"
 	},