@twin.org/entity-storage-connector-synchronised 0.0.2-next.4 → 0.0.2-next.5

package/dist/cjs/index.cjs

@@ -40,6 +40,11 @@ class SynchronisedEntityStorageConnector {
      * @internal
      */
     _eventBusComponent;
+    /**
+     * The node identity.
+     * @internal
+     */
+    _nodeIdentity;
     /**
      * Create a new instance of SynchronisedEntityStorageConnector.
      * @param options The options for the connector.
@@ -87,6 +92,7 @@ class SynchronisedEntityStorageConnector {
      * @returns Nothing.
      */
     async start(nodeIdentity, nodeLoggingConnectorType, componentState) {
+        this._nodeIdentity = nodeIdentity;
         // Tell the synchronised storage about this storage key
         await this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.RegisterStorageKey, {
             storageKey: this._storageKey
@@ -112,15 +118,19 @@ class SynchronisedEntityStorageConnector {
      */
     async set(entity, conditions) {
         core.Guards.object(this.CLASS_NAME, "entity", entity);
-        // Make sure the entity has the required properties
-        entity.dateModified = new Date(Date.now()).toISOString();
-        await this._entityStorageConnector.set(entity, conditions);
-        // Tell the synchronised storage about the entity changes
-        await this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.LocalItemChange, {
-            storageKey: this._storageKey,
-            operation: synchronisedStorageModels.SyncChangeOperation.Set,
-            id: entity[this._primaryKey.property]
-        });
+        if (core.Is.stringValue(this._nodeIdentity)) {
+            // Make sure the entity has the required properties
+            entity.dateModified = new Date(Date.now()).toISOString();
+            entity.nodeIdentity = this._nodeIdentity;
+            await this._entityStorageConnector.set(entity, conditions);
+            // Tell the synchronised storage about the entity changes
+            await this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.LocalItemChange, {
+                storageKey: this._storageKey,
+                operation: synchronisedStorageModels.SyncChangeOperation.Set,
+                nodeIdentity: this._nodeIdentity,
+                id: entity[this._primaryKey.property]
+            });
+        }
     }
     /**
      * Remove the entity.
@@ -130,13 +140,16 @@ class SynchronisedEntityStorageConnector {
      */
     async remove(id, conditions) {
         core.Guards.stringValue(this.CLASS_NAME, "id", id);
-        await this._entityStorageConnector.remove(id, conditions);
-        // Tell the synchronised storage about the entity removal
-        await this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.LocalItemChange, {
-            storageKey: this._storageKey,
-            operation: synchronisedStorageModels.SyncChangeOperation.Delete,
-            id
-        });
+        if (core.Is.stringValue(this._nodeIdentity)) {
+            await this._entityStorageConnector.remove(id, conditions);
+            // Tell the synchronised storage about the entity removal
+            await this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.LocalItemChange, {
+                storageKey: this._storageKey,
+                operation: synchronisedStorageModels.SyncChangeOperation.Delete,
+                nodeIdentity: this._nodeIdentity,
+                id
+            });
+        }
     }
     /**
      * Find all the entities which match the conditions.
@@ -158,53 +171,144 @@ class SynchronisedEntityStorageConnector {
     handleEventBusMessages() {
         // When the synchronised storage requests an item, we need to provide it
         this._eventBusComponent.subscribe(synchronisedStorageModels.SynchronisedStorageTopics.LocalItemRequest, async (params) => {
-            // Only handle the request if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                let entity;
-                try {
-                    entity = await this._entityStorageConnector.get(params.data.id);
-                }
-                catch { }
-                // Publish the item response with the entity
-                this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.LocalItemResponse, {
-                    storageKey: this._storageKey,
-                    id: params.data.id,
-                    entity
-                });
-            }
+            await this.handleLocalItemRequest(params);
         });
         // When the synchronised storage requests a batch, we need to provide it
         this._eventBusComponent.subscribe(synchronisedStorageModels.SynchronisedStorageTopics.BatchRequest, async (params) => {
-            // Only handle the request if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                let cursor;
-                do {
-                    const result = await this._entityStorageConnector.query(undefined, [{ property: "dateModified", sortDirection: entity.SortDirection.Ascending }], undefined, cursor, params.data.batchSize);
-                    cursor = result.cursor;
-                    // Publish the batch response with the entities
-                    this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.BatchResponse, {
-                        storageKey: this._storageKey,
-                        entities: result.entities,
-                        lastEntry: !core.Is.stringValue(cursor)
-                    });
-                } while (core.Is.stringValue(cursor));
-            }
+            await this.handleBatchRequest(params);
         });
         // Subscribe to remote item set events from the synchronised storage and update the local storage
         this._eventBusComponent.subscribe(synchronisedStorageModels.SynchronisedStorageTopics.RemoteItemSet, async (params) => {
-            // Only remove the item if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                await this.set(params.data.entity);
-            }
+            await this.handleRemoteItemSet(params);
         });
         // Subscribe to remote item remove events from the synchronised storage and update the local storage
         this._eventBusComponent.subscribe(synchronisedStorageModels.SynchronisedStorageTopics.RemoteItemRemove, async (params) => {
-            // Only remove the item if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                await this.remove(params.data.id);
-            }
+            await this.handleRemoteItemRemove(params);
+        });
+        // Subscribe to resets from the synchronised storage and update the local storage
+        this._eventBusComponent.subscribe(synchronisedStorageModels.SynchronisedStorageTopics.Reset, async (params) => {
+            await this.handleReset(params);
         });
     }
+    /**
+     * Handle a local item request.
+     * @param event The request parameters
+     * @internal
+     */
+    async handleLocalItemRequest(event) {
+        // Only handle the request if it matches the storage key
+        if (event.data.storageKey === this._storageKey) {
+            let entity;
+            try {
+                entity = await this._entityStorageConnector.get(event.data.id);
+            }
+            catch { }
+            // Publish the item response with the entity
+            this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.LocalItemResponse, {
+                storageKey: this._storageKey,
+                id: event.data.id,
+                entity
+            });
+        }
+    }
+    /**
+     * Handle a remote item set event.
+     * @param event The event parameters
+     * @internal
+     */
+    async handleRemoteItemSet(event) {
+        // Only set the item if it matches the storage key
+        // and it is from another node, remote updates can not change data for this node
+        // That must be done via the regular entity storage methods
+        if (event.data.storageKey === this._storageKey &&
+            event.data.entity.nodeIdentity !== this._nodeIdentity) {
+            await this._entityStorageConnector.set(event.data.entity);
+        }
+    }
+    /**
+     * Handle a remote item remove event.
+     * @param params The event parameters
+     * @internal
+     */
+    async handleRemoteItemRemove(params) {
+        // Only remove the item if it matches the storage key
+        // and it is from another node, remote updates can not change data for this node
+        // That must be done via the regular entity storage methods
+        if (params.data.storageKey === this._storageKey &&
+            params.data.nodeIdentity !== this._nodeIdentity) {
+            await this._entityStorageConnector.remove(params.data.id);
+        }
+    }
+    /**
+     * Handle a batch request.
+     * @param event The request parameters
+     * @internal
+     */
+    async handleBatchRequest(event) {
+        // Only handle the request if it matches the storage key
+        if (event.data.storageKey === this._storageKey) {
+            let cursor;
+            do {
+                const condition = {
+                    conditions: []
+                };
+                if (event.data.requestMode === synchronisedStorageModels.SyncNodeIdentityMode.Local ||
+                    event.data.requestMode === synchronisedStorageModels.SyncNodeIdentityMode.Remote) {
+                    condition.conditions.push({
+                        property: "nodeIdentity",
+                        value: this._nodeIdentity,
+                        comparison: event.data.requestMode === synchronisedStorageModels.SyncNodeIdentityMode.Local
+                            ? entity.ComparisonOperator.Equals
+                            : entity.ComparisonOperator.NotEquals
+                    });
+                }
+                const result = await this._entityStorageConnector.query(condition, [{ property: "dateModified", sortDirection: entity.SortDirection.Ascending }], undefined, cursor, event.data.batchSize);
+                cursor = result.cursor;
+                // Publish the batch response with the entities
+                this._eventBusComponent.publish(synchronisedStorageModels.SynchronisedStorageTopics.BatchResponse, {
+                    storageKey: this._storageKey,
+                    entities: result.entities,
+                    lastEntry: !core.Is.stringValue(cursor)
+                });
+            } while (core.Is.stringValue(cursor));
+        }
+    }
+    /**
+     * Handle a reset event.
+     * @param event The event parameters
+     * @internal
+     */
+    async handleReset(event) {
+        // Only reset the storage if it matches the storage key
+        if (event.data.storageKey === this._storageKey) {
+            let cursor;
+            let toRemove = [];
+            // Build a list of the ids to remove
+            do {
+                const condition = {
+                    conditions: []
+                };
+                // Depending on the reset mode we can filter the entities to remove
+                if (event.data.resetMode === synchronisedStorageModels.SyncNodeIdentityMode.Local ||
+                    event.data.resetMode === synchronisedStorageModels.SyncNodeIdentityMode.Remote) {
+                    condition.conditions.push({
+                        property: "nodeIdentity",
+                        value: this._nodeIdentity,
+                        comparison: event.data.resetMode === synchronisedStorageModels.SyncNodeIdentityMode.Local
+                            ? entity.ComparisonOperator.Equals
+                            : entity.ComparisonOperator.NotEquals
+                    });
+                }
+                const result = await this._entityStorageConnector.query(condition, undefined, undefined, cursor);
+                cursor = result.cursor;
+                toRemove = toRemove.concat(result.entities.map(entity => entity.id));
+            } while (core.Is.stringValue(cursor));
+            // Remove the entities
+            for (let i = 0; i < toRemove.length; i++) {
+                await this.remove(toRemove[i]);
+            }
+        }
+    }
 }
 
 exports.SynchronisedEntityStorageConnector = SynchronisedEntityStorageConnector;

