@schafevormfenster/rest-commons 0.1.1

package/src/time/parse-relative-time.ts

@@ -0,0 +1,50 @@
+import { getLogger } from "@schafevormfenster/logging";
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+
+dayjs.extend(utc);
+
+const log = getLogger("rest.helpers.relative-time-parser");
+
+/**
+ * Helper function to convert relative time expressions to ISO8601 timestamps
+ * All calculations are performed in UTC timezone
+ *
+ * @param relativeTime - Relative time expression like "1d", "3h", "30m"
+ * @returns ISO8601 timestamp string
+ */
+export const parseRelativeTime = (relativeTime: string): string => {
+  const relativePattern = /^(\d+)([mhdwM])$/;
+  const match = relativePattern.exec(relativeTime);
+
+  if (!match) {
+    log.error(
+      { relativeTime, error: `Invalid relative time format: ${relativeTime}` },
+      `Invalid relative time format: ${relativeTime}`
+    );
+    throw new Error(`Invalid relative time format: ${relativeTime}`);
+  }
+
+  const [, amount, unit] = match;
+  const numberAmount = Number.parseInt(amount, 10);
+
+  // Map unit to Day.js unit names
+  const unitMap: Record<string, dayjs.ManipulateType> = {
+    m: "minute",
+    h: "hour",
+    d: "day",
+    w: "week",
+    M: "month",
+  };
+
+  const dayjsUnit = unitMap[unit];
+  if (!dayjsUnit) {
+    log.error(
+      { unit, error: `Invalid time unit: ${unit}` },
+      `Invalid time unit: ${unit}`
+    );
+    throw new Error(`Invalid time unit: ${unit}`);
+  }
+
+  return dayjs.utc().subtract(numberAmount, dayjsUnit).toISOString();
+};

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

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+
+import { RelativeTimeSchema } from "./relative-time.schema";
+
+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");
+    expect(RelativeTimeSchema.parse("999d")).toBe("999d");
+  });
+
+  it("should reject invalid relative time expressions", () => {
+    expect(() => RelativeTimeSchema.parse("1")).toThrow();
+    expect(() => RelativeTimeSchema.parse("d")).toThrow();
+    expect(() => RelativeTimeSchema.parse("1x")).toThrow();
+    expect(() => RelativeTimeSchema.parse("1day")).toThrow();
+    expect(() => RelativeTimeSchema.parse("")).toThrow();
+    expect(() => RelativeTimeSchema.parse("1.5d")).toThrow();
+  });
+});

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

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+import { parseRelativeTime } from "./time-helpers";
+
+/**
+ * Core validation schema for relative time expressions
+ * Supports: "1m" (minute), "2h" (hour), "3d" (day), "1w" (week), "2M" (month)
+ * Validates format but does not transform
+ */
+export const RelativeTimeSchema = z
+  .string()
+  .describe("Relative time expression")
+  .regex(
+    /^(\d+)([mhdwM])$/,
+    "Must be a relative time expression (e.g., '1d', '3h', '30m', '1w', '2M')"
+  );
+
+export type RelativeTime = z.infer<typeof RelativeTimeSchema>;
+
+/**
+ * Transformation schema that converts relative time to ISO8601
+ * Direction: past (subtracts from current time)
+ * @example
+ * RelativeTimePastSchema.parse("1d") // "2024-01-14T12:00:00.000Z" (if now is 2024-01-15T12:00:00Z)
+ */
+export const RelativeTimePastSchema = RelativeTimeSchema.transform((value) =>
+  parseRelativeTime(value, new Date(), "past")
+);
+
+/**
+ * Transformation schema that converts relative time to ISO8601
+ * Direction: future (adds to current time)
+ * @example
+ * RelativeTimeFutureSchema.parse("1d") // "2024-01-16T12:00:00.000Z" (if now is 2024-01-15T12:00:00Z)
+ */
+export const RelativeTimeFutureSchema = RelativeTimeSchema.transform((value) =>
+  parseRelativeTime(value, new Date(), "future")
+);

