@condorcet.vote/cef-writer 1.2.0

package/src/Cef.ts

@@ -0,0 +1,405 @@
+import { CommentLine } from './CommentLine';
+import {
+  CefWriteException,
+  InvalidValueException,
+  InvalidWriterStateException,
+  ReservedCharacterException,
+} from './Exception';
+import type { ParameterInterface } from './Parameter';
+import { VoteLine } from './VoteLine';
+
+/**
+ * A sink the writer can stream lines into, mirroring the contract of PHP's
+ * `\SplFileObject::fwrite()`: `write()` returns the number of bytes actually
+ * written. Returning fewer bytes than supplied (or throwing) signals an I/O
+ * failure and triggers a {@link CefWriteException}.
+ */
+export interface WriteTarget {
+  write(chunk: string): number;
+}
+
+/**
+ * A mutable string sink, the idiomatic TypeScript stand-in for PHP's
+ * "string passed by reference" target. The writer appends every line to it;
+ * read the accumulated document back with {@link toString} (or {@link value}).
+ */
+export class StringBuffer {
+  private content = '';
+
+  public append(chunk: string): void {
+    this.content += chunk;
+  }
+
+  public get value(): string {
+    return this.content;
+  }
+
+  public toString(): string {
+    return this.content;
+  }
+}
+
+/**
+ * Options accepted by the {@link Cef} constructor. Exactly one of `file` or
+ * `string` must be provided.
+ */
+export interface CefOptions {
+  /**
+   * A filesystem path (opened in truncating write mode) or any
+   * {@link WriteTarget} (e.g. an already-open {@link FileWriteTarget}).
+   */
+  file?: string | WriteTarget;
+
+  /**
+   * A {@link StringBuffer} the writer appends every line to.
+   */
+  string?: StringBuffer;
+}
+
+/**
+ * Streaming writer for a single Condorcet Election Format document.
+ *
+ * Each `add*()` call emits one line to the underlying target *immediately* —
+ * the library never buffers more than a single line in memory and previously
+ * written content cannot be edited.
+ *
+ * The target is chosen at construction time:
+ *   - a {@link WriteTarget} (passed through);
+ *   - a filesystem path (opened with mode `w`);
+ *   - a {@link StringBuffer} that the writer will append to.
+ *
+ * # Phases
+ *
+ * Parameters must be emitted before votes. Comments and empty lines may be
+ * emitted at any time. Once the first {@link VoteLine} is written, calling
+ * {@link addParameter} throws an {@link InvalidWriterStateException}.
+ *
+ * # autoFormat
+ *
+ * When `true` (default), the writer follows the visually relaxed flavor of the
+ * spec — spaces around `>`, `=`, `;`, `,`; one blank line automatically
+ * inserted between the parameter block and the first vote. When `false`, the
+ * most compact form is emitted.
+ */
+export class Cef {
+  /**
+   * Factory that turns a filesystem path into a {@link WriteTarget}.
+   *
+   * The browser entry point leaves this `null`, so the browser bundle never
+   * references {@link FileWriteTarget} (and therefore never pulls in `node:fs`).
+   * The Node entry point wires it to {@link FileWriteTarget}, enabling the
+   * `new Cef({ file: '/some/path' })` convenience.
+   *
+   * @internal
+   */
+  public static fileWriteTargetFactory: ((path: string) => WriteTarget) | null = null;
+
+  public autoFormat = true;
+
+  /**
+   * The active file target, or `null` when writing to a string.
+   */
+  public readonly file: WriteTarget | null;
+
+  /**
+   * Reference to the caller's string buffer in string mode, `null` in file
+   * mode.
+   */
+  private readonly stringTarget: StringBuffer | null;
+
+  private parameterEmitted = false;
+
+  private voteEmitted = false;
+
+  private autoSeparatorWritten = false;
+
+  /**
+   * Exactly one of `options.file` or `options.string` must be provided.
+   *
+   * @throws {InvalidWriterStateException}
+   */
+  public constructor(options: CefOptions = {}) {
+    const hasFile = options.file !== undefined;
+    const hasString = options.string !== undefined;
+
+    if (hasFile === hasString) {
+      throw new InvalidWriterStateException(
+        'Exactly one of file or string must be provided to the Cef constructor.'
+      );
+    }
+
+    if (hasString) {
+      this.file = null;
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      this.stringTarget = options.string!;
+
+      return;
+    }
+
+    this.stringTarget = null;
+
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const file = options.file!;
+
+    if (typeof file === 'string') {
+      this.file = this.createFileWriteTarget(file);
+    } else if (typeof file === 'object' && typeof file.write === 'function') {
+      this.file = file;
+    } else {
+      throw new InvalidWriterStateException(
+        'The file option must be a string path or a WriteTarget.'
+      );
+    }
+  }
+
+  /**
+   * Create a file-backed {@link WriteTarget} from a path, via the factory the
+   * Node entry point registers in {@link Cef.fileWriteTargetFactory}.
+   *
+   * @throws {InvalidWriterStateException} when no factory is registered — i.e.
+   *   in the browser bundle, where filesystem access is unavailable.
+   */
+  private createFileWriteTarget(path: string): WriteTarget {
+    const factory = Cef.fileWriteTargetFactory;
+
+    if (factory === null) {
+      throw new InvalidWriterStateException(
+        'Writing to a file path is not available in this environment (browser?). ' +
+          'Use StringBuffer instead, or pass a custom WriteTarget. In Node.js, ' +
+          "import from '@condorcet.vote/cef-writer' (not '@condorcet.vote/cef-writer/browser')."
+      );
+    }
+
+    return factory(path);
+  }
+
+  /**
+   * Emit a parameter line `#/Name: value`.
+   *
+   * @throws {CefFormatException} if a vote has already been written
+   */
+  public addParameter(parameter: ParameterInterface): this {
+    if (this.voteEmitted) {
+      throw new InvalidWriterStateException('Parameters must be written before any vote line.');
+    }
+
+    const separator = this.autoFormat ? ': ' : ':';
+    const line =
+      '#/' + parameter.getName() + separator + parameter.getFormattedValue(this.autoFormat);
+
+    this.writeLine(line);
+    this.parameterEmitted = true;
+
+    return this;
+  }
+
+  /**
+   * Emit a vote line. Locks parameter mode permanently.
+   */
+  public addVote(vote: VoteLine): this {
+    this.writeAutoSeparatorIfNeeded();
+
+    let line = vote.format(this.autoFormat);
+
+    if (vote.inlineComment !== null) {
+      line += this.renderInlineComment(vote.inlineComment);
+    }
+
+    this.writeLine(line);
+    this.voteEmitted = true;
+
+    return this;
+  }
+
+  /**
+   * Emit a vote line directly from a pre-built string, skipping the allocation
+   * of a {@link VoteLine} instance. Use this when you already have ballots as
+   * text and want the fastest path to the output.
+   *
+   * The full CEF vote-line format is enforced — the same validation rules that
+   * {@link VoteLine.fromString} applies are run via
+   * {@link VoteLine.assertValidString}. In particular:
+   *   - structural checks first: a single trailing line terminator
+   *     (`\r\n`, `\n`, `\r`) is stripped, surrounding whitespace is trimmed,
+   *     the result must be non-empty, must not contain any remaining
+   *     `\r`/`\n`, and must not start with `#` (which would be a comment or a
+   *     parameter line, not a vote);
+   *   - format checks then: tags, ranking, weight, quantifier and inline
+   *     comment are parsed and validated against every CEF rule.
+   *
+   * The `autoFormat` flag has no effect on a raw line: what you pass is what
+   * gets written (after structural cleaning).
+   *
+   * @throws {CefFormatException}
+   */
+  public addRawVoteLine(line: string): this {
+    let cleaned = line.replace(/\r\n$|[\r\n]$/, '');
+    cleaned = cleaned.trim();
+
+    if (cleaned === '') {
+      throw new InvalidValueException('Raw vote line cannot be empty.');
+    }
+
+    if (/[\r\n]/.test(cleaned)) {
+      throw new InvalidValueException(
+        'Raw vote line must be a single line; embedded newlines are not allowed.'
+      );
+    }
+
+    if (cleaned.startsWith('#')) {
+      throw new ReservedCharacterException(
+        'Raw vote line cannot start with "#"; that would be a comment or parameter line, not a vote.'
+      );
+    }
+
+    VoteLine.assertValidString(cleaned);
+
+    this.writeAutoSeparatorIfNeeded();
+    this.writeLine(cleaned);
+    this.voteEmitted = true;
+
+    return this;
+  }
+
+  /**
+   * Emit a vote line from a **ranking-only** string plus strictly-typed
+   * companions — the secure, paranoid sibling of {@link addRawVoteLine}.
+   *
+   * Whereas {@link addRawVoteLine} accepts a full vote line (and therefore lets
+   * the caller embed tags, a weight, a quantifier or an inline comment inside
+   * the text), `addRawVote()` guarantees that `vote` carries *only* a ranking.
+   * Any line break, the `||` tag separator, and every reserved character
+   * (`^`, `*`, `#`, `;`, `,`, `/`) are rejected, so the string can never
+   * smuggle a weight, quantifier, tag, inline comment or second vote into the
+   * output. Use this when the ranking comes from an untrusted source.
+   *
+   * Weight, quantifier and tags are supplied exclusively through the typed
+   * options. `weight` and `quantifier` are nullable and default to `null`, in
+   * which case they are omitted from the output; when provided they must be
+   * strictly positive. Just like {@link addRawVoteLine}, the ranking string is
+   * written verbatim — its original spacing is preserved and `autoFormat` does
+   * not reformat it. The `autoFormat` flag still governs the layout of the
+   * library-built companions (the `||` tag separator, `^weight`, `*quantifier`).
+   *
+   * @throws {CefFormatException}
+   */
+  public addRawVote(
+    vote: string,
+    options: {
+      quantifier?: number | null;
+      weight?: number | null;
+      tags?: readonly string[] | null;
+    } = {}
+  ): this {
+    const voteLine = VoteLine.fromRawRankingString(vote, {
+      tags: options.tags ?? [],
+      weight: options.weight ?? null,
+      quantifier: options.quantifier ?? null,
+    });
+
+    this.writeAutoSeparatorIfNeeded();
+    this.writeLine(voteLine.format(this.autoFormat));
+    this.voteEmitted = true;
+
+    return this;
+  }
+
+  /**
+   * Emit a standalone comment line.
+   */
+  public addComment(comment: CommentLine): this {
+    this.writeLine(comment.format(this.autoFormat));
+
+    return this;
+  }
+
+  /**
+   * Convenience helper: build a {@link CommentLine} from raw text and emit it
+   * in a single call.
+   */
+  public addCommentLine(text: string): this {
+    return this.addComment(new CommentLine(text));
+  }
+
+  /**
+   * Emit an empty line.
+   */
+  public addEmptyLine(): this {
+    this.writeLine('');
+
+    return this;
+  }
+
+  /**
+   * Close the underlying file target, if any. No-op in string mode or when the
+   * target does not expose a `close()` method.
+   */
+  public close(): void {
+    if (this.file !== null && 'close' in this.file && typeof this.file.close === 'function') {
+      (this.file as { close: () => void }).close();
+    }
+  }
+
+  /**
+   * Insert one blank line between the parameter block and the first vote when
+   * `autoFormat` is on. Idempotent.
+   */
+  private writeAutoSeparatorIfNeeded(): void {
+    if (
+      this.autoFormat &&
+      this.parameterEmitted &&
+      !this.voteEmitted &&
+      !this.autoSeparatorWritten
+    ) {
+      this.writeLine('');
+      this.autoSeparatorWritten = true;
+    }
+  }
+
+  private renderInlineComment(comment: string): string {
+    if (!this.autoFormat) {
+      return '#' + comment;
+    }
+
+    const needsLeadingSpace = comment === '' || !comment.startsWith(' ');
+
+    return ' #' + (needsLeadingSpace ? ' ' : '') + comment;
+  }
+
+  private writeLine(content: string): void {
+    const line = content + '\n';
+
+    if (this.file !== null) {
+      const expected = Buffer.byteLength(line, 'utf-8');
+      let written: number;
+
+      try {
+        written = this.file.write(line);
+      } catch (error) {
+        throw new CefWriteException(
+          `Failed to write ${String(expected)} bytes to the file target. ` +
+            'The underlying handle may be closed, read-only, or out of space.',
+          { cause: error }
+        );
+      }
+
+      if (written < expected) {
+        throw new CefWriteException(
+          `Failed to write ${String(expected)} bytes to the file target (write returned ${String(written)}). ` +
+            'The underlying handle may be closed, read-only, or out of space.'
+        );
+      }
+
+      return;
+    }
+
+    if (this.stringTarget === null) {
+      throw new InvalidWriterStateException(
+        'Cef writer has no target: neither file nor string is set. ' +
+          'This indicates a corrupted internal state that the constructor should have prevented.'
+      );
+    }
+
+    this.stringTarget.append(line);
+  }
+}

