@semiont/event-sourcing

What a reader of a knowledge base's record needs: the materialized view of a resource, and the id an annotation is recorded under.

The record itself is the Archivist's. It appends every change to an event log in the knowledge base's working tree and materializes a view of each resource's current state. This package reads those views; it writes nothing.

Who uses it

• The Librarian, in @semiont/make-meaning, reads views with FilesystemViewStorage from the state tree the Archivist writes.
• @semiont/jobs uses annotationIdFor, so that the same annotation made twice has one id.

Building an application? You do not need this package. An application reads a resource through @semiont/sdk (browse.resource, browse.events), and writes by using the verbs.

What is in it

| | | |---|---| | FilesystemViewStorage | Reads a resource's view from <resourcesDir>/<ab>/<cd>/<resourceId>.json | | ViewStorage | The read it implements: get(resourceId) | | ResourceView | A view: the resource's descriptor, its annotations, and the sequence of the last event applied. The spec's ResourceView | | annotationIdFor, AnnotationIdentity | An annotation's id, from what makes it that annotation |

Example

import { FilesystemViewStorage, annotationIdFor } from '@semiont/event-sourcing';
import { SemiontState } from '@semiont/core/node';
import { resourceId } from '@semiont/core';

const state = new SemiontState({ name: 'my-knowledge-base' });
const views = new FilesystemViewStorage(state);

const view = await views.get(resourceId('doc-123'));
if (view) {
  console.log(view.resource.name, view.annotations.annotations.length, view.lastSequence);
}

const id = annotationIdFor({
  resourceId: 'doc-123',
  motivation: 'highlighting',
  anchor: '0:5:Hello',
});

What a change must keep

• It only reads. The Archivist is the one writer of the views. It renames whole files into place, so a reader sees a whole view or none.
• A missing view is null. So is a file that does not parse, which is logged. Anything else throws.
• An id becomes a file name only after it is checked. get refuses a string that is not a ResourceId, so .. never reaches the path.
• The view's shape is the spec's. ResourceView is generated from the schema the Archivist writes to, in @semiont/core.
• An annotation's id is its content. annotationIdFor hashes the resource, the motivation, the anchor and the body. Nothing about when or by whom it was emitted is an input, so emitting it again gives the same id.

Documentation

• API reference: reading a view, and annotation ids.
• The Archivist: where each file of the record is, and how each event changes the views.

License

Apache-2.0