Skip to main content

​
Overview

The BallotRepository class handles all database operations for ballots in the Consensus e-voting platform. It implements the IBallotRepository interface and uses SQLite for data persistence.

​
Constructor

constructor(db?: Database.Database)
​
db
Database.Database
Optional database instance. If not provided, uses the singleton DatabaseConnection instance.

​
Methods

​
save

Persists a new ballot to the database. 
save(ballot: Ballot): void
​
ballot
Ballot
required
The ballot entity to save to the database. Preferences are stored as JSON.
​
return
void
No return value. Throws an error if the save operation fails.
Example: 
const ballot = new Ballot(
  "ballot-123",
  "elec-456",
  ["candidate-1", "candidate-2", "candidate-3"]
);

ballotRepository.save(ballot);

​
findById

Retrieves a ballot by its unique identifier. 
findById(ballotID: string): Ballot | null
​
ballotID
string
required
The unique identifier of the ballot to retrieve.
​
return
Ballot | null
Returns the Ballot entity if found, or null if no ballot exists with the given ID.
Example: 
const ballot = ballotRepository.findById("ballot-123");
if (ballot) {
  console.log(`Ballot cast at: ${ballot.castAt}`);
}

​
findByElectionId

Retrieves all ballots for a specific election. 
findByElectionId(electionID: string): Ballot[]
​
electionID
string
required
The unique identifier of the election.
​
return
Ballot[]
Array of all ballots cast in the specified election. Returns empty array if no ballots found.
Example: 
const ballots = ballotRepository.findByElectionId("elec-456");
console.log(`Total ballots cast: ${ballots.length}`);

​
countByElectionId

Counts the total number of ballots cast in a specific election. 
countByElectionId(electionID: string): number
​
electionID
string
required
The unique identifier of the election.
​
return
number
The total count of ballots cast in the election.
Example: 
const count = ballotRepository.countByElectionId("elec-456");
console.log(`${count} ballots have been cast`);

​
countByCandidate

Counts the number of ballots where a specific candidate is the first preference. 
countByCandidate(electionID: string, candidateID: string): number
​
electionID
string
required
The unique identifier of the election.
​
candidateID
string
required
The unique identifier of the candidate.
​
return
number
The count of ballots where the candidate is listed as the first preference (index 0 in the preferences array).
Example: 
const votes = ballotRepository.countByCandidate("elec-456", "candidate-1");
console.log(`Candidate received ${votes} first-preference votes`);

​
Ballot

The Ballot entity with the following properties:
  • ballotID: string - Unique identifier (readonly)
  • electionID: string - ID of the election this ballot belongs to (readonly)
  • preferences: string[] - Array of candidate IDs in preference order (readonly)
    • For FPTP elections: single candidate ID
    • For preferential elections: multiple candidate IDs ranked by preference
  • castAt: Date - Timestamp when the ballot was cast (readonly, defaults to current time)

​
Notes

  • Ballot preferences are stored as JSON in the database and parsed when retrieved
  • The countByCandidate method uses SQLite’s json_extract function to query the first preference
  • All ballot properties are readonly to ensure ballot integrity after casting

Build docs developers (and LLMs) love

Get started for freeTalk to us