package/src/CefFormat.ts

@@ -0,0 +1,152 @@
+import {
+  InvalidUtf8Exception,
+  InvalidValueException,
+  ReservedCharacterException,
+} from './Exception';
+
+/**
+ * Internal helpers shared across the writer and the value objects.
+ *
+ * A namespace of static utilities that encode rules from the CEF specification
+ * (reserved characters, blank-ballot sentinel, etc.).
+ *
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace CefFormat {
+  /**
+   * Characters that the specification reserves for syntactic use and that
+   * therefore must never appear inside any user-supplied value.
+   */
+  export const RESERVED_CHARACTERS: readonly string[] = [
+    '>',
+    '=',
+    ';',
+    ',',
+    '#',
+    '/',
+    '*',
+    '^',
+  ];
+
+  /**
+   * Sentinel value emitted as the whole ranking of a blank ballot.
+   */
+  export const EMPTY_RANKING = '/EMPTY_RANKING/';
+
+  /**
+   * Tag/ranking separator on a vote line.
+   */
+  export const TAGS_SEPARATOR = '||';
+
+  /**
+   * Reject any value that contains a reserved character or a line break. Empty
+   * strings are rejected too — this helper is meant for *required* structural
+   * values (names, tags, candidate labels, …).
+   *
+   * @throws {CefFormatException}
+   */
+  export function assertValueIsClean(value: string, context: string): void {
+    if (value === '') {
+      throw new InvalidValueException(`${context} cannot be empty.`);
+    }
+
+    assertNoReservedNorLineBreak(value, context);
+  }
+
+  /**
+   * Reject any value that contains a reserved character, a line break, a null
+   * byte, or an invalid UTF-8 byte sequence. Accept the empty string. Use for
+   * optionally-empty value strings (e.g. a custom parameter's free-form value).
+   *
+   * @throws {CefFormatException}
+   */
+  export function assertNoReservedNorLineBreak(value: string, context: string): void {
+    assertSafeText(value, context);
+
+    for (const reserved of RESERVED_CHARACTERS) {
+      if (value.includes(reserved)) {
+        throw new ReservedCharacterException(
+          `${context} cannot contain the reserved character "${reserved}".`
+        );
+      }
+    }
+  }
+
+  /**
+   * Inline comments are free-form text but must stay on a single line and
+   * contain only valid UTF-8 (with no null byte).
+   *
+   * @throws {CefFormatException}
+   */
+  export function assertSingleLine(value: string, context: string): void {
+    assertSafeText(value, context);
+  }
+
+  /**
+   * Reject any value that contains the `||` tag separator.
+   *
+   * The separator is the only forbidden pattern that per-character validation
+   * cannot catch on its own, because `|` is not itself a reserved character.
+   * Both ranking strings and tag values rely on this check.
+   *
+   * @throws {CefFormatException}
+   */
+  export function assertNoTagSeparator(value: string, context: string): void {
+    if (value.includes(TAGS_SEPARATOR)) {
+      throw new ReservedCharacterException(
+        `${context} cannot contain the "${TAGS_SEPARATOR}" tag separator.`
+      );
+    }
+  }
+
+  /**
+   * Verify that `value` is valid UTF-8, single-line, and contains no null byte.
+   * Shared base for every value-bound assertion above.
+   *
+   * UTF-8 validity is checked by rejecting ill-formed strings — those carrying
+   * an unpaired UTF-16 surrogate, which cannot be encoded to well-formed
+   * UTF-8. This is the TypeScript analog of PHP's `mb_check_encoding()`.
+   *
+   * @throws {CefFormatException}
+   */
+  function assertSafeText(value: string, context: string): void {
+    if (!isWellFormedUtf16(value)) {
+      throw new InvalidUtf8Exception(`${context} contains an invalid UTF-8 byte sequence.`);
+    }
+
+    if (/[\r\n]/.test(value)) {
+      throw new InvalidValueException(`${context} cannot contain a line break.`);
+    }
+
+    if (value.includes('\0')) {
+      throw new InvalidValueException(`${context} cannot contain a null byte.`);
+    }
+  }
+
+  /**
+   * Return `true` when every UTF-16 surrogate in `value` is correctly paired,
+   * i.e. the string can be encoded to well-formed UTF-8.
+   */
+  function isWellFormedUtf16(value: string): boolean {
+    for (let i = 0; i < value.length; i++) {
+      const code = value.charCodeAt(i);
+
+      if (code >= 0xd800 && code <= 0xdbff) {
+        // High surrogate: must be immediately followed by a low surrogate.
+        const next = value.charCodeAt(i + 1);
+
+        if (Number.isNaN(next) || next < 0xdc00 || next > 0xdfff) {
+          return false;
+        }
+
+        i++;
+      } else if (code >= 0xdc00 && code <= 0xdfff) {
+        // Lone low surrogate.
+        return false;
+      }
+    }
+
+    return true;
+  }
+}

