Core Utilities¶

This is the catch-all bucket for the cross-cutting primitives the rest of the binding builds on: Definitions and NameSpace register the DSM types of an application; Path addresses and edits a portion of a nested value; Error parses the structured description carried by a thrown Viper error; the Hash* family hashes blobs; and the Logger* family emits leveled diagnostics. Because the bucket is broad, the Quick Start below touches only a representative few — consult the Reference section below for the rest.

When to use: reach for Path to navigate or mutate nested values by location; for Error to turn a caught ViperError into queryable fields; and for the logging family when you need leveled, optionally-captured diagnostics. Definitions and NameSpace come into play when you register custom types (see Database).

Quick Start¶

const { Path, Error: VError, LoggerReport, ValueInt64, ValueString } =
    require('@digitalsubstrate/dsviper');

// Path — address a portion of a nested value, then read or write it.
// JS has no `/` operator overload, so chain the fluent .field()/.index()/.key().
const path = new Path().field('user').field('settings').key('theme').const();
path.representation();              // human-readable, includes "user" / "settings"
// path.at(value) reads; path.set(value, 'dark') writes; both take a Value.
const decoded = Path.decode(path.encode(), defs.const());  // ValueBlob round-trip

// Error — a thrown Viper runtime error is a JS Error with a structured message.
try {
    ValueInt64.cast(new ValueString('hello'));   // type mismatch -> throws
} catch (e) {
    e.name;                        // "ViperError"
    const err = VError.parse(e.message);          // undefined if it doesn't match
    err.component();               // "Viper.ValueInt64"
    err.domain();                  // "TypeErrors"
    err.code();                    // a number
    err.message();                 // "expected int64, got string [cast]."
    err.explained();               // multi-line, all fields
}

// Logging — a leveled facade. Levels are raw uint8 severities passed to the
// constructor (DEBUG=10, INFO=20, WARNING=30, ERROR=40, CRITICAL=50); a logger
// emits only when its level <= the message level. LoggerReport captures to an
// array; LoggerConsole writes to stdout; LoggerNull discards.
const reporter = new LoggerReport(20);            // INFO and above
const log = reporter.logging();
log.info('started');
log.warning('careful');
reporter.messages();               // ["INF:started", "WNG:careful"]

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

Key classes¶

Class	Purpose	Example
`Path`	Constructs the location of a portion of a value
`Error`	The structured error raised by Viper: component, domain, code and message
`Logging`	An interface to emit a message
`LoggerReport`	Collects messages instead of emitting them
`HashSHA1`	Hashes data with SHA1
`NameSpace`	A UUID and a name, under which types are registered
`Definitions`	Registers concepts, clubs, enums, structs and attachments

The mirror of this page for the Python binding is Core Utilities.

Namespace¶

Class	Description
`NameSpace`	A UUID and a name, under which a model’s types are registered

Paths¶

Class	Description
`Path`	Constructs the location of a portion of a value
`PathConst`	A finished Path: read or write the value it points at
`PathComponent`	One step of a Path: what kind of step, and the value it carries
`PathElementInfo`	Where an element sits inside a set
`PathEntryKeyInfo`	Where an entry sits inside a map

Function Pools¶

Class	Description
`FunctionPrototype`	The signature of a function: its return type and its parameters

Hashing¶

Class	Description
`Hashing`	An interface to abstract a hasher
`HashCRC32`	Hashes data with CRC32
`HashMD5`	Hashes data with MD5
`HashSHA1`	Hashes data with SHA1
`HashSHA256`	Hashes data with SHA256
`HashSHA3`	Hashes data with SHA3

Logging¶

Class	Description
`Logging`	An interface to emit a message
`LoggerConsole`	Prints a message on the console
`LoggerReport`	Collects messages instead of emitting them
`LoggerNull`	Discards every message, whatever its level

Utilities¶

Class	Description
`ViperError`	The error a failing call throws, where JS has no name of its own for it
`Error`	Reads a Viper error: component, domain, code and message
`Cancelation`	A cancellation flag
`Semaphore`	A named semaphore, created or opened by name so that separate processes share it
`SharedMemory`	A named memory region shared between processes
`Socket`	A passive socket for a server: bound by its factory, listened on by the server it is handed to
`Float16`	The 16-bit storage of a float value, converted to and from float
`KeyHelper`	Answers three questions on the key side of a model: which keys of a key type carry a document, which attachments a type is keyed into, and which attachments a given key has no document for
`KeyNamer`	Finds a display name for a key among the attachments that carry one

