@condorcet.vote/cef-writer 1.2.0

package/src/FileWriteTarget.ts

@@ -0,0 +1,42 @@
+import * as fs from 'node:fs';
+
+import type { WriteTarget } from './Cef';
+
+/**
+ * A {@link WriteTarget} backed by a real file descriptor, opened in truncating
+ * write mode. Created automatically when a filesystem path is passed to the
+ * {@link Cef} constructor in Node.js environments.
+ *
+ * **Note**: This class is only available in Node.js environments. Browser users
+ * must use {@link StringBuffer} or provide a custom {@link WriteTarget}.
+ *
+ * @example
+ * ```typescript
+ * import { Cef, FileWriteTarget } from '@condorcet.vote/cef-writer';
+ *
+ * const target = new FileWriteTarget('/tmp/election.cvotes');
+ * const cef = new Cef({ file: target });
+ * // ... add parameters and votes
+ * cef.close();
+ * ```
+ */
+export class FileWriteTarget implements WriteTarget {
+  private readonly fd: number;
+
+  private closed = false;
+
+  public constructor(path: string) {
+    this.fd = fs.openSync(path, 'w');
+  }
+
+  public write(chunk: string): number {
+    return fs.writeSync(this.fd, Buffer.from(chunk, 'utf-8'));
+  }
+
+  public close(): void {
+    if (!this.closed) {
+      fs.closeSync(this.fd);
+      this.closed = true;
+    }
+  }
+}

package/src/Parameter/CandidatesParameter.ts

@@ -0,0 +1,49 @@
+import { CefFormat } from '../CefFormat';
+import { DuplicateCandidateException, InvalidValueException } from '../Exception';
+import type { ParameterInterface } from './ParameterInterface';
+import { StandardParameter } from './StandardParameter';
+
+/**
+ * `#/Candidates:` parameter — declares the official list of candidates.
+ *
+ * Candidate names are written separated by `;`. With auto-format on, the
+ * separator is padded with spaces (`A ; B ; C`) for readability; otherwise the
+ * most compact form (`A;B;C`) is used.
+ */
+export class CandidatesParameter implements ParameterInterface {
+  public readonly candidates: readonly string[];
+
+  /**
+   * @param candidates non-empty list of distinct candidate names
+   *
+   * @throws {CefFormatException}
+   */
+  public constructor(candidates: readonly string[]) {
+    if (candidates.length === 0) {
+      throw new InvalidValueException('Candidates list cannot be empty.');
+    }
+
+    const seen = new Set<string>();
+
+    for (const candidate of candidates) {
+      const trimmed = candidate.trim();
+      CefFormat.assertValueIsClean(trimmed, 'Candidate name');
+
+      if (seen.has(trimmed)) {
+        throw new DuplicateCandidateException(`Duplicate candidate "${trimmed}".`);
+      }
+
+      seen.add(trimmed);
+    }
+
+    this.candidates = candidates.map((candidate) => candidate.trim());
+  }
+
+  public getName(): string {
+    return StandardParameter.Candidates;
+  }
+
+  public getFormattedValue(autoFormat = true): string {
+    return this.candidates.join(autoFormat ? ' ; ' : ';');
+  }
+}

package/src/Parameter/CustomParameter.ts

@@ -0,0 +1,45 @@
+import { CefFormat } from '../CefFormat';
+import { InvalidValueException, ReservedCharacterException } from '../Exception';
+import type { ParameterInterface } from './ParameterInterface';
+
+/**
+ * Free-form parameter for tooling that extends CEF with project-specific keys.
+ *
+ * The name must avoid every reserved character and `:`, since `:` separates a
+ * parameter from its value. The value must avoid line breaks but is otherwise
+ * free-form (the spec only reserves characters for *structured* values).
+ */
+export class CustomParameter implements ParameterInterface {
+  public readonly name: string;
+
+  public readonly value: string;
+
+  /**
+   * @throws {CefFormatException}
+   */
+  public constructor(name: string, value: string) {
+    const trimmedName = name.trim();
+
+    if (trimmedName === '') {
+      throw new InvalidValueException('Custom parameter name cannot be empty.');
+    }
+
+    if (trimmedName.includes(':')) {
+      throw new ReservedCharacterException('Custom parameter name cannot contain ":".');
+    }
+
+    CefFormat.assertValueIsClean(trimmedName, 'Custom parameter name');
+    CefFormat.assertNoReservedNorLineBreak(value, 'Custom parameter value');
+
+    this.name = trimmedName;
+    this.value = value;
+  }
+
+  public getName(): string {
+    return this.name;
+  }
+
+  public getFormattedValue(_autoFormat = true): string {
+    return this.value;
+  }
+}

