eyeling

A compact Notation3 (N3) reasoner in JavaScript.

• Single self-contained bundle (eyeling.js), no external runtime deps
• Forward (=>) + backward (<=) chaining over Horn-style rules
• Outputs only newly derived forward facts by default (optionally with compact proof comments)
• If the input contains one or more top-level { ... } log:query { ... }. directives, the output becomes the unique instantiated conclusion triples of those queries (a forward-rule-like projection)
• Works in Node.js and fully client-side (browser/worker)

Links

• Handbook: https://eyereasoner.github.io/eyeling/HANDBOOK
• Semantics: https://eyereasoner.github.io/eyeling/SEMANTICS
• Playground: https://eyereasoner.github.io/eyeling/demo
• Notation3 test suite: https://codeberg.org/phochste/notation3tests
• Eyeling conformance report: https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md

Eyeling is regularly checked against the community Notation3 test suite; the report above tracks current pass/fail results.

If you want to understand how the parser, unifier, proof search, skolemization, scoped closure, and builtins are implemented, start with the handbook.

Quick start

Requirements

• Node.js >= 18

Install

npm i eyeling

CLI

Run on a file:

npx eyeling examples/socrates.n3

See all options:

npx eyeling --help

log:query output selection

If your input contains one or more top-level directives of the form:

{ ?x a :Human. } log:query { ?x a :Mortal. }.

Eyeling will still compute the saturated forward closure, but it will print only the unique instantiated conclusion triples of those log:query directives (instead of printing all newly derived forward facts).

JavaScript API

CommonJS:

const { reason } = require('eyeling');

const input = `
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix : <http://example.org/socrates#>.

:Socrates a :Human.
:Human rdfs:subClassOf :Mortal.

{ ?S a ?A. ?A rdfs:subClassOf ?B } => { ?S a ?B }.
`;

console.log(reason({ proofComments: false }, input));

ESM:

import eyeling from 'eyeling';
console.log(eyeling.reason({ proofComments: false }, input));

Streaming / in-process reasoning (browser/worker, direct eyeling.js):

const { closureN3 } = eyeling.reasonStream(input, {
  proof: false,
  onDerived: ({ triple }) => console.log(triple),
});

// With log:query directives present, closureN3 contains the query-selected triples.
// The return value also includes `queryMode`, `queryTriples`, and `queryDerived`.

Note: the npm reason() helper shells out to the bundled eyeling.js CLI for simplicity and robustness.

Builtins

Builtins are defined in eyeling-builtins.ttl and described in the HANDBOOK.

Testing (repo checkout)

npm test

License

MIT (see LICENSE).