Reference¶

class NameSpace(uuid, name)¶

A UUID and a name, under which a model’s types are registered.

The uuid is the model’s lasting identity. Every type declared here takes its runtimeId from it, and a database holds documents under those ids, so the same uuid is what lets a later run read what an earlier one wrote. Pin it as a literal wherever the model is declared, for that reason. The name is free to change: two namespaces are equal when their uuids are, whatever they are called.

GLOBAL is the one the runtime’s own primitive types carry - Type.STRING and Type.INT32 answer it, a structure you declare answers yours. It is not a namespace to register into: createConcept and its siblings refuse it. Its uuid is the invalid one, which is why the constructor refuses that uuid - a namespace built on it would be the global one.

The name is an identifier: a letter, then letters, digits and underscores.

exported from index.d

Arguments:

uuid (ValueUUId)
name (string)

NameSpace.GLOBAL¶: type: readonly NameSpace

NameSpace.compare(other)¶

Return -1, 0 or 1. Throws if other is not a NameSpace.

Arguments:

other (NameSpace)

Returns:

number

NameSpace.equals(other)¶

Return true if both are equal. other of another type answers false.

Arguments:

other (unknown)

Returns:

boolean

NameSpace.hashKey()¶

A value-identity key for a native Map or Set, following equals: the uuid alone,: the name not taking part, so a renamed namespace keeps its key. A hash, so collisions are possible but negligible.

Returns:: bigint

NameSpace.name()¶

Return the namespace name, empty for the global one.

Returns:: string

NameSpace.uuid()¶

Return the uuid identifying the namespace.

Returns:: ValueUUId

class Path(path)¶

Constructs the location of a portion of a value.

Build one with new Path() and append components, or start from a static factory: fromField, fromIndex, fromKey, fromPosition, fromEntry, fromElement and fromUnwrap.

A Path and a PathConst with the same components compare equal: they carry the same path, and only the Path can still be extended.

exported from index.d

Arguments:

path (PathConst | null)

Path.[Symbol․iterator]()¶

Iterate the path’s components (for..of / spread), via the PathConst view.

Returns:: Iterator<PathComponent>

Path.const()¶

Return the PathConst interface.

Returns:: PathConst

Path.copy()¶

Return a Path holding the same components.

Returns:: Path

Path.element(index)¶

Append an element component at index and return this.

An element addresses a member of a set, which has no key to address it by.

Arguments:

index (number)

Returns:

Path

Path.entry(key)¶

Append an entry component for key and return this.

An entry component addresses the key itself, which a key component, addressing the value, cannot reach.

Arguments:

key (InputValue)

Returns:

Path

Path.equals(other)¶

Return true if other is a Path or a PathConst with the same components.: other of any other type answers false. There is no compare() on a Path - a path has no total order.

Arguments:

other (unknown)

Returns:

boolean

Path.field(name)¶

Append a field component for name and return this, addressing that field of a: struct.

Arguments:

name (string)

Returns:

Path

Path.index(value)¶

Append an index component for value and return this, addressing the element at: that index of a vector or a tuple.

Arguments:

value (number)

Returns:

Path

Path.key(value)¶

Append a key component for value and return this, addressing the value a map holds: under that key.

Arguments:

value (InputValue)

Returns:

Path

Path.path(other)¶

Append every component of other and return this.

Arguments:

other (PathConst)

Returns:

Path

Path.position(value)¶

Append a position component for value and return this, addressing the element an: xarray holds at that position.

Arguments:

value (ValueUUId)

Returns:

Path

Path.representation()¶

Return a string representation.

Returns:: string

Path.toJSON()¶

Serialize for JSON.stringify - the path’s representation string (the easy toJSON: case: a string, no bigint), so JSON.stringify(path) yields that string, not {}.

Returns:: string

Path.unwrap()¶

Append an unwrap component and return this.

It addresses what an optional, a variant or an any holds - the three types whose value is reached by unwrapping it.

Returns:: Path