package/src/Parameter/ImplicitRankingParameter.ts

@@ -0,0 +1,17 @@
+import type { ParameterInterface } from './ParameterInterface';
+import { StandardParameter } from './StandardParameter';
+
+/**
+ * `#/Implicit Ranking:` parameter — boolean toggle.
+ */
+export class ImplicitRankingParameter implements ParameterInterface {
+  public constructor(public readonly enabled: boolean) {}
+
+  public getName(): string {
+    return StandardParameter.ImplicitRanking;
+  }
+
+  public getFormattedValue(_autoFormat = true): string {
+    return this.enabled ? 'true' : 'false';
+  }
+}

package/src/Parameter/NumberOfSeatsParameter.ts

@@ -0,0 +1,25 @@
+import { InvalidValueException } from '../Exception';
+import type { ParameterInterface } from './ParameterInterface';
+import { StandardParameter } from './StandardParameter';
+
+/**
+ * `#/Number of Seats:` parameter — strictly positive integer.
+ */
+export class NumberOfSeatsParameter implements ParameterInterface {
+  /**
+   * @throws {CefFormatException}
+   */
+  public constructor(public readonly seats: number) {
+    if (!Number.isInteger(seats) || seats < 1) {
+      throw new InvalidValueException('Number of seats must be a positive integer.');
+    }
+  }
+
+  public getName(): string {
+    return StandardParameter.NumberOfSeats;
+  }
+
+  public getFormattedValue(_autoFormat = true): string {
+    return String(this.seats);
+  }
+}

package/src/Parameter/ParameterInterface.ts

@@ -0,0 +1,20 @@
+/**
+ * Contract every parameter object (standard or custom) must implement.
+ *
+ * A parameter knows how to render its own *name* and *value* but not how to
+ * assemble the final line: line assembly is the responsibility of the writer,
+ * which decides spacing based on the `autoFormat` flag.
+ */
+export interface ParameterInterface {
+  /**
+   * The parameter name, as it must appear after the `#/` prefix.
+   */
+  getName(): string;
+
+  /**
+   * The parameter value, already serialized but **without** the surrounding
+   * `#/Name: ` prefix. The boolean `autoFormat` flag lets the parameter choose
+   * whether to expand its value with optional whitespace.
+   */
+  getFormattedValue(autoFormat?: boolean): string;
+}

package/src/Parameter/StandardParameter.ts

@@ -0,0 +1,13 @@
+/**
+ * Enumeration of the parameter names defined by the CEF specification.
+ *
+ * The string value of each case is the exact, case-correct name that must
+ * appear after the `#/` prefix in the generated file.
+ */
+export enum StandardParameter {
+  Candidates = 'Candidates',
+  NumberOfSeats = 'Number of Seats',
+  ImplicitRanking = 'Implicit Ranking',
+  VotingMethods = 'Voting Methods',
+  WeightAllowed = 'Weight Allowed',
+}

package/src/Parameter/VotingMethodsParameter.ts

@@ -0,0 +1,36 @@
+import { CefFormat } from '../CefFormat';
+import { InvalidValueException } from '../Exception';
+import type { ParameterInterface } from './ParameterInterface';
+import { StandardParameter } from './StandardParameter';
+
+/**
+ * `#/Voting Methods:` parameter — list of method identifiers separated by `;`.
+ */
+export class VotingMethodsParameter implements ParameterInterface {
+  public readonly methods: readonly string[];
+
+  /**
+   * @param methods non-empty list of method names
+   *
+   * @throws {CefFormatException}
+   */
+  public constructor(methods: readonly string[]) {
+    if (methods.length === 0) {
+      throw new InvalidValueException('Voting methods list cannot be empty.');
+    }
+
+    for (const method of methods) {
+      CefFormat.assertValueIsClean(method.trim(), 'Voting method name');
+    }
+
+    this.methods = methods.map((method) => method.trim());
+  }
+
+  public getName(): string {
+    return StandardParameter.VotingMethods;
+  }
+
+  public getFormattedValue(autoFormat = true): string {
+    return this.methods.join(autoFormat ? ' ; ' : ';');
+  }
+}