package/src/time/since-parameter.schema.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+import { SinceParameterSchema } from "./since-parameter.schema";
+
+describe("SinceParameterSchema", () => {
+  beforeEach(() => {
+    // Mock the current time to a fixed date for consistent testing
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2024-07-26T15:20:00Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should accept valid ISO8601 timestamps", () => {
+    const result = SinceParameterSchema.parse("2024-07-26T15:20:00Z");
+    expect(result).toBe("2024-07-26T15:20:00.000Z");
+  });
+
+  it("should accept ISO8601 timestamps with timezone offsets", () => {
+    const result = SinceParameterSchema.parse("2024-07-26T17:20:00+02:00");
+    expect(result).toBe("2024-07-26T15:20:00.000Z");
+  });
+
+  it("should convert relative time expressions to ISO8601", () => {
+    const result = SinceParameterSchema.parse("1d");
+    expect(result).toBe("2024-07-25T15:20:00.000Z");
+  });
+
+  it("should convert various relative time units", () => {
+    expect(SinceParameterSchema.parse("30m")).toBe("2024-07-26T14:50:00.000Z");
+    expect(SinceParameterSchema.parse("2h")).toBe("2024-07-26T13:20:00.000Z");
+    expect(SinceParameterSchema.parse("3d")).toBe("2024-07-23T15:20:00.000Z");
+    expect(SinceParameterSchema.parse("1w")).toBe("2024-07-19T15:20:00.000Z");
+    expect(SinceParameterSchema.parse("1M")).toBe("2024-06-26T15:20:00.000Z");
+  });
+
+  it("should reject invalid formats", () => {
+    expect(() => SinceParameterSchema.parse("invalid")).toThrow(
+      /Must be either ISO8601 timestamp or relative time expression/
+    );
+    expect(() => SinceParameterSchema.parse("2024-13-32")).toThrow(
+      /Must be either ISO8601 timestamp or relative time expression/
+    );
+    expect(() => SinceParameterSchema.parse("1x")).toThrow(
+      /Must be either ISO8601 timestamp or relative time expression/
+    );
+  });
+
+  it("should reject invalid ISO8601 formats", () => {
+    expect(() => SinceParameterSchema.parse("2024-07-26")).toThrow(
+      /Must be either ISO8601 timestamp or relative time expression/
+    );
+    expect(() => SinceParameterSchema.parse("not-a-date")).toThrow(
+      /Must be either ISO8601 timestamp or relative time expression/
+    );
+  });
+});

package/src/time/since-parameter.schema.ts

@@ -0,0 +1,69 @@
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+import { z } from "zod";
+
+dayjs.extend(utc);
+
+/**
+ * Schema that accepts either ISO8601 timestamps or relative time expressions
+ * All calculations are performed in UTC timezone
+ */
+export const SinceParameterSchema = z
+  .string()
+  .describe("Timestamp in ISO8601 format or relative time expression")
+  .transform((value, context) => {
+    // Try to parse as ISO8601 first
+    const iso8601Pattern =
+      /^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$/;
+
+    if (iso8601Pattern.test(value)) {
+      try {
+        return new Date(value).toISOString();
+      } catch {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Invalid ISO8601 timestamp format",
+        });
+        return z.NEVER;
+      }
+    }
+
+    // Try to parse as relative time
+    const relativePattern = /^(\d+)([mhdwM])$/;
+    const match = relativePattern.exec(value);
+
+    if (!match) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "Must be either ISO8601 timestamp or relative time expression (e.g., '1d', '3h', '30m')",
+      });
+      return z.NEVER;
+    }
+
+    const [, amount, unit] = match;
+    const numberAmount = Number.parseInt(amount, 10);
+
+    // Map unit to Day.js unit names
+    const unitMap: Record<string, dayjs.ManipulateType> = {
+      m: "minute",
+      h: "hour",
+      d: "day",
+      w: "week",
+      M: "month",
+    };
+
+    const dayjsUnit = unitMap[unit];
+    if (!dayjsUnit) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "Invalid time unit. Use 'm' (minutes), 'h' (hours), 'd' (days), 'w' (weeks), or 'M' (months)",
+      });
+      return z.NEVER;
+    }
+
+    return dayjs.utc().subtract(numberAmount, dayjsUnit).toISOString();
+  });
+
+export type SinceParameter = z.infer<typeof SinceParameterSchema>;

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