static Path.decode(blob, definitions, streamCodecInstancing)¶

Return a Path by decoding the blob with Codec.STREAM_BINARY if not: specified.

Arguments:

blob (ValueBlob)
definitions (DefinitionsConst)
streamCodecInstancing (StreamCodecInstancing | null)

Returns:

Path

static Path.fromElement(index)¶

Create and return a Path with an element component at index.

Arguments:

index (number)

Returns:

Path

static Path.fromEntry(value)¶

Return a Path of one entry component for value.

Arguments:

value (InputValue)

Returns:

Path

static Path.fromField(name)¶

Return a Path of one field component for name.

Arguments:

name (string)

Returns:

Path

static Path.fromIndex(index)¶

Return a Path of one index component for index.

Arguments:

index (number)

Returns:

Path

static Path.fromKey(key)¶

Return a Path of one key component for key.

Arguments:

key (InputValue)

Returns:

Path

static Path.fromPosition(position)¶

Return a Path of one position component for position.

Arguments:

position (ValueUUId)

Returns:

Path

static Path.fromUnwrap()¶

Return a Path of one unwrap component.

Returns:: Path

static Path.read(streamReading, definitions)¶

Read and return a Path.

Arguments:

streamReading (StreamReading)
definitions (DefinitionsConst)

Returns:

Path

class PathConst()¶

A finished Path: read or write the value it points at.

at() reads, set() and patch() assign. It also walks itself - parent, ancestors, components - reports whether it is regular, and encodes to a blob.

A PathConst and a Path with the same components compare equal: they carry the same path, and only the Path can still be extended.

Note: Not directly instantiable.

exported from index.d

PathConst.ancestors()¶

Return the list of ancestors.

Returns:: Path[]

PathConst.at(target, encoded)¶

Return what the path addresses inside target.

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

Arguments:

target (Value)
encoded (boolean | null)

Returns:

Value | OutputValue

PathConst.checkType(type)¶

Return the type the path reaches in type, or undefined through an any or a variant.

The type under an any or a variant is known only at runtime. Throw when the path does not fit type.

Arguments:

type (Type)

Returns:

Type | undefined

PathConst.components()¶

Return the list of components.

Returns:: PathComponent[]

PathConst.copy()¶

Return a mutable Path holding the same components.

Returns:: Path

PathConst.elementInfo()¶

Return the PathElementInfo.

Returns:: PathElementInfo

PathConst.encode(streamCodecInstancing)¶

Serialize the path into a blob.

Unrelated to the encoded= keyword of at(), which selects a native or a Value.

streamCodecInstancing chooses the codec; Codec.STREAM_BINARY is used when it is undefined - the same default Path.decode reads with.

Arguments:

streamCodecInstancing (StreamCodecInstancing | null)

Returns:

ValueBlob

PathConst.entryKeyInfo()¶

Return the PathEntryKeyInfo.

Returns:: PathEntryKeyInfo

PathConst.equals(other)¶

Return true if other is a PathConst or a Path with the same components.: other of any other type answers false. There is no compare() on a PathConst - a path has no total order.

Arguments:

other (unknown)

Returns:

boolean

PathConst.fromComponent(index)¶

Return a path from index.

Arguments:

index (number)

Returns:

Path

PathConst.hasPrefix(path)¶

Return true if path is a prefix of this one.

Arguments:

path (PathConst)

Returns:

boolean

PathConst.isApplicable(value)¶

Check if the path is applicable to the value.

Arguments:

value (Value)

Returns:

boolean

PathConst.isElementPath()¶

Return true if the path contains Element components.

Returns:: boolean

PathConst.isEntryKeyPath()¶

Return true if the path contains Entry components.

Returns:: boolean

PathConst.isRegular()¶

Return true if the path holds neither an entry nor an element component.

set() takes a regular path, patch() one that is not.

Returns:: boolean

PathConst.isRoot()¶

Return true if this path is the root.

Returns:: boolean

PathConst.lastComponent()¶

Return the last component as a Path.

Returns:: Path

PathConst.lastComponentValue(encoded)¶

Return what the last component addresses, or throw on a root path.

An unwrap addresses void, which reads as null.

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

Arguments:

encoded (boolean | null)

Returns:

Value | OutputValue

PathConst.parent()¶

