npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@xanthous/n3

v1.3.5

Published

Lightning fast, asynchronous, streaming Turtle / N3 / RDF library.

Downloads

129

Readme

Lightning fast, asynchronous, streaming RDF for JavaScript

Build Status Coverage Status npm version DOI

The N3.js library is an implementation of the RDF.js low-level specification that lets you handle RDF in JavaScript easily. It offers:

Parsing and writing is:

Installation

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

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

N3.js seamlessly works in browsers via webpack or browserify. If you're unfamiliar with these tools, you can read webpack: Creating a Bundle – getting started or Introduction to browserify. You will need to create a "UMD bundle" and supply a name (e.g. with the -s N3 option in browserify).

Creating triples/quads

N3.js follows the RDF.js low-level specification.

N3.DataFactory will give you the factory functions to create triples and quads:

const { DataFactory } = N3;
const { namedNode, literal, defaultGraph, quad } = DataFactory;
const myQuad = quad(
  namedNode('https://ruben.verborgh.org/profile/#me'),
  namedNode('http://xmlns.com/foaf/0.1/givenName'),
  literal('Ruben', 'en'),
  defaultGraph(),
);
console.log(myQuad.subject.value);         // https://ruben.verborgh.org/profile/#me
console.log(myQuad.object.value);          // Ruben
console.log(myQuad.object.datatype.value); // http://www.w3.org/1999/02/22-rdf-syntax-ns#langString
console.log(myQuad.object.language);       // en

In the rest of this document, we will treat “triples” and “quads” equally: we assume that a quad is simply a triple in a named or default graph.

Parsing

From an RDF document to quads

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

const parser = new N3.Parser();
parser.parse(
  `PREFIX c: <http://example.org/cartoons#>
   c:Tom a c:Cat.
   c:Jerry a c:Mouse;
           c:smarterThan c:Tom.`,
  (error, quad, prefixes) => {
    if (quad)
      console.log(quad);
    else
      console.log("# That's all, folks!", prefixes);
  });

The callback's first argument is an optional error value, the second is a quad. If there are no more quads, the callback is invoked one last time with null for quad 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:

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

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

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

It is possible to provide the base IRI of the document that you want to parse. This is done by passing a baseIRI argument upon creation:

const parser = new N3.Parser({ baseIRI: 'http://example.org/' });

By default, N3.Parser will prefix blank node labels with a b{digit}_ prefix. This is done to prevent collisions of unrelated blank nodes having identical labels. The blankNodePrefix constructor argument can be used to modify the prefix or, if set to an empty string, completely disable prefixing:

const parser = new N3.Parser({ blankNodePrefix: '' });

From an RDF stream to quads

N3.Parser can parse Node.js streams as they grow, returning quads as soon as they're ready.

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

N3.StreamParser is a Node.js stream and RDF.js Sink implementation. This solution is ideal if your consumer is slower, since source data is only read when the consumer is ready.

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

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

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

Writing

From quads to a string

N3.Writer serializes quads as an RDF document. Write quads through addQuad.

const writer = new N3.Writer({ prefixes: { c: 'http://example.org/cartoons#' } });
writer.addQuad(
  namedNode('http://example.org/cartoons#Tom'),
  namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
  namedNode('http://example.org/cartoons#Cat')
);
writer.addQuad(quad(
  namedNode('http://example.org/cartoons#Tom'),
  namedNode('http://example.org/cartoons#name'),
  literal('Tom')
));
writer.end((error, result) => console.log(result));

By default, N3.Writer writes Turtle (or TriG if some quads are in a named graph). To write N-Triples (or N-Quads) instead, pass a format argument upon creation:

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

From quads to an RDF stream

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

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

From a quad stream to an RDF stream

N3.StreamWriter is a Node.js stream and RDF.js Sink implementation.

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

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:

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

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 triples with :Mickey as subject.

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

const mickey = store.getQuads(namedNode('http://ex.org/Mickey'), null, null)[0];
console.log(mickey);

Addition and deletion of quads

The store provides the following manipulation methods (documentation):

  • addQuad to insert one quad
  • addQuads to insert an array of quads
  • removeQuad to remove one quad
  • removeQuads to remove an array of quads
  • remove to remove a stream of quads
  • removeMatches to remove all quads matching the given pattern
  • deleteGraph to remove all quads with the given graph
  • createBlankNode returns an unused blank node identifier

Searching quads or entities

The store provides the following search methods (documentation):

  • getQuads returns an array of quads matching the given pattern
  • match returns a stream of quads matching the given pattern
  • countQuads counts the number of quads matching the given pattern
  • forEach executes a callback on all matching quads
  • every returns whether a callback on matching quads always returns true
  • some returns whether a callback on matching quads returns true at least once
  • getSubjects returns an array of unique subjects occurring in matching quads
  • forSubjects executes a callback on unique subjects occurring in matching quads
  • getPredicates returns an array of unique predicates occurring in matching quad
  • forPredicates executes a callback on unique predicates occurring in matching quads
  • getObjects returns an array of unique objects occurring in matching quad
  • forObjects executes a callback on unique objects occurring in matching quads
  • getGraphs returns an array of unique graphs occurring in matching quad
  • forGraphs executes a callback on unique graphs occurring in matching quads

Compatibility

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

Interface specifications

The N3.js submodules are compatible with the following RDF.js interfaces:

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