final part of adding documentation

Author: maboke123

packages/raft-core/src/config/ClusterConfig.ts

@@ -1,15 +1,24 @@
 import { NodeId } from "../core/Config";
 
+/**
+ * Cluster member identity and transport address.
+ */
 export interface ClusterMember {
     id: NodeId;
     address: string;
 }
 
+/**
+ * Cluster membership split into voters and learners.
+ */
 export interface ClusterConfig {
     voters: ClusterMember[];
     learners: ClusterMember[];
 }
 
+/**
+ * Compares two configurations by voter and learner membership ids.
+ */
 export function clusterConfigsEqual(a: ClusterConfig, b: ClusterConfig): boolean {
     if (a.voters.length !== b.voters.length) return false;
     if (a.learners.length !== b.learners.length) return false;
@@ -30,18 +39,22 @@ export function clusterConfigsEqual(a: ClusterConfig, b: ClusterConfig): boolean
     return true;
 }
 
+/** Returns true when node is a voter in config. */
 export function isVoter(config: ClusterConfig, nodeId: NodeId): boolean {
     return config.voters.some(m => m.id === nodeId);
 }
 
+/** Returns true when node is a learner in config. */
 export function isLearner(config: ClusterConfig, nodeId: NodeId): boolean {
     return config.learners.some(m => m.id === nodeId);
 }
 
+/** Returns true when node is either voter or learner in config. */
 export function isNodeInCluster(config: ClusterConfig, nodeId: NodeId): boolean {
     return isVoter(config, nodeId) || isLearner(config, nodeId);
 }
 
+/** Returns majority quorum size for current voter set. */
 export function getQuorumSize(config: ClusterConfig): number {
     return Math.floor(config.voters.length / 2) + 1;
 }

packages/raft-core/src/core/Config.ts

@@ -1,17 +1,34 @@
 import { ClusterMember } from "../config/ClusterConfig";
 
+/** Logical node identifier used across raft-core. */
 export type NodeId = string;
 
+/**
+ * Static node bootstrap/runtime configuration.
+ */
 export interface RaftConfig {
+    /** Local node id. */
     nodeId: NodeId;
+    /** Local transport address. */
     address: string;
+    /** Other cluster members (excluding self). */
     peers: ClusterMember[];
+    /** Minimum election timeout in milliseconds. */
     electionTimeoutMinMs: number;
+    /** Maximum election timeout in milliseconds. */
     electionTimeoutMaxMs: number;
+    /** Heartbeat interval in milliseconds. */
     heartbeatIntervalMs: number;
+    /** Optional committed-entry threshold for triggering snapshots. */
     snapshotThreshold?: number;
 }
 
