@12-apps/jobs 1.4.0 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/jobs",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "description": "Generic background-job library: a typed job registry with retries, exponential backoff and cron schedules, behind a swappable driver port (BullMQ/Redis in production, inline execution in tests). Framework-free; knows nothing about the host app's domain, ORM or transport.",
   "exports": {
@@ -20,8 +20,8 @@
     "bullmq": "^5.81.2"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.5.0",
-    "@12-apps/typescript-config": "^1.5.0",
+    "@12-apps/eslint-config": "^1.5.2",
+    "@12-apps/typescript-config": "^1.5.2",
     "eslint": "^9.39.1",
     "eslint-plugin-test-flakiness": "^1.4.0",
     "typescript": "^5.9.2",
@@ -46,6 +46,14 @@
     "prisma",
     "*.js",
     "*.mjs",
-    "*.md"
+    "*.md",
+    "!eslint.config.js",
+    "!**/__tests__/**",
+    "!**/tests/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.stories.*",
+    "!**/*.test-story.*",
+    "!**/test-helpers.*"
   ]
 }

package/eslint.config.js

@@ -1,22 +0,0 @@
-import { config as baseConfig } from "@12-apps/eslint-config/base";
-import testFlakiness from "eslint-plugin-test-flakiness";
-
-/**
- * The everyday DX lint for this package. Mirrors `packages/entitlements`:
- * `eslint-plugin-test-flakiness` is registered with every rule OFF so that
- * inline disable directives in test files RESOLVE here, while the rules
- * themselves stay enforced by the repo-root flakiness lane.
- */
-
-/** @type {import("eslint").Linter.Config[]} */
-export default [
-  ...baseConfig,
-  {
-    files: ["**/__tests__/**", "**/*.test.ts"],
-    plugins: { "test-flakiness": testFlakiness },
-    linterOptions: { reportUnusedDisableDirectives: "off" },
-  },
-  {
-    ignores: ["dist/**", "node_modules/**", "coverage/**"],
-  },
-];

package/src/core/__tests__/registry.test.ts

