dandelion-mesh 1.0.0

package/build/main/raft/log/RaftLog.test-util.js

@@ -0,0 +1,82 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Wenhao Ji <predator.ray@gmail.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCommonRaftLogTests = void 0;
+function runCommonRaftLogTests(t, createLog) {
+    const log = createLog();
+    // Initial state
+    t.is(log.length(), 0);
+    t.is(log.lastIndex(), 0);
+    t.is(log.lastTerm(), 0);
+    t.deepEqual(log.loadState(), { currentTerm: 0, votedFor: null });
+    // Append and retrieve
+    const entries = [
+        { term: 1, command: 'a' },
+        { term: 1, command: 'b' },
+        { term: 2, command: 'c' },
+    ];
+    log.append(entries);
+    t.is(log.length(), 3);
+    t.is(log.lastIndex(), 3);
+    t.is(log.lastTerm(), 2);
+    t.deepEqual(log.getEntry(1), entries[0]);
+    t.deepEqual(log.getEntry(2), entries[1]);
+    t.deepEqual(log.getEntry(3), entries[2]);
+    t.is(log.getEntry(0), undefined);
+    t.is(log.getEntry(4), undefined);
+    // getTerm
+    t.is(log.getTerm(1), 1);
+    t.is(log.getTerm(3), 2);
+    t.is(log.getTerm(0), 0);
+    t.is(log.getTerm(4), 0);
+    // getEntries
+    t.deepEqual(log.getEntries(1, 2), [entries[0], entries[1]]);
+    t.deepEqual(log.getEntries(2, 3), [entries[1], entries[2]]);
+    t.deepEqual(log.getEntries(1, 3), entries);
+    t.deepEqual(log.getEntries(2, 2), [entries[1]]);
+    t.deepEqual(log.getEntries(3, 2), []);
+    t.deepEqual(log.getEntries(4, 5), []);
+    // Persistent state
+    const newState = { currentTerm: 5, votedFor: 'node1' };
+    log.saveState(newState);
+    t.deepEqual(log.loadState(), newState);
+    // Truncate
+    log.truncateFrom(2);
+    t.is(log.length(), 1);
+    t.is(log.lastIndex(), 1);
+    t.is(log.lastTerm(), 1);
+    t.deepEqual(log.getEntry(1), entries[0]);
+    t.is(log.getEntry(2), undefined);
+    // Truncate from 1
+    log.truncateFrom(1);
+    t.is(log.length(), 0);
+    t.is(log.lastIndex(), 0);
+    t.is(log.lastTerm(), 0);
+    // Truncate with index <= 0 (should be safe, usually does nothing or clears all)
+    log.append(entries);
+    log.truncateFrom(0);
+    t.is(log.length(), 3, 'truncateFrom(0) should be a no-op per implementation');
+}
+exports.runCommonRaftLogTests = runCommonRaftLogTests;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUmFmdExvZy50ZXN0LXV0aWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvcmFmdC9sb2cvUmFmdExvZy50ZXN0LXV0aWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FxQkc7OztBQVFILFNBQWdCLHFCQUFxQixDQUNuQyxDQUFtQixFQUNuQixTQUEyQjtJQUUzQixNQUFNLEdBQUcsR0FBRyxTQUFTLEVBQUUsQ0FBQztJQUV4QixnQkFBZ0I7SUFDaEIsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxHQUFHLENBQUMsTUFBTSxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDdEIsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxHQUFHLENBQUMsU0FBUyxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDekIsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxHQUFHLENBQUMsUUFBUSxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDeEIsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxHQUFHLENBQUMsU0FBUyxFQUFFLEVBQUUsRUFBRSxXQUFXLEVBQUUsQ0FBQyxFQUFFLFFBQVEsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDO0lBRWpFLHNCQUFzQjtJQUN0QixNQUFNLE9BQU8sR0FBa0I7UUFDN0IsRUFBRSxJQUFJLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxHQUFVLEVBQUU7UUFDaEMsRUFBRSxJQUFJLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxHQUFVLEVBQUU7UUFDaEMsRUFBRSxJQUFJLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxHQUFVLEVBQUU7S0FDakMsQ0FBQztJQUNGLEdBQUcsQ0FBQyxNQUFNLENBQUMsT0FBTyxDQUFDLENBQUM7SUFFcEIsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxHQUFHLENBQUMsTUFBTSxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDdEIsQ0FBQyxDQUFDLEVBQUUsQ0FB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

