eyeling 1.15.14 → 1.16.0

package/HANDBOOK.md

@@ -1747,6 +1747,13 @@ The engine’s `reasonStream` API can accept an `onDerived` callback. Each time
 
 This is especially useful in interactive demos (and is the basis of the playground streaming tab).
 
+The same API can now also emit RDF/JS output. When `rdfjs: true` is passed, every `onDerived(...)` payload includes both:
+
+- `triple` — Eyeling’s N3 string form
+- `quad` — the same fact as an RDF/JS default-graph quad
+
+For fully stream-oriented RDF/JS consumers there is also `reasonRdfJs(...)`, which exposes the derived facts as an async iterable of RDF/JS quads.
+
 ---
 
 <a id="ch14"></a>
@@ -1783,22 +1790,35 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 
 `lib/entry.js` exports:
 
-- public APIs: `reasonStream`, `main`, `version`
+- public APIs: `reasonStream`, `reasonRdfJs`, `rdfjs`, `main`, `version`
 - plus a curated set of internals used by the demo (`lex`, `Parser`, `forwardChain`, etc.)
 
+`rdfjs` is a small built-in RDF/JS `DataFactory`, so browser / worker code can construct quads without pulling in another package first.
+
 ### 14.3 `index.js`: the npm API wrapper
 
 The npm `reason(...)` function does something intentionally simple and robust:
 
-- write your N3 input to a temp file
+- normalize the JavaScript input into N3 text
+- write that N3 input to a temp file
 - spawn the bundled CLI (`node eyeling.js ... input.n3`)
 - return stdout (and forward stderr)
 
-This ensures the API matches the CLI perfectly and keeps the public surface small.
+This keeps the observable output identical to the CLI while still allowing richer JS-side inputs.
+
+In particular, the npm API now accepts:
+
+- raw N3 strings
+- RDF/JS fact inputs (`quads`, `facts`, or `dataset`)
+- Eyeling rule objects or full AST bundles like `[prefixes, triples, frules, brules]`
+
+For structured JavaScript input, rules are supplied as current Eyeling `Rule` / `Triple` object graphs or as JSON-serialized `--ast` output with `_type` markers.
+
+If you want to use N3 source text, pass the whole input as a plain N3 string.
 
-One practical implication:
+One practical implication remains:
 
-- if you want _in-process_ access to the engine objects (facts arrays, derived proof objects), use `reasonStream` from the bundle entry rather than the subprocess-based API.
+- if you want _in-process_ access to the engine objects (facts arrays, derived proof objects), use `reasonStream` / `reasonRdfJs` from the bundle entry rather than the subprocess-based API.
 
 ---
 

package/README.md

@@ -99,6 +99,64 @@ Notes:
 - By default, the npm helper keeps output machine-friendly (`proofComments: false`).
 - The npm helper shells out to the bundled `eyeling.js` CLI for simplicity and robustness.
 
+### RDF/JS and Eyeling rule-object interop
+
+The JavaScript APIs now accept three input styles:
+
+1. plain N3 text
+2. RDF/JS facts (`quads`, `facts`, or `dataset`)
+3. Eyeling rule objects / AST bundles (the same shapes you get from `eyeling --ast`)
+
+If you want to use N3 source text, pass the whole input as a plain N3 string.
+
+For RDF/JS facts, the graph must be the default graph. Named-graph quads are rejected.
+
+For structured inputs, `rules` is supplied as current Eyeling rule objects:
+
+```js
+const { reason, rdfjs } = require('eyeling');
+
+const ex = 'http://example.org/';
+
+const rule = {
+  _type: 'Rule',
+  premise: [
+    {
+      _type: 'Triple',
+      s: { _type: 'Var', name: 'x' },
+      p: { _type: 'Iri', value: ex + 'parent' },
+      o: { _type: 'Var', name: 'y' },
+    },
+  ],
+  conclusion: [
+    {
+      _type: 'Triple',
+      s: { _type: 'Var', name: 'x' },
+      p: { _type: 'Iri', value: ex + 'ancestor' },
+      o: { _type: 'Var', name: 'y' },
+    },
+  ],
+  isForward: true,
+  isFuse: false,
+  headBlankLabels: [],
+};
+
+const out = reason(
+  { proofComments: false },
+  {
+    quads: [rdfjs.quad(rdfjs.namedNode(ex + 'alice'), rdfjs.namedNode(ex + 'parent'), rdfjs.namedNode(ex + 'bob'))],
+    rules: [rule],
+  },
+);
+```
+
+You can also pass a full AST bundle directly:
+
+```js
+const ast = [prefixes, triples, forwardRules, backwardRules];
+const out2 = reason({ proofComments: false }, ast);
+```
+
 ### Direct bundle / browser-worker API: `reasonStream()`
 
 For in-process reasoning (browser, worker, or direct use of `eyeling.js`):
@@ -113,6 +171,8 @@ const result = eyeling.reasonStream(input, {
 console.log(result.closureN3);
 ```
 
+`eyeling.js` now also exposes `eyeling.rdfjs` and `eyeling.reasonRdfJs(...)` for RDF/JS workflows.
+
 #### `reasonStream()` output behavior
 
 `closureN3` is also mode-dependent:
@@ -126,8 +186,25 @@ To exclude input facts from the normal-mode closure, pass:
 includeInputFactsInClosure: false;
 ```
 
+When `rdfjs: true` is passed, `onDerived` also receives a `quad` field and the result may include `closureQuads` / `queryQuads`.
+
 The returned object also includes `queryMode`, `queryTriples`, and `queryDerived` (and in normal mode, `onDerived` fires for newly derived facts; in `log:query` mode it fires for the query-selected derived triples).
 
+### `reasonRdfJs()`
+
+`reasonRdfJs(input, opts)` exposes derived results as an async iterable of RDF/JS quads as they are produced:
+
+```js
+const { reasonRdfJs, rdfjs } = require('eyeling');
+
+for await (const quad of reasonRdfJs({
+  quads: [rdfjs.quad(rdfjs.namedNode(ex + 'alice'), rdfjs.namedNode(ex + 'parent'), rdfjs.namedNode(ex + 'bob'))],
+  rules: [rule],
+})) {
+  console.log(quad.subject.value, quad.predicate.value, quad.object.value);
+}
+```
+
 ## Builtins
 
 Builtins are defined in [eyeling-builtins.ttl](https://github.com/eyereasoner/eyeling/blob/main/eyeling-builtins.ttl) and described in the [Handbook (Chapter 11)](https://eyereasoner.github.io/eyeling/HANDBOOK#ch11).