@condorcet.vote/cef-writer 1.2.0

package/dist/Cef.js

@@ -0,0 +1,291 @@
+import { CommentLine } from './CommentLine';
+import { CefWriteException, InvalidValueException, InvalidWriterStateException, ReservedCharacterException, } from './Exception';
+import { VoteLine } from './VoteLine';
+/**
+ * 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 {
+    content = '';
+    append(chunk) {
+        this.content += chunk;
+    }
+    get value() {
+        return this.content;
+    }
+    toString() {
+        return this.content;
+    }
+}
+/**
+ * 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
+     */
+    static fileWriteTargetFactory = null;
+    autoFormat = true;
+    /**
+     * The active file target, or `null` when writing to a string.
+     */
+    file;
+    /**
+     * Reference to the caller's string buffer in string mode, `null` in file
+     * mode.
+     */
+    stringTarget;
+    parameterEmitted = false;
+    voteEmitted = false;
+    autoSeparatorWritten = false;
+    /**
+     * Exactly one of `options.file` or `options.string` must be provided.
+     *
+     * @throws {InvalidWriterStateException}
+     */
+    constructor(options = {}) {
+        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.
+     */
+    createFileWriteTarget(path) {
+        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
+     */
+    addParameter(parameter) {
+        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.
+     */
+    addVote(vote) {
+        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}
+     */
+    addRawVoteLine(line) {
+        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}
+     */
+    addRawVote(vote, options = {}) {
+        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.
+     */
+    addComment(comment) {
+        this.writeLine(comment.format(this.autoFormat));
+        return this;
+    }
+    /**
+     * Convenience helper: build a {@link CommentLine} from raw text and emit it
+     * in a single call.
+     */
+    addCommentLine(text) {
+        return this.addComment(new CommentLine(text));
+    }
+    /**
+     * Emit an empty line.
+     */
+    addEmptyLine() {
+        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.
+     */
+    close() {
+        if (this.file !== null && 'close' in this.file && typeof this.file.close === 'function') {
+            this.file.close();
+        }
+    }
+    /**
+     * Insert one blank line between the parameter block and the first vote when
+     * `autoFormat` is on. Idempotent.
+     */
+    writeAutoSeparatorIfNeeded() {
+        if (this.autoFormat &&
+            this.parameterEmitted &&
+            !this.voteEmitted &&
+            !this.autoSeparatorWritten) {
+            this.writeLine('');
+            this.autoSeparatorWritten = true;
+        }
+    }
+    renderInlineComment(comment) {
+        if (!this.autoFormat) {
+            return '#' + comment;
+        }
+        const needsLeadingSpace = comment === '' || !comment.startsWith(' ');
+        return ' #' + (needsLeadingSpace ? ' ' : '') + comment;
+    }
+    writeLine(content) {
+        const line = content + '\n';
+        if (this.file !== null) {
+            const expected = Buffer.byteLength(line, 'utf-8');
+            let written;
+            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/dist/CefFormat.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+export declare namespace CefFormat {
+    /**
+     * Characters that the specification reserves for syntactic use and that
+     * therefore must never appear inside any user-supplied value.
+     */
+    const RESERVED_CHARACTERS: readonly string[];
+    /**
+     * Sentinel value emitted as the whole ranking of a blank ballot.
+     */
+    const EMPTY_RANKING = "/EMPTY_RANKING/";
+    /**
+     * Tag/ranking separator on a vote line.
+     */
+    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}
+     */
+    function assertValueIsClean(value: string, context: string): void;
+    /**
+     * 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}
+     */
+    function assertNoReservedNorLineBreak(value: string, context: string): void;
+    /**
+     * 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}
+     */
+    function assertSingleLine(value: string, context: string): void;
+    /**
+     * 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}
+     */
+    function assertNoTagSeparator(value: string, context: string): void;
+}
+//# sourceMappingURL=CefFormat.d.ts.map

package/dist/CefFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CefFormat.d.ts","sourceRoot":"","sources":["../src/CefFormat.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AAEH,yBAAiB,SAAS,CAAC;IACzB;;;OAGG;IACI,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAShD,CAAC;IAEF;;OAEG;IACI,MAAM,aAAa,oBAAoB,CAAC;IAE/C;;OAEG;IACI,MAAM,cAAc,OAAO,CAAC;IAEnC;;;;;;OAMG;IACH,SAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMvE;IAED;;;;;;OAMG;IACH,SAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAUjF;IAED;;;;;OAKG;IACH,SAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAErE;IAED;;;;;;;;OAQG;IACH,SAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMzE;CAmDF"}

package/dist/CefFormat.js

@@ -0,0 +1,133 @@
+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 var CefFormat;
+(function (CefFormat) {
+    /**
+     * Characters that the specification reserves for syntactic use and that
+     * therefore must never appear inside any user-supplied value.
+     */
+    CefFormat.RESERVED_CHARACTERS = [
+        '>',
+        '=',
+        ';',
+        ',',
+        '#',
+        '/',
+        '*',
+        '^',
+    ];
+    /**
+     * Sentinel value emitted as the whole ranking of a blank ballot.
+     */
+    CefFormat.EMPTY_RANKING = '/EMPTY_RANKING/';
+    /**
+     * Tag/ranking separator on a vote line.
+     */
+    CefFormat.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}
+     */
+    function assertValueIsClean(value, context) {
+        if (value === '') {
+            throw new InvalidValueException(`${context} cannot be empty.`);
+        }
+        assertNoReservedNorLineBreak(value, context);
+    }
+    CefFormat.assertValueIsClean = assertValueIsClean;
+    /**
+     * 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}
+     */
+    function assertNoReservedNorLineBreak(value, context) {
+        assertSafeText(value, context);
+        for (const reserved of CefFormat.RESERVED_CHARACTERS) {
+            if (value.includes(reserved)) {
+                throw new ReservedCharacterException(`${context} cannot contain the reserved character "${reserved}".`);
+            }
+        }
+    }
+    CefFormat.assertNoReservedNorLineBreak = assertNoReservedNorLineBreak;
+    /**
+     * 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}
+     */
+    function assertSingleLine(value, context) {
+        assertSafeText(value, context);
+    }
+    CefFormat.assertSingleLine = assertSingleLine;
+    /**
+     * 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}
+     */
+    function assertNoTagSeparator(value, context) {
+        if (value.includes(CefFormat.TAGS_SEPARATOR)) {
+            throw new ReservedCharacterException(`${context} cannot contain the "${CefFormat.TAGS_SEPARATOR}" tag separator.`);
+        }
+    }
+    CefFormat.assertNoTagSeparator = assertNoTagSeparator;
+    /**
+     * 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, context) {
+        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) {
+        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;
+    }
+})(CefFormat || (CefFormat = {}));

package/dist/CommentLine.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A standalone comment line (`# text`).
+ *
+ * Inline comments attached to vote lines are not represented by this class —
+ * they live on `VoteLine.inlineComment` instead.
+ */
+export declare class CommentLine {
+    readonly text: string;
+    /**
+     * @throws {CefFormatException}
+     */
+    constructor(text: string);
+    /**
+     * Render the line *without* trailing newline.
+     */
+    format(autoFormat?: boolean): string;
+}
+//# sourceMappingURL=CommentLine.d.ts.map

package/dist/CommentLine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommentLine.d.ts","sourceRoot":"","sources":["../src/CommentLine.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;gBACgB,IAAI,EAAE,MAAM;IAK/B;;OAEG;IACI,MAAM,CAAC,UAAU,UAAO,GAAG,MAAM;CASzC"}

package/dist/CommentLine.js

@@ -0,0 +1,27 @@
+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 {
+    text;
+    /**
+     * @throws {CefFormatException}
+     */
+    constructor(text) {
+        CefFormat.assertSingleLine(text, 'Comment');
+        this.text = text;
+    }
+    /**
+     * Render the line *without* trailing newline.
+     */
+    format(autoFormat = true) {
+        if (this.text === '') {
+            return '#';
+        }
+        const needsLeadingSpace = autoFormat && !this.text.startsWith(' ');
+        return '#' + (needsLeadingSpace ? ' ' : '') + this.text;
+    }
+}

package/dist/Exception/CefFormatException.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare class CefFormatException extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=CefFormatException.d.ts.map

package/dist/Exception/CefFormatException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CefFormatException.d.ts","sourceRoot":"","sources":["../../src/Exception/CefFormatException.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAKnC"}

package/dist/Exception/CefFormatException.js

@@ -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 {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/Exception/CefWriteException.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare class CefWriteException extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=CefWriteException.d.ts.map

package/dist/Exception/CefWriteException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CefWriteException.d.ts","sourceRoot":"","sources":["../../src/Exception/CefWriteException.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKlE"}

package/dist/Exception/CefWriteException.js

@@ -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 {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/Exception/DuplicateCandidateException.d.ts

@@ -0,0 +1,9 @@
+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 declare class DuplicateCandidateException extends CefFormatException {
+}
+//# sourceMappingURL=DuplicateCandidateException.d.ts.map

package/dist/Exception/DuplicateCandidateException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DuplicateCandidateException.d.ts","sourceRoot":"","sources":["../../src/Exception/DuplicateCandidateException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,kBAAkB;CAAG"}

package/dist/Exception/DuplicateCandidateException.js

@@ -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/dist/Exception/InvalidUtf8Exception.d.ts

@@ -0,0 +1,13 @@
+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 declare class InvalidUtf8Exception extends CefFormatException {
+}
+//# sourceMappingURL=InvalidUtf8Exception.d.ts.map

package/dist/Exception/InvalidUtf8Exception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvalidUtf8Exception.d.ts","sourceRoot":"","sources":["../../src/Exception/InvalidUtf8Exception.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,kBAAkB;CAAG"}

package/dist/Exception/InvalidUtf8Exception.js

@@ -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 {
+}