npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@graphistry/node-api

v5.1.1

Published

Graphistry API client for use with node.js

Downloads

379

Readme

@graphistry/node-api: Graphistry's Node.js client API

Automatically upload and visualize datasets using node, powered by Graphistry's GPU graph visualization infrastructure

Install

npm install @graphistry/node-api

Standard native esm imports

import { EdgeFile, NodeFile, Dataset, Client } from '@graphistry/node-api';

Still transitioning to esm?

  • You may need "type": "module" in your package.json
  • Transpiling should preserve esm import syntax. Ex: "babel": { "presets": [ ["@babel/preset-env", {"modules": false}] ] }

The node-api-test sample project shares an example of a native node project. Please contact the team for additional format support.

Usage

The many options

The API is split between the client wrapper and the JSON configuration payloads:

Ex: JavaScript with async/await

import { EdgeFile, NodeFile, Dataset, Client } from '@graphistry/node-api';

//defaults: 'https', 'hub.graphistry.com', 'https://hub.graphistry.com'
const client = new Client('my_username', 'my_password');

//columnar data is fastest; column per attribute; reuse across datasets
const edgesFile = new EdgeFile({'s': ['a1', 'b2'], 'd': ['b2', 'c3']});
const nodesFile = new NodeFile({'n': ['a1', 'b2', 'c3'], 'a1': ['x', 'y', 'z']});

const dataset = new Dataset({
    node_encodings: { bindings: { node: 'n' } },
    edge_encodings: { bindings: { source: 's', destination: 'd' } },
    metadata: {},
    name: 'testdata',
}, edgesFile, nodesFile);

await dataset.upload(client);
console.info(`View at ${dataset.datasetID} at ${dataset.datasetURL}`);

Ex: TypeScript with async/await

Exactly the same!

Ex: Using promises

import { EdgeFile, NodeFile, Dataset, Client } from '@graphistry/node-api';

//defaults: 'https', 'hub.graphistry.com', 'https://hub.graphistry.com'
const client = new Client(user, password);

//columnar data is fastest; column per attribute; reuse across datasets
const edgesFile = new EdgeFile({'s': ['a1', 'b2'], 'd': ['b2', 'c3']});
const nodesFile = new NodeFile({'n': ['a1', 'b2', 'c3'], 'a1': ['x', 'y', 'z']});

(new Dataset({
        node_encodings: { bindings: { node: 'n' } },
        edge_encodings: { bindings: { source: 's', destination: 'd' } },
        metadata: {},
        name: 'testdata',
    }, edgesFile, nodesFile))
.upload(client)
.then(dataset => {
    console.info(`View at ${dataset.datasetID} at ${dataset.datasetURL}`);
})
.catch(err => {
    console.error('Oops', err);
})

Ex: Apache Arrow uploads

We recommend uploading Apache Arrow format data in most scenarios due to the speed and reliability guarantees:

import { tableFromArrays, tableToIPC, Table } from 'apache-arrow';
import { EdgeFile } from '@graphistry/node-api';

//columnar data is fastest; column per attribute; reuse across datasets
const edgesJSON = {'s': ['a1', 'b2'], 'd': ['b2', 'c3']};
const edgesTable: Table = tableFromArrays(edgesJSON);
const edgesUint8: Uint8Array = tableToIPC(edgesArr, 'file');
const edgesFile = new EdgeFile(edgesUint8, 'arrow');

Ex: Using an organization

You can log into an organization instead of a personal account

import { Client } from '@graphistry/node-api';
const c = new Client('my_user', 'my_pass', 'my_org');

Ex: Custom token

If you already have a JWT token, you can pass it in

import { Client } from '@graphistry/node-api';
const c = new Client();
c.setToken('Bearer 123abc');

Ex: Custom server

You can switch which server to use for uploads and for downloads, which is useful for self-hosted servers and advanced enterprise network configurations

