@condorcet.vote/cef-writer 1.2.0

package/dist/VoteLine.js

@@ -0,0 +1,289 @@
+import { CefFormat } from './CefFormat';
+import { InvalidValueException, InvalidWriterStateException } from './Exception';
+import { Ranking } from './Ranking';
+/**
+ * A single ballot.
+ *
+ * Instances are never built with `new`: use one of the static named
+ * constructors — {@link fromRanking} (typed ranks or a {@link Ranking}),
+ * {@link fromString} (a full CEF vote-line string), or
+ * {@link fromRawRankingString} (a pre-validated *verbatim* ranking string).
+ *
+ * The ranking is held as a {@link Ranking} value object on {@link ranking}. An
+ * empty ranking renders as the `/EMPTY_RANKING/` blank-ballot sentinel. In the
+ * verbatim mode the ranking string is written untouched and is *not* parsed,
+ * so {@link ranking} is `null`.
+ *
+ * Optional companions:
+ *   - `tags`          — labels separated by `,`, appended before `||`;
+ *   - `weight`        — strictly positive integer; only meaningful when the
+ *                       `Weight Allowed` parameter is enabled in the document;
+ *   - `quantifier`    — strictly positive integer that collapses identical
+ *                       votes onto a single line;
+ *   - `inlineComment` — free-form trailing comment introduced by `#`.
+ */
+export class VoteLine {
+    /**
+     * The parsed ranking, or `null` when the ballot was built from a verbatim
+     * ranking string via {@link fromRawRankingString} — in that mode the ranking
+     * is deliberately *not* parsed into a {@link Ranking} structure.
+     */
+    ranking;
+    /**
+     * Verbatim, pre-validated ranking string written to the output untouched.
+     * Set only in the {@link fromRawRankingString} mode; `null` otherwise (when
+     * {@link ranking} carries the parsed structure instead).
+     */
+    rawRanking;
+    tags;
+    weight;
+    quantifier;
+    inlineComment;
+    /**
+     * @internal Use a static named constructor instead: {@link fromRanking},
+     *           {@link fromString} or {@link fromRawRankingString}.
+     *
+     * @throws {CefFormatException} on any specification violation
+     */
+    constructor(ranking, verbatim, tags = [], weight = null, quantifier = null, inlineComment = null) {
+        if (verbatim) {
+            // Verbatim mode: validate the ranking string but skip parsing it into a
+            // Ranking — it is written as-is by format().
+            if (typeof ranking !== 'string') {
+                throw new InvalidWriterStateException('Verbatim mode requires a ranking string.');
+            }
+            Ranking.assertValidString(ranking);
+            this.ranking = null;
+            this.rawRanking = ranking.trim();
+        }
+        else {
+            if (!(ranking instanceof Ranking)) {
+                throw new InvalidWriterStateException('Non-verbatim mode requires a Ranking instance.');
+            }
+            this.ranking = ranking;
+            this.rawRanking = null;
+        }
+        this.tags = VoteLine.validateTags(tags);
+        VoteLine.assertCompanions(weight, quantifier);
+        if (inlineComment !== null) {
+            CefFormat.assertSingleLine(inlineComment, 'Inline comment');
+        }
+        this.weight = weight;
+        this.quantifier = quantifier;
+        this.inlineComment = inlineComment;
+    }
+    /**
+     * Build a {@link VoteLine} from typed ranks or a ready-made {@link Ranking}.
+     *
+     * This is the primary, typed constructor. The `ranking` argument is either an
+     * ordered list of ranks (each inner list a non-empty group of tied
+     * candidates; pass `[]` for the `/EMPTY_RANKING/` blank ballot) or a
+     * {@link Ranking} value object.
+     *
+     * @throws {CefFormatException} on any specification violation
+     */
+    static fromRanking(ranking, options = {}) {
+        return new VoteLine(ranking instanceof Ranking ? ranking : new Ranking(ranking), false, options.tags ?? [], options.weight ?? null, options.quantifier ?? null, options.inlineComment ?? null);
+    }
+    /**
+     * Build a {@link VoteLine} from a raw CEF vote-line string.
+     *
+     * Accepted shape — every component except the ranking is optional:
+     *
+     *     [tag1, tag2 || ] ranking [ ^weight] [ *quantifier] [# comment]
+     *
+     * Both the relaxed and the compact spacing flavors are accepted, e.g.
+     * `"A>B^7*2"` and `"A > B ^7 * 2"` parse identically. The `/EMPTY_RANKING/`
+     * sentinel is recognised as a blank ballot.
+     *
+     * The string is parsed into its components; the resulting `VoteLine` is then
+     * constructed through the normal constructor, so every validation rule
+     * (reserved characters, empty rank, duplicate candidate, positive weight /
+     * quantifier) applies.
+     *
+     * @throws {CefFormatException}
+     */
+    static fromString(line) {
+        const parts = VoteLine.parseStringComponents(line);
+        return new VoteLine(parts.ranking, false, parts.tags, parts.weight, parts.quantifier, parts.inlineComment);
+    }
+    /**
+     * Validate that `line` is a syntactically valid CEF vote line, without
+     * allocating a `VoteLine` instance.
+     *
+     * The exact same parsing and validation pipeline that {@link fromString} uses
+     * is applied — only the final object construction is skipped. Useful for hot
+     * paths that want to write a pre-built line straight to the output after a
+     * strict format check.
+     *
+     * @throws {CefFormatException}
+     */
+    static assertValidString(line) {
+        VoteLine.parseStringComponents(line);
+    }
+    /**
+     * Build a {@link VoteLine} from a ranking-only string, kept *verbatim*.
+     *
+     * The special, allocation-light sibling of {@link fromRanking}: the ranking
+     * string is validated as a ranking and *nothing else* — any reserved
+     * character (`^`, `*`, `#`, `;`, `,`, `/`), the `||` tag separator, or a line
+     * break is rejected, so it cannot smuggle a weight, quantifier, tag or inline
+     * comment — but it is **not** parsed into a {@link Ranking}. The string is
+     * stored as-is and written untouched by {@link format} (only the
+     * library-built companions — the `||` separator, `^weight`, `*quantifier` —
+     * follow `autoFormat`). The resulting instance therefore has a `null`
+     * {@link ranking}. Used by `Cef.addRawVote()`.
+     *
+     * @throws {CefFormatException}
+     */
+    static fromRawRankingString(ranking, options = {}) {
+        return new VoteLine(ranking, true, options.tags ?? [], options.weight ?? null, options.quantifier ?? null);
+    }
+    /**
+     * Shared parser+validator used by {@link fromString} and
+     * {@link assertValidString}.
+     *
+     * Trims the input, extracts every component, and runs the same per-field
+     * validation (reserved characters, empty rank, duplicate candidate, positive
+     * weight / quantifier, single-line comment) that the constructor performs.
+     * Returns the components.
+     *
+     * @throws {CefFormatException}
+     */
+    static parseStringComponents(line) {
+        const original = line;
+        let work = line.trim();
+        if (work === '') {
+            throw new InvalidValueException('Vote line string cannot be empty.');
+        }
+        let inlineComment = null;
+        const hashPos = work.indexOf('#');
+        if (hashPos !== -1) {
+            let after = work.slice(hashPos + 1);
+            if (after.startsWith(' ')) {
+                after = after.slice(1);
+            }
+            after = VoteLine.rtrim(after);
+            inlineComment = after !== '' ? after : null;
+            work = VoteLine.rtrim(work.slice(0, hashPos));
+        }
+        if (inlineComment !== null) {
+            CefFormat.assertSingleLine(inlineComment, 'Inline comment');
+        }
+        const rawTags = [];
+        const separator = CefFormat.TAGS_SEPARATOR;
+        const separatorPos = work.indexOf(separator);
+        if (separatorPos !== -1) {
+            const tagsPart = work.slice(0, separatorPos);
+            work = work.slice(separatorPos + separator.length).trim();
+            for (const rawTag of tagsPart.split(',')) {
+                rawTags.push(rawTag.trim());
+            }
+        }
+        let weight = null;
+        let quantifier = null;
+        const matches = /^([\s\S]*?)(?:\s*\^\s*(\d+))?(?:\s*\*\s*(\d+))?\s*$/.exec(work);
+        if (matches !== null) {
+            work = matches[1].trim();
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (matches[2] !== undefined) {
+                weight = Number.parseInt(matches[2], 10);
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (matches[3] !== undefined) {
+                quantifier = Number.parseInt(matches[3], 10);
+            }
+        }
+        if (weight !== null && weight < 1) {
+            throw new InvalidValueException('Weight must be a positive integer.');
+        }
+        if (quantifier !== null && quantifier < 1) {
+            throw new InvalidValueException('Quantifier must be a positive integer.');
+        }
+        if (work === '') {
+            throw new InvalidWriterStateException(`Vote line "${original.trim()}" has no ranking.`);
+        }
+        return {
+            ranking: Ranking.fromString(work),
+            tags: VoteLine.validateTags(rawTags),
+            weight,
+            quantifier,
+            inlineComment,
+        };
+    }
+    /**
+     * Render the ballot — *without* trailing newline or inline comment — using
+     * the spacing flavor selected by `autoFormat`.
+     */
+    format(autoFormat = true) {
+        return this.assembleLine(this.renderRanking(autoFormat), autoFormat);
+    }
+    /**
+     * Return the ranking part of the line: the verbatim string in raw mode, or
+     * the parsed ranking rendered with `autoFormat` otherwise.
+     */
+    renderRanking(autoFormat) {
+        if (this.rawRanking !== null) {
+            return this.rawRanking;
+        }
+        if (this.ranking === null) {
+            throw new InvalidWriterStateException('VoteLine has neither a parsed ranking nor a verbatim ranking string.');
+        }
+        return this.ranking.format(autoFormat);
+    }
+    /**
+     * Reject a non-null, non-positive weight or quantifier.
+     *
+     * @throws {CefFormatException}
+     */
+    static assertCompanions(weight, quantifier) {
+        if (weight !== null && (!Number.isInteger(weight) || weight < 1)) {
+            throw new InvalidValueException('Weight must be a positive integer.');
+        }
+        if (quantifier !== null && (!Number.isInteger(quantifier) || quantifier < 1)) {
+            throw new InvalidValueException('Quantifier must be a positive integer.');
+        }
+    }
+    /**
+     * Wrap a ranking string with the tag prefix and the weight / quantifier
+     * suffix, using the spacing flavor selected by `autoFormat`.
+     */
+    assembleLine(ranking, autoFormat) {
+        let line = '';
+        if (this.tags.length > 0) {
+            const tagSeparator = autoFormat ? ', ' : ',';
+            line += this.tags.join(tagSeparator);
+            line += autoFormat ? ' || ' : '||';
+        }
+        line += ranking;
+        if (this.weight !== null) {
+            line += autoFormat ? ' ^' + String(this.weight) : '^' + String(this.weight);
+        }
+        if (this.quantifier !== null) {
+            line += autoFormat ? ' * ' + String(this.quantifier) : '*' + String(this.quantifier);
+        }
+        return line;
+    }
+    /**
+     * @throws {CefFormatException}
+     */
+    static validateTags(tags) {
+        const cleaned = [];
+        for (const tag of tags) {
+            const trimmed = tag.trim();
+            if (trimmed === '') {
+                throw new InvalidValueException('Tag cannot be empty.');
+            }
+            CefFormat.assertNoTagSeparator(trimmed, 'Tag');
+            CefFormat.assertValueIsClean(trimmed, 'Tag');
+            cleaned.push(trimmed);
+        }
+        return cleaned;
+    }
+    /**
+     * Strip trailing whitespace, mirroring PHP's `rtrim()`.
+     */
+    static rtrim(value) {
+        return value.replace(/\s+$/, '');
+    }
+}

package/dist/index.browser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CEF Writer — a TypeScript library that streams valid Condorcet Election
+ * Format (CEF) documents to a string buffer with a friendly object API.
+ *
+ * This is the browser-only entry point. For Node.js usage, import from the
+ * main export which includes {@link FileWriteTarget} for file system access.
+ *
+ * TypeScript port of {@link https://github.com/CondorcetVote/CEF-Writer | CondorcetVote/CEF-Writer}.
+ */
+export { Cef, StringBuffer, type CefOptions, type WriteTarget } from './Cef';
+export { CefFormat } from './CefFormat';
+export { CommentLine } from './CommentLine';
+export { Ranking } from './Ranking';
+export { VoteLine } from './VoteLine';
+export { CefFormatException, CefWriteException, DuplicateCandidateException, InvalidUtf8Exception, InvalidValueException, InvalidWriterStateException, ReservedCharacterException, } from './Exception';
+export { CandidatesParameter, CustomParameter, ImplicitRankingParameter, NumberOfSeatsParameter, StandardParameter, VotingMethodsParameter, WeightAllowedParameter, type ParameterInterface, } from './Parameter';
+//# sourceMappingURL=index.browser.d.ts.map

package/dist/index.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,OAAO,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.browser.js

@@ -0,0 +1,16 @@
+/**
+ * CEF Writer — a TypeScript library that streams valid Condorcet Election
+ * Format (CEF) documents to a string buffer with a friendly object API.
+ *
+ * This is the browser-only entry point. For Node.js usage, import from the
+ * main export which includes {@link FileWriteTarget} for file system access.
+ *
+ * TypeScript port of {@link https://github.com/CondorcetVote/CEF-Writer | CondorcetVote/CEF-Writer}.
+ */
+export { Cef, StringBuffer } from './Cef';
+export { CefFormat } from './CefFormat';
+export { CommentLine } from './CommentLine';
+export { Ranking } from './Ranking';
+export { VoteLine } from './VoteLine';
+export { CefFormatException, CefWriteException, DuplicateCandidateException, InvalidUtf8Exception, InvalidValueException, InvalidWriterStateException, ReservedCharacterException, } from './Exception';
+export { CandidatesParameter, CustomParameter, ImplicitRankingParameter, NumberOfSeatsParameter, StandardParameter, VotingMethodsParameter, WeightAllowedParameter, } from './Parameter';

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CEF Writer — default export for Node.js environments.
+ *
+ * For browser usage, import from `@condorcet.vote/cef-writer/browser` instead.
+ * See {@link https://github.com/CondorcetVote/CEF-Writer-Typescript#browser-usage | browser usage documentation}.
+ */
+export * from './index.node';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * CEF Writer — default export for Node.js environments.
+ *
+ * For browser usage, import from `@condorcet.vote/cef-writer/browser` instead.
+ * See {@link https://github.com/CondorcetVote/CEF-Writer-Typescript#browser-usage | browser usage documentation}.
+ */
+export * from './index.node';

package/dist/index.node.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CEF Writer — a TypeScript library that streams valid Condorcet Election
+ * Format (CEF) documents to a file or string buffer with a friendly object API.
+ *
+ * This is the Node.js entry point with full file system support via
+ * {@link FileWriteTarget}. For browser-only usage, import from
+ * `@condorcet.vote/cef-writer/browser` which excludes Node.js dependencies.
+ *
+ * TypeScript port of {@link https://github.com/CondorcetVote/CEF-Writer | CondorcetVote/CEF-Writer}.
+ */
+export { Cef, StringBuffer, type CefOptions, type WriteTarget } from './Cef';
+export { FileWriteTarget } from './FileWriteTarget';
+export { CefFormat } from './CefFormat';
+export { CommentLine } from './CommentLine';
+export { Ranking } from './Ranking';
+export { VoteLine } from './VoteLine';
+export { CefFormatException, CefWriteException, DuplicateCandidateException, InvalidUtf8Exception, InvalidValueException, InvalidWriterStateException, ReservedCharacterException, } from './Exception';
+export { CandidatesParameter, CustomParameter, ImplicitRankingParameter, NumberOfSeatsParameter, StandardParameter, VotingMethodsParameter, WeightAllowedParameter, type ParameterInterface, } from './Parameter';
+//# sourceMappingURL=index.node.d.ts.map

package/dist/index.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.node.d.ts","sourceRoot":"","sources":["../src/index.node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,OAAO,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.node.js

@@ -0,0 +1,25 @@
+/**
+ * CEF Writer — a TypeScript library that streams valid Condorcet Election
+ * Format (CEF) documents to a file or string buffer with a friendly object API.
+ *
+ * This is the Node.js entry point with full file system support via
+ * {@link FileWriteTarget}. For browser-only usage, import from
+ * `@condorcet.vote/cef-writer/browser` which excludes Node.js dependencies.
+ *
+ * TypeScript port of {@link https://github.com/CondorcetVote/CEF-Writer | CondorcetVote/CEF-Writer}.
+ */
+import { Cef } from './Cef';
+import { FileWriteTarget } from './FileWriteTarget';
+// Wire the file-path convenience for Node.js. This is the side effect that
+// makes `new Cef({ file: '/some/path' })` work; the browser entry point omits
+// it, keeping `node:fs` out of browser bundles. Marked in package.json's
+// `sideEffects` so bundlers never tree-shake this registration away.
+Cef.fileWriteTargetFactory = (path) => new FileWriteTarget(path);
+export { Cef, StringBuffer } from './Cef';
+export { FileWriteTarget } from './FileWriteTarget';
+export { CefFormat } from './CefFormat';
+export { CommentLine } from './CommentLine';
+export { Ranking } from './Ranking';
+export { VoteLine } from './VoteLine';
+export { CefFormatException, CefWriteException, DuplicateCandidateException, InvalidUtf8Exception, InvalidValueException, InvalidWriterStateException, ReservedCharacterException, } from './Exception';
+export { CandidatesParameter, CustomParameter, ImplicitRankingParameter, NumberOfSeatsParameter, StandardParameter, VotingMethodsParameter, WeightAllowedParameter, } from './Parameter';

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@condorcet.vote/cef-writer",
+  "version": "1.2.0",
+  "description": "Streaming TypeScript writer that produces valid Condorcet Election Format (CEF) documents line by line. A faithful port of CondorcetVote/CEF-Writer.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": [
+    "./dist/index.node.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.browser.js",
+      "node": "./dist/index.node.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/index.browser.d.ts",
+      "browser": "./dist/index.browser.js",
+      "import": "./dist/index.browser.js",
+      "default": "./dist/index.browser.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
+  },
+  "packageManager": "bun@latest",
+  "keywords": [
+    "cef",
+    "condorcet",
+    "election",
+    "condorcet-election-format",
+    "voting",
+    "writer",
+    "typescript"
+  ],
+  "author": "Julien Boudry",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CondorcetVote/CEF-Writer-Typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CondorcetVote/CEF-Writer-Typescript/issues"
+  },
+  "homepage": "https://github.com/CondorcetVote/CEF-Writer-Typescript#readme",
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@types/bun": "1.3.14",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^10.4.1",
+    "prettier": "^3.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "8.61.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}