The N3.js library lets you handle Turtle and RDF in JavaScript (Node and browser) easily. It offers:
- Turtle parsing (fully compliant with the Turtle standard)
- in-memory storage and manipulation
- Turtle writing
It has the following characteristics:
- extreme performance – by far the fastest parser in JavaScript
- asynchronous – triples arrive as soon as possible
- streaming – streams are parsed as data comes in, so you can easily parse files that don't fit into memory
At a later stage, this library will support Notation3 (N3), a Turtle superset.
N3.js comes as an npm package.
$ npm install n3
var N3 = require('n3');
It is also fully compatible with browserify.
Alternatively, it offers a minimal browser version (without Node stream support).
$ cd n3
$ npm install
$ make browser
<script src="n3-browser.min.js"></script>
For maximum performance and easy of use,
triples are represented as simple objects.
Since URIs are most common when dealing with RDF,
they are represented as simple strings.
@prefix c: <https://example.org/cartoons#>.
c:Tom a c:Cat.
is represented as
{
subject: 'https://example.org/cartoons#Tom',
predicate: 'https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
object: 'https://example.org/cartoons#Cat'
}
Literals are represented as double quoted strings.
c:Tom c:name "Tom".
is represented as
{
subject: 'https://example.org/cartoons#Tom',
predicate: 'https://example.org/cartoons#name',
object: '"Tom"'
}
This allows you to create and compare literals fast and easily:
triple.object === 'https://example.org/cartoons#Cat'
triple.object === '"Tom"'
The Utility section details entity representation in more depth.
N3.Parser
parses strings into triples using a callback.
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
as triple
value
and a hash of prefixes as the third argument.
var parser = N3.Parser();
parser.parse('@prefix c: <https://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)
});
Addionally, a second callback function (prefix, uri)
can be passed to parse
.
N3.Parser
can also parse triples from a Turtle document that arrives in fragments.
var parser = N3.Parser(), triples = [];
parser.parse(function (error, triple, prefixes) { triple && triples.push(triple); });
parser.addChunk('@prefix c: <https://example.org/cartoons#>.\n');
parser.addChunk('c:Tom a ');
parser.addChunk('c:Cat. c:Jerry a');
console.log(triples); // First triple
parser.addChunk(' c:Mouse.');
parser.end();
console.log(triples); // Both triples
N3.Parser
can parse streams as they grow, returning triples as soon as they're ready.
This behavior sets N3.js apart from most other Turtle libraries.
var parser = N3.Parser(),
turtleStream = fs.createReadStream('cartoons.ttl');
parser.parse(turtleStream, console.log);
In addition, N3.StreamParser
offers a Node Stream implementation,
so you can transform Turtle streams and pipe them to anywhere.
This solution is ideal if your consumer is slower,
as it avoids parser backpressure.
var streamParser = N3.StreamParser(),
turtleStream = fs.createReadStream('cartoons.ttl');
turtleStream.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 uri
arguments.
In this example below, 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(':Pluto', 'a', ':Dog');
store.addTriple(':Mickey', 'a', ':Mouse');
var mickey = store.find(':Mickey', null, null)[0];
console.log(mickey.subject, mickey.predicate, mickey.object, '.');
N3.Writer
can serialize triples as a Turtle string.
var writer = N3.Writer({ 'c': 'https://example.org/cartoons#' });
writer.addTriple('https://example.org/cartoons#Tom',
'https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
'https://example.org/cartoons#Cat');
writer.addTriple({
subject: 'https://example.org/cartoons#Tom',
predicate: 'https://example.org/cartoons#name',
object: '"Tom"'
});
writer.end(function (error, result) { console.log(result); });
N3.Writer
can also write triples to an output stream.
var writer = N3.Writer(process.stdout, { 'c': 'https://example.org/cartoons#' });
writer.addTriple('https://example.org/cartoons#Tom',
'https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
'https://example.org/cartoons#Cat');
writer.addTriple({
subject: 'https://example.org/cartoons#Tom',
predicate: 'https://example.org/cartoons#name',
object: '"Tom"'
});
writer.end();
N3.StreamWriter
is a Turtle writer implementation as a Node Stream.
var streamParser = new N3.StreamParser(),
inputStream = fs.createReadStream('cartoons.ttl'),
streamWriter = new N3.StreamWriter({ 'c': 'https://example.org/cartoons#' });
inputStream.pipe(streamParser);
streamParser.pipe(streamWriter);
streamWriter.pipe(process.stdout);
N3.Util
offers helpers for URI and literal representations.
As URIs are most common, they are represented as simple strings:
var N3Util = N3.Util;
N3Util.isUri('https://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"^^<https://www.w3.org/2001/XMLSchema#integer>'); // true
N3Util.getLiteralType('"3"^^<https://www.w3.org/2001/XMLSchema#integer>'); // 'https://www.w3.org/2001/XMLSchema#integer'
N3Util.isLiteral('"https://example.org/"'); // true
N3Util.getLiteralValue('"https://example.org/"'); // 'https://example.org/'
Note the difference between 'https://example.org/'
(URI) and '"https://example.org/"'
(literal).
Also note that the double quoted literals are not raw Turtle syntax:
N3Util.isLiteral('"This word is "quoted"!"'); // true
The above string represents the string This word is "quoted"!,
even though the correct Turtle syntax for that is "This word is \"quoted\"!"
N3.js thus always parses literals, but adds quotes to differentiate from URIs:
new N3.Parser().parse('<a> <b> "This word is \\"quoted\\"!".', console.log);
// { subject: 'a', predicate: 'b', object: '"This word is "quoted"!"' }
Blank nodes start with _:
, and can be tested for as follows:
N3Util.isBlank('_:b1'); // true
N3Util.isUri('_:b1'); // false
N3Util.isLiteral('_:b1'); // false
QNames can be tested and expanded:
var prefixes = { 'rdfs': 'https://www.w3.org/2000/01/rdf-schema#' };
N3Util.isQName('rdfs:label'); // true;
N3Util.expandQName('rdfs:label', prefixes); // https://www.w3.org/2000/01/rdf-schema#label
For convenience, N3Util
can also be loaded globally:
require('n3').Util(global);
isUri('https://example.org/cartoons#Mickey'); // true
isLiteral('"Mickey Mouse"'); // true
If desired, the methods can even be added directly on all strings:
require('n3').Util(String, true);
'https://example.org/cartoons#Mickey'.isUri(); // true
'"Mickey Mouse"'.isLiteral(); // true
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 larger features, it's best to contact me first.