fix: treat offset-less datetimes as UTC

Author: farnabaz

src/runtime/internal/preview/utils.ts

@@ -70,25 +70,19 @@ export function parseSourceBase(source: CollectionSource) {
 }
 
 /**
- * Format a date string as `YYYY-MM-DD` for SQL DATE columns.
+ * Format a date value as `YYYY-MM-DD` for SQL DATE columns.
  *
  * Duplicated from `src/utils/content/transformers/utils.ts` because that
  * file lives outside the `runtime/` subtree and is not emitted to dist.
  * Importing it from the preview runtime causes a broken path in the
  * published package.
  *
- * Uses UTC getters to avoid timezone-dependent date shifts on non-UTC
- * CI runners or servers.
+ * Always uses UTC. Offset-less datetimes are treated as UTC.
  *
  * @see https://github.com/nuxt/content/issues/3742
  */
 export const formatDate = (date: string | Date): string => {
-  const input = date instanceof Date ? date.toISOString() : String(date)
-  if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
-    return input
-  }
-  const normalized = input.replace(/^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})(\.\d+)?$/, '$1T$2$3Z')
-  const d = new Date(normalized)
+  const d = toUtcDate(date)
   if (Number.isNaN(d.getTime())) {
     throw new TypeError(`Invalid date value: "${date}"`)
   }
@@ -101,20 +95,15 @@ export const formatDate = (date: string | Date): string => {
 }
 
 /**
- * Format a date string as `YYYY-MM-DD HH:mm:ss` for SQL DATETIME columns.
+ * Format a datetime value as `YYYY-MM-DD HH:mm:ss` for SQL DATETIME columns.
  *
- * Uses UTC getters to avoid timezone-dependent shifts.
+ * Always uses UTC. Offset-less datetimes are treated as UTC.
  *
  * @see {@link formatDate} for why this is duplicated here.
  * @see https://github.com/nuxt/content/issues/3742
  */
 export const formatDateTime = (datetime: string | Date): string => {
-  const input = datetime instanceof Date ? datetime.toISOString() : String(datetime)
-  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(input)) {
-    return input
-  }
-  const normalized = input.replace(/^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})(\.\d+)?$/, '$1T$2$3Z')
-  const d = new Date(normalized)
+  const d = toUtcDate(datetime)
   if (Number.isNaN(d.getTime())) {
     throw new TypeError(`Invalid datetime value: "${datetime}"`)
   }
@@ -128,3 +117,41 @@ export const formatDateTime = (datetime: string | Date): string => {
 
   return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')} ${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`
 }
+
+/**
+ * Parse a date/datetime value as UTC.
+ *
+ * - Date objects are used as-is
+ * - Space-separated datetimes (`YYYY-MM-DD HH:mm:ss[.sss]`) become ISO + Z
+ * - Offset-less ISO datetimes (`YYYY-MM-DDTHH:mm:ss[.sss]`) get a Z suffix
+ * - Date-only (`YYYY-MM-DD`) and values that already include Z/offset pass through
+ */
+function toUtcDate(value: string | Date): Date {
+  if (value instanceof Date) {
+    return value
+  }
+
+  const input = String(value).trim()
+
+  // Already has an explicit offset or Z — Date parses correctly as absolute time
+  if (/(?:z|[+-]\d{2}:?\d{2})$/i.test(input)) {
+    return new Date(input)
+  }
+
+  // Space-separated SQL-style datetime → ISO + Z
+  const spaceSeparated = input.replace(
+    /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})(\.\d+)?$/,
+    '$1T$2$3Z',
+  )
+  if (spaceSeparated !== input) {
+    return new Date(spaceSeparated)
+  }
+
+  // Offset-less ISO datetime (`2023-01-01T00:00:00`) → treat as UTC
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?$/.test(input)) {
+    return new Date(`${input}Z`)
+  }
+
+  // Date-only and everything else — Date-only is already UTC midnight per ES
+  return new Date(input)
+}

src/utils/content/transformers/utils.ts

@@ -4,13 +4,32 @@ export const defineTransformer = (transformer: ContentTransformer) => {
   return transformer
 }
 
