Lightning fast, spec-compatible, streaming RDF for JavaScript
JavaScript

README.md

Lightning fast, asynchronous, streaming RDF for JavaScript

Build Status Coverage Status npm version

The N3.js library lets you handle RDF in JavaScript easily, in Node.js and the browser. It offers:

Parsing and writing is:

  • asynchronous – triples arrive as soon as possible
  • streaming – streams are parsed as data comes in, so you can parse files larger than memory
  • fast – by far the fastest parser in JavaScript

Installation

For Node.js, N3.js comes as an npm package.

$ npm install n3
var N3 = require('n3');

N3.js seamlessly works in browsers. Generate a browser version as follows:

$ cd N3.js
$ npm install
$ npm run browser
<script src="n3-browser.min.js"></script>

In addition, N3.js is fully compatible with browserify, so you can write code for Node.js and deploy it to browsers.

Triple representation

For maximum performance and ease of use, triples are simple objects with string properties.

URLs, URIs and IRIs are simple strings. For example, parsing this RDF document:

@prefix c: <http://example.org/cartoons#>.
c:Tom a c:Cat.

results in this JavaScript object:

{
  subject:   'http://example.org/cartoons#Tom',
  predicate: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type',
  object:    'http://example.org/cartoons#Cat'
}

Literals are represented as double quoted strings. For example, parsing this RDF document:

c:Tom c:name "Tom".

results in this JavaScript object:

{
  subject:   'http://example.org/cartoons#Tom',
  predicate: 'http://example.org/cartoons#name',
  object:    '"Tom"'
}

This allows you to create and compare literals fast and easily:

triple.object === 'http://example.org/cartoons#Cat'
triple.object === '"Tom"'

For literals with a language or type, add a marker (@ or ^^) and the corresponding value as-is:

'"Tom"@en-gb' // lowercase language
'"1"^^http://www.w3.org/2001/XMLSchema#integer' // no angular brackets <>

An optional fourth element signals the graph to which a triple belongs:

{
  subject:   'http://example.org/cartoons#Tom',
  predicate: 'http://example.org/cartoons#name',
  object:    '"Tom"',
  graph:     'http://example.org/mycartoon'
}

The N3.js Utility (N3.Util) can help you with these representations.

Parsing

From an RDF document to triples

N3.Parser transforms Turtle, TriG, N-Triples or N-Quads document into triples through a callback:

var parser = N3.Parser();
parser.parse('@prefix c: <http://example.org/cartoons#>.\n' +
             'c:Tom a c:Cat.\n' +
             'c:Jerry a c:Mouse;\n' +
             '        c:smarterThan c:Tom.',
             function (error, triple, prefixes) {
               if (triple)
                 console.log(triple.subject, triple.predicate, triple.object, '.');
               else
                 console.log("# That's all, folks!", prefixes)
             });

The callback's first argument is an error value, the second is a triple. If there are no more triples, the callback is invoked one last time with null for triple and a hash of prefixes as third argument.
Pass a second callback to parse to retrieve prefixes as they are read.
If no callbacks are provided, parsing happens synchronously.

By default, N3.Parser parses a permissive superset of Turtle, TriG, N-Triples and N-Quads.
For strict compatibility with any of those languages, pass a format argument upon creation:

var parser1 = N3.Parser({ format: 'N-Triples' });
var parser2 = N3.Parser({ format: 'application/trig' });

Notation3 (N3) is supported only through the format argument:

var parser3 = N3.Parser({ format: 'N3' });
var parser4 = N3.Parser({ format: 'Notation3' });
var parser5 = N3.Parser({ format: 'text/n3' });

From an RDF stream to triples

N3.Parser can parse Node.js streams as they grow, returning triples as soon as they're ready.
This behavior sets N3.js apart from most other libraries.

var parser = N3.Parser(),
    rdfStream = fs.createReadStream('cartoons.ttl');
parser.parse(rdfStream, console.log);

