eyeling 1.7.20 → 1.8.0

package/README.md

@@ -122,6 +122,7 @@ Options:
   -a, --ast               Print parsed AST as JSON and exit.
   --strings               Print log:outputString strings (ordered by key) instead of N3 output.
   --enforce-https         Rewrite http:// IRIs to https:// for log dereferencing builtins.
+  --stream                Stream derived triples as soon as they are derived.
 ```
 
 By default, `eyeling`:

package/eyeling.js

@@ -111,9 +111,7 @@ let enforceHttpsEnabled = false;
 
 function __maybeEnforceHttps(iri) {
   if (!enforceHttpsEnabled) return iri;
-  return typeof iri === 'string' && iri.startsWith('http://')
-    ? 'https://' + iri.slice('http://'.length)
-    : iri;
+  return typeof iri === 'string' && iri.startsWith('http://') ? 'https://' + iri.slice('http://'.length) : iri;
 }
 
 // Environment detection (Node vs Browser/Worker).
@@ -427,12 +425,7 @@ let __tracePrefixes = null;
 function __traceWriteLine(line) {
   // Prefer stderr in Node, fall back to console.error elsewhere.
   try {
-    if (
-      __IS_NODE &&
-      typeof process !== 'undefined' &&
-      process.stderr &&
-      typeof process.stderr.write === 'function'
-    ) {
+    if (__IS_NODE && typeof process !== 'undefined' && process.stderr && typeof process.stderr.write === 'function') {
       process.stderr.write(String(line) + '\n');
       return;
     }
@@ -3109,7 +3102,6 @@ function termToJsString(t) {
   return typeof lex === 'string' ? lex : String(lex);
 }
 
-
 function makeStringLiteral(str) {
   // JSON.stringify gives us a valid N3/Turtle-style quoted string
   // (with proper escaping for quotes, backslashes, newlines, …).
@@ -3757,19 +3749,37 @@ function __tfnFormatYear(y) {
 
 function __tfnAdd1ms(c) {
   // Mutates and returns c; c: {year,month,day,hour,minute,second,millis}
-  if (c.millis < 999) { c.millis++; return c; }
+  if (c.millis < 999) {
+    c.millis++;
+    return c;
+  }
   c.millis = 0;
-  if (c.second < 59) { c.second++; return c; }
+  if (c.second < 59) {
+    c.second++;
+    return c;
+  }
   c.second = 0;
-  if (c.minute < 59) { c.minute++; return c; }
+  if (c.minute < 59) {
+    c.minute++;
+    return c;
+  }
   c.minute = 0;
-  if (c.hour < 23) { c.hour++; return c; }
+  if (c.hour < 23) {
+    c.hour++;
+    return c;
+  }
   c.hour = 0;
 
   const dim = __tfnDaysInMonth(c.year, c.month);
-  if (c.day < dim) { c.day++; return c; }
+  if (c.day < dim) {
+    c.day++;
+    return c;
+  }
   c.day = 1;
-  if (c.month < 12) { c.month++; return c; }
+  if (c.month < 12) {
+    c.month++;
+    return c;
+  }
   c.month = 1;
   c.year = c.year + 1n;
   return c;
@@ -3777,16 +3787,31 @@ function __tfnAdd1ms(c) {
 
 function __tfnSub1ms(c) {
   // Mutates and returns c; c: {year,month,day,hour,minute,second,millis}
-  if (c.millis > 0) { c.millis--; return c; }
+  if (c.millis > 0) {
+    c.millis--;
+    return c;
+  }
   c.millis = 999;
-  if (c.second > 0) { c.second--; return c; }
+  if (c.second > 0) {
+    c.second--;
+    return c;
+  }
   c.second = 59;
-  if (c.minute > 0) { c.minute--; return c; }
+  if (c.minute > 0) {
+    c.minute--;
+    return c;
+  }
   c.minute = 59;
-  if (c.hour > 0) { c.hour--; return c; }
+  if (c.hour > 0) {
+    c.hour--;
+    return c;
+  }
   c.hour = 23;
 
-  if (c.day > 1) { c.day--; return c; }
+  if (c.day > 1) {
+    c.day--;
+    return c;
+  }
   // move to previous month
   if (c.month > 1) {
     c.month--;
@@ -3824,7 +3849,15 @@ function __tfnComputePeriodBounds(parts) {
 
   if (parts.kind === 'date') {
     const startC = { year: parts.year, month: parts.month, day: parts.day, hour: 0, minute: 0, second: 0, millis: 0 };
-    const endC = { year: parts.year, month: parts.month, day: parts.day, hour: 23, minute: 59, second: 59, millis: 999 };
+    const endC = {
+      year: parts.year,
+      month: parts.month,
+      day: parts.day,
+      hour: 23,
+      minute: 59,
+      second: 59,
+      millis: 999,
+    };
     return { tzMin, tzMax, startC, endC };
   }
 
@@ -3857,12 +3890,8 @@ function __tfnBindDefaultTimezone(timeLit, tzLit) {
   if (__tfnHasTimezoneSuffix(v)) return timeLit;
 
   // Only support the temporal types we parse.
-  if (
-    dt !== XSD_NS + 'dateTime' &&
-    dt !== XSD_NS + 'date' &&
-    dt !== XSD_NS + 'gYearMonth' &&
-    dt !== XSD_NS + 'gYear'
-  ) return null;
+  if (dt !== XSD_NS + 'dateTime' && dt !== XSD_NS + 'date' && dt !== XSD_NS + 'gYearMonth' && dt !== XSD_NS + 'gYear')
+    return null;
 
   const outLex = `"${v}${tz}"^^<${dt}>`;
   return internLiteral(outLex);
@@ -5163,72 +5192,73 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return [];
   }
 
-// -----------------------------------------------------------------
-// 4.3.1 tfn: Time Functions builtins
-// -----------------------------------------------------------------
-
-// tfn:periodMinInclusive / periodMaxInclusive / periodMinExclusive / periodMaxExclusive
-// Schema: ( $s.1+ )+ tfn:* $o-
-const tfnPeriodKind =
-  pv === TFN_NS + 'periodMinInclusive'
-    ? 'minInc'
-    : pv === TFN_NS + 'periodMaxInclusive'
-      ? 'maxInc'
-      : pv === TFN_NS + 'periodMinExclusive'
-        ? 'minEx'
-        : pv === TFN_NS + 'periodMaxExclusive'
-          ? 'maxEx'
-          : null;
-if (tfnPeriodKind) {
-  if (!(g.s instanceof ListTerm) || g.s.elems.length !== 1) return [];
-  const arg = g.s.elems[0];
-  const parts = __tfnParseTemporalLiteralParts(arg);
-  if (!parts) return [];
-  const bounds = __tfnComputePeriodBounds(parts);
-  if (!bounds) return [];
-
-  let out;
-  if (tfnPeriodKind === 'minInc') {
-    out = __tfnMakeDateTimeLiteral({ ...bounds.startC }, bounds.tzMin);
-  } else if (tfnPeriodKind === 'maxInc') {
-    out = __tfnMakeDateTimeLiteral({ ...bounds.endC }, bounds.tzMax);
-  } else if (tfnPeriodKind === 'minEx') {
-    const c = __tfnSub1ms({ ...bounds.startC });
-    out = __tfnMakeDateTimeLiteral(c, bounds.tzMin);
-  } else { // maxEx
-    const c = __tfnAdd1ms({ ...bounds.endC });
-    out = __tfnMakeDateTimeLiteral(c, bounds.tzMax);
-  }
+  // -----------------------------------------------------------------
+  // 4.3.1 tfn: Time Functions builtins
+  // -----------------------------------------------------------------
 
-  if (g.o instanceof Var) {
-    const s2 = { ...subst };
-    s2[g.o.name] = out;
-    return [s2];
+  // tfn:periodMinInclusive / periodMaxInclusive / periodMinExclusive / periodMaxExclusive
+  // Schema: ( $s.1+ )+ tfn:* $o-
+  const tfnPeriodKind =
+    pv === TFN_NS + 'periodMinInclusive'
+      ? 'minInc'
+      : pv === TFN_NS + 'periodMaxInclusive'
+        ? 'maxInc'
+        : pv === TFN_NS + 'periodMinExclusive'
+          ? 'minEx'
+          : pv === TFN_NS + 'periodMaxExclusive'
+            ? 'maxEx'
+            : null;
+  if (tfnPeriodKind) {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 1) return [];
+    const arg = g.s.elems[0];
+    const parts = __tfnParseTemporalLiteralParts(arg);
+    if (!parts) return [];
+    const bounds = __tfnComputePeriodBounds(parts);
+    if (!bounds) return [];
+
+    let out;
+    if (tfnPeriodKind === 'minInc') {
+      out = __tfnMakeDateTimeLiteral({ ...bounds.startC }, bounds.tzMin);
+    } else if (tfnPeriodKind === 'maxInc') {
+      out = __tfnMakeDateTimeLiteral({ ...bounds.endC }, bounds.tzMax);
+    } else if (tfnPeriodKind === 'minEx') {
+      const c = __tfnSub1ms({ ...bounds.startC });
+      out = __tfnMakeDateTimeLiteral(c, bounds.tzMin);
+    } else {
+      // maxEx
+      const c = __tfnAdd1ms({ ...bounds.endC });
+      out = __tfnMakeDateTimeLiteral(c, bounds.tzMax);
+    }
+
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = out;
+      return [s2];
+    }
+    if (g.o instanceof Blank) return [{ ...subst }];
+
+    const s2 = unifyTerm(g.o, out, subst);
+    return s2 !== null ? [s2] : [];
   }
-  if (g.o instanceof Blank) return [{ ...subst }];
 
-  const s2 = unifyTerm(g.o, out, subst);
-  return s2 !== null ? [s2] : [];
-}
+  // tfn:bindDefaultTimezone
+  // Schema: ( $s.1+ $s.2+ )+ tfn:bindDefaultTimezone $o-
+  if (pv === TFN_NS + 'bindDefaultTimezone') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 2) return [];
+    const [timeLit, tzLit] = g.s.elems;
+    const out = __tfnBindDefaultTimezone(timeLit, tzLit);
+    if (!out) return [];
 
-// tfn:bindDefaultTimezone
-// Schema: ( $s.1+ $s.2+ )+ tfn:bindDefaultTimezone $o-
-if (pv === TFN_NS + 'bindDefaultTimezone') {
-  if (!(g.s instanceof ListTerm) || g.s.elems.length !== 2) return [];
-  const [timeLit, tzLit] = g.s.elems;
-  const out = __tfnBindDefaultTimezone(timeLit, tzLit);
-  if (!out) return [];
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = out;
+      return [s2];
+    }
+    if (g.o instanceof Blank) return [{ ...subst }];
 
-  if (g.o instanceof Var) {
-    const s2 = { ...subst };
-    s2[g.o.name] = out;
-    return [s2];
+    const s2 = unifyTerm(g.o, out, subst);
+    return s2 !== null ? [s2] : [];
   }
-  if (g.o instanceof Blank) return [{ ...subst }];
-
-  const s2 = unifyTerm(g.o, out, subst);
-  return s2 !== null ? [s2] : [];
-}
 
   // -----------------------------------------------------------------
   // 4.4 list: builtins
@@ -6879,7 +6909,7 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
           if (allKnown) continue;
         }
 
-        const maxSols = (r.isFuse || headIsStrictGround) ? 1 : undefined;
+        const maxSols = r.isFuse || headIsStrictGround ? 1 : undefined;
         const sols = proveGoals(r.premise.slice(), empty, facts, backRules, 0, visited, varGen, maxSols);
 
         // Inference fuse
@@ -7413,7 +7443,8 @@ function main() {
       `  -s, --super-restricted  Disable all builtins except => and <=.\n` +
       `  -a, --ast               Print parsed AST as JSON and exit.\n` +
       `  --strings               Print log:outputString strings (ordered by key) instead of N3 output.\n` +
-      `  --enforce-https         Rewrite http:// IRIs to https:// for log dereferencing builtins.\n`;
+      `  --enforce-https         Rewrite http:// IRIs to https:// for log dereferencing builtins.\n` +
+      `  --stream                Stream derived triples as soon as they are derived.\n`;
     (toStderr ? console.error : console.log)(msg);
   }
 
