@valentinkolb/sync 0.1.0

package/tests/jobs.test.ts

@@ -0,0 +1,465 @@
+import { test, expect, beforeEach } from "bun:test";
+import { redis } from "bun";
+import { z } from "zod";
+import { jobs, ValidationError } from "../index";
+
+const testSchema = z.object({
+  message: z.string(),
+});
+
+// Clean up Redis before each test
+beforeEach(async () => {
+  const keys = await redis.send("KEYS", ["jobs:test:*"]);
+  if (Array.isArray(keys) && keys.length > 0) {
+    await redis.send("DEL", keys as string[]);
+  }
+});
+
+test("send creates a job with correct properties", async () => {
+  const q = jobs.create({
+    name: "test:send",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const job = await q.send({ message: "hello" });
+
+  expect(job.id).toBeDefined();
+  expect(job.data.message).toBe("hello");
+  expect(job.status).toBe("waiting");
+  expect(job.attempts).toBe(0);
+  expect(job.maxRetries).toBe(0);
+  expect(job.timeout).toBe(30000);
+  expect(job.createdAt).toBeGreaterThan(0);
+});
+
+test("send validates data against schema", async () => {
+  const q = jobs.create({
+    name: "test:validate",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  try {
+    // @ts-expect-error - intentionally invalid
+    await q.send({ invalid: "data" });
+    expect(true).toBe(false); // Should not reach
+  } catch (e) {
+    expect(e).toBeInstanceOf(ValidationError);
+  }
+});
+
+test("send with delay creates delayed job", async () => {
+  const q = jobs.create({
+    name: "test:delay",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const job = await q.send({ message: "delayed" }, { delay: 5000 });
+
+  expect(job.status).toBe("delayed");
+  expect(job.scheduledAt).toBeGreaterThan(Date.now());
+});
+
+test("send with at creates scheduled job", async () => {
+  const q = jobs.create({
+    name: "test:at",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const scheduledTime = Date.now() + 10000;
+  const job = await q.send({ message: "scheduled" }, { at: scheduledTime });
+
+  expect(job.status).toBe("delayed");
+  expect(job.scheduledAt).toBe(scheduledTime);
+});
+
+test("send with interval creates periodic job", async () => {
+  const q = jobs.create({
+    name: "test:interval",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const job = await q.send({ message: "periodic" }, { interval: 60000 });
+
+  expect(job.status).toBe("delayed"); // Starts delayed
+  expect(job.interval).toBe(60000);
+  expect(job.scheduledAt).toBeGreaterThan(Date.now());
+});
+
+test("send with interval and startImmediately creates immediate periodic job", async () => {
+  const q = jobs.create({
+    name: "test:interval-immediate",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const job = await q.send({ message: "periodic" }, { interval: 60000, startImmediately: true });
+
+  expect(job.status).toBe("waiting"); // Starts immediately
+  expect(job.interval).toBe(60000);
+});
+
+test("send with retries sets maxRetries", async () => {
+  const q = jobs.create({
+    name: "test:retries",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const job = await q.send({ message: "retry" }, { retries: 3 });
+
+  expect(job.maxRetries).toBe(3);
+});
+
+test("send with timeout sets timeout", async () => {
+  const q = jobs.create({
+    name: "test:timeout",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const job = await q.send({ message: "timeout" }, { timeout: 60000 });
+
+  expect(job.timeout).toBe(60000);
+});
+
+test("process executes handler for jobs", async () => {
+  const q = jobs.create({
+    name: "test:process",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const processed: string[] = [];
+
+  await q.send({ message: "job1" });
+  await q.send({ message: "job2" });
+
+  const stop = q.process(
+    async (job) => {
+      processed.push(job.data.message);
+    },
+    { pollInterval: 50 },
+  );
+
+  // Wait for processing
+  await Bun.sleep(200);
+  stop();
+
+  expect(processed).toContain("job1");
+  expect(processed).toContain("job2");
+});
+
+test("process calls onSuccess on successful job", async () => {
+  const q = jobs.create({
+    name: "test:onsuccess",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let successCalled = false;
+  let successJobId = "";
+
+  await q.send({ message: "success" });
+
+  const stop = q.process(
+    async () => {
+      // Success
+    },
+    {
+      pollInterval: 50,
+      onSuccess: (job) => {
+        successCalled = true;
+        successJobId = job.id;
+      },
+    },
+  );
+
+  await Bun.sleep(200);
+  stop();
+
+  expect(successCalled).toBe(true);
+  expect(successJobId).toBeDefined();
+});
+
+test("process retries failed jobs", async () => {
+  const q = jobs.create({
+    name: "test:retry",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let attempts = 0;
+
+  await q.send({ message: "retry" }, { retries: 2 });
+
+  const stop = q.process(
+    async () => {
+      attempts++;
+      if (attempts < 3) {
+        throw new Error("fail");
+      }
+    },
+    { pollInterval: 50 },
+  );
+
+  await Bun.sleep(500);
+  stop();
+
+  expect(attempts).toBe(3); // 1 initial + 2 retries
+});
+
+test("process calls onError when job permanently fails", async () => {
+  const q = jobs.create({
+    name: "test:onerror",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let errorCalled = false;
+  let errorMessage = "";
+
+  await q.send({ message: "fail" }, { retries: 0 });
+
+  const stop = q.process(
+    async () => {
+      throw new Error("permanent failure");
+    },
+    {
+      pollInterval: 50,
+      onError: (job, error) => {
+        errorCalled = true;
+        errorMessage = error.message;
+      },
+    },
+  );
+
+  await Bun.sleep(200);
+  stop();
+
+  expect(errorCalled).toBe(true);
+  expect(errorMessage).toBe("permanent failure");
+});
+
+test("process calls onFinally after every attempt", async () => {
+  const q = jobs.create({
+    name: "test:onfinally",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let finallyCalls = 0;
+
+  await q.send({ message: "finally" }, { retries: 1 });
+
+  const stop = q.process(
+    async () => {
+      throw new Error("fail");
+    },
+    {
+      pollInterval: 50,
+      onFinally: () => {
+        finallyCalls++;
+      },
+    },
+  );
+
+  await Bun.sleep(300);
+  stop();
+
+  expect(finallyCalls).toBe(2); // 1 initial + 1 retry
+});
+
+test("delayed jobs are promoted when ready", async () => {
+  const q = jobs.create({
+    name: "test:promote",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let processed = false;
+
+  await q.send({ message: "delayed" }, { delay: 100 });
+
+  const stop = q.process(
+    async () => {
+      processed = true;
+    },
+    { pollInterval: 50 },
+  );
+
+  // Should not be processed yet
+  await Bun.sleep(50);
+  expect(processed).toBe(false);
+
+  // Should be processed after delay
+  await Bun.sleep(200);
+  expect(processed).toBe(true);
+
+  stop();
+});
+
+test("interval jobs are rescheduled after completion", async () => {
+  const q = jobs.create({
+    name: "test:interval-reschedule",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let processCount = 0;
+
+  await q.send({ message: "interval" }, { interval: 100, startImmediately: true });
+
+  const stop = q.process(
+    async () => {
+      processCount++;
+    },
+    { pollInterval: 50 },
+  );
+
+  await Bun.sleep(350);
+  stop();
+
+  expect(processCount).toBeGreaterThanOrEqual(2);
+});
+
+test("interval jobs are rescheduled after failure", async () => {
+  const q = jobs.create({
+    name: "test:interval-fail",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let processCount = 0;
+  let errorCount = 0;
+
+  await q.send({ message: "interval-fail" }, { interval: 100, startImmediately: true, retries: 0 });
+
+  const stop = q.process(
+    async () => {
+      processCount++;
+      throw new Error("always fail");
+    },
+    {
+      pollInterval: 50,
+      onError: () => {
+        errorCount++;
+      },
+    },
+  );
+
+  await Bun.sleep(350);
+  stop();
+
+  expect(processCount).toBeGreaterThanOrEqual(2);
+  expect(errorCount).toBeGreaterThanOrEqual(2);
+});
+
+test("concurrent processing with multiple workers", async () => {
+  const q = jobs.create({
+    name: "test:concurrent",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  const processed: string[] = [];
+  const startTimes: number[] = [];
+
+  // Send 5 jobs
+  for (let i = 0; i < 5; i++) {
+    await q.send({ message: `job${i}` });
+  }
+
+  const stop = q.process(
+    async (job) => {
+      startTimes.push(Date.now());
+      await Bun.sleep(100); // Simulate work
+      processed.push(job.data.message);
+    },
+    { concurrency: 3, pollInterval: 50 },
+  );
+
+  await Bun.sleep(500);
+  stop();
+
+  expect(processed.length).toBe(5);
+
+  // Check that some jobs started concurrently (within 50ms of each other)
+  const concurrent = startTimes.filter((t, i) => i > 0 && t - startTimes[i - 1] < 50);
+  expect(concurrent.length).toBeGreaterThan(0);
+});
+
+test("job timeout causes hard fail", async () => {
+  const q = jobs.create({
+    name: "test:timeout-fail",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  await q.send({ message: "slow" }, { timeout: 100, retries: 0 });
+
+  // Start a processor that will claim the job but not finish it
+  let jobClaimed = false;
+  const stop = q.process(
+    async () => {
+      jobClaimed = true;
+      // Simulate a hanging job - sleep longer than timeout
+      await Bun.sleep(500);
+    },
+    { pollInterval: 50 },
+  );
+
+  // Wait for job to be claimed
+  await Bun.sleep(80);
+  expect(jobClaimed).toBe(true);
+
+  // Stop processor so we can start a new one that will check timeouts
+  stop();
+
+  // Wait for timeout to expire
+  await Bun.sleep(100);
+
+  // Start new processor to trigger timeout check
+  let timeoutDetected = false;
+  const stop2 = q.process(async () => {}, {
+    pollInterval: 50,
+  });
+
+  // Wait for timeout check to run
+  await Bun.sleep(150);
+  stop2();
+
+  // Verify job was marked as failed
+  const failedCount = await redis.scard("jobs:test:test:timeout-fail:failed");
+  expect(failedCount).toBe(1);
+});
+
+test("stop function stops processing", async () => {
+  const q = jobs.create({
+    name: "test:stop",
+    schema: testSchema,
+    prefix: "jobs:test",
+  });
+
+  let processCount = 0;
+
+  const stop = q.process(
+    async () => {
+      processCount++;
+    },
+    { pollInterval: 50 },
+  );
+
+  stop();
+
+  // Send jobs after stop
+  await q.send({ message: "after-stop" });
+
+  await Bun.sleep(200);
+
+  expect(processCount).toBe(0);
+});

package/tests/mutex.test.ts

@@ -0,0 +1,223 @@
+import { test, expect, beforeEach } from "bun:test";
+import { redis } from "bun";
+import { mutex, LockError } from "../index";
+
+// Clean up Redis before each test
+beforeEach(async () => {
+  const keys = await redis.send("KEYS", ["mutex:test:*"]);
+  if (Array.isArray(keys) && keys.length > 0) {
+    await redis.send("DEL", keys as string[]);
+  }
+});
+
+test("acquires lock successfully", async () => {
+  const m = mutex.create({ prefix: "mutex:test" });
+
+  const lock = await m.acquire("resource:1");
+  expect(lock).not.toBeNull();
+  expect(lock!.resource).toBe("mutex:test:resource:1");
+  expect(lock!.value).toHaveLength(32); // 16 bytes hex = 32 chars
+
+  await m.release(lock!);
+});
+
+test("only one lock can be held at a time", async () => {
+  const m = mutex.create({
+    prefix: "mutex:test",
+    retryCount: 0, // Don't retry
+  });
+
+  const lock1 = await m.acquire("resource:2");
+  expect(lock1).not.toBeNull();
+
+  const lock2 = await m.acquire("resource:2");
+  expect(lock2).toBeNull();
+
+  await m.release(lock1!);
+});
+
+test("lock is released and can be acquired again", async () => {
+  const m = mutex.create({
+    prefix: "mutex:test",
+    retryCount: 0,
+  });
+
+  const lock1 = await m.acquire("resource:3");
+  expect(lock1).not.toBeNull();
+
+  await m.release(lock1!);
+
+  const lock2 = await m.acquire("resource:3");
+  expect(lock2).not.toBeNull();
+
+  await m.release(lock2!);
+});
+
+test("lock expires after TTL", async () => {
+  const m = mutex.create({
+    prefix: "mutex:test",
+    retryCount: 0,
+    defaultTtl: 100, // 100ms TTL
+  });
+
+  const lock1 = await m.acquire("resource:4");
+  expect(lock1).not.toBeNull();
+
+  // Wait for lock to expire
+  await Bun.sleep(150);
+
+  // Should be able to acquire now
+  const lock2 = await m.acquire("resource:4");
+  expect(lock2).not.toBeNull();
+
+  await m.release(lock2!);
+});
+
+test("withLock executes function and releases lock", async () => {
+  const m = mutex.create({ prefix: "mutex:test" });
+
+  let executed = false;
+  const result = await m.withLock("resource:5", async () => {
+    executed = true;
+    return 42;
+  });
+
+  expect(executed).toBe(true);
+  expect(result).toBe(42);
+
+  // Lock should be released, can acquire again
+  const lock = await m.acquire("resource:5");
+  expect(lock).not.toBeNull();
+  await m.release(lock!);
+});
+
+test("withLock releases lock on error", async () => {
+  const m = mutex.create({ prefix: "mutex:test", retryCount: 0 });
+
+  try {
+    await m.withLock("resource:6", async () => {
+      throw new Error("test error");
+    });
+  } catch (e) {
+    expect((e as Error).message).toBe("test error");
+  }
+
+  // Lock should be released
+  const lock = await m.acquire("resource:6");
+  expect(lock).not.toBeNull();
+  await m.release(lock!);
+});
+
+test("withLock returns null when lock cannot be acquired", async () => {
+  const m = mutex.create({ prefix: "mutex:test", retryCount: 0 });
+
+  // Hold the lock
+  const lock1 = await m.acquire("resource:7");
+
+  // Try withLock - should return null
+  const result = await m.withLock("resource:7", async () => {
+    return 42;
+  });
+
+  expect(result).toBeNull();
+
+  await m.release(lock1!);
+});
+
+test("withLockOrThrow throws LockError when lock cannot be acquired", async () => {
+  const m = mutex.create({ prefix: "mutex:test", retryCount: 0 });
+
+  // Hold the lock
+  const lock1 = await m.acquire("resource:8");
+
+  try {
+    await m.withLockOrThrow("resource:8", async () => {
+      return 42;
+    });
+    expect(true).toBe(false); // Should not reach
+  } catch (e) {
+    expect(e).toBeInstanceOf(LockError);
+    expect((e as LockError).resource).toBe("resource:8");
+  }
+
+  await m.release(lock1!);
+});
+
+test("extend prolongs lock TTL", async () => {
+  const m = mutex.create({
+    prefix: "mutex:test",
+    retryCount: 0,
+    defaultTtl: 100,
+  });
+
+  const lock = await m.acquire("resource:9");
+  expect(lock).not.toBeNull();
+
+  // Extend the lock
+  const extended = await m.extend(lock!, 1000);
+  expect(extended).toBe(true);
+  expect(lock!.ttl).toBe(1000);
+
+  // Wait past original TTL
+  await Bun.sleep(150);
+
+  // Lock should still be held (can't acquire)
+  const lock2 = await m.acquire("resource:9");
+  expect(lock2).toBeNull();
+
+  await m.release(lock!);
+});
+
+test("extend fails if lock was lost", async () => {
+  const m = mutex.create({
+    prefix: "mutex:test",
+    retryCount: 0,
+    defaultTtl: 100,
+  });
+
+  const lock = await m.acquire("resource:10");
+  expect(lock).not.toBeNull();
+
+  // Wait for lock to expire
+  await Bun.sleep(150);
+
+  // Try to extend expired lock
+  const extended = await m.extend(lock!, 1000);
+  expect(extended).toBe(false);
+});
+
+test("different resources can be locked independently", async () => {
+  const m = mutex.create({ prefix: "mutex:test", retryCount: 0 });
+
+  const lockA = await m.acquire("resource:a");
+  const lockB = await m.acquire("resource:b");
+
+  expect(lockA).not.toBeNull();
+  expect(lockB).not.toBeNull();
+
+  await m.release(lockA!);
+  await m.release(lockB!);
+});
+
+test("retries with delay when lock is held", async () => {
+  const m = mutex.create({
+    prefix: "mutex:test",
+    retryCount: 5,
+    retryDelay: 50,
+    defaultTtl: 100,
+  });
+
+  // Acquire lock that will expire
+  const lock1 = await m.acquire("resource:11");
+  expect(lock1).not.toBeNull();
+
+  // Try to acquire - should retry and eventually succeed
+  const start = Date.now();
+  const lock2 = await m.acquire("resource:11");
+  const elapsed = Date.now() - start;
+
+  expect(lock2).not.toBeNull();
+  expect(elapsed).toBeGreaterThanOrEqual(50); // At least one retry
+
+  await m.release(lock2!);
+});

package/tests/preload.ts

@@ -0,0 +1,2 @@
+// Set Redis URL for tests before any imports
+process.env.REDIS_URL = "redis://localhost:6399";