package/src/Parameter/WeightAllowedParameter.ts

@@ -0,0 +1,17 @@
+import type { ParameterInterface } from './ParameterInterface';
+import { StandardParameter } from './StandardParameter';
+
+/**
+ * `#/Weight Allowed:` parameter — boolean toggle.
+ */
+export class WeightAllowedParameter implements ParameterInterface {
+  public constructor(public readonly enabled: boolean) {}
+
+  public getName(): string {
+    return StandardParameter.WeightAllowed;
+  }
+
+  public getFormattedValue(_autoFormat = true): string {
+    return this.enabled ? 'true' : 'false';
+  }
+}

package/src/Parameter/index.ts

@@ -0,0 +1,8 @@
+export { CandidatesParameter } from './CandidatesParameter';
+export { CustomParameter } from './CustomParameter';
+export { ImplicitRankingParameter } from './ImplicitRankingParameter';
+export { NumberOfSeatsParameter } from './NumberOfSeatsParameter';
+export type { ParameterInterface } from './ParameterInterface';
+export { StandardParameter } from './StandardParameter';
+export { VotingMethodsParameter } from './VotingMethodsParameter';
+export { WeightAllowedParameter } from './WeightAllowedParameter';

package/src/Ranking.ts

@@ -0,0 +1,197 @@
+import { CefFormat } from './CefFormat';
+import { DuplicateCandidateException, InvalidValueException } from './Exception';
+
+/**
+ * An ordered ranking of candidates.
+ *
+ * The ranking is expressed as an ordered list of ranks; each rank is itself a
+ * list of candidate names tied at that position. An empty top-level ranking
+ * (`[]`) renders as the `/EMPTY_RANKING/` blank-ballot sentinel.
+ *
+ * A `Ranking` is immutable and self-validating: any specification violation
+ * (reserved character, empty rank, duplicate candidate) throws a
+ * {@link CefFormatException} at construction time. Render it to a CEF string
+ * with {@link format} (or by casting to `string` via {@link toString}).
+ */
+export class Ranking {
+  public readonly ranks: readonly (readonly string[])[];
+
+  /**
+   * @param ranks Ordered ranks; each inner list is non-empty. Pass `[]` for
+   *              the `/EMPTY_RANKING/` blank ballot.
+   *
+   * @throws {CefFormatException} on any specification violation
+   */
+  public constructor(ranks: readonly (readonly string[])[]) {
+    this.ranks = Ranking.validate(ranks);
+  }
+
+  /**
+   * Build a {@link Ranking} from a ranking-only string.
+   *
+   * The string may contain candidate names joined by the `>` (rank) and `=`
+   * (tie) operators, or the `/EMPTY_RANKING/` sentinel. Any reserved character
+   * (`^`, `*`, `#`, `;`, `,`, `/`), the `||` tag separator, or a line break is
+   * rejected — there is no way to smuggle a weight, quantifier, tag or inline
+   * comment through the string.
+   *
+   * @param ranking Ranking only, e.g. `"A > B = C"` or `"/EMPTY_RANKING/"`.
+   *
+   * @throws {CefFormatException}
+   */
+  public static fromString(ranking: string): Ranking {
+    return new Ranking(Ranking.split(Ranking.normalizeString(ranking)));
+  }
+
+  /**
+   * Validate a ranking-only string without allocating a {@link Ranking}.
+   *
+   * Runs the exact same checks as {@link fromString} (empty input, `||` tag
+   * separator, reserved characters, line breaks, duplicate candidates) but
+   * never materialises the parsed structure nor a `Ranking` instance — useful
+   * for hot paths that write the ranking string verbatim after a strict format
+   * check.
+   *
+   * @param ranking Ranking only, e.g. `"A > B = C"` or `"/EMPTY_RANKING/"`.
+   *
+   * @throws {CefFormatException}
+   */
+  public static assertValidString(ranking: string): void {
+    const work = Ranking.normalizeString(ranking);
+
+    if (work === CefFormat.EMPTY_RANKING) {
+      return;
+    }
+
+    const seen = new Set<string>();
+
+    for (const rankString of work.split('>')) {
+      for (const candidate of rankString.split('=')) {
+        Ranking.assertCandidate(candidate, seen);
+      }
+    }
+  }
+
+  /**
+   * Trim a ranking-only string and reject the two patterns that the
+   * per-candidate validation cannot catch on its own: an empty input and the
+   * `||` tag separator. Returns the trimmed work string.
+   *
+   * @throws {CefFormatException}
+   */
+  private static normalizeString(ranking: string): string {
+    const work = ranking.trim();
+
+    if (work === '') {
+      throw new InvalidValueException(
+        'Ranking string cannot be empty; use "/EMPTY_RANKING/" for a blank ballot.'
+      );
+    }
+
+    // The "||" tag separator is the only forbidden pattern that per-candidate
+    // validation would not catch on its own ("|" is not a reserved character),
+    // so reject it explicitly here. Every reserved character and line break is
+    // rejected later, candidate by candidate.
+    CefFormat.assertNoTagSeparator(work, 'Ranking');
+
+    return work;
+  }
+
+  /**
+   * Render the ranking — *without* trailing newline, tags, weight, quantifier
+   * or inline comment — using the spacing flavor selected by `autoFormat`.
+   *
+   * When `autoFormat` is `true` (default), ranks are separated by `" > "` and
+   * tied candidates by `" = "`; when `false`, the most compact `>` / `=` form
+   * is emitted. An empty ranking yields the `/EMPTY_RANKING/` sentinel.
+   */
+  public format(autoFormat = true): string {
+    if (this.ranks.length === 0) {
+      return CefFormat.EMPTY_RANKING;
+    }
+
+    const rankSep = autoFormat ? ' > ' : '>';
+    const tieSep = autoFormat ? ' = ' : '=';
+
+    return this.ranks.map((rank) => rank.join(tieSep)).join(rankSep);
+  }
+
+  /**
+   * Render the ranking in its relaxed (auto-formatted) flavor.
+   */
+  public toString(): string {
+    return this.format();
+  }
+
+  /**
+   * Split a cleaned ranking string into its raw, *un-validated* rank/tie
+   * structure. The `/EMPTY_RANKING/` sentinel maps to an empty list. Ranks are
+   * separated by `>`, tied candidates within a rank by `=`; every token is
+   * trimmed but not otherwise checked here.
+   */
+  private static split(work: string): string[][] {
+    if (work === CefFormat.EMPTY_RANKING) {
+      return [];
+    }
+
+    const rawRanking: string[][] = [];
+
+    for (const rankString of work.split('>')) {
+      const rank: string[] = [];
+
+      for (const candidate of rankString.split('=')) {
+        rank.push(candidate.trim());
+      }
+
+      rawRanking.push(rank);
+    }
+
+    return rawRanking;
+  }
+
+  /**
+   * @throws {CefFormatException}
+   */
+  private static validate(ranks: readonly (readonly string[])[]): string[][] {
+    const cleaned: string[][] = [];
+    const seen = new Set<string>();
+
+    ranks.forEach((rank, rankIndex) => {
+      if (rank.length === 0) {
+        throw new InvalidValueException(`Rank #${String(rankIndex + 1)} is empty.`);
+      }
+
+      const cleanedRank: string[] = [];
+
+      for (const candidate of rank) {
+        cleanedRank.push(Ranking.assertCandidate(candidate, seen));
+      }
+
+      cleaned.push(cleanedRank);
+    });
+
+    return cleaned;
+  }
+
+  /**
+   * Trim and validate a single candidate name, rejecting reserved characters,
+   * line breaks, invalid UTF-8 and duplicates. The `seen` set is updated to
+   * detect repeats across the whole ranking.
+   *
+   * @throws {CefFormatException}
+   */
+  private static assertCandidate(candidate: string, seen: Set<string>): string {
+    const trimmed = candidate.trim();
+    CefFormat.assertValueIsClean(trimmed, 'Ranked candidate');
+
+    if (seen.has(trimmed)) {
+      throw new DuplicateCandidateException(
+        `Candidate "${trimmed}" appears more than once in the ranking.`
+      );
+    }
+
+    seen.add(trimmed);
+
+    return trimmed;
+  }
+}