Home

Awesome

NOTE: This package has been consolidated into the vega/vega repository, where future development and issues will be handled. This repository has been archived and is now read-only.

vega-loader

Network request and file loading utilities.

API Reference

File Loading

<a name="loader" href="#loader">#</a> vega.<b>loader</b>([<i>options</i>]) <>

Creates a new loader instance with default options. A loader object provides methods for loading files from the network or disk, and for sanitizing requested URLs and filenames. If provided, the key-value pairs in the options object will be passed as default options to the various loader methods.

The options object can include the following entries:

<a name="load" href="#load">#</a> loader.<b>load</b>(<i>uri</i>[, <i>options</i>]) <>

Loads a file from either the network or disk, and returns a Promise for asyncronously accessing the loaded content. This method does not perform any parsing, it simply returns the loaded data as either a Buffer or String instance, depending on the execution environment. To subsequently parse loaded data, use the read method.

The uri argument is a value indicating the file to load. This is typically either an absolute or relative URL string. If running server-side via node.js, this argument might also be a file path (e.g., 'file:///path/to/file.txt').

If provided, the options argument will be combined with any default options passed to the loader constructor. In the case of identical property names, values from the options argument for this method will be used.

var loader = vega.loader();
loader.load('data.json').then(function(data) {
  // do something with loaded data
}).catch(function(error) {
  // error handling here
});

<a name="load_sanitize" href="load_sanitize">#</a> loader.<b>sanitize</b>(<i>uri</i>, <i>options</i>) <>

URI sanitizer function, which takes a uri and options object as input, and returns a Promise that resolves to a return object that includes a sanitized URL under the href property. This method is used internally by load to ensure the URL is valid and to add additional protocol and hostname information, if needed. This method accepts the same options object accepted by load and returns a Promise. If sanitization is successful, the Promise resolves to a return object containing the URL string as (href), along with a non-enumerable boolean localFile flag, indicating if the file should be loaded from the local filesystem. The Promise rejects if the uri is invalid or disallowed. This method is over-writable for clients who wish to implement custom sanitization.

If provided, the options argument will be combined with any default options passed to the loader constructor. In the case of identical property names, values from the options argument for this method will be used.

<a name="load_http" href="load_http">#</a> loader.<b>http</b>(<i>url</i>, <i>options</i>) <>

Function used internally by load for servicing HTTP requests. Uses fetch by default. Clients may overwrite this method to perform custom HTTP request handling.

If provided, the options argument may include any valid fetch RequestInit properties. The provided options will be combined with any default options passed to the loader constructor under the http property. In the case of identical property names, values from the options argument for this method will be used.

<a name="load_file" href="load_file">#</a> loader.<b>file</b>(<i>filename</i>) <>

Function used internally by load for local file system requests. This method is over-writable for clients who wish to implement custom file loading. Uses the node.js fs module by default.

Data Format Parsing

<a name="read" href="#read">#</a> vega.<b>read</b>(<i>data</i>, <i>schema</i>[, <i>dateParse</i>]) <>

Parse loaded data according to a given format schema. The data argument should be either a String or Buffer instance, typically the result of calling load.

The schema object contents may depend on the data format (see below). Common options include:

The 'date' data type also accepts an optional format string ('date:format'). If provided, the optional dateParse function is used to generate date-time parsers for a date format string. If dateParse is unspecified, the d3-time-format library is used by default. Date-time format strings may be quoted (date:'%A'), but quoting is not required. In addition, parsing of date-time format strings to UTC time is supported ('utc:format').

// read loaded csv data, automatically infer value types
var data = null;
loader.load('data/stocks.csv').then(function(data) {
  data = vega.read(csv_data, {type: 'csv', parse: 'auto'});
});

// read loaded csv data, using provided value types
var data = null;
loader.load('data/stocks.csv').then(function(data) {
  data = vega.read(data, {
    type: 'csv',
    parse: {'date': 'date', 'price': 'number'}
  });
});

// read loaded topojson data, extract mesh of countries
var topojson = null;
loader.load('data/world-110m.json').then(function(data) {
  topojson = vega.read(data, {type: 'topojson', mesh: 'countries'});
});

<a name="inferType" href="#inferType">#</a> vega.<b>inferType</b>(<i>values</i>[, <i>field</i>]) <>

Given an array of values, infers their data type as one of 'boolean', 'integer', 'number', 'date', or 'string'. An optional field accessor can be used to first extract values from the input array, and is equivalent to first calling values.map(field).

<a name="inferTypes" href="#inferTypes">#</a> vega.<b>inferTypes</b>(<i>data</i>, <i>fields</i>) <>

Given an array of data objects and a list of string-typed field names (fields), infers the data type for each field. Returns an object that maps field names to inferred types, determined using the inferType method.

<a name="typeParsers" href="#typeParsers">#</a> vega.<b>typeParsers</b> <>

An object containing a set of parsing functions for converting input values to a specified data type. All parsing functions return null if the input is null, undefined or the empty string ('').

The supported functions are:

<a name="formats" href="#formats">#</a> vega.<b>formats</b>(<i>name</i>[, <i>format</i>]) <>

Registry function for data format parsers. If invoked with two arguments, adds a new format parser with the provided name. Otherwise, returns an existing parser with the given name. The method signature of a format parser is:

A format parser that accepts two arguments, the input data to parse (e.g., a block of CSV text) and a set of format-specific options. The following data formats are registered by default: