@schafevormfenster/rest-commons 0.1.1

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

@@ -0,0 +1,294 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createBoundedFlexibleTimeSchema,
+  createBoundedRelativeTimeSchema,
+} from "./bounded-time.schema";
+
+describe("createBoundedFlexibleTimeSchema", () => {
+  describe("without boundaries", () => {
+    it("should accept any valid flexible time when no options provided", () => {
+      const schema = createBoundedFlexibleTimeSchema();
+
+      expect(() => schema.parse("1d")).not.toThrow();
+      expect(() => schema.parse("3h")).not.toThrow();
+      expect(() => schema.parse("2024-01-15T12:00:00Z")).not.toThrow();
+    });
+  });
+
+  describe("minimum boundary", () => {
+    it("should reject times older than minimum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1d" });
+
+      // 2 days ago should be rejected (older than 1 day minimum)
+      expect(() => schema.parse("2d")).toThrow(/must be more recent than 1d ago/);
+    });
+
+    it("should accept times newer than minimum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1w" });
+
+      // 3 days ago is more recent than 1 week ago
+      expect(() => schema.parse("3d")).not.toThrow();
+    });
+
+    it("should accept time at minimum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1d" });
+
+      // Exactly 1 day ago should be accepted
+      expect(() => schema.parse("1d")).not.toThrow();
+    });
+
+    it("should work with ISO8601 timestamps", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1w" });
+      const now = new Date();
+      const twoWeeksAgo = new Date(now.getTime() - 14 * 24 * 60 * 60 * 1000);
+
+      // 2 weeks ago should be rejected
+      expect(() => schema.parse(twoWeeksAgo.toISOString())).toThrow(
+        /must be more recent than/
+      );
+    });
+  });
+
+  describe("maximum boundary", () => {
+    it("should reject times beyond maximum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ max: "1M" });
+      const now = new Date();
+      const twoMonthsFuture = new Date(now);
+      twoMonthsFuture.setMonth(twoMonthsFuture.getMonth() + 2);
+
+      expect(() => schema.parse(twoMonthsFuture.toISOString())).toThrow(
+        /must be before 1M in the future/
+      );
+    });
+
+    it("should accept times within maximum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ max: "1M" });
+      const now = new Date();
+      const twoWeeksFuture = new Date(now.getTime() + 14 * 24 * 60 * 60 * 1000);
+
+      expect(() => schema.parse(twoWeeksFuture.toISOString())).not.toThrow();
+    });
+
+    it("should accept time at maximum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ max: "1d" });
+      const now = new Date();
+      const oneDayFuture = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+
+      expect(() => schema.parse(oneDayFuture.toISOString())).not.toThrow();
+    });
+  });
+
+  describe("both boundaries", () => {
+    it("should accept times within both boundaries", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1w", max: "1M" });
+
+      // 3 days ago is between 1 week ago and 1 month future
+      expect(() => schema.parse("3d")).not.toThrow();
+    });
+
+    it("should reject times outside minimum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1d", max: "1M" });
+
+      expect(() => schema.parse("3d")).toThrow(/must be more recent than 1d ago/);
+    });
+
+    it("should reject times outside maximum boundary", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1w", max: "1M" });
+      const now = new Date();
+      const twoMonthsFuture = new Date(now);
+      twoMonthsFuture.setMonth(twoMonthsFuture.getMonth() + 2);
+
+      expect(() => schema.parse(twoMonthsFuture.toISOString())).toThrow(
+        /must be before 1M in the future/
+      );
+    });
+
+    it("should handle complex boundary combinations", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "30d", max: "6M" });
+      const now = new Date();
+      
+      // 15 days ago is more recent than 30 days (should pass)
+      const fifteenDaysAgo = new Date(now.getTime() - 15 * 24 * 60 * 60 * 1000);
+      expect(() => schema.parse(fifteenDaysAgo.toISOString())).not.toThrow();
+
+      // 45 days ago is older than 30 days (should fail)
+      const fortyFiveDaysAgo = new Date(now.getTime() - 45 * 24 * 60 * 60 * 1000);
+      expect(() => schema.parse(fortyFiveDaysAgo.toISOString())).toThrow();
+    });
+  });
+
+  describe("relative time inputs", () => {
+    it("should handle minute-based relative times", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1h", max: "1d" });
+
+      expect(() => schema.parse("30m")).not.toThrow();
+    });
+
+    it("should handle hour-based relative times", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1d", max: "1w" });
+
+      expect(() => schema.parse("12h")).not.toThrow();
+    });
+
+    it("should handle week-based relative times", () => {
+      const schema = createBoundedFlexibleTimeSchema({ min: "1M", max: "6M" });
+
+      expect(() => schema.parse("2w")).not.toThrow();
+    });
+  });
+});
+
+describe("createBoundedRelativeTimeSchema", () => {
+  describe("without boundaries", () => {
+    it("should accept any valid relative time when no options provided", () => {
+      const schema = createBoundedRelativeTimeSchema();
+
+      expect(() => schema.parse("1d")).not.toThrow();
+      expect(() => schema.parse("3h")).not.toThrow();
+      expect(() => schema.parse("30m")).not.toThrow();
+    });
+  });
+
+  describe("minimum boundary (most recent allowed)", () => {
+    it("should reject times more recent than minimum", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1h" });
+
+      // 30 minutes ago is too recent (less than 1 hour ago)
+      expect(() => schema.parse("30m")).toThrow(/must be at least 1h ago/);
+    });
+
+    it("should accept times older than minimum", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1h" });
+
+      // 3 hours ago is old enough (more than 1 hour ago)
+      expect(() => schema.parse("3h")).not.toThrow();
+    });
+
+    it("should accept time near minimum boundary", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1d" });
+
+      // Times older than 1 day should be accepted
+      expect(() => schema.parse("2d")).not.toThrow();
+      expect(() => schema.parse("25h")).not.toThrow();
+    });
+  });
+
+  describe("maximum boundary (oldest allowed)", () => {
+    it("should reject times older than maximum", () => {
+      const schema = createBoundedRelativeTimeSchema({ max: "30d" });
+
+      // 60 days ago is too old (more than 30 days ago)
+      expect(() => schema.parse("60d")).toThrow(/cannot be more than 30d ago/);
+    });
+
+    it("should accept times newer than maximum", () => {
+      const schema = createBoundedRelativeTimeSchema({ max: "30d" });
+
+      // 15 days ago is recent enough (less than 30 days ago)
+      expect(() => schema.parse("15d")).not.toThrow();
+    });
+
+    it("should accept time at maximum boundary", () => {
+      const schema = createBoundedRelativeTimeSchema({ max: "7d" });
+
+      // Exactly 7 days ago should be accepted
+      expect(() => schema.parse("7d")).not.toThrow();
+    });
+  });
+
+  describe("both boundaries", () => {
+    it("should accept times within both boundaries", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "30d" });
+
+      // 3 days ago is between 1 hour and 30 days ago
+      expect(() => schema.parse("3d")).not.toThrow();
+    });
+
+    it("should reject times too recent (before minimum)", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "30d" });
+
+      // 30 minutes ago is too recent
+      expect(() => schema.parse("30m")).toThrow(/must be at least 1h ago/);
+    });
+
+    it("should reject times too old (after maximum)", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "30d" });
+
+      // 60 days ago is too old
+      expect(() => schema.parse("60d")).toThrow(/cannot be more than 30d ago/);
+    });
+
+    it("should handle complex boundary combinations", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1d", max: "7d" });
+
+      // 3 days ago is within range
+      expect(() => schema.parse("3d")).not.toThrow();
+
+      // 12 hours ago is too recent
+      expect(() => schema.parse("12h")).toThrow();
+
+      // 10 days ago is too old
+      expect(() => schema.parse("10d")).toThrow();
+    });
+  });
+
+  describe("various time units", () => {
+    it("should handle minute-based boundaries", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "30m", max: "2h" });
+
+      expect(() => schema.parse("1h")).not.toThrow();
+      expect(() => schema.parse("15m")).toThrow();
+      expect(() => schema.parse("3h")).toThrow();
+    });
+
+    it("should handle hour-based boundaries", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "6h", max: "24h" });
+
+      expect(() => schema.parse("12h")).not.toThrow();
+      expect(() => schema.parse("3h")).toThrow();
+      expect(() => schema.parse("48h")).toThrow();
+    });
+
+    it("should handle day-based boundaries", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1d", max: "14d" });
+
+      expect(() => schema.parse("7d")).not.toThrow();
+      expect(() => schema.parse("12h")).toThrow();
+      expect(() => schema.parse("30d")).toThrow();
+    });
+
+    it("should handle week-based boundaries", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1w", max: "4w" });
+
+      expect(() => schema.parse("2w")).not.toThrow();
+      expect(() => schema.parse("3d")).toThrow();
+      expect(() => schema.parse("6w")).toThrow();
+    });
+
+    it("should handle month-based boundaries", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1M", max: "6M" });
+
+      expect(() => schema.parse("3M")).not.toThrow();
+      expect(() => schema.parse("2w")).toThrow();
+      expect(() => schema.parse("12M")).toThrow();
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle very small time ranges", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "5m", max: "15m" });
+
+      expect(() => schema.parse("10m")).not.toThrow();
+      expect(() => schema.parse("3m")).toThrow();
+      expect(() => schema.parse("20m")).toThrow();
+    });
+
+    it("should handle very large time ranges", () => {
+      const schema = createBoundedRelativeTimeSchema({ min: "1M", max: "12M" });
+
+      expect(() => schema.parse("6M")).not.toThrow();
+      expect(() => schema.parse("2w")).toThrow();
+    });
+  });
+});

