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); CommitAttachmentMutating is one — it extends it, as in C++, so it is accepted wherever read access is required and attachmentGetting() hands out the read-only view of the same attachments — and adds the 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 CommitAttachmentMutating
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.

Core Classes

Class

Description

Attachment

Binds a key type - a concept, a club or any_concept - to a document type, registered in a Definitions

Attachment Interfaces

Class

Description

AttachmentGetting

Read access to the documents attached to a set of keys

CommitAttachmentMutating

Expresses fine-grained mutations of the documents attached to keys

Reference

class Attachment()
Binds a key type - a concept, a club or any_concept - to a document type, registered in

a Definitions.

From it, keys are minted and documents created. It holds no document: a store does, and AttachmentGetting reads one by attachment and key.

An attachment compares, orders and hashes by its runtimeId, which its definition determines: two declaring the same namespace, name, key type and document type are equal however they were obtained, so one can key a Map or join a Set through hashKey(), or be sorted with compare().

Note: Not directly instantiable.

exported from index.d

Attachment.compare(other)

Return -1, 0 or 1, ordering by runtimeId. Throws if other is not an Attachment.

Arguments:
  • other (Attachment)

Returns:

number

Attachment.createDocument()

Return a new document.

Returns:

Value

Attachment.createKey(instanceId)
Return a key for this attachment, naming the instance instanceId, or a fresh

instance when it is undefined.

Arguments:
  • instanceId (ValueUUId | null)

Returns:

ValueKey

Attachment.createStructure(initialValue)

Return a new document of this attachment’s document type.

initialValue fills it in; throw if it does not fit the type.

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

Returns:

ValueStructure

Attachment.description(namespace)

Return the attachment rendered for display.

With namespace, every name is written relative to it. Without, the key and document types are written relative to the attachment’s own namespace, and the attachment’s name in full.

Arguments:
  • namespace (NameSpace | null)

Returns:

string

Attachment.documentType()

Return the type of the document.

Returns:

Type

Attachment.documentation()

Return the documentation the attachment was created with, empty when none was given.

Returns:

string

Attachment.equals(other)
Total: true when other is an Attachment declaring the same namespace, name, key type

and document type, however it was obtained; false for anything else.

Arguments:
  • other (unknown)

Returns:

boolean

Attachment.hashKey()
Return a bigint that is equal for two attachments that are equal, so a native Map

or Set holds an attachment by what it declares rather than by identity.

Returns:

bigint

Attachment.identifier()
Return the identifier, unique among the attachments: the attachment’s namespace, its

key type written relative to that namespace, and its name. App::User.profile for an attachment profile of namespace App on a concept User of App; App::Lib::User.profile when the concept is Lib’s; App::any_concept.tag for a key any_concept.

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 set<key> type a whole key listing has.

Returns:

TypeSet

Attachment.optionalDocumentType()

Return optional<documentType>: the type of what get() answers.

Returns:

TypeOptional

Attachment.representation(namespace)

Return the declaration as text, qualified against namespace when one is given.

Arguments:
  • namespace (NameSpace | null)

Returns:

string

Attachment.runtimeId()

Return the uuid identifying this attachment.

It is computed from what the attachment is, so the same declaration yields the same id in any Definitions. Definitions says what each kind is computed from.

Returns:

ValueUUId

Attachment.typeKey()

Return the type key<elementType>.

Returns:

TypeKey

Attachment.typeName()

Return the attachment’s namespace and name, App::profile.

It is not unique: two attachments of one name over different key concepts share it. identifier() is the unique address, App::User.profile.

Returns:

TypeName

class AttachmentGetting()

Read access to the documents attached to a set of keys.

keys, has, get, enumerate, and diffKeys against another state.

Note: Not directly instantiable.

exported from index.d

AttachmentGetting.attachment(attachmentRuntimeId)
Return the attachment attachmentRuntimeId names, or throw if the definitions hold

none.

Arguments:
  • attachmentRuntimeId (ValueUUId)

Returns:

Attachment

AttachmentGetting.definitions()

Return the Definitions every value reachable here is typed by.

Returns:

DefinitionsConst

AttachmentGetting.enumerate(attachment, encoded)

Return every (key, document) pair attachment holds.

Passing encoded false returns each document as a Value rather than a native object.

Arguments:
  • attachment (Attachment)

  • encoded (false)

Returns:

[ValueKey, Value][]

AttachmentGetting.get(attachment, key)

Return a ValueOptional over the document attachment holds at key.

Always a ValueOptional, never undefined: ask isNil() whether it holds anything, and unwrap() for the document itself.

An absent document answers a nil ValueOptional; a key the attachment’s key type does not admit throws, so isNil() reports absence and never a mismatched key.

The document comes back as a copy; mutating it does not reach what is stored.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

Returns:

ValueOptional

AttachmentGetting.has(attachment, key)

Return true if attachment holds a document at key.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

Returns:

boolean

AttachmentGetting.keys(attachment)

Return every key attachment holds a document for.

The set is taken now: a later write does not reach it.

Arguments:
  • attachment (Attachment)

Returns:

ValueSet<ValueKey>

static AttachmentGetting.diffKeys(currentAttachmentGetting, otherAttachmentGetting, attachment)

Return the tuple (addedKeys, removedKeys, differentKeys, sameKeys).

Computed for attachment, from currentAttachmentGetting, the reference, to otherAttachmentGetting.

  • addedKeys: keys present in ‘other’ and not in ‘current’.

  • removedKeys: keys present in ‘current’ and not in ‘other’.

  • differentKeys: documents present in both but not equal.

  • sameKeys: documents present in both and equal.

The order decides which keys are added and which removed: for what changed since the last load, pass the last loaded state first and the new state second.