-export const formatDateTime = (datetime: string | Date): string => {
-  const input = datetime instanceof Date ? datetime.toISOString() : String(datetime)
-  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(input)) {
-    return input
+/**
+ * Format a date value as `YYYY-MM-DD` for SQL DATE columns.
+ *
+ * Always uses UTC. Offset-less datetimes (e.g. `2023-01-01T00:00:00`,
+ * `2023-01-01 00:00:00`) are treated as UTC rather than local time.
+ */
+export const formatDate = (date: string | Date): string => {
+  const d = toUtcDate(date)
+  if (Number.isNaN(d.getTime())) {
+    throw new TypeError(`Invalid date value: "${date}"`)
   }
-  const normalized = input.replace(/^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})(\.\d+)?$/, '$1T$2$3Z')
-  const d = new Date(normalized)
+
+  const year = d.getUTCFullYear()
+  const month = d.getUTCMonth() + 1
+  const day = d.getUTCDate()
+
+  return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')}`
+}
+
+/**
+ * Format a datetime value as `YYYY-MM-DD HH:mm:ss` for SQL DATETIME columns.
+ *
+ * Always uses UTC. Offset-less datetimes are treated as UTC.
+ */
+export const formatDateTime = (datetime: string | Date): string => {
+  const d = toUtcDate(datetime)
   if (Number.isNaN(d.getTime())) {
     throw new TypeError(`Invalid datetime value: "${datetime}"`)
   }
@@ -25,20 +44,40 @@ export const formatDateTime = (datetime: string | Date): string => {
   return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')} ${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`
 }
 
-export const formatDate = (date: string | Date): string => {
-  const input = date instanceof Date ? date.toISOString() : String(date)
-  if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
-    return input
+/**
+ * Parse a date/datetime value as UTC.
+ *
+ * - Date objects are used as-is
+ * - Space-separated datetimes (`YYYY-MM-DD HH:mm:ss[.sss]`) become ISO + Z
+ * - Offset-less ISO datetimes (`YYYY-MM-DDTHH:mm:ss[.sss]`) get a Z suffix
+ * - Date-only (`YYYY-MM-DD`) and values that already include Z/offset pass through
+ */
+function toUtcDate(value: string | Date): Date {
+  if (value instanceof Date) {
+    return value
   }
-  const normalized = input.replace(/^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})(\.\d+)?$/, '$1T$2$3Z')
-  const d = new Date(normalized)
-  if (Number.isNaN(d.getTime())) {
-    throw new TypeError(`Invalid date value: "${date}"`)
+
+  const input = String(value).trim()
+
+  // Already has an explicit offset or Z — Date parses correctly as absolute time
+  if (/(?:z|[+-]\d{2}:?\d{2})$/i.test(input)) {
+    return new Date(input)
   }
 
-  const year = d.getUTCFullYear()
-  const month = d.getUTCMonth() + 1
-  const day = d.getUTCDate()
+  // Space-separated SQL-style datetime → ISO + Z
+  const spaceSeparated = input.replace(
+    /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})(\.\d+)?$/,
+    '$1T$2$3Z',
+  )
+  if (spaceSeparated !== input) {
+    return new Date(spaceSeparated)
+  }
 
-  return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')}`
+  // Offset-less ISO datetime (`2023-01-01T00:00:00`) → treat as UTC
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?$/.test(input)) {
+    return new Date(`${input}Z`)
+  }
+
+  // Date-only and everything else — Date-only is already UTC midnight per ES
+  return new Date(input)
 }

test/unit/formatDate.test.ts

@@ -16,21 +16,38 @@ describe('formatDate', () => {
   })
 
   it('handles end-of-year dates consistently in UTC', () => {
-    // 2022-12-31T23:00:00Z is still Dec 31 in UTC even if it's Jan 1 locally
+    // Still Dec 31 in UTC even when local TZ has crossed into Jan 1
     expect(formatDate('2022-12-31T23:00:00.000Z')).toBe('2022-12-31')
   })
 
   it('handles dates near midnight boundary in UTC', () => {
-    // This is Jan 1 00:30 UTC — should be 2023-01-01, not 2022-12-31
     expect(formatDate('2023-01-01T00:30:00.000Z')).toBe('2023-01-01')
   })
 
