Migrating to the OpenSpace JavaScript API 1.0.0

This guide outlines the required changes when upgrading from the old (unversioned) OpenSpace JavaScript API to the latest version (1.0.0), introduced in OpenSpace version 0.22.0. These include breaking changes, so existing integrations of the API will need to be updated.

Migration Summary

• Replace singleReturnLibrary() and multiReturnLibrary() with library() details

• Remove any usage of library(boolean) details

• Replace topic.iterator() with direct iteration over topic details

• Replace topic.iterator().next() with topic.next() details

• Remove [1] when accessing Lua return values details

• Manually handle empty host when port is specified for window.openspaceApi(host, port) details

Installation

npm

If you are using npm, update to the latest version:

npm install openspace-api-js@0.9.11

Script tag

If you are including the API via a script tag, the preferred approach is to load it directly from the OpenSpace CDN:

<script type="text/javascript" src="https://liu-se.cdn.openspaceproject.com/api/1.0.0/openspace-api.js"></script>

If you require an offline-capable version, download the latest release and serve it locally:

<script type="text/javascript" src="openspace-api.js"></script>

API Changes

singleReturnLibrary and multiReturnLibrary - removed

The separate library constructors have been unified into a single method.

// Before - single return
const openspace = api.singleReturnLibrary();
openspace.setPropertyValueSingle("someprop", true);

// Before - multi return
const openspace = api.multiReturnLibrary();
openspace.setPropertyValueSingle("someprop", true);

// After
const openspace = api.library();
openspace.setPropertyValueSingle("someprop", true);

library(boolean) - simplified

The boolean parameter is no longer supported.

// Before
const openspace = api.library(true);
const openspace = api.library(false);

// After
const openspace = api.library();

Topic iteration - simplified

The .iterator() function is removed and instead Topics are now directly async iterable.

// Before
const topic = api.subscribeToProperty("Scene.Earth.Scale.Scale");

for await (const data of topic.iterator()) {
  console.log(data.value);
}

// After
const topic = api.subscribeToProperty("Scene.Earth.Scale.Scale");

for await (const data of topic) {
  console.log(data.value);
}

As a result, iterator.next() is no longer valid. A new function topic.next() can be used to await and access the next data value.

// Before
const topic = api.subscribeToProperty("Scene.Earth.Scale.Scale");

const data = await topic.iterator().next();
console.log(data.value.value);

// After
const topic = api.subscribeToProperty("Scene.Earth.Scale.Scale");

const data = await topic.next();
console.log(data.value);

Lua return values - simplified

Lua return values are no longer wrapped under key [1]. Values are now returned directly.

If you previously used singleReturnLibrary() no changes are necessary - this behavior is now the default.

// Before
const openspace = api.library();
const value = await openspace.time.currentTime();
const time = value[1];

// Or accessed directly
const openspace = api.library();
const time = await openspace.time.currentTime()[1];

// After
const openspace = api.library();
const time = await openspace.time.currentTime();

Manual handling of empty host IP to window.openspaceApi(host, port)

The host now needs to be a valid value when calling window.openspaceApi(host, port). Before, empty or falsey values led to 'localhost' being used as default. Now you need to handle this manually.

// Before - this worked even if the ipaddress field was empty. Host would be 'localhost'
let host = document.getElementById('ipaddress').value;
let api = window.openspaceApi(host, 4682);

// After - openspaceApi no longer accepts an empty value => handle the 'localhost' case somehow
let host = document.getElementById('ipaddress').value;
if (!host) {
  host = 'localhost';
}
let api = window.openspaceApi(host, 4682);

// Or a shorter alternative
let host = document.getElementById('ipaddress').value;
let api = window.openspaceApi(host ?? 'localhost', 4682);

Note that 'localhost' and 4682 are the default values for the the window.openspaceApi function, so this would also work if no custom IP is needed:

// Specifying no host port defaults to 'localhost' and 4682
let api = window.openspaceApi();