n3.js-messages 0.1.0

package/lib/formats.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.baseVersion = baseVersion;
+exports.isMessagesVersion = isMessagesVersion;
+exports.isSupportedVersion = isSupportedVersion;
+exports.resolveFormat = resolveFormat;
+// **formats** describes the RDF syntaxes that support RDF Messages.
+
+const FORMATS = {
+  turtle: {
+    name: 'Turtle',
+    lineMode: false
+  },
+  trig: {
+    name: 'TriG',
+    lineMode: false
+  },
+  ntriples: {
+    name: 'N-Triples',
+    lineMode: true
+  },
+  nquads: {
+    name: 'N-Quads',
+    lineMode: true
+  }
+};
+
+// The version labels of RDF 1.2 syntaxes, as accepted by N3.js
+const BASE_VERSIONS = ['1.2', '1.2-basic', '1.1'];
+
+// ### `resolveFormat` maps a format name or media type to a supported syntax
+function resolveFormat(format = 'TriG') {
+  const key = String(format).toLowerCase().split(';')[0].trim().replace(/^(?:text|application)\//, '').replace(/^x-/, '').replace(/[-_ ]/g, '');
+  const resolved = FORMATS[key];
+  if (!resolved) throw new TypeError(`Unsupported RDF Messages format: "${format}". ` + 'Supported formats are Turtle, TriG, N-Triples and N-Quads.');
+  return resolved;
+}
+
+// ### `isMessagesVersion` checks whether a version label announces RDF Messages
+function isMessagesVersion(version) {
+  return typeof version === 'string' && version.endsWith('-messages');
+}
+
+// ### `baseVersion` strips the `-messages` suffix of a version label
+function baseVersion(version) {
+  return isMessagesVersion(version) ? version.slice(0, -'-messages'.length) : version;
+}
+
+// ### `isSupportedVersion` checks whether a (base) version label is supported
+function isSupportedVersion(version, supported = BASE_VERSIONS) {
+  return supported.includes(version);
+}

package/lib/index.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "MessageParser", {
+  enumerable: true,
+  get: function () {
+    return _MessageParser.default;
+  }
+});
+Object.defineProperty(exports, "MessageStreamParser", {
+  enumerable: true,
+  get: function () {
+    return _MessageStreamParser.default;
+  }
+});
+Object.defineProperty(exports, "MessageStreamWriter", {
+  enumerable: true,
+  get: function () {
+    return _MessageStreamWriter.default;
+  }
+});
+Object.defineProperty(exports, "MessageWriter", {
+  enumerable: true,
+  get: function () {
+    return _MessageWriter.default;
+  }
+});
+Object.defineProperty(exports, "parseMessages", {
+  enumerable: true,
+  get: function () {
+    return _MessageParser.parseMessages;
+  }
+});
+Object.defineProperty(exports, "writeMessages", {
+  enumerable: true,
+  get: function () {
+    return _MessageWriter.writeMessages;
+  }
+});
+var _MessageParser = _interopRequireWildcard(require("./MessageParser.js"));
+var _MessageStreamParser = _interopRequireDefault(require("./MessageStreamParser.js"));
+var _MessageWriter = _interopRequireWildcard(require("./MessageWriter.js"));
+var _MessageStreamWriter = _interopRequireDefault(require("./MessageStreamWriter.js"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }

package/lib/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "n3.js-messages",
+  "version": "0.1.0",
+  "description": "RDF Messages (message-delimited Turtle, TriG, N-Triples and N-Quads) for N3.js: message-aware parser, streaming parser and writer.",
+  "author": "Pieter Colpaert",
+  "license": "MIT",
+  "keywords": [
+    "rdf",
+    "rdf-messages",
+    "n3",
+    "turtle",
+    "trig",
+    "n-triples",
+    "n-quads",
+    "streaming",
+    "rdfjs"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "require": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "lib",
+    "index.d.ts"
+  ],
+  "peerDependencies": {
+    "n3": ">=2.0.0 <3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pietercolpaert/n3.js-messages.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pietercolpaert/n3.js-messages/issues"
+  },
+  "homepage": "https://github.com/pietercolpaert/n3.js-messages#readme",
+  "scripts": {
+    "build": "babel src -d lib --copy-files --no-copy-ignored && node scripts/write-lib-package.js",
+    "prepack": "npm run build",
+    "test": "jest",
+    "coverage": "jest --coverage",
+    "lint": "eslint src test spec perf scripts",
+    "test:spec": "node spec/runner.js",
+    "test:spec:earl": "node spec/runner.js --earl > spec/earl-report.ttl",
+    "test:types": "tsc -p test/types/tsconfig.json",
+    "test:package": "node scripts/test-package.js",
+    "perf": "node perf/run.js",
+    "perf:compare": "node perf/compare.js",
+    "spec:update": "node scripts/update-spec.js"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.29.7",
+    "@babel/core": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
+    "@types/n3": "^1.26.4",
+    "@types/node": "^26.6.4",
+    "babel-jest": "^30.5.2",
+    "eslint": "^10.12.0",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-jest": "^29.16.6",
+    "globals": "^17.13.0",
+    "jest": "^30.5.2",
+    "n3": "^2.10.6",
+    "rdf-isomorphic": "^2.0.1",
+    "rdf-parser-ts": "^0.4.0",
+    "rdf-writer-ts": "^0.2.1",
+    "typescript": "^6.0.3"
+  },
+  "jest": {
+    "testMatch": [
+      "**/test/**/*-test.js"
+    ],
+    "collectCoverage": true,
+    "collectCoverageFrom": [
+      "src/**/*.js"
+    ],
+    "coverageReporters": [
+      "json-summary",
+      "text",
+      "lcov"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 100,
+        "functions": 100,
+        "lines": 100,
+        "statements": 100
+      }
+    }
+  },
+  "dependencies": {
+    "@rdfjs/types": "^2.0.1"
+  }
+}

