n3.js-messages 0.1.2 → 0.1.4

package/README.md

@@ -108,8 +108,12 @@ const text = writeMessages(messages, { format: 'N-Quads' });  // synchronous, re
   message survives a round trip.
 - Each message starts from a clean serializer state, so consecutive messages in the same named graph are valid. Prefixes (and `baseIRI` with
   `writeBase: true`) are declared once; `addPrefix` declares more before the next message.
-- `addMessage` and `end` accept a callback or return a promise. They complete when the output stream has accepted the data, not when it was queued.
-- `MessageStreamWriter` is the `Transform` equivalent: messages in (object mode), text out.
+- Quads can also be streamed within a message, with constant memory: `beginMessage()` (optional), `addQuad(quad)` (written immediately),
+  `endMessage()` (writes the delimiter and resets the serializer state; without an open message it writes an empty one). `end()` closes an open message.
+  Alternatively, tag quads as in rdf-writer-ts, `addQuad(quad, messageIndex)`: a change of index ends the current message and writes the empty messages in
+  between; a lower index is an error. `addMessage(quads)` is shorthand for begin, add all, end, and fails if a message is open.
+- `addMessage`, `addQuad`, `beginMessage`, `endMessage` and `end` accept a callback or return a promise. They complete when the output stream has accepted the data, not when it was queued.
+- `MessageStreamWriter` is the `Transform` equivalent: messages in (object mode), text out. It also accepts `{ quad, messageIndex }` objects.
 
 ## Blank node semantics
 

package/index.d.ts

@@ -101,6 +101,16 @@ export class MessageWriter {
   constructor(outputStream?: MessageOutputStream | NodeJS.WritableStream | null, options?: MessageWriterOptions);
   addMessage(quads: RDF.BaseQuad[], done: (error: Error | null) => void): void;
   addMessage(quads: RDF.BaseQuad[]): Promise<void>;
+  /** Opens a message; optional, as `addQuad` opens one implicitly. */
+  beginMessage(done: (error: Error | null) => void): void;
+  beginMessage(): Promise<void>;
+  /** Writes a quad right away. With a 0-based `messageIndex`, a change of index ends the message and writes empty messages for gaps; a lower index is an error. */
+  addQuad(quad: RDF.BaseQuad, messageIndex: number | undefined, done: (error: Error | null) => void): void;
+  addQuad(quad: RDF.BaseQuad, done: (error: Error | null) => void): void;
+  addQuad(quad: RDF.BaseQuad, messageIndex?: number): Promise<void>;
+  /** Ends the open message (writes an empty message if none is open). */
+  endMessage(done: (error: Error | null) => void): void;
+  endMessage(): Promise<void>;
   addPrefix(prefix: string, iri: RDF.NamedNode | string, done: (error: Error | null) => void): void;
   addPrefix(prefix: string, iri: RDF.NamedNode | string): Promise<void>;
   /** Without an output stream, the result is the written string. */

package/lib/MessageStreamWriter.js

@@ -9,7 +9,7 @@ var _MessageWriter = _interopRequireDefault(require("./MessageWriter.js"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 // **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.
 
 class MessageStreamWriter extends _stream.Transform {
   constructor(options) {
@@ -26,7 +26,8 @@ class MessageStreamWriter extends _stream.Transform {
     }));
   }
   _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);
   }
   _flush(done) {
     this._writer.end(done);

package/lib/MessageWriter.js

@@ -40,6 +40,8 @@ class MessageWriter {
     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);
     this._newPrefixes = {};
     // The N3.js writer writes to this sink, which it never ends
@@ -53,8 +55,37 @@ class MessageWriter {
   // The callback (or returned promise) completes once the output is flushed.
   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.
+  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.
+  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.
+  endMessage(done) {
+    return this._complete(done, () => {
+      if (!this._open) this._begin();
+      this._close();
     });
   }
 
@@ -72,6 +103,7 @@ class MessageWriter {
     // 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)));
   }
@@ -150,16 +182,40 @@ class MessageWriter {
       });
     }
   }
-  _writeMessage(quads) {
+
+  // Opens a message: declares the prefixes that were added since the previous one
+  _begin() {
+    this._start();
     const writer = this._writer;
     for (const prefix of Object.keys(this._newPrefixes)) {
       writer.addPrefix(prefix, this._newPrefixes[prefix]);
       this._declared[prefix] = this._newPrefixes[prefix];
     }
     this._newPrefixes = {};
+    this._open = true;
+    this._count++;
+  }
+  _add(quad) {
     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();
+    this._writer.addQuad(quad.subject, quad.predicate, quad.object, quad.graph, record);
+  }
+  _close() {
+    this._open = false;
+    this._writer.addDelimiter();
+  }
+
+  // Makes message `index` the open message, writing empty messages for the gap
+  _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();
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n3.js-messages",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",

package/src/MessageStreamWriter.js

@@ -1,6 +1,6 @@
 // **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';
 
@@ -13,7 +13,9 @@ export default class MessageStreamWriter extends Transform {
   }
 
   _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);
   }
 
   _flush(done) {

package/src/MessageWriter.js

@@ -37,6 +37,8 @@ export default class MessageWriter {
     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);
     this._newPrefixes = {};
     // The N3.js writer writes to this sink, which it never ends
@@ -48,8 +50,38 @@ export default class MessageWriter {
   // The callback (or returned promise) completes once the output is flushed.
   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.
+  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.
+  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.
+  endMessage(done) {
+    return this._complete(done, () => {
+      if (!this._open) this._begin();
+      this._close();
     });
   }
 
@@ -69,6 +101,8 @@ export default class MessageWriter {
     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)));
@@ -165,17 +199,39 @@ export default class MessageWriter {
     }
   }
 
-  _writeMessage(quads) {
+  // Opens a message: declares the prefixes that were added since the previous one
+  _begin() {
+    this._start();
     const writer = this._writer;
     for (const prefix of Object.keys(this._newPrefixes)) {
       writer.addPrefix(prefix, this._newPrefixes[prefix]);
       this._declared[prefix] = this._newPrefixes[prefix];
     }
     this._newPrefixes = {};
+    this._open = true;
+    this._count++;
+  }
+  _add(quad) {
     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();
+    this._writer.addQuad(quad.subject, quad.predicate, quad.object, quad.graph, record);
+  }
+  _close() {
+    this._open = false;
+    this._writer.addDelimiter();
+  }
+
+  // Makes message `index` the open message, writing empty messages for the gap
+  _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();
   }
 }