dsviper for Node.js

The @digitalsubstrate/dsviper npm package is a native Node.js binding over the same Viper C++ 1.2 runtime that backs the Python dsviper. It ships as prebuilt binaries (prebuilds/<platform>-<arch>/), built with node-addon-api and cmake-js, and requires Node 16+.

The two distributions share a runtime but not a package name: pip install dsviper gives you the Python runtime; npm install @digitalsubstrate/dsviper gives you the Node binding. Both drive the same Viper C++ engine and the same on-disk format.

Note

dsviper is distributed under the Digital Substrate Commercial License 1.2, which grants a free Evaluation License for assessment and training, and a paid Commercial License by written agreement. See License before any commercial use.

Place in the ecosystem

  • Depends on — Viper C++.

  • Sibling of — the Python dsviper runtime: a second binding over the same engine, not a replacement.

  • Distribution — the @digitalsubstrate/dsviper npm package (npm install @digitalsubstrate/dsviper), shipped as prebuilt native binaries. Like the Python dsviper, it is not bundled in the DevKit ZIP.

Two ways to work

As with the Python runtime, there are two ways to reach the engine:

  • Dynamic API — load definitions at runtime and work through the runtime type system, value system, and commit tier (Type*, Value*, Definitions, CommitMutableState, Attachment*). These are the same class names documented for Python under DSM Processing and Serialization. This path is available today and is what the pages in this section cover.

  • Static TS API — typed TypeScript packages generated from a DSM model by Kibo, using the kibo-template-viper TypeScript templates (the Node analogue of the Python static path). The generated surface is catalogued under Templated Features; this section documents the dynamic API only.

Value semantics: Java-like, not Pythonic

The Node surface corresponds to the Python type stub without the local function pools and without Python’s __dunder__ methods. It does keep the remote service clients (ServiceRemote): a Node back-end consumes function pools over the wire, it just doesn’t host them. That asymmetry is confined to services — a Node host can serve a commit database, see Serving a database. Where Python overloads operators, Node exposes explicit, Java-like methods — equals, hash, compare are the value contract. When porting a Python snippet, translate through this table:

Python (dunder / builtin)

Node (explicit method)

a == b (__eq__)

a.equals(b)

a < b, a > b, … (__lt__ / __gt__)

a.compare(b) — three-way, returns a number

hash(a) (__hash__)

a.hash()

str(a) / repr(a) (__str__ / __repr__)

a.toString() / a.representation()

for x in v (__iter__)

iterable — [...v], or the iterator class

v[i] (__getitem__)

v.at(i) / v.get(k)

v[i] = x (__setitem__)

v.set(i, x)

k in m (__contains__)

m.has(k) / m.contains(x)

len(v) (__len__)

v.size()

equals and compare seamlessly coerce a native argument, so you rarely wrap by hand: new ValueDouble(2).equals(2) is true and new ValueDouble(1).compare(2) < 0. Comparing two values of incompatible types throws (compare) or returns false (equals) rather than guessing.

Warning

JavaScript == does not call equals. Between two values it is reference equality — a == b is false even when they hold the same value, so always use .equals. (Against a primitive, a == 3.0, +a, and `${a}` do work, via Symbol.toPrimitive.)

API reference

The complete Node class reference is generated from the package’s TypeScript declarations (index.d.ts) and mirrors the dynamic-API classes documented for Python. Because operations are named methods here rather than dunders, methods such as equals, compare, hash, and toString appear as first-class, documented entries — more explicit than their Python operator-overload equivalents.

The declarations carry doc comments mirrored from the Python stub, so the generated reference is prose-rich and stays in step with the Python API documentation by construction. The one systematic gap is the dunder-replacement methods themselves — equals, compare, hash — which have no source docstring to extract, because their Python origins are operator dunders (__eq__, __lt__, __hash__) that carry none. Those few are worth a hand-written line on the relevant pages.

The full generated reference is in dsviper for Node.js API.

Topics