n3.js-messages 0.1.2 → 0.2.0

package/src/MessageParserCore.js

@@ -5,29 +5,42 @@ import { EventEmitter } from 'events';
 import { Parser, DataFactory } from 'n3';
 import { resolveFormat, isMessagesVersion, baseVersion, isSupportedVersion } from './formats.js';
 
+/** @typedef {import('@rdfjs/types').Term} BaseTerm */
+/** @template {import('@rdfjs/types').BaseQuad} [Q=import('@rdfjs/types').Quad] */
 export default class MessageParserCore {
   // `sink` receives `message(quads, index)`, `end(prefixes)`, `error(error)`
   // and optionally `quad(quad, messageIndex)`, `prefix(prefix, term)`, `version(label)`
+  /**
+   * @param {import('../common.js').MessageParserOptions<Q> | undefined} options
+   * @param {import('./internal.js').ParserSink<Q>} sink
+   */
   constructor(options, sink) {
     options = options || {};
     const format = resolveFormat(options.format);
     this._sink = sink;
-    this._factory = options.factory || DataFactory;
+
+    /** @type {import('../common.js').MessageQuadFactory<Q>} */
+    this._factory = options.factory || /** @type {import('../common.js').MessageQuadFactory<Q>} */ (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;
+
+    /** @type {Q[] | null} */
     this._current = null;
+
+    /** @type {Map<string, import('@rdfjs/types').BlankNode> | null} */
     this._scope = null;
     this._seenQuad = false;
     this._failed = false;
     this._finished = false;
 
+    /** @type {import('n3').ParserOptions} */
     const n3Options = {
       format: format.name,
-      factory: this._factory,
+      factory: /** @type {import('@rdfjs/types').DataFactory} */ (/** @type {unknown} */ (this._factory)),
       // Version labels are validated here, because N3.js does not know `-messages` labels
       parseUnsupportedVersions: true,
       // N3.js reports `MESSAGE` and `@message .` between statements through `onDirective`,
@@ -47,7 +60,7 @@ export default class MessageParserCore {
     this._line = 0;
     this._delimiterLine = 0;
     new Parser(n3Options).parse(this._input, {
-      onQuad: (error, quad, prefixes) => this._onQuad(error, quad, prefixes),
+      onQuad: (error, quad, prefixes) => this._onQuad(error, /** @type {Q | null} */ (quad), prefixes),
       onPrefix: (prefix, term) => this._failed || sink.prefix && sink.prefix(prefix, term),
       onVersion: label => this._failed || this._announce(label),
       onDirective: () => this._failed || this._delimiter(),
@@ -56,6 +69,7 @@ export default class MessageParserCore {
   }
 
   // ### `write` accepts the next chunk of text
+  /** @param {string} text */
   write(text) {
     if (!this._failed && !this._finished && text.length > 0)
       this._input.emit('data', text);
@@ -68,6 +82,7 @@ export default class MessageParserCore {
   }
 
   // Keeps track of lines; in N-Triples and N-Quads, a delimiter must be on its own line
+  /** @param {{ line: number; type: string }} token */
   _onToken(token) {
     const line = token.line, delimiter = token.type === 'MESSAGE';
     if (this._lineMode && !this._failed &&
@@ -78,6 +93,9 @@ export default class MessageParserCore {
     this._line = line;
   }
 
+  /** @param {Error | null} error
+   * @param {Q | null} quad
+   * @param {Record<string, import('@rdfjs/types').NamedNode>} [prefixes] */
   _onQuad(error, quad, prefixes) {
     if (this._failed || this._finished)
       return;
@@ -93,6 +111,7 @@ export default class MessageParserCore {
     }
   }
 
+  /** @param {Q} quad */
   _addQuad(quad) {
     this._seenQuad = true;
     // Blank node labels are scoped to their message
@@ -105,6 +124,7 @@ export default class MessageParserCore {
       this._sink.quad(quad, this._index);
   }
 
+  /** @param {string} label */
   _announce(label) {
     const error = this._checkVersion(label);
     if (error)
@@ -119,6 +139,8 @@ export default class MessageParserCore {
   }
 
   // Validates a version label, and returns an error for unsupported ones
+  /** @param {string} label
+   * @param {boolean} [throwing] */
   _checkVersion(label, throwing) {
     if (isSupportedVersion(baseVersion(label), this._supportedVersions))
       return null;
@@ -144,6 +166,7 @@ export default class MessageParserCore {
     this._sink.message(quads, this._index++);
   }
 
+  /** @param {Error} error */
   _fail(error) {
     this._failed = true;
     this._current = null;
@@ -152,6 +175,8 @@ export default class MessageParserCore {
 
   // ## Blank node scoping
 
+  /** @param {Q} quad
+   * @returns {Q} */
   _scopeQuad(quad) {
     const subject = this._scopeTerm(quad.subject);
     const predicate = this._scopeTerm(quad.predicate);
@@ -162,6 +187,9 @@ export default class MessageParserCore {
       quad : this._factory.quad(subject, predicate, object, graph);
   }
 
+  /** @template {BaseTerm} T
+   * @param {T} term
+   * @returns {T} */
   _scopeTerm(term) {
     if (term.termType === 'BlankNode') {
       const scope = this._scope || (this._scope = new Map());
@@ -171,8 +199,9 @@ export default class MessageParserCore {
           this._factory.blankNode(`${this._blankNodePrefix}${this._blankNodeCounter++}`);
         scope.set(term.value, scoped);
       }
-      return scoped;
+      return /** @type {T} */ (/** @type {unknown} */ (scoped));
     }
-    return term.termType === 'Quad' ? this._scopeQuad(term) : term;
+    return term.termType === 'Quad' ? /** @type {T} */ (/** @type {unknown} */ (
+      this._scopeQuad(/** @type {Q} */ (/** @type {unknown} */ (term))))) : term;
   }
 }

package/src/MessageStreamParser.js

@@ -6,10 +6,14 @@ import { Transform } from 'stream';
 import { StringDecoder } from 'string_decoder';
 import MessageParserCore from './MessageParserCore.js';
 
+/** @template {import('@rdfjs/types').BaseQuad} [Q=import('@rdfjs/types').Quad] */
 export default class MessageStreamParser extends Transform {
+  /** @param {import('../common.js').MessageParserOptions<Q>} [options] */
   constructor(options) {
     super({ decodeStrings: false, readableObjectMode: true });
     this._decoder = new StringDecoder('utf8');
+
+    /** @type {Error | null} */
     this._error = null;
     this._core = new MessageParserCore(options, {
       message: quads => this.push(quads),
@@ -20,11 +24,15 @@ export default class MessageStreamParser extends Transform {
     });
   }
 
+  /** @param {string | Buffer} chunk
+   * @param {BufferEncoding} encoding
+   * @param {import('node:stream').TransformCallback} done */
   _transform(chunk, encoding, done) {
     this._core.write(typeof chunk === 'string' ? chunk : this._decoder.write(chunk));
     done(this._error);
   }
 
+  /** @param {import('node:stream').TransformCallback} done */
   _flush(done) {
     this._core.write(this._decoder.end());
     this._core.end();

package/src/MessageStreamWriter.js

@@ -1,21 +1,29 @@
 // **MessageStreamWriter** is a Node.js stream that serializes RDF Messages.
 //
-// It consumes messages (arrays of quads) and produces text.
+// It consumes messages (arrays of quads), or `{ quad, messageIndex }` objects, and produces text.
 import { Transform } from 'stream';
 import MessageWriter from './MessageWriter.js';
 
 export default class MessageStreamWriter extends Transform {
+  /** @param {import('../common.js').MessageWriterOptions} [options] */
   constructor(options) {
     super({ writableObjectMode: true, encoding: 'utf8' });
     // Writing into this stream never blocks, and output is pushed synchronously
+    /** @type {Pick<import('./internal.js').Output, 'write'>} */
     const output = { write: (chunk, encoding, done) => (this.push(chunk), done && done()) };
     this._writer = new MessageWriter(output, Object.assign({}, options, { end: false }));
   }
 
+  /** @param {import('../browser.js').MessageWriterInput} message
+   * @param {BufferEncoding} encoding
+   * @param {import('node:stream').TransformCallback} done */
   _transform(message, encoding, done) {
-    this._writer.addMessage(message, done);
+    // A message (array of quads), or a quad of a message: `{ quad, messageIndex }`
+    if (Array.isArray(message)) this._writer.addMessage(message, done);
+    else this._writer.addQuad(message.quad, message.messageIndex, done);
   }
 
+  /** @param {import('node:stream').TransformCallback} done */
   _flush(done) {
     this._writer.end(done);
   }

package/src/MessageWriter.js

@@ -9,6 +9,7 @@
 import { Writer } from 'n3';
 import { resolveFormat, isMessagesVersion, baseVersion, isSupportedVersion } from './formats.js';
 
+/** @extends {Writer<import('@rdfjs/types').BaseQuad>} */
 class LogWriter extends Writer {
   // ### `addDelimiter` ends the current message
   addDelimiter() {
@@ -17,11 +18,22 @@ class LogWriter extends Writer {
   }
 }
 
+/** @typedef {import('./internal.js').Done} Done */
+/** @typedef {import('./internal.js').End} End */
+/** @typedef {import('../common.js').MessageWriterOptions} Options */
+/** @typedef {Pick<import('./internal.js').Output, 'write'> & Partial<Pick<import('./internal.js').Output, 'end'>>} Output */
 export default class MessageWriter {
   // `outputStream` is optional: without it, `end` returns the output as a string
+  /** @overload
+   * @param {Options} [options] */
+  /** @overload
+   * @param {Output | null} outputStream
+   * @param {Options} [options] */
+  /** @param {Output | Options | null} [outputStream]
+   * @param {Options} [options] */
   constructor(outputStream, options) {
-    if (outputStream && typeof outputStream.write !== 'function')
-      options = outputStream, outputStream = null;
+    if (outputStream && typeof /** @type {Output} */ (outputStream).write !== 'function')
+      options = /** @type {Options} */ (outputStream), outputStream = null;
     options = options || {};
     this._format = resolveFormat(options.format);
     this._options = options;
@@ -30,45 +42,105 @@ export default class MessageWriter {
       throw new TypeError(`Unsupported RDF Messages version: "${this._version}"`);
 
     this._output = '';
-    this._stream = outputStream;
+    this._stream = /** @type {Output | null | undefined} */ (outputStream);
     this._endStream = !outputStream || options.end !== false;
     this._pending = 0;
+
+    /** @type {Done[]} */
     this._waiting = [];
+
+    /** @type {Error | null} */
     this._error = null;
     this._started = false;
     this._ended = false;
+    this._open = false;
+    this._count = 0; // messages begun so far: the index of the next message
     this._declared = Object.assign({}, options.prefixes);
+
+    /** @type {Record<string, string>} */
     this._newPrefixes = {};
     // The N3.js writer writes to this sink, which it never ends
+    /** @type {Pick<Output, 'write'>} */
     this._sink = { write: (chunk, encoding, done) => this._write(chunk, done) };
+
+    /** @type {LogWriter | null} */
     this._writer = null;
   }
 
   // ### `addMessage` writes the quads of one message, followed by a delimiter.
   // The callback (or returned promise) completes once the output is flushed.
+  /** @param {import('@rdfjs/types').BaseQuad[]} quads
+   * @param {Done} [done] */
   addMessage(quads, done) {
     return this._complete(done, () => {
-      this._start();
-      this._writeMessage(quads || []);
+      if (this._open) throw new Error('A message is already open');
+      this._begin();
+      for (const quad of quads || []) this._add(quad);
+      this._close();
+    });
+  }
+
+  // ### `beginMessage` opens a message. It is optional: the first `addQuad` opens one implicitly.
+  /** @param {Done} [done] */
+  beginMessage(done) {
+    return this._complete(done, () => {
+      if (this._open) throw new Error('A message is already open');
+      this._begin();
+    });
+  }
+
+  // ### `addQuad` writes a quad into the open message right away (a message is opened if there is none).
+  // With a `messageIndex` (0-based), a change of index ends the current message and writes the empty
+  // messages in between, as rdf-writer-ts does; a lower index than the current one is an error.
+  /** @param {import('@rdfjs/types').BaseQuad} quad
+   * @param {number | Done} [messageIndex]
+   * @param {Done} [done] */
+  addQuad(quad, messageIndex, done) {
+    if (typeof messageIndex === 'function') done = messageIndex, messageIndex = undefined;
+    return this._complete(done, () => {
+      if (messageIndex !== undefined && messageIndex !== null) this._moveTo(messageIndex);
+      else if (!this._open) this._begin();
+      this._add(quad);
+    });
+  }
+
+  // ### `endMessage` ends the open message with a delimiter. Without an open message, it writes an empty one.
+  /** @param {Done} [done] */
+  endMessage(done) {
+    return this._complete(done, () => {
+      if (!this._open) this._begin();
+      this._close();
     });
   }
 
   // ### `addPrefix` declares a prefix, which is written before the next message
   // and stays in effect for all messages after it
+  /** @param {string} prefix
+   * @param {string | import('@rdfjs/types').NamedNode} iri
+   * @param {Done} [done] */
   addPrefix(prefix, iri, done) {
     return this._complete(done, () => {
-      if (!this._format.lineMode && this._declared[prefix] !== (iri.value || iri))
-        this._newPrefixes[prefix] = iri.value || iri;
+      if (!this._format.lineMode && this._declared[prefix] !== (typeof iri === 'string' ? iri : iri.value))
+        this._newPrefixes[prefix] = typeof iri === 'string' ? iri : iri.value;
     });
   }
 
   // ### `end` ends the log and, unless disabled, the output stream.
   // The callback receives the output as a string if no output stream was given.
+  /** @overload
+   * @returns {Promise<string | void>} */
+  /** @overload
+   * @param {End} done
+   * @returns {void} */
+  /** @param {End} [done]
+   * @returns {Promise<string | void> | void} */
   end(done) {
     // Ending twice is harmless
     if (this._ended)
       return typeof done === 'function' ? done(null) : Promise.resolve();
     this._start();
+    if (this._open)
+      this._close();
     if (typeof done === 'function')
       return this._finish(done);
     return new Promise((resolve, reject) => this._finish((error, result) => error ? reject(error) : resolve(result)));
@@ -77,6 +149,9 @@ export default class MessageWriter {
   // ## Private methods
 
   // Runs an action and reports completion with a callback or a promise
+  /** @param {Done | undefined} done
+   * @param {() => void} action
+   * @returns {Promise<void> | void} */
   _complete(done, action) {
     if (this._ended)
       this._error = this._error || new Error('Cannot write after end');
@@ -85,7 +160,7 @@ export default class MessageWriter {
         action();
       }
       catch (error) {
-        this._error = this._error || error;
+        this._error = this._error || /** @type {Error} */ (error);
       }
     if (typeof done === 'function')
       return this._whenFlushed(done);
@@ -93,25 +168,29 @@ export default class MessageWriter {
   }
 
   // Ends the output once all queued writes were accepted
+  /** @param {End} callback */
   _finish(callback) {
     this._ended = true;
     this._whenFlushed(error => this._endOutput(error, callback));
   }
 
+  /** @param {Error | null | undefined} error
+   * @param {End} callback */
   _endOutput(error, callback) {
     if (error || !this._endStream)
       return callback(error);
     if (!this._stream)
       return callback(null, this._output);
     try {
-      this._stream.end(endError => callback(endError));
+      (/** @type {Required<Output>} */ (this._stream)).end(endError => callback(endError));
     }
     catch (endError) {
-      callback(endError);
+      callback(/** @type {Error} */ (endError));
     }
   }
 
   // Calls back once all queued writes were accepted by the output
+  /** @param {Done} done */
   _whenFlushed(done) {
     if (this._pending === 0)
       this._settle(done);
@@ -119,12 +198,15 @@ export default class MessageWriter {
       this._waiting.push(done);
   }
 
+  /** @param {Done} done */
   _settle(done) {
     const error = this._error;
     this._error = null;
     done(error || null);
   }
 
+  /** @param {string} chunk
+   * @param {Done} [done] */
   _write(chunk, done) {
     if (!this._stream) {
       this._output += chunk;
@@ -135,11 +217,13 @@ export default class MessageWriter {
       this._stream.write(chunk, 'utf8', error => this._written(error, done));
     }
     catch (error) {
-      this._written(error, done);
+      this._written(/** @type {Error} */ (error), done);
     }
   }
 
   // Registers that the output accepted a write, and wakes up those waiting for the output
+  /** @param {Error | null | undefined} error
+   * @param {Done} [done] */
   _written(error, done) {
     this._pending--;
     this._error = this._error || error || null;
@@ -165,32 +249,66 @@ export default class MessageWriter {
     }
   }
 
-  _writeMessage(quads) {
-    const writer = this._writer;
+  // Opens a message: declares the prefixes that were added since the previous one
+  _begin() {
+    this._start();
+    const writer = /** @type {LogWriter} */ (this._writer);
     for (const prefix of Object.keys(this._newPrefixes)) {
-      writer.addPrefix(prefix, this._newPrefixes[prefix]);
-      this._declared[prefix] = this._newPrefixes[prefix];
+      const iri = /** @type {string} */ (this._newPrefixes[prefix]);
+      writer.addPrefix(prefix, iri);
+      this._declared[prefix] = iri;
     }
     this._newPrefixes = {};
+    this._open = true;
+    this._count++;
+  }
+
+  /** @param {import('@rdfjs/types').BaseQuad} quad */
+  _add(quad) {
+    /** @type {Done} */
     const record = error => error && (this._error = this._error || error);
-    for (const quad of quads)
-      writer.addQuad(quad.subject, quad.predicate, quad.object, quad.graph, record);
-    writer.addDelimiter();
+    (/** @type {LogWriter} */ (this._writer)).addQuad(quad.subject, quad.predicate, quad.object, quad.graph, record);
+  }
+  _close() {
+    this._open = false;
+    (/** @type {LogWriter} */ (this._writer)).addDelimiter();
+  }
+
+  // Makes message `index` the open message, writing empty messages for the gap
+  /** @param {number} index */
+  _moveTo(index) {
+    const current = this._count - 1;
+    if (!Number.isInteger(index) || index < 0) throw new RangeError(`Invalid message index: ${index}`);
+    if (this._open && index === current) return;
+    if (index <= current) throw new RangeError(`Message index ${index} is lower than the current message index ${current}`);
+    if (this._open) this._close();
+    while (this._count < index) {
+      this._begin();
+      this._close();
+    }
+    this._begin();
   }
 }
 
+/** @param {Iterable<import('@rdfjs/types').BaseQuad[]>} messages
+ * @param {Options} [options]
+ * @returns {string} */
 // ### `writeMessages` synchronously serializes an array of messages to a string
 export function writeMessages(messages, options) {
   const writer = new MessageWriter(options);
+
+  /** @type {Error[]} */
   const errors = [];
-  let output;
+  let output = '';
+
+  /** @param {Error | null | undefined} error */
   function collect(error) {
     if (error)
       errors.push(error);
   }
   for (const message of messages)
     writer.addMessage(message, collect);
-  writer.end((error, result) => (collect(error), output = result));
+  writer.end((error, result) => (collect(error), output = /** @type {string} */ (result)));
   if (errors.length > 0)
     throw errors[0];
   return output;

package/src/browser.js

@@ -0,0 +1,61 @@
+import MessageParserCore from './MessageParserCore.js';
+import MessageWriter from './MessageWriter.js';
+
+export { default as MessageParser, parseMessages } from './MessageParser.js';
+export { default as MessageWriter, writeMessages } from './MessageWriter.js';
+
+/**
+ * A Web Streams parser; strings and UTF-8 bytes can be piped directly from fetch.
+ * @template {import('@rdfjs/types').BaseQuad} [Q=import('@rdfjs/types').Quad]
+ * @extends {TransformStream<import('../browser.js').MessageChunk, Q[]>}
+ */
+export class MessageStreamParser extends TransformStream {
+  /** @param {import('../browser.js').BrowserParserOptions<Q>} [options] */
+  constructor(options = {}) {
+    const decoder = new TextDecoder();
+
+    /** @type {MessageParserCore<Q>} */
+    let core;
+    super({
+      start(controller) {
+        core = new MessageParserCore(options, {
+          message: quads => controller.enqueue(quads),
+          end: () => {},
+          error: error => { throw error; },
+          prefix: options.onPrefix,
+          version: options.onVersion,
+        });
+      },
+      transform(chunk) {
+        core.write(typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true }));
+      },
+      flush() {
+        core.write(decoder.decode());
+        core.end();
+      },
+    });
+  }
+}
+
+/** A Web Streams writer; accepts messages or individual indexed quads.
+ * @extends {TransformStream<import('../browser.js').MessageWriterInput, string>} */
+export class MessageStreamWriter extends TransformStream {
+  /** @param {import('../common.js').MessageWriterOptions} [options] */
+  constructor(options) {
+    /** @type {MessageWriter} */
+    let writer;
+    super({
+      start(controller) {
+        /** @type {Pick<import('./internal.js').Output, 'write'>} */
+        const output = { write: (chunk, encoding, done) => { controller.enqueue(chunk); done(); } };
+        writer = new MessageWriter(output, { ...options, end: false });
+      },
+      transform(message) {
+        return Array.isArray(message) ? writer.addMessage(message) : writer.addQuad(message.quad, message.messageIndex);
+      },
+      flush() {
+        return writer.end().then(() => {});
+      },
+    });
+  }
+}

package/src/formats.js

@@ -1,5 +1,6 @@
 // **formats** describes the RDF syntaxes that support RDF Messages.
 
+/** @type {Record<string, { name: string; lineMode: boolean }>} */
 const FORMATS = {
   turtle: { name: 'Turtle', lineMode: false },
   trig: { name: 'TriG', lineMode: false },
@@ -12,7 +13,7 @@ const BASE_VERSIONS = ['1.2', '1.2-basic', '1.1'];
 
 // ### `resolveFormat` maps a format name or media type to a supported syntax
 export function resolveFormat(format = 'TriG') {
-  const key = String(format).toLowerCase().split(';')[0].trim()
+  const key = String(format).toLowerCase().replace(/;[\s\S]*$/, '').trim()
     .replace(/^(?:text|application)\//, '')
     .replace(/^x-/, '')
     .replace(/[-_ ]/g, '');
@@ -23,16 +24,19 @@ export function resolveFormat(format = 'TriG') {
   return resolved;
 }
 
+/** @param {unknown} version */
 // ### `isMessagesVersion` checks whether a version label announces RDF Messages
 export function isMessagesVersion(version) {
   return typeof version === 'string' && version.endsWith('-messages');
 }
 
+/** @param {string} version */
 // ### `baseVersion` strips the `-messages` suffix of a version label
 export function baseVersion(version) {
   return isMessagesVersion(version) ? version.slice(0, -'-messages'.length) : version;
 }
 
+/** @param {string} version */
 // ### `isSupportedVersion` checks whether a (base) version label is supported
 export function isSupportedVersion(version, supported = BASE_VERSIONS) {
   return supported.includes(version);

package/src/internal.d.ts

@@ -0,0 +1,15 @@
+import type * as RDF from '@rdfjs/types';
+export interface ParserSink<Q extends RDF.BaseQuad> {
+  message(quads: Q[], index: number): unknown;
+  end(prefixes?: Record<string, RDF.NamedNode>): unknown;
+  error(error: Error): unknown;
+  quad?(quad: Q, index: number): unknown;
+  prefix?(prefix: string, term: RDF.NamedNode): unknown;
+  version?(label: string): unknown;
+}
+export type Done = (error?: Error | null) => void;
+export type End = (error?: Error | null, result?: string) => void;
+export interface Output {
+  write(chunk: string, encoding: string, done: Done): unknown;
+  end(done: Done): unknown;
+}