package/src/CommentLine.ts

@@ -0,0 +1,32 @@
+import { CefFormat } from './CefFormat';
+
+/**
+ * A standalone comment line (`# text`).
+ *
+ * Inline comments attached to vote lines are not represented by this class —
+ * they live on `VoteLine.inlineComment` instead.
+ */
+export class CommentLine {
+  public readonly text: string;
+
+  /**
+   * @throws {CefFormatException}
+   */
+  public constructor(text: string) {
+    CefFormat.assertSingleLine(text, 'Comment');
+    this.text = text;
+  }
+
+  /**
+   * Render the line *without* trailing newline.
+   */
+  public format(autoFormat = true): string {
+    if (this.text === '') {
+      return '#';
+    }
+
+    const needsLeadingSpace = autoFormat && !this.text.startsWith(' ');
+
+    return '#' + (needsLeadingSpace ? ' ' : '') + this.text;
+  }
+}

package/src/Exception/CefFormatException.ts

@@ -0,0 +1,19 @@
+/**
+ * Base class for every input/format violation thrown by the library.
+ *
+ * Catch this class to handle any format-related failure uniformly; catch one
+ * of the dedicated subclasses ({@link InvalidUtf8Exception},
+ * {@link ReservedCharacterException}, {@link InvalidValueException},
+ * {@link DuplicateCandidateException}, {@link InvalidWriterStateException}) to
+ * branch on a specific kind of violation.
+ *
+ * Non-final on purpose so the library and downstream callers can refine the
+ * hierarchy further if needed.
+ */
+export class CefFormatException extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/Exception/CefWriteException.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown when writing to the underlying target (a file or string buffer) fails.
+ * Distinct from {@link CefFormatException} because the cause is the I/O layer —
+ * disk full, broken pipe, closed handle, read-only file — not an invalid input
+ * from the caller.
+ */
+export class CefWriteException extends Error {
+  public constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/Exception/DuplicateCandidateException.ts

@@ -0,0 +1,8 @@
+import { CefFormatException } from './CefFormatException';
+
+/**
+ * Thrown when the same candidate label appears more than once where the CEF
+ * specification forbids it — either in `#/Candidates:` or in a single vote's
+ * ranking (across tied groups included).
+ */
+export class DuplicateCandidateException extends CefFormatException {}

package/src/Exception/InvalidUtf8Exception.ts

@@ -0,0 +1,12 @@
+import { CefFormatException } from './CefFormatException';
+
+/**
+ * Thrown when a value contains a byte sequence that does not decode as valid
+ * UTF-8. The CEF specification mandates UTF-8, so any non-UTF-8 input is
+ * rejected before it can land in the output stream.
+ *
+ * In this TypeScript port — where strings are sequences of UTF-16 code units —
+ * "non-UTF-8" means an ill-formed string carrying an unpaired surrogate, which
+ * cannot be encoded to well-formed UTF-8.
+ */
+export class InvalidUtf8Exception extends CefFormatException {}

package/src/Exception/InvalidValueException.ts

@@ -0,0 +1,14 @@
+import { CefFormatException } from './CefFormatException';
+
+/**
+ * Thrown when a value is structurally impossible at the CEF level — regardless
+ * of which reserved/UTF-8 rule it would otherwise hit.
+ *
+ * Typical triggers:
+ *   - empty string where one is required (candidate name, tag, parameter name);
+ *   - embedded line break or null byte;
+ *   - non-positive `weight` or `quantifier`;
+ *   - empty list when one or more entries are required (candidates, methods);
+ *   - empty rank inside a ranking.
+ */
+export class InvalidValueException extends CefFormatException {}

package/src/Exception/InvalidWriterStateException.ts

@@ -0,0 +1,13 @@
+import { CefFormatException } from './CefFormatException';
+
+/**
+ * Thrown when the streaming writer is asked to perform an operation that does
+ * not fit its current internal state.
+ *
+ * Typical triggers:
+ *   - adding a parameter after the first vote has been emitted;
+ *   - constructing a `Cef` with neither a file nor a string target, or with
+ *     both at once;
+ *   - parsing a vote-line string that ends up without a ranking.
+ */
+export class InvalidWriterStateException extends CefFormatException {}

package/src/Exception/ReservedCharacterException.ts

@@ -0,0 +1,11 @@
+import { CefFormatException } from './CefFormatException';
+
+/**
+ * Thrown when a value contains a character that the CEF format reserves for
+ * structural use and therefore forbids inside any value.
+ *
+ * Covers the eight spec-listed reserved characters (`> = ; , # / * ^`) as well
+ * as the secondary syntactic separators the library enforces: `:` in a custom
+ * parameter name, `||` in a tag, and a leading `#` on a raw vote line.
+ */
+export class ReservedCharacterException extends CefFormatException {}

package/src/Exception/index.ts

@@ -0,0 +1,7 @@
+export { CefFormatException } from './CefFormatException';
+export { CefWriteException } from './CefWriteException';
+export { DuplicateCandidateException } from './DuplicateCandidateException';
+export { InvalidUtf8Exception } from './InvalidUtf8Exception';
+export { InvalidValueException } from './InvalidValueException';
+export { InvalidWriterStateException } from './InvalidWriterStateException';
+export { ReservedCharacterException } from './ReservedCharacterException';