@flink-app/flink 1.0.0 → 2.0.0-alpha.100

package/spec/FlinkJob.spec.ts

@@ -0,0 +1,171 @@
+import { FlinkApp, autoRegisteredJobs } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { FlinkJobFile } from "../src/FlinkJob";
+import { FlinkLogFactory } from "../src/FlinkLogFactory";
+
+interface TestContext extends FlinkContext {}
+
+describe("FlinkJob error handling", () => {
+    let app: FlinkApp<TestContext>;
+    let consoleErrorSpy: jasmine.Spy;
+
+    beforeEach(() => {
+        consoleErrorSpy = spyOn(console, "error");
+    });
+
+    afterEach(async () => {
+        autoRegisteredJobs.length = 0;
+        if (app?.started) {
+            await app.stop();
+        }
+    });
+
+    it("should catch and log errors from afterDelay 0ms jobs without crashing", async () => {
+        const job: FlinkJobFile = {
+            Job: { id: "failing-job-0ms", afterDelay: "0ms" },
+            default: async () => {
+                throw new Error("Job error 0ms");
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-errors-0ms", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 50));
+
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it("should catch and log errors from afterDelay jobs without crashing", async () => {
+        const job: FlinkJobFile = {
+            Job: { id: "failing-job-delay", afterDelay: "10ms" },
+            default: async () => {
+                throw new Error("Job error with delay");
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-errors-delay", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it("should catch and log errors from interval jobs without crashing", async () => {
+        const job: FlinkJobFile = {
+            Job: { id: "failing-interval-job", interval: "10ms" },
+            default: async () => {
+                throw new Error("Interval job error");
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-errors-interval", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it("should run afterDelay 0ms job exactly once", async () => {
+        let runCount = 0;
+
+        const job: FlinkJobFile = {
+            Job: { id: "once-job-0ms", afterDelay: "0ms" },
+            default: async () => {
+                runCount++;
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-once-0ms", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        expect(runCount).toBe(1);
+    });
+});
+
+describe("FlinkJob leader election with runOnAllInstances", () => {
+    let app: FlinkApp<TestContext>;
+
+    afterEach(async () => {
+        autoRegisteredJobs.length = 0;
+        if (app?.started) {
+            await app.stop();
+        }
+    });
+
+    it("should run all jobs when leader election is enabled but no db is configured", async () => {
+        const schedulerLog = FlinkLogFactory.createLogger("flink.scheduler");
+        const warnSpy = spyOn(schedulerLog, "warn");
+
+        let leaderJobRan = false;
+        let allInstanceJobRan = false;
+
+        autoRegisteredJobs.push({
+            Job: { id: "leader-only-job", afterDelay: "0ms" },
+            default: async () => {
+                leaderJobRan = true;
+            },
+        });
+
+        autoRegisteredJobs.push({
+            Job: { id: "all-instance-job", afterDelay: "0ms", runOnAllInstances: true },
+            default: async () => {
+                allInstanceJobRan = true;
+            },
+        });
+
+        app = new FlinkApp<TestContext>({
+            name: "test-leader-no-db",
+            disableHttpServer: true,
+            scheduling: { leaderElection: true },
+        });
+
+        await app.start();
+        await new Promise((resolve) => setTimeout(resolve, 50));
+
+        // Without db, falls back to running all jobs
+        expect(leaderJobRan).toBe(true);
+        expect(allInstanceJobRan).toBe(true);
+        expect(warnSpy).toHaveBeenCalled();
+        const warnMessage = warnSpy.calls.mostRecent().args[0];
+        expect(warnMessage).toContain("Leader election is enabled but no database is configured");
+    });
+
+    it("should not start scheduler for leader-only jobs when not leader", async () => {
+        // Without a real MongoDB, we can't fully test leader election.
+        // This test verifies that when leaderElection is enabled without db,
+        // the warning is shown and all jobs still run as a fallback.
+        let jobRanCount = 0;
+
+        autoRegisteredJobs.push({
+            Job: { id: "interval-job", interval: "50ms" },
+            default: async () => {
+                jobRanCount++;
+            },
+        });
+
+        app = new FlinkApp<TestContext>({
+            name: "test-no-db-fallback",
+            disableHttpServer: true,
+            scheduling: { leaderElection: true },
+        });
+
+        await app.start();
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        // Should have run at least once since it falls back without db
+        expect(jobRanCount).toBeGreaterThan(0);
+    });
+});

package/spec/FlinkLogFactory.spec.ts

@@ -0,0 +1,337 @@
+import { FlinkLogFactory } from "../src/FlinkLogFactory";
+
+describe("FlinkLogFactory - Hierarchical Prefix Matching", () => {
+    beforeEach(() => {
+        // Reset factory state before each test
+        FlinkLogFactory.resetComponentLevels();
+        FlinkLogFactory.resetHierarchicalLevels();
+        FlinkLogFactory.resetWildcardLevels();
+        FlinkLogFactory.setGlobalLevel("info");
+    });
+
+    describe("Basic Prefix Matching (Java-style)", () => {
+        it("should match flink.ai.* prefix", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            const openaiLog = FlinkLogFactory.createLogger("flink.ai.openai");
+            const anthropicLog = FlinkLogFactory.createLogger("flink.ai.anthropic");
+            const dbLog = FlinkLogFactory.createLogger("flink.database.mongodb");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.anthropic")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.mongodb")).toBeNull(); // Falls back to global
+        });
+
+        it("should match multi-level prefixes", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            const deepLog = FlinkLogFactory.createLogger("flink.ai.openai.v4.gpt");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4.gpt")).toBe("debug");
+        });
+
+        it("should handle prefix with trailing dot", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai.", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+        });
+
+        it("should handle prefix without trailing dot", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+        });
+    });
+
+    describe("Case Insensitivity", () => {
+        it("should normalize logger names to lowercase", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            const log1 = FlinkLogFactory.createLogger("flink.ai.openai");
+            const log2 = FlinkLogFactory.createLogger("Flink.AI.OpenAI");
+            const log3 = FlinkLogFactory.createLogger("FLINK.AI.OPENAI");
+
+            // All should return the same logger instance
+            expect(log1).toBe(log2);
+            expect(log2).toBe(log3);
+        });
+
+        it("should resolve levels case-insensitively", () => {
+            FlinkLogFactory.setHierarchicalLevel("Flink.AI", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("Flink.AI.OpenAI")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("FLINK.AI.OPENAI")).toBe("debug");
+        });
+    });
+
+    describe("Precedence Rules", () => {
+        it("should prefer exact match over prefix", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+            FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace"); // Exact
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.anthropic")).toBe("debug"); // Prefix
+        });
+
+        it("should prefer more specific prefix over less specific", () => {
+            FlinkLogFactory.setGlobalLevel("warn");
+            FlinkLogFactory.setHierarchicalLevel("flink", "info");
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+            FlinkLogFactory.setHierarchicalLevel("flink.ai.openai", "trace");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4")).toBe("trace"); // Most specific: flink.ai.openai
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.claude")).toBe("debug"); // flink.ai
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.mongodb")).toBe("info"); // flink
+            expect(FlinkLogFactory.getEffectiveLevel("other.service")).toBeNull(); // Global fallback
+        });
+
+        it("should handle overlapping prefixes correctly", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink", "warn");
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug"); // More specific
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database")).toBe("warn"); // Less specific
+        });
+    });
+
+    describe("Wildcard Patterns", () => {
+        it("should support single-level wildcard (*)", () => {
+            FlinkLogFactory.setWildcardLevel("flink.ai.*", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug"); // Matches
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4")).toBeNull(); // Too deep
+        });
+
+        it("should support multi-level wildcard (**)", () => {
+            FlinkLogFactory.setWildcardLevel("flink.ai.**", "trace");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4")).toBe("trace");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4.gpt")).toBe("trace");
+        });
+
+        it("should support partial segment wildcard", () => {
+            FlinkLogFactory.setWildcardLevel("flink.database.mongo*", "warn");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.mongodb")).toBe("warn");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.mongoose")).toBe("warn");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.redis")).toBeNull();
+        });
+
+        it("should prefer prefix match over wildcard", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+            FlinkLogFactory.setWildcardLevel("flink.ai.*", "trace");
+
+            // Prefix is checked first and matches (more intuitive)
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+        });
+    });
+
+    describe("Environment Variable Parsing", () => {
+        beforeEach(() => {
+            // Clear environment
+            delete process.env.LOG_LEVEL;
+        });
+
+        it("should parse LOG_LEVEL env var for global level", () => {
+            process.env.LOG_LEVEL = "debug";
+
+            // Reset to force re-initialization
+            (FlinkLogFactory as any).initialized = false;
+            FlinkLogFactory.configure();
+
+            expect(FlinkLogFactory.getGlobalLevel()).toBe("debug");
+        });
+
+        it("should ignore invalid LOG_LEVEL values", () => {
+            process.env.LOG_LEVEL = "invalid";
+
+            (FlinkLogFactory as any).initialized = false;
+            FlinkLogFactory.configure();
+
+            expect(FlinkLogFactory.getGlobalLevel()).toBe("info"); // Default
+        });
+
+        it("should be case-insensitive", () => {
+            process.env.LOG_LEVEL = "DEBUG";
+
+            (FlinkLogFactory as any).initialized = false;
+            FlinkLogFactory.configure();
+
+            expect(FlinkLogFactory.getGlobalLevel()).toBe("debug");
+        });
+    });
+
+    describe("Config File Loading", () => {
+        it("should parse components map with wildcards", () => {
+            const config = {
+                global: "info" as const,
+                showTimestamps: false,
+                components: {
+                    "flink.ai.openai": "trace" as const,
+                    "flink.ai.*": "debug" as const,
+                    "flink.database.**": "warn" as const,
+                    "flink.handlers.": "info" as const
+                }
+            };
+
+            (FlinkLogFactory as any).initialized = false;
+            FlinkLogFactory.configure(config);
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.anthropic")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.mongodb.connection")).toBe("warn");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.handlers.car")).toBe("info");
+            expect(FlinkLogFactory.getShowTimestamps()).toBe(false);
+        });
+
+        it("should prioritize config file over env var", () => {
+            process.env.LOG_LEVEL = "error";
+
+            const config = {
+                global: "debug" as const,
+                components: {}
+            };
+
+            (FlinkLogFactory as any).initialized = false;
+            FlinkLogFactory.configure(config);
+
+            expect(FlinkLogFactory.getGlobalLevel()).toBe("debug"); // Config wins
+        });
+    });
+
+    describe("Programmatic API", () => {
+        it("should allow setting hierarchical levels", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+        });
+
+        it("should allow setting wildcard levels", () => {
+            FlinkLogFactory.setWildcardLevel("flink.ai.*", "trace");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace");
+        });
+
+        it("should allow setting exact levels", () => {
+            FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace");
+        });
+
+        it("should allow clearing exact levels", () => {
+            FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+            FlinkLogFactory.setComponentLevel("flink.ai.openai", null);
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBeNull();
+        });
+
+        it("should allow resetting hierarchical levels", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+            FlinkLogFactory.resetHierarchicalLevels();
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBeNull();
+        });
+
+        it("should allow resetting wildcard levels", () => {
+            FlinkLogFactory.setWildcardLevel("flink.ai.*", "debug");
+            FlinkLogFactory.resetWildcardLevels();
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBeNull();
+        });
+    });
+
+    describe("Edge Cases", () => {
+        it("should handle empty segments in pattern", () => {
+            // Double dots should be normalized
+            FlinkLogFactory.setHierarchicalLevel("flink..ai", "debug");
+
+            // Should not match due to empty segment
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBeNull();
+        });
+
+        it("should handle single segment names", () => {
+            FlinkLogFactory.setComponentLevel("performance", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("performance")).toBe("debug");
+        });
+
+        it("should handle flink prefix requirement", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            // Without flink prefix
+            expect(FlinkLogFactory.getEffectiveLevel("ai.openai")).toBeNull();
+
+            // With flink prefix
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+        });
+
+        it("should not match partial prefix", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            // Should not match "flink.air" - must be followed by dot
+            expect(FlinkLogFactory.getEffectiveLevel("flink.airline")).toBeNull();
+        });
+
+        it("should handle exact match for name with dots", () => {
+            FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4")).toBeNull();
+        });
+    });
+
+    describe("Specificity Ordering", () => {
+        it("should sort hierarchical configs by specificity", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink", "warn");
+            FlinkLogFactory.setHierarchicalLevel("flink.ai.openai", "trace");
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+            // Most specific should win
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4")).toBe("trace");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.claude")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database")).toBe("warn");
+        });
+
+        it("should sort wildcard configs by specificity", () => {
+            FlinkLogFactory.setWildcardLevel("flink.*", "warn");
+            FlinkLogFactory.setWildcardLevel("flink.ai.**", "trace");
+            FlinkLogFactory.setWildcardLevel("flink.ai.*", "debug");
+
+            // More specific wildcard should win
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug"); // flink.ai.* (2 segments)
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.v4")).toBe("trace"); // flink.ai.** (2 segments, multi-level)
+        });
+    });
+
+    describe("Real-World Scenarios", () => {
+        it("should handle typical development setup", () => {
+            FlinkLogFactory.setGlobalLevel("warn");
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+            FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace"); // Trace for OpenAI
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.anthropic")).toBe("debug"); // Debug for other AI
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.mongodb")).toBeNull(); // Warn (global)
+        });
+
+        it("should handle production debugging", () => {
+            FlinkLogFactory.setGlobalLevel("error");
+            FlinkLogFactory.setHierarchicalLevel("flink.ai.openai", "debug");
+
+            // Only OpenAI components get debug, everything else is error
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai.streaming")).toBe("debug");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.anthropic")).toBeNull(); // Error (global)
+        });
+
+        it("should handle test environment", () => {
+            FlinkLogFactory.setHierarchicalLevel("flink.ai", "trace");
+            FlinkLogFactory.setHierarchicalLevel("flink.database", "debug");
+
+            expect(FlinkLogFactory.getEffectiveLevel("flink.ai.openai")).toBe("trace");
+            expect(FlinkLogFactory.getEffectiveLevel("flink.database.mongodb")).toBe("debug");
+        });
+    });
+});