package/src/MessageParser.js

@@ -0,0 +1,71 @@
+// **MessageParser** parses RDF Message Logs (Turtle, TriG, N-Triples and N-Quads).
+import { StringDecoder } from 'string_decoder';
+import MessageParserCore from './MessageParserCore.js';
+
+export default class MessageParser {
+  constructor(options) {
+    this._options = options || {};
+    // Fail early on unsupported options
+    this._createCore({});
+  }
+
+  _createCore(sink) {
+    return new MessageParserCore(this._options, sink);
+  }
+
+  // ### `parse` parses a string or a readable stream of RDF Messages.
+  //
+  // Without callbacks, a string is parsed synchronously into an array of
+  // messages (arrays of quads), and parse errors are thrown.
+  // With a callback `(error, message, prefixes)`, or an object with the
+  // callbacks `onMessage(error, message, prefixes)`, `onQuad(error, quad, messageIndex)`,
+  // `onPrefix(prefix, term)` and `onVersion(label)`, messages are reported as soon
+  // as they are complete. The final call has `null` as message.
+  parse(input, callbacks) {
+    if (typeof callbacks === 'function')
+      callbacks = { onMessage: callbacks };
+    const messages = callbacks ? null : [];
+    let error = null;
+    callbacks = callbacks || {};
+    const sink = {
+      message: (quads, index) => callbacks.onMessage ? callbacks.onMessage(null, quads, undefined, index) : messages && messages.push(quads),
+      end: prefixes => callbacks.onMessage && callbacks.onMessage(null, null, prefixes),
+      error: e => {
+        error = e;
+        callbacks.onMessage && callbacks.onMessage(e);
+        callbacks.onQuad && callbacks.onQuad(e);
+      },
+    };
+    if (callbacks.onQuad)
+      sink.quad = (quad, index) => callbacks.onQuad(null, quad, index);
+    if (callbacks.onPrefix)
+      sink.prefix = callbacks.onPrefix;
+    if (callbacks.onVersion)
+      sink.version = callbacks.onVersion;
+    const core = this._createCore(sink);
+
+    // Parse a string at once
+    if (typeof input === 'string') {
+      core.write(input);
+      core.end();
+      if (error && messages)
+        throw error;
+      return messages || undefined;
+    }
+
+    // Parse a stream chunk by chunk
+    const decoder = new StringDecoder('utf8');
+    input.on('data', chunk => core.write(typeof chunk === 'string' ? chunk : decoder.write(chunk)));
+    input.on('end', () => {
+      core.write(decoder.end());
+      core.end();
+    });
+    input.on('error', e => sink.error(e));
+    return undefined;
+  }
+}
+
+// ### `parseMessages` synchronously parses a string into an array of messages
+export function parseMessages(input, options) {
+  return new MessageParser(options).parse(input);
+}