package/build/main/raft/log/SessionStorageRaftLog.d.ts

@@ -0,0 +1,9 @@
+import { StorageRaftLog } from './StorageRaftLog';
+/**
+ * sessionStorage-backed Raft log implementation.
+ * Survives page refreshes within the same tab, but is cleared when the tab is closed.
+ * Useful for short-lived Raft groups or testing.
+ */
+export declare class SessionStorageRaftLog<T = unknown> extends StorageRaftLog<T> {
+    constructor(namespace: string);
+}

package/build/main/raft/log/SessionStorageRaftLog.js

@@ -0,0 +1,38 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Wenhao Ji <predator.ray@gmail.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStorageRaftLog = void 0;
+const StorageRaftLog_1 = require("./StorageRaftLog");
+/**
+ * sessionStorage-backed Raft log implementation.
+ * Survives page refreshes within the same tab, but is cleared when the tab is closed.
+ * Useful for short-lived Raft groups or testing.
+ */
+class SessionStorageRaftLog extends StorageRaftLog_1.StorageRaftLog {
+    constructor(namespace) {
+        super(sessionStorage, namespace);
+    }
+}
+exports.SessionStorageRaftLog = SessionStorageRaftLog;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2Vzc2lvblN0b3JhZ2VSYWZ0TG9nLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3JhZnQvbG9nL1Nlc3Npb25TdG9yYWdlUmFmdExvZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXFCRzs7O0FBRUgscURBQWtEO0FBRWxEOzs7O0dBSUc7QUFDSCxNQUFhLHFCQUFtQyxTQUFRLCtCQUFpQjtJQUN2RSxZQUFZLFNBQWlCO1FBQzNCLEtBQUssQ0FBQyxjQUFjLEVBQUUsU0FBUyxDQUFDLENBQUM7SUFDbkMsQ0FBQztDQUNGO0FBSkQsc0RBSUMifQ==

package/build/main/raft/log/StorageRaftLog.d.ts

@@ -0,0 +1,28 @@
+import { LogEntry, RaftPersistentState } from '../types';
+import { RaftLog } from './RaftLog';
+/**
+ * Common base class for Storage-backed Raft log implementations (localStorage or sessionStorage).
+ *
+ * Storage layout (all keys prefixed with `{prefix}`):
+ *   `{prefix}:state`          → JSON of RaftPersistentState
+ *   `{prefix}:log:length`     → number of log entries
+ *   `{prefix}:log:{index}`    → JSON of LogEntry at 1-based index
+ */
+export declare abstract class StorageRaftLog<T = unknown> implements RaftLog<T> {
+    protected readonly storage: Storage;
+    protected readonly prefix: string;
+    constructor(storage: Storage, namespace: string);
+    loadState(): RaftPersistentState;
+    saveState(state: RaftPersistentState): void;
+    length(): number;
+    protected setLength(len: number): void;
+    getEntry(index: number): LogEntry<T> | undefined;
+    getTerm(index: number): number;
+    append(entries: LogEntry<T>[]): void;
+    truncateFrom(index: number): void;
+    getEntries(startIndex: number, endIndex: number): LogEntry<T>[];
+    lastIndex(): number;
+    lastTerm(): number;
+    /** Remove all stored data for this namespace from storage */
+    clear(): void;
+}

package/build/main/raft/log/StorageRaftLog.js