Return the parent Path or throw if this path is the root.

Returns:: Path

PathConst.patch(target, value)¶

Replace, in target, a value that serves as its own key.

Such a value cannot be assigned in place, because changing it changes where it belongs: patch removes it and puts the new one back. Two shapes address one, and the path must be one of them - isElementPath() and isEntryKeyPath() answer which, and anything else throws.

An element of a set, addressed by element(index): the element is the key. And the key of a map entry, addressed by entry(key) followed by index(0), where index(1) would address the value instead - that one throws here, since a value is assigned with set().

Arguments:

target (Value)
value (InputValue)

PathConst.regularized()¶

Return the path made regular.

An entry or an element component addresses a value that serves as its own key; the regular path addresses what it holds instead, so element(0) becomes [0] and entry(key).index(0) becomes [key]. A path already regular is answered unchanged.

Returns:: Path

PathConst.representation()¶

Return a string representation.

Returns:: string

PathConst.set(target, value)¶

Assign the value at this path in target.

The path must be regular, and not the root: an entry or an element component throws - patch() is the one that takes those.

Arguments:

target (Value)
value (InputValue)

PathConst.toComponent(index)¶

Return a path to index (excluded).

Arguments:

index (number)

Returns:

Path

PathConst.write(streamWriting)¶

Write the path into streamWriting.

Arguments:

streamWriting (StreamWriting)

class PathComponent()¶

One step of a Path: what kind of step, and the value it carries.

The kind is one of seven: unwrap, index, key, position and field address into a value; entry and element are the two irregular kinds, which PathEntryKeyInfo and PathElementInfo describe in full.

Note: Not directly instantiable.

exported from index.d

PathComponent.type()¶

Return which kind of component this is - unwrap, index, key, position, field, entry: or element.

Returns:: string

PathComponent.value(encoded)¶

Return what the component addresses: void for an unwrap, which reads as null.

A field name, an index, a key or a position. An entry carries the map key whose key it addresses, an element its index in the set’s order; entryKeyInfo() and elementInfo() on the path describe them in full.

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

Arguments:

encoded (boolean | null)

Returns:

Value | OutputValue

class PathElementInfo()¶

Where an element sits inside a set.

The path to the set, the path to the element, and its index.

Note: Not directly instantiable.

exported from index.d

PathElementInfo.elementPath()¶

Return the path for the element.

Returns:: PathConst

PathElementInfo.index()¶

Return the index for the element.

Returns:: number

PathElementInfo.setPath()¶

Return the path for the set.

Returns:: PathConst

class PathEntryKeyInfo()¶

Where an entry sits inside a map.

The path to the map, the path to the key, and the key itself.

Note: Not directly instantiable.

exported from index.d

PathEntryKeyInfo.key()¶

Return the key the entry addresses.

Returns:: Value

PathEntryKeyInfo.keyPath()¶

Return the path for the key.

Returns:: PathConst

PathEntryKeyInfo.mapPath()¶

Return the path for the map.

Returns:: PathConst

class FunctionPrototype()¶

The signature of a function: its return type and its parameters.

Note: Not directly instantiable.

exported from index.d

FunctionPrototype.name()¶

Return the name of the function this prototype is the signature of.

Returns:: string

FunctionPrototype.parameters()¶

Return the list of parameters.

Returns:: [string, Type][]

FunctionPrototype.returnType()¶

Return the type of the returned value.

Returns:: Type

class Hashing()¶

An interface to abstract a hasher.

Note: Not directly instantiable.

exported from index.d

Hashing.blockSize()¶

Return the internal block size of the hash algorithm in bytes.

Returns:: number

Hashing.digest()¶

Return the hash of everything fed so far, as raw bytes.

Returns:: ValueBlob

Hashing.digestSize()¶

Return the size of the resulting hash in bytes.

Returns:: number

Hashing.hexdigest()¶

Return the digest in hexadecimal.

Returns:: string

Hashing.name()¶

Return the name of the algorithm, as it appears in a codec header.

Returns:: string

Hashing.reset()¶: Reset the hasher.

Hashing.update(blob)¶

Feed blob into the hash.

Arguments:

blob (ValueBlob)

class HashCRC32()¶

Hashes data with CRC32.

exported from index.d

