@bash-app/bash-common 30.246.0 → 30.253.0

package/src/utils/__tests__/discountEngine/discountCalculator.test.ts

@@ -0,0 +1,410 @@
+import {
+  OfferDiscountType,
+  SpecialOffer,
+  SpecialOfferType,
+} from "@prisma/client";
+import { describe, expect, test } from "@jest/globals";
+import {
+  calculatePromoCodeDiscount,
+  calculateSpecialOfferDiscount,
+  calculateBOGODiscount,
+  calculateGroupDiscount,
+  calculateVolumeDiscount,
+  calculateEarlyBirdDiscount,
+  calculateBundleDiscount,
+  formatDiscountDescription,
+  type BashEventPromoCodeWithPromoter,
+} from "../../discountEngine/discountCalculator.js";
+
+const NOW = new Date("2026-01-01T00:00:00Z");
+
+function basePromoCode(
+  overrides: Partial<BashEventPromoCodeWithPromoter> &
+    Pick<BashEventPromoCodeWithPromoter, "id" | "code">
+): BashEventPromoCodeWithPromoter {
+  return {
+    ticketTierId: "tier-1",
+    discountAmountInCents: null,
+    discountAmountPercentage: null,
+    maxRedemptions: null,
+    redeemBy: null,
+    promoterId: null,
+    stripeCouponId: null,
+    meta: null,
+    bashPointsRewardPerTicket: null,
+    ...overrides,
+  };
+}
+
+function baseSpecialOffer(
+  overrides: Partial<SpecialOffer> & Pick<SpecialOffer, "id" | "title" | "offerType">
+): SpecialOffer {
+  return {
+    createdAt: NOW,
+    updatedAt: NOW,
+    ticketTierId: "tier-1",
+    description: null,
+    discountType: OfferDiscountType.PERCENTAGE,
+    discountValue: 10,
+    isActive: true,
+    displayBadge: true,
+    badgeText: null,
+    buyQuantity: null,
+    getQuantity: null,
+    getDiscountPercent: null,
+    minGroupSize: null,
+    maxGroupSize: null,
+    tieredDiscounts: null,
+    startDate: null,
+    endDate: null,
+    availableUntil: null,
+    maxRedemptions: null,
+    maxPerUser: null,
+    limitedQuantity: null,
+    currentRedemptions: 0,
+    viewCount: 0,
+    clickCount: 0,
+    lastRedemptionAt: null,
+    priceIncreasesAt: null,
+    newPriceAfterIncrease: null,
+    countdownEnabled: false,
+    bundledItems: null,
+    bundleSavings: null,
+    requiresAttribution: false,
+    referralDiscountForBuyer: null,
+    referralDiscountForFriend: null,
+    commissionRate: null,
+    requiresEventAttendance: null,
+    hostSpecificLoyalty: false,
+    canStackWithPromoCodes: true,
+    canStackWithOtherOffers: false,
+    priority: 0,
+    urgencyMessage: null,
+    showSocialProof: false,
+    highlightColor: null,
+    sortOrder: 0,
+    minPriceFloor: null,
+    maxDiscountPercent: null,
+    ...overrides,
+  };
+}
+
+describe("calculatePromoCodeDiscount", () => {
+  test("applies percentage discount", () => {
+    const promo = basePromoCode({
+      id: "promo-1",
+      code: "SAVE20",
+      discountAmountPercentage: 20,
+    });
+    const result = calculatePromoCodeDiscount(promo, 5000, 2);
+    expect(result).toMatchObject({
+      sourceType: "PROMO_CODE",
+      discountType: "PERCENTAGE",
+      discountValue: 20,
+      originalPrice: 10000,
+      amountDiscounted: 2000,
+      finalPrice: 8000,
+    });
+  });
+
+  test("applies fixed amount discount capped at order total", () => {
+    const promo = basePromoCode({
+      id: "promo-2",
+      code: "FLAT10",
+      discountAmountInCents: 1500,
+    });
+    const result = calculatePromoCodeDiscount(promo, 1000, 1);
+    expect(result.amountDiscounted).toBe(1000);
+    expect(result.finalPrice).toBe(0);
+  });
+
+  test("includes attribution when promoter has userId", () => {
+    const promo = basePromoCode({
+      id: "promo-3",
+      code: "PROMO",
+      discountAmountPercentage: 10,
+      promoterId: "promoter-row-1",
+      promoter: { userId: "user-abc" },
+    });
+    const result = calculatePromoCodeDiscount(promo, 5000, 1);
+    expect(result.attribution).toEqual({
+      userId: "user-abc",
+      commissionRate: 5.0,
+      commissionAmount: 25,
+    });
+  });
+
+  test("omits attribution when promoter userId is missing", () => {
+    const promo = basePromoCode({
+      id: "promo-4",
+      code: "PROMO",
+      discountAmountPercentage: 10,
+      promoterId: "promoter-row-1",
+      promoter: { userId: null },
+    });
+    expect(calculatePromoCodeDiscount(promo, 5000, 1).attribution).toBeUndefined();
+  });
+});
+
+describe("calculateBOGODiscount", () => {
+  test("buy 2 get 1 free (100% off)", () => {
+    const offer = baseSpecialOffer({
+      id: "bogo-1",
+      title: "BOGO",
+      offerType: SpecialOfferType.BOGO,
+      buyQuantity: 2,
+      getQuantity: 1,
+      getDiscountPercent: 100,
+    });
+    // 3 tickets → 1 set → 1 free ticket at $50
+    expect(calculateBOGODiscount(offer, 3, 5000)).toBe(5000);
+    expect(calculateBOGODiscount(offer, 2, 5000)).toBe(0);
+  });
+
+  test("partial discount on free tickets", () => {
+    const offer = baseSpecialOffer({
+      id: "bogo-2",
+      title: "Half off extra",
+      offerType: SpecialOfferType.BOGO,
+      buyQuantity: 1,
+      getQuantity: 1,
+      getDiscountPercent: 50,
+    });
+    expect(calculateBOGODiscount(offer, 2, 4000)).toBe(2000);
+  });
+});
+
+describe("calculateGroupDiscount", () => {
+  test("returns 0 when below min group size", () => {
+    const offer = baseSpecialOffer({
+      id: "group-1",
+      title: "Group",
+      offerType: SpecialOfferType.GROUP_DISCOUNT,
+      minGroupSize: 5,
+      discountValue: 20,
+    });
+    expect(calculateGroupDiscount(offer, 3, 5000)).toBe(0);
+  });
+
+  test("returns 0 when above max group size", () => {
+    const offer = baseSpecialOffer({
+      id: "group-2",
+      title: "Group",
+      offerType: SpecialOfferType.GROUP_DISCOUNT,
+      maxGroupSize: 10,
+      discountValue: 20,
+    });
+    expect(calculateGroupDiscount(offer, 11, 5000)).toBe(0);
+  });
+
+  test("uses highest applicable tiered discount", () => {
+    const offer = baseSpecialOffer({
+      id: "group-3",
+      title: "Tiered",
+      offerType: SpecialOfferType.GROUP_DISCOUNT,
+      tieredDiscounts: [
+        { qty: 5, discount: 10 },
+        { qty: 10, discount: 20 },
+      ],
+    });
+    expect(calculateGroupDiscount(offer, 10, 5000)).toBe(10000);
+    expect(calculateGroupDiscount(offer, 5, 5000)).toBe(2500);
+  });
+
+  test("falls back to percentage discount", () => {
+    const offer = baseSpecialOffer({
+      id: "group-4",
+      title: "Simple group",
+      offerType: SpecialOfferType.GROUP_DISCOUNT,
+      discountType: OfferDiscountType.PERCENTAGE,
+      discountValue: 15,
+    });
+    expect(calculateGroupDiscount(offer, 4, 5000)).toBe(3000);
+  });
+
+  test("falls back to fixed amount per ticket", () => {
+    const offer = baseSpecialOffer({
+      id: "group-5",
+      title: "Fixed group",
+      offerType: SpecialOfferType.GROUP_DISCOUNT,
+      discountType: OfferDiscountType.FIXED_AMOUNT,
+      discountValue: 500,
+    });
+    expect(calculateGroupDiscount(offer, 3, 5000)).toBe(1500);
+  });
+});
+
+describe("calculateVolumeDiscount", () => {
+  test("delegates to group discount logic", () => {
+    const offer = baseSpecialOffer({
+      id: "vol-1",
+      title: "Volume",
+      offerType: SpecialOfferType.VOLUME_DISCOUNT,
+      discountType: OfferDiscountType.PERCENTAGE,
+      discountValue: 10,
+    });
+    expect(calculateVolumeDiscount(offer, 2, 5000)).toBe(
+      calculateGroupDiscount(offer, 2, 5000)
+    );
+  });
+});
+
+describe("calculateEarlyBirdDiscount", () => {
+  test("returns 0 after availableUntil", () => {
+    const offer = baseSpecialOffer({
+      id: "eb-1",
+      title: "Early bird",
+      offerType: SpecialOfferType.EARLY_BIRD,
+      availableUntil: new Date("2026-01-01T00:00:00Z"),
+      discountValue: 20,
+    });
+    expect(
+      calculateEarlyBirdDiscount(offer, 5000, new Date("2026-02-01T00:00:00Z"))
+    ).toBe(0);
+  });
+
+  test("applies percentage before cutoff", () => {
+    const offer = baseSpecialOffer({
+      id: "eb-2",
+      title: "Early bird",
+      offerType: SpecialOfferType.EARLY_BIRD,
+      availableUntil: new Date("2026-06-01T00:00:00Z"),
+      discountType: OfferDiscountType.PERCENTAGE,
+      discountValue: 20,
+    });
+    expect(
+      calculateEarlyBirdDiscount(offer, 5000, new Date("2026-03-01T00:00:00Z"))
+    ).toBe(1000);
+  });
+
+  test("applies fixed amount capped at ticket price", () => {
+    const offer = baseSpecialOffer({
+      id: "eb-3",
+      title: "Early bird flat",
+      offerType: SpecialOfferType.EARLY_BIRD,
+      discountType: OfferDiscountType.FIXED_AMOUNT,
+      discountValue: 8000,
+    });
+    expect(
+      calculateEarlyBirdDiscount(offer, 5000, new Date("2026-03-01T00:00:00Z"))
+    ).toBe(5000);
+  });
+});
+
+describe("calculateBundleDiscount", () => {
+  test("returns bundleSavings from offer", () => {
+    const offer = baseSpecialOffer({
+      id: "bundle-1",
+      title: "Bundle",
+      offerType: SpecialOfferType.BUNDLE,
+      bundleSavings: 2500,
+    });
+    expect(
+      calculateBundleDiscount(offer, [{ type: "ticket", price: 5000 }])
+    ).toBe(2500);
+  });
+
+  test("returns 0 when bundleSavings is null", () => {
+    const offer = baseSpecialOffer({
+      id: "bundle-2",
+      title: "Bundle",
+      offerType: SpecialOfferType.BUNDLE,
+      bundleSavings: null,
+    });
+    expect(calculateBundleDiscount(offer, [])).toBe(0);
+  });
+});
+
+describe("calculateSpecialOfferDiscount", () => {
+  test("EARLY_BIRD percentage via switch", () => {
+    const offer = baseSpecialOffer({
+      id: "so-1",
+      title: "Early Bird",
+      offerType: SpecialOfferType.EARLY_BIRD,
+      discountType: OfferDiscountType.PERCENTAGE,
+      discountValue: 25,
+    });
+    const result = calculateSpecialOfferDiscount(offer, 4000, 2);
+    expect(result).toMatchObject({
+      sourceType: "SPECIAL_OFFER",
+      discountType: "PERCENTAGE",
+      amountDiscounted: 2000,
+      originalPrice: 8000,
+      finalPrice: 6000,
+    });
+  });
+
+  test("BUNDLE uses pre-calculated savings", () => {
+    const offer = baseSpecialOffer({
+      id: "so-2",
+      title: "Bundle Deal",
+      offerType: SpecialOfferType.BUNDLE,
+      bundleSavings: 1000,
+    });
+    const result = calculateSpecialOfferDiscount(offer, 5000, 1);
+    expect(result.discountType).toBe("FIXED_AMOUNT");
+    expect(result.amountDiscounted).toBe(1000);
+  });
+
+  test("REFERRAL uses buyer discount", () => {
+    const offer = baseSpecialOffer({
+      id: "so-3",
+      title: "Referral",
+      offerType: SpecialOfferType.REFERRAL,
+      referralDiscountForBuyer: 500,
+      requiresAttribution: true,
+      commissionRate: 10,
+    });
+    const result = calculateSpecialOfferDiscount(offer, 5000, 1, "referrer-user");
+    expect(result.amountDiscounted).toBe(500);
+    expect(result.attribution).toEqual({
+      userId: "referrer-user",
+      commissionRate: 10,
+      commissionAmount: 50,
+    });
+  });
+
+  test("BOGO sets FREE_ITEMS discount type", () => {
+    const offer = baseSpecialOffer({
+      id: "so-4",
+      title: "BOGO",
+      offerType: SpecialOfferType.BOGO,
+      buyQuantity: 1,
+      getQuantity: 1,
+      getDiscountPercent: 100,
+    });
+    const result = calculateSpecialOfferDiscount(offer, 5000, 2);
+    expect(result.discountType).toBe("FREE_ITEMS");
+    expect(result.amountDiscounted).toBe(5000);
+  });
+});
+
+describe("formatDiscountDescription", () => {
+  test("formats percentage discount", () => {
+    const text = formatDiscountDescription({
+      sourceType: "PROMO_CODE",
+      sourceId: "1",
+      sourceName: "SAVE20",
+      discountType: "PERCENTAGE",
+      discountValue: 20,
+      amountDiscounted: 2000,
+      originalPrice: 10000,
+      finalPrice: 8000,
+    });
+    expect(text).toBe("SAVE20: -20% ($20.00)");
+  });
+
+  test("formats fixed amount discount", () => {
+    const text = formatDiscountDescription({
+      sourceType: "SPECIAL_OFFER",
+      sourceId: "2",
+      sourceName: "Flat Off",
+      discountType: "FIXED_AMOUNT",
+      discountValue: 500,
+      amountDiscounted: 500,
+      originalPrice: 5000,
+      finalPrice: 4500,
+    });
+    expect(text).toBe("Flat Off: -$5.00");
+  });
+});

