graphy.js

A collection of RDF libraries for JavaScript

View the Project on GitHub

« API / Textual RDF Content Handlers

This documentation covers the following graphy packages:

Contents

A note about Events

These modules offer two distinct approaches to binding event listeners. The traditional .on(...) approach will allow you to attach event listeners on the Transform object that is returned by the module function. This style was popularized by node.js, however this actually does incur a non-trivial amount of overhead for setup, teardown, and emittance.

A sleeker alternative to the .on(...) approach is the inline events style. Simply provide a callback function for each event you want to attach a listener to at the time the module function is called, passing a direct reference to at most one callback function per event. This approach allows the module to bypass the EventEmitter methods and can result in slightly better performance; it is also more pleasant to look at. However, it might not be suitable for users who need the ability to add multiple event listeners, to remove listeners, or to add listeners at a later time.

See the read examples for a demonstration of the two styles of attaching event listeners.

Accessibility

The following code block demonstrates three different ways to access these modules (shown here for the read verb):

// stand-alone readers
const nt_read = require('@graphy/content.nt.read');
const nq_read = require('@graphy/content.nq.read');
const ttl_read = require('@graphy/content.ttl.read');
const trig_read = require('@graphy/content.trig.read');

// readers via named access from the graphy 'super module'
const graphy = require('graphy');
const nt_read = graphy.content.nt.read;
const nq_read = graphy.content.nq.read;
const ttl_read = graphy.content.ttl.read;
const trig_read = graphy.content.trig.read;

// readers via Content-Type query from the graphy 'super module'
const graphy = require('graphy');
const nt_read = graphy.content('application/n-triples').read;
const nq_read = graphy.content('application/n-quads').read;
const ttl_read = graphy.content('text/turtle').read;
const trig_read = graphy.content('application/trig').read;

Verbs

This section documents the ‘verb’ part of each content module. A ‘verb’ refers to the fact that the module’s export is itself a function.

Difference between scribe and write verbs

The scribe and write verbs are both for serializing RDF to a writable stream. However, scribe is the more basic serializer built for speed, while write is the more advanced serializer built to support rich features such as stylized output (e.g., custom spacing), serializing comments, RDF collections, and so forth.

Additionally, write employs several safety checks that help prevent serializing malformed RDF from faulty write input (e.g., literals in subject position, blank nodes or literals in predicate position, invalid IRI strings, and so on), whereas scribe does not perform such safety checks.

The scribe verb supports the following WritableDataEvent types:

The write verb supports the following WritableDataEvent types (* = difference from scribe):

read([input: string | stream][, config: ReadConfig])

Accessible via the following modules:

Usage examples

Read from a Turtle file in Node.js:

cons fs = require('fs');
const ttl_read = require('@graphy/content.ttl.read');

fs.createReadStream('input.ttl')
    .pipe(ttl_read())
    .on('data', (y_quad) => {
       console.dir(y_quad.isolate());
    })
    .on('eof', () => {
        console.log('done!');
    });

Read a Turtle string:

const ttl_read = require('@graphy/content.ttl.read');

ttl_read(`
    @prefix foaf: <http://xmlns.com/foaf/0.1/> .

    <#spiderman> a foaf:Person ;
        foaf:name "Spiderman" .
`, {
    // whew! simplified inline events style  ;)
    data(y_quad) {
        console.dir(y_quad);
    },

    eof(h_prefixes) {
        console.log('done!');
    },
})

Overloaded variants:

EXPERIMENTAL! The scan verb is currently experimental and has limited test coverage.

scan([input: string | stream][, config: ScanConfig])

Accessible via the following modules:

Usage examples

Count the number of statements in an N-Quads document from stdin in Node.js:

const nq_scan = require('@graphy/content.nq.scan');

// create the scanner instance, provide the input stream as the first argument (equivalent to using '.import' method on returned instance)
nq_scan(process.stdin, {
    // the code to run on each thread (creates a function that will be called with special arguments)
    run: /* syntax: js */ `
      (read, err, update, submit) => {
        let c_stmts = 0;

        return read({
          data() {
            c_stmts += 1;
          },

          error(e_read) {
            err(e_read);
          },

          eof() {
            submit(c_stmts);
          },
        });
      }
    `,

    // how to combine the results received from each call to 'submit'
    reduce: (c_stmts_a, c_stmts_b) => c_stmts_a + c_stmts_b,

    // the final value to report
    report(c_stmts) {
        console.log(`${c_stmts} statements total.`);
    },
});

