@twin.org/auditable-item-graph-service 0.0.3-next.13 → 0.0.3-next.14

package/dist/es/auditableItemGraphService.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0.
 import { AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
 import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
-import { ArrayHelper, ComponentFactory, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
+import { ArrayHelper, Coerce, ComponentFactory, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
 import { DataTypeHelper } from "@twin.org/data-core";
 import { JsonLdDataTypes, JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
 import { ComparisonOperator, LogicalOperator, SortDirection } from "@twin.org/entity";
@@ -124,7 +124,8 @@ export class AuditableItemGraphService {
             await this.updateEdgeList(context, vertexModel, vertex.edges);
             delete originalEntity.aliasIndex;
             delete originalEntity.resourceTypeIndex;
-            await this.addChangeset(context, originalEntity, vertexModel, true);
+            await this.addChangeset(context, originalEntity, vertexModel, true, 0);
+            vertexModel.version = 0;
             await this._vertexStorage.set({
                 ...vertexModel,
                 ...this.buildIndexes(vertexModel)
@@ -183,9 +184,13 @@ export class AuditableItemGraphService {
             await this.updateAliasList(context, newEntity, vertex.aliases);
             await this.updateResourceList(context, newEntity, vertex.resources);
             await this.updateEdgeList(context, newEntity, vertex.edges);
-            const patches = await this.addChangeset(context, originalEntity, newEntity, false);
+            const nextVersion = Is.empty(vertexEntity.version)
+                ? (await this.internalGetChangesets(vertexId)).length
+                : vertexEntity.version + 1;
+            const patches = await this.addChangeset(context, originalEntity, newEntity, false, nextVersion);
             if (patches.length > 0) {
                 newEntity.dateModified = context.now;
+                newEntity.version = nextVersion;
                 const indexes = this.buildIndexes(newEntity);
                 await this._vertexStorage.set({
                     ...newEntity,
@@ -348,6 +353,105 @@ export class AuditableItemGraphService {
             throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getFailed", undefined, error);
         }
     }
+    /**
+     * Get a graph vertex at a specific version.
+     * @param id The id of the vertex.
+     * @param versionId The id of the version (changeset id) to retrieve.
+     * @returns The vertex reconstructed at that version.
+     * @throws NotFoundError if the vertex or version is not found.
+     */
+    async getVersion(id, versionId) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "versionId", versionId);
+        const urnParsed = Urn.fromValidString(id);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id
+            });
+        }
+        try {
+            const vertexId = urnParsed.namespaceSpecific(0);
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const targetChangeset = await this._changesetStorage.get(versionId);
+            if (Is.empty(targetChangeset) || targetChangeset.vertexId !== vertexId) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "versionNotFound", versionId);
+            }
+            const changesets = await this.internalGetChangesets(vertexId, {
+                maxVersion: targetChangeset.version
+            });
+            let entityState = {
+                id: vertexEntity.id,
+                dateCreated: vertexEntity.dateCreated,
+                organizationIdentity: vertexEntity.organizationIdentity
+            };
+            for (const changeset of changesets) {
+                entityState = JsonHelper.patch(entityState, changeset.patches);
+            }
+            const vertexModel = this.vertexEntityToJsonLd(entityState);
+            vertexModel.version = targetChangeset.version;
+            const result = await JsonLdProcessor.compact(vertexModel, vertexModel["@context"]);
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getVersionFailed", undefined, error);
+        }
+    }
+    /**
+     * Get all versions of a graph vertex.
+     * @param id The id of the vertex.
+     * @param options Additional options for the operation.
+     * @param options.after Only return versions created after this ISO 8601 timestamp (exclusive).
+     * @param options.before Only return versions created before this ISO 8601 timestamp (exclusive).
+     * @returns The list of vertex versions.
+     * @throws NotFoundError if the vertex is not found.
+     */
+    async getVersions(id, options) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        const urnParsed = Urn.fromValidString(id);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id
+            });
+        }
+        try {
+            const vertexId = urnParsed.namespaceSpecific(0);
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const beforeDate = Coerce.dateTime(options?.before);
+            const afterDate = Coerce.dateTime(options?.after);
+            const allChangesets = await this.internalGetChangesets(vertexId, {
+                before: beforeDate?.toISOString()
+            });
+            const versions = [];
+            for (const changeset of allChangesets) {
+                const changesetDate = Coerce.dateTime(changeset.dateCreated);
+                const afterExcluded = !Is.empty(afterDate) && !Is.empty(changesetDate) && changesetDate <= afterDate;
+                if (!afterExcluded) {
+                    versions.push(changeset.version ?? 0);
+                }
+            }
+            const versionList = {
+                "@context": [
+                    SchemaOrgContexts.Context,
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon
+                ],
+                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexVersionList],
+                [SchemaOrgTypes.ItemListElement]: versions
+            };
+            return await JsonLdProcessor.compact(versionList, versionList["@context"]);
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getVersionsFailed", undefined, error);
+        }
+    }
     /**
      * Remove the verifiable storage for an item.
      * @param id The id of the vertex to get.
@@ -599,10 +703,47 @@ export class AuditableItemGraphService {
                 patchFrom: p.from,
                 patchValue: p.value
             })),
-            proofId: changesetEntity.proofId
+            proofId: changesetEntity.proofId,
+            version: changesetEntity.version
         };
         return model;
     }
+    /**
+     * Fetch all changesets for a vertex in ascending date order.
+     * @param vertexId The internal vertex id.
+     * @param options Optional filtering options.
+     * @param options.before Only fetch changesets created strictly before this ISO 8601 timestamp.
+     * @param options.maxVersion Only fetch changesets with version <= this value.
+     * @returns All changeset entities sorted ascending by dateCreated.
+     * @internal
+     */
+    async internalGetChangesets(vertexId, options) {
+        const all = [];
+        let cursor;
+        const conditions = [
+            { property: "vertexId", value: vertexId, comparison: ComparisonOperator.Equals }
+        ];
+        if (Is.stringValue(options?.before)) {
+            conditions.push({
+                property: "dateCreated",
+                value: options.before,
+                comparison: ComparisonOperator.LessThan
+            });
+        }
+        if (!Is.empty(options?.maxVersion)) {
+            conditions.push({
+                property: "version",
+                value: options.maxVersion,
+                comparison: ComparisonOperator.LessThanOrEqual
+            });
+        }
+        do {
+            const result = await this._changesetStorage.query({ conditions, logicalOperator: LogicalOperator.And }, [{ property: "dateCreated", sortDirection: SortDirection.Ascending }], undefined, cursor);
+            all.push(...result.entities);
+            cursor = result.cursor;
+        } while (Is.stringValue(cursor));
+        return all;
+    }
     /**
      * Update the aliases of a vertex model.
      * @param context The context for the operation.
@@ -820,10 +961,11 @@ export class AuditableItemGraphService {
      * @param original The original vertex.
      * @param updated The updated vertex.
      * @param isNew Whether this is a new item.
+     * @param version The version number of the vertex after this changeset.
      * @returns True if there were changes.
      * @internal
      */
-    async addChangeset(context, original, updated, isNew) {
+    async addChangeset(context, original, updated, isNew, version) {
         const patches = JsonHelper.diff(original, updated);
         // If there is a diff set or this is the first time the item is created.
         if (patches.length > 0 || isNew) {
@@ -832,13 +974,14 @@ export class AuditableItemGraphService {
                 vertexId: updated.id,
                 dateCreated: context.now,
                 userIdentity: context.contextIds?.[ContextIdKeys.User],
-                patches
+                patches,
+                version
             };
             // 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 = 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);
+            changesetEntity.proofId = await this._immutableProofComponent.create(JsonLdHelper.toNodeObject(reducedChangesetJsonLd));
             // Link the verifiable storage id to the changeset
             await this._changesetStorage.set(changesetEntity);
             return patches;