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:


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 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.).