gelatin

libPlasma bindings/implementation for Node.js. Work in progress.

g-speak version

Since it has a native component, gelatin requires the g-speak platform to be installed wherever it's used. At build/npm install time, the version of g-speak used is determined this way:

1. If GELATIN_G_SPEAK_HOME is set in the environment, use that path to look up g-speak. For example, GELATIN_G_SPEAK_HOME=/opt/oblong/g-speak3.26 npm install will build/link against g-speak 3.26 installed to /opt/oblong.
2. Otherwise, look up the most recent compatible version of g-speak in /opt/oblong.

build dependencies

gelatin has these dependencies at build/npm install time:

• python3 and python2.7, for node-gyp
• oblong-loamX.Y
• oblong-plasmaX.Y

where X.Y is the g-speak version determined above.

Some older versions of g-speak require also, on Ubuntu 16.04:

• libjpeg-dev
• libpng12-dev
• libtiff5-dev

runtime dependencies

At runtime, gelatin depends on:

• oblong-loamX.Y
• oblong-plasmaX.Y
• oblong-system-protistX.Y

where X.Y is the g-speak version used at build time.

The location of peek and poke binaries are found using the G_SPEAK_HOME path computed in the g-speak version section. This path can be overridden at runtime by setting GELATIN_G_SPEAK_HOME in the environment; useful if paths are relocated in a container or snap.

examples

Check the examples/ directory for some commented examples of using gelatin. examples/wandsplit.js is quite practical (inspired by a real-world use case) and uses the most gelatin features of the examples.

const util = require('util');
const peek = require('gelatin').peek;

const pool = process.argv[2];

function main() {
  if (!pool) {
    console.error('pool argument required.');
    process.exitCode = 1;
    return;
  }

  const p = peek(pool);

  p.on('data', (protein) => {
    console.log('metabolized protein with descrips:', protein.descrips);
    if (protein.descrips.indexOf('hangup') >= 0) {
      p.end();
    }
  });
  p.on('error', (err) => {
    console.error(`peek error: ${util.inspect(err)}`);
  });

  console.log('now deposit/poke a protein to pool', pool);
}

main();

API documentation

To generate API documentation from the source repo:

npm install
npm run doc

The documentation will be available at doc/out/index.html

type conversions

Conversions are defined for converting JavaScript values to Slaw values, and for converting Slaw values to JavaScript's values. For JavaScript's primitive types, these are:

| Javascript type/value | Slaw type/value | |----------------------------------|--------------------------------| | null (null) | (null) | | undefined (void 0) | (null) | | boolean (true) | boolean | | number (-5 or 23 or 4.56) | unt32/int32/float64 (see note) | | string ("hello world") | string |

Numeric conversions are a pain because, where slaw has a plethora of numeric types, JavaScript (from a high-level perspective) has just one number type: double-precision float. JavaScript does, under the hood, support int32_t and uint32_t representations of certain numbers (see, for example ), and when a JavaScript number is represented this way its slaw conversion is to the appropriate slaw number type. But it's not always obvious which representation a JavaScript number has, so be careful. Note also that conversions from slaw int64/unt64 to JavaScript number values may be lossy.

For object types and the special Slaw.nil value, the conversions are:

| Javascript type/value | Slaw type/value | |------------------------------------------------------|-----------------| | Map (new Map([["hello", 123]])) | map | | Array ([ true, false ]) | list | | gelatin.Slaw.nil (gelatin.Slaw.nil) | nil | | gelatin.Vect (new gelatin.Vect([0.0, 1.0, 0.])) | v3float64 | | gelatin.Vect2 (new gelatin.Vect2([0.0, 1.0])) | v2float64 | | gelatin.Vect4 (new gelatin.Vect4([0, 1, 2, 3])) | v4float64 | | gelatin.Protein (new gelatin.Protein(["foo"], {})) | protein | | Object (other) ({foo: 123}) (note: only from JS) | map |

Composite values like Maps and Arrays convert each of their elements to slaw. For convenience, it's possible to create a slaw map using a "Plain Old JavaScript Object", but a slaw map always converts to a JavaScript Map value.

platform compatibility

gelatin officially supports the Node.JS v4.2 "Argon" LTS release on Linux and OS X/macOS. Unofficially, gelatin also tries its best to support the latest Node versions released through Homebrew for OS X/macOS.

plasma-js-bridge compatibility

Limited plasma-js-bridge compatibility is offered. peek() accepts an optional callback argument, and a gelatin/compat module is provided for plasma-js-bridge compatible functions such as oldestIndex and newest. Access the compat module like so:

const plas = require('gelatin/compat');

copyright & license

Copyright (c) 2016 Oblong Industries, Inc. Code released under the MIT license.