HashCRC32.blockSize()¶

Return the internal block size of the hash algorithm in bytes.

Returns:: number

HashCRC32.digest()¶

Return the hash of everything fed so far, as raw bytes.

Returns:: ValueBlob

HashCRC32.digestSize()¶

Return the size of the resulting hash in bytes.

Returns:: number

HashCRC32.hashing()¶

Return the Hashing interface.

Returns:: Hashing

HashCRC32.hexdigest()¶

Return the digest in hexadecimal.

Returns:: string

HashCRC32.name()¶

Return the name of the algorithm, as it appears in a codec header.

Returns:: string

HashCRC32.reset()¶: Reset the hasher.

HashCRC32.update(blob)¶

Feed blob into the hash.

Arguments:

blob (ValueBlob)

static HashCRC32.hash(blob)¶

Return the hexdigest of the blob.

Arguments:

blob (ValueBlob)

Returns:

string

class HashMD5()¶

Hashes data with MD5.

exported from index.d

HashMD5.blockSize()¶

Return the internal block size of the hash algorithm in bytes.

Returns:: number

HashMD5.digest()¶

Return the hash of everything fed so far, as raw bytes.

Returns:: ValueBlob

HashMD5.digestSize()¶

Return the size of the resulting hash in bytes.

Returns:: number

HashMD5.hashing()¶

Return the Hashing interface.

Returns:: Hashing

HashMD5.hexdigest()¶

Return the digest in hexadecimal.

Returns:: string

HashMD5.name()¶

Return the name of the algorithm, as it appears in a codec header.

Returns:: string

HashMD5.reset()¶: Reset the hasher.

HashMD5.update(blob)¶

Feed blob into the hash.

Arguments:

blob (ValueBlob)

static HashMD5.hash(blob)¶

Return the hexdigest of the blob.

Arguments:

blob (ValueBlob)

Returns:

string

class HashSHA1()¶

Hashes data with SHA1.

exported from index.d

HashSHA1.blockSize()¶

Return the internal block size of the hash algorithm in bytes.

Returns:: number

HashSHA1.digest()¶

Return the hash of everything fed so far, as raw bytes.

Returns:: ValueBlob

HashSHA1.digestSize()¶

Return the size of the resulting hash in bytes.

Returns:: number

HashSHA1.hashing()¶

Return the Hashing interface.

Returns:: Hashing

HashSHA1.hexdigest()¶

Return the digest in hexadecimal.

Returns:: string

HashSHA1.name()¶

Return the name of the algorithm, as it appears in a codec header.

Returns:: string

HashSHA1.reset()¶: Reset the hasher.

HashSHA1.update(blob)¶

Feed blob into the hash.

Arguments:

blob (ValueBlob)

static HashSHA1.hash(blob)¶

Return the hexdigest of the blob.

Arguments:

blob (ValueBlob)

Returns:

string

class HashSHA256()¶

Hashes data with SHA256.

exported from index.d

HashSHA256.blockSize()¶

Return the internal block size of the hash algorithm in bytes.

Returns:: number

HashSHA256.digest()¶

Return the hash of everything fed so far, as raw bytes.

Returns:: ValueBlob

HashSHA256.digestSize()¶

Return the size of the resulting hash in bytes.

Returns:: number

HashSHA256.hashing()¶

Return the Hashing interface.

Returns:: Hashing

HashSHA256.hexdigest()¶

Return the digest in hexadecimal.

Returns:: string

HashSHA256.name()¶

Return the name of the algorithm, as it appears in a codec header.

Returns:: string

HashSHA256.reset()¶: Reset the hasher.

HashSHA256.update(blob)¶

Feed blob into the hash.

Arguments:

blob (ValueBlob)

static HashSHA256.hash(blob)¶

Return the hexdigest of the blob.

Arguments:

blob (ValueBlob)

Returns:

string

class HashSHA3(bits)¶

Hashes data with SHA3.

bits is ‘224’, ‘256’, ‘384’ or ‘512’, as a string; another value throws.

exported from index.d

Arguments:

bits (string | null)

HashSHA3.blockSize()¶

Return the internal block size of the hash algorithm in bytes.

Returns:: number

HashSHA3.digest()¶

Return the hash of everything fed so far, as raw bytes.

