@schafevormfenster/rest-commons 0.1.1

package/src/time/time-schemas.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "vitest";
+
+import { RelativeTimeSchema, FlexibleTimeSchema } from "./time-schemas";
+
+describe("time-schemas", () => {
+  describe("RelativeTimeSchema", () => {
+    describe("valid formats", () => {
+      it("should validate correct relative time formats", () => {
+        expect(() => RelativeTimeSchema.parse("1s")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("30m")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("24h")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("7d")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("2w")).not.toThrow();
+      });
+
+      it("should accept 'now' literal", () => {
+        expect(() => RelativeTimeSchema.parse("now")).not.toThrow();
+      });
+
+      it("should accept 'today' literal", () => {
+        expect(() => RelativeTimeSchema.parse("today")).not.toThrow();
+      });
+
+      it("should accept various numeric amounts", () => {
+        expect(() => RelativeTimeSchema.parse("1s")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("999s")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("100d")).not.toThrow();
+      });
+
+      it("should accept negative relative times", () => {
+        expect(() => RelativeTimeSchema.parse("-1s")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("-30m")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("-24h")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("-7d")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("-2w")).not.toThrow();
+      });
+
+      it("should accept week notation without offset", () => {
+        expect(() => RelativeTimeSchema.parse("week-start")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("week-end")).not.toThrow();
+      });
+
+      it("should accept week notation with positive offset", () => {
+        expect(() => RelativeTimeSchema.parse("week-start+1w")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("week-start+2w")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("week-end+1w")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("week-end+10w")).not.toThrow();
+      });
+
+      it("should accept week notation with negative offset", () => {
+        expect(() => RelativeTimeSchema.parse("week-start-1w")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("week-start-2w")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("week-end-1w")).not.toThrow();
+        expect(() => RelativeTimeSchema.parse("week-end-10w")).not.toThrow();
+      });
+    });
+
+    describe("invalid formats", () => {
+      it("should reject formats without numbers", () => {
+        expect(() => RelativeTimeSchema.parse("m")).toThrow();
+        expect(() => RelativeTimeSchema.parse("h")).toThrow();
+        expect(() => RelativeTimeSchema.parse("d")).toThrow();
+      });
+
+      it("should reject formats without units", () => {
+        expect(() => RelativeTimeSchema.parse("1")).toThrow();
+        expect(() => RelativeTimeSchema.parse("123")).toThrow();
+      });
+
+      it("should reject invalid units", () => {
+        expect(() => RelativeTimeSchema.parse("1x")).toThrow();
+        expect(() => RelativeTimeSchema.parse("1y")).toThrow();
+        expect(() => RelativeTimeSchema.parse("1month")).toThrow();
+      });
+
+      it("should reject decimal amounts", () => {
+        expect(() => RelativeTimeSchema.parse("1.5h")).toThrow();
+        expect(() => RelativeTimeSchema.parse("0.5d")).toThrow();
+        expect(() => RelativeTimeSchema.parse("-1.5h")).toThrow();
+        expect(() => RelativeTimeSchema.parse("-0.5d")).toThrow();
+      });
+
+      it("should be case-sensitive for literals", () => {
+        expect(() => RelativeTimeSchema.parse("Now")).toThrow();
+        expect(() => RelativeTimeSchema.parse("NOW")).toThrow();
+        expect(() => RelativeTimeSchema.parse("Today")).toThrow();
+        expect(() => RelativeTimeSchema.parse("TODAY")).toThrow();
+      });
+
+      it("should reject empty strings", () => {
+        expect(() => RelativeTimeSchema.parse("")).toThrow();
+      });
+
+      it("should reject whitespace", () => {
+        expect(() => RelativeTimeSchema.parse(" ")).toThrow();
+        expect(() => RelativeTimeSchema.parse("1 h")).toThrow();
+        expect(() => RelativeTimeSchema.parse(" 1h")).toThrow();
+        expect(() => RelativeTimeSchema.parse("1h ")).toThrow();
+      });
+
+      it("should reject invalid week notation formats", () => {
+        expect(() => RelativeTimeSchema.parse("week-middle")).toThrow();
+        expect(() => RelativeTimeSchema.parse("week-begin")).toThrow();
+        expect(() => RelativeTimeSchema.parse("weekstart")).toThrow();
+        expect(() => RelativeTimeSchema.parse("week-start+1d")).toThrow();
+        expect(() => RelativeTimeSchema.parse("week-end+2h")).toThrow();
+        expect(() => RelativeTimeSchema.parse("week-start1w")).toThrow();
+        expect(() => RelativeTimeSchema.parse("week-start+")).toThrow();
+        expect(() => RelativeTimeSchema.parse("week-end-")).toThrow();
+      });
+    });
+  });
+
+  describe("FlexibleTimeSchema", () => {
+    describe("ISO 8601 dates", () => {
+      it("should accept valid ISO 8601 dates", () => {
+        expect(() =>
+          FlexibleTimeSchema.parse("2024-01-01T00:00:00.000Z")
+        ).not.toThrow();
+        expect(() =>
+          FlexibleTimeSchema.parse("2024-01-01T12:30:45Z")
+        ).not.toThrow();
+        expect(() =>
+          FlexibleTimeSchema.parse("2024-12-31T23:59:59.999Z")
+        ).not.toThrow();
+      });
+
+      it("should accept ISO 8601 with timezone offsets", () => {
+        expect(() =>
+          FlexibleTimeSchema.parse("2024-01-01T12:00:00+01:00")
+        ).not.toThrow();
+        expect(() =>
+          FlexibleTimeSchema.parse("2024-01-01T12:00:00-05:00")
+        ).not.toThrow();
+      });
+    });
+
+    describe("relative time formats", () => {
+      it("should accept relative time formats", () => {
+        expect(() => FlexibleTimeSchema.parse("1h")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("30m")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("7d")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("2w")).not.toThrow();
+      });
+
+      it("should accept negative relative time formats", () => {
+        expect(() => FlexibleTimeSchema.parse("-1h")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("-30m")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("-7d")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("-2w")).not.toThrow();
+      });
+    });
+
+    describe("literals", () => {
+      it("should accept 'now' and 'today' literals", () => {
+        expect(() => FlexibleTimeSchema.parse("now")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("today")).not.toThrow();
+      });
+
+      it("should accept week notation", () => {
+        expect(() => FlexibleTimeSchema.parse("week-start")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("week-end")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("week-start+1w")).not.toThrow();
+        expect(() => FlexibleTimeSchema.parse("week-end-2w")).not.toThrow();
+      });
+    });
+
+    describe("invalid formats", () => {
+      it("should reject invalid formats", () => {
+        expect(() => FlexibleTimeSchema.parse("invalid")).toThrow();
+        expect(() => FlexibleTimeSchema.parse("")).toThrow();
+        expect(() => FlexibleTimeSchema.parse("not a date")).toThrow();
+      });
+
+      it("should reject partial ISO 8601 dates", () => {
+        expect(() => FlexibleTimeSchema.parse("2024-01-01")).toThrow();
+        expect(() => FlexibleTimeSchema.parse("2024-01")).toThrow();
+      });
+    });
+  });
+});

