Types

The DATEX Runtime comes with its own type system which is mapped to JavaScript types. DATEX types can be accessed via Datex.Type.

Supported built-in JavaScript and Web types

¹⁾ Primitive JS values are immutable and cannot be synchronized on their own, but when wrapped in a Ref.
²⁾ UIX-DOM required
³⁾ The corresponding object values of primitive values (e.g. new Number() for number) are not supported

Std types

The Datex.Type.std namespace contains all the builtin (std) DATEX types that can be accessed as runtime values, e.g.:

// primitive types
Datex.Type.std.text
Datex.Type.std.integer
Datex.Type.std.integer_8
Datex.Type.std.integer_64

// complex types
Datex.Type.std.Array
Datex.Type.std.Array_8
Datex.Type.std.Function

There also exist globally accessible short names for some of the types, matching their respective typescript names:

Datex.Type.std.text === string
Datex.Type.std.decimal === number
Datex.Type.std.integer === bigint
Datex.Type.std.boolean === boolean
Datex.Type.std.Any === any

Special JS types

Most builtin JavaScript types, like Map, Set or Array have equivalent types in the DATEX std library. There are only a few types that are implemented specifically to match JS types:

js:Function

The js:Function (Datex.Type.js.Function) is a special wrapper around a JavaScript function that can be transferred between endpoints.

In contrast to a normal function (std:Function) that can also be mapped to a JavaScript function, a js:Function is always executed on the endpoint where it is called, not on the origin endpoint.

A transferable functions can be created from a normal JS function. Dependencies from the parent scope can be declared with a use() statement:

import { JSTransferableFunction } from "datex-core-legacy/types/js-function.ts";

const data = $$([1,2,3]);

// create a js:Function
const transferableFn = JSTransferableFunction.create(() => {
    use (data);

    console.log(data);
    // ...
})

// call function on another endpoint (endpoint must have arbitrary source code execution permission)
await datex `@example :: ${transferableFn}()`

Note

When you are using transferable functions within a UIX project, dependencies from the parent scope are automatically detected and transferred. You don't need to explicitly declare them with use().

js:Object

In contrast to std:Object, js:Object is used for JavaScript object with a prototype other than Object.prototype or null (e.g. a class instance).

Examples for std:Objects:

• A plain object like {x: 1, y: new Set()}
• Object with null prototype (e.g. {__proto__: null, x: 1})

Examples for js:Objects:

• A builtin object like console
• A class instance like new WebSocket("ws://example.com")

The property values of a js:Object are never automatically bound to pointers when the object is bound to a pointer.

js:Symbol

DATEX has no native symbol type. JavaScript symbols are mapped to js:Symbol values.

js:MediaStream

This type mapping allows sharing MediaStream objects with audio/video tracks between browser endpoints. Backend (Deno) endpoints are not yet supported due to missing support for WebRTC.

Structs

The struct helper function allows you to define custom DATEX types with a fixed structure. All struct values are represented as plain objects in JavaScripts. They can take any DATEX compatible value as properties.

Datex runtime type validation is enabled for struct instances per default. Because all the properties are known at construction time, structs are more efficient than plain objects.

Usage:

import { struct, inferType } from "datex-core-legacy/types/struct.ts";

// struct definition
const MyStruct = struct({
    a: string, // short name for Datex.Type.std.text
    b: Set, // JavaScript 'Set' class, equivalent to Datex.Type.std.Set
    c: Array<number>, // generic Array class (generic type argument has no effect at runtime!)
    // nested struct
    x: {
        xx: string,
        yy: Map<string, string>
    }
})

// inferred TS definition:
type MyStruct = inferType<typeof MyStruct>
// -----------------------------------------------
//      | 
//      V
{
    a: string,
    b: Set<any>,
    c: Array<number>,
    x: {
        xx: string,
        yy: Map<string, string>
    }
}
// -------------------------------------------------
 
// instantiation (throws a runtime error if it doesn't match the struct definition)
const myStruct: MyStruct = MyStruct({
    a: "aaaaaa",
    b: new Set(),
    c: [1,2,3],
    x: {
        xx: "xxxxxxx",
        yy: new Set(['1','2'])
    }
})

With the inferType helper, the TypeScript type for the struct definition can be inferred.

A struct definition accepts strings a keys and Datex.Types, JavaScript classes or other struct definitions as values.

Mapping your own JS classes to DATEX types

Check out the chapter Classes for more information.