import { Client } from '@graphistry/node-api';
const c = new Client(
    'my_user', 'my_pass', 'optional_my_org',
    'https', //upload protcol
    'hub.graphistry.com', //upload server
    'https://hub.graphistry.com' //url to use in browsers
)

Using API Options

  • Set parsing options for different File formats and shapes

  • Configure Dataset nodes & edges to use data-driven colors, sizes, icons, and badges using simple and complex encodings, including both continuous and categorical mappings

  • Theme with custom branding around background & foreground colors, images, logos, titles, and more

const client = new Client(user, password, org, protocol, host);

// Row-oriented data slower to upload but often convenient
const edgesRows = [
    { 's': 'a', 'd': 'b', 'v': 'e1' },
    { 's': 'b', 'd': 'c', 'v': 'e2' },
    { 's': 'c', 'd': 'a', 'v': 'e3' }
];
const nodesRows = [
    { 'n': 'a', 'vv': 10, 't': 'person' },
    { 'n': 'b', 'vv': 20, 't': 'person' },
    { 'n': 'c', 'vv': 30 , 't': 'car' }
];

const edgesFile = new EdgeFile(
    edgesRows, 'json', 'my_edges',
    // Also: file_compression, sql_transforms, ...
    // https://hub.graphistry.com/docs/api/2/rest/files/
    {
        // JSON parsing options:
        // - https://hub.graphistry.com/docs/api/2/rest/upload/data/#uploadjson2
        // - https://pandas.pydata.org/docs/reference/api/pandas.read_json.html
        parser_options: {
            orient: 'records'  // Row-oriented: Array of objects
        }                      // Default: to columnar json - Object of arrays
    }
);

// Node files are optional, mainly for properties
const nodesFile = new NodeFile(nodesRows);

const dataset = new Dataset(
    {

        // Also: color, size, title, icon, badge, axis
        // - https://hub.graphistry.com/docs/api/2/rest/upload/colors
        // - https://hub.graphistry.com/docs/api/2/rest/upload/complex/
        node_encodings: {
            bindings: {
                node: 'n', // id (required)
                node_title: 'vv'
            },
            complex: {
                default: {
                    pointColorEncoding: {
                        graphType: "point",
                        encodingType: "color",
                        attribute: "vv",
                        variation: "continuous",
                        colors: ["blue", "yellow", "red"]
                    },
                    pointIconEncoding: {
                        graphType: "point",
                        encodingType: "icon",
                        attribute: "t",
                        variation: "categorical",
                        mapping: {
                            categorical: {
                                fixed: {
                                    "person": "user",
                                    "car": "car"
                                },
                                other: "question"
                            }
                        }
                    }
                }
            }
        },

        //Also: color, weight, icon, badge, title
        // - https://hub.graphistry.com/docs/api/2/rest/upload/colors
        // - https://hub.graphistry.com/docs/api/2/rest/upload/complex/
        edge_encodings: {
            bindings: {
                source: 's', destination: 'd'
            },
            complex: { }
        },

        // Brand & theme: Background, foreground, logo, page metadata
        // https://hub.graphistry.com/docs/api/2/rest/upload/metadata/
        metadata: {
            bg: {
                color: 'silver'
            },
            logo: {
                "url": "http://a.com/logo.png",
            }
        },
        name: 'testdata',
    },
    edgesFile,
    nodesFile,

    // Visual and layout settings
    // https://hub.graphistry.com/docs/api/1/rest/url/#urloptions
    {
        strongGravity: true,
        edgeCurvature: 0.5
    }
);

await dataset.upload(client);

console.info(`View dataset ${dataset.datasetID} at ${dataset.datasetURL}`);
console.info(`Dataset using node file ${nodesFile.fileID}, edge file ${edgesFile.fileID}`);

Underlying REST API

For further information about authentication, files, and datasets, see the Graphistry REST API docs.

TypeScript

Types are already automatically bundled with this module

For source maps, you may want to add NODE_OPTIONS=--enable-source-maps to your environment or run node as node --enable-source-maps.