Convert N-Triples from stdin to Turtle on stdout in Node.js:

const nt_scan = require('@graphy/content.nt.scan');

// create the scanner instance
nt_scan(process.stdin, {
    // use the 'scribe' preset
    preset: 'scribe',

    // 'db_chunk' will be a Buffer in this preset, simply write it to stdout
    update(db_chunk) {
        process.stdout.write(db_chunk);
    },

    // this will fire once the scanner is done
    report() {
        // do stuff...
    },
})
    // example using the RDFJS Sink '.import' method to provide input stream
    .import(process.stdin);

Overloaded variants:

scribe([config: ScribeConfig])

Accessible via the following modules:

Usage examples

Serialize some RDF data to Turtle on-the-fly:

const ttl_scribe = require('@graphy/content.ttl.scribe');
const factory = require('@graphy/core.data.factory');

let ds_scriber = ttl_scribe({
    prefixes: {
        dbr: 'http://dbpedia.org/resource/',
        ex: 'http://ex.org/',
    },
});

ds_scriber.on('data', (s_turtle) => {
    console.log(s_turtle+'');
});

// write an RDFJS quad
ds_scriber.write(factory.quad(...[
  factory.namedNode('http://dbpedia.org/resource/Banana'),
  factory.namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#a'),
  factory.namedNode('http://dbpedia.org/ontology/Plant'),
]));

// or write using a concise-triples struct in strict-mode (c3r)
ds_scriber.write({
    type: 'c3r',
    value: {
        'dbr:Banana': {
            'ex:color': ['dbr:Yellow'],
        },
    },
});

Prints:

@prefix dbr: <http://dbpedia.org/resource/> .
@prefix ex: <http://ex.org/> .

dbr:Banana a dbo:Plant .

dbr:Banana ex:color dbr:Yellow .

write([config: WriteConfig])

Accessible via the following modules:

Usage examples

Serialize some RDF data to Turtle on-the-fly:

const ttl_write = require('@graphy/content.ttl.write');

let ds_writer = ttl_write({
    prefixes: {
        dbr: 'http://dbpedia.org/resource/',
        ex: 'http://ex.org/',
    },
});

ds_writer.on('data', (s_turtle) => {
    console.log(s_turtle+'');
});

ds_writer.write({
    type: 'c3',
    value: {
        'dbr:Banana': {
            'ex:lastSeen': new Date(),
        },
    },
});

Prints:

@prefix dbr: <http://dbpedia.org/resource/> .
@prefix ex: <http://ex.org/> .

dbr:Banana ex:lastSeen "2019-01-16T06:59:53.401Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

Scriber extends Transform<WritableDataEvent | @RDFJS/Quad, string>

Methods:

Writer extends Scriber

Methods:

Event definitions

events ReadEvents

The definition for all possible events emitted during content reading. Please see this note about events to understand how this definition applies to both the traditional .on()-style of event binding as well as the inline-style.

Events:

events WriteEvents

The definition for all possible events emitted during content writing. Please see this note about events to understand how this definition applies to both the traditional .on()-style of event binding as well as the inline-style.

Events:

Configs

config ReadConfigNoInput inlines ReadEvents implements @RDFJS/ConstructorOptions

An interface that defines the config object passed to a content reader.

Options:

config ReadConfigWithInput extends #ReadConfigNoInput

Options:

Required:

config ScanConfigNoInput inlines ScanEvents

An interface that defines the config object passed to a content scanner.

Options:

config WriteConfig inlines WriteEvents

An interface that defines the config object passed to a content writer.

Options:

config ListsConfig

config CommentConfig

Interfaces

interface UseInputString

Indicates a utf8-encoded string to use as input to a reader.

interface UseInputStream

Indicates a readable stream to use as input to a reader.

interface WritableDataEvent

An object that describes an event of writable RDF data (including metadata and directives such as prefix mappings, comments, etc.).