@factoidal/core 0.7.0 → 0.10.0

package/rdfjs.mjs

@@ -0,0 +1,594 @@
+// factoidal — RDF/JS data model + N-Quads token converters.
+//
+// Implements the RDF/JS Data Model specification
+// (https://rdf.js.org/data-model-spec/): DataFactory producing
+// NamedNode / BlankNode / Literal / Variable / DefaultGraph / Quad
+// terms with spec-compliant `termType` / `value` / `language` /
+// `datatype` and `.equals()`. Self-contained — no runtime deps.
+//
+// Also provides converters between RDF/JS quads and the engine's
+// N-Quads token strings, which are the package's dataset interchange
+// handle (the Lean engine parses and serializes N-Quads; the
+// converters below only tokenize/untokenize the engine's own output —
+// full RDF parsing of user input always goes through the engine).
+//
+// ES module (0.9.0): the same file serves Node (index.mjs, and
+// rdfjs.js for require()) and the browser (browser.js), with no build
+// step. On output, \\ \" \n \r \t (and nothing else) are escaped;
+// unescaping additionally accepts the full N-Triples ECHAR + UCHAR set
+// (\t \b \n \r \f \" \' \\ \uXXXX \UXXXXXXXX) since engine input may
+// legally contain them.
+
+const XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string';
+const RDF_LANGSTRING =
+  'http://www.w3.org/1999/02/22-rdf-syntax-ns#langString';
+
+// ---------------------------------------------------------------------
+// Terms
+// ---------------------------------------------------------------------
+
+class NamedNode {
+  constructor(iri) {
+    this.termType = 'NamedNode';
+    this.value = iri;
+    Object.freeze(this);
+  }
+  equals(other) {
+    return !!other && other.termType === 'NamedNode' &&
+      other.value === this.value;
+  }
+}
+
+class BlankNode {
+  constructor(label) {
+    this.termType = 'BlankNode';
+    this.value = label;
+    Object.freeze(this);
+  }
+  equals(other) {
+    return !!other && other.termType === 'BlankNode' &&
+      other.value === this.value;
+  }
+}
+
+class Literal {
+  constructor(value, language, datatype) {
+    this.termType = 'Literal';
+    this.value = value;
+    this.language = language || '';
+    this.datatype = datatype ||
+      new NamedNode(language ? RDF_LANGSTRING : XSD_STRING);
+    Object.freeze(this);
+  }
+  equals(other) {
+    return !!other && other.termType === 'Literal' &&
+      other.value === this.value &&
+      other.language === this.language &&
+      !!other.datatype && other.datatype.value === this.datatype.value;
+  }
+}
+
+class Variable {
+  constructor(name) {
+    this.termType = 'Variable';
+    this.value = name;
+    Object.freeze(this);
+  }
+  equals(other) {
+    return !!other && other.termType === 'Variable' &&
+      other.value === this.value;
+  }
+}
+
+class DefaultGraph {
+  constructor() {
+    this.termType = 'DefaultGraph';
+    this.value = '';
+    Object.freeze(this);
+  }
+  equals(other) {
+    return !!other && other.termType === 'DefaultGraph';
+  }
+}
+
+const DEFAULT_GRAPH = new DefaultGraph();
+
+class Quad {
+  constructor(subject, predicate, object, graph) {
+    // Per spec, a Quad is itself a Term with termType 'Quad', value ''.
+    this.termType = 'Quad';
+    this.value = '';
+    this.subject = subject;
+    this.predicate = predicate;
+    this.object = object;
+    this.graph = graph || DEFAULT_GRAPH;
+    Object.freeze(this);
+  }
+  equals(other) {
+    return !!other &&
+      (other.termType === 'Quad' || other.termType === undefined) &&
+      this.subject.equals(other.subject) &&
+      this.predicate.equals(other.predicate) &&
+      this.object.equals(other.object) &&
+      this.graph.equals(other.graph);
+  }
+}
+
+// ---------------------------------------------------------------------
+// DataFactory
+// ---------------------------------------------------------------------
+
+let blankNodeCounter = 0;
+
+const dataFactory = {
+  namedNode(value) {
+    return new NamedNode(String(value));
+  },
+  blankNode(label) {
+    return new BlankNode(
+      label !== undefined && label !== null
+        ? String(label)
+        : 'fjs_b' + (blankNodeCounter++)
+    );
+  },
+  literal(value, languageOrDatatype) {
+    const v = String(value);
+    if (languageOrDatatype === undefined || languageOrDatatype === null) {
+      return new Literal(v, '', null);
+    }
+    if (typeof languageOrDatatype === 'string') {
+      return new Literal(v, languageOrDatatype, null);
+    }
+    // A NamedNode datatype.
+    if (languageOrDatatype.termType === 'NamedNode') {
+      if (languageOrDatatype.value === RDF_LANGSTRING) {
+        // langString without a language tag is not constructible; treat
+        // as plain string per the most defensive reading of the spec.
+        return new Literal(v, '', null);
+      }
+      return new Literal(v, '', new NamedNode(languageOrDatatype.value));
+    }
+    throw new TypeError(
+      'literal: second argument must be a language string or a NamedNode'
+    );
+  },
+  variable(name) {
+    return new Variable(String(name));
+  },
+  defaultGraph() {
+    return DEFAULT_GRAPH;
+  },
+  quad(subject, predicate, object, graph) {
+    return new Quad(subject, predicate, object, graph);
+  },
+  fromTerm(original) {
+    if (!original || typeof original.termType !== 'string') {
+      throw new TypeError('fromTerm: not a term');
+    }
+    switch (original.termType) {
+      case 'NamedNode':    return new NamedNode(original.value);
+      case 'BlankNode':    return new BlankNode(original.value);
+      case 'Variable':     return new Variable(original.value);
+      case 'DefaultGraph': return DEFAULT_GRAPH;
+      case 'Literal':
+        return new Literal(
+          original.value,
+          original.language || '',
+          original.language
+            ? null
+            : new NamedNode(
+                (original.datatype && original.datatype.value) || XSD_STRING)
+        );
+      case 'Quad':         return dataFactory.fromQuad(original);
+      default:
+        throw new TypeError(`fromTerm: unknown termType '${original.termType}'`);
+    }
+  },
+  fromQuad(original) {
+    if (!original || !original.subject) {
+      throw new TypeError('fromQuad: not a quad');
+    }
+    return new Quad(
+      dataFactory.fromTerm(original.subject),
+      dataFactory.fromTerm(original.predicate),
+      dataFactory.fromTerm(original.object),
+      original.graph ? dataFactory.fromTerm(original.graph) : DEFAULT_GRAPH
+    );
+  },
+};
+
+// ---------------------------------------------------------------------
+// SPARQL Results JSON term -> RDF/JS term
+// ---------------------------------------------------------------------
+
+/**
+ * Convert a SPARQL 1.1 Results JSON term object
+ * ({type:'uri'|'bnode'|'literal'|'typed-literal', value, 'xml:lang',
+ * datatype}) into an RDF/JS term.
+ */
+function termFromSrj(t) {
+  if (!t || typeof t.type !== 'string') {
+    throw new TypeError('termFromSrj: not a results-JSON term');
+  }
+  switch (t.type) {
+    case 'uri':
+      return dataFactory.namedNode(t.value);
+    case 'bnode':
+      return dataFactory.blankNode(t.value);
+    case 'literal':
+    case 'typed-literal': {
+      const lang = t['xml:lang'];
+      if (lang) return dataFactory.literal(t.value, lang);
+      if (t.datatype) {
+        return dataFactory.literal(t.value, dataFactory.namedNode(t.datatype));
+      }
+      return dataFactory.literal(t.value);
+    }
+    case 'triple': {
+      // RDF 1.2 triple term in SPARQL Results JSON:
+      // {"type":"triple","value":{"subject":T,"predicate":T,"object":T}}
+      // (SPARQL_Protocol.json_term) -> an RDF/JS Quad term. Recursive:
+      // the object may itself be a triple term.
+      const v = t.value || {};
+      return dataFactory.quad(
+        termFromSrj(v.subject), termFromSrj(v.predicate), termFromSrj(v.object));
+    }
+    default:
+      throw new TypeError(`termFromSrj: unknown term type '${t.type}'`);
+  }
+}
+
+// ---------------------------------------------------------------------
+// N-Quads token output (mirrors RDF.NQuads.Serialize.escape_char)
+// ---------------------------------------------------------------------
+
+function escapeLiteral(s) {
+  let out = '';
+  for (const ch of s) {
+    switch (ch) {
+      case '\\': out += '\\\\'; break;
+      case '"':  out += '\\"';  break;
+      case '\n': out += '\\n';  break;
+      case '\r': out += '\\r';  break;
+      case '\t': out += '\\t';  break;
+      default:   out += ch;
+    }
+  }
+  return out;
+}
+
+/** Serialize one RDF/JS term to its N-Quads token. */
+function termToNQuads(term) {
+  switch (term.termType) {
+    case 'NamedNode':
+      return '<' + term.value + '>';
+    case 'BlankNode':
+      return '_:' + term.value;
+    case 'Literal': {
+      const body = '"' + escapeLiteral(term.value) + '"';
+      if (term.language) return body + '@' + term.language;
+      if (term.datatype && term.datatype.value !== XSD_STRING) {
+        return body + '^^<' + term.datatype.value + '>';
+      }
+      return body;
+    }
+    case 'DefaultGraph':
+      return '';
+    case 'Quad':
+      // RDF 1.2 triple term -> <<( s p o )>> (matches the engine's
+      // Mode_12 N-Quads serializer, so it round-trips back through the
+      // *12 parse path).
+      return '<<( ' + termToNQuads(term.subject) + ' ' +
+        termToNQuads(term.predicate) + ' ' +
+        termToNQuads(term.object) + ' )>>';
+    default:
+      throw new TypeError(
+        `termToNQuads: cannot serialize termType '${term.termType}'`);
+  }
+}
+
+/** Serialize one RDF/JS quad to an N-Quads line (with trailing " .\n"). */
+function quadToNQuads(quad) {
+  const g = quad.graph && quad.graph.termType !== 'DefaultGraph'
+    ? ' ' + termToNQuads(quad.graph)
+    : '';
+  return termToNQuads(quad.subject) + ' ' +
+    termToNQuads(quad.predicate) + ' ' +
+    termToNQuads(quad.object) + g + ' .\n';
+}
+
+/** Serialize an iterable of quads to an N-Quads document. */
+function quadsToNQuads(quads) {
+  let out = '';
+  for (const q of quads) out += quadToNQuads(q);
+  return out;
+}
+
+// ---------------------------------------------------------------------
+// N-Quads token input.
+//
+// A line tokenizer for the engine's own N-Quads output (and canonical
+// N-Quads generally): one statement per line, terms separated by
+// whitespace, ECHAR/UCHAR escapes inside literals. This is a token
+// reader for a machine-generated regular syntax, not a general RDF
+// parser — user documents in any syntax go through the engine.
+// ---------------------------------------------------------------------
+
+const UNESCAPE_MAP = {
+  't': '\t', 'b': '\b', 'n': '\n', 'r': '\r', 'f': '\f',
+  '"': '"', "'": "'", '\\': '\\',
+};
+
+function unescapeLiteral(s, lineNo) {
+  if (s.indexOf('\\') < 0) return s;
+  let out = '';
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c !== '\\') { out += c; continue; }
+    const e = s[++i];
+    if (e in UNESCAPE_MAP) { out += UNESCAPE_MAP[e]; continue; }
+    if (e === 'u') {
+      out += String.fromCodePoint(parseInt(s.slice(i + 1, i + 5), 16));
+      i += 4;
+      continue;
+    }
+    if (e === 'U') {
+      out += String.fromCodePoint(parseInt(s.slice(i + 1, i + 9), 16));
+      i += 8;
+      continue;
+    }
+    throw new SyntaxError(
+      `N-Quads line ${lineNo}: bad escape '\\${e}'`);
+  }
+  return out;
+}
+
+// Read one term starting at s[i]; returns [term, nextIndex].
+function readTerm(s, i, lineNo, factory) {
+  const c = s[i];
+  // RDF 1.2 triple term: <<( s p o )>> -> an RDF/JS Quad term
+  // (termType 'Quad'). Checked BEFORE the '<' IRI case since a triple
+  // term also opens with '<'. This reads the engine's own Mode_12
+  // N-Quads serializer output (RDF.NQuads.Serialize) into RDF/JS
+  // objects; it is not a conformance parser (that is the F* --rdf12
+  // path) — same interop role the rest of this reader plays.
+  if (c === '<' && s[i + 1] === '<' && s[i + 2] === '(') {
+    let j = skipWs(s, i + 3);
+    const [sub, a] = readTerm(s, j, lineNo, factory); j = skipWs(s, a);
+    const [pred, b] = readTerm(s, j, lineNo, factory); j = skipWs(s, b);
+    const [obj, d] = readTerm(s, j, lineNo, factory); j = skipWs(s, d);
+    if (s[j] === ')' && s[j + 1] === '>' && s[j + 2] === '>') {
+      return [factory.quad(sub, pred, obj), j + 3];
+    }
+    throw new SyntaxError(
+      `N-Quads line ${lineNo}: unterminated triple term (expected ')>>')`);
+  }
+  if (c === '<') {
+    const end = s.indexOf('>', i + 1);
+    if (end < 0) throw new SyntaxError(`N-Quads line ${lineNo}: unclosed IRI`);
+    return [factory.namedNode(s.slice(i + 1, end)), end + 1];
+  }
+  if (c === '_' && s[i + 1] === ':') {
+    let j = i + 2;
+    while (j < s.length && !/\s/.test(s[j])) j++;
+    return [factory.blankNode(s.slice(i + 2, j)), j];
+  }
+  if (c === '"') {
+    // Scan to the closing unescaped quote.
+    let j = i + 1;
+    for (;;) {
+      if (j >= s.length) {
+        throw new SyntaxError(`N-Quads line ${lineNo}: unclosed literal`);
+      }
+      if (s[j] === '\\') { j += 2; continue; }
+      if (s[j] === '"') break;
+      j++;
+    }
+    const lex = unescapeLiteral(s.slice(i + 1, j), lineNo);
+    j++; // past closing quote
+    if (s[j] === '@') {
+      let k = j + 1;
+      while (k < s.length && !/\s/.test(s[k])) k++;
+      return [factory.literal(lex, s.slice(j + 1, k)), k];
+    }
+    if (s[j] === '^' && s[j + 1] === '^' && s[j + 2] === '<') {
+      const end = s.indexOf('>', j + 3);
+      if (end < 0) {
+        throw new SyntaxError(`N-Quads line ${lineNo}: unclosed datatype IRI`);
+      }
+      return [
+        factory.literal(lex, factory.namedNode(s.slice(j + 3, end))),
+        end + 1,
+      ];
+    }
+    return [factory.literal(lex), j];
+  }
+  throw new SyntaxError(
+    `N-Quads line ${lineNo}: unexpected character '${c}' at column ${i + 1}`);
+}
+
+function skipWs(s, i) {
+  while (i < s.length && (s[i] === ' ' || s[i] === '\t')) i++;
+  return i;
+}
+
+/**
+ * Tokenize one N-Quads statement line into an RDF/JS quad.
+ * Returns null for blank/comment lines.
+ */
+function nquadsLineToQuad(line, lineNo, factory) {
+  const f = factory || dataFactory;
+  let i = skipWs(line, 0);
+  if (i >= line.length || line[i] === '#') return null;
+  const terms = [];
+  while (terms.length < 4) {
+    const [term, next] = readTerm(line, i, lineNo, f);
+    terms.push(term);
+    i = skipWs(line, next);
+    if (line[i] === '.') break;
+  }
+  if (line[i] !== '.') {
+    throw new SyntaxError(`N-Quads line ${lineNo}: missing terminating '.'`);
+  }
+  if (terms.length < 3) {
+    throw new SyntaxError(`N-Quads line ${lineNo}: fewer than 3 terms`);
+  }
+  return f.quad(terms[0], terms[1], terms[2], terms[3] || f.defaultGraph());
+}
+
+/**
+ * Tokenize an engine-emitted N-Quads document into RDF/JS quads.
+ *
+ * options.blankNodePrefix — prepended to every blank-node label, used
+ * by parse() to keep labels from separate parse calls distinct (blank
+ * node identity is document-scoped; the prefix is bookkeeping, the
+ * semantic per-document renaming lives in F*
+ * RDF.Dataset.Merge.rename_dataset_bnodes).
+ */
+function nquadsToQuads(text, options) {
+  const opts = options || {};
+  const factory = opts.factory || dataFactory;
+  const f = opts.blankNodePrefix
+    ? {
+        ...factory,
+        blankNode: (label) => factory.blankNode(
+          label === undefined || label === null
+            ? undefined
+            : opts.blankNodePrefix + label),
+      }
+    : factory;
+  const quads = [];
+  const lines = String(text).split('\n');
+  for (let n = 0; n < lines.length; n++) {
+    const q = nquadsLineToQuad(lines[n].replace(/\r$/, ''), n + 1, f);
+    if (q) quads.push(q);
+  }
+  return quads;
+}
+
+// ---------------------------------------------------------------------
+// Dataset — a minimal RDF/JS DatasetCore over an in-memory quad array.
+// ---------------------------------------------------------------------
+
+// A string that two terms share exactly when equals() holds between them
+// (the fields each equals() above compares). JSON arrays are
+// self-delimiting, so the key of a quad, four term keys in a row, is
+// injective too. The Dataset keeps the keys of its quads in a Set: add()
+// and has() are then one lookup each. Until 2026-10-10 both scanned the
+// quad array, so building a Dataset of n quads cost n^2/2 equals() calls:
+// 12,000 quads took 3.1 s in parse() (issue 713 stage 5).
+function termKey(t) {
+  if (!t) return 'null';
+  switch (t.termType) {
+    case 'Literal':
+      return JSON.stringify(['Literal', t.value, t.language, t.datatype ? t.datatype.value : null]);
+    case 'DefaultGraph':
+      return '["DefaultGraph"]';
+    case 'Quad':
+      return '["Quad",' + termKey(t.subject) + ',' + termKey(t.predicate) + ',' +
+        termKey(t.object) + ',' + termKey(t.graph) + ']';
+    default:
+      return JSON.stringify([t.termType, t.value]);
+  }
+}
+
+function quadKey(q) {
+  return termKey(q.subject) + termKey(q.predicate) + termKey(q.object) +
+    termKey(q.graph || DEFAULT_GRAPH);
+}
+
+/**
+ * An in-memory RDF/JS DatasetCore over a quad array. The package's Dataset
+ * (lib/dataset.mjs) keeps its data in the engine; this class is for callers
+ * that build quads in JavaScript, for example to hand to fn.js.
+ */
+class DatasetCore {
+  constructor(quads, options) {
+    this._quads = [];
+    // The quadKey() of every quad in _quads, for set semantics in O(1).
+    this._keys = new Set();
+    if (quads) for (const q of quads) this.add(q);
+    const opts = options || {};
+    // Own, non-enumerable properties (issue #680/#681): a frozen
+    // snapshot of the prefixes/diagnostics the engine reported at
+    // parse time, so JSON.stringify()/toArray() (and any caller
+    // enumerating own enumerable keys) see only the quads, exactly as
+    // before this landed.
+    Object.defineProperty(this, 'prefixes', {
+      value: Object.freeze({ ...(opts.prefixes || {}) }),
+      enumerable: false, writable: false, configurable: false,
+    });
+    Object.defineProperty(this, 'diagnostics', {
+      value: Object.freeze((opts.diagnostics || []).slice()),
+      enumerable: false, writable: false, configurable: false,
+    });
+  }
+  get size() {
+    return this._quads.length;
+  }
+  add(quad) {
+    const key = quadKey(quad);
+    if (!this._keys.has(key)) {
+      this._keys.add(key);
+      this._quads.push(quad);
+    }
+    return this;
+  }
+  delete(quad) {
+    if (this._keys.delete(quadKey(quad))) {
+      const ix = this._quads.findIndex((q) => q.equals(quad));
+      if (ix >= 0) this._quads.splice(ix, 1);
+    }
+    return this;
+  }
+  has(quad) {
+    return this._keys.has(quadKey(quad));
+  }
+  match(subject, predicate, object, graph) {
+    const out = new DatasetCore();
+    for (const q of this._quads) {
+      if (subject   && !subject.equals(q.subject))     continue;
+      if (predicate && !predicate.equals(q.predicate)) continue;
+      if (object    && !object.equals(q.object))       continue;
+      if (graph     && !graph.equals(q.graph))         continue;
+      out._quads.push(q);
+      out._keys.add(quadKey(q));
+    }
+    return out;
+  }
+  [Symbol.iterator]() {
+    return this._quads[Symbol.iterator]();
+  }
+  toArray() {
+    return this._quads.slice();
+  }
+  /** N-Quads text — the engine interchange handle. */
+  toNQuads() {
+    return quadsToNQuads(this._quads);
+  }
+  toString() {
+    return this.toNQuads();
+  }
+  static fromNQuads(text, options) {
+    return new DatasetCore(nquadsToQuads(text, options), options);
+  }
+}
+
+export {
+  dataFactory,
+  NamedNode,
+  BlankNode,
+  Literal,
+  Variable,
+  DefaultGraph,
+  Quad,
+  DatasetCore,
+  termFromSrj,
+  nquadsLineToQuad,
+  termToNQuads,
+  quadToNQuads,
+  quadsToNQuads,
+  nquadsToQuads,
+  XSD_STRING,
+  RDF_LANGSTRING,
+}

package/sample-store.d.ts

@@ -1,16 +1,8 @@
-/** The collection root of the sample Shardborough store bundled with this
- * package: the directory that holds CURRENT. */
-export declare function sampleStorePath (): string
-
-export declare const sampleStoreFacts: Readonly<{
-  triples: number
-  blocks: number
-  layout: string
-  wireVersion: number
-  source: string
-  licence: string
-  licenceUrl: string
-  publisher: string
-}>
-
-export default sampleStorePath
+// @factoidal/core/sample-store (Node only): a small store packed on demand.
+/** The triples of the sample store, as Turtle. */
+export const SAMPLE_TURTLE: string;
+/** What the sample store holds. */
+export const sampleStoreFacts: Readonly<{ triples: number; source: string; layout: string }>;
+/** Pack the sample store under `dir` (or a new temporary directory) unless it holds CURRENT; return the root. */
+export function sampleStorePath(dir?: string): string;
+export default sampleStorePath;