feat: add scalar types utility functions and corresponding tests

Author: arnabrahman

packages/event-handler/src/appsync-graphql/scalarTypesUtils.ts

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+
+/**
+ * ID - A unique identifier for an object. This scalar is serialized like a String
+ * but isn't meant to be human-readable.
+ */
+export const makeId = () => randomUUID();
+
+/**
+ * AWSTimestamp - An integer value representing the number of seconds
+ * before or after 1970-01-01-T00:00Z.
+ */
+export const awsTimestamp = () => Math.floor(Date.now() / 1000);
+
+/**
+ * AWSDate - An extended ISO 8601 date string in the format YYYY-MM-DD.
+ *
+ * @param timezoneOffset - Timezone offset in hours, defaults to 0
+ */
+export const awsDate = (timezoneOffset = 0) =>
+  formattedTime(new Date(), '%Y-%m-%d', timezoneOffset);
+
+/**
+ * AWSTime - An extended ISO 8601 time string in the format hh:mm:ss.sss.
+ *
+ * @param timezoneOffset - Timezone offset in hours, defaults to 0
+ */
+export const awsTime = (timezoneOffset = 0) =>
+  formattedTime(new Date(), '%H:%M:%S.%f', timezoneOffset);
+
+/**
+ * AWSDateTime - An extended ISO 8601 date and time string in the format
+ * YYYY-MM-DDThh:mm:ss.sssZ.
+ *
+ * @param timezoneOffset - Timezone offset in hours, defaults to 0
+ */
+export const awsDateTime = (timezoneOffset = 0) =>
+  formattedTime(new Date(), '%Y-%m-%dT%H:%M:%S.%f', timezoneOffset);
+
+/**
+ * String formatted time with optional timezone offset
+ *
+ * @param now - Current Date object with zero timezone offset
+ * @param format - Date format function to apply before adding timezone offset
+ * @param timezoneOffset - Timezone offset in hours, defaults to 0
+ */
+const formattedTime = (
+  now: Date,
+  format: string,
+  timezoneOffset: number
+): string => {
+  if (timezoneOffset < -12 || timezoneOffset > 14) {
+    // Reference: https://en.wikipedia.org/wiki/List_of_UTC_offsets
+    throw new RangeError(
+      'timezoneOffset must be between -12 and +14 (inclusive)'
+    );
+  }
+  const adjustedDate = new Date(
+    now.getTime() + timezoneOffset * 60 * 60 * 1000
+  );
+
+  const formattedDateParts: Record<string, string> = {
+    '%Y': adjustedDate.getUTCFullYear().toString(),
+    '%m': (adjustedDate.getUTCMonth() + 1).toString().padStart(2, '0'),
+    '%d': adjustedDate.getUTCDate().toString().padStart(2, '0'),
+    '%H': adjustedDate.getUTCHours().toString().padStart(2, '0'),
+    '%M': adjustedDate.getUTCMinutes().toString().padStart(2, '0'),
+    '%S': adjustedDate.getUTCSeconds().toString().padStart(2, '0'),
+    '.%f': `.${adjustedDate.getUTCMilliseconds().toString().padStart(3, '0')}`,
+  };
+
+  const dateTimeStr = format.replace(
+    /%Y|%m|%d|%H|%M|%S|\.%f/g,
+    (match) => formattedDateParts[match]
+  );
+
+  let postfix: string;
+  if (timezoneOffset === 0) {
+    postfix = 'Z';
+  } else {
+    const sign = timezoneOffset > 0 ? '+' : '-';
+    const absOffset = Math.abs(timezoneOffset);
+    const hours = Math.floor(absOffset);
+    const minutes = Math.floor((absOffset - hours) * 60);
+    postfix = `${sign}${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:00`;
+  }
+
+  return `${dateTimeStr}${postfix}`;
+};

packages/event-handler/tests/unit/appsync-graphql/scalarTypesUtils.test.ts

