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

package/docs/reference/classes/AuditableItemGraphService.md

@@ -0,0 +1,539 @@
+# Class: AuditableItemGraphService
+
+Class for performing auditable item graph operations.
+
+## Implements
+
+- `IAuditableItemGraphComponent`
+- `IHealthProviderComponent`
+
+## Constructors
+
+### Constructor
+
+> **new AuditableItemGraphService**(`options?`): `AuditableItemGraphService`
+
+Create a new instance of AuditableItemGraphService.
+
+#### Parameters
+
+##### options?
+
+[`IAuditableItemGraphServiceConstructorOptions`](../interfaces/IAuditableItemGraphServiceConstructorOptions.md)
+
+The dependencies for the auditable item graph connector.
+
+#### Returns
+
+`AuditableItemGraphService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+***
+
+### NAMESPACE\_CHANGESET {#namespace_changeset}
+
+> `readonly` `static` **NAMESPACE\_CHANGESET**: `string` = `"changeset"`
+
+The namespace for the service changeset.
+
+***
+
+### NAMESPACE\_EDGE {#namespace_edge}
+
+> `readonly` `static` **NAMESPACE\_EDGE**: `string` = `"edge"`
+
+The namespace for the service edge.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.className`
+
+***
+
+### healthApplication() {#healthapplication}
+
+> **healthApplication**(`callback`): `Promise`\<`IHealth`[] \| `undefined`\>
+
+Runs a set/get/remove cycle against the vertex entity storage using the organisation identity
+from the current context.
+
+#### Parameters
+
+##### callback
+
+`HealthApplicationCallback`
+
+The callback to invoke when a deferred health result is ready.
+
+#### Returns
+
+`Promise`\<`IHealth`[] \| `undefined`\>
+
+The health status of the service.
+
+#### Implementation of
+
+`IHealthProviderComponent.healthApplication`
+
+***
+
+### start() {#start}
+
+> **start**(): `Promise`\<`void`\>
+
+Register all AIG metrics with the telemetry component.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when all metrics have been registered.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.start`
+
+***
+
+### create() {#create}
+
+> **create**(`vertex`): `Promise`\<`string`\>
+
+Create a new graph vertex.
+
+#### Parameters
+
+##### vertex
+
+`Omit`\<`IAuditableItemGraphVertex`, `"id"`\>
+
+The vertex to create.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The id of the new graph item.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.create`
+
+***
+
+### update() {#update}
+
+> **update**(`vertex`): `Promise`\<`void`\>
+
+Update a graph vertex (PUT - full replacement of vertex state).
+Concurrent updates for the same vertex are serialized via `Mutex` on the vertex id.
+
+#### Parameters
+
+##### vertex
+
+`IAuditableItemGraphVertex`
+
+The vertex to update.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the vertex has been updated.
+
+#### Throws
+
+GeneralError If a bypass vertex is being switched back to audited.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.update`
+
+***
+
+### updatePartial() {#updatepartial}
+
+> **updatePartial**(`partial`): `Promise`\<`void`\>
+
+Partially update a graph vertex (PATCH - explicit list patches; only defined properties applied).
+Serialized with `update` via `Mutex` on the same vertex id within this instance.
+
+#### Parameters
+
+##### partial
+
+`IAuditableItemGraphPartialVertex`
+
+The partial vertex update.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the partial update has been applied.
+
+#### Throws
+
+GeneralError If a bypass vertex is being switched back to audited.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.updatePartial`
+
+***
+
+### get() {#get}
+
+> **get**(`id`, `options?`): `Promise`\<`IAuditableItemGraphVertex`\>
+
+Get a graph vertex.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex to get.
+
+##### options?
+
+Additional options for the get operation.
+
+###### includeDeleted?
+
+`boolean`
+
+Whether to include deleted/updated aliases, resource, edges, defaults to false.
+
+###### verifySignatureDepth?
+
+`VerifyDepth`
+
+How many signatures to verify, defaults to "none".
+
+#### Returns
+
+`Promise`\<`IAuditableItemGraphVertex`\>
+
+The vertex if found.
+
+#### Throws
+
+NotFoundError if the vertex is not found.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.get`
+
+***
+
+### getChangesets() {#getchangesets}
+
+> **getChangesets**(`id`, `cursor?`, `limit?`, `options?`): `Promise`\<\{ `changesets`: `IAuditableItemGraphChangesetList`; `cursor?`: `string`; \}\>
+
+Get a graph vertex changeset list.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex to get.
+
+##### cursor?
+
+`string`
+
+The optional cursor to get next chunk.
+
+##### limit?
+
+`number`
+
+Limit the number of entities to return.
+
+##### options?
+
+Additional options for the get operation.
+
+###### verifySignatureDepth?
+
+`VerifyDepth`
+
+How many signatures to verify, defaults to "none".
+
+#### Returns
+
+`Promise`\<\{ `changesets`: `IAuditableItemGraphChangesetList`; `cursor?`: `string`; \}\>
+
+The vertex if found.
+
+#### Throws
+
+NotFoundError if the vertex is not found.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.getChangesets`
+
+***
+
+### getChangeset() {#getchangeset}
+
+> **getChangeset**(`id`, `options?`): `Promise`\<`IAuditableItemGraphChangeset`\>
+
+Get a graph vertex changeset.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex to get.
+
+##### options?
+
+Additional options for the get operation.
+
+###### verifySignatureDepth?
+
+`VerifyDepth`
+
+How many signatures to verify, defaults to "none".
+
+#### Returns
+
+`Promise`\<`IAuditableItemGraphChangeset`\>
+
+The vertex if found.
+
+#### Throws
+
+NotFoundError if the vertex is not found.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.getChangeset`
+
+***
+
+### getVersion() {#getversion}
+
+> **getVersion**(`id`, `version`): `Promise`\<`IAuditableItemGraphVertex`\>
+
+Get a graph vertex at a specific version.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex.
+
+##### version
+
+`number`
+
+The version number to retrieve.
+
+#### Returns
+
+`Promise`\<`IAuditableItemGraphVertex`\>
+
+The vertex reconstructed at that version.
+
+#### Throws
+
+NotFoundError if the vertex or version is not found, a bypass vertex never has versions.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.getVersion`
+
+***
+
+### getVersions() {#getversions}
+
+> **getVersions**(`id`, `options?`): `Promise`\<`IAuditableItemGraphVertexVersionList`\>
+
+Get all versions of a graph vertex.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex.
+
+##### options?
+
+Additional options for the operation.
+
+###### after?
+
+`string`
+
+Only return versions created after this ISO 8601 timestamp (exclusive).
+
+###### before?
+
+`string`
+
+Only return versions created before this ISO 8601 timestamp (exclusive).
+
+#### Returns
+
+`Promise`\<`IAuditableItemGraphVertexVersionList`\>
+
+The list of vertex versions, a bypass vertex returns a single baseline entry for its
+current state when that falls within the requested range.
+
+#### Throws
+
+NotFoundError if the vertex is not found.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.getVersions`
+
+***
+
+### removeProof() {#removeproof}
+
+> **removeProof**(`id`): `Promise`\<`void`\>
+
+Remove the proof for an item.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex to remove the proof from.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the proof has been removed from all changesets.
+
+#### Throws
+
+NotFoundError if the vertex is not found.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.removeProof`
+
+***
+
+### query() {#query}
+
+> **query**(`options?`, `conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuditableItemGraphVertexList`; `cursor?`: `string`; \}\>
+
+Query the graph for vertices.
+
+#### Parameters
+
+##### options?
+
+The query options.
+
+###### id?
+
+`string`
+
+The optional id to look for.
+
+###### idMode?
+
+`"id"` \| `"alias"` \| `"both"`
+
+Look in id, alias or both, defaults to both.
+
+###### idExact?
+
+`boolean`
+
+Find only exact matches, default to false meaning partial matching.
+
+###### resourceTypes?
+
+`string`[]
+
+Include vertices with specific resource types.
+
+##### conditions?
+
+`EntityCondition`\<`IAuditableItemGraphVertex`\>
+
+Conditions to use in the query.
+
+##### orderBy?
+
+`"dateCreated"` \| `"dateModified"`
+
+The order for the results, defaults to created.
+
+##### orderByDirection?
+
+`SortDirection`
+
+The direction for the order, defaults to desc.
+
+##### properties?
+
+keyof `IAuditableItemGraphVertex`[]
+
+The properties to return, if not provided defaults to id, created, aliases and object.
+
+##### cursor?
+
+`string`
+
+The cursor to request the next chunk of entities.
+
+##### limit?
+
+`number`
+
+The maximum number of entities to return, a page can contain fewer so follow
+the cursor until it is absent to read them all.
+
+#### Returns
+
+`Promise`\<\{ `entries`: `IAuditableItemGraphVertexList`; `cursor?`: `string`; \}\>
+
+The entities, which can be partial if a limited keys list was provided.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.query`

package/docs/reference/classes/AuditableItemGraphVertex.md

@@ -0,0 +1,93 @@
+# Class: AuditableItemGraphVertex
+
+Class describing the auditable item graph vertex.
+
+## Constructors
+
+### Constructor
+
+> **new AuditableItemGraphVertex**(): `AuditableItemGraphVertex`
+
+#### Returns
+
+`AuditableItemGraphVertex`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The id of the vertex.
+
+***
+
+### organizationIdentity {#organizationidentity}
+
+> **organizationIdentity**: `string`
+
+The identity of the organization which controls the vertex.
+
+***
+
+### dateCreated {#datecreated}
+
+> **dateCreated**: `string`
+
+The date/time of when the vertex was created.
+
+***
+
+### dateModified? {#datemodified}
+
+> `optional` **dateModified?**: `string`
+
+The date/time of when the vertex was last modified.
+
+***
+
+### auditMode? {#auditmode}
+
+> `optional` **auditMode?**: `AuditableItemGraphAuditMode`
+
+How the mutations of the vertex are recorded, when absent the vertex behaves as audited.
+
+***
+
+### annotationObject? {#annotationobject}
+
+> `optional` **annotationObject?**: `IJsonLdNodeObject`
+
+Object to associate with the vertex as JSON-LD.
+
+***
+
+### aliases? {#aliases}
+
+> `optional` **aliases?**: [`AuditableItemGraphAlias`](AuditableItemGraphAlias.md)[]
+
+Alternative aliases that can be used to identify the vertex.
+
+***
+
+### resources? {#resources}
+
+> `optional` **resources?**: [`AuditableItemGraphResource`](AuditableItemGraphResource.md)[]
+
+The resources attached to the vertex.
+
+***
+
+### edges? {#edges}
+
+> `optional` **edges?**: [`AuditableItemGraphEdge`](AuditableItemGraphEdge.md)[]
+
+Edges connected to the vertex.
+
+***
+
+### version? {#version}
+
+> `optional` **version?**: `number`
+
+The current version of the vertex, incremented on each changeset.

package/docs/reference/classes/AuditableItemGraphVertexIndex.md

@@ -0,0 +1,75 @@
+# Class: AuditableItemGraphVertexIndex
+
+Class describing the auditable item graph vertex index.
+
+The composite index is built on a fixed length hash of the value rather than the value itself,
+so its key stays within the size limit some databases place on an index key however long the
+value is.
+
+## Constructors
+
+### Constructor
+
+> **new AuditableItemGraphVertexIndex**(): `AuditableItemGraphVertexIndex`
+
+#### Returns
+
+`AuditableItemGraphVertexIndex`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The id of the index.
+
+***
+
+### vertexId {#vertexid}
+
+> **vertexId**: `string`
+
+The id of the vertex this index refers to.
+
+***
+
+### type {#type}
+
+> **type**: `string`
+
+Index type.
+
+***
+
+### value {#value}
+
+> **value**: `string`
+
+Index value, case folded so lookups do not depend on the column collation.
+
+***
+
+### valueHash {#valuehash}
+
+> **valueHash**: `string`
+
+The hash of the value, used for exact lookups.
+
+***
+
+### dateCreated {#datecreated}
+
+> **dateCreated**: `string`
+
+The date/time of when the vertex was created, copied so the index can order and page its
+own matches without reading the vertex.
+
+***
+
+### dateModified? {#datemodified}
+
+> `optional` **dateModified?**: `string`
+
+The date/time of when the vertex was last modified, copied so a query ordered by the
+modified date can also be paged from the index.