Skip to main content

​
Overview

The ElectionService handles all business logic related to elections in the Consensus e-voting platform. It manages the complete election lifecycle from draft creation through activation and closure, implements the Observer pattern for election state changes, and enforces validation rules for election integrity.

​
Constructor

constructor(
    electionRepository: IElectionRepository,
    candidateRepository: ICandidateRepository,
    eventEmitter?: ElectionEventEmitter
)
​
electionRepository
IElectionRepository
required
Repository for election data persistence
​
candidateRepository
ICandidateRepository
required
Repository for candidate data persistence
​
eventEmitter
ElectionEventEmitter
Optional event emitter for Observer pattern notifications (created automatically if not provided)

​
Methods

​
createElection

Creates a new election in DRAFT status. 
createElection(dto: ElectionCreationDTO): Election
​
dto
ElectionCreationDTO
required
Election creation dataElectionCreationDTO:
  • name: string - Election name
  • electionType: ElectionType - Type (FPTP, STV, AV, PREFERENTIAL)
  • startDate: Date - Election start date
  • endDate: Date - Election end date
  • description: string - Election description
​
Election
Election
The newly created election entity with DRAFT status
Throws:
  • "End date must be after start date" - Invalid date range
  • "Start date cannot be in the past" - Start date before current date
Example: 
const dto: ElectionCreationDTO = {
    name: "Test Election",
    electionType: ElectionType.FPTP,
    startDate: new Date('2026-04-01'),
    endDate: new Date('2026-04-07'),
    description: "A test election"
};

const election = service.createElection(dto);
console.log(election.status); // ElectionStatus.DRAFT

​
addCandidate

Adds a candidate to a draft election. 
addCandidate(electionID: string, dto: CandidateCreationDTO): Candidate
​
electionID
string
required
ID of the election to add the candidate to
​
dto
CandidateCreationDTO
required
Candidate dataCandidateCreationDTO:
  • name: string - Candidate name
  • party: string - Political party affiliation
  • biography: string - Candidate biography
​
Candidate
Candidate
The newly created candidate entity
Throws:
  • "Election not found" - Invalid election ID
  • "Cannot add candidates to non-draft elections" - Election is already active or closed
Example: 
const candidate = service.addCandidate(election.electionID, {
    name: "John Smith",
    party: "Independent",
    biography: "Experienced community leader"
});

​
removeCandidate

Removes a candidate from a draft election. 
removeCandidate(electionID: string, candidateID: string): void
​
electionID
string
required
ID of the election
​
candidateID
string
required
ID of the candidate to remove
Throws:
  • "Election not found" - Invalid election ID
  • "Cannot remove candidates from non-draft elections" - Election is already active or closed
  • "Candidate not found" - Invalid candidate ID
  • "Candidate does not belong to this election" - Candidate/election mismatch

​
getElectionById

Retrieves an election by its ID. 
getElectionById(electionID: string): Election | null
​
electionID
string
required
ID of the election to retrieve
​
Election | null
Election | null
The election entity if found, otherwise null

​
getCandidates

Retrieves all candidates for a specific election. 
getCandidates(electionID: string): Candidate[]
​
electionID
string
required
ID of the election
​
Candidate[]
Candidate[]
Array of candidate entities for the election

​
getActiveElections

Retrieves all currently active elections. 
getActiveElections(): Election[]
​
Election[]
Election[]
Array of active election entities

​
getAllElections

Retrieves all elections regardless of status. 
getAllElections(): Election[]
​
Election[]
Election[]
Array of all election entities

​
getClosedElections

Retrieves all closed elections. 
getClosedElections(): Election[]
​
Election[]
Election[]
Array of closed election entities

​
activateElection

Activates a draft election, making it available for voting. 
activateElection(electionID: string): void
​
electionID
string
required
ID of the election to activate
Throws:
  • "Election not found" - Invalid election ID
  • "Election must have at least 2 candidates" - Insufficient candidates
Notes:
  • Triggers Observer pattern notification to all subscribers
  • Changes election status from DRAFT to ACTIVE
Example: 
service.addCandidate(electionID, { name: "C1", party: "P1", biography: "B1" });
service.addCandidate(electionID, { name: "C2", party: "P2", biography: "B2" });
service.activateElection(electionID);

​
closeElection

Closes an election, preventing further votes. 
closeElection(electionID: string): void
​
electionID
string
required
ID of the election to close
Throws:
  • "Election not found" - Invalid election ID
Notes:
  • Triggers Observer pattern notification to all subscribers
  • Changes election status to CLOSED
  • Results become available after closure

​
deleteElection

Deletes a draft election and all its candidates. 
deleteElection(electionID: string): void
​
electionID
string
required
ID of the election to delete
Throws:
  • "Election not found" - Invalid election ID
  • "Only draft elections can be deleted" - Election is active or closed
Notes:
  • Automatically deletes all associated candidates
  • Cannot delete active or closed elections

​
getEventEmitter

Returns the event emitter to allow external code to subscribe observers. 
getEventEmitter(): ElectionEventEmitter
​
ElectionEventEmitter
ElectionEventEmitter
The event emitter instance for subscribing to election state changes
Example: 
const emitter = service.getEventEmitter();
emitter.subscribe(myObserver);

​
ElectionStatus

Enum representing election lifecycle states:
  • DRAFT - Election created but not yet active
  • ACTIVE - Election open for voting
  • CLOSED - Election ended, results available

​
ElectionType

Enum representing voting systems:
  • FPTP - First Past The Post
  • STV - Single Transferable Vote
  • AV - Alternative Vote
  • PREFERENTIAL - Preferential voting

Build docs developers (and LLMs) love

Get started for freeTalk to us