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 |
|---|---|
Binds a key type - a concept, a club or any_concept - to a document type, registered in a Definitions |
Attachment Interfaces¶
Class |
Description |
|---|---|
Read access to the documents attached to a set of keys |
|
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
otheris 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
otheris 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
- Total: true when
- 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)