n3.js Documentation

N3.js can be used in browsers via bundlers like Webpack or Browserify (creating a UMD bundle). Alternatively, you can load it via CDN using a UMD bundle or as an ES module.

UMD Bundle (Global N3):

<script src="https://unpkg.com/n3/browser/n3.min.js"></script>

ES Module:

<script type="module">
  import { Store, Parser, Writer } from 'https://unpkg.com/n3/browser/n3.esm.min.js';
</script>

For Node.js environments, install N3.js using npm. You can then require it in your application using require('n3').

$ npm install n3

const N3 = require('n3');

Since N3.StreamParser implements a standard writable stream interface, you can consume Web Streams (like those from fetch) directly.

In Node.js (v17+): Convert the Web Stream to a Node.js stream using Readable.fromWeb().

In Browsers: Manually write chunks from the Web Stream reader to the StreamParser and handle backpressure using the drain event.

// Node.js 17+
const streamParser = new N3.StreamParser(),
      { Readable } = require('stream');
Readable.fromWeb(response.body).pipe(streamParser);

// Browser
const streamParser = new N3.StreamParser(),
      reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
(async () => {
  for (let result; !(result = await reader.read()).done;) {
    if (!streamParser.write(result.value))
      await new Promise(resolve => streamParser.once('drain', resolve));
  }
  streamParser.end();
})();

When you call .match(subject, predicate, object, graph) on an N3Store (or via the internal DatasetCoreAndReadableStream logic), it returns a DatasetCoreAndReadableStream.

This object acts as both a Dataset and a ReadableStream. It allows you to perform dataset operations (like filter, map, union, toArray) on a specific subset of the data defined by the match pattern, while also being able to stream those results.

// match() returns a streamable dataset subset
const subsetStream = store.match('http://example.org/s', 'http://example.org/p', null, null);

// You can still use Dataset methods on the stream
const subsetArray = subsetStream.toArray();

// Or consume it as a stream
subsetStream.on('data', (quad) => {
  console.log('Matched quad:', quad);
});

Use N3.Writer to serialize quads into an RDF document string. By default, it writes Turtle (or TriG if named graphs are present). You can specify other formats like N-Triples or application/trig via the format option in the constructor. Use addQuad to provide data and end to finalize the serialization.

const writer = new N3.Writer({ prefixes: { c: 'http://example.org/cartoons#' } });
writer.addQuad(quad(
  namedNode('http://example.org/cartoons#Tom'),   // Subject
  namedNode('http://example.org/cartoons#name'),  // Predicate
  literal('Tom')                                  // Object
));
writer.end((error, result) => console.log(result));

N3.StreamWriter is a Node.js stream and RDF.js Sink implementation. It allows you to pipe parsed quads directly into a writer, which can then be piped to an output stream (e.g., process.stdout).

const 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);

N3.Store allows for fast in-memory storage and retrieval of triples. It implements the Dataset interface. To reduce memory consumption when using multiple stores, you can have them share an N3.EntityIndex.

const store = new N3.Store();
store.add(
  quad(
    namedNode('http://ex.org/Pluto'),
    namedNode('http://ex.org/type'),
    namedNode('http://ex.org/Dog')
  )
);
store.add(
  quad(
    namedNode('http://ex.org/Mickey'),
    namedNode('http://ex.org/type'),
    namedNode('http://ex.org/Mouse')
  )
);

// Retrieve all quads
for (const quad of store)
  console.log(quad);
// Retrieve Mickey's quads
for (const quad of store.match(namedNode('http://ex.org/Mickey'), null, null))
  console.log(quad);

You can direct N3.Writer output to a Node.js stream (like process.stdout) by passing the stream as the first argument to the constructor. Set { end: false } in the options if you want to keep the stream open for further writing.

const writer = new N3.Writer(process.stdout, { end: false, prefixes: { c: 'http://example.org/cartoons#' } });
writer.addQuad(
  namedNode('http://example.org/cartoons#Tom'),                   // Subject
  namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),   // Predicate
  namedNode('http://example.org/cartoons#Cat')                    // Object
);
writer.addQuad(quad(
  namedNode('http://example.org/cartoons#Tom'),     // Subject
  namedNode('http://example.org/cartoons#name'),  // Predicate
  literal('Tom')                                    // Object
));
writer.end();