Overview

DATEX

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

JavaScript Type Support DATEX Type Synchronizable Limitations
string Full std:text Yes 1) 3)
number Full std:decimal Yes 1) 3)
bigint Full std:integer Yes 1) 3)
boolean Full std:boolean Yes 1) 3)
null Full std:null Yes 1) -
undefined Full std:void Yes 1) -
symbol Partial js:Symbol Yes 1) Registered and well-known symbols are not yet supported
Object Full std:Object Yes Objects with prototypes other than Object.prototype or null are mapped to js:Object
Object (with prototype) Sufficient js:Object Yes No synchronisation for nested objects per default
Array Full std:Array Yes -
Set Full std:Set Yes -
Map Full std:Map Yes -
WeakSet None - - Cannot be implemented because WeakSet internals are not accessible. Alternative: StorageWeakSet
WeakMap None - - Cannot be implemented because WeakMap internals are not accessible. Alternative: StorageWeakMap
Function Sufficient std:Function No (Immutable) Functions always return a Promise, even if they are synchronous
AsyncFunction Sufficient std:Function No (Immutable) -
Generator Sufficient js:AsyncGenerator No (Immutable) Generators are always mapped to AsyncGenerators. Generators cannot be stored persistently
AsyncGenerator Sufficient js:AsyncGenerator No (Immutable) Generators cannot be stored persistently
ArrayBuffer Partial std:buffer No ArrayBuffer mutations are currently not synchronized
Uint8Array Partial js:TypedArray/u8 No ArrayBuffer mutations are currently not synchronized
Uint16Array Partial js:TypedArray/u16 No ArrayBuffer mutations are currently not synchronized
Uint32Array Partial js:TypedArray/u32 No ArrayBuffer mutations are currently not synchronized
BigUint64Array Partial js:TypedArray/u64 No ArrayBuffer mutations are currently not synchronized
Int8Array Partial js:TypedArray/i8 No ArrayBuffer mutations are currently not synchronized
Int16Array Partial js:TypedArray/i16 No ArrayBuffer mutations are currently not synchronized
Int32Array Partial js:TypedArray/i32 No ArrayBuffer mutations are currently not synchronized
BigInt64Array Partial js:TypedArray/i64 No ArrayBuffer mutations are currently not synchronized
Float32Array Partial js:TypedArray/f32 No ArrayBuffer mutations are currently not synchronized
Float64Array Partial js:TypedArray/f64 No ArrayBuffer mutations are currently not synchronized
Promise Full js:Promise No (Immutable) Promises cannot be stored persistently
URL Partial std:url No URL mutations are currently not synchronized
Date Partial std:time No Date objects are currently asymetrically mapped to DATEX Time objects
Blob Full std:*/*, No (Immutable) -
File Full js:File No (Immutable) -
ReadableStream Full js:ReadableStream Yes -
WritableStream Full js:WritableStream Yes -
RegExp Partial js:RegExp No (Immutable) RegExp values wrapped in a Ref are currently not synchronized
WeakRef Full std:WeakRef No (Immutable) -
MediaStream Partial js:MediaStream Yes MediaStreams are only supported in browsers that provide a WebRTC API
Error Partial std:Error No Error subclasses are not correctly mapped
HTMLElement Partial 2) std:html No HTML element mutations are currently not synchronized
SVGElement Partial 2) std:svg No SVG element mutations are currently not synchronized
MathMLElement Partial 2) std:mathml No MathML element mutations are currently not synchronized
Document Partial 2) std:htmldocument No Document mutations are currently not synchronized
DocumentFragment Partial 2) std:htmlfragment No DocumentFragment mutations are currently not synchronized

1) Primitive JS values are immutable and cannot be synchronized on their own, but when wrapped in a Ref.
2) UIX-DOM required
3) 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.

Did this doc help you?

Privacy Policy

Help us improving our docs

Our documentations are fully open source. Something is wrong or unclear?

Make a contribution