@schafevormfenster/rest-commons 0.1.1

package/src/time/flexible-time-parser.test.ts

@@ -0,0 +1,586 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+import {
+  parseFlexibleTime,
+  createFlexibleTimeParser,
+} from "./flexible-time-parser";
+
+describe("flexible-time-parser", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2024-01-15T12:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("parseFlexibleTime", () => {
+    const baseTime = new Date("2024-01-15T12:00:00.000Z");
+
+    describe("ISO 8601 parsing", () => {
+      it("should parse ISO 8601 dates unchanged", () => {
+        const isoDate = "2024-01-01T10:00:00.000Z";
+        expect(parseFlexibleTime(isoDate, baseTime)).toBe(isoDate);
+      });
+
+      it("should preserve different ISO 8601 formats", () => {
+        expect(parseFlexibleTime("2024-12-31T23:59:59.999Z", baseTime)).toBe(
+          "2024-12-31T23:59:59.999Z"
+        );
+        expect(parseFlexibleTime("2024-06-15T12:30:45Z", baseTime)).toBe(
+          "2024-06-15T12:30:45.000Z"
+        );
+      });
+
+      it("should handle ISO 8601 with timezone offsets", () => {
+        // ISO 8601 with timezone offset gets normalized to UTC
+        const result = parseFlexibleTime("2024-01-15T13:00:00+01:00", baseTime);
+        expect(result).toBe("2024-01-15T12:00:00.000Z"); // +01:00 converts to UTC
+      });
+    });
+
+    describe("literal parsing", () => {
+      it("should parse 'now' to current datetime", () => {
+        expect(parseFlexibleTime("now", baseTime)).toBe(
+          "2024-01-15T12:00:00.000Z"
+        );
+      });
+
+      it("should parse 'today' to current day at midnight UTC", () => {
+        expect(parseFlexibleTime("today", baseTime)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+      });
+
+      it("should handle 'today' for different times of day", () => {
+        const morning = new Date("2024-01-15T03:30:45.123Z");
+        expect(parseFlexibleTime("today", morning)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+
+        const evening = new Date("2024-01-15T23:59:59.999Z");
+        expect(parseFlexibleTime("today", evening)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+      });
+
+      it("should handle 'today' across different dates", () => {
+        const date1 = new Date("2024-03-20T15:00:00.000Z");
+        expect(parseFlexibleTime("today", date1)).toBe(
+          "2024-03-20T00:00:00.000Z"
+        );
+
+        const date2 = new Date("2024-12-25T08:30:00.000Z");
+        expect(parseFlexibleTime("today", date2)).toBe(
+          "2024-12-25T00:00:00.000Z"
+        );
+      });
+
+      it("should parse 'tomorrow' as shortcut for 1d", () => {
+        expect(parseFlexibleTime("tomorrow", baseTime)).toBe(
+          "2024-01-16T12:00:00.000Z"
+        );
+      });
+
+      it("should parse 'yesterday' as shortcut for -1d", () => {
+        expect(parseFlexibleTime("yesterday", baseTime)).toBe(
+          "2024-01-14T12:00:00.000Z"
+        );
+      });
+    });
+
+    describe("relative time parsing", () => {
+      it("should parse seconds correctly (future)", () => {
+        expect(parseFlexibleTime("30s", baseTime)).toBe(
+          "2024-01-15T12:00:30.000Z"
+        );
+        expect(parseFlexibleTime("1s", baseTime)).toBe(
+          "2024-01-15T12:00:01.000Z"
+        );
+      });
+
+      it("should parse minutes correctly (future)", () => {
+        expect(parseFlexibleTime("1m", baseTime)).toBe(
+          "2024-01-15T12:01:00.000Z"
+        );
+        expect(parseFlexibleTime("30m", baseTime)).toBe(
+          "2024-01-15T12:30:00.000Z"
+        );
+      });
+
+      it("should parse hours correctly (future)", () => {
+        expect(parseFlexibleTime("1h", baseTime)).toBe(
+          "2024-01-15T13:00:00.000Z"
+        );
+        expect(parseFlexibleTime("2h", baseTime)).toBe(
+          "2024-01-15T14:00:00.000Z"
+        );
+        expect(parseFlexibleTime("12h", baseTime)).toBe(
+          "2024-01-16T00:00:00.000Z"
+        );
+      });
+
+      it("should parse days correctly (future)", () => {
+        expect(parseFlexibleTime("1d", baseTime)).toBe(
+          "2024-01-16T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("7d", baseTime)).toBe(
+          "2024-01-22T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("30d", baseTime)).toBe(
+          "2024-02-14T12:00:00.000Z"
+        );
+      });
+
+      it("should parse weeks correctly (future)", () => {
+        expect(parseFlexibleTime("1w", baseTime)).toBe(
+          "2024-01-22T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("2w", baseTime)).toBe(
+          "2024-01-29T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("4w", baseTime)).toBe(
+          "2024-02-12T12:00:00.000Z"
+        );
+      });
+
+      it("should parse negative seconds correctly (past)", () => {
+        expect(parseFlexibleTime("-30s", baseTime)).toBe(
+          "2024-01-15T11:59:30.000Z"
+        );
+        expect(parseFlexibleTime("-1s", baseTime)).toBe(
+          "2024-01-15T11:59:59.000Z"
+        );
+      });
+
+      it("should parse negative minutes correctly (past)", () => {
+        expect(parseFlexibleTime("-1m", baseTime)).toBe(
+          "2024-01-15T11:59:00.000Z"
+        );
+        expect(parseFlexibleTime("-30m", baseTime)).toBe(
+          "2024-01-15T11:30:00.000Z"
+        );
+      });
+
+      it("should parse negative hours correctly (past)", () => {
+        expect(parseFlexibleTime("-1h", baseTime)).toBe(
+          "2024-01-15T11:00:00.000Z"
+        );
+        expect(parseFlexibleTime("-2h", baseTime)).toBe(
+          "2024-01-15T10:00:00.000Z"
+        );
+        expect(parseFlexibleTime("-12h", baseTime)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+      });
+
+      it("should parse negative days correctly (past)", () => {
+        expect(parseFlexibleTime("-1d", baseTime)).toBe(
+          "2024-01-14T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("-7d", baseTime)).toBe(
+          "2024-01-08T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("-30d", baseTime)).toBe(
+          "2023-12-16T12:00:00.000Z"
+        );
+      });
+
+      it("should parse negative weeks correctly (past)", () => {
+        expect(parseFlexibleTime("-1w", baseTime)).toBe(
+          "2024-01-08T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("-2w", baseTime)).toBe(
+          "2024-01-01T12:00:00.000Z"
+        );
+        expect(parseFlexibleTime("-4w", baseTime)).toBe(
+          "2023-12-18T12:00:00.000Z"
+        );
+      });
+    });
+
+    describe("default baseTime", () => {
+      it("should use current time as default base for 'now'", () => {
+        expect(parseFlexibleTime("now")).toBe("2024-01-15T12:00:00.000Z");
+      });
+
+      it("should use current time as default base for 'today'", () => {
+        expect(parseFlexibleTime("today")).toBe("2024-01-15T00:00:00.000Z");
+      });
+
+      it("should use current time as default base for relative times", () => {
+        expect(parseFlexibleTime("1h")).toBe("2024-01-15T13:00:00.000Z");
+        expect(parseFlexibleTime("1d")).toBe("2024-01-16T12:00:00.000Z");
+        expect(parseFlexibleTime("-1h")).toBe("2024-01-15T11:00:00.000Z");
+        expect(parseFlexibleTime("-1d")).toBe("2024-01-14T12:00:00.000Z");
+      });
+    });
+
+    describe("error handling", () => {
+      it("should throw error for invalid formats", () => {
+        expect(() => parseFlexibleTime("invalid", baseTime)).toThrow(
+          "Invalid time format"
+        );
+        expect(() => parseFlexibleTime("1x", baseTime)).toThrow(
+          "Invalid time format"
+        );
+        expect(() => parseFlexibleTime("not-a-date", baseTime)).toThrow(
+          "Invalid time format"
+        );
+      });
+
+      it("should throw error for zero amounts", () => {
+        expect(() => parseFlexibleTime("0h", baseTime)).toThrow(
+          "Time amount cannot be zero"
+        );
+        expect(() => parseFlexibleTime("0d", baseTime)).toThrow(
+          "Time amount cannot be zero"
+        );
+        expect(() => parseFlexibleTime("-0h", baseTime)).toThrow(
+          "Time amount cannot be zero"
+        );
+      });
+
+      it("should provide helpful error messages", () => {
+        expect(() => parseFlexibleTime("invalid", baseTime)).toThrow(
+          "Expected ISO 8601 date, 'now', 'today', 'tomorrow', 'yesterday', relative format"
+        );
+        expect(() => parseFlexibleTime("invalid", baseTime)).toThrow(
+          "week notation"
+        );
+      });
+    });
+
+    describe("edge cases", () => {
+      it("should handle large relative time values", () => {
+        const result = parseFlexibleTime("365d", baseTime);
+        expect(result).toBe("2025-01-14T12:00:00.000Z");
+      });
+
+      it("should handle large negative relative time values", () => {
+        const result = parseFlexibleTime("-365d", baseTime);
+        expect(result).toBe("2023-01-15T12:00:00.000Z");
+      });
+
+      it("should handle boundary cases for 'today'", () => {
+        const midnight = new Date("2024-01-15T00:00:00.000Z");
+        expect(parseFlexibleTime("today", midnight)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+
+        const almostMidnight = new Date("2024-01-15T00:00:00.001Z");
+        expect(parseFlexibleTime("today", almostMidnight)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+      });
+    });
+  });
+
+  describe("createFlexibleTimeParser", () => {
+    it("should create a parser with fixed base time", () => {
+      const baseTime = new Date("2024-01-15T12:00:00.000Z");
+      const parser = createFlexibleTimeParser(baseTime);
+
+      expect(parser("1h")).toBe("2024-01-15T13:00:00.000Z");
+      expect(parser("2d")).toBe("2024-01-17T12:00:00.000Z");
+    });
+
+    it("should preserve ISO 8601 dates with fixed parser", () => {
+      const baseTime = new Date("2024-01-15T12:00:00.000Z");
+      const parser = createFlexibleTimeParser(baseTime);
+      const isoDate = "2024-01-01T10:00:00.000Z";
+
+      expect(parser(isoDate)).toBe(isoDate);
+    });
+
+    it("should handle 'now' and 'today' with fixed base time", () => {
+      const baseTime = new Date("2024-01-15T12:00:00.000Z");
+      const parser = createFlexibleTimeParser(baseTime);
+
+      expect(parser("now")).toBe("2024-01-15T12:00:00.000Z");
+      expect(parser("today")).toBe("2024-01-15T00:00:00.000Z");
+    });
+
+    it("should maintain consistent base time across multiple calls", () => {
+      const baseTime = new Date("2024-01-15T12:00:00.000Z");
+      const parser = createFlexibleTimeParser(baseTime);
+
+      const result1 = parser("now");
+      const result2 = parser("now");
+      const result3 = parser("1h");
+
+      expect(result1).toBe(result2);
+      expect(result1).toBe("2024-01-15T12:00:00.000Z");
+      expect(result3).toBe("2024-01-15T13:00:00.000Z");
+    });
+
+    it("should work with different base times", () => {
+      const baseTime1 = new Date("2024-01-01T00:00:00.000Z");
+      const parser1 = createFlexibleTimeParser(baseTime1);
+
+      const baseTime2 = new Date("2024-12-31T23:59:59.999Z");
+      const parser2 = createFlexibleTimeParser(baseTime2);
+
+      expect(parser1("now")).toBe("2024-01-01T00:00:00.000Z");
+      expect(parser2("now")).toBe("2024-12-31T23:59:59.999Z");
+
+      expect(parser1("today")).toBe("2024-01-01T00:00:00.000Z");
+      expect(parser2("today")).toBe("2024-12-31T00:00:00.000Z");
+    });
+
+    it("should handle negative relative times with fixed parser", () => {
+      const baseTime = new Date("2024-01-15T12:00:00.000Z");
+      const parser = createFlexibleTimeParser(baseTime);
+
+      expect(parser("-1h")).toBe("2024-01-15T11:00:00.000Z");
+      expect(parser("-2d")).toBe("2024-01-13T12:00:00.000Z");
+      expect(parser("-1w")).toBe("2024-01-08T12:00:00.000Z");
+    });
+  });
+
+  describe("week notation parsing", () => {
+    // Base time: Monday, Jan 15, 2024 at 12:00 PM UTC
+    const baseTime = new Date("2024-01-15T12:00:00.000Z");
+
+    describe("week-start (current week Monday)", () => {
+      it("should return Monday 00:00:00 when base is Monday", () => {
+        expect(parseFlexibleTime("week-start", baseTime)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+      });
+
+      it("should return Monday 00:00:00 when base is mid-week", () => {
+        const wednesday = new Date("2024-01-17T15:30:00.000Z");
+        expect(parseFlexibleTime("week-start", wednesday)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+      });
+
+      it("should return Monday 00:00:00 when base is Sunday", () => {
+        const sunday = new Date("2024-01-21T23:59:59.999Z");
+        expect(parseFlexibleTime("week-start", sunday)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+      });
+    });
+
+    describe("week-end (current week Sunday)", () => {
+      it("should return Sunday 23:59:59.999 when base is Monday", () => {
+        expect(parseFlexibleTime("week-end", baseTime)).toBe(
+          "2024-01-21T23:59:59.999Z"
+        );
+      });
+
+      it("should return Sunday 23:59:59.999 when base is mid-week", () => {
+        const wednesday = new Date("2024-01-17T15:30:00.000Z");
+        expect(parseFlexibleTime("week-end", wednesday)).toBe(
+          "2024-01-21T23:59:59.999Z"
+        );
+      });
+
+      it("should return Sunday 23:59:59.999 when base is Sunday", () => {
+        const sunday = new Date("2024-01-21T12:00:00.000Z");
+        expect(parseFlexibleTime("week-end", sunday)).toBe(
+          "2024-01-21T23:59:59.999Z"
+        );
+      });
+    });
+
+    describe("week-start with positive offset (future weeks)", () => {
+      it("should parse week-start+1w as next Monday", () => {
+        expect(parseFlexibleTime("week-start+1w", baseTime)).toBe(
+          "2024-01-22T00:00:00.000Z"
+        );
+      });
+
+      it("should parse week-start+2w as Monday 2 weeks ahead", () => {
+        expect(parseFlexibleTime("week-start+2w", baseTime)).toBe(
+          "2024-01-29T00:00:00.000Z"
+        );
+      });
+
+      it("should parse week-start+4w as Monday 4 weeks ahead", () => {
+        expect(parseFlexibleTime("week-start+4w", baseTime)).toBe(
+          "2024-02-12T00:00:00.000Z"
+        );
+      });
+    });
+
+    describe("week-start with negative offset (past weeks)", () => {
+      it("should parse week-start-1w as previous Monday", () => {
+        expect(parseFlexibleTime("week-start-1w", baseTime)).toBe(
+          "2024-01-08T00:00:00.000Z"
+        );
+      });
+
+      it("should parse week-start-2w as Monday 2 weeks ago", () => {
+        expect(parseFlexibleTime("week-start-2w", baseTime)).toBe(
+          "2024-01-01T00:00:00.000Z"
+        );
+      });
+
+      it("should parse week-start-3w as Monday 3 weeks ago", () => {
+        expect(parseFlexibleTime("week-start-3w", baseTime)).toBe(
+          "2023-12-25T00:00:00.000Z"
+        );
+      });
+    });
+
+    describe("week-end with positive offset (future weeks)", () => {
+      it("should parse week-end+1w as next Sunday", () => {
+        expect(parseFlexibleTime("week-end+1w", baseTime)).toBe(
+          "2024-01-28T23:59:59.999Z"
+        );
+      });
+
+      it("should parse week-end+2w as Sunday 2 weeks ahead", () => {
+        expect(parseFlexibleTime("week-end+2w", baseTime)).toBe(
+          "2024-02-04T23:59:59.999Z"
+        );
+      });
+
+      it("should parse week-end+3w as Sunday 3 weeks ahead", () => {
+        expect(parseFlexibleTime("week-end+3w", baseTime)).toBe(
+          "2024-02-11T23:59:59.999Z"
+        );
+      });
+    });
+
+    describe("week-end with negative offset (past weeks)", () => {
+      it("should parse week-end-1w as previous Sunday", () => {
+        expect(parseFlexibleTime("week-end-1w", baseTime)).toBe(
+          "2024-01-14T23:59:59.999Z"
+        );
+      });
+
+      it("should parse week-end-2w as Sunday 2 weeks ago", () => {
+        expect(parseFlexibleTime("week-end-2w", baseTime)).toBe(
+          "2024-01-07T23:59:59.999Z"
+        );
+      });
+
+      it("should parse week-end-3w as Sunday 3 weeks ago", () => {
+        expect(parseFlexibleTime("week-end-3w", baseTime)).toBe(
+          "2023-12-31T23:59:59.999Z"
+        );
+      });
+    });
+
+    describe("week notation from different weekdays", () => {
+      it("should calculate week-start correctly from Tuesday", () => {
+        const tuesday = new Date("2024-01-16T10:00:00.000Z");
+        expect(parseFlexibleTime("week-start", tuesday)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+        expect(parseFlexibleTime("week-start+1w", tuesday)).toBe(
+          "2024-01-22T00:00:00.000Z"
+        );
+      });
+
+      it("should calculate week-end correctly from Friday", () => {
+        const friday = new Date("2024-01-19T18:00:00.000Z");
+        expect(parseFlexibleTime("week-end", friday)).toBe(
+          "2024-01-21T23:59:59.999Z"
+        );
+        expect(parseFlexibleTime("week-end-1w", friday)).toBe(
+          "2024-01-14T23:59:59.999Z"
+        );
+      });
+
+      it("should calculate correctly from Saturday", () => {
+        const saturday = new Date("2024-01-20T20:00:00.000Z");
+        expect(parseFlexibleTime("week-start", saturday)).toBe(
+          "2024-01-15T00:00:00.000Z"
+        );
+        expect(parseFlexibleTime("week-end", saturday)).toBe(
+          "2024-01-21T23:59:59.999Z"
+        );
+      });
+    });
+
+    describe("week notation error handling", () => {
+      it("should throw error for invalid week boundary", () => {
+        expect(() => parseFlexibleTime("week-middle", baseTime)).toThrow(
+          "Invalid time format"
+        );
+        expect(() => parseFlexibleTime("week-begin", baseTime)).toThrow(
+          "Invalid time format"
+        );
+      });
+
+      it("should throw error for zero offset", () => {
+        expect(() => parseFlexibleTime("week-start+0w", baseTime)).toThrow(
+          "Week offset cannot be zero"
+        );
+        expect(() => parseFlexibleTime("week-end-0w", baseTime)).toThrow(
+          "Week offset cannot be zero"
+        );
+      });
+
+      it("should throw error for invalid offset format", () => {
+        expect(() => parseFlexibleTime("week-start+1d", baseTime)).toThrow(
+          "Invalid time format"
+        );
+        expect(() => parseFlexibleTime("week-end+2h", baseTime)).toThrow(
+          "Invalid time format"
+        );
+        expect(() => parseFlexibleTime("week-start1w", baseTime)).toThrow(
+          "Invalid time format"
+        );
+      });
+
+      it("should throw error for malformed syntax", () => {
+        expect(() => parseFlexibleTime("weekstart", baseTime)).toThrow(
+          "Invalid time format"
+        );
+        expect(() => parseFlexibleTime("week-start+", baseTime)).toThrow(
+          "Invalid time format"
+        );
+        expect(() => parseFlexibleTime("week-end-", baseTime)).toThrow(
+          "Invalid time format"
+        );
+      });
+    });
+
+    describe("week notation edge cases", () => {
+      it("should handle large positive offsets", () => {
+        expect(parseFlexibleTime("week-start+10w", baseTime)).toBe(
+          "2024-03-25T00:00:00.000Z"
+        );
+        expect(parseFlexibleTime("week-end+10w", baseTime)).toBe(
+          "2024-03-31T23:59:59.999Z"
+        );
+      });
+
+      it("should handle large negative offsets", () => {
+        expect(parseFlexibleTime("week-start-10w", baseTime)).toBe(
+          "2023-11-06T00:00:00.000Z"
+        );
+        expect(parseFlexibleTime("week-end-10w", baseTime)).toBe(
+          "2023-11-12T23:59:59.999Z"
+        );
+      });
+
+      it("should handle year boundary crossings", () => {
+        const endOfYear = new Date("2024-12-30T12:00:00.000Z"); // Monday
+        expect(parseFlexibleTime("week-start+1w", endOfYear)).toBe(
+          "2025-01-06T00:00:00.000Z"
+        );
+        expect(parseFlexibleTime("week-end+1w", endOfYear)).toBe(
+          "2025-01-12T23:59:59.999Z"
+        );
+      });
+
+      it("should handle leap year correctly", () => {
+        const leapDay = new Date("2024-02-29T12:00:00.000Z"); // Thursday
+        expect(parseFlexibleTime("week-start", leapDay)).toBe(
+          "2024-02-26T00:00:00.000Z"
+        );
+        expect(parseFlexibleTime("week-end", leapDay)).toBe(
+          "2024-03-03T23:59:59.999Z"
+        );
+      });
+    });
+  });
+});