package/src/time/time-schemas.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+
+import { ISO8601Schema } from "./iso8601.types";
+
+export type TimeUnit = "s" | "m" | "h" | "d" | "w";
+
+export interface RelativeTimeConfig {
+  amount: number;
+  unit: TimeUnit;
+}
+
+export const RelativeTimeSchema = z.union([
+  z.literal("now"),
+  z.literal("today"),
+  z.literal("tomorrow"),
+  z.literal("yesterday"),
+  z
+    .string()
+    .regex(
+      /^(-?\d+)([smhdw])$/,
+      "Invalid relative time format. Use format like '1m' (1 min future), '2h' (2 hours future), '3d' (3 days future), '-1d' (1 day past), '-2w' (2 weeks past)"
+    ),
+  z
+    .string()
+    .regex(
+      /^week-(start|end)(([+-])\d+w)?$/,
+      "Invalid week notation format. Use format like 'week-start', 'week-end', 'week-start+1w', 'week-end-2w'"
+    ),
+]);
+
+/**
+ * Flexible time schema that accepts either ISO 8601 dates or relative time formats
+ *
+ * Supports:
+ * - ISO 8601 dates: "2024-01-01T12:00:00Z"
+ * - Literals: "now" (current datetime), "today" (current day at 00:00:00), "tomorrow" (next day), "yesterday" (previous day)
+ * - Relative future times: "30s", "5m", "2h", "3d", "1w" (positive = future)
+ * - Relative past times: "-1d" (yesterday), "-2w" (2 weeks ago) (negative = past)
+ * - Week notation: "week-start" (Monday 00:00:00), "week-end" (Sunday 23:59:59), "week-start+1w" (next week start), "week-end-2w" (end of 2 weeks ago)
+ */
+export const FlexibleTimeSchema = z.union([ISO8601Schema, RelativeTimeSchema]);
+export type FlexibleTime = z.infer<typeof FlexibleTimeSchema>;