+  it('treats date-only strings as UTC calendar dates', () => {
+    expect(formatDate('2023-01-01')).toBe('2023-01-01')
+    expect(formatDate('2024-12-31')).toBe('2024-12-31')
+  })
+
+  it('treats offset-less ISO datetimes as UTC', () => {
+    // ES would parse this as local time; we force UTC
+    expect(formatDate('2023-01-01T00:00:00')).toBe('2023-01-01')
+    expect(formatDate('2022-12-31T23:30:00')).toBe('2022-12-31')
+  })
+
   it('parses space-separated datetime as UTC', () => {
     expect(formatDate('2022-06-15 14:30:00')).toBe('2022-06-15')
   })
 
-  it('handles Date object input', () => {
+  it('respects explicit non-UTC offsets', () => {
+    // 2023-01-01 00:30 in UTC+5:30 → 2022-12-31 19:00 UTC
+    expect(formatDate('2023-01-01T00:30:00+05:30')).toBe('2022-12-31')
+  })
+
+  it('handles Date object input via UTC components', () => {
     expect(formatDate(new Date('2022-06-15T14:30:00.000Z'))).toBe('2022-06-15')
+    // Near midnight UTC boundary
+    expect(formatDate(new Date('2022-12-31T23:00:00.000Z'))).toBe('2022-12-31')
   })
 
   it('throws on invalid date', () => {
@@ -40,7 +57,15 @@ describe('formatDate', () => {
 
   it('produces same output as the build-time copy', async () => {
     const buildTime = await import('../../src/utils/content/transformers/utils')
-    const inputs = ['2022-06-15T12:00:00.000Z', '2023-01-01T00:00:00.000Z', '2024-12-31T23:59:59.000Z']
+    const inputs = [
+      '2022-06-15T12:00:00.000Z',
+      '2023-01-01T00:00:00.000Z',
+      '2024-12-31T23:59:59.000Z',
+      '2023-01-01',
+      '2023-01-01T00:00:00',
+      '2022-06-15 14:30:00',
+      '2023-01-01T00:30:00+05:30',
+    ]
     for (const input of inputs) {
       expect(formatDate(input)).toBe(buildTime.formatDate(input))
     }
@@ -61,16 +86,30 @@ describe('formatDateTime', () => {
   })
 
   it('uses UTC time components regardless of system timezone', () => {
-    // Midnight UTC should always produce 00:00:00
     expect(formatDateTime('2022-06-15T00:00:00.000Z')).toBe('2022-06-15 00:00:00')
-    // 23:59:59 UTC should always produce that time, not shift to next day
     expect(formatDateTime('2022-12-31T23:59:59.000Z')).toBe('2022-12-31 23:59:59')
   })
 
+  it('treats offset-less ISO datetimes as UTC', () => {
+    expect(formatDateTime('2022-06-15T14:30:45')).toBe('2022-06-15 14:30:45')
+    expect(formatDateTime('2022-12-31T23:00:00')).toBe('2022-12-31 23:00:00')
+  })
+
+  it('parses space-separated datetime as UTC', () => {
+    expect(formatDateTime('2022-06-15 14:30:45')).toBe('2022-06-15 14:30:45')
+  })
+
+  it('respects explicit non-UTC offsets', () => {
+    expect(formatDateTime('2022-06-15T14:30:45+02:00')).toBe('2022-06-15 12:30:45')
+  })
+
+  it('handles Date object input', () => {
+    expect(formatDateTime(new Date('2022-06-15T14:30:45.000Z'))).toBe('2022-06-15 14:30:45')
+  })
+
   it('the date portion matches formatDate output', () => {
     const input = '2022-06-15T14:30:45.000Z'
-    const result = formatDateTime(input)
-    expect(result.split(' ')[0]).toBe(formatDate(input))
+    expect(formatDateTime(input).split(' ')[0]).toBe(formatDate(input))
   })
 
   it('throws on invalid datetime', () => {
@@ -80,7 +119,13 @@ describe('formatDateTime', () => {
 
   it('produces same output as the build-time copy', async () => {
     const buildTime = await import('../../src/utils/content/transformers/utils')
-    const inputs = ['2022-06-15T14:30:45.000Z', '2023-01-01T00:00:00.000Z']
+    const inputs = [
+      '2022-06-15T14:30:45.000Z',
+      '2023-01-01T00:00:00.000Z',
+      '2022-06-15T14:30:45',
+      '2022-06-15 14:30:45',
+      '2022-06-15T14:30:45+02:00',
+    ]
     for (const input of inputs) {
       expect(formatDateTime(input)).toBe(buildTime.formatDateTime(input))
     }