@3sixty/auditable-item-graph-service 0.0.0-stage → 0.20.0-next.0

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

@@ -0,0 +1,58 @@
+import type { AuditableItemGraphAuditMode } from "@3sixty/auditable-item-graph-models";
+import { type IJsonLdNodeObject } from "@3sixty/data-json-ld";
+import type { AuditableItemGraphAlias } from "./auditableItemGraphAlias.js";
+import type { AuditableItemGraphEdge } from "./auditableItemGraphEdge.js";
+import type { AuditableItemGraphResource } from "./auditableItemGraphResource.js";
+/**
+ * Class describing the auditable item graph vertex.
+ */
+export declare class AuditableItemGraphVertexV1 {
+    /**
+     * The id of the vertex.
+     */
+    id: string;
+    /**
+     * The identity of the organization which controls the vertex.
+     */
+    organizationIdentity: string;
+    /**
+     * The date/time of when the vertex was created.
+     */
+    dateCreated: string;
+    /**
+     * The date/time of when the vertex was last modified.
+     */
+    dateModified?: string;
+    /**
+     * How the mutations of the vertex are recorded, when absent the vertex behaves as audited.
+     */
+    auditMode?: AuditableItemGraphAuditMode;
+    /**
+     * Combined alias index for the vertex used for querying.
+     */
+    aliasIndex?: string;
+    /**
+     * Combined resource type index for the vertex used for querying.
+     */
+    resourceTypeIndex?: string;
+    /**
+     * Object to associate with the vertex as JSON-LD.
+     */
+    annotationObject?: IJsonLdNodeObject;
+    /**
+     * Alternative aliases that can be used to identify the vertex.
+     */
+    aliases?: AuditableItemGraphAlias[];
+    /**
+     * The resources attached to the vertex.
+     */
+    resources?: AuditableItemGraphResource[];
+    /**
+     * Edges connected to the vertex.
+     */
+    edges?: AuditableItemGraphEdge[];
+    /**
+     * The current version of the vertex, incremented on each changeset.
+     */
+    version?: number;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./auditableItemGraphRoutes.js";
+export * from "./auditableItemGraphService.js";
+export * from "./entities/auditableItemGraphAlias.js";
+export * from "./entities/auditableItemGraphChangeset.js";
+export * from "./entities/auditableItemGraphEdge.js";
+export * from "./entities/auditableItemGraphPatch.js";
+export * from "./entities/auditableItemGraphResource.js";
+export * from "./entities/auditableItemGraphVertex.js";
+export * from "./entities/auditableItemGraphVertexIndex.js";
+export * from "./entities/auditableItemGraphVertexV0.js";
+export * from "./entities/auditableItemGraphVertexV1.js";
+export * from "./models/IAuditableItemGraphServiceConfig.js";
+export * from "./models/IAuditableItemGraphServiceConstructorOptions.js";
+export * from "./restEntryPoints.js";
+export * from "./schema.js";
+export * from "./utils/auditableItemGraphVertexIndexHelper.js";

package/dist/types/models/IAuditableItemGraphServiceConfig.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configuration for the auditable item graph service.
+ */
+export interface IAuditableItemGraphServiceConfig {
+    /**
+     * Timeout in milliseconds for acquiring a mutex lock.
+     */
+    mutexTimeoutMs?: number;
+}

package/dist/types/models/IAuditableItemGraphServiceConstructorOptions.d.ts

@@ -0,0 +1,38 @@
+import type { IAuditableItemGraphServiceConfig } from "./IAuditableItemGraphServiceConfig.js";
+/**
+ * Options for the constructor of the auditable item graph service.
+ */
+export interface IAuditableItemGraphServiceConstructorOptions {
+    /**
+     * The immutable proof component type.
+     * @default immutable-proof
+     */
+    immutableProofComponentType?: string;
+    /**
+     * The entity storage for vertices.
+     * @default auditable-item-graph-vertex
+     */
+    vertexEntityStorageType?: string;
+    /**
+     * The entity storage for vertex indices.
+     * @default auditable-item-graph-vertex-index
+     */
+    vertexIndexEntityStorageType?: string;
+    /**
+     * The entity storage for changesets.
+     * @default auditable-item-graph-changeset
+     */
+    changesetEntityStorageType?: string;
+    /**
+     * The event bus component type, defaults to no event bus.
+     */
+    eventBusComponentType?: string;
+    /**
+     * The component type for the optional telemetry component used for event metrics, defaults to no telemetry.
+     */
+    telemetryComponentType?: string;
+    /**
+     * The configuration for the service.
+     */
+    config?: IAuditableItemGraphServiceConfig;
+}

package/dist/types/models/IAuditableItemGraphServiceContext.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Context for the auditable item graph service.
+ */
+export interface IAuditableItemGraphServiceContext {
+    /**
+     * The current date/time.
+     */
+    now: string;
+    /**
+     * The organization identity for the operation.
+     */
+    organizationIdentity: string;
+    /**
+     * The user identity for the operation.
+     */
+    userIdentity?: string;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@3sixty/api-models";
+/**
+ * The REST entry points for the auditable item graph service.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/schema.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Initialize the schema for the auditable item graph entity storage connector.
+ */
+export declare function initSchema(): void;

package/dist/types/utils/auditableItemGraphVertexIndexHelper.d.ts

@@ -0,0 +1,25 @@
+import type { AuditableItemGraphVertexIndex } from "../entities/auditableItemGraphVertexIndex.js";
+/**
+ * Helper methods for building auditable item graph vertex index entries.
+ */
+export declare class AuditableItemGraphVertexIndexHelper {
+    /**
+     * Create the index entry for one type and value of a vertex. The value is case folded and
+     * hashed, and the id is derived from the content so the same entry always produces the same id.
+     * The modification date is excluded from the id as it is optional and changes over time.
+     * @param vertexId The id of the vertex the entry refers to.
+     * @param type The index type.
+     * @param value The index value.
+     * @param dateCreated The creation date of the vertex.
+     * @param dateModified The modification date of the vertex.
+     * @returns The index entry.
+     */
+    static createIndexEntry(vertexId: string, type: string, value: string, dateCreated: string, dateModified?: string): AuditableItemGraphVertexIndex;
+    /**
+     * Hash an index value so the composite index key has a fixed size whatever the value length.
+     * The value is case folded first so lookups are case insensitive.
+     * @param value The value to hash.
+     * @returns The base64 url encoded Blake2b-160 hash, or undefined when there is no value.
+     */
+    static hashValue(value?: string): string | undefined;
+}

package/docs/examples.md

@@ -0,0 +1,273 @@
+# Auditable Item Graph Service Examples
+
+Use these examples when you want to run graph operations in process, keep an audit trail, and work with strongly typed entities.
+
+## AuditableItemGraphService
+
+```typescript
+import { AuditableItemGraphService } from '@3sixty/auditable-item-graph-service';
+
+const service = new AuditableItemGraphService();
+
+console.log(service.className()); // AuditableItemGraphService
+```
+
+```typescript
+import { AuditableItemGraphService } from '@3sixty/auditable-item-graph-service';
+
+const service = new AuditableItemGraphService();
+
+const vertexId = await service.create({
+  annotationObject: {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    type: 'Create',
+    actor: {
+      type: 'Person',
+      id: 'did:example:alice',
+      name: 'Alice'
+    },
+    object: {
+      type: 'Note',
+      content: 'Initial version'
+    }
+  },
+  aliases: [{ id: 'order-2026-0195', aliasFormat: 'orderRef' }],
+  resources: [
+    { resourceObject: { '@context': 'https://schema.org', type: 'Thing', name: 'Order 2026-0195' } }
+  ]
+});
+
+await service.update({
+  id: vertexId,
+  aliases: [{ id: 'order-2026-0195', aliasFormat: 'orderRef' }],
+  resources: [
+    {
+      id: 'resource-order',
+      resourceObject: {
+        '@context': 'https://schema.org',
+        type: 'Thing',
+        name: 'Order 2026-0195 (amended)'
+      }
+    }
+  ],
+  edges: [{ targetId: 'aig:018f5a6cfd9444d58c7c2d4df1fd0fff', edgeRelationships: ['derivedFrom'] }]
+});
+
+console.log(vertexId); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23
+```
+
+```typescript
+import { VerifyDepth } from '@3sixty/auditable-item-graph-models';
+import { AuditableItemGraphService } from '@3sixty/auditable-item-graph-service';
+
+const service = new AuditableItemGraphService();
+const vertexId = 'aig:018f5a6cfd9444d58c7c2d4df1fd0a23';
+
+const vertex = await service.get(vertexId, {
+  includeDeleted: false,
+  verifySignatureDepth: VerifyDepth.Current
+});
+
+const changesetChunk = await service.getChangesets(vertexId, undefined, 10, {
+  verifySignatureDepth: VerifyDepth.Current
+});
+
+const firstChangeset = changesetChunk.changesets.itemListElement?.[0];
+
+if (firstChangeset?.id) {
+  const changeset = await service.getChangeset(firstChangeset.id, {
+    verifySignatureDepth: VerifyDepth.Current
+  });
+
+  console.log(vertex.id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23
+  console.log(changeset.id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23:changeset:018f5a6cfd9444d58c7c2d4df1fd0b10
+}
+```
+
+```typescript
+import { ComparisonOperator, SortDirection } from '@3sixty/entity';
+import { AuditableItemGraphService } from '@3sixty/auditable-item-graph-service';
+
+const service = new AuditableItemGraphService();
+
+const queryResult = await service.query(
+  {
+    id: 'order-2026',
+    idMode: 'alias',
+    idExact: false,
+    resourceTypes: ['Thing']
+  },
+  [
+    {
+      field: 'dateCreated',
+      comparison: ComparisonOperator.GreaterThan,
+      value: '2026-01-01T00:00:00.000Z'
+    }
+  ],
+  'dateCreated',
+  SortDirection.Descending,
+  ['id', 'dateCreated', 'aliases'],
+  undefined,
+  25
+);
+
+console.log(queryResult.entries.itemListElement?.length ?? 0); // 3
+
+await service.removeVerifiable('aig:018f5a6cfd9444d58c7c2d4df1fd0a23');
+```
+
+Vertices which only need their current state can opt out of versioning with `auditMode`. Bypass is a
+terminal mode; switching an audited vertex to bypass compacts its history and removes the associated
+proofs, and a bypass vertex can never return to audited.
+
+```typescript
+import { AuditableItemGraphAuditMode } from '@3sixty/auditable-item-graph-models';
+import { AuditableItemGraphService } from '@3sixty/auditable-item-graph-service';
+
+const service = new AuditableItemGraphService();
+
+const lookupId = await service.create({
+  auditMode: AuditableItemGraphAuditMode.Bypass,
+  aliases: [{ id: 'currency-rates', aliasFormat: 'lookupRef' }]
+});
+
+// Overwrites the stored state in place, no changeset is written.
+await service.updatePartial({
+  id: lookupId,
+  annotationObject: { '@context': 'https://schema.org', type: 'Thing', name: 'Rates 2026-03-10' }
+});
+
+const changesets = await service.getChangesets(lookupId);
+
+console.log(changesets.changesets.itemListElement?.length ?? 0); // 0
+
+// Archive an existing audited vertex by compacting it to its current state.
+await service.updatePartial({
+  id: 'aig:018f5a6cfd9444d58c7c2d4df1fd0a23',
+  auditMode: AuditableItemGraphAuditMode.Bypass
+});
+```
+
+## AuditableItemGraphVertex
+
+```typescript
+import {
+  AuditableItemGraphAlias,
+  AuditableItemGraphEdge,
+  AuditableItemGraphResource,
+  AuditableItemGraphVertex
+} from '@3sixty/auditable-item-graph-service';
+
+const alias = new AuditableItemGraphAlias();
+alias.id = 'order-2026-0195';
+alias.aliasFormat = 'orderRef';
+alias.dateCreated = '2026-03-10T09:30:00.000Z';
+
+const resource = new AuditableItemGraphResource();
+resource.id = 'resource-order';
+resource.dateCreated = '2026-03-10T09:30:00.000Z';
+resource.resourceObject = {
+  '@context': 'https://schema.org',
+  type: 'Thing',
+  name: 'Order 2026-0195'
+};
+
+const edge = new AuditableItemGraphEdge();
+edge.id = 'edge-1';
+edge.dateCreated = '2026-03-10T09:30:00.000Z';
+edge.targetId = 'aig:018f5a6cfd9444d58c7c2d4df1fd0fff';
+edge.edgeRelationships = ['derivedFrom'];
+
+const vertex = new AuditableItemGraphVertex();
+vertex.id = '018f5a6cfd9444d58c7c2d4df1fd0a23';
+vertex.organizationIdentity = 'did:web:example.org';
+vertex.dateCreated = '2026-03-10T09:30:00.000Z';
+vertex.aliases = [alias];
+vertex.resources = [resource];
+vertex.edges = [edge];
+
+console.log(vertex.aliases?.length ?? 0); // 1
+```
+
+## AuditableItemGraphChangeset
+
+```typescript
+import {
+  AuditableItemGraphChangeset,
+  AuditableItemGraphPatch
+} from '@3sixty/auditable-item-graph-service';
+
+const patch = new AuditableItemGraphPatch();
+patch.op = 'replace';
+patch.path = '/resources/0/resourceObject/name';
+patch.value = 'Order 2026-0195 (amended)';
+
+const changeset = new AuditableItemGraphChangeset();
+changeset.id = '018f5a6cfd9444d58c7c2d4df1fd0b10';
+changeset.vertexId = '018f5a6cfd9444d58c7c2d4df1fd0a23';
+changeset.dateCreated = '2026-03-10T09:40:00.000Z';
+changeset.userIdentity = 'did:web:example.org:users:alice';
+changeset.patches = [patch];
+
+console.log(changeset.patches.length); // 1
+```
+
+## AuditableItemGraphAlias
+
+```typescript
+import { AuditableItemGraphAlias } from '@3sixty/auditable-item-graph-service';
+
+const alias = new AuditableItemGraphAlias();
+alias.id = 'order-2026-0195';
+alias.aliasFormat = 'orderRef';
+alias.dateCreated = '2026-03-10T09:30:00.000Z';
+
+console.log(alias.id); // order-2026-0195
+```
+
+## AuditableItemGraphResource
+
+```typescript
+import { AuditableItemGraphResource } from '@3sixty/auditable-item-graph-service';
+
+const resource = new AuditableItemGraphResource();
+resource.id = 'resource-order';
+resource.dateCreated = '2026-03-10T09:30:00.000Z';
+resource.resourceObject = {
+  '@context': 'https://schema.org',
+  type: 'Thing',
+  name: 'Order 2026-0195'
+};
+
+console.log(resource.id); // resource-order
+```
+
+## AuditableItemGraphEdge
+
+```typescript
+import { AuditableItemGraphEdge } from '@3sixty/auditable-item-graph-service';
+
+const edge = new AuditableItemGraphEdge();
+edge.id = 'edge-1';
+edge.dateCreated = '2026-03-10T09:30:00.000Z';
+edge.targetId = 'aig:018f5a6cfd9444d58c7c2d4df1fd0fff';
+edge.edgeRelationships = ['derivedFrom'];
+
+console.log(edge.edgeRelationships[0]); // derivedFrom
+```
+
+## AuditableItemGraphPatch
+
+```typescript
+import { AuditableItemGraphPatch } from '@3sixty/auditable-item-graph-service';
+
+const patch = new AuditableItemGraphPatch();
+patch.op = 'add';
+patch.path = '/aliases/-';
+patch.value = {
+  id: 'order-2026-0195',
+  aliasFormat: 'orderRef'
+};
+
+console.log(patch.op); // add
+```