@@ -0,0 +1,117 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Wenhao Ji <predator.ray@gmail.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageRaftLog = void 0;
+/**
+ * Common base class for Storage-backed Raft log implementations (localStorage or sessionStorage).
+ *
+ * Storage layout (all keys prefixed with `{prefix}`):
+ *   `{prefix}:state`          → JSON of RaftPersistentState
+ *   `{prefix}:log:length`     → number of log entries
+ *   `{prefix}:log:{index}`    → JSON of LogEntry at 1-based index
+ */
+class StorageRaftLog {
+    constructor(storage, namespace) {
+        this.storage = storage;
+        this.prefix = `dandelion-raft:${namespace}`;
+    }
+    // --- Persistent state ---
+    loadState() {
+        const raw = this.storage.getItem(`${this.prefix}:state`);
+        if (!raw)
+            return { currentTerm: 0, votedFor: null };
+        return JSON.parse(raw);
+    }
+    saveState(state) {
+        this.storage.setItem(`${this.prefix}:state`, JSON.stringify(state));
+    }
+    // --- Log operations ---
+    length() {
+        const raw = this.storage.getItem(`${this.prefix}:log:length`);
+        return raw ? parseInt(raw, 10) : 0;
+    }
+    setLength(len) {
+        this.storage.setItem(`${this.prefix}:log:length`, String(len));
+    }
+    getEntry(index) {
+        if (index < 1 || index > this.length())
+            return undefined;
+        const raw = this.storage.getItem(`${this.prefix}:log:${index}`);
+        return raw ? JSON.parse(raw) : undefined;
+    }
+    getTerm(index) {
+        var _a, _b;
+        return (_b = (_a = this.getEntry(index)) === null || _a === void 0 ? void 0 : _a.term) !== null && _b !== void 0 ? _b : 0;
+    }
+    append(entries) {
+        let len = this.length();
+        for (const entry of entries) {
+            len++;
+            this.storage.setItem(`${this.prefix}:log:${len}`, JSON.stringify(entry));
+        }
+        this.setLength(len);
+    }
+    truncateFrom(index) {
+        if (index < 1)
+            return;
+        const len = this.length();
+        for (let i = index; i <= len; i++) {
+            this.storage.removeItem(`${this.prefix}:log:${i}`);
+        }
+        this.setLength(index - 1);
+    }
+    getEntries(startIndex, endIndex) {
+        const len = this.length();
+        if (startIndex > endIndex || startIndex > len)
+            return [];
+        const result = [];
+        const end = Math.min(endIndex, len);
+        for (let i = startIndex; i <= end; i++) {
+            const entry = this.getEntry(i);
+            if (entry)
+                result.push(entry);
+        }
+        return result;
+    }
+    lastIndex() {
+        return this.length();
+    }
+    lastTerm() {
+        const len = this.length();
+        if (len === 0)
+            return 0;
+        return this.getTerm(len);
+    }
+    /** Remove all stored data for this namespace from storage */
+    clear() {
+        const len = this.length();
+        for (let i = 1; i <= len; i++) {
+            this.storage.removeItem(`${this.prefix}:log:${i}`);
+        }
+        this.storage.removeItem(`${this.prefix}:log:length`);
+        this.storage.removeItem(`${this.prefix}:state`);
+    }
+}
+exports.StorageRaftLog = StorageRaftLog;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU3RvcmFnZVJhZnRMb2cuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvcmFmdC9sb2cvU3RvcmFnZVJhZnRMb2cudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FxQkc7OztBQU1IOzs7Ozs7O0dBT0c7QUFDSCxNQUFzQixjQUFjO0lBR2xDLFlBQStCLE9BQWdCLEVBQUUsU0FBaUI7UUFBbkMsWUFBTyxHQUFQLE9BQU8sQ0FBUztRQUM3QyxJQUFJLENBQUMsTUFBTSxHQUFHLGtCQUFrQixTQUFTLEVBQUUsQ0FBQztJQUM5QyxDQUFDO0lBRUQsMkJBQTJCO0lBRTNCLFNBQVM7UUFDUCxNQUFNLEdBQUcsR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLE9BQU8sQ0FBQyxHQUFHLElBQUksQ0FBQyxNQUFNLFFBQVEsQ0FBQyxDQUFDO1FBQ3pELElBQUksQ0FBQyxHQUFHO1lBQUUsT0FBTyxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsUUFBUSxFQUFFLElBQUksRUFBRSxDQUFDO1FBQ3BELE9BQU8sSUFBSSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUN6QixDQUFDO0lBRUQsU0FBUyxDQUFDLEtBQTBCO1FBQ2xDLElBQUksQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLEdBQUcsSUFBSSxDQUFDLE1BQU0sUUFBUSxFQUFFLElBQUksQ0FBQyxTQUFTLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQztJQUN0RSxDQUFDO0lBRUQseUJBQXlCO0lBRXpCLE1BQU07UUFDSixNQUFNLEdBQUcsR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLE9BQU8sQ0FBQyxHQUFHLElBQUksQ0FBQyxNQUFNLGFBQWEsQ0FBQyxDQUFDO1FBQzlELE9BQU8sR0FBRyxDQUFDLENBQUMsQ0FBQyxRQUFRLENBQUMsR0FBRyxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDckMs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

