Tutorial¶
This tutorial walks through a complete example from Node.js: loading a data
model, seeding a database, and performing a full write / read / history cycle
with CommitDatabase. It is the Node twin of the Python
Tutorial.
Prerequisites: This tutorial assumes you have read DSM Processing and understand the
assemble → parse → introspectworkflow, plus the Database lifecycle (stage → commit → reconstruct).
const {
DSMBuilder, DefinitionsInspector,
CommitDatabase, CommitMutableState, CommitStateBuilder, Path,
} = require('@digitalsubstrate/dsviper');
The User/Login Model¶
We’ll use a simple model with Users who have Login credentials and Identity information.
Step 1: Define the Data Model¶
Create a file model.dsm:
// Types definitions
namespace Tuto {f529bc42-0618-4f54-a3fb-d55f95c5ad03} {
"""A user."""
concept User;
"""Login credentials for a User."""
struct Login {
string nickname;
string password;
};
"""Identity information for a User."""
struct Identity {
string firstname;
string lastname;
};
"""A small avatar image stored inline."""
struct Thumbnail {
uint16 width;
uint16 height;
blob data;
};
"""A high-resolution texture stored by reference."""
struct Texture {
uint16 width;
uint16 height;
blob_id pixels;
};
"""Lifecycle state of a User account."""
enum Status {
pending,
active,
completed
};
"""Account state for a User."""
struct Account {
Status state;
};
attachment<User, Login> login;
attachment<User, Identity> identity;
attachment<User, Thumbnail> avatar;
attachment<User, Texture> portrait;
attachment<User, Account> account;
};
Step 2: Validate the Model¶
Parsing both validates the syntax and hands back the runtime definitions. Always check the report before trusting the result:
const [report, dsmDefs, defs] = DSMBuilder.assemble('model.dsm').parse();
report.hasError(); // false
defs is a DefinitionsConst — the immutable runtime snapshot, ready for a
database to adopt.
Step 3: Create a Database¶
Unlike the Python flow — which builds a .cdb file up front with dsm_util —
the Node lifecycle creates the store in process and extends it with the
definitions you just parsed:
const db = CommitDatabase.createInMemory();
db.extendDefinitions(defs);
defs.isEqual(db.definitions()); // true
Step 4: Open and Explore¶
A DefinitionsInspector lists the types and attachments the database carries:
const insp = new DefinitionsInspector(defs);
insp.conceptTypeNames().map(String); // ['Tuto::User']
insp.enumerationTypeNames().map(String); // ['Tuto::Status']
insp.structureTypeNames().map(String);
// ['Tuto::Account', 'Tuto::Identity', 'Tuto::Login', 'Tuto::Texture', 'Tuto::Thumbnail']
insp.attachmentIdentifiers();
// ['Tuto::User.account', 'Tuto::User.avatar', 'Tuto::User.identity',
// 'Tuto::User.login', 'Tuto::User.portrait']
Step 5: Look Up the Attachment¶
Note
Or inject the namespace. definitions.inject(target) binds one frozen
object per namespace on target, globalThis when it is omitted — so
Tuto.attachments.User.login reaches the attachment, as in Python. This step
looks it up explicitly instead, by its identifier, from the inspector. The
identifier strings are exactly the ones attachmentIdentifiers() returns.
const login_att = insp.queryAttachment('Tuto::User.login');
login_att.keyType().typeName().name(); // 'User'
login_att.documentType().typeName().name(); // 'Login'
query* returns undefined on a miss; use check* (e.g. insp.checkAttachment)
when you want a ViperError thrown instead.
Step 6: Create a Key and Document¶
Create a key for a new User. instanceId() returns the underlying UUID
(randomly generated):
const key = login_att.createKey();
key.instanceId().isValid(); // true
Create a Login document and fill its fields. Structures have no attribute
protocol — read with .at(), write with .assign() (a batch setter that
returns the structure) or .set(field, value) for a single field:
const login = login_att.createStructure({ nickname: '', password: '' });
login.at('nickname'); // ''
login.assign({ nickname: 'zoop', password: 'robust' });
login.at('nickname'); // 'zoop'
Step 7: Commit to Database¶
Stage the document against the key on a mutable state, then seal the batch into a commit:
const state = new CommitMutableState(CommitStateBuilder.initialState(db));
state.attachmentMutating().set(login_att, key, login);
const commitId = db.commitMutations('First Commit', state);
String(commitId).length; // 40 (a ValueCommitId)
db.lastCommitId().equals(commitId); // true
Note
Scope of this tutorial
The single-stream flow shown here does not exercise the reduction behaviour described in Commit: everything commits in sequence onto one head, so mutations are never silently dropped and no last-writer-wins arbitration takes place. The contract becomes load-bearing once two heads are folded automatically — see Modes of Use for the diagnostic and which mode applies to your application.
Step 8: Read from Database¶
A read is a reconstruction: CommitStateBuilder.state replays the mutation
trace up to a commit and hands you an immutable snapshot. get returns a
ValueOptional — .unwrap() peels it to the document:
const s = CommitStateBuilder.state(db, commitId);
const result = s.attachmentGetting().get(login_att, key);
result.isNil(); // false
result.unwrap().at('nickname'); // 'zoop'
Value semantics are Java-like: compare documents with .equals(), never with
== between two Values (that is reference equality).
Step 9: Update a Field¶
Update one location through a Path rather than re-setting the whole document.
Capture the new commit id that commitMutations returns — reads always address
an explicit commit, so chaining requires the id:
const next = new CommitMutableState(CommitStateBuilder.state(db, commitId));
next.attachmentMutating().update(login_att, key, new Path().field('nickname').const(), 'zoopy');
const updatedId = db.commitMutations('Update Nickname', next);
Step 10: View History¶
Each commit is a point in the history; reconstruct the state at any of them:
CommitStateBuilder.state(db, updatedId)
.attachmentGetting().get(login_att, key).unwrap().at('nickname'); // 'zoopy'
CommitStateBuilder.state(db, commitId)
.attachmentGetting().get(login_att, key).unwrap().at('nickname'); // 'zoop'
// Before any write, the document is absent:
CommitStateBuilder.initialState(db)
.attachmentGetting().get(login_att, key).isNil(); // true
Step 11: Inspect Commit Headers¶
const header = db.commitHeader(updatedId);
header.label(); // 'Update Nickname'
header.parentCommitId().equals(commitId); // true
The walkthrough above uses the dynamic API (definitions loaded at runtime). The same operations are available through the static API — a typed TypeScript package generated from the model by Kibo, catalogued under Templated Features. See Value Chains for the contrast.