Returns:: ValueBlob

HashSHA3.digestSize()¶

Return the size of the resulting hash in bytes.

Returns:: number

HashSHA3.hashing()¶

Return the Hashing interface.

Returns:: Hashing

HashSHA3.hexdigest()¶

Return the hexa digest.

Returns:: string

HashSHA3.name()¶

Return the name of the algorithm, as it appears in a codec header.

Returns:: string

HashSHA3.reset()¶: Reset the hasher.

HashSHA3.update(blob)¶

Feed blob into the hash.

Arguments:

blob (ValueBlob)

static HashSHA3.hash(blob, bits)¶

Return the hex digest of blob, using the SHA3 variant bits names - ‘224’, ‘256’,: ‘384’ or ‘512’.

Arguments:

blob (ValueBlob)
bits (string | null)

Returns:

string

class Logging()¶

An interface to emit a message.

Note: Not directly instantiable.

exported from index.d

Logging.LEVEL_ALL¶: type: readonly number

Logging.LEVEL_CRITICAL¶: type: readonly number

Logging.LEVEL_DEBUG¶: type: readonly number

Logging.LEVEL_ERROR¶: type: readonly number

Logging.LEVEL_INFO¶: type: readonly number

Logging.LEVEL_WARNING¶: type: readonly number

Logging.critical(message)¶

Log the message for level Critical.

Arguments:

message (string)

Logging.debug(message)¶

Log the message for level Debug.

Arguments:

message (string)

Logging.error(message)¶

Log the message for level Error.

Arguments:

message (string)

Logging.info(message)¶

Log the message for level Info.

Arguments:

message (string)

Logging.log(level, message)¶

Log the message at level.

level is one of Logging.LEVEL_DEBUG, LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR or LEVEL_CRITICAL - the severity of this message, where a logger’s own level is the minimum it keeps.

Arguments:

level (number)
message (string)

Logging.warning(message)¶

Log the message for level Warning.

Arguments:

message (string)

class LoggerConsole(level)¶

Prints a message on the console.

level is the minimum severity kept; anything below it is dropped. Logging.LEVEL_ALL, the default, keeps everything.

exported from index.d

Arguments:

level (number | null)

LoggerConsole.logging()¶

Return the Logging interface.

Returns:: Logging

class LoggerReport(level)¶

Collects messages instead of emitting them.

level is the minimum severity kept; anything below it is dropped. Logging.LEVEL_ALL, the default, keeps everything. Nothing empties the list, so a report holds every message it ever took.

exported from index.d

Arguments:

level (number | null)

LoggerReport.logging()¶

Return the Logging interface.

Returns:: Logging

LoggerReport.messages()¶

Return the messages collected so far, each one the severity’s three letters, a: colon, then the text - DBG, INF, WNG, ERR or CRI.

Returns:: string[]

class LoggerNull(level)¶

Discards every message, whatever its level.

level is accepted so that it takes the same arguments as the other loggers, and changes nothing.

exported from index.d

Arguments:

level (number | null)

LoggerNull.logging()¶

Return the Logging interface.

Returns:: Logging

class ViperError()¶

The error a failing call throws, where JS has no name of its own for it.

Its message carries the structured error the C++ side produced; code, component and domain carry three of its fields, and Error.parse(e.message) reads them all apart.

A call crosses three layers, and what it throws says which refused.

The signature: an argument of the wrong kind or out of range throws an ordinary TypeError or RangeError with a plain message, for which Error.parse answers undefined.

The conversion of a JS native into a typed value: content that does not fit the type throws ViperError, whose message names the type expected, what was given, and the path to the element at fault.

The runtime: an operation it refuses throws ViperError.

A read keeps the name JS has for it: an index past the end throws a RangeError whose name is ‘ViperError’ and which carries code, component and domain. The signature’s RangeError keeps the name ‘RangeError’, which is how the two are told apart.

exported from index.d

Extends:

Error

ViperError.code¶

type: readonly number

The numeric code, unique within the domain.

ViperError.component¶

type: readonly string

The component the error comes from, such as Viper.CommitDatabase.

ViperError.domain¶

type: readonly string

The error domain, which names the family the code belongs to.

class Error(module, domain, code, message)¶

Reads a Viper error: component, domain, code and message.