package/src/time/bounded-time.schema.ts

@@ -0,0 +1,111 @@
+import { FlexibleTimePastSchema } from "./flexible-time.schema";
+import { RelativeTimePastSchema } from "./relative-time.schema";
+import { parseRelativeTime } from "./time-helpers";
+
+/**
+ * Options for creating bounded schemas
+ */
+export interface BoundaryOptions {
+  /** Minimum allowed time (ISO8601 or relative from now) */
+  min?: string;
+  /** Maximum allowed time (ISO8601 or relative from now) */
+  max?: string;
+}
+
+/**
+ * Creates a flexible time schema with min/max boundaries
+ * @param options - Boundary configuration
+ * @returns Zod schema with boundary validation
+ * @example
+ * const schema = createBoundedFlexibleTimeSchema({ min: "1w", max: "1M" });
+ * schema.parse("3d"); // valid (between 1 week ago and 1 month in future)
+ * schema.parse("2M"); // throws error (exceeds max)
+ */
+export function createBoundedFlexibleTimeSchema(options: BoundaryOptions = {}) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let schema: any = FlexibleTimePastSchema;
+
+  if (options.min) {
+    // Min is the oldest allowed time (furthest in the past)
+    // For relative times going backwards, larger values are older
+    const minTime = parseRelativeTime(options.min, new Date(), "past");
+    const minMs = new Date(minTime).getTime();
+
+    schema = schema.refine(
+      (value: string) => {
+        const valueMs = new Date(value).getTime();
+        return valueMs >= minMs;
+      },
+      {
+        message: `Time must be more recent than ${options.min} ago (minimum: ${minTime})`,
+      }
+    );
+  }
+
+  if (options.max) {
+    // Max is the newest allowed time (can be in future for flexible time)
+    const maxTime = parseRelativeTime(options.max, new Date(), "future");
+    const maxMs = new Date(maxTime).getTime();
+
+    schema = schema.refine(
+      (value: string) => {
+        const valueMs = new Date(value).getTime();
+        return valueMs <= maxMs;
+      },
+      {
+        message: `Time must be before ${options.max} in the future (maximum: ${maxTime})`,
+      }
+    );
+  }
+
+  return schema;
+}
+
+/**
+ * Creates a relative time schema with min/max boundaries
+ * @param options - Boundary configuration (relative times going backwards from now)
+ * @returns Zod schema with boundary validation
+ * @example
+ * const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "30d" });
+ * schema.parse("3d"); // valid (3 days ago, between 1h and 30d ago)
+ * schema.parse("30m"); // throws error (too recent, less than 1h ago)
+ * schema.parse("60d"); // throws error (too old, more than 30d ago)
+ */
+export function createBoundedRelativeTimeSchema(options: BoundaryOptions = {}) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let schema: any = RelativeTimePastSchema;
+
+  if (options.min) {
+    // Min is the most recent allowed (closest to now)
+    const minTime = parseRelativeTime(options.min, new Date(), "past");
+    const minMs = new Date(minTime).getTime();
+
+    schema = schema.refine(
+      (value: string) => {
+        const valueMs = new Date(value).getTime();
+        return valueMs <= minMs; // Value must be older (earlier) than min
+      },
+      {
+        message: `Time must be at least ${options.min} ago (more recent than ${minTime})`,
+      }
+    );
+  }
+
+  if (options.max) {
+    // Max is the oldest allowed (furthest from now)
+    const maxTime = parseRelativeTime(options.max, new Date(), "past");
+    const maxMs = new Date(maxTime).getTime();
+
+    schema = schema.refine(
+      (value: string) => {
+        const valueMs = new Date(value).getTime();
+        return valueMs >= maxMs; // Value must be newer (later) than max
+      },
+      {
+        message: `Time cannot be more than ${options.max} ago (older than ${maxTime})`,
+      }
+    );
+  }
+
+  return schema;
+}