package/build/main/raft/log/StorageRaftLog.test-util.d.ts

@@ -0,0 +1,3 @@
+import { ExecutionContext } from 'ava';
+import { StorageRaftLog } from './StorageRaftLog';
+export declare function runStorageRaftLogTests<T>(t: ExecutionContext, createLog: (namespace: string) => StorageRaftLog<T>): void;

package/build/main/raft/log/StorageRaftLog.test-util.js

@@ -0,0 +1,54 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Wenhao Ji <predator.ray@gmail.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStorageRaftLogTests = void 0;
+const RaftLog_test_util_1 = require("./RaftLog.test-util");
+function runStorageRaftLogTests(t, createLog) {
+    // 1. common RaftLog interface
+    const logCommon = createLog('test-common');
+    logCommon.clear();
+    (0, RaftLog_test_util_1.runCommonRaftLogTests)(t, () => logCommon);
+    // 2. persistence across instances
+    const namespace = 'test-persistence';
+    const log1 = createLog(namespace);
+    log1.clear();
+    log1.append([{ term: 1, command: 'persist-me' }]);
+    log1.saveState({ currentTerm: 1, votedFor: 'peer1' });
+    // Create a new instance with same namespace
+    const log2 = createLog(namespace);
+    t.is(log2.length(), 1);
+    t.deepEqual(log2.getEntry(1), { term: 1, command: 'persist-me' });
+    t.deepEqual(log2.loadState(), { currentTerm: 1, votedFor: 'peer1' });
+    // 3. clear removes all data in namespace
+    const namespaceClear = 'test-clear';
+    const logClear = createLog(namespaceClear);
+    logClear.append([{ term: 1, command: 'a' }]);
+    logClear.saveState({ currentTerm: 1, votedFor: 'b' });
+    logClear.clear();
+    t.is(logClear.length(), 0);
+    t.deepEqual(logClear.loadState(), { currentTerm: 0, votedFor: null });
+    t.is(logClear.getEntry(1), undefined);
+}
+exports.runStorageRaftLogTests = runStorageRaftLogTests;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU3RvcmFnZVJhZnRMb2cudGVzdC11dGlsLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3JhZnQvbG9nL1N0b3JhZ2VSYWZ0TG9nLnRlc3QtdXRpbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXFCRzs7O0FBSUgsMkRBQTREO0FBRzVELFNBQWdCLHNCQUFzQixDQUNwQyxDQUFtQixFQUNuQixTQUFtRDtJQUVuRCw4QkFBOEI7SUFDOUIsTUFBTSxTQUFTLEdBQUcsU0FBUyxDQUFDLGFBQWEsQ0FBQyxDQUFDO0lBQzNDLFNBQVMsQ0FBQyxLQUFLLEVBQUUsQ0FBQztJQUNsQixJQUFBLHlDQUFxQixFQUFDLENBQUMsRUFBRSxHQUFHLEVBQUUsQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUUxQyxrQ0FBa0M7SUFDbEMsTUFBTSxTQUFTLEdBQUcsa0JBQWtCLENBQUM7SUFDckMsTUFBTSxJQUFJLEdBQUcsU0FBUyxDQUFDLFNBQVMsQ0FBQyxDQUFDO0lBQ2xDLElBQUksQ0FBQyxLQUFLLEVBQUUsQ0FBQztJQUViLElBQUksQ0FBQyxNQUFNLENBQUMsQ0FBQyxFQUFFLElBQUksRUFBRSxDQUFDLEVBQUUsT0FBTyxFQUFFLFlBQW1CLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDekQsSUFBSSxDQUFDLFNBQVMsQ0FBQyxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsUUFBUSxFQUFFLE9BQU8sRUFBRSxDQUFDLENBQUM7SUFFdEQsNENBQTRDO0lBQzVDLE1BQU0sSUFBSSxHQUFHLFNBQVMsQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUNsQyxDQUFDLENBQUMsRUFBRSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsRUFBRSxDQUFDLENBQUMsQ0FBQztJQUN2QixDQUFDLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDLEVBQUUsRUFBRSxJQUFJLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxZQUFtQixFQUFFLENBQUMsQ0FBQztJQUN6RSxDQUFDLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxTQUFTLEVBQUUsRUFBRSxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsUUFBUSxFQUFFLE9BQU8sRUFBRSxDQUFDLENBQUM7SUFFckUseUNBQXlDO0lBQ3pDLE1BQU0sY0FBYyxHQUFHLFlBQVksQ0FBQztJQUNwQyxNQUFNLFFBQVEsR0FBRyxTQUFTLENBQUMsY0FBYyxDQUFDLENBQUM7SUFDM0MsUUFBUSxDQUFDLE1BQU0sQ0FBQyxDQUFDLEVBQUUsSUFBSSxFQUFFLENBQUMsRUFBRSxPQUFPLEVBQUUsR0FBVSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQ3BELFFBQVEsQ0FBQyxTQUFTLENBQUMsRUFBRSxXQUFXLEVBQUUsQ0FBQyxFQUFFLFFBQVEsRUFBRSxHQUFHLEVBQUUsQ0FBQyxDQUFDO0lBRXRELFFBQVEsQ0FBQyxLQUFLLEVBQUUsQ0FBQztJQUVqQixDQUFDLENBQUMsRUFBRSxDQUFDLFFBQVEsQ0FBQyxNQUFNLEVBQUUsRUFBRSxDQUFDLENBQUMsQ0FBQztJQUMzQixDQUFDLENBQUMsU0FBUyxDQUFDLFFBQVEsQ0FBQyxTQUFTLEVBQUUsRUFBRSxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsUUFBUSxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7SUFDdEUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxRQUFRLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLFNBQVMsQ0FBQyxDQUFDO0FBQ3hDLENBQUM7QUFsQ0Qsd0RBa0NDIn0=