It is not what a failing call throws; ViperError says what each layer of a call throws. Pass the message of the thrown error to Error.parse to read the four fields apart. A plain message, which a refusal of the signature carries, parses to undefined.

exported from index.d

Arguments:

module (string)
domain (string)
code (number)
message (string)

Error.code()¶

Return the numeric code, unique within the domain.

Returns:: number

Error.component()¶

Return the component the error comes from, such as Viper.CommitDatabase.

Returns:: string

Error.domain()¶

Return the error domain, which names the family the code belongs to.

Returns:: string

Error.explained()¶

Return the structured description, which parse() reads back.

[host@process]:Component:Domain:Code:Message

Returns:: string

Error.hostname()¶

Return the host the error was thrown on - the remote one when it came over RPC.

Returns:: string

Error.message()¶

Return the sentence describing what failed.

Returns:: string

Error.processName()¶

Return the process the error was thrown in, as set by Error.setProcessName().

Returns:: string

static Error.parse(description)¶

Return the Error description encodes, or undefined if it is not one.

The inverse of explained(), used to carry an error across RPC.

Arguments:

description (string)

Returns:

Error | undefined

static Error.setProcessName(name)¶

Assign the name of the process reported in Error.

Arguments:

name (string)

class Cancelation()¶

A cancellation flag. Nothing is interrupted.

cancel() sets it; a running operation reads requested() at points of its own choosing and returns early. One that never reads it runs to the end.

Shared between a host signal handler and a server loop.

exported from index.d

Cancelation.cancel()¶: Request a cancellation.

Safe to call from a signal handler: it sets one atomic flag.

Cancelation.requested()¶

Return true once a cancellation has been requested - it stays true, there is no: reset.

Returns:: boolean

class Semaphore()¶

A named semaphore, created or opened by name so that separate processes

share it. Use the static factory method create(…) or open(…).

The object holds the handle and releases it when V8 collects the object, which is neither timely nor guaranteed; there is no close(). The name is a separate thing that no object owns: unlink(name) is what removes it, and a name left behind can outlive every process that used it. exists(name) answers whether one is there.

Note: Not directly instantiable - use Semaphore.create / Semaphore.open.

exported from index.d

Semaphore.name()¶

Return the name the semaphore is published under, which another process: opens it by.

Returns:: string

Semaphore.post()¶

Release one, waking a waiter if there is one.

Returns:: boolean

Semaphore.tryWait()¶

Take one if the count is positive and return true; return false at once: otherwise, without blocking.

Returns:: boolean

Semaphore.wait()¶

Block until the count is positive, then take one.

The wait blocks the event loop, so no callback, timer or I/O of this process runs to post: when the count is zero, the post that ends it comes from another process. To wait without blocking, poll tryWait() between setImmediate turns instead.

Returns:: boolean

static Semaphore.create(name)¶

Create a semaphore published under name.

Arguments:

name (string)

Returns:

Semaphore

static Semaphore.exists(name)¶

Return true if a semaphore is already published under name.

Arguments:

name (string)

Returns:

boolean

static Semaphore.open(name)¶

Open the semaphore published under name.

Arguments:

name (string)

Returns:

Semaphore

static Semaphore.unlink(name)¶

Remove the semaphore published under name.

Arguments:

name (string)

Returns:

boolean

class SharedMemory()¶

A named memory region shared between processes.

Created or opened by name, so separate processes map the same bytes. Use create(…) or open(…). The bytes are read and written through StreamReaderSharedMemory and StreamWriterSharedMemory, which each take one of these; address() is the raw mapping, for foreign code that expects a pointer.

The object holds the mapping and releases it when V8 collects the object, which is neither timely nor guaranteed; there is no close(). The name is a separate thing that no object owns: unlink(name) is what removes it, and a name left behind can outlive every process that used it. exists(name) answers whether one is there.

Note: Not directly instantiable - use SharedMemory.create / SharedMemory.open.

exported from index.d

SharedMemory.address()¶

Return the address the region is mapped at in this process.

Returns:: bigint

SharedMemory.fd()¶

Return the file descriptor the region is mapped from; -1 on Windows,: where a region is held by a handle, not a descriptor.

Returns:: number

SharedMemory.name()¶

Return the name the region is published under, which another process opens it by.