package/src/utils/__tests__/generalDateTimeUtils.test.ts

@@ -0,0 +1,34 @@
+import { DayOfWeek } from "@prisma/client";
+import { describe, expect, test } from "@jest/globals";
+import {
+  dayOfWeekIdxToDay,
+  dayOfWeekIdxToDayOfWeek,
+  dayOfWeekToIdx,
+  dayOfWeekToString,
+} from "../generalDateTimeUtils.js";
+
+describe("generalDateTimeUtils", () => {
+  test("dayOfWeekToString maps each weekday to a short label", () => {
+    expect(dayOfWeekToString[DayOfWeek.Monday]).toBe("M");
+    expect(dayOfWeekToString[DayOfWeek.Thursday]).toBe("TR");
+    expect(dayOfWeekToString[DayOfWeek.Saturday]).toBe("S");
+  });
+
+  test("dayOfWeekToIdx assigns Monday=1 through Sunday=7", () => {
+    expect(dayOfWeekToIdx[DayOfWeek.Monday]).toBe(1);
+    expect(dayOfWeekToIdx[DayOfWeek.Sunday]).toBe(7);
+  });
+
+  test("dayOfWeekIdxToDayOfWeek round-trips with dayOfWeekToIdx", () => {
+    for (const day of Object.values(DayOfWeek)) {
+      const idx = dayOfWeekToIdx[day];
+      expect(dayOfWeekIdxToDayOfWeek[idx]).toBe(day);
+    }
+  });
+
+  test("dayOfWeekIdxToDay rotates Sunday to index 1", () => {
+    expect(dayOfWeekIdxToDay[7]).toBe(1);
+    expect(dayOfWeekIdxToDay[1]).toBe(2);
+    expect(dayOfWeekIdxToDay[6]).toBe(7);
+  });
+});