@@ -0,0 +1,263 @@
+import { describe, expect, it } from "vitest";
+
+import { parseFlexibleTime, parseRelativeTime } from "./time-helpers";
+
+describe("parseRelativeTime", () => {
+  const baseDate = new Date("2024-01-15T12:00:00.000Z");
+
+  describe("past direction", () => {
+    it("should subtract minutes", () => {
+      const result = parseRelativeTime("30m", baseDate, "past");
+      expect(result).toBe("2024-01-15T11:30:00.000Z");
+    });
+
+    it("should subtract hours", () => {
+      const result = parseRelativeTime("3h", baseDate, "past");
+      expect(result).toBe("2024-01-15T09:00:00.000Z");
+    });
+
+    it("should subtract days", () => {
+      const result = parseRelativeTime("2d", baseDate, "past");
+      expect(result).toBe("2024-01-13T12:00:00.000Z");
+    });
+
+    it("should subtract weeks", () => {
+      const result = parseRelativeTime("1w", baseDate, "past");
+      expect(result).toBe("2024-01-08T12:00:00.000Z");
+    });
+
+    it("should subtract months", () => {
+      const result = parseRelativeTime("1M", baseDate, "past");
+      expect(result).toBe("2023-12-15T12:00:00.000Z");
+    });
+
+    it("should default to past direction", () => {
+      const result = parseRelativeTime("1d", baseDate);
+      expect(result).toBe("2024-01-14T12:00:00.000Z");
+    });
+  });
+
+  describe("future direction", () => {
+    it("should add minutes", () => {
+      const result = parseRelativeTime("30m", baseDate, "future");
+      expect(result).toBe("2024-01-15T12:30:00.000Z");
+    });
+
+    it("should add hours", () => {
+      const result = parseRelativeTime("3h", baseDate, "future");
+      expect(result).toBe("2024-01-15T15:00:00.000Z");
+    });
+
+    it("should add days", () => {
+      const result = parseRelativeTime("2d", baseDate, "future");
+      expect(result).toBe("2024-01-17T12:00:00.000Z");
+    });
+
+    it("should add weeks", () => {
+      const result = parseRelativeTime("1w", baseDate, "future");
+      expect(result).toBe("2024-01-22T12:00:00.000Z");
+    });
+
+    it("should add months", () => {
+      const result = parseRelativeTime("1M", baseDate, "future");
+      expect(result).toBe("2024-02-15T12:00:00.000Z");
+    });
+  });
+
+  describe("various time amounts", () => {
+    it("should handle single digit amounts", () => {
+      const result = parseRelativeTime("1d", baseDate, "past");
+      expect(result).toBe("2024-01-14T12:00:00.000Z");
+    });
+
+    it("should handle double digit amounts", () => {
+      const result = parseRelativeTime("15d", baseDate, "past");
+      expect(result).toBe("2023-12-31T12:00:00.000Z");
+    });
+
+    it("should handle large amounts", () => {
+      const result = parseRelativeTime("365d", baseDate, "past");
+      expect(result).toBe("2023-01-15T12:00:00.000Z");
+    });
+  });
+
+  describe("default parameters", () => {
+    it("should use current time when 'from' is not provided", () => {
+      const result = parseRelativeTime("1d");
+      expect(result).toBeTruthy();
+      expect(typeof result).toBe("string");
+    });
+  });
+
+  describe("error handling", () => {
+    it("should throw error for invalid format", () => {
+      expect(() => parseRelativeTime("invalid", baseDate)).toThrow(
+        /Invalid relative time format: invalid/
+      );
+    });
+
+    it("should throw error for missing unit", () => {
+      expect(() => parseRelativeTime("5", baseDate)).toThrow(
+        /Invalid relative time format/
+      );
+    });
+
+    it("should throw error for missing amount", () => {
+      expect(() => parseRelativeTime("d", baseDate)).toThrow(
+        /Invalid relative time format/
+      );
+    });
+
+    it("should throw error for invalid unit", () => {
+      expect(() => parseRelativeTime("5x", baseDate)).toThrow(
+        /Invalid relative time format/
+      );
+    });
+
+    it("should throw error for spaces in input", () => {
+      expect(() => parseRelativeTime("5 d", baseDate)).toThrow(
+        /Invalid relative time format/
+      );
+    });
+  });
+
+  describe("UTC timezone handling", () => {
+    it("should return ISO8601 strings in UTC", () => {
+      const result = parseRelativeTime("1d", baseDate, "past");
+      expect(result).toMatch(/Z$/);
+    });
+
+    it("should maintain UTC regardless of input timezone", () => {
+      const localDate = new Date("2024-01-15T12:00:00+05:00");
+      const result = parseRelativeTime("1d", localDate, "past");
+      expect(result).toMatch(/Z$/);
+    });
+  });
+});
+
+describe("parseFlexibleTime", () => {
+  const baseDate = new Date("2024-01-15T12:00:00.000Z");
+
+  describe("ISO8601 input", () => {
+    it("should parse valid ISO8601 datetime", () => {
+      const input = "2024-01-15T12:00:00Z";
+      const result = parseFlexibleTime(input, baseDate);
+      expect(result).toBe("2024-01-15T12:00:00.000Z");
+    });
+
+    it("should normalize ISO8601 to standard format", () => {
+      const input = "2024-01-15T12:00:00+00:00";
+      const result = parseFlexibleTime(input, baseDate);
+      expect(result).toBe("2024-01-15T12:00:00.000Z");
+    });
+
+    it("should handle ISO8601 with milliseconds", () => {
+      const input = "2024-01-15T12:00:00.123Z";
+      const result = parseFlexibleTime(input, baseDate);
+      expect(result).toBe("2024-01-15T12:00:00.123Z");
+    });
+
+    it("should handle ISO8601 with different timezones", () => {
+      const input = "2024-01-15T12:00:00+05:00";
+      const result = parseFlexibleTime(input, baseDate);
+      expect(result).toBe("2024-01-15T07:00:00.000Z");
+    });
+  });
+
+  describe("relative time input", () => {
+    it("should parse relative time in past direction (default)", () => {
+      const result = parseFlexibleTime("1d", baseDate);
+      expect(result).toBe("2024-01-14T12:00:00.000Z");
+    });
+
+    it("should parse relative time with explicit past direction", () => {
+      const result = parseFlexibleTime("2h", baseDate, "past");
+      expect(result).toBe("2024-01-15T10:00:00.000Z");
+    });
+
+    it("should parse relative time in future direction", () => {
+      const result = parseFlexibleTime("3d", baseDate, "future");
+      expect(result).toBe("2024-01-18T12:00:00.000Z");
+    });
+
+    it("should handle minutes", () => {
+      const result = parseFlexibleTime("30m", baseDate, "past");
+      expect(result).toBe("2024-01-15T11:30:00.000Z");
+    });
+
+    it("should handle hours", () => {
+      const result = parseFlexibleTime("6h", baseDate, "past");
+      expect(result).toBe("2024-01-15T06:00:00.000Z");
+    });
+
+    it("should handle weeks", () => {
+      const result = parseFlexibleTime("2w", baseDate, "past");
+      expect(result).toBe("2024-01-01T12:00:00.000Z");
+    });
+
+    it("should handle months", () => {
+      const result = parseFlexibleTime("1M", baseDate, "past");
+      expect(result).toBe("2023-12-15T12:00:00.000Z");
+    });
+  });
+
+  describe("default parameters", () => {
+    it("should use current time when 'from' is not provided", () => {
+      const result = parseFlexibleTime("1d");
+      expect(result).toBeTruthy();
+      expect(typeof result).toBe("string");
+    });
+
+    it("should default to past direction", () => {
+      const result = parseFlexibleTime("1h", baseDate);
+      expect(result).toBe("2024-01-15T11:00:00.000Z");
+    });
+  });
+
+  describe("error handling", () => {
+    it("should throw error for invalid input", () => {
+      expect(() => parseFlexibleTime("invalid", baseDate)).toThrow(
+        /Invalid flexible time format: invalid/
+      );
+    });
+
+    it("should throw error for malformed ISO8601", () => {
+      expect(() => parseFlexibleTime("2024-13-01", baseDate)).toThrow(
+        /Invalid flexible time format/
+      );
+    });
+
+    it("should throw error for malformed relative time", () => {
+      expect(() => parseFlexibleTime("5x", baseDate)).toThrow(
+        /Invalid flexible time format/
+      );
+    });
+
+    it("should throw error for empty string", () => {
+      expect(() => parseFlexibleTime("", baseDate)).toThrow(
+        /Invalid flexible time format/
+      );
+    });
+  });
+
+  describe("prioritization (ISO8601 first)", () => {
+    it("should prioritize ISO8601 parsing over relative time", () => {
+      const iso = "2024-01-15T12:00:00Z";
+      const result = parseFlexibleTime(iso, baseDate);
+      // Should be parsed as ISO8601, not as relative time
+      expect(result).toBe("2024-01-15T12:00:00.000Z");
+    });
+  });
+
+  describe("UTC timezone handling", () => {
+    it("should return ISO8601 strings in UTC", () => {
+      const result = parseFlexibleTime("1d", baseDate, "past");
+      expect(result).toMatch(/Z$/);
+    });
+
+    it("should normalize all outputs to UTC", () => {
+      const result = parseFlexibleTime("2024-01-15T12:00:00+05:00", baseDate);
+      expect(result).toMatch(/Z$/);
+    });
+  });
+});

