@twin.org/auditable-item-graph-service 0.0.2-next.3 → 0.0.2-next.5

package/dist/cjs/index.cjs

@@ -89,7 +89,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                             ],
                             edges: [
                                 {
-                                    id: "edge1",
+                                    targetId: "aig:1234567890",
                                     edgeRelationships: ["frenemy"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -98,7 +98,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                                     }
                                 },
                                 {
-                                    id: "edge2",
+                                    targetId: "aig:45678901234",
                                     edgeRelationships: ["end"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -297,6 +297,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                             edges: [
                                 {
                                     id: "edge1",
+                                    targetId: "aig:1234567890",
                                     edgeRelationships: ["frenemy"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -306,6 +307,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                                 },
                                 {
                                     id: "edge2",
+                                    targetId: "aig:45678901234",
                                     edgeRelationships: ["end"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -521,6 +523,7 @@ async function auditableItemGraphList(httpRequestContext, componentName, request
     const result = await component.query({
         id: request.query?.id,
         idMode: request.query?.idMode,
+        idExact: core.Coerce.boolean(request.query?.idExact),
         resourceTypes: apiModels.HttpParameterHelper.arrayFromString(request.query?.resourceTypes)
     }, apiModels.HttpParameterHelper.objectFromString(request.query?.conditions), request.query?.orderBy, request.query?.orderByDirection, apiModels.HttpParameterHelper.arrayFromString(request.query?.properties), request.query?.cursor, core.Coerce.integer(request.query?.pageSize));
     return {
@@ -537,15 +540,19 @@ async function auditableItemGraphList(httpRequestContext, componentName, request
  * Class for performing auditable item graph operations.
  */
 class AuditableItemGraphService {
+    /**
+     * The namespace for the service.
+     * @internal
+     */
+    static NAMESPACE = "aig";
     /**
      * The namespace for the service changeset.
      */
     static NAMESPACE_CHANGESET = "changeset";
     /**
-     * The namespace for the service.
-     * @internal
+     * The namespace for the service edge.
      */
-    static _NAMESPACE = "aig";
+    static NAMESPACE_EDGE = "edge";
     /**
      * The keys to pick when creating the proof for the stream.
      * @internal
@@ -639,7 +646,7 @@ class AuditableItemGraphService {
                 ...vertexModel,
                 ...this.buildIndexes(vertexModel)
             });
-            const fullId = new core.Urn(AuditableItemGraphService._NAMESPACE, id).toString();
+            const fullId = new core.Urn(AuditableItemGraphService.NAMESPACE, id).toString();
             await this._eventBusComponent?.publish(auditableItemGraphModels.AuditableItemGraphTopics.VertexCreated, { id: fullId });
             return fullId;
         }
@@ -660,9 +667,9 @@ class AuditableItemGraphService {
     async get(id, options) {
         core.Guards.stringValue(this.CLASS_NAME, "id", id);
         const urnParsed = core.Urn.fromValidString(id);
-        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService._NAMESPACE) {
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
             throw new core.GeneralError(this.CLASS_NAME, "namespaceMismatch", {
-                namespace: AuditableItemGraphService._NAMESPACE,
+                namespace: AuditableItemGraphService.NAMESPACE,
                 id
             });
         }
@@ -735,9 +742,9 @@ class AuditableItemGraphService {
         core.Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
         core.Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
         const urnParsed = core.Urn.fromValidString(vertex.id);
-        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService._NAMESPACE) {
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
             throw new core.GeneralError(this.CLASS_NAME, "namespaceMismatch", {
-                namespace: AuditableItemGraphService._NAMESPACE,
+                namespace: AuditableItemGraphService.NAMESPACE,
                 id: vertex.id
             });
         }
@@ -790,9 +797,9 @@ class AuditableItemGraphService {
         core.Guards.stringValue(this.CLASS_NAME, "id", id);
         core.Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
         const urnParsed = core.Urn.fromValidString(id);
-        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService._NAMESPACE) {
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
             throw new core.GeneralError(this.CLASS_NAME, "namespaceMismatch", {
-                namespace: AuditableItemGraphService._NAMESPACE,
+                namespace: AuditableItemGraphService.NAMESPACE,
                 id
             });
         }
@@ -832,6 +839,7 @@ class AuditableItemGraphService {
      * @param options The query options.
      * @param options.id The optional id to look for.
      * @param options.idMode Look in id, alias or both, defaults to both.
+     * @param options.idExact Find only exact matches, default to false meaning partial matching.
      * @param options.includesResourceTypes Include vertices with specific resource types.
      * @param conditions Conditions to use in the query.
      * @param orderBy The order for the results, defaults to created.
@@ -853,13 +861,14 @@ class AuditableItemGraphService {
             const combinedConditions = conditions ?? [];
             const orderProperty = orderBy ?? "dateCreated";
             const orderDirection = orderByDirection ?? entity.SortDirection.Descending;
+            const idExact = options?.idExact ?? false;
             const idOrAlias = options?.id;
             if (core.Is.stringValue(idOrAlias)) {
                 const idMode = options?.idMode ?? "both";
                 if (idMode === "id" || idMode === "both") {
                     combinedConditions.push({
                         property: "id",
-                        comparison: entity.ComparisonOperator.Includes,
+                        comparison: idExact ? entity.ComparisonOperator.Equals : entity.ComparisonOperator.Includes,
                         value: idOrAlias
                     });
                 }
@@ -867,7 +876,7 @@ class AuditableItemGraphService {
                     combinedConditions.push({
                         property: "aliasIndex",
                         comparison: entity.ComparisonOperator.Includes,
-                        value: idOrAlias.toLowerCase()
+                        value: idExact ? `||${idOrAlias.toLowerCase()}||` : idOrAlias.toLowerCase()
                     });
                 }
             }
@@ -876,7 +885,7 @@ class AuditableItemGraphService {
                     combinedConditions.push({
                         property: "resourceTypeIndex",
                         comparison: entity.ComparisonOperator.Includes,
-                        value: resourceType.toLowerCase()
+                        value: `||${resourceType.toLowerCase()}||`
                     });
                 }
             }
@@ -925,7 +934,7 @@ class AuditableItemGraphService {
                 standardsSchemaOrg.SchemaOrgContexts.ContextRoot
             ],
             type: auditableItemGraphModels.AuditableItemGraphTypes.Vertex,
-            id: new core.Urn(AuditableItemGraphService._NAMESPACE, vertexEntity.id).toString(),
+            id: new core.Urn(AuditableItemGraphService.NAMESPACE, vertexEntity.id).toString(),
             dateCreated: vertexEntity.dateCreated,
             dateModified: vertexEntity.dateModified,
             nodeIdentity: vertexEntity.nodeIdentity,
@@ -980,7 +989,8 @@ class AuditableItemGraphService {
                         standardsSchemaOrg.SchemaOrgContexts.ContextRoot
                     ],
                     type: auditableItemGraphModels.AuditableItemGraphTypes.Edge,
-                    id: edgeEntity.id,
+                    id: this.fullEdgeId(vertexEntity.id, edgeEntity.id),
+                    targetId: edgeEntity.targetId,
                     dateCreated: edgeEntity.dateCreated,
                     dateModified: edgeEntity.dateModified,
                     dateDeleted: edgeEntity.dateDeleted,
@@ -994,11 +1004,12 @@ class AuditableItemGraphService {
     }
     /**
      * Map the changeset entity to a JSON-LD.
+     * @param vertexId The id of the vertex the changeset belongs to.
      * @param changesetEntity The changeset entity.
      * @returns The model.
      * @internal
      */
-    changesetEntityToJsonLd(changesetEntity) {
+    changesetEntityToJsonLd(vertexId, changesetEntity) {
         const model = {
             "@context": [
                 auditableItemGraphModels.AuditableItemGraphContexts.ContextRoot,
@@ -1006,7 +1017,11 @@ class AuditableItemGraphService {
                 standardsSchemaOrg.SchemaOrgContexts.ContextRoot
             ],
             type: auditableItemGraphModels.AuditableItemGraphTypes.Changeset,
-            id: changesetEntity.id,
+            id: new core.Urn(AuditableItemGraphService.NAMESPACE, [
+                vertexId,
+                AuditableItemGraphService.NAMESPACE_CHANGESET,
+                changesetEntity.id
+            ]).toString(),
             dateCreated: changesetEntity.dateCreated,
             userIdentity: changesetEntity.userIdentity,
             patches: changesetEntity.patches.map(p => ({
@@ -1058,6 +1073,12 @@ class AuditableItemGraphService {
     async updateAlias(context, vertex, alias) {
         core.Guards.object(this.CLASS_NAME, "alias", alias);
         core.Guards.stringValue(this.CLASS_NAME, "alias.id", alias.id);
+        if (alias.unique ?? false) {
+            const existingVertices = await this.findMatchingVertices(vertex.id, alias.id);
+            if (existingVertices) {
+                throw new core.GeneralError(this.CLASS_NAME, "aliasNotUnique", { aliasId: alias.id });
+            }
+        }
         if (core.Is.object(alias.annotationObject)) {
             const validationFailures = [];
             await dataJsonLd.JsonLdHelper.validate(alias.annotationObject, validationFailures);
@@ -1159,7 +1180,7 @@ class AuditableItemGraphService {
         // The active edges that are not in the update list should be marked as deleted.
         if (core.Is.arrayValue(active)) {
             for (const edge of active) {
-                if (!edges?.find(a => a.id === edge.id)) {
+                if (!edges?.find(e => core.Is.stringValue(e.id) && this.reduceEdgeId(e.id) === edge.id)) {
                     edge.dateDeleted = context.now;
                 }
             }
@@ -1179,15 +1200,15 @@ class AuditableItemGraphService {
      */
     async updateEdge(context, vertex, edge) {
         core.Guards.object(this.CLASS_NAME, "edge", edge);
-        core.Guards.stringValue(this.CLASS_NAME, "edge.id", edge.id);
+        core.Guards.stringValue(this.CLASS_NAME, "edge.targetId", edge.targetId);
         core.Guards.arrayValue(this.CLASS_NAME, "edge.edgeRelationships", edge.edgeRelationships);
         const validationFailures = [];
-        if (edge.id === vertex.id) {
+        if (edge.targetId === vertex.id) {
             validationFailures.push({
                 property: "id",
                 reason: `validation.${core.StringHelper.camelCase(this.CLASS_NAME)}.edgeIdSameAsVertexId`,
                 properties: {
-                    id: edge.id
+                    targetId: edge.targetId
                 }
             });
         }
@@ -1195,22 +1216,29 @@ class AuditableItemGraphService {
             await dataJsonLd.JsonLdHelper.validate(edge.annotationObject, validationFailures);
         }
         core.Validation.asValidationError(this.CLASS_NAME, "edge.annotationObject", validationFailures);
+        let findId = core.Is.stringValue(edge.id) ? this.reduceEdgeId(edge.id) : undefined;
+        if (core.Is.empty(findId)) {
+            findId = core.Converter.bytesToHex(core.RandomHelper.generate(32), false);
+        }
         // Try to find an existing edge with the same id.
-        const existing = vertex.edges?.find(r => r.id === edge.id);
+        const existing = vertex.edges?.find(r => r.id === findId);
         if (core.Is.empty(existing) || !core.Is.empty(existing?.dateDeleted)) {
             // Did not find a matching item, or found one which is deleted.
             vertex.edges ??= [];
             const model = {
-                id: edge.id,
+                id: findId,
+                targetId: edge.targetId,
                 dateCreated: context.now,
                 annotationObject: edge.annotationObject,
                 edgeRelationships: edge.edgeRelationships
             };
             vertex.edges.push(model);
         }
-        else if (!core.ArrayHelper.matches(existing.edgeRelationships, edge.edgeRelationships) ||
+        else if (existing.targetId !== edge.targetId ||
+            !core.ArrayHelper.matches(existing.edgeRelationships, edge.edgeRelationships) ||
             !core.ObjectHelper.equal(existing.annotationObject, edge.annotationObject, false)) {
-            // Existing resource found, update the annotationObject.
+            // Existing edge found, update the properties.
+            existing.targetId = edge.targetId;
             existing.dateModified = context.now;
             existing.edgeRelationships = edge.edgeRelationships;
             existing.annotationObject = edge.annotationObject;
@@ -1238,10 +1266,7 @@ class AuditableItemGraphService {
             };
             // Create the JSON-LD object we want to use for the proof
             // this is a subset of fixed properties from the changeset object.
-            const reducedChangesetJsonLd = await this.changesetEntityToJsonLd({
-                ...core.ObjectHelper.pick(changesetEntity, AuditableItemGraphService._PROOF_KEYS_CHANGESET),
-                id: `${AuditableItemGraphService._NAMESPACE}:${updated.id}:${AuditableItemGraphService.NAMESPACE_CHANGESET}:${changesetEntity.id}`
-            });
+            const reducedChangesetJsonLd = await this.changesetEntityToJsonLd(original.id, core.ObjectHelper.pick(changesetEntity, AuditableItemGraphService._PROOF_KEYS_CHANGESET));
             // Create the proof for the changeset object
             changesetEntity.proofId = await this._immutableProofComponent.create(reducedChangesetJsonLd, context.userIdentity, context.nodeIdentity);
             // Link the verifiable storage id to the changeset
@@ -1277,7 +1302,7 @@ class AuditableItemGraphService {
             if (core.Is.arrayValue(storedChangesets)) {
                 for (let i = 0; i < storedChangesets.length; i++) {
                     const storedChangeset = storedChangesets[i];
-                    const storedChangesetJsonLd = this.changesetEntityToJsonLd(storedChangeset);
+                    const storedChangesetJsonLd = this.changesetEntityToJsonLd(vertexId.namespaceSpecific(), storedChangeset);
                     changesets.push(storedChangesetJsonLd);
                     // If we are verifying all signatures
                     // or this is the last changeset (cursor is empty)
@@ -1345,10 +1370,72 @@ class AuditableItemGraphService {
         }
         const resourceTypeIndex = resourceTypes.join("||").toLowerCase();
         return {
-            aliasIndex: core.Is.stringValue(aliasIndex) ? aliasIndex : undefined,
-            resourceTypeIndex: core.Is.stringValue(resourceTypeIndex) ? resourceTypeIndex : undefined
+            aliasIndex: core.Is.stringValue(aliasIndex) ? `||${aliasIndex}||` : undefined,
+            resourceTypeIndex: core.Is.stringValue(resourceTypeIndex) ? `||${resourceTypeIndex}||` : undefined
         };
     }
+    /**
+     * Find vertices with matching aliases.
+     * @param vertexId The id of the vertex to exclude from the search.
+     * @param aliasId The alias id to try and find.
+     * @returns True if any other vertices have matching aliases.
+     * @internal
+     */
+    async findMatchingVertices(vertexId, aliasId) {
+        const results = await this._vertexStorage.query({
+            conditions: [
+                {
+                    property: "aliasIndex",
+                    comparison: entity.ComparisonOperator.Includes,
+                    value: `||${aliasId.toLowerCase()}||`
+                },
+                {
+                    property: "id",
+                    value: vertexId,
+                    comparison: entity.ComparisonOperator.NotEquals
+                }
+            ],
+            logicalOperator: entity.LogicalOperator.And
+        });
+        return results.entities.length > 0;
+    }
+    /**
+     * Reduce the edge ID from a URN.
+     * @param urn The URN to reduce.
+     * @returns The edge ID.
+     * @throws GeneralError if the URN is not valid or not an edge URN.
+     * @internal
+     */
+    reduceEdgeId(urn) {
+        const urnParsed = core.Urn.fromValidString(urn);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new core.GeneralError(this.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id: urn
+            });
+        }
+        if (urnParsed.namespaceSpecificParts().length !== 3) {
+            throw new core.GeneralError(this.CLASS_NAME, "invalidEdgeId", { id: urn });
+        }
+        if (urnParsed.namespaceSpecificParts()[1] !== AuditableItemGraphService.NAMESPACE_EDGE) {
+            throw new core.GeneralError(this.CLASS_NAME, "invalidEdgeId", { id: urn });
+        }
+        return urnParsed.namespaceSpecificParts()[2];
+    }
+    /**
+     * Create a full edge ID URN from a vertex ID and edge ID.
+     * @param vertexId The vertex id the edge belongs to.
+     * @param edgeId The edge id.
+     * @returns The full edge ID URN.
+     * @internal
+     */
+    fullEdgeId(vertexId, edgeId) {
+        return new core.Urn(AuditableItemGraphService.NAMESPACE, [
+            vertexId,
+            AuditableItemGraphService.NAMESPACE_EDGE,
+            edgeId
+        ]).toString();
+    }
 }
 
 // Copyright 2024 IOTA Stiftung.
@@ -1491,6 +1578,10 @@ exports.AuditableItemGraphEdge = class AuditableItemGraphEdge {
      * The timestamp of when the edge was deleted, as we never actually remove items.
      */
     dateDeleted;
+    /**
+     * The target id of the edge.
+     */
+    targetId;
     /**
      * The relationships between the two vertices.
      */
@@ -1516,6 +1607,10 @@ __decorate([
     entity.property({ type: "string", format: "date-time", optional: true }),
     __metadata("design:type", String)
 ], exports.AuditableItemGraphEdge.prototype, "dateDeleted", void 0);
+__decorate([
+    entity.property({ type: "string" }),
+    __metadata("design:type", String)
+], exports.AuditableItemGraphEdge.prototype, "targetId", void 0);
 __decorate([
     entity.property({ type: "array" }),
     __metadata("design:type", Array)

package/dist/esm/index.mjs

@@ -87,7 +87,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                             ],
                             edges: [
                                 {
-                                    id: "edge1",
+                                    targetId: "aig:1234567890",
                                     edgeRelationships: ["frenemy"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -96,7 +96,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                                     }
                                 },
                                 {
-                                    id: "edge2",
+                                    targetId: "aig:45678901234",
                                     edgeRelationships: ["end"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -295,6 +295,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                             edges: [
                                 {
                                     id: "edge1",
+                                    targetId: "aig:1234567890",
                                     edgeRelationships: ["frenemy"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -304,6 +305,7 @@ function generateRestRoutesAuditableItemGraph(baseRouteName, componentName) {
                                 },
                                 {
                                     id: "edge2",
+                                    targetId: "aig:45678901234",
                                     edgeRelationships: ["end"],
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -519,6 +521,7 @@ async function auditableItemGraphList(httpRequestContext, componentName, request
     const result = await component.query({
         id: request.query?.id,
         idMode: request.query?.idMode,
+        idExact: Coerce.boolean(request.query?.idExact),
         resourceTypes: HttpParameterHelper.arrayFromString(request.query?.resourceTypes)
     }, HttpParameterHelper.objectFromString(request.query?.conditions), request.query?.orderBy, request.query?.orderByDirection, HttpParameterHelper.arrayFromString(request.query?.properties), request.query?.cursor, Coerce.integer(request.query?.pageSize));
     return {
@@ -535,15 +538,19 @@ async function auditableItemGraphList(httpRequestContext, componentName, request
  * Class for performing auditable item graph operations.
  */
 class AuditableItemGraphService {
+    /**
+     * The namespace for the service.
+     * @internal
+     */
+    static NAMESPACE = "aig";
     /**
      * The namespace for the service changeset.
      */
     static NAMESPACE_CHANGESET = "changeset";
     /**
-     * The namespace for the service.
-     * @internal
+     * The namespace for the service edge.
      */
-    static _NAMESPACE = "aig";
+    static NAMESPACE_EDGE = "edge";
     /**
      * The keys to pick when creating the proof for the stream.
      * @internal
@@ -637,7 +644,7 @@ class AuditableItemGraphService {
                 ...vertexModel,
                 ...this.buildIndexes(vertexModel)
             });
-            const fullId = new Urn(AuditableItemGraphService._NAMESPACE, id).toString();
+            const fullId = new Urn(AuditableItemGraphService.NAMESPACE, id).toString();
             await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexCreated, { id: fullId });
             return fullId;
         }
@@ -658,9 +665,9 @@ class AuditableItemGraphService {
     async get(id, options) {
         Guards.stringValue(this.CLASS_NAME, "id", id);
         const urnParsed = Urn.fromValidString(id);
-        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService._NAMESPACE) {
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
             throw new GeneralError(this.CLASS_NAME, "namespaceMismatch", {
-                namespace: AuditableItemGraphService._NAMESPACE,
+                namespace: AuditableItemGraphService.NAMESPACE,
                 id
             });
         }
@@ -733,9 +740,9 @@ class AuditableItemGraphService {
         Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
         Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
         const urnParsed = Urn.fromValidString(vertex.id);
-        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService._NAMESPACE) {
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
             throw new GeneralError(this.CLASS_NAME, "namespaceMismatch", {
-                namespace: AuditableItemGraphService._NAMESPACE,
+                namespace: AuditableItemGraphService.NAMESPACE,
                 id: vertex.id
             });
         }
@@ -788,9 +795,9 @@ class AuditableItemGraphService {
         Guards.stringValue(this.CLASS_NAME, "id", id);
         Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
         const urnParsed = Urn.fromValidString(id);
-        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService._NAMESPACE) {
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
             throw new GeneralError(this.CLASS_NAME, "namespaceMismatch", {
-                namespace: AuditableItemGraphService._NAMESPACE,
+                namespace: AuditableItemGraphService.NAMESPACE,
                 id
             });
         }
@@ -830,6 +837,7 @@ class AuditableItemGraphService {
      * @param options The query options.
      * @param options.id The optional id to look for.
      * @param options.idMode Look in id, alias or both, defaults to both.
+     * @param options.idExact Find only exact matches, default to false meaning partial matching.
      * @param options.includesResourceTypes Include vertices with specific resource types.
      * @param conditions Conditions to use in the query.
      * @param orderBy The order for the results, defaults to created.
@@ -851,13 +859,14 @@ class AuditableItemGraphService {
             const combinedConditions = conditions ?? [];
             const orderProperty = orderBy ?? "dateCreated";
             const orderDirection = orderByDirection ?? SortDirection.Descending;
+            const idExact = options?.idExact ?? false;
             const idOrAlias = options?.id;
             if (Is.stringValue(idOrAlias)) {
                 const idMode = options?.idMode ?? "both";
                 if (idMode === "id" || idMode === "both") {
                     combinedConditions.push({
                         property: "id",
-                        comparison: ComparisonOperator.Includes,
+                        comparison: idExact ? ComparisonOperator.Equals : ComparisonOperator.Includes,
                         value: idOrAlias
                     });
                 }
@@ -865,7 +874,7 @@ class AuditableItemGraphService {
                     combinedConditions.push({
                         property: "aliasIndex",
                         comparison: ComparisonOperator.Includes,
-                        value: idOrAlias.toLowerCase()
+                        value: idExact ? `||${idOrAlias.toLowerCase()}||` : idOrAlias.toLowerCase()
                     });
                 }
             }
@@ -874,7 +883,7 @@ class AuditableItemGraphService {
                     combinedConditions.push({
                         property: "resourceTypeIndex",
                         comparison: ComparisonOperator.Includes,
-                        value: resourceType.toLowerCase()
+                        value: `||${resourceType.toLowerCase()}||`
                     });
                 }
             }
@@ -923,7 +932,7 @@ class AuditableItemGraphService {
                 SchemaOrgContexts.ContextRoot
             ],
             type: AuditableItemGraphTypes.Vertex,
-            id: new Urn(AuditableItemGraphService._NAMESPACE, vertexEntity.id).toString(),
+            id: new Urn(AuditableItemGraphService.NAMESPACE, vertexEntity.id).toString(),
             dateCreated: vertexEntity.dateCreated,
             dateModified: vertexEntity.dateModified,
             nodeIdentity: vertexEntity.nodeIdentity,
@@ -978,7 +987,8 @@ class AuditableItemGraphService {
                         SchemaOrgContexts.ContextRoot
                     ],
                     type: AuditableItemGraphTypes.Edge,
-                    id: edgeEntity.id,
+                    id: this.fullEdgeId(vertexEntity.id, edgeEntity.id),
+                    targetId: edgeEntity.targetId,
                     dateCreated: edgeEntity.dateCreated,
                     dateModified: edgeEntity.dateModified,
                     dateDeleted: edgeEntity.dateDeleted,
@@ -992,11 +1002,12 @@ class AuditableItemGraphService {
     }
     /**
      * Map the changeset entity to a JSON-LD.
+     * @param vertexId The id of the vertex the changeset belongs to.
      * @param changesetEntity The changeset entity.
      * @returns The model.
      * @internal
      */
-    changesetEntityToJsonLd(changesetEntity) {
+    changesetEntityToJsonLd(vertexId, changesetEntity) {
         const model = {
             "@context": [
                 AuditableItemGraphContexts.ContextRoot,
@@ -1004,7 +1015,11 @@ class AuditableItemGraphService {
                 SchemaOrgContexts.ContextRoot
             ],
             type: AuditableItemGraphTypes.Changeset,
-            id: changesetEntity.id,
+            id: new Urn(AuditableItemGraphService.NAMESPACE, [
+                vertexId,
+                AuditableItemGraphService.NAMESPACE_CHANGESET,
+                changesetEntity.id
+            ]).toString(),
             dateCreated: changesetEntity.dateCreated,
             userIdentity: changesetEntity.userIdentity,
             patches: changesetEntity.patches.map(p => ({
@@ -1056,6 +1071,12 @@ class AuditableItemGraphService {
     async updateAlias(context, vertex, alias) {
         Guards.object(this.CLASS_NAME, "alias", alias);
         Guards.stringValue(this.CLASS_NAME, "alias.id", alias.id);
+        if (alias.unique ?? false) {
+            const existingVertices = await this.findMatchingVertices(vertex.id, alias.id);
+            if (existingVertices) {
+                throw new GeneralError(this.CLASS_NAME, "aliasNotUnique", { aliasId: alias.id });
+            }
+        }
         if (Is.object(alias.annotationObject)) {
             const validationFailures = [];
             await JsonLdHelper.validate(alias.annotationObject, validationFailures);
@@ -1157,7 +1178,7 @@ class AuditableItemGraphService {
         // The active edges that are not in the update list should be marked as deleted.
         if (Is.arrayValue(active)) {
             for (const edge of active) {
-                if (!edges?.find(a => a.id === edge.id)) {
+                if (!edges?.find(e => Is.stringValue(e.id) && this.reduceEdgeId(e.id) === edge.id)) {
                     edge.dateDeleted = context.now;
                 }
             }
@@ -1177,15 +1198,15 @@ class AuditableItemGraphService {
      */
     async updateEdge(context, vertex, edge) {
         Guards.object(this.CLASS_NAME, "edge", edge);
-        Guards.stringValue(this.CLASS_NAME, "edge.id", edge.id);
+        Guards.stringValue(this.CLASS_NAME, "edge.targetId", edge.targetId);
         Guards.arrayValue(this.CLASS_NAME, "edge.edgeRelationships", edge.edgeRelationships);
         const validationFailures = [];
-        if (edge.id === vertex.id) {
+        if (edge.targetId === vertex.id) {
             validationFailures.push({
                 property: "id",
                 reason: `validation.${StringHelper.camelCase(this.CLASS_NAME)}.edgeIdSameAsVertexId`,
                 properties: {
-                    id: edge.id
+                    targetId: edge.targetId
                 }
             });
         }
@@ -1193,22 +1214,29 @@ class AuditableItemGraphService {
             await JsonLdHelper.validate(edge.annotationObject, validationFailures);
         }
         Validation.asValidationError(this.CLASS_NAME, "edge.annotationObject", validationFailures);
+        let findId = Is.stringValue(edge.id) ? this.reduceEdgeId(edge.id) : undefined;
+        if (Is.empty(findId)) {
+            findId = Converter.bytesToHex(RandomHelper.generate(32), false);
+        }
         // Try to find an existing edge with the same id.
-        const existing = vertex.edges?.find(r => r.id === edge.id);
+        const existing = vertex.edges?.find(r => r.id === findId);
         if (Is.empty(existing) || !Is.empty(existing?.dateDeleted)) {
             // Did not find a matching item, or found one which is deleted.
             vertex.edges ??= [];
             const model = {
-                id: edge.id,
+                id: findId,
+                targetId: edge.targetId,
                 dateCreated: context.now,
                 annotationObject: edge.annotationObject,
                 edgeRelationships: edge.edgeRelationships
             };
             vertex.edges.push(model);
         }
-        else if (!ArrayHelper.matches(existing.edgeRelationships, edge.edgeRelationships) ||
+        else if (existing.targetId !== edge.targetId ||
+            !ArrayHelper.matches(existing.edgeRelationships, edge.edgeRelationships) ||
             !ObjectHelper.equal(existing.annotationObject, edge.annotationObject, false)) {
-            // Existing resource found, update the annotationObject.
+            // Existing edge found, update the properties.
+            existing.targetId = edge.targetId;
             existing.dateModified = context.now;
             existing.edgeRelationships = edge.edgeRelationships;
             existing.annotationObject = edge.annotationObject;
@@ -1236,10 +1264,7 @@ class AuditableItemGraphService {
             };
             // Create the JSON-LD object we want to use for the proof
             // this is a subset of fixed properties from the changeset object.
-            const reducedChangesetJsonLd = await this.changesetEntityToJsonLd({
-                ...ObjectHelper.pick(changesetEntity, AuditableItemGraphService._PROOF_KEYS_CHANGESET),
-                id: `${AuditableItemGraphService._NAMESPACE}:${updated.id}:${AuditableItemGraphService.NAMESPACE_CHANGESET}:${changesetEntity.id}`
-            });
+            const reducedChangesetJsonLd = await this.changesetEntityToJsonLd(original.id, ObjectHelper.pick(changesetEntity, AuditableItemGraphService._PROOF_KEYS_CHANGESET));
             // Create the proof for the changeset object
             changesetEntity.proofId = await this._immutableProofComponent.create(reducedChangesetJsonLd, context.userIdentity, context.nodeIdentity);
             // Link the verifiable storage id to the changeset
@@ -1275,7 +1300,7 @@ class AuditableItemGraphService {
             if (Is.arrayValue(storedChangesets)) {
                 for (let i = 0; i < storedChangesets.length; i++) {
                     const storedChangeset = storedChangesets[i];
-                    const storedChangesetJsonLd = this.changesetEntityToJsonLd(storedChangeset);
+                    const storedChangesetJsonLd = this.changesetEntityToJsonLd(vertexId.namespaceSpecific(), storedChangeset);
                     changesets.push(storedChangesetJsonLd);
                     // If we are verifying all signatures
                     // or this is the last changeset (cursor is empty)
@@ -1343,10 +1368,72 @@ class AuditableItemGraphService {
         }
         const resourceTypeIndex = resourceTypes.join("||").toLowerCase();
         return {
-            aliasIndex: Is.stringValue(aliasIndex) ? aliasIndex : undefined,
-            resourceTypeIndex: Is.stringValue(resourceTypeIndex) ? resourceTypeIndex : undefined
+            aliasIndex: Is.stringValue(aliasIndex) ? `||${aliasIndex}||` : undefined,
+            resourceTypeIndex: Is.stringValue(resourceTypeIndex) ? `||${resourceTypeIndex}||` : undefined
         };
     }
+    /**
+     * Find vertices with matching aliases.
+     * @param vertexId The id of the vertex to exclude from the search.
+     * @param aliasId The alias id to try and find.
+     * @returns True if any other vertices have matching aliases.
+     * @internal
+     */
+    async findMatchingVertices(vertexId, aliasId) {
+        const results = await this._vertexStorage.query({
+            conditions: [
+                {
+                    property: "aliasIndex",
+                    comparison: ComparisonOperator.Includes,
+                    value: `||${aliasId.toLowerCase()}||`
+                },
+                {
+                    property: "id",
+                    value: vertexId,
+                    comparison: ComparisonOperator.NotEquals
+                }
+            ],
+            logicalOperator: LogicalOperator.And
+        });
+        return results.entities.length > 0;
+    }
+    /**
+     * Reduce the edge ID from a URN.
+     * @param urn The URN to reduce.
+     * @returns The edge ID.
+     * @throws GeneralError if the URN is not valid or not an edge URN.
+     * @internal
+     */
+    reduceEdgeId(urn) {
+        const urnParsed = Urn.fromValidString(urn);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(this.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id: urn
+            });
+        }
+        if (urnParsed.namespaceSpecificParts().length !== 3) {
+            throw new GeneralError(this.CLASS_NAME, "invalidEdgeId", { id: urn });
+        }
+        if (urnParsed.namespaceSpecificParts()[1] !== AuditableItemGraphService.NAMESPACE_EDGE) {
+            throw new GeneralError(this.CLASS_NAME, "invalidEdgeId", { id: urn });
+        }
+        return urnParsed.namespaceSpecificParts()[2];
+    }
+    /**
+     * Create a full edge ID URN from a vertex ID and edge ID.
+     * @param vertexId The vertex id the edge belongs to.
+     * @param edgeId The edge id.
+     * @returns The full edge ID URN.
+     * @internal
+     */
+    fullEdgeId(vertexId, edgeId) {
+        return new Urn(AuditableItemGraphService.NAMESPACE, [
+            vertexId,
+            AuditableItemGraphService.NAMESPACE_EDGE,
+            edgeId
+        ]).toString();
+    }
 }
 
 // Copyright 2024 IOTA Stiftung.
@@ -1489,6 +1576,10 @@ let AuditableItemGraphEdge = class AuditableItemGraphEdge {
      * The timestamp of when the edge was deleted, as we never actually remove items.
      */
     dateDeleted;
+    /**
+     * The target id of the edge.
+     */
+    targetId;
     /**
      * The relationships between the two vertices.
      */
@@ -1514,6 +1605,10 @@ __decorate([
     property({ type: "string", format: "date-time", optional: true }),
     __metadata("design:type", String)
 ], AuditableItemGraphEdge.prototype, "dateDeleted", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], AuditableItemGraphEdge.prototype, "targetId", void 0);
 __decorate([
     property({ type: "array" }),
     __metadata("design:type", Array)

package/dist/types/auditableItemGraphService.d.ts

@@ -10,6 +10,10 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
      * The namespace for the service changeset.
      */
     static readonly NAMESPACE_CHANGESET: string;
+    /**
+     * The namespace for the service edge.
+     */
+    static readonly NAMESPACE_EDGE: string;
     /**
      * Runtime name for the class.
      */
@@ -35,6 +39,7 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
         aliases?: {
             id: string;
             aliasFormat?: string;
+            unique?: boolean;
             annotationObject?: IJsonLdNodeObject;
         }[];
         resources?: {
@@ -42,7 +47,7 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
             resourceObject?: IJsonLdNodeObject;
         }[];
         edges?: {
-            id: string;
+            targetId: string;
             edgeRelationships: string[];
             annotationObject?: IJsonLdNodeObject;
         }[];
@@ -88,6 +93,7 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
         }[];
         edges?: {
             id: string;
+            targetId: string;
             edgeRelationships: string[];
             annotationObject?: IJsonLdNodeObject;
         }[];
@@ -105,6 +111,7 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
      * @param options The query options.
      * @param options.id The optional id to look for.
      * @param options.idMode Look in id, alias or both, defaults to both.
+     * @param options.idExact Find only exact matches, default to false meaning partial matching.
      * @param options.includesResourceTypes Include vertices with specific resource types.
      * @param conditions Conditions to use in the query.
      * @param orderBy The order for the results, defaults to created.
@@ -117,6 +124,7 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
     query(options?: {
         id?: string;
         idMode?: "id" | "alias" | "both";
+        idExact?: boolean;
         includesResourceTypes?: string[];
     }, conditions?: IComparator[], orderBy?: keyof Pick<IAuditableItemGraphVertex, "dateCreated" | "dateModified">, orderByDirection?: SortDirection, properties?: (keyof IAuditableItemGraphVertex)[], cursor?: string, pageSize?: number): Promise<IAuditableItemGraphVertexList>;
     /**

package/dist/types/entities/auditableItemGraphEdge.d.ts

@@ -19,6 +19,10 @@ export declare class AuditableItemGraphEdge {
      * The timestamp of when the edge was deleted, as we never actually remove items.
      */
     dateDeleted?: string;
+    /**
+     * The target id of the edge.
+     */
+    targetId: string;
     /**
      * The relationships between the two vertices.
      */

package/docs/changelog.md

@@ -1,5 +1,33 @@
 # @twin.org/auditable-item-graph-service - Changelog
 
+## [0.0.2-next.5](https://github.com/twinfoundation/auditable-item-graph/compare/auditable-item-graph-service-v0.0.2-next.4...auditable-item-graph-service-v0.0.2-next.5) (2025-09-26)
+
+
+### Features
+
+* update edges to use targetId instead of id ([6c5d0e3](https://github.com/twinfoundation/auditable-item-graph/commit/6c5d0e31b6e2ea74bfa2f3344e4be628e5f237af))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/auditable-item-graph-models bumped from 0.0.2-next.4 to 0.0.2-next.5
+
+## [0.0.2-next.4](https://github.com/twinfoundation/auditable-item-graph/compare/auditable-item-graph-service-v0.0.2-next.3...auditable-item-graph-service-v0.0.2-next.4) (2025-09-24)
+
+
+### Features
+
+* add unique flag for alias, and exact match option for id query ([33dbd19](https://github.com/twinfoundation/auditable-item-graph/commit/33dbd19cabd9fbfaba81032f1d1a6527584c3f5a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/auditable-item-graph-models bumped from 0.0.2-next.3 to 0.0.2-next.4
+
 ## [0.0.2-next.3](https://github.com/twinfoundation/auditable-item-graph/compare/auditable-item-graph-service-v0.0.2-next.2...auditable-item-graph-service-v0.0.2-next.3) (2025-08-29)
 
 

package/docs/open-api/spec.json

@@ -87,7 +87,7 @@
 										],
 										"edges": [
 											{
-												"id": "edge1",
+												"targetId": "aig:1234567890",
 												"edgeRelationships": [
 													"frenemy"
 												],
@@ -98,7 +98,7 @@
 												}
 											},
 											{
-												"id": "edge2",
+												"targetId": "aig:45678901234",
 												"edgeRelationships": [
 													"end"
 												],
@@ -216,6 +216,15 @@
 							]
 						}
 					},
+					{
+						"name": "idExact",
+						"description": "Find only exact matches, default to false meaning partial matching.",
+						"in": "query",
+						"required": false,
+						"schema": {
+							"type": "boolean"
+						}
+					},
 					{
 						"name": "resourceTypes",
 						"description": "Include vertices with specific resource types, comma separated.",
@@ -759,6 +768,7 @@
 										"edges": [
 											{
 												"id": "edge1",
+												"targetId": "aig:1234567890",
 												"edgeRelationships": [
 													"frenemy"
 												],
@@ -770,6 +780,7 @@
 											},
 											{
 												"id": "edge2",
+												"targetId": "aig:45678901234",
 												"edgeRelationships": [
 													"end"
 												],
@@ -873,6 +884,9 @@
 									"aliasFormat": {
 										"type": "string"
 									},
+									"unique": {
+										"type": "boolean"
+									},
 									"annotationObject": {
 										"$ref": "https://schema.twindev.org/json-ld/JsonLdNodeObject"
 									}
@@ -911,7 +925,7 @@
 							{
 								"type": "object",
 								"properties": {
-									"id": {
+									"targetId": {
 										"type": "string"
 									},
 									"edgeRelationships": {
@@ -925,7 +939,7 @@
 									}
 								},
 								"required": [
-									"id",
+									"targetId",
 									"edgeRelationships"
 								],
 								"additionalProperties": false
@@ -956,6 +970,9 @@
 									"aliasFormat": {
 										"type": "string"
 									},
+									"unique": {
+										"type": "boolean"
+									},
 									"annotationObject": {
 										"$ref": "https://schema.twindev.org/json-ld/JsonLdNodeObject"
 									}
@@ -997,6 +1014,9 @@
 									"id": {
 										"type": "string"
 									},
+									"targetId": {
+										"type": "string"
+									},
 									"edgeRelationships": {
 										"type": "array",
 										"items": {
@@ -1009,6 +1029,7 @@
 								},
 								"required": [
 									"id",
+									"targetId",
 									"edgeRelationships"
 								],
 								"additionalProperties": false

package/docs/reference/classes/AuditableItemGraphEdge.md

@@ -46,6 +46,14 @@ The timestamp of when the edge was deleted, as we never actually remove items.
 
 ***
 
+### targetId
+
+> **targetId**: `string`
+
+The target id of the edge.
+
+***
+
 ### edgeRelationships
 
 > **edgeRelationships**: `string`[]

package/docs/reference/classes/AuditableItemGraphService.md

@@ -36,6 +36,14 @@ The namespace for the service changeset.
 
 ***
 
+### NAMESPACE\_EDGE
+
+> `readonly` `static` **NAMESPACE\_EDGE**: `string` = `"edge"`
+
+The namespace for the service edge.
+
+***
+
 ### CLASS\_NAME
 
 > `readonly` **CLASS\_NAME**: `string`
@@ -286,6 +294,12 @@ The optional id to look for.
 
 Look in id, alias or both, defaults to both.
 
+###### idExact?
+
+`boolean`
+
+Find only exact matches, default to false meaning partial matching.
+
 ###### includesResourceTypes?
 
 `string`[]

package/locales/en.json

@@ -8,11 +8,13 @@
 			"queryingFailed": "Querying the Auditable Item Graph failed",
 			"removeVerifiableFailed": "Removing the verifiable data the Auditable Item Graph vertex failed",
 			"vertexNotFound": "The vertex with the Id \"{notFoundId}\" was not found",
-			"resourceIdMissing": "You must provide either the id, or the resourceObject must contain an id property for index \"{index}\""
+			"resourceIdMissing": "You must provide either the id, or the resourceObject must contain an id property for index \"{index}\"",
+			"aliasNotUnique": "The alias id \"{aliasId}\" is already in use on another vertex and the unique flag was set",
+			"invalidEdgeId": "The edge id \"{edgeId}\" is not valid"
 		},
 		"validation": {
 			"auditableItemGraphService": {
-				"edgeIdSameAsVertexId": "The edge id \"{id}\"can not point to the vertex it belongs to"
+				"edgeIdSameAsVertexId": "The edge with target id \"{targetId}\" can not point to the vertex it belongs to"
 			}
 		}
 	},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/auditable-item-graph-service",
-	"version": "0.0.2-next.3",
+	"version": "0.0.2-next.5",
 	"description": "Auditable Item Graph contract implementation and REST endpoint definitions",
 	"repository": {
 		"type": "git",
@@ -15,7 +15,7 @@
 	},
 	"dependencies": {
 		"@twin.org/api-models": "next",
-		"@twin.org/auditable-item-graph-models": "0.0.2-next.3",
+		"@twin.org/auditable-item-graph-models": "0.0.2-next.5",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
 		"@twin.org/data-json-ld": "next",