In addition, N3.StreamParser offers a Node.js stream implementation, so you can transform RDF streams and pipe them to anywhere. This solution is ideal if your consumer is slower, since source data is only read when the consumer is ready.

var streamParser = N3.StreamParser(),
    rdfStream = fs.createReadStream('cartoons.ttl');
rdfStream.pipe(streamParser);
streamParser.pipe(new SlowConsumer());

function SlowConsumer() {
  var writer = new require('stream').Writable({ objectMode: true });
  writer._write = function (triple, encoding, done) {
    console.log(triple);
    setTimeout(done, 1000);
  };
  return writer;
}

A dedicated prefix event signals every prefix with prefix and iri arguments.

Writing

From triples to a string

N3.Writer serializes triples as an RDF document. Write triples through addTriple.

var writer = N3.Writer({ prefixes: { c: 'http://example.org/cartoons#' } });
writer.addTriple('http://example.org/cartoons#Tom',
                 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type',
                 'http://example.org/cartoons#Cat');
writer.addTriple({
  subject:   'http://example.org/cartoons#Tom',
  predicate: 'http://example.org/cartoons#name',
  object:    '"Tom"'
});
writer.end(function (error, result) { console.log(result); });

By default, N3.Writer writes Turtle (or TriG for triples with a graph property).
To write N-Triples (or N-Quads) instead, pass a format argument upon creation:

var writer1 = N3.Writer({ format: 'N-Triples' });
var writer2 = N3.Writer({ format: 'application/trig' });

From triples to an RDF stream

N3.Writer can also write triples to a Node.js stream.

var writer = N3.Writer(process.stdout, { prefixes: { c: 'http://example.org/cartoons#' } });
writer.addTriple('http://example.org/cartoons#Tom',
                 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type',
                 'http://example.org/cartoons#Cat');
writer.addTriple({
  subject:   'http://example.org/cartoons#Tom',
  predicate: 'http://example.org/cartoons#name',
  object:    '"Tom"'
});
writer.end();

From a triple stream to an RDF stream

N3.StreamWriter is a writer implementation as a Node.js stream.

var streamParser = new N3.StreamParser(),
    inputStream = fs.createReadStream('cartoons.ttl'),
    streamWriter = new N3.StreamWriter({ prefixes: { c: 'http://example.org/cartoons#' } });
inputStream.pipe(streamParser);
streamParser.pipe(streamWriter);
streamWriter.pipe(process.stdout);

Blank nodes and lists

You might want to use the […] and list (…) notations of Turtle and TriG. However, a streaming writer cannot create these automatically: the shorthand notations are only possible if blank nodes or list heads are not used later on, which can only be determined conclusively at the end of the stream.

The blank and list functions allow you to create them manually instead:

var writer = N3.Writer({ prefixes: { c: 'http://example.org/cartoons#',
                                     foaf: 'http://xmlns.com/foaf/0.1/' } });
writer.addTriple(writer.blank('http://xmlns.com/foaf/0.1/givenName', '"Tom"@en'),
                 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type',
                 'http://example.org/cartoons#Cat');
writer.addTriple('http://example.org/cartoons#Jerry',
                 'http://xmlns.com/foaf/0.1/knows',
                 writer.blank([{
                   predicate: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type',
                   object: 'http://example.org/cartoons#Cat'
                 },{
                   predicate: 'http://xmlns.com/foaf/0.1/givenName',
                   object: '"Tom"@en',
                 }]));
writer.addTriple('http://example.org/cartoons#Mammy',
                 'http://example.org/cartoons#hasPets',
                 writer.list([
                   'http://example.org/cartoons#Tom',
                   'http://example.org/cartoons#Jerry'
                 ]));
writer.end(function (error, result) { console.log(result); });

Be careful to use the output of blank and list only once and only as argument to addTriple of the same writer, as return values of these functions are unspecified.

Storing

N3.Store allows you to store triples in memory and find them fast.