package/src/time/time-helpers.ts

@@ -0,0 +1,78 @@
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+
+import { ISO8601Schema } from "./iso8601.schema";
+import { RelativeTimeSchema } from "./relative-time.schema";
+
+dayjs.extend(utc);
+
+/**
+ * Helper function to parse relative time and calculate the datetime
+ * All calculations are performed in UTC timezone
+ * @param relativeTime - Relative time string like "1d", "3h", "30m"
+ * @param from - Base datetime to calculate from (defaults to now)
+ * @param direction - Whether to subtract (past) or add (future)
+ * @returns ISO8601 datetime string
+ */
+export function parseRelativeTime(
+  relativeTime: string,
+  from: Date = new Date(),
+  direction: "past" | "future" = "past"
+): string {
+  const match = relativeTime.match(/^(\d+)([mhdwM])$/);
+  if (!match) {
+    throw new Error(
+      `Invalid relative time format: ${relativeTime}. Expected format like '1d', '3h', '30m'`
+    );
+  }
+
+  const [, amount, unit] = match;
+  const numberAmount = Number.parseInt(amount, 10);
+
+  // Map unit to Day.js unit names
+  const unitMap: Record<string, dayjs.ManipulateType> = {
+    m: "minute",
+    h: "hour",
+    d: "day",
+    w: "week",
+    M: "month",
+  };
+
+  const dayjsUnit = unitMap[unit];
+  if (!dayjsUnit) {
+    throw new Error(`Invalid time unit: ${unit}`);
+  }
+
+  const operation = direction === "past" ? "subtract" : "add";
+  return dayjs.utc(from)[operation](numberAmount, dayjsUnit).toISOString();
+}
+
+/**
+ * Helper function to parse flexible time (ISO8601 or relative) to ISO8601
+ * All calculations are performed in UTC timezone
+ * @param flexibleTime - ISO8601 string or relative time expression
+ * @param from - Base datetime for relative time calculations (defaults to now)
+ * @param direction - Whether relative times are past or future (defaults to past)
+ * @returns ISO8601 datetime string
+ */
+export function parseFlexibleTime(
+  flexibleTime: string,
+  from: Date = new Date(),
+  direction: "past" | "future" = "past"
+): string {
+  // Try to parse as ISO8601 first
+  const isoResult = ISO8601Schema.safeParse(flexibleTime);
+  if (isoResult.success) {
+    return new Date(flexibleTime).toISOString();
+  }
+
+  // Try to parse as relative time
+  const relativeResult = RelativeTimeSchema.safeParse(flexibleTime);
+  if (relativeResult.success) {
+    return parseRelativeTime(flexibleTime, from, direction);
+  }
+
+  throw new Error(
+    `Invalid flexible time format: ${flexibleTime}. Expected ISO8601 datetime or relative time expression`
+  );
+}