package/build/main/raft/types.d.ts

@@ -0,0 +1,53 @@
+/** Raft server role */
+export type RaftRole = 'follower' | 'candidate' | 'leader';
+/** A single entry in the Raft log */
+export interface LogEntry<T = unknown> {
+    /** The term in which this entry was created */
+    term: number;
+    /** The command/data stored in this entry */
+    command: T;
+}
+export interface RequestVoteArgs {
+    type: 'RequestVote';
+    term: number;
+    candidateId: string;
+    lastLogIndex: number;
+    lastLogTerm: number;
+}
+export interface RequestVoteResult {
+    type: 'RequestVoteResult';
+    term: number;
+    voteGranted: boolean;
+}
+export interface AppendEntriesArgs<T = unknown> {
+    type: 'AppendEntries';
+    term: number;
+    leaderId: string;
+    prevLogIndex: number;
+    prevLogTerm: number;
+    entries: LogEntry<T>[];
+    leaderCommit: number;
+}
+export interface AppendEntriesResult {
+    type: 'AppendEntriesResult';
+    term: number;
+    success: boolean;
+    /** The peer ID of the responder (so the leader knows who replied) */
+    responderId: string;
+    /** The index of the last entry the follower accepted (for updating matchIndex) */
+    matchIndex: number;
+}
+export type RaftMessage<T = unknown> = RequestVoteArgs | RequestVoteResult | AppendEntriesArgs<T> | AppendEntriesResult;
+/** Persistent Raft state that must survive restarts */
+export interface RaftPersistentState {
+    currentTerm: number;
+    votedFor: string | null;
+}
+export interface RaftNodeEvents<T = unknown> {
+    /** Fired when a new leader is elected (may be self) */
+    leaderChanged: (leaderId: string | null) => void;
+    /** Fired when a log entry is committed and should be applied */
+    committed: (entry: LogEntry<T>, index: number) => void;
+    /** Fired when this node's role changes */
+    roleChanged: (role: RaftRole) => void;
+}