package/src/MessageParserCore.js

@@ -0,0 +1,197 @@
+// **MessageParserCore** is the push-based engine behind all message parsers.
+// It feeds scanned text to the public N3.js parser and groups the resulting
+// quads into messages.
+import { EventEmitter } from 'events';
+import { Parser, DataFactory } from 'n3';
+import { TurtleScanner, LineScanner } from './MessageScanner.js';
+import { resolveFormat, isMessagesVersion, baseVersion, isSupportedVersion } from './formats.js';
+
+// Unrecognizable by construction: a document cannot contain it by accident
+function createSentinel() {
+  return `rdf-messages-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+
+export default class MessageParserCore {
+  // `sink` receives `message(quads, index)`, `end(prefixes)`, `error(error)`
+  // and optionally `quad(quad, messageIndex)`, `prefix(prefix, term)`, `version(label)`
+  constructor(options, sink) {
+    options = options || {};
+    const format = resolveFormat(options.format);
+    this._sink = sink;
+    this._factory = options.factory || DataFactory;
+    this._blankNodePrefix = typeof options.blankNodePrefix === 'string' ?
+      options.blankNodePrefix.replace(/^_:/, '') : undefined;
+    this._blankNodeCounter = 0;
+    this._supportedVersions = Parser.SUPPORTED_VERSIONS;
+    this._messages = options.messages === true || isMessagesVersion(options.version);
+    this._index = 0;
+    this._current = null;
+    this._scope = null;
+    this._seenQuad = false;
+    this._failed = false;
+    this._finished = false;
+
+    const n3Options = {
+      format: format.name,
+      factory: this._factory,
+      // Version labels are validated here, because N3.js does not know `-messages` labels
+      parseUnsupportedVersions: true,
+    };
+    if (options.baseIRI)
+      n3Options.baseIRI = options.baseIRI;
+    if (options.version) {
+      this._checkVersion(options.version, true);
+      n3Options.version = baseVersion(options.version);
+    }
+
+    const sentinel = createSentinel();
+    this._sentinel = sentinel;
+    this._scanner = format.lineMode ? new LineScanner(sentinel) : new TurtleScanner(sentinel);
+    this._input = new EventEmitter();
+    const callbacks = {
+      onQuad: (error, quad, prefixes) => this._onQuad(error, quad, prefixes),
+      onPrefix: (prefix, term) => this._failed || sink.prefix && sink.prefix(prefix, term),
+      onVersion: label => this._onVersion(label),
+    };
+    if (format.lineMode)
+      callbacks.onComment = comment => this._onComment(comment);
+    new Parser(n3Options).parse(this._input, callbacks);
+  }
+
+  // ### `write` accepts the next chunk of text
+  write(text) {
+    if (!this._failed && !this._finished && text.length > 0)
+      this._feed(this._scanner.push(text));
+  }
+
+  // ### `end` signals the end of the input
+  end() {
+    if (!this._failed && !this._finished) {
+      this._feed(this._scanner.end());
+      this._input.emit('end');
+    }
+  }
+
+  _feed(text) {
+    if (text.length > 0)
+      this._input.emit('data', text);
+  }
+
+  _onQuad(error, quad, prefixes) {
+    if (this._failed || this._finished)
+      return;
+    if (error)
+      this._fail(error);
+    else if (quad)
+      this._addQuad(quad);
+    else {
+      this._finished = true;
+      if (this._current !== null)
+        this._emitMessage();
+      this._sink.end(prefixes);
+    }
+  }
+
+  _addQuad(quad) {
+    this._seenQuad = true;
+    // Blank node labels are scoped to their message
+    if (this._messages)
+      quad = this._scopeQuad(quad);
+    if (this._current === null)
+      this._current = [];
+    this._current.push(quad);
+    if (this._sink.quad)
+      this._sink.quad(quad, this._index);
+  }
+
+  _onVersion(label) {
+    if (this._failed)
+      return;
+    if (label === this._sentinel)
+      this._delimiter(this._scanner.delimiterLines.shift());
+    else
+      this._announce(label);
+  }
+
+  // Line mode reports delimiters and versions as comments
+  _onComment(comment) {
+    if (this._failed || !comment.startsWith(this._sentinel))
+      return;
+    const rest = comment.substring(this._sentinel.length);
+    if (rest[0] === 'M')
+      this._delimiter(Number(rest.substring(1)));
+    else
+      this._announce(rest.substring(1));
+  }
+
+  _announce(label) {
+    const error = this._checkVersion(label);
+    if (error)
+      return this._fail(error);
+    if (isMessagesVersion(label) && !this._messages) {
+      if (this._seenQuad)
+        return this._fail(new Error(`Version "${label}" must be announced before the first statement.`));
+      this._messages = true;
+    }
+    if (this._sink.version)
+      this._sink.version(label);
+  }
+
+  // Validates a version label, and returns an error for unsupported ones
+  _checkVersion(label, throwing) {
+    if (isSupportedVersion(baseVersion(label), this._supportedVersions))
+      return null;
+    const error = new Error(`Detected unsupported version: "${label}"`);
+    if (throwing)
+      throw error;
+    return error;
+  }
+
+  _delimiter(line) {
+    if (!this._messages) {
+      return this._fail(new Error(`Unexpected "MESSAGE" on line ${line}: the document did not announce ` +
+                                  'a version with the "-messages" suffix.'));
+    }
+    this._emitMessage();
+  }
+
+  // Finalizes the current message, which is empty if no quad was seen
+  _emitMessage() {
+    const quads = this._current || [];
+    this._current = null;
+    this._scope = null;
+    this._sink.message(quads, this._index++);
+  }
+
+  _fail(error) {
+    this._failed = true;
+    this._current = null;
+    this._sink.error(error);
+  }
+
+  // ## Blank node scoping
+
+  _scopeQuad(quad) {
+    const subject = this._scopeTerm(quad.subject);
+    const predicate = this._scopeTerm(quad.predicate);
+    const object = this._scopeTerm(quad.object);
+    const graph = this._scopeTerm(quad.graph);
+    return subject === quad.subject && predicate === quad.predicate &&
+           object === quad.object && graph === quad.graph ?
+      quad : this._factory.quad(subject, predicate, object, graph);
+  }
+
+  _scopeTerm(term) {
+    if (term.termType === 'BlankNode') {
+      const scope = this._scope || (this._scope = new Map());
+      let scoped = scope.get(term.value);
+      if (!scoped) {
+        scoped = this._blankNodePrefix === undefined ? this._factory.blankNode() :
+          this._factory.blankNode(`${this._blankNodePrefix}${this._blankNodeCounter++}`);
+        scope.set(term.value, scoped);
+      }
+      return scoped;
+    }
+    return term.termType === 'Quad' ? this._scopeQuad(term) : term;
+  }
+}