package/spec/FlinkRepo.spec.ts

@@ -60,7 +60,7 @@ describe("FlinkRepo", () => {
     it("should update document", async () => {
         const createdDoc = await repo.create({ name: "bar" });
 
-        const updatedDoc = await repo.updateOne(createdDoc._id + "", {
+        const updatedDoc = await repo.updateById(createdDoc._id + "", {
             name: "foo",
             "nested.field": 1,
         });

package/spec/LeaderElection.spec.ts

@@ -0,0 +1,174 @@
+import { LeaderElection } from "../src/LeaderElection";
+
+describe("LeaderElection", () => {
+    let mockCollection: any;
+    let mockDb: any;
+
+    beforeEach(() => {
+        mockCollection = {
+            createIndex: jasmine.createSpy("createIndex").and.resolveTo(undefined),
+            findOneAndUpdate: jasmine.createSpy("findOneAndUpdate"),
+            deleteOne: jasmine.createSpy("deleteOne").and.resolveTo(undefined),
+        };
+
+        mockDb = {
+            collection: jasmine.createSpy("collection").and.returnValue(mockCollection),
+        };
+    });
+
+    it("should create collection with provided name", () => {
+        new LeaderElection(mockDb, { collectionName: "_my_leader" });
+        expect(mockDb.collection).toHaveBeenCalledWith("_my_leader");
+    });
+
+    it("should use default collection name", () => {
+        new LeaderElection(mockDb);
+        expect(mockDb.collection).toHaveBeenCalledWith("_flink_leader");
+    });
+
+    it("should create TTL index on start", async () => {
+        const le = new LeaderElection(mockDb, { leaseDurationMs: 10000 });
+
+        mockCollection.findOneAndUpdate.and.resolveTo({
+            instanceId: "will-not-match",
+        });
+
+        await le.start(
+            () => {},
+            () => {}
+        );
+        await le.stop();
+
+        expect(mockCollection.createIndex).toHaveBeenCalledWith(
+            { lastHeartbeat: 1 },
+            { expireAfterSeconds: 20 } // 2x lease duration in seconds
+        );
+    });
+
+    it("should call onBecameLeader when claiming leadership", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        // findOneAndUpdate returns a document with our instanceId
+        // We need to intercept the instanceId set in the update
+        mockCollection.findOneAndUpdate.and.callFake((_filter: any, update: any) => {
+            return Promise.resolve({
+                instanceId: update.$set.instanceId,
+            });
+        });
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(true);
+        expect(onBecameLeader).toHaveBeenCalledTimes(1);
+        expect(onLostLeadership).not.toHaveBeenCalled();
+
+        await le.stop();
+    });
+
+    it("should not become leader when another instance holds the lock", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        // findOneAndUpdate returns a document with a different instanceId
+        mockCollection.findOneAndUpdate.and.resolveTo({
+            instanceId: "other-instance",
+        });
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(false);
+        expect(onBecameLeader).not.toHaveBeenCalled();
+
+        await le.stop();
+    });
+
+    it("should handle duplicate key error gracefully", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        const duplicateKeyError = new Error("E11000 duplicate key");
+        (duplicateKeyError as any).code = 11000;
+        mockCollection.findOneAndUpdate.and.rejectWith(duplicateKeyError);
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(false);
+        expect(onBecameLeader).not.toHaveBeenCalled();
+
+        await le.stop();
+    });
+
+    it("should release leadership on stop", async () => {
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        mockCollection.findOneAndUpdate.and.callFake((_filter: any, update: any) => {
+            return Promise.resolve({
+                instanceId: update.$set.instanceId,
+            });
+        });
+
+        await le.start(
+            () => {},
+            () => {}
+        );
+
+        expect(le.isLeader).toBe(true);
+
+        await le.stop();
+
+        expect(mockCollection.deleteOne).toHaveBeenCalled();
+        expect(le.isLeader).toBe(false);
+    });
+
+    it("should call onLostLeadership when losing the lock", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 100,
+        });
+
+        let callCount = 0;
+        mockCollection.findOneAndUpdate.and.callFake((_filter: any, update: any) => {
+            callCount++;
+            if (callCount === 1) {
+                // First call: we become leader
+                return Promise.resolve({ instanceId: update.$set.instanceId });
+            }
+            // Subsequent calls: another instance took over
+            return Promise.resolve({ instanceId: "other-instance" });
+        });
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(true);
+
+        // Wait for next heartbeat cycle
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        expect(onLostLeadership).toHaveBeenCalledTimes(1);
+        expect(le.isLeader).toBe(false);
+
+        await le.stop();
+    });
+});