In this example, we create a new store and add the triples :Pluto a :Dog. and :Mickey a :Mouse.
Then, we find a triple with :Mickey as subject.

var store = N3.Store();
store.addTriple('http://ex.org/Pluto',  'http://ex.org/type', 'http://ex.org/Dog');
store.addTriple('http://ex.org/Mickey', 'http://ex.org/type', 'http://ex.org/Mouse');

var mickey = store.find('http://ex.org/Mickey', null, null)[0];
console.log(mickey.subject, mickey.predicate, mickey.object, '.');

Utility

N3.Util offers helpers for IRI and literal representations.
As IRIs are most common, they are represented as simple strings:

var N3Util = N3.Util;
N3Util.isIRI('http://example.org/cartoons#Mickey'); // true

Literals are represented as double quoted strings:

N3Util.isLiteral('"Mickey Mouse"'); // true
N3Util.getLiteralValue('"Mickey Mouse"'); // 'Mickey Mouse'
N3Util.isLiteral('"Mickey Mouse"@en'); // true
N3Util.getLiteralLanguage('"Mickey Mouse"@en'); // 'en'
N3Util.isLiteral('"3"^^http://www.w3.org/2001/XMLSchema#integer'); // true
N3Util.getLiteralType('"3"^^http://www.w3.org/2001/XMLSchema#integer'); // 'http://www.w3.org/2001/XMLSchema#integer'
N3Util.isLiteral('"http://example.org/"'); // true
N3Util.getLiteralValue('"http://example.org/"'); // 'http://example.org/'

Note the difference between 'http://example.org/' (IRI) and '"http://example.org/"' (literal).
Also note that the double quoted literals are not raw Turtle/TriG syntax:

N3Util.isLiteral('"This word is "quoted"!"'); // true
N3Util.isLiteral('"3"^^http://www.w3.org/2001/XMLSchema#integer'); // true

The above string represents the string This word is "quoted"!, even though the correct Turtle/TriG syntax for that is "This word is \"quoted\"!" N3.js thus always parses literals, but adds quotes to differentiate from IRIs:

new N3.Parser().parse('<a> <b> "This word is \\"quoted\\"!".', console.log);
// { subject: 'a', predicate: 'b', object: '"This word is "quoted"!"' }

Literals can be created with createLiteral:

N3Util.createLiteral('My text', 'en-gb');
N3Util.createLiteral('123', 'http://www.w3.org/2001/XMLSchema#integer');
N3Util.createLiteral(123);
N3Util.createLiteral(false);

Blank nodes start with _:, and can be tested for as follows:

N3Util.isBlank('_:b1'); // true
N3Util.isIRI('_:b1'); // false
N3Util.isLiteral('_:b1'); // false

Prefixed names can be tested and expanded:

var prefixes = { rdfs: 'http://www.w3.org/2000/01/rdf-schema#' };
N3Util.isPrefixedName('rdfs:label'); // true;
N3Util.expandPrefixedName('rdfs:label', prefixes); // http://www.w3.org/2000/01/rdf-schema#label

Loading the utility globally

For convenience, N3Util can be loaded globally:

require('n3').Util(global);
isIRI('http://example.org/cartoons#Mickey'); // true
isLiteral('"Mickey Mouse"'); // true

If desired, its methods can even be added directly on all strings:

require('n3').Util(String, true);
'http://example.org/cartoons#Mickey'.isIRI(); // true
'"Mickey Mouse"'.isLiteral(); // true

Compatibility

Specifications

The N3.js parser and writer is fully compatible with the following W3C specifications:

In addition, the N3.js parser also supports Notation3 (N3) (no official specification yet).

Pass a format option to the constructor with the name or MIME type of a format for strict, fault-intolerant behavior.

License, status and contributions

The N3.js library is copyrighted by Ruben Verborgh and released under the MIT License.

Contributions are welcome, and bug reports or pull requests are always helpful. If you plan to implement a larger feature, it's best to contact me first.