Attachments¶

An attachment connects values to documents via keys. It is the fundamental mechanism for associating typed data with document instances: each attachment is, in effect, a typed map from a key to a document.

An attachment is declared on a pair of types — a concept (or club, or ANY_CONCEPT) and a value type:

const att = defs.createAttachment(ns, 'A_I', conceptType, Type.INT64);

Keys are minted from the attachment and projected to match how the value is filed: att.createKey().toParentKey() for the parent concept, .toClubKey(club) for a club membership, and .toAnyConceptKey() for an ANY_CONCEPT attachment.

When to use: reach for an attachment whenever you need to store and retrieve values keyed by document. AttachmentGetting provides read access (keys, get, has); AttachmentMutating extends it with write operations (set, update, and the collection-field ops unionInSet / subtractInSet, unionInMap / subtractInMap, insertInXarray / updateInXarray / removeInXarray).

Quick Start¶

const {
    CommitDatabase, CommitStateBuilder, CommitMutableState, Type,
} = require('@digitalsubstrate/dsviper');

const db = CommitDatabase.createInMemory();
db.extendDefinitions(defs.const());

// Write via AttachmentMutating
const mutableState = new CommitMutableState(CommitStateBuilder.initialState(db));
const mutating = mutableState.attachmentMutating();
mutating.set(att, key, 42);                 // INT64 document
db.commitMutations('Set A_I', mutableState);

// Read via AttachmentGetting, off the last commit
const state = CommitStateBuilder.state(db, db.lastCommitId());
const getting = state.attachmentGetting();

for (const k of getting.keys(att)) {        // keys(att) is iterable
    const doc = getting.get(att, k);        // ValueOptional
    console.log(doc.unwrap());              // INT64 unwraps to a bigint (42n)
}

db.close();

For a structured value type, build the document from the attachment itself:

const att_s = defs.createAttachment(ns, 'ac_S', Type.ANY_CONCEPT, structType);
mutating.set(att_s, key.toAnyConceptKey(), att_s.createStructure({ f_i: 42, f_s: 'a string' }));

Operations on a closed CommitDatabase, or a commit that violates an attachment’s type constraints, throw a JS Error whose name is 'ViperError'.

See also: the Python reference, the database guide, and the commit API.

Generated from the @digitalsubstrate/dsviper TypeScript declarations (index.d.ts) by TypeDoc.

Summary¶

Class	Description
`Attachment`	A class used to represent an attachment
`AttachmentGetting`	An interface used to retrieve a value (aka document) state
`AttachmentMutating`	An interface used to express fine-grained mutations of a value

Reference¶

class Attachment()¶

A class used to represent an attachment.

Note: Not directly instantiable.

exported from index.d

Attachment.createDocument()¶

Return a new document.

Returns:: Value

Attachment.createKey(instanceId)¶

Return a new key.

Arguments:

instanceId (ValueUUId)

Returns:

ValueKey

Attachment.createStructure(initialValue)¶

Create a new structure and may initialize it or throw.

Arguments:

initialValue (ValueStructure | { [fieldName: string]: InputValue; })

Returns:

ValueStructure

Attachment.description(namespace)¶

Return the description.

Arguments:

namespace (NameSpace)

Returns:

string

Attachment.documentType()¶

Return the type of the document.

Returns:: Type

Attachment.documentation()¶

Return the documentation.

Returns:: string

Attachment.identifier()¶

Return the identifier.

Returns:: string

Attachment.keyType()¶

Return the type of the key.

Returns:: AbstractionType

Attachment.keyTypeName()¶

Return the key’s TypeName.

Returns:: TypeName

Attachment.keysType()¶

Return the type of the key.

Returns:: TypeSet

Attachment.optionalDocumentType()¶

Return the type of the optional document.

Returns:: TypeOptional

Attachment.representation(namespace)¶

Return the representation.

Arguments:

namespace (NameSpace)

Returns:

string

Attachment.runtimeId()¶

Return the uuid assigned by the runtime.

Returns:: ValueUUId

Attachment.typeKey()¶

Return the type key<element_type>.

Returns:: TypeKey

Attachment.typeName()¶

Return the TypeName.

Returns:: TypeName

class AttachmentGetting()¶

An interface used to retrieve a value (aka document)

state.

Note: Not directly instantiable.

exported from index.d

AttachmentGetting.attachment(attachmentRuntimeId)¶

Return the attachment or throw.

Arguments:

attachmentRuntimeId (ValueUUId)

Returns:

Attachment

AttachmentGetting.definitions()¶