Arguments:
  • currentAttachmentGetting (AttachmentGetting)

  • otherAttachmentGetting (AttachmentGetting)

  • attachment (Attachment)

Returns:

[ValueSet<OutputValue>, ValueSet<OutputValue>, ValueSet<OutputValue>, ValueSet<OutputValue>]

class CommitAttachmentMutating()

Expresses fine-grained mutations of the documents attached to keys.

No key can be removed once written. To empty one, create the attachment over an optional document type and set it to nil: the key then holds a nil document, and keys() still lists it and has() answers true. A Database, which keeps only the current state, has delete instead.

What a key holds can be replaced whole with set, or rewritten inside the document with update, the subtract* methods and removeInXarray.

Every write is checked against the model before it is recorded: the document against the attachment’s type, the key against the attachment’s key type, the path against the shape of the document, and the value against what that path holds. Any of them throws, and nothing is written. So does an attachment the database has not registered with extendDefinitions.

set and diff create the document a key does not hold yet. The other writes change a document in place, so they need one there. On a key that holds no document they are checked all the same, and one that passes has no effect: nothing is written, and nothing throws.

Note: Not directly instantiable.

exported from index.d

Extends:
  • AttachmentGetting

CommitAttachmentMutating.attachment(attachmentRuntimeId)
Return the attachment attachmentRuntimeId names, or throw if the definitions hold

none.

Arguments:
  • attachmentRuntimeId (ValueUUId)

Returns:

Attachment

CommitAttachmentMutating.attachmentGetting()

Return this object seen through the AttachmentGetting interface.

The two are views of one object: what comes back reads the same documents, not a copy, so a later write through this one is visible there. CommitAttachmentMutating does derive from AttachmentGetting - in C++ and in both bindings - so passing it where a reader is expected already works; this exists to say which view you mean.

Returns:

AttachmentGetting

CommitAttachmentMutating.definitions()

Return the Definitions every value reachable here is typed by.

Returns:

DefinitionsConst

CommitAttachmentMutating.diff(attachment, key, value, recursive)

Write only what differs between value and what attachment holds at key.

recursive computes the difference field by field inside a structure, instead of replacing it whole.

An xarray is written by position: what was inserted, removed or changed. One whose shared positions changed order is replaced whole.

This writes; AttachmentGetting.diffKeys only reports.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • value (InputValue)

  • recursive (boolean | null)

CommitAttachmentMutating.enumerate(attachment, encoded)

Return every (key, document) pair attachment holds.

Passing encoded false returns each document as a Value rather than a native object.

Arguments:
  • attachment (Attachment)

  • encoded (false)

Returns:

[ValueKey, Value][]

CommitAttachmentMutating.get(attachment, key)

Return a ValueOptional over the document attachment holds at key.

Always a ValueOptional, never undefined: ask isNil() whether it holds anything, and unwrap() for the document itself.

An absent document answers a nil ValueOptional; a key the attachment’s key type does not admit throws, so isNil() reports absence and never a mismatched key.

The document comes back as a copy; mutating it does not reach what is stored.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

Returns:

ValueOptional

CommitAttachmentMutating.has(attachment, key)

Return true if attachment holds a document at key.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

Returns:

boolean

CommitAttachmentMutating.insertInXarray(attachment, key, path, beforePosition, newPosition, value)

Insert value at newPosition, before beforePosition, in an xarray.

The xarray sits at path in the document attachment holds at key.

A newPosition the xarray holds, or held before a removal, keeps its place: value is written there and beforePosition is ignored. A beforePosition the xarray does not hold leaves it unchanged.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • beforePosition (ValueUUId)

  • newPosition (ValueUUId)

  • value (InputValue)

CommitAttachmentMutating.keys(attachment)

Return every key attachment holds a document for.

The set is taken now: a later write does not reach it.

Arguments:
  • attachment (Attachment)

Returns:

ValueSet<ValueKey>

CommitAttachmentMutating.removeInXarray(attachment, key, path, position)

Remove position from the xarray at path, in the document attachment holds at key.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • position (ValueUUId)

CommitAttachmentMutating.set(attachment, key, value)

Write value into attachment at key, replacing what was there.

The value is copied in: mutating it afterwards does not reach what was written, and writing the same object under two keys stores two independent documents.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • value (InputValue)

CommitAttachmentMutating.subtractInMap(attachment, key, path, value)
Remove from the map at path, in the document attachment holds at key, the entries

whose map key is in value.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • value (InputValue)

CommitAttachmentMutating.subtractInSet(attachment, key, path, value)
Remove the elements of value from the set at path, in the document attachment holds

at key.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • value (InputValue)

CommitAttachmentMutating.unionInMap(attachment, key, path, value)
Add the entries of value to the map at path, in the document attachment holds at

key, replacing the map keys already there.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • value (InputValue)

CommitAttachmentMutating.unionInSet(attachment, key, path, value)
Add the elements of value to the set at path, in the document attachment holds at

key.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • value (InputValue)

CommitAttachmentMutating.update(attachment, key, path, value)

Write value at path, inside the document attachment holds at key.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • value (InputValue)

CommitAttachmentMutating.updateInMap(attachment, key, path, value)

Update the entries of the map at path from those of value.

The map sits in the document attachment holds at key.

Only map keys already there are written; a map key that only value carries is ignored - unionInMap inserts it instead.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • value (InputValue)

CommitAttachmentMutating.updateInXarray(attachment, key, path, position, value)
Write value at position, in the xarray at path inside the document attachment holds

at key.

Arguments:
  • attachment (Attachment)

  • key (ValueKey)

  • path (PathConst)

  • position (ValueUUId)

  • value (InputValue)