@@ -7435,6 +7466,7 @@ function main() {
   const showAst = argv.includes('--ast') || argv.includes('-a');
 
   const outputStringsMode = argv.includes('--strings');
+  const streamMode = argv.includes('--stream');
 
   // --enforce-https: rewrite http:// -> https:// for log dereferencing builtins
   if (argv.includes('--enforce-https')) {
@@ -7517,13 +7549,133 @@ function main() {
   materializeRdfLists(triples, frules, brules);
 
   const facts = triples.filter((tr) => isGroundTriple(tr));
-  const derived = forwardChain(facts, frules, brules);
+
   // If requested, print log:outputString values (ordered by subject key) and exit.
+  // Note: log:outputString values may depend on derived facts, so we must saturate first.
   if (outputStringsMode) {
+    forwardChain(facts, frules, brules);
     const out = __collectOutputStringsFromFacts(facts, prefixes);
     if (out) process.stdout.write(out);
     process.exit(0);
   }
+
+  // In --stream mode we print prefixes *before* any derivations happen.
+  // To keep the header small and stable, emit only prefixes that are actually
+  // used (as QNames) in the *input* N3 program.
+  function prefixesUsedInInputTokens(toks2, prefEnv) {
+    const used = new Set();
+
+    function maybeAddFromQName(name) {
+      if (typeof name !== 'string') return;
+      if (!name.includes(':')) return;
+      if (name.startsWith('_:')) return; // blank node
+
+      // Split only on the first ':'
+      const idx = name.indexOf(':');
+      const p = name.slice(0, idx); // may be '' for ":foo"
+
+      // Ignore things like "http://..." unless that prefix is actually defined.
+      if (!Object.prototype.hasOwnProperty.call(prefEnv.map, p)) return;
+
+      used.add(p);
+    }
+
+    for (let i = 0; i < toks2.length; i++) {
+      const t = toks2[i];
+
+      // Skip @prefix ... .
+      if (t.typ === 'AtPrefix') {
+        // @prefix <pfx:> <iri> .
+        // We skip the directive itself so declared-but-unused prefixes don't count.
+        // Advance until we pass the terminating dot (if present).
+        while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
+        continue;
+      }
+      // Skip @base ... .
+      if (t.typ === 'AtBase') {
+        while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
+        continue;
+      }
+
+      // Skip SPARQL/Turtle PREFIX pfx: <iri>
+      if (
+        t.typ === 'Ident' &&
+        typeof t.value === 'string' &&
+        t.value.toLowerCase() === 'prefix' &&
+        toks2[i + 1] &&
+        toks2[i + 1].typ === 'Ident' &&
+        typeof toks2[i + 1].value === 'string' &&
+        toks2[i + 1].value.endsWith(':') &&
+        toks2[i + 2] &&
+        (toks2[i + 2].typ === 'IriRef' || toks2[i + 2].typ === 'Ident')
+      ) {
+        // Consume PREFIX <pfx:> <iri>
+        i += 2;
+        continue;
+      }
+      // Skip SPARQL BASE <iri>
+      if (
+        t.typ === 'Ident' &&
+        typeof t.value === 'string' &&
+        t.value.toLowerCase() === 'base' &&
+        toks2[i + 1] &&
+        toks2[i + 1].typ === 'IriRef'
+      ) {
+        i += 1;
+        continue;
+      }
+
+      // Count QNames in identifiers (including datatypes like xsd:integer).
+      if (t.typ === 'Ident') {
+        maybeAddFromQName(t.value);
+      }
+    }
+
+    return used;
+  }
+
+  function restrictPrefixEnv(prefEnv, usedSet) {
+    const m = {};
+    for (const p of usedSet) {
+      if (Object.prototype.hasOwnProperty.call(prefEnv.map, p)) {
+        m[p] = prefEnv.map[p];
+      }
+    }
+    return new PrefixEnv(m, prefEnv.baseIri || '');
+  }
+
+  // Streaming mode: print (input) prefixes first, then print derived triples as soon as they are found.
+  if (streamMode) {
+    const usedInInput = prefixesUsedInInputTokens(toks, prefixes);
+    const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
+
+    // Ensure log:trace uses the same compact prefix set as the output.
+    __tracePrefixes = outPrefixes;
+
+    const entries = Object.entries(outPrefixes.map)
+      .filter(([_p, base]) => !!base)
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+
+    for (const [pfx, base] of entries) {
+      if (pfx === '') console.log(`@prefix : <${base}> .`);
+      else console.log(`@prefix ${pfx}: <${base}> .`);
+    }
+    if (entries.length) console.log();
+
+    forwardChain(facts, frules, brules, (df) => {
+      if (proofCommentsEnabled) {
+        printExplanation(df, outPrefixes);
+        console.log(tripleToN3(df.fact, outPrefixes));
+        console.log();
+      } else {
+        console.log(tripleToN3(df.fact, outPrefixes));
+      }
+    });
+    return;
+  }
+
+  // Default (non-streaming): derive everything first, then print only the newly derived facts.
+  const derived = forwardChain(facts, frules, brules);
   const derivedTriples = derived.map((df) => df.fact);
   const usedPrefixes = prefixes.prefixesUsedForOutput(derivedTriples);
 

package/index.js

@@ -22,7 +22,11 @@ function reason(opt = {}, n3_input = '') {
   const proofCommentsSpecified = typeof opt.proofComments === 'boolean' || typeof opt.noProofComments === 'boolean';
 
   const proofComments =
-    typeof opt.proofComments === 'boolean' ? opt.proofComments : typeof opt.noProofComments === 'boolean' ? !opt.noProofComments : false;
+    typeof opt.proofComments === 'boolean'
+      ? opt.proofComments
+      : typeof opt.noProofComments === 'boolean'
+        ? !opt.noProofComments
+        : false;
 
   // Only pass a flag when the caller explicitly asked.
   // (CLI default is now: no proof comments.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.7.20",
+  "version": "1.8.0",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [

package/test/api.test.js

@@ -2,6 +2,9 @@
 
 const assert = require('node:assert/strict');
 const { reason } = require('..');
+// Direct eyeling.js API (in-process) for testing reasonStream/onDerived.
+// This is the "latest eyeling.js" surface and is used by the browser demo.
+const { reasonStream } = require('../eyeling.js');
 
 const TTY = process.stdout.isTTY;
 const C = TTY ? { g: '\x1b[32m', r: '\x1b[31m', y: '\x1b[33m', dim: '\x1b[2m', n: '\x1b[0m' } : { g: '', r: '', y: '', dim: '', n: '' };
@@ -687,6 +690,104 @@ _:l2 rdf:rest rdf:nil.
       new RegExp(`${EX}s>\\s+<${EX}q3>\\s+<${EX}b>\\s*\\.`),
     ],
   },
+
+  // -------------------------
+  // Newer eyeling.js features
+  // -------------------------
+
+  {
+    name: '51 --strings: prints log:outputString values ordered by key (subject)',
+    opt: ['--strings', '-n'],
+    input: `@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+<http://example.org/2> log:outputString "B".
+<http://example.org/1> log:outputString "A".
+`,
+    // CLI prints concatenated strings and exits.
+    check(out) {
+      assert.equal(String(out).trimEnd(), 'AB');
+    },
+  },
+
+  {
+    name: '52 --ast: prints parse result as JSON array [prefixes, triples, frules, brules]',
+    opt: ['--ast'],
+    input: `@prefix ex: <http://example.org/>.
+ex:s ex:p ex:o.
+`,
+    expect: [/^\s*\[/m],
+    check(out) {
+      const v = JSON.parse(String(out));
+      assert.ok(Array.isArray(v), 'AST output should be a JSON array');
+      assert.equal(v.length, 4, 'AST output should have 4 top-level elements');
+      // The second element is the parsed triples array.
+      assert.ok(Array.isArray(v[1]), 'AST[1] (triples) should be an array');
+    },
+  },
+
+  {
+    name: '53 --stream: prints prefixes used in input (not just derived output) before streaming triples',
+    opt: ['--stream', '-n'],
+    input: `@prefix ex: <http://example.org/>.
+@prefix p: <http://premise.example/>.
+@prefix unused: <http://unused.example/>.
+
+ex:a p:trig ex:b.
+{ ?s p:trig ?o. } => { ?s ex:q ?o. }.
+`,
+    expect: [
+      /@prefix\s+ex:\s+<http:\/\/example\.org\/>\s*\./m,
+      /@prefix\s+p:\s+<http:\/\/premise\.example\/>\s*\./m,
+      /(?:ex:a|<http:\/\/example\.org\/a>)\s+(?:ex:q|<http:\/\/example\.org\/q>)\s+(?:ex:b|<http:\/\/example\.org\/b>)\s*\./m,
+    ],
+    notExpect: [/@prefix\s+unused:/m, /^#/m],
+    check(out) {
+      const lines = String(out).split(/\r?\n/);
+      const firstNonPrefix = lines.findIndex((l) => {
+        const t = l.trim();
+        return t && !t.startsWith('@prefix');
+      });
+      assert.ok(firstNonPrefix > 0, 'Expected at least one @prefix line before the first triple');
+      for (let i = 0; i < firstNonPrefix; i++) {
+        const t = lines[i].trim();
+        if (!t) continue;
+        assert.ok(t.startsWith('@prefix'), `Non-prefix line found before first triple: ${lines[i]}`);
+      }
+    },
+  },
+
+  {
+    name: '54 reasonStream: onDerived callback fires and includeInputFactsInClosure=false excludes input facts',
+    run() {
+      const input = `
+{ <http://example.org/s> <http://example.org/p> <http://example.org/o>. }
+  => { <http://example.org/s> <http://example.org/q> <http://example.org/o>. }.
+
+<http://example.org/s> <http://example.org/p> <http://example.org/o>.
+`;
+
+      const seen = [];
+      const r = reasonStream(input, {
+        proof: false,
+        includeInputFactsInClosure: false,
+        onDerived: ({ triple }) => seen.push(triple),
+      });
+
+      // stash for check()
+      this._seen = seen;
+      this._result = r;
+      return r.closureN3;
+    },
+    expect: [/http:\/\/example\.org\/q/m],
+    notExpect: [/http:\/\/example\.org\/p/m],
+    check(out, tc) {
+      assert.equal(tc._seen.length, 1, 'Expected onDerived to be called once');
+      assert.match(tc._seen[0], /http:\/\/example\.org\/q/, 'Expected streamed triple to be the derived one');
+      // closureN3 should be exactly the derived triple (no input facts).
+      assert.ok(String(out).trim().includes('http://example.org/q'));
+      assert.ok(!String(out).includes('http://example.org/p'));
+    },
+  },
 ];
 
 let passed = 0;
@@ -699,7 +800,7 @@ let failed = 0;
   for (const tc of cases) {
     const start = msNow();
     try {
-      const out = reason(tc.opt, tc.input);
+      const out = typeof tc.run === 'function' ? await tc.run() : reason(tc.opt, tc.input);
 
       if (tc.expectErrorCode != null || tc.expectError) {
         throw new Error(`Expected an error, but reason() returned output:\n${out}`);
@@ -708,7 +809,7 @@ let failed = 0;
       for (const re of tc.expect || []) mustMatch(out, re, `${tc.name}: missing expected pattern ${re}`);
       for (const re of tc.notExpect || []) mustNotMatch(out, re, `${tc.name}: unexpected pattern ${re}`);
 
-      if (typeof tc.check === 'function') tc.check(out);
+      if (typeof tc.check === 'function') tc.check(out, tc);
 
       const dur = msNow() - start;
       ok(`${tc.name} ${C.dim}(${dur} ms)${C.n}`);