package/src/time/time.schema.test.ts

@@ -0,0 +1,237 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+import { createBoundedFlexibleTimeSchema, createBoundedRelativeTimeSchema } from "./bounded-time.schema";
+import {
+  FlexibleTimeSchema,
+  FlexibleTimePastSchema,
+  FlexibleTimeFutureSchema,
+} from "./flexible-time.schema";
+import { ISO8601Schema, ISO8601DateSchema } from "./iso8601.schema";
+import {
+  RelativeTimeSchema,
+  RelativeTimePastSchema,
+  RelativeTimeFutureSchema,
+} from "./relative-time.schema";
+import { parseRelativeTime, parseFlexibleTime } from "./time-helpers";
+
+describe("time.schema", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2024-07-26T15:20:00Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("ISO8601Schema", () => {
+    it("should accept valid ISO8601 timestamps", () => {
+      expect(ISO8601Schema.parse("2024-07-26T15:20:00Z")).toBe(
+        "2024-07-26T15:20:00Z"
+      );
+      expect(ISO8601Schema.parse("2024-07-26T15:20:00.000Z")).toBe(
+        "2024-07-26T15:20:00.000Z"
+      );
+      expect(ISO8601Schema.parse("2024-07-26T17:20:00+02:00")).toBe(
+        "2024-07-26T17:20:00+02:00"
+      );
+    });
+
+    it("should reject invalid ISO8601 formats", () => {
+      expect(() => ISO8601Schema.parse("2024-07-26")).toThrow();
+      expect(() => ISO8601Schema.parse("invalid")).toThrow();
+    });
+  });
+
+  describe("ISO8601DateSchema", () => {
+    it("should accept valid date formats", () => {
+      expect(ISO8601DateSchema.parse("2024-07-26")).toBe("2024-07-26");
+      expect(ISO8601DateSchema.parse("2024-01-01")).toBe("2024-01-01");
+    });
+
+    it("should reject invalid dates", () => {
+      expect(() => ISO8601DateSchema.parse("2024-13-01")).toThrow();
+      expect(() => ISO8601DateSchema.parse("2024-01-32")).toThrow();
+      expect(() => ISO8601DateSchema.parse("2024-07-26T15:20:00Z")).toThrow();
+    });
+  });
+
+  describe("RelativeTimeSchema", () => {
+    it("should accept valid relative time expressions", () => {
+      expect(RelativeTimeSchema.parse("1d")).toBe("1d");
+      expect(RelativeTimeSchema.parse("3h")).toBe("3h");
+      expect(RelativeTimeSchema.parse("30m")).toBe("30m");
+      expect(RelativeTimeSchema.parse("1w")).toBe("1w");
+      expect(RelativeTimeSchema.parse("2M")).toBe("2M");
+    });
+
+    it("should reject invalid formats", () => {
+      expect(() => RelativeTimeSchema.parse("1")).toThrow();
+      expect(() => RelativeTimeSchema.parse("d")).toThrow();
+      expect(() => RelativeTimeSchema.parse("1x")).toThrow();
+    });
+  });
+
+  describe("FlexibleTimeSchema", () => {
+    it("should accept ISO8601 timestamps", () => {
+      expect(FlexibleTimeSchema.parse("2024-07-26T15:20:00Z")).toBe(
+        "2024-07-26T15:20:00Z"
+      );
+    });
+
+    it("should accept relative time expressions", () => {
+      expect(FlexibleTimeSchema.parse("1d")).toBe("1d");
+      expect(FlexibleTimeSchema.parse("3h")).toBe("3h");
+    });
+
+    it("should reject invalid formats", () => {
+      expect(() => FlexibleTimeSchema.parse("invalid")).toThrow();
+    });
+  });
+
+  describe("parseRelativeTime", () => {
+    it("should parse relative time in past direction", () => {
+      expect(parseRelativeTime("1d", new Date("2024-07-26T15:20:00Z"), "past")).toBe(
+        "2024-07-25T15:20:00.000Z"
+      );
+      expect(parseRelativeTime("30m", new Date("2024-07-26T15:20:00Z"), "past")).toBe(
+        "2024-07-26T14:50:00.000Z"
+      );
+    });
+
+    it("should parse relative time in future direction", () => {
+      expect(parseRelativeTime("1d", new Date("2024-07-26T15:20:00Z"), "future")).toBe(
+        "2024-07-27T15:20:00.000Z"
+      );
+      expect(parseRelativeTime("2h", new Date("2024-07-26T15:20:00Z"), "future")).toBe(
+        "2024-07-26T17:20:00.000Z"
+      );
+    });
+
+    it("should handle all time units", () => {
+      const base = new Date("2024-07-26T15:20:00Z");
+      expect(parseRelativeTime("30m", base, "past")).toBe("2024-07-26T14:50:00.000Z");
+      expect(parseRelativeTime("2h", base, "past")).toBe("2024-07-26T13:20:00.000Z");
+      expect(parseRelativeTime("3d", base, "past")).toBe("2024-07-23T15:20:00.000Z");
+      expect(parseRelativeTime("1w", base, "past")).toBe("2024-07-19T15:20:00.000Z");
+      expect(parseRelativeTime("1M", base, "past")).toBe("2024-06-26T15:20:00.000Z");
+    });
+  });
+
+  describe("parseFlexibleTime", () => {
+    it("should parse ISO8601 timestamps", () => {
+      expect(parseFlexibleTime("2024-07-26T15:20:00Z")).toBe(
+        "2024-07-26T15:20:00.000Z"
+      );
+    });
+
+    it("should parse relative times", () => {
+      expect(parseFlexibleTime("1d", new Date("2024-07-26T15:20:00Z"), "past")).toBe(
+        "2024-07-25T15:20:00.000Z"
+      );
+      expect(parseFlexibleTime("2h", new Date("2024-07-26T15:20:00Z"), "future")).toBe(
+        "2024-07-26T17:20:00.000Z"
+      );
+    });
+  });
+
+  describe("RelativeTimePastSchema", () => {
+    it("should transform relative time to ISO8601 (past direction)", () => {
+      expect(RelativeTimePastSchema.parse("1d")).toBe("2024-07-25T15:20:00.000Z");
+      expect(RelativeTimePastSchema.parse("30m")).toBe("2024-07-26T14:50:00.000Z");
+      expect(RelativeTimePastSchema.parse("1w")).toBe("2024-07-19T15:20:00.000Z");
+    });
+  });
+
+  describe("RelativeTimeFutureSchema", () => {
+    it("should transform relative time to ISO8601 (future direction)", () => {
+      expect(RelativeTimeFutureSchema.parse("1d")).toBe("2024-07-27T15:20:00.000Z");
+      expect(RelativeTimeFutureSchema.parse("2h")).toBe("2024-07-26T17:20:00.000Z");
+    });
+  });
+
+  describe("FlexibleTimePastSchema", () => {
+    it("should transform ISO8601 timestamps", () => {
+      expect(FlexibleTimePastSchema.parse("2024-07-26T15:20:00Z")).toBe(
+        "2024-07-26T15:20:00.000Z"
+      );
+    });
+
+    it("should transform relative times (past direction)", () => {
+      expect(FlexibleTimePastSchema.parse("1d")).toBe("2024-07-25T15:20:00.000Z");
+      expect(FlexibleTimePastSchema.parse("3h")).toBe("2024-07-26T12:20:00.000Z");
+    });
+  });
+
+  describe("FlexibleTimeFutureSchema", () => {
+    it("should transform ISO8601 timestamps", () => {
+      expect(FlexibleTimeFutureSchema.parse("2024-07-26T15:20:00Z")).toBe(
+        "2024-07-26T15:20:00.000Z"
+      );
+    });
+
+    it("should transform relative times (future direction)", () => {
+      expect(FlexibleTimeFutureSchema.parse("1d")).toBe("2024-07-27T15:20:00.000Z");
+      expect(FlexibleTimeFutureSchema.parse("2h")).toBe("2024-07-26T17:20:00.000Z");
+    });
+  });
+
+  describe("createBoundedFlexibleTimeSchema", () => {
+    it("should enforce minimum boundary (oldest allowed)", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1w" });
+      
+      // Should accept times more recent than 1w ago
+      expect(() => schema.parse("3d")).not.toThrow();
+      
+      // Should reject times older than 1w ago
+      expect(() => schema.parse("2w")).toThrow(/Time must be more recent than/);
+    });
+
+    it("should enforce maximum boundary (newest allowed)", () => {
+      const schema = createBoundedFlexibleTimeSchema({ max: "1d" });
+      
+      // Should accept times before max (older than 1d in future)
+      expect(() => schema.parse("1w")).not.toThrow();
+      
+      // Max in future means we accept past times, but we're using FlexibleTimePastSchema
+      // so it processes relative times as "going back"
+      expect(() => schema.parse("2024-10-01T00:00:00Z")).toThrow(/Time must be before/);
+    });
+
+    it("should enforce both min and max boundaries", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "2w", max: "1d" });
+      
+      // Should accept times within range
+      expect(() => schema.parse("3d")).not.toThrow();
+      expect(() => schema.parse("1w")).not.toThrow();
+      
+      // Should reject times outside range
+      expect(() => schema.parse("3w")).toThrow();
+    });
+
+    it("should work with ISO8601 inputs", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1w", max: "1w" });
+      
+      expect(() => schema.parse("2024-07-23T15:20:00Z")).not.toThrow();
+    });
+  });
+
+  describe("createBoundedRelativeTimeSchema", () => {
+    it("should enforce minimum boundary", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "30d" });
+      
+      // Should accept times within range
+      expect(() => schema.parse("1d")).not.toThrow();
+      
+      // Should reject times outside range
+      expect(() => schema.parse("60d")).toThrow();
+    });
+
+    it("should work with all time units", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "1M" });
+      
+      expect(() => schema.parse("1d")).not.toThrow();
+      expect(() => schema.parse("30m")).toThrow(); // Less than min
+    });
+  });
+});