package/src/utils/__tests__/luxonUtils.test.ts

@@ -0,0 +1,171 @@
+import { DayOfWeek } from "@prisma/client";
+import { DateTime } from "luxon";
+import { describe, expect, test } from "@jest/globals";
+import {
+  dateRangeDurationMatch,
+  dateTimeDiffHours,
+  dateTimeFormat,
+  dateTimeFormatDateRange,
+  dateTimeFromDate,
+  dateTimeFromDayTime,
+  dateTimeRangeCrossesMidnight,
+  dateTimeToTimeComponents,
+  dateTimeWithinRange,
+  dayOfWeekFromIdx,
+  dayOfWeekGetIdx,
+  filterConflictingIntervals,
+  luxonDateRangeSort,
+  mergeCrossDayHours,
+  utcOffsetMinutesToTimezone,
+} from "../luxonUtils.js";
+
+describe("luxonUtils", () => {
+  describe("day of week helpers", () => {
+    test("dayOfWeekGetIdx accepts enum and numeric index", () => {
+      expect(dayOfWeekGetIdx(DayOfWeek.Wednesday)).toBe(3);
+      expect(dayOfWeekGetIdx(5)).toBe(5);
+    });
+
+    test("dayOfWeekFromIdx accepts index and enum passthrough", () => {
+      expect(dayOfWeekFromIdx(4)).toBe(DayOfWeek.Thursday);
+      expect(dayOfWeekFromIdx(DayOfWeek.Friday)).toBe(DayOfWeek.Friday);
+    });
+
+    test("dateTimeFromDayTime builds weekday time in zone", () => {
+      const dt = dateTimeFromDayTime(DayOfWeek.Monday, 14, 30, "UTC");
+      expect(dt.weekday).toBe(1);
+      expect(dt.hour).toBe(14);
+      expect(dt.minute).toBe(30);
+    });
+  });
+
+  describe("dateTimeFromDate and formatting", () => {
+    test("dateTimeFromDate parses ISO string", () => {
+      const dt = dateTimeFromDate("2024-03-15T18:00:00.000Z", "UTC");
+      expect(dt.year).toBe(2024);
+      expect(dt.month).toBe(3);
+      expect(dt.day).toBe(15);
+    });
+
+    test("dateTimeToTimeComponents extracts hour and minute", () => {
+      const dt = DateTime.fromObject({ hour: 9, minute: 15 }, { zone: "UTC" });
+      expect(dateTimeToTimeComponents(dt)).toEqual({ hour: 9, minute: 15 });
+    });
+
+    test("dateTimeFormat returns empty string for nullish", () => {
+      expect(dateTimeFormat(null)).toBe("");
+      expect(dateTimeFormat(undefined)).toBe("");
+    });
+  });
+
+  describe("range helpers", () => {
+    const start = DateTime.fromISO("2024-01-01T10:00:00", { zone: "UTC" });
+    const end = DateTime.fromISO("2024-01-01T18:00:00", { zone: "UTC" });
+    const range = { start, end };
+
+    test("dateTimeWithinRange detects containment", () => {
+      const inside = DateTime.fromISO("2024-01-01T12:00:00", { zone: "UTC" });
+      const outside = DateTime.fromISO("2024-01-01T19:00:00", { zone: "UTC" });
+      expect(dateTimeWithinRange(inside, range)).toBe(true);
+      expect(dateTimeWithinRange(outside, range)).toBe(false);
+    });
+
+    test("dateRangeDurationMatch compares durations within tolerance", () => {
+      const lhs = {
+        start: DateTime.fromISO("2024-01-01T10:00:00", { zone: "UTC" }),
+        end: DateTime.fromISO("2024-01-01T12:00:00", { zone: "UTC" }),
+      };
+      const rhs = {
+        start: DateTime.fromISO("2024-02-01T10:00:00", { zone: "UTC" }),
+        end: DateTime.fromISO("2024-02-01T12:00:30", { zone: "UTC" }),
+      };
+      expect(dateRangeDurationMatch(lhs, rhs, 60)).toBe(true);
+    });
+
+    test("dateTimeFormatDateRange uses time-only end on same day", () => {
+      const sameDayStart = DateTime.fromISO("2024-06-01T18:00:00", { zone: "UTC" });
+      const sameDayEnd = DateTime.fromISO("2024-06-01T22:00:00", { zone: "UTC" });
+      const formatted = dateTimeFormatDateRange(sameDayStart, sameDayEnd);
+      expect(formatted).toContain(" to ");
+      expect(formatted.split(" to ")[1]).toMatch(/\d/);
+    });
+
+    test("dateTimeRangeCrossesMidnight detects overnight ranges", () => {
+      const overnight = {
+        start: DateTime.fromObject({ hour: 22, minute: 0 }, { zone: "UTC" }),
+        end: DateTime.fromObject({ hour: 2, minute: 0 }, { zone: "UTC" }),
+      };
+      const sameDay = {
+        start: DateTime.fromObject({ hour: 9, minute: 0 }, { zone: "UTC" }),
+        end: DateTime.fromObject({ hour: 17, minute: 0 }, { zone: "UTC" }),
+      };
+      expect(dateTimeRangeCrossesMidnight(overnight)).toBe(true);
+      expect(dateTimeRangeCrossesMidnight(sameDay)).toBe(false);
+    });
+  });
+
+  describe("mergeCrossDayHours", () => {
+    test("merges ranges separated by one minute or less", () => {
+      const base = DateTime.fromObject({ hour: 9 }, { zone: "UTC" });
+      const merged = mergeCrossDayHours([
+        { start: base, end: base.plus({ hours: 2 }) },
+        { start: base.plus({ hours: 2, minutes: 1 }), end: base.plus({ hours: 4 }) },
+      ]);
+      expect(merged).toHaveLength(1);
+      expect(merged[0].end.hour).toBe(13);
+    });
+
+    test("keeps separate ranges when gap exceeds one minute", () => {
+      const base = DateTime.fromObject({ hour: 9 }, { zone: "UTC" });
+      const merged = mergeCrossDayHours([
+        { start: base, end: base.plus({ hours: 1 }) },
+        { start: base.plus({ hours: 2 }), end: base.plus({ hours: 3 }) },
+      ]);
+      expect(merged).toHaveLength(2);
+    });
+  });
+
+  describe("filterConflictingIntervals", () => {
+    test("subtracts blocked hours from available hours", () => {
+      const day = DateTime.fromObject({ hour: 8 }, { zone: "UTC" });
+      const available = [{ start: day, end: day.plus({ hours: 8 }) }];
+      const blocked = [
+        {
+          start: day.plus({ hours: 2 }),
+          end: day.plus({ hours: 3 }),
+        },
+      ];
+      const remaining = filterConflictingIntervals(available, blocked);
+      expect(remaining.length).toBeGreaterThan(0);
+      expect(remaining.every((r) => r.end > r.start)).toBe(true);
+    });
+  });
+
+  describe("utcOffsetMinutesToTimezone", () => {
+    test("formats positive and negative offsets", () => {
+      expect(utcOffsetMinutesToTimezone(300)).toBe("UTC+05:00");
+      expect(utcOffsetMinutesToTimezone(-480)).toBe("UTC-08:00");
+    });
+  });
+
+  describe("dateTimeDiffHours", () => {
+    test("returns 0 when start or end missing", () => {
+      expect(dateTimeDiffHours(null, DateTime.now())).toBe(0);
+      expect(dateTimeDiffHours(DateTime.now(), null)).toBe(0);
+    });
+  });
+
+  describe("luxonDateRangeSort", () => {
+    test("sorts ranges by start time ascending", () => {
+      const later = {
+        start: DateTime.fromISO("2024-01-02T10:00:00", { zone: "UTC" }),
+        end: DateTime.fromISO("2024-01-02T12:00:00", { zone: "UTC" }),
+      };
+      const earlier = {
+        start: DateTime.fromISO("2024-01-01T10:00:00", { zone: "UTC" }),
+        end: DateTime.fromISO("2024-01-01T12:00:00", { zone: "UTC" }),
+      };
+      expect(luxonDateRangeSort([later, earlier])).toEqual([earlier, later]);
+    });
+  });
+});