package/dist/esm/index.mjs

@@ -1,7 +1,7 @@
 import { Guards, StringHelper, Is, GeneralError, ComponentFactory } from '@twin.org/core';
-import { EntitySchemaFactory, EntitySchemaHelper, SortDirection } from '@twin.org/entity';
+import { EntitySchemaFactory, EntitySchemaHelper, ComparisonOperator, SortDirection } from '@twin.org/entity';
 import { EntityStorageConnectorFactory } from '@twin.org/entity-storage-models';
-import { SynchronisedStorageTopics, SyncChangeOperation } from '@twin.org/synchronised-storage-models';
+import { SynchronisedStorageTopics, SyncChangeOperation, SyncNodeIdentityMode } from '@twin.org/synchronised-storage-models';
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -38,6 +38,11 @@ class SynchronisedEntityStorageConnector {
      * @internal
      */
     _eventBusComponent;
+    /**
+     * The node identity.
+     * @internal
+     */
+    _nodeIdentity;
     /**
      * Create a new instance of SynchronisedEntityStorageConnector.
      * @param options The options for the connector.
@@ -85,6 +90,7 @@ class SynchronisedEntityStorageConnector {
      * @returns Nothing.
      */
     async start(nodeIdentity, nodeLoggingConnectorType, componentState) {
+        this._nodeIdentity = nodeIdentity;
         // Tell the synchronised storage about this storage key
         await this._eventBusComponent.publish(SynchronisedStorageTopics.RegisterStorageKey, {
             storageKey: this._storageKey
@@ -110,15 +116,19 @@ class SynchronisedEntityStorageConnector {
      */
     async set(entity, conditions) {
         Guards.object(this.CLASS_NAME, "entity", entity);
-        // Make sure the entity has the required properties
-        entity.dateModified = new Date(Date.now()).toISOString();
-        await this._entityStorageConnector.set(entity, conditions);
-        // Tell the synchronised storage about the entity changes
-        await this._eventBusComponent.publish(SynchronisedStorageTopics.LocalItemChange, {
-            storageKey: this._storageKey,
-            operation: SyncChangeOperation.Set,
-            id: entity[this._primaryKey.property]
-        });
+        if (Is.stringValue(this._nodeIdentity)) {
+            // Make sure the entity has the required properties
+            entity.dateModified = new Date(Date.now()).toISOString();
+            entity.nodeIdentity = this._nodeIdentity;
+            await this._entityStorageConnector.set(entity, conditions);
+            // Tell the synchronised storage about the entity changes
+            await this._eventBusComponent.publish(SynchronisedStorageTopics.LocalItemChange, {
+                storageKey: this._storageKey,
+                operation: SyncChangeOperation.Set,
+                nodeIdentity: this._nodeIdentity,
+                id: entity[this._primaryKey.property]
+            });
+        }
     }
     /**
      * Remove the entity.
@@ -128,13 +138,16 @@ class SynchronisedEntityStorageConnector {
      */
     async remove(id, conditions) {
         Guards.stringValue(this.CLASS_NAME, "id", id);
-        await this._entityStorageConnector.remove(id, conditions);
-        // Tell the synchronised storage about the entity removal
-        await this._eventBusComponent.publish(SynchronisedStorageTopics.LocalItemChange, {
-            storageKey: this._storageKey,
-            operation: SyncChangeOperation.Delete,
-            id
-        });
+        if (Is.stringValue(this._nodeIdentity)) {
+            await this._entityStorageConnector.remove(id, conditions);
+            // Tell the synchronised storage about the entity removal
+            await this._eventBusComponent.publish(SynchronisedStorageTopics.LocalItemChange, {
+                storageKey: this._storageKey,
+                operation: SyncChangeOperation.Delete,
+                nodeIdentity: this._nodeIdentity,
+                id
+            });
+        }
     }
     /**
      * Find all the entities which match the conditions.
@@ -156,53 +169,144 @@ class SynchronisedEntityStorageConnector {
     handleEventBusMessages() {
         // When the synchronised storage requests an item, we need to provide it
         this._eventBusComponent.subscribe(SynchronisedStorageTopics.LocalItemRequest, async (params) => {
-            // Only handle the request if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                let entity;
-                try {
-                    entity = await this._entityStorageConnector.get(params.data.id);
-                }
-                catch { }
-                // Publish the item response with the entity
-                this._eventBusComponent.publish(SynchronisedStorageTopics.LocalItemResponse, {
-                    storageKey: this._storageKey,
-                    id: params.data.id,
-                    entity
-                });
-            }
+            await this.handleLocalItemRequest(params);
         });
         // When the synchronised storage requests a batch, we need to provide it
         this._eventBusComponent.subscribe(SynchronisedStorageTopics.BatchRequest, async (params) => {
-            // Only handle the request if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                let cursor;
-                do {
-                    const result = await this._entityStorageConnector.query(undefined, [{ property: "dateModified", sortDirection: SortDirection.Ascending }], undefined, cursor, params.data.batchSize);
-                    cursor = result.cursor;
-                    // Publish the batch response with the entities
-                    this._eventBusComponent.publish(SynchronisedStorageTopics.BatchResponse, {
-                        storageKey: this._storageKey,
-                        entities: result.entities,
-                        lastEntry: !Is.stringValue(cursor)
-                    });
-                } while (Is.stringValue(cursor));
-            }
+            await this.handleBatchRequest(params);
         });
         // Subscribe to remote item set events from the synchronised storage and update the local storage
         this._eventBusComponent.subscribe(SynchronisedStorageTopics.RemoteItemSet, async (params) => {
-            // Only remove the item if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                await this.set(params.data.entity);
-            }
+            await this.handleRemoteItemSet(params);
         });
         // Subscribe to remote item remove events from the synchronised storage and update the local storage
         this._eventBusComponent.subscribe(SynchronisedStorageTopics.RemoteItemRemove, async (params) => {
-            // Only remove the item if it matches the storage key
-            if (params.data.storageKey === this._storageKey) {
-                await this.remove(params.data.id);
-            }
+            await this.handleRemoteItemRemove(params);
+        });
+        // Subscribe to resets from the synchronised storage and update the local storage
+        this._eventBusComponent.subscribe(SynchronisedStorageTopics.Reset, async (params) => {
+            await this.handleReset(params);
         });
     }
+    /**
+     * Handle a local item request.
+     * @param event The request parameters
+     * @internal
+     */
+    async handleLocalItemRequest(event) {
+        // Only handle the request if it matches the storage key
+        if (event.data.storageKey === this._storageKey) {
+            let entity;
+            try {
+                entity = await this._entityStorageConnector.get(event.data.id);
+            }
+            catch { }
+            // Publish the item response with the entity
+            this._eventBusComponent.publish(SynchronisedStorageTopics.LocalItemResponse, {
+                storageKey: this._storageKey,
+                id: event.data.id,
+                entity
+            });
+        }
+    }
+    /**
+     * Handle a remote item set event.
+     * @param event The event parameters
+     * @internal
+     */
+    async handleRemoteItemSet(event) {
+        // Only set the item if it matches the storage key
+        // and it is from another node, remote updates can not change data for this node
+        // That must be done via the regular entity storage methods
+        if (event.data.storageKey === this._storageKey &&
+            event.data.entity.nodeIdentity !== this._nodeIdentity) {
+            await this._entityStorageConnector.set(event.data.entity);
+        }
+    }
+    /**
+     * Handle a remote item remove event.
+     * @param params The event parameters
+     * @internal
+     */
+    async handleRemoteItemRemove(params) {
+        // Only remove the item if it matches the storage key
+        // and it is from another node, remote updates can not change data for this node
+        // That must be done via the regular entity storage methods
+        if (params.data.storageKey === this._storageKey &&
+            params.data.nodeIdentity !== this._nodeIdentity) {
+            await this._entityStorageConnector.remove(params.data.id);
+        }
+    }
+    /**
+     * Handle a batch request.
+     * @param event The request parameters
+     * @internal
+     */
+    async handleBatchRequest(event) {
+        // Only handle the request if it matches the storage key
+        if (event.data.storageKey === this._storageKey) {
+            let cursor;
+            do {
+                const condition = {
+                    conditions: []
+                };
+                if (event.data.requestMode === SyncNodeIdentityMode.Local ||
+                    event.data.requestMode === SyncNodeIdentityMode.Remote) {
+                    condition.conditions.push({
+                        property: "nodeIdentity",
+                        value: this._nodeIdentity,
+                        comparison: event.data.requestMode === SyncNodeIdentityMode.Local
+                            ? ComparisonOperator.Equals
+                            : ComparisonOperator.NotEquals
+                    });
+                }
+                const result = await this._entityStorageConnector.query(condition, [{ property: "dateModified", sortDirection: SortDirection.Ascending }], undefined, cursor, event.data.batchSize);
+                cursor = result.cursor;
+                // Publish the batch response with the entities
+                this._eventBusComponent.publish(SynchronisedStorageTopics.BatchResponse, {
+                    storageKey: this._storageKey,
+                    entities: result.entities,
+                    lastEntry: !Is.stringValue(cursor)
+                });
+            } while (Is.stringValue(cursor));
+        }
+    }
+    /**
+     * Handle a reset event.
+     * @param event The event parameters
+     * @internal
+     */
+    async handleReset(event) {
+        // Only reset the storage if it matches the storage key
+        if (event.data.storageKey === this._storageKey) {
+            let cursor;
+            let toRemove = [];
+            // Build a list of the ids to remove
+            do {
+                const condition = {
+                    conditions: []
+                };
+                // Depending on the reset mode we can filter the entities to remove
+                if (event.data.resetMode === SyncNodeIdentityMode.Local ||
+                    event.data.resetMode === SyncNodeIdentityMode.Remote) {
+                    condition.conditions.push({
+                        property: "nodeIdentity",
+                        value: this._nodeIdentity,
+                        comparison: event.data.resetMode === SyncNodeIdentityMode.Local
+                            ? ComparisonOperator.Equals
+                            : ComparisonOperator.NotEquals
+                    });
+                }
+                const result = await this._entityStorageConnector.query(condition, undefined, undefined, cursor);
+                cursor = result.cursor;
+                toRemove = toRemove.concat(result.entities.map(entity => entity.id));
+            } while (Is.stringValue(cursor));
+            // Remove the entities
+            for (let i = 0; i < toRemove.length; i++) {
+                await this.remove(toRemove[i]);
+            }
+        }
+    }
 }
 
 export { SynchronisedEntityStorageConnector };

package/docs/changelog.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.0.2-next.5](https://github.com/twinfoundation/entity-storage/compare/entity-storage-connector-synchronised-v0.0.2-next.4...entity-storage-connector-synchronised-v0.0.2-next.5) (2025-08-11)
+
+
+### Features
+
+* support new synchronised storage features ([0d9ebab](https://github.com/twinfoundation/entity-storage/commit/0d9ebab237040892cab8e7db751aa2e40c0c76e0))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.0.2-next.4 to 0.0.2-next.5
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.0.2-next.4 to 0.0.2-next.5
+
 ## [0.0.2-next.4](https://github.com/twinfoundation/entity-storage/compare/entity-storage-connector-synchronised-v0.0.2-next.3...entity-storage-connector-synchronised-v0.0.2-next.4) (2025-08-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-connector-synchronised",
-	"version": "0.0.2-next.4",
+	"version": "0.0.2-next.5",
 	"description": "Entity Storage connector implementation using synchronised storage",
 	"repository": {
 		"type": "git",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.0.2-next.4",
+		"@twin.org/entity-storage-models": "0.0.2-next.5",
 		"@twin.org/event-bus-models": "next",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",