package/src/time/timezone-independence.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+import { parseFlexibleTime } from "./flexible-time-parser";
+import { parseRelativeTime } from "./parse-relative-time";
+
+/**
+ * Timezone independence tests
+ * These tests verify that all time calculations produce identical results
+ * regardless of the system timezone setting.
+ */
+describe("timezone independence", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    // Set a fixed time for consistent testing
+    vi.setSystemTime(new Date("2024-01-15T12:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const baseTime = new Date("2024-01-15T12:00:00.000Z");
+
+  describe("flexible time parser", () => {
+    it("should return UTC midnight for 'today' regardless of local timezone", () => {
+      // This test verifies the fix for the "today" literal bug
+      // Before fix: would use local Date object causing timezone-dependent results
+      // After fix: uses dayjs.utc().startOf('day') for consistent UTC results
+      const result = parseFlexibleTime("today", baseTime);
+      expect(result).toBe("2024-01-15T00:00:00.000Z");
+      
+      // Verify the exact time components in UTC
+      const date = new Date(result);
+      expect(date.getUTCHours()).toBe(0);
+      expect(date.getUTCMinutes()).toBe(0);
+      expect(date.getUTCSeconds()).toBe(0);
+      expect(date.getUTCMilliseconds()).toBe(0);
+    });
+
+    it("should calculate week boundaries in UTC", () => {
+      // Monday 00:00:00 UTC (start of ISO week)
+      const weekStart = parseFlexibleTime("week-start", baseTime);
+      expect(weekStart).toBe("2024-01-15T00:00:00.000Z");
+      
+      const startDate = new Date(weekStart);
+      expect(startDate.getUTCDay()).toBe(1); // Monday
+      expect(startDate.getUTCHours()).toBe(0);
+      expect(startDate.getUTCMinutes()).toBe(0);
+      
+      // Sunday 23:59:59.999 UTC (end of ISO week)
+      const weekEnd = parseFlexibleTime("week-end", baseTime);
+      expect(weekEnd).toBe("2024-01-21T23:59:59.999Z");
+      
+      const endDate = new Date(weekEnd);
+      expect(endDate.getUTCDay()).toBe(0); // Sunday
+      expect(endDate.getUTCHours()).toBe(23);
+      expect(endDate.getUTCMinutes()).toBe(59);
+      expect(endDate.getUTCSeconds()).toBe(59);
+      expect(endDate.getUTCMilliseconds()).toBe(999);
+    });
+
+    it("should add relative time in UTC without DST interference", () => {
+      // These operations should add exact milliseconds in UTC
+      // No DST adjustments should occur
+      expect(parseFlexibleTime("1d", baseTime)).toBe("2024-01-16T12:00:00.000Z");
+      expect(parseFlexibleTime("1w", baseTime)).toBe("2024-01-22T12:00:00.000Z");
+      expect(parseFlexibleTime("-1d", baseTime)).toBe("2024-01-14T12:00:00.000Z");
+      expect(parseFlexibleTime("-1w", baseTime)).toBe("2024-01-08T12:00:00.000Z");
+    });
+
+    it("should handle DST boundary dates correctly", () => {
+      // US DST transition: March 10, 2024 at 2:00 AM (spring forward)
+      const beforeDST = new Date("2024-03-09T12:00:00.000Z");
+      const afterDST = new Date("2024-03-11T12:00:00.000Z");
+      
+      // Adding 1 day should add exactly 24 hours in UTC
+      expect(parseFlexibleTime("1d", beforeDST)).toBe("2024-03-10T12:00:00.000Z");
+      expect(parseFlexibleTime("1d", afterDST)).toBe("2024-03-12T12:00:00.000Z");
+      
+      // Week start should still be Monday 00:00:00 UTC
+      expect(parseFlexibleTime("week-start", beforeDST)).toBe("2024-03-04T00:00:00.000Z");
+      expect(parseFlexibleTime("week-start", afterDST)).toBe("2024-03-11T00:00:00.000Z");
+    });
+
+    it("should handle year boundary crossing in UTC", () => {
+      const endOfYear = new Date("2024-12-31T23:00:00.000Z");
+      
+      expect(parseFlexibleTime("1d", endOfYear)).toBe("2025-01-01T23:00:00.000Z");
+      expect(parseFlexibleTime("1w", endOfYear)).toBe("2025-01-07T23:00:00.000Z");
+      expect(parseFlexibleTime("today", endOfYear)).toBe("2024-12-31T00:00:00.000Z");
+    });
+
+    it("should handle leap year correctly in UTC", () => {
+      const leapDay = new Date("2024-02-29T12:00:00.000Z");
+      
+      expect(parseFlexibleTime("1d", leapDay)).toBe("2024-03-01T12:00:00.000Z");
+      expect(parseFlexibleTime("-1d", leapDay)).toBe("2024-02-28T12:00:00.000Z");
+      expect(parseFlexibleTime("today", leapDay)).toBe("2024-02-29T00:00:00.000Z");
+    });
+  });
+
+  describe("relative time parser", () => {
+    it("should subtract time in UTC", () => {
+      vi.setSystemTime(new Date("2024-07-26T15:20:00.000Z"));
+      
+      // All subtractions should be exact in UTC
+      expect(parseRelativeTime("1h")).toBe("2024-07-26T14:20:00.000Z");
+      expect(parseRelativeTime("1d")).toBe("2024-07-25T15:20:00.000Z");
+      expect(parseRelativeTime("1w")).toBe("2024-07-19T15:20:00.000Z");
+      expect(parseRelativeTime("1M")).toBe("2024-06-26T15:20:00.000Z");
+    });
+
+    it("should handle DST boundaries when subtracting time", () => {
+      // Set time after DST transition
+      vi.setSystemTime(new Date("2024-03-11T15:20:00.000Z"));
+      
+      // Subtracting 1 day should go back exactly 24 hours in UTC
+      expect(parseRelativeTime("1d")).toBe("2024-03-10T15:20:00.000Z");
+      expect(parseRelativeTime("2d")).toBe("2024-03-09T15:20:00.000Z");
+    });
+  });
+
+  describe("cross-timezone consistency", () => {
+    it("should produce identical results for UTC date components", () => {
+      // All these operations should produce results with consistent UTC components
+      const results = [
+        parseFlexibleTime("today", baseTime),
+        parseFlexibleTime("week-start", baseTime),
+        parseFlexibleTime("week-end", baseTime),
+      ];
+      
+      for (const result of results) {
+        const date = new Date(result);
+        // All results should end with Z (UTC)
+        expect(result).toMatch(/Z$/);
+        // Date parsing should work correctly
+        expect(date.toISOString()).toBe(result);
+      }
+    });
+
+    it("should handle midnight edge cases in UTC", () => {
+      const midnight = new Date("2024-01-15T00:00:00.000Z");
+      const almostMidnight = new Date("2024-01-14T23:59:59.999Z");
+      const afterMidnight = new Date("2024-01-15T00:00:00.001Z");
+      
+      // All should normalize to the same day start
+      expect(parseFlexibleTime("today", midnight)).toBe("2024-01-15T00:00:00.000Z");
+      expect(parseFlexibleTime("today", almostMidnight)).toBe("2024-01-14T00:00:00.000Z");
+      expect(parseFlexibleTime("today", afterMidnight)).toBe("2024-01-15T00:00:00.000Z");
+    });
+
+    it("should maintain precision to milliseconds in UTC", () => {
+      const preciseTime = new Date("2024-01-15T12:34:56.789Z");
+      
+      // Week boundaries should maintain millisecond precision
+      const weekEnd = parseFlexibleTime("week-end", preciseTime);
+      expect(weekEnd).toBe("2024-01-21T23:59:59.999Z");
+      expect(weekEnd.endsWith(".999Z")).toBe(true);
+      
+      // 'now' should preserve exact time
+      expect(parseFlexibleTime("now", preciseTime)).toBe("2024-01-15T12:34:56.789Z");
+    });
+  });
+
+  describe("ISO 8601 preservation", () => {
+    it("should preserve .000Z format in all outputs", () => {
+      const results = [
+        parseFlexibleTime("today", baseTime),
+        parseFlexibleTime("now", baseTime),
+        parseFlexibleTime("1d", baseTime),
+        parseFlexibleTime("week-start", baseTime),
+      ];
+      
+      for (const result of results) {
+        expect(result).toMatch(/\.\d{3}Z$/);
+      }
+    });
+
+    it("should handle timezone offset inputs correctly", () => {
+      // Input with timezone offset should normalize to UTC
+      const withOffset = "2024-01-15T13:00:00+01:00";
+      const result = parseFlexibleTime(withOffset, baseTime);
+      
+      // Should normalize to UTC (13:00+01:00 = 12:00Z)
+      expect(result).toBe("2024-01-15T12:00:00.000Z");
+    });
+  });
+});