Returns:: string

SharedMemory.size()¶

Return the size of the region in bytes.

Returns:: number

static SharedMemory.create(name, size)¶

Create a region of size bytes, published under name.

Arguments:

name (string)
size (number)

Returns:

SharedMemory

static SharedMemory.exists(name)¶

Return true if a region is already published under name.

Arguments:

name (string)

Returns:

boolean

static SharedMemory.open(name, size)¶

Open the region published under name, mapping size bytes of it.

Arguments:

name (string)
size (number)

Returns:

SharedMemory

static SharedMemory.unlink(name)¶

Remove the region published under name.

Arguments:

name (string)

Returns:

boolean

class Socket()¶

A passive socket for a server: bound by its factory, listened on by the

server it is handed to.

Only the passive factories a server needs are exposed: the active side, the socket options and the I/O surface stay internal - a Node host consumes a service through the *Remote classes, it does not drive a socket by hand.

On macOS/Linux a unix socket path is limited to ~104 bytes; a longer path fails bind with a misleading “Address already in use”.

Note: Not directly instantiable. Use createPassiveLocal() or createPassiveInet().

exported from index.d

Socket.[Symbol․dispose]()¶

Socket.close()¶

Release the socket. A passive local socket is a file on disk, and the destructor: only runs when V8 collects - which is neither timely nor guaranteed - so a host that abandons a socket must close it. Idempotent.

Socket.isClosed()¶

Return true once the socket has been released.

Returns:: boolean

static Socket.createPassiveInet(hostname, service)¶

Return a socket bound to host and service, over TCP.

service is a port number or a service name, as a string. The socket is bound, not yet listening: the server it is handed to listens on it. Nothing reads the port back, so a service of ‘0’, which lets the system choose one, leaves the caller unable to tell a client where to connect.

Arguments:

hostname (string)
service (string)

Returns:

Socket

static Socket.createPassiveLocal(socketPath)¶

Return a socket bound to the unix socket socketPath.

It is bound, not yet listening: the server it is handed to listens on it.

Arguments:

socketPath (string)

Returns:

Socket

class Float16()¶

The 16-bit storage of a float value, converted to and from float.

Note: Not directly instantiable.

exported from index.d

static Float16.fromFloat(v)¶

Return the float16 as an unsigned int.

Arguments:

v (number)

Returns:

number

static Float16.toFloat(v)¶

Return the float from an unsigned int representing a float16 storage.

Arguments:

v (number)

Returns:

number

class KeyHelper()¶

Answers three questions on the key side of a model: which keys of a key type carry a

document, which attachments a type is keyed into, and which attachments a given key has no document for.

Note: Not directly instantiable.

exported from index.d

static KeyHelper.attachments(type, definitions)¶

Return the attachments of definitions whose key type is type.

Arguments:

type (Type)
definitions (DefinitionsConst)

Returns:

Attachment[]

static KeyHelper.collectKeys(typeKey, attachmentGetting)¶

Return every key of type typeKey that attachmentGetting holds a document for.

Arguments:

typeKey (TypeKey)
attachmentGetting (AttachmentGetting)

Returns:

ValueSet

static KeyHelper.missingAttachments(key, attachmentGetting)¶

Return the attachments key could have but attachmentGetting holds no document for.

Arguments:

key (ValueKey)
attachmentGetting (AttachmentGetting)

Returns:

Attachment[]

class KeyNamer(definitions)¶

Finds a display name for a key among the attachments that carry one.

An attachment carries one when it is called name and holds a string, or when its document is a structure with a string field called name. When several are keyed on one concept, the one read is the first by runtimeId, not by the order they were declared in.

exported from index.d

Arguments:

definitions (DefinitionsConst)

KeyNamer.name(key, attachmentGetting)¶

Return the display name of key, read through attachmentGetting, or undefined if no: attachment carries one.

Arguments:

key (ValueKey)
attachmentGetting (AttachmentGetting)

Returns:

string | undefined

KeyNamer.smartName(key, attachmentGetting)¶

Return the display name of key, falling back to what the surrounding attachments: reachable through attachmentGetting can spell out, or undefined.

Arguments:

key (ValueKey)
attachmentGetting (AttachmentGetting)

Returns:

string | undefined