package/src/utils/__tests__/mathUtils.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Tests for numeric rounding helpers.
+ */
+
+import { describe, expect, test } from "@jest/globals";
+import { roundToNearestDivisor } from "../mathUtils.js";
+
+describe("mathUtils", () => {
+  describe("roundToNearestDivisor", () => {
+    test("rounds to nearest cent (divisor 100)", () => {
+      expect(roundToNearestDivisor(12.345, 100)).toBe(12.35);
+      expect(roundToNearestDivisor(12.344, 100)).toBe(12.34);
+    });
+
+    test("rounds to nearest tenth (divisor 10)", () => {
+      expect(roundToNearestDivisor(3.14, 10)).toBe(3.1);
+      expect(roundToNearestDivisor(3.16, 10)).toBe(3.2);
+    });
+
+    test("returns whole numbers unchanged when divisor is 1", () => {
+      expect(roundToNearestDivisor(42, 1)).toBe(42);
+      expect(roundToNearestDivisor(42.6, 1)).toBe(43);
+    });
+
+    test("handles zero and negative values", () => {
+      expect(roundToNearestDivisor(0, 100)).toBe(0);
+      expect(roundToNearestDivisor(-1.235, 100)).toBe(-1.24);
+    });
+  });
+});

package/src/utils/__tests__/objUtils.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Tests for object type guards and deep merge.
+ */
+
+import { describe, expect, test } from "@jest/globals";
+import { isObject, deepMerge } from "../objUtils.js";
+
+describe("objUtils", () => {
+  describe("isObject", () => {
+    test("returns true for plain objects", () => {
+      expect(isObject({ a: 1 })).toBe(true);
+      expect(isObject(Object.create(null))).toBe(true);
+    });
+
+    test("returns false for null, arrays, dates, and primitives", () => {
+      expect(isObject(null)).toBe(false);
+      expect(isObject([1, 2])).toBe(false);
+      expect(isObject(new Date())).toBe(false);
+      expect(isObject("string")).toBe(false);
+      expect(isObject(42)).toBe(false);
+    });
+  });
+
+  describe("deepMerge", () => {
+    test("overwrites scalar values from source", () => {
+      expect(deepMerge({ a: 1, b: 2 }, { b: 99 })).toEqual({ a: 1, b: 99 });
+    });
+
+    test("recursively merges nested objects", () => {
+      expect(deepMerge({ nested: { x: 1, y: 2 } }, { nested: { y: 3, z: 4 } })).toEqual({
+        nested: { x: 1, y: 3, z: 4 },
+      });
+    });
+
+    test("concatenates arrays when mergeArrays is true", () => {
+      expect(deepMerge({ tags: ["a"] }, { tags: ["b"] }, true)).toEqual({ tags: ["a", "b"] });
+    });
+
+    test("replaces arrays by default", () => {
+      expect(deepMerge({ tags: ["a"] }, { tags: ["b"] })).toEqual({ tags: ["b"] });
+    });
+
+    test("handles null/undefined target or source", () => {
+      expect(deepMerge(null, { a: 1 })).toEqual({ a: 1 });
+      expect(deepMerge({ a: 1 }, null)).toEqual({ a: 1 });
+    });
+  });
+});