package/build/main/raft/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcmFmdC90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/build/main/transport/PeerJSTransport.d.ts

@@ -0,0 +1,46 @@
+import Peer from 'peerjs';
+import { Transport, TransportEventName, TransportEvents } from './Transport';
+/** Minimal subset of PeerJS DataConnection used by PeerJSTransport. */
+export interface DataConnectionLike {
+    readonly peer: string;
+    send(data: unknown): void | Promise<void>;
+    close(): void;
+    on(event: 'open', cb: () => void): void;
+    on(event: 'data', cb: (data: unknown) => void): void;
+    on(event: 'close', cb: () => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+}
+/** Minimal subset of PeerJS Peer used by PeerJSTransport. */
+export interface PeerLike {
+    on(event: 'open', cb: (id: string) => void): void;
+    on(event: 'connection', cb: (conn: DataConnectionLike) => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+    on(event: 'close', cb: () => void): void;
+    connect(peerId: string, options?: unknown): DataConnectionLike;
+    destroy(): void;
+}
+export interface PeerJSTransportOptions {
+    /** PeerJS Peer constructor options (host, port, path, etc.) */
+    peerOptions?: ConstructorParameters<typeof Peer>[1];
+    /** Optional fixed peer ID; if omitted PeerJS assigns one */
+    peerId?: string;
+}
+export declare class PeerJSTransport implements Transport {
+    private readonly peer;
+    private readonly connections;
+    private readonly pendingConnections;
+    private _localPeerId;
+    private readonly listeners;
+    constructor(peer: PeerLike);
+    constructor(options?: PeerJSTransportOptions);
+    get localPeerId(): string | undefined;
+    get connectedPeers(): ReadonlyArray<string>;
+    connect(remotePeerId: string): void;
+    send(remotePeerId: string, data: unknown): Promise<void>;
+    broadcast(data: unknown): Promise<void>;
+    on<E extends TransportEventName>(event: E, listener: TransportEvents[E]): void;
+    off<E extends TransportEventName>(event: E, listener: TransportEvents[E]): void;
+    close(): void;
+    private setupConnection;
+    private emit;
+}

package/build/main/transport/PeerJSTransport.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PeerJSTransport = void 0;
+const peerjs_1 = __importDefault(require("peerjs"));
+const CONNECT_OPTIONS = {
+    reliable: true,
+    serialization: 'json',
+};
+function isPeerLike(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        'on' in obj &&
+        'connect' in obj &&
+        'destroy' in obj);
+}
+class PeerJSTransport {
+    constructor(peerOrOptions) {
+        this.connections = new Map();
+        this.pendingConnections = new Map();
+        this.listeners = {
+            open: new Set(),
+            peerConnected: new Set(),
+            peerDisconnected: new Set(),
+            message: new Set(),
+            error: new Set(),
+            close: new Set(),
+        };
+        if (peerOrOptions && isPeerLike(peerOrOptions)) {
+            this.peer = peerOrOptions;
+        }
+        else {
+            const options = peerOrOptions;
+            this.peer = (options === null || options === void 0 ? void 0 : options.peerId)
+                ? new peerjs_1.default(options.peerId, options === null || options === void 0 ? void 0 : options.peerOptions)
+                : new peerjs_1.default(options === null || options === void 0 ? void 0 : options.peerOptions);
+        }
+        this.peer.on('open', (id) => {
+            this._localPeerId = id;
+            this.emit('open', id);
+        });
+        this.peer.on('connection', (conn) => {
+            this.setupConnection(conn);
+        });
+        this.peer.on('error', (err) => {
+            this.emit('error', err);
+        });
+        this.peer.on('close', () => {
+            this.emit('close');
+        });
+    }
+    get localPeerId() {
+        return this._localPeerId;
+    }
+    get connectedPeers() {
+        return Array.from(this.connections.keys());
+    }
+    connect(remotePeerId) {
+        if (this.connections.has(remotePeerId) ||
+            this.pendingConnections.has(remotePeerId)) {
+            return;
+        }
+        const conn = this.peer.connect(remotePeerId, CONNECT_OPTIONS);
+        this.setupConnection(conn);
+    }
+    async send(remotePeerId, data) {
+        const conn = this.connections.get(remotePeerId);
+        if (!conn) {
+            throw new Error(`No connection to peer: ${remotePeerId}`);
+        }
+        await conn.send(data);
+    }
+    async broadcast(data) {
+        const promises = [];
+        for (const conn of this.connections.values()) {
+            promises.push(Promise.resolve(conn.send(data)));
+        }
+        await Promise.all(promises);
+    }
+    on(event, listener) {
+        this.listeners[event].add(listener);
+    }
+    off(event, listener) {
+        this.listeners[event].delete(listener);
+    }
+    close() {
+        for (const conn of this.connections.values()) {
+            conn.close();
+        }
+        this.connections.clear();
+        this.pendingConnections.clear();
+        this.peer.destroy();
+    }
+    setupConnection(conn) {
+        const remotePeerId = conn.peer;
+        this.pendingConnections.set(remotePeerId, conn);
+        conn.on('open', () => {
+            this.pendingConnections.delete(remotePeerId);
+            // If we already have a connection to this peer (e.g. simultaneous connect),
+            // keep the one where local < remote to break the tie deterministically.
+            const existing = this.connections.get(remotePeerId);
+            if (existing) {
+                if (this._localPeerId && this._localPeerId < remotePeerId) {
+                    // keep existing, close the new one
+                    conn.close();
+                    return;
+                }
+                else {
+                    // replace existing with new
+                    existing.close();
+                }
+            }
+            this.connections.set(remotePeerId, conn);
+            this.emit('peerConnected', remotePeerId);
+        });
+        conn.on('data', (data) => {
+            this.emit('message', conn.peer, data);
+        });
+        conn.on('close', () => {
+            this.pendingConnections.delete(remotePeerId);
+            if (this.connections.get(remotePeerId) === conn) {
+                this.connections.delete(remotePeerId);
+                this.emit('peerDisconnected', remotePeerId);
+            }
+        });
+        conn.on('error', (err) => {
+            this.emit('error', err);
+        });
+    }
+    emit(event, ...args) {
+        for (const listener of this.listeners[event]) {
+            listener(...args);
+        }
+    }
+}
+exports.PeerJSTransport = PeerJSTransport;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUGVlckpTVHJhbnNwb3J0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3RyYW5zcG9ydC9QZWVySlNUcmFuc3BvcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7O0FBQUEsb0RBQWlEO0FBNkJqRCxNQUFNLGVBQWUsR0FBc0I7SUFDekMsUUFBUSxFQUFFLElBQUk7SUFDZCxhQUFhLEVBQUUsTUFBTTtDQUN0QixDQUFDO0FBU0YsU0FBUyxVQUFVLENBQUMsR0FBWTtJQUM5QixPQUFPLENBQ0wsT0FBTyxHQUFHLEtBQUssUUFBUTtRQUN2QixHQUFHLEtBQUssSUFBSTtRQUNaLElBQUksSUFBSSxHQUFHO1FBQ1gsU0FBUyxJQUFJLEdBQUc7UUFDaEIsU0FBUyxJQUFJLEdBQUcsQ0FDakIsQ0FBQztBQUNKLENBQUM7QUFFRCxNQUFhLGVBQWU7SUFnQjFCLFlBQVksYUFBaUQ7UUFkNUMsZ0JBQVcsR0FBRyxJQUFJLEdBQUcsRUFBOEIsQ0FBQztRQUNwRCx1QkFBa0IsR0FBRyxJQUFJLEdBQUcsRUFBOEIsQ0FBQztRQUUzRCxjQUFTLEdBQWdCO1lBQ3hDLElBQUksRUFBRSxJQUFJLEdBQUcsRUFBRTtZQUNmLGFBQWEsRUFBRSxJQUFJLEdBQUcsRUFBRTtZQUN4QixnQkFBZ0IsRUFBRSxJQUFJLEdBQUcsRUFBRTtZQUMzQixPQUFPLEVBQUUsSUFBSSxHQUFHLEVBQUU7WUFDbEIsS0FBSyxFQUFFLElBQUksR0FBRyxFQUFFO1lBQ2hCLEtBQUssRUFBRSxJQUFJLEdBQUcsRUFBRTtTQUNqQixDQUFDO1FBS0EsSUFBSSxhQUFhLElBQUksVUFBVSxDQUFDLGFBQWEsQ0FBQyxFQUFFO1lBQzlDLElBQUksQ0FBQyxJQUFJLEdBQUcsYUFBYSxDQUFDO1NBQzNCO2FBQU07WUFDTCxNQUFNLE9BQU8sR0FBRyxhQUFtRCxDQUFDO1lBQ3BFLElBQUksQ0FBQyxJQUFJLEdBQUcsQ0FBQSxPQUFPLGFBQVAsT0FBTyx1QkFBUCxPQUFPLENB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

package/build/main/transport/Transport.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Abstract transport layer for peer-to-peer communication.
+ * Implementations handle connection establishment, message sending/receiving,
+ * and peer lifecycle management.
+ */
+export interface TransportEvents {
+    /** Fired when this peer is ready and has an assigned ID */
+    open: (localPeerId: string) => void;
+    /** Fired when a new remote peer connects */
+    peerConnected: (remotePeerId: string) => void;
+    /** Fired when a remote peer disconnects */
+    peerDisconnected: (remotePeerId: string) => void;
+    /** Fired when a message is received from a remote peer */
+    message: (fromPeerId: string, data: unknown) => void;
+    /** Fired on transport-level errors */
+    error: (error: Error) => void;
+    /** Fired when the transport is closed */
+    close: () => void;
+}
+export type TransportEventName = keyof TransportEvents;
+export interface Transport {
+    /** The local peer ID, available after 'open' fires */
+    readonly localPeerId: string | undefined;
+    /** IDs of all currently connected remote peers */
+    readonly connectedPeers: ReadonlyArray<string>;
+    /** Connect to a remote peer by ID */
+    connect(remotePeerId: string): void;
+    /** Send a message to a specific remote peer */
+    send(remotePeerId: string, data: unknown): Promise<void>;
+    /** Broadcast a message to all connected peers */
+    broadcast(data: unknown): Promise<void>;
+    /** Register an event listener */
+    on<E extends TransportEventName>(event: E, listener: TransportEvents[E]): void;
+    /** Remove an event listener */
+    off<E extends TransportEventName>(event: E, listener: TransportEvents[E]): void;
+    /** Shut down the transport and close all connections */
+    close(): void;
+}

package/build/main/transport/Transport.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Abstract transport layer for peer-to-peer communication.
+ * Implementations handle connection establishment, message sending/receiving,
+ * and peer lifecycle management.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiVHJhbnNwb3J0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3RyYW5zcG9ydC9UcmFuc3BvcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7O0dBSUcifQ==