@@ -1,101 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-import { createInlineJobDriver } from "../../drivers/inline";
-import { clearJobs, defineJob, DuplicateJobError, findJob, listJobs } from "../registry";
-import { configureJobs, enqueueJob, resetJobRuntime, startJobWorkers } from "../runtime";
-
-afterEach(() => {
-  clearJobs();
-  resetJobRuntime();
-});
-
-describe("defineJob", () => {
-  it("registers the definition under its name", () => {
-    const job = defineJob({ name: "a.job", handle: () => Promise.resolve() });
-
-    expect(job.name).toBe("a.job");
-    expect(findJob("a.job")).toBe(job.definition);
-    expect(listJobs()).toHaveLength(1);
-  });
-
-  it("refuses a duplicate name rather than replacing the handler", () => {
-    defineJob({ name: "a.job", handle: () => Promise.resolve() });
-
-    expect(() => defineJob({ name: "a.job", handle: () => Promise.resolve() })).toThrow(
-      DuplicateJobError,
-    );
-  });
-});
-
-describe("enqueue", () => {
-  it("runs the handler through the installed driver", async () => {
-    const handle = vi.fn().mockResolvedValue(undefined);
-    const job = defineJob<{ id: string }>({ name: "a.job", handle });
-    configureJobs({ driver: createInlineJobDriver({ logger: silentLogger() }) });
-
-    const result = await job.enqueue({ id: "x" });
-
-    expect(result).toEqual({ enqueued: true });
-    expect(handle).toHaveBeenCalledWith(
-      { id: "x" },
-      expect.objectContaining({ attempt: 1, maxAttempts: 1 }),
-    );
-  });
-
-  it("reports rather than throws when no driver is configured", async () => {
-    const job = defineJob({ name: "a.job", handle: () => Promise.resolve() });
-
-    await expect(job.enqueue()).resolves.toEqual({
-      enqueued: false,
-      reason: "no-driver",
-    });
-  });
-
-  it("reports rather than throws when the driver itself fails", async () => {
-    const definition = { name: "a.job", handle: () => Promise.resolve() };
-    configureJobs({
-      logger: silentLogger(),
-      driver: {
-        kind: "broken",
-        enqueue: () => Promise.reject(new Error("redis is down")),
-        start: () => Promise.resolve(),
-        stop: () => Promise.resolve(),
-      },
-    });
-
-    await expect(enqueueJob(definition, undefined, {})).resolves.toEqual({
-      enqueued: false,
-      reason: "error",
-    });
-  });
-});
-
-describe("startJobWorkers", () => {
-  it("starts every registered job once, ignoring a second call", async () => {
-    defineJob({ name: "a.job", handle: () => Promise.resolve() });
-    const start = vi.fn().mockResolvedValue(undefined);
-    configureJobs({
-      logger: silentLogger(),
-      driver: {
-        kind: "spy",
-        enqueue: () => Promise.resolve({ enqueued: true }),
-        start,
-        stop: () => Promise.resolve(),
-      },
-    });
-
-    await startJobWorkers();
-    await startJobWorkers();
-
-    expect(start).toHaveBeenCalledTimes(1);
-    expect(start.mock.calls[0]?.[0]).toHaveLength(1);
-  });
-
-  it("refuses to start with no driver configured", async () => {
-    await expect(startJobWorkers()).rejects.toThrow("no driver configured");
-  });
-});
-
-function silentLogger() {
-  return { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-}

package/src/drivers/__tests__/concurrency.test.ts

@@ -1,42 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import type { AnyJobDefinition } from "../../core/types";
-import { __testables } from "../bullmq";
-
-/**
- * The queue-concurrency rule. Pinned on its own because getting it wrong is
- * SILENT: a job that asked for single-flight would simply run concurrently,
- * and nothing would fail — the sweeps would just start racing each other again.
- */
-const { resolveConcurrency, DEFAULT_CONCURRENCY } = __testables;
-
-function job(overrides: Partial<AnyJobDefinition> = {}): AnyJobDefinition {
-  return { name: "a.job", handle: () => Promise.resolve(), ...overrides };
-}
-
-describe("resolveConcurrency", () => {
-  it("falls back to the default when no job on the queue states one", () => {
-    expect(resolveConcurrency([job(), job({ name: "b.job" })])).toBe(DEFAULT_CONCURRENCY);
-  });
-
-  it("honours a stated 1 instead of raising it to the default", () => {
-    // The regression this exists for: `Math.max(DEFAULT, ...)` silently turns
-    // single-flight back into the default and undoes the guarantee.
-    expect(resolveConcurrency([job({ concurrency: 1 })])).toBe(1);
-  });
-
-  it("takes the highest STATED value when several are given", () => {
-    expect(
-      resolveConcurrency([job({ concurrency: 1 }), job({ name: "b.job", concurrency: 4 })]),
-    ).toBe(4);
-  });
-
-  it("ignores a stated value alongside unstated ones rather than averaging in the default", () => {
-    expect(resolveConcurrency([job({ concurrency: 2 }), job({ name: "b.job" })])).toBe(2);
-  });
-
-  it("ignores a nonsensical value", () => {
-    expect(resolveConcurrency([job({ concurrency: 0 })])).toBe(DEFAULT_CONCURRENCY);
-    expect(resolveConcurrency([job({ concurrency: -3 })])).toBe(DEFAULT_CONCURRENCY);
-  });
-});

package/src/drivers/__tests__/inline.test.ts

@@ -1,79 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import type { AnyJobDefinition } from "../../core/types";
-import { createInlineJobDriver } from "../inline";
-
-function silentLogger() {
-  return { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-}
-
-function definition(overrides: Partial<AnyJobDefinition> = {}): AnyJobDefinition {
-  return { name: "a.job", handle: () => Promise.resolve(), ...overrides };
-}
-
-describe("inline driver", () => {
-  it("awaits the handler so a test sees the side effect", async () => {
-    const seen: string[] = [];
-    const driver = createInlineJobDriver({ logger: silentLogger() });
-
-    await driver.enqueue(
-      definition({ handle: (payload) => {
-        seen.push(payload as string);
-        return Promise.resolve();
-      } }),
-      "one",
-      {},
-    );
-
-    expect(seen).toEqual(["one"]);
-  });
-
-  it("retries up to `attempts` and records the run", async () => {
-    const handle = vi
-      .fn()
-      .mockRejectedValueOnce(new Error("transient"))
-      .mockResolvedValueOnce(undefined);
-    const driver = createInlineJobDriver({ logger: silentLogger() });
-
-    await driver.enqueue(definition({ attempts: 3, handle }), undefined, {});
-
-    expect(handle).toHaveBeenCalledTimes(2);
-    expect(driver.runs).toEqual([
-      { name: "a.job", payload: undefined, attempts: 2, error: undefined },
-    ]);
-  });
-
-  it("swallows a handler that fails every attempt, logging it once", async () => {
-    const logger = silentLogger();
-    const handle = vi.fn().mockRejectedValue(new Error("permanent"));
-    const driver = createInlineJobDriver({ logger });
-
-    await expect(
-      driver.enqueue(definition({ attempts: 2, handle }), undefined, {}),
-    ).resolves.toEqual({ enqueued: true });
-
-    expect(handle).toHaveBeenCalledTimes(2);
-    expect(logger.error).toHaveBeenCalledTimes(1);
-    expect(driver.runs[0]?.error).toBeInstanceOf(Error);
-  });
-
-  it("warns that a delay is ignored instead of silently dropping it", async () => {
-    const logger = silentLogger();
-    const driver = createInlineJobDriver({ logger });
-
-    await driver.enqueue(definition(), undefined, { delayMs: 3_000 });
-
-    expect(logger.warn).toHaveBeenCalledWith(
-      expect.stringContaining("ignored a 3000ms delay"),
-    );
-  });
-
-  it("warns that registered schedules will never fire", async () => {
-    const logger = silentLogger();
-    const driver = createInlineJobDriver({ logger });
-
-    await driver.start([definition({ schedule: { pattern: "0 * * * *" } })]);
-
-    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("a.job"));
-  });
-});

package/src/drivers/__tests__/redis-url.test.ts

@@ -1,57 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { InvalidRedisUrlError, parseRedisUrl } from "../redis-url";
-
-describe("parseRedisUrl", () => {
-  it("defaults host, port and database", () => {
-    expect(parseRedisUrl("redis://localhost")).toEqual({
-      host: "localhost",
-      port: 6379,
-      username: undefined,
-      password: undefined,
-      db: undefined,
-      tls: undefined,
-      maxRetriesPerRequest: null,
-      enableReadyCheck: false,
-    });
-  });
-
-  it("reads credentials, port and database from the URL", () => {
-    const parsed = parseRedisUrl("redis://user:p%40ss@redis:6380/3");
-
-    expect(parsed).toMatchObject({
-      host: "redis",
-      port: 6380,
-      username: "user",
-      password: "p@ss",
-      db: 3,
-    });
-  });
-
-  it("enables TLS for rediss://", () => {
-    expect(parseRedisUrl("rediss://redis:6379").tls).toEqual({});
-  });
-
-  it("always pins the two options BullMQ requires", () => {
-    const parsed = parseRedisUrl("redis://redis:6379/1");
-
-    expect(parsed.maxRetriesPerRequest).toBeNull();
-    expect(parsed.enableReadyCheck).toBe(false);
-  });
-
-  it("rejects a non-Redis protocol", () => {
-    expect(() => parseRedisUrl("http://redis:6379")).toThrow(InvalidRedisUrlError);
-  });
-
-  it("rejects a malformed URL", () => {
-    expect(() => parseRedisUrl("not a url")).toThrow(InvalidRedisUrlError);
-  });
-
-  it("never puts the URL (which can carry a password) in the error message", () => {
-    expect(() => parseRedisUrl("http://user:hunter2@redis:6379")).toThrow(
-      expect.objectContaining({
-        message: expect.not.stringContaining("hunter2") as unknown as string,
-      }),
-    );
-  });
-});