@@ -0,0 +1,143 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import {
+  awsDate,
+  awsDateTime,
+  awsTime,
+  awsTimestamp,
+  makeId,
+} from '../../../src/appsync-graphql/scalarTypesUtils.js';
+
+const mockDate = new Date('2025-06-15T10:30:45.123Z');
+describe('Scalar Types Utils', () => {
+  beforeAll(() => {
+    vi.useFakeTimers().setSystemTime(mockDate);
+  });
+
+  afterAll(() => {
+    vi.useRealTimers();
+  });
+  describe('makeId', () => {
+    it('should generate a valid UUID', () => {
+      const id = makeId();
+      // UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+      const uuidRegex =
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+      expect(id).toMatch(uuidRegex);
+    });
+
+    it('should generate unique IDs', () => {
+      const id1 = makeId();
+      const id2 = makeId();
+      expect(id1).not.toBe(id2);
+    });
+  });
+
+  describe('awsDate', () => {
+    it('should return a date in YYYY-MM-DD format with Z timezone', () => {
+      const result = awsDate();
+      expect(result).toBe('2025-06-15Z');
+    });
+
+    it('should handle positive timezone offset', () => {
+      const result = awsDate(5);
+      expect(result).toBe('2025-06-15+05:00:00');
+    });
+
+    it('should handle negative timezone offset', () => {
+      const result = awsDate(-8);
+      expect(result).toBe('2025-06-15-08:00:00');
+    });
+
+    it('should handle date change with timezone offset', () => {
+      const result = awsDate(-11);
+      expect(result).toBe('2025-06-14-11:00:00');
+    });
+
+    it('should handle fractional timezone offset', () => {
+      const result = awsDate(5.5);
+      expect(result).toBe('2025-06-15+05:30:00');
+    });
+
+    it('should handle negative fractional timezone offset', () => {
+      const result = awsDate(-9.5);
+      expect(result).toBe('2025-06-15-09:30:00');
+    });
+
+    it('should throw RangeError for invalid timezone offset', () => {
+      expect(() => awsDate(15)).toThrow(RangeError);
+      expect(() => awsDate(-13)).toThrow(RangeError);
+    });
+  });
+
+  describe('awsTime', () => {
+    it('should return a time in HH:MM:SS.sss format with Z timezone', () => {
+      const result = awsTime();
+      expect(result).toBe('10:30:45.123Z');
+    });
+
+    it('should handle positive timezone offset', () => {
+      const result = awsTime(3);
+      expect(result).toBe('13:30:45.123+03:00:00');
+    });
+
+    it('should handle negative timezone offset', () => {
+      const result = awsTime(-5);
+      expect(result).toBe('05:30:45.123-05:00:00');
+    });
+
+    it('should handle fractional timezone offset', () => {
+      const result = awsTime(5.5);
+      expect(result).toBe('16:00:45.123+05:30:00');
+    });
+
+    it('should throw RangeError for invalid timezone offset', () => {
+      expect(() => awsTime(15)).toThrow(RangeError);
+      expect(() => awsTime(-13)).toThrow(RangeError);
+    });
+  });
+
+  describe('awsDateTime', () => {
+    it('should return a datetime in ISO 8601 format with Z timezone', () => {
+      const result = awsDateTime();
+      expect(result).toBe('2025-06-15T10:30:45.123Z');
+    });
+
+    it('should handle positive timezone offset', () => {
+      const result = awsDateTime(2);
+      expect(result).toBe('2025-06-15T12:30:45.123+02:00:00');
+    });
+
+    it('should handle negative timezone offset', () => {
+      const result = awsDateTime(-7);
+      expect(result).toBe('2025-06-15T03:30:45.123-07:00:00');
+    });
+
+    it('should handle date/time change with timezone offset', () => {
+      const result = awsDateTime(-11);
+      expect(result).toBe('2025-06-14T23:30:45.123-11:00:00');
+    });
+
+    it('should handle fractional timezone offset', () => {
+      const result = awsDateTime(5.5);
+      expect(result).toBe('2025-06-15T16:00:45.123+05:30:00');
+    });
+
+    it('should handle negative fractional timezone offset', () => {
+      const result = awsDateTime(-9.5);
+      expect(result).toBe('2025-06-15T01:00:45.123-09:30:00');
+    });
+
+    it('should throw RangeError for invalid timezone offset', () => {
+      expect(() => awsDateTime(15)).toThrow(RangeError);
+      expect(() => awsDateTime(-13)).toThrow(RangeError);
+    });
+  });
+
+  describe('awsTimestamp', () => {
+    it('should return current time as Unix timestamp in seconds', () => {
+      const result = awsTimestamp();
+      const expected = Math.floor(mockDate.getTime() / 1000);
+      expect(result).toBe(expected);
+    });
+  });
+});