@sparq-org/eyereasoner-compat

A drop-in migration package for eye-js: the same n3reasoner(data, query?, options?) API, backed by sparq's native Notation3 forward-chaining reasoner compiled to WebAssembly — no SWI-Prolog, and a lighter browser payload. Migrating is a one-line package.json change.

🚀 Quickstart

npm install @sparq-org/eyereasoner-compat

import { n3reasoner } from '@sparq-org/eyereasoner-compat';

const data = `
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix : <http://example.org/socrates#>.
:Socrates a :Human.
:Human rdfs:subClassOf :Mortal.
{?A rdfs:subClassOf ?B. ?S a ?A} => {?S a ?B}.`;

const query = `@prefix : <http://example.org/socrates#>. {:Socrates a ?WHAT} => {:Socrates a ?WHAT}.`;

await n3reasoner(data, query);   // => ":Socrates a :Human, :Mortal" (as N-Triples)
await n3reasoner(data);          // => all inferred (derivations)

The wasm engine ships inside the tarball and loads with no configuration (Node reads it from disk; browsers/CDNs resolve it relative to the module). No network fetch of a hosted asset.

CDN usage (no bundler)

<script type="module">
  import { n3reasoner } from 'https://esm.sh/@sparq-org/eyereasoner-compat';
  console.log(await n3reasoner('@prefix : <http://ex/>. {:a a :A} => {:a a :B}. :a a :A.'));
</script>

Also available via https://cdn.jsdelivr.net/npm/@sparq-org/eyereasoner-compat/+esm and https://unpkg.com/@sparq-org/eyereasoner-compat. If a bundler cannot auto-resolve the wasm, point at it explicitly: import { configureWasm } from '...'; configureWasm(new URL(...)); before the first call.

✨ Features

• n3reasoner — the eye-js drop-in. Same overloads: string/[string,…] → string, Quad[] → Quad[] (RDF/JS), overridable with options.outputType: 'string' | 'quads'. String output is canonical N-Triples (a valid Turtle/N3 subset).

• Output modes (options.output, query-less calls):

  | mode | eye-js flag | sparq backing | status | | --- | --- | --- | --- | | derivations (default) | --pass-only-new | newly-derived triples only | ✅ | | deductive_closure | --pass | full ground closure | ✅ | | none | — | empty result | ✅ | | deductive_closure_plus_rules | --pass-all | — | ❌ throws (deferred) | | grounded_deductive_closure_plus_rules | --pass-all-ground | — | ❌ throws (deferred) |

  The …_plus_rules modes echo the rules into the output; sparq's chainer consumes rules and emits only ground triples, so they fail loudly rather than return a different result set.

• Query filter. A query { premise } => { conclusion } becomes a SPARQL CONSTRUCT over the closure (EYE --query semantics). Combining an explicit output with a query throws, as in eye-js. Query rules using builtins / quoted formulae / lists fail closed (a clear error, never a silently wrong answer) — tracked for a follow-up.

• Builtins coverage (honest). sparq's N3 engine supports a subset of EYE's library: math: (sum, difference, product, quotient, greaterThan, lessThan, equalTo, …), string: (concatenation, contains, startsWith, endsWith, matches, replace, …), list: (member, append, memberCount, first, last, …), time: and log: core. EYE's full builtin library is larger; a rule using an unsupported builtin simply does not fire (and in a query rule it fails closed). See skills/inference/SKILL.md.

• SWIPL/EYE-image surface → migration stubs. SwiplEye, loadEyeImage, loadImage, runQuery, buildQuery, qaQuery, query, queryOnce, executeBasicEyeQuery, linguareasoner, EYE_PVM are re-exported so imports compile, but throw a clear migration error — they are inherently SWI-Prolog-bound and cannot be backed by sparq. The SWIPL / cb options are accepted and warn-and-ignore.

• Lighter payload. The single wasm asset is markedly smaller than eye-js's SWI-Prolog build (swipl-web.wasm + swipl-web.data, ~3.83 MB combined). Reproduce the exact bytes:

  wasm-pack build ../../crates/sparq-reason-wasm --target web --release
  f=../../crates/sparq-reason-wasm/pkg/sparq_reason_wasm_bg.wasm
  echo "raw: $(stat -c%s "$f")  gzip -9: $(gzip -9 -c "$f" | wc -c)"

📚 Learn more

• Reasoning semantics / builtins — skills/inference/SKILL.md.
• The wasm engine — crates/sparq-reason-wasm.
• eye-js — the upstream API this mirrors: https://github.com/eyereasoner/eye-js.
• Contribute — AGENTS.md.

License

MIT.