MEOS.js

TypeScript/JavaScript bindings for MEOS, the C library that powers MobilityDB spatiotemporal types.

MEOS is compiled to WebAssembly (wasm64/MEMORY64) via Emscripten. MEOS.js wraps the resulting .wasm module in a typed TypeScript API so you can work with temporal values, spans, sets, and bounding boxes in Node.js or the browser.

Documentation: https://nyuke235.github.io/MEOS.js/

Table of contents

• Requirements
• Installation
• Quick start
• Memory management
• Implemented types

Requirements

• Docker: only needed to build the WASM module from source. Not needed if you use the prebuilt files.

• A JS engine with WebAssembly MEMORY64 support: needed to run MEOS.js, because meos.wasm is compiled with -sMEMORY64=1. In practice:

  • server-side: Node.js 22+
  • browser-side: recent Chromium-based browsers or Firefox with the MEMORY64 proposal enabled

  initMeos() probes for MEMORY64 at startup and throws a clear error if the engine doesn't support it.

Node.js 22+ is additionally required to run the tests, the code generator, the TypeScript build and the docs. Not needed for the WASM build itself.

Installation

1. Get the WASM module

Option A build from source (Docker only)

docker build --output type=local,dest=./wasm --target wasm .

This produces wasm/meos.js and wasm/meos.wasm. The first build may take a while as it compiles GEOS, PROJ, SQLite, GSL, JSON-C, and MobilityDB from source.

Option B use the prebuilt files

todo

2. Install dependencies

npm install

3. Run the tests

npm test

Coming soon: MEOS.js is supposed to be published on npm so you can just npm install meos.js and skip the WASM build and source checkout entirely.

Quick start

import { initMeos, TsTzSpan, IntSpan, TBox, STBox } from './core/index';

await initMeos();

// Timestamp span
const period = TsTzSpan.fromString('[2020-01-01, 2021-01-01)');
console.log(period.toString()); // [2020-01-01 00:00:00+00, 2021-01-01 00:00:00+00)
period.free();

// Integer span
const range = IntSpan.fromBounds(1, 100);
console.log(range.width()); // 99
range.free();

// Spatiotemporal bounding box
const box = STBox.fromString('STBOX XT(((0,0),(10,10)),[2020-01-01,2020-12-31])');
console.log(box.hasX()); // true
console.log(box.hasT()); // true
box.free();

Memory management

Every MEOS.js object wraps a raw pointer allocated in WASM memory. This memory is not managed by the JavaScript garbage collector and must be freed explicitly.

Option 1: manual free()

const span = TsTzSpan.fromString('[2020-01-01, 2021-01-01)');
// ... use span ...
span.free();

Option 2: using (recommended)

All types implement [Symbol.dispose](), so you can use the Explicit Resource Management syntax. The object is freed automatically when the block exits, even if an exception is thrown.

{
    using span = TsTzSpan.fromString('[2020-01-01, 2021-01-01)');
    console.log(span.toString());
} // span.free() called automatically here

using requires TypeScript 5.2+ with "lib": ["ES2022"] or "ESNext" in tsconfig.json.

Implemented types

Click any type name to open its API reference.

Abstract bases: Span · SpanSet

Number spans & sets: IntSpan · IntSpanSet · IntSet · FloatSpan · FloatSpanSet · FloatSet · BigIntSpan · BigIntSpanSet · BigIntSet

Text: TextSet

Time: TsTzSpan · TsTzSpanSet · TsTzSet · DateSpan · DateSpanSet · DateSet

Bounding boxes: TBox · STBox

Temporal booleans: TBool · TBoolInst · TBoolSeq · TBoolSeqSet

Temporal integers: TInt · TIntInst · TIntSeq · TIntSeqSet

Temporal floats: TFloat · TFloatInst · TFloatSeq · TFloatSeqSet

Temporal text: TText · TTextInst · TTextSeq · TTextSeqSet

Temporal geometry point (planar, 2D/3D): TGeomPoint · TGeomPointInst · TGeomPointSeq · TGeomPointSeqSet

Temporal geography point (geodetic, 2D/3D): TGeogPoint · TGeogPointInst · TGeogPointSeq · TGeogPointSeqSet

Factory functions createTBool, createTInt, createTFloat, createTText, createTGeomPoint, createTGeogPoint dispatch to the right subtype based on the MEOS internal type flag.