+/**
+ * Validates Raft node configuration invariants.
+ *
+ * @param config Configuration object to validate.
+ * @throws Error When any required field is invalid.
+ */
 export function validateConfig(config: RaftConfig): void {
     if(!config.nodeId || typeof config.nodeId !== 'string') {
         throw new Error(`Invalid nodeId: ${config.nodeId}. nodeId must be a non-empty string.`);
@@ -58,6 +75,12 @@ export function validateConfig(config: RaftConfig): void {
     }
 }
 
+/**
+ * Creates and validates a Raft configuration object.
+ *
+ * @returns Validated RaftConfig instance.
+ * @throws Error When provided values violate config invariants.
+ */
 export function createConfig(nodeId: NodeId, address: string, peers: ClusterMember[], electionTimeoutMinMs: number, electionTimeoutMaxMs: number, heartbeatIntervalMs: number, snapshotThreshold?: number): RaftConfig {
     const config: RaftConfig = {
         nodeId,

packages/raft-core/src/events/EventBus.ts

@@ -1,8 +1,12 @@
 import { RaftEvent, RaftEventBus } from "./RaftEvents";
 
+/**
+ * In-process event bus implementation with in-memory subscriber list.
+ */
 export class LocalEventBus implements RaftEventBus {
     private handlers: Array<(event: RaftEvent) => void> = [];
 
+    /** Publishes an event to all current subscribers. */
     emit(event: RaftEvent): void {
         for (const handler of this.handlers) {
             try {
@@ -13,6 +17,12 @@ export class LocalEventBus implements RaftEventBus {
         }
     }
 
+    /**
+     * Registers a subscriber callback.
+     *
+     * @param handler Subscriber function.
+     * @returns Unsubscribe callback.
+     */
     subscribe(handler: (event: RaftEvent) => void): () => void {
         this.handlers.push(handler);
         return () => {
@@ -21,10 +31,15 @@ export class LocalEventBus implements RaftEventBus {
     }
 }
 
+/**
+ * Event bus implementation that drops all events and subscriptions.
+ */
 export class NoOpEventBus implements RaftEventBus {
+    /** Ignores published events. */
     emit(_event: RaftEvent): void {
         // no-op
     }
+    /** Returns a no-op unsubscribe callback. */
     subscribe(handler: (event: RaftEvent) => void): () => void {
         return () => {
             // no-op

packages/raft-core/src/events/EventStore.ts

@@ -1,17 +1,31 @@
 import { RaftEvent, RaftEventBus } from "./RaftEvents";
 
+/**
+ * Configuration for in-memory event retention.
+ */
 export interface EventStoreOptions {
+    /** Maximum number of retained historical events. */
     maxEvents: number;
 }
 
+/**
+ * In-memory event store that records bus events and broadcasts live updates.
+ */
 export class EventStore {
     private events: RaftEvent[] = [];
     private liveSubscribers: Set<(event: RaftEvent) => void> = new Set();
 
+    /**
+     * Subscribes to an event bus and starts buffering incoming events.
+     *
+     * @param bus Source event bus.
+     * @param options Retention configuration.
+     */
     constructor(bus: RaftEventBus, private options: EventStoreOptions) {
         bus.subscribe((event) => this.append(event));
     }
 
+    /** Appends an event to retention buffer and notifies live subscribers. */
     private append(event: RaftEvent): void {
         this.events.push(event);
 
@@ -24,15 +38,23 @@ export class EventStore {
         }
     }
 
+    /** Returns a copy of currently retained events. */
     getAllEvents(): RaftEvent[] {
         return [...this.events];
     }
 
+    /**
+     * Subscribes to live appended events.
+     *
+     * @param subscriber Live event callback.
+     * @returns Unsubscribe callback.
+     */
     onLiveEvent(subscriber: (event: RaftEvent) => void): () => void {
         this.liveSubscribers.add(subscriber);
         return () => this.liveSubscribers.delete(subscriber);
     }
 
+    /** Returns current number of retained events. */
     getSize(): number {
         return this.events.length;
     }

packages/raft-core/src/events/RaftEvents.ts

@@ -11,6 +11,9 @@ import {
 import { RaftState } from "../core/StateMachine";
 import { ClusterConfig, ClusterMember } from "../config/ClusterConfig";
 
+/**
+ * Common fields present in node-scoped Raft runtime events.
+ */
 export interface BaseEvent {
     eventId: string;
     timestamp: number;
@@ -109,6 +112,9 @@ export interface NextIndexDecrementedEvent extends BaseEvent {
     term: number;
 }
 
+/**
+ * Supported wire-level message event categories used by transport instrumentation.
+ */
 export type MessageType = 
     | "RequestVote"
     | "RequestVoteResponse"
@@ -163,7 +169,9 @@ export interface InstallSnapshotResponseEvent extends BaseMessageEvent {
     latencyMs: number;
 }
 
+/** Message-sent event variants. */
 export type MessageSentEvent = RequestVoteSentEvent | AppendEntriesSentEvent | InstallSnapshotRequestEvent;
+/** Message-received event variants. */
 export type MessageReceivedEvent = RequestVoteReceivedEvent | AppendEntriesReceivedEvent | InstallSnapshotResponseEvent;
 
 export interface MessageDroppedEvent extends BaseMessageEvent {
@@ -265,6 +273,9 @@ export interface FatalErrorEvent extends BaseEvent {
     error: string;
 }
 
+/**
+ * Union of all observability events emitted by raft-core.
+ */
 export type RaftEvent =
     | NodeStateChangedEvent
     | TermChangedEvent
@@ -296,6 +307,9 @@ export type RaftEvent =
     | ConfigChangeRejectedEvent
     | FatalErrorEvent;
 
+/**
+ * Event bus abstraction for publishing and subscribing to Raft runtime events.
+ */
 export interface RaftEventBus {
     emit(event: RaftEvent): void;
     subscribe(handler: (event: RaftEvent) => void): () => void;

packages/raft-core/src/index.ts

@@ -1,3 +1,6 @@
+/**
+ * Public raft-core package exports.
+ */
 export { RaftNode } from "./core/RaftNode";
 export type {
     RaftNodeOptions,

packages/raft-core/src/lock/AsyncLock.ts

@@ -1,7 +1,13 @@
+/**
+ * Minimal FIFO async mutual exclusion lock.
+ */
 export class AsyncLock {
     private locked: boolean = false
     private queue: Array<() => void> = []
 
+    /**
+     * Acquires lock when available or waits until current holder releases.
+     */
     async acquire(): Promise<void> {
 
         if (!this.locked) {
@@ -12,6 +18,11 @@ export class AsyncLock {
         await new Promise<void>(resolve => this.queue.push(resolve));
     }
 
+    /**
+     * Releases lock and wakes next queued waiter if present.
+     *
+     * @throws Error When lock is not currently held.
+     */
     release(): void {
         if (!this.locked) {
             throw new Error('Cannot release an unlocked lock');
@@ -25,6 +36,12 @@ export class AsyncLock {
         }
     }
 
+    /**
+     * Executes callback while holding lock and always releases afterwards.
+     *
+     * @param callback Async critical section body.
+     * @returns Callback result.
+     */
     async runExclusive<T>(callback: () => Promise<T>): Promise<T> {
         await this.acquire();
         try {
@@ -34,10 +51,12 @@ export class AsyncLock {
         }
     }
 
+    /** Returns true when lock is currently held. */
     isLocked(): boolean {
         return this.locked;
     }
 
+    /** Returns number of waiters queued for lock acquisition. */
     getQueueLength(): number {
         return this.queue.length;
     }

packages/raft-core/src/log/LogEntry.ts

@@ -1,24 +1,46 @@
 import { ClusterConfig } from "../config/ClusterConfig";
 
+/**
+ * Application command payload replicated through Raft log.
+ */
 export interface Command {
+    /** Command discriminator used by application state machine. */
   type: string;
+    /** Command payload consumed by application state machine. */
   payload: any;
 }
 
+/**
+ * Supported replicated log entry categories.
+ */
 export enum LogEntryType {
     COMMAND = 'COMMAND',
     CONFIG = 'CONFIG',
     NOOP = 'NOOP'
 }
 
+/**
+ * Replicated Raft log record.
+ */
 export interface LogEntry {
+    /** Raft term when this entry was created. */
   term: number;
+    /** Monotonic log index. */
   index: number;
+    /** Entry semantic type. */
   type: LogEntryType;
+    /** Command payload for COMMAND entries. */
   command?: Command;
+    /** Cluster config payload for CONFIG entries. */
   config?: ClusterConfig
 }
 
+/**
+ * Validates a single log entry shape and type-specific payload fields.
+ *
+ * @param entry Entry to validate.
+ * @throws Error When entry shape is invalid.
+ */
 export function validateLogEntry(entry: LogEntry): void {
     if (!Number.isInteger(entry.term) || entry.term < 0) {
         throw new Error(`Invalid term: ${entry.term}. Term must be a non-negative integer.`);
@@ -51,6 +73,12 @@ export function validateLogEntry(entry: LogEntry): void {
     }
 }
 
+/**
+ * Validates a complete log sequence for per-entry validity and monotonic ordering.
+ *
+ * @param log Log entries in index order.
+ * @throws Error When sequence invariants are violated.
+ */
 export function validateLogSequence(log: LogEntry[]): void {
     if (log.length === 0) {
         return;
@@ -74,6 +102,9 @@ export function validateLogSequence(log: LogEntry[]): void {
     }
 }
 
+/**
+ * Deep-compares two command payloads for deterministic test assertions.
+ */
 export function commandsEqual(cmd1: Command, cmd2: Command): boolean {
     if (cmd1.type !== cmd2.type) {
         return false;
@@ -84,6 +115,9 @@ export function commandsEqual(cmd1: Command, cmd2: Command): boolean {
     return payload1 === payload2;
 }
 
+/**
+ * Compares two log entries by metadata and type-specific payload.
+ */
 export function entriesEqual(entry1: LogEntry, entry2: LogEntry): boolean {
     if (entry1.term !== entry2.term || entry1.index !== entry2.index) {
         return false;
@@ -106,6 +140,9 @@ export function entriesEqual(entry1: LogEntry, entry2: LogEntry): boolean {
     return commandsEqual(entry1.command!, entry2.command!);
 }
 
+/**
+ * Compares two logs entry-by-entry.
+ */
 export function logsEqual(log1: LogEntry[], log2: LogEntry[]): boolean {
     if (log1.length !== log2.length) {
         return false;