Return the definitions.

Returns:: DefinitionsConst

AttachmentGetting.enumerate(attachment, encoded)¶

Return a list of (key, document).

Arguments:

attachment (Attachment)
encoded (boolean)

Returns:

[ValueKey, OutputValue][]

AttachmentGetting.get(attachment, key)¶

Return an optional<document_type> associated with the key in the: attachment.

Arguments:

attachment (Attachment)
key (ValueKey)

Returns:

ValueOptional

AttachmentGetting.has(attachment, key)¶

Return true if a document is present for the key.

Arguments:

attachment (Attachment)
key (ValueKey)

Returns:

boolean

AttachmentGetting.keys(attachment)¶

Return all keys.

Arguments:

attachment (Attachment)

Returns:

ValueSet

static AttachmentGetting.diffKeys(currentAttachmentGetting, otherAttachmentGetting, attachment)¶

Return the tuple (added_keys, removed_keys, different_keys, same_keys).

added_keys: keys present in ‘other’ and not in ‘current’.

removed_keys: keys present in ‘current’ and not in ‘other’.

different_keys: documents present in both but not equal.

same_keys: documents present in both and equal.

Arguments:

currentAttachmentGetting (AttachmentGetting)
otherAttachmentGetting (AttachmentGetting)
attachment (Attachment)

Returns:

[ValueSet, ValueSet, ValueSet, ValueSet]

class AttachmentMutating()¶

An interface used to express fine-grained mutations of a value.

Note: Not directly instantiable.

exported from index.d

Extends:

AttachmentGetting

AttachmentMutating.attachment(attachmentRuntimeId)¶

Return the attachment or throw.

Arguments:

attachmentRuntimeId (ValueUUId)

Returns:

Attachment

AttachmentMutating.definitions()¶

Return the definition.

Returns:: DefinitionsConst

AttachmentMutating.diff(attachment, key, value, recursive)¶

Applies the mutation opcodes from the calculation of the difference: between the value passed in parameter and the current value in the state. If recursive is true, the difference is recursively computed by structure’s field.

Arguments:

attachment (Attachment)
key (ValueKey)
value (InputValue)
recursive (boolean)

AttachmentMutating.enumerate(attachment, encoded)¶

Return the list (key, document).

Arguments:

attachment (Attachment)
encoded (boolean)

Returns:

[ValueKey, OutputValue][]

AttachmentMutating.get(attachment, key)¶

Return an optional<document_type> associated with the key.

Arguments:

attachment (Attachment)
key (ValueKey)

Returns:

ValueOptional

AttachmentMutating.has(attachment, key)¶

Return true if a document is associated with the key.

Arguments:

attachment (Attachment)
key (ValueKey)

Returns:

boolean

AttachmentMutating.insertInXarray(attachment, key, path, beforePosition, newPosition, value)¶

Insert a value by creating a new_position before before_position.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
beforePosition (ValueUUId)
newPosition (ValueUUId)
value (InputValue)

AttachmentMutating.keys(attachment)¶

Return all keys.

Arguments:

attachment (Attachment)

Returns:

ValueSet

AttachmentMutating.removeInXarray(attachment, key, path, position)¶

Remove the position.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
position (ValueUUId)

AttachmentMutating.set(attachment, key, value)¶

Associate the document with the key.

Arguments:

attachment (Attachment)
key (ValueKey)
value (InputValue)

AttachmentMutating.subtractInMap(attachment, key, path, value)¶

Form the subtraction between the map located at path in the document: associated with the key and the value.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
value (InputValue)

AttachmentMutating.subtractInSet(attachment, key, path, value)¶

Form the subtraction between the set at path in the document associated: with the key and the value.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
value (InputValue)

AttachmentMutating.unionInMap(attachment, key, path, value)¶

Form the union between the map located at path in the document: associated with the key and the value.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
value (InputValue)

AttachmentMutating.unionInSet(attachment, key, path, value)¶

Form the union between the set at path in the document associated: with key and the value.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
value (InputValue)

AttachmentMutating.update(attachment, key, path, value)¶

Update the value located at path in the document associated with the key.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
value (InputValue)

AttachmentMutating.updateInMap(attachment, key, path, value)¶

Form the subtraction between the map located at path in the document: associated with the key and the value.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
value (InputValue)

AttachmentMutating.updateInXarray(attachment, key, path, position, value)¶

Update the value at position.

Arguments:

attachment (Attachment)
key (ValueKey)
path (PathConst)
position (ValueUUId)
value (InputValue)