feat: withDateOperation HOF and startOf util

Author: bart-krakowski

packages/time/src/date/parse/tests/parse.test.ts

@@ -1,5 +1,4 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
-import { Temporal } from '@js-temporal/polyfill'
 import { parse } from '../parse'
 
 const dateTimeFormat = new Intl.DateTimeFormat('en-US', {

packages/time/src/date/startOf/startOf.ts

@@ -0,0 +1,57 @@
+import { withDateOperation } from '../withDateOperation'
+import type {
+  DateInput,
+  DateOperationOptions,
+  DateOperationResult,
+} from '../withDateOperation'
+
+export type StartOfUnit =
+  | 'year'
+  | 'month'
+  | 'week'
+  | 'day'
+  | 'hour'
+  | 'minute'
+  | 'second'
+  | 'millisecond'
+
+export interface StartOfArgs extends Record<string, unknown> {
+  unit: StartOfUnit
+}
+
+/**
+ * startOf
+ * Returns the start of a given unit for a date/time instance
+ */
+export function startOf(
+  input: DateInput,
+  args: StartOfArgs,
+  options?: DateOperationOptions,
+): DateOperationResult {
+  return withDateOperation<StartOfArgs>((zdt, { unit }) => {
+    switch (unit) {
+      case 'year':
+        return zdt.with({ month: 1, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 })
+      case 'month':
+        return zdt.with({ day: 1, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 })
+      case 'week': {
+        const dayOfWeek = zdt.dayOfWeek
+        const firstDayOfWeek = 1
+        const daysToSubtract = (dayOfWeek - firstDayOfWeek + 7) % 7
+        return zdt.subtract({ days: daysToSubtract })
+      }
+      case 'day':
+        return zdt.with({ hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 })
+      case 'hour':
+        return zdt.with({ minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 })
+      case 'minute':
+        return zdt.with({ second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 })
+      case 'second':
+        return zdt.with({ millisecond: 0, microsecond: 0, nanosecond: 0 })
+      case 'millisecond':
+        return zdt.with({ microsecond: 0, nanosecond: 0 })
+      default:
+        return zdt
+    }
+  })(input, args, options)
+}

packages/time/src/date/startOf/tests/startOf.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'vitest'
+import { startOf } from '../startOf'
+
+describe('startOf', () => {
+  describe('with string input', () => {
+    test('should return start of year', () => {
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'year' }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toBe('2024-01-01T00:00:00Z')
+      expect(result.options.timeZone).toBe('UTC')
+      expect(result.options.calendar).toBeDefined()
+    })
+
+    test('should return start of month', () => {
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'month' }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toBe('2024-03-01T00:00:00Z')
+    })
+
+    test('should return start of day', () => {
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'day' }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toBe('2024-03-15T00:00:00Z')
+    })
+
+    test('should return start of hour', () => {
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'hour' })
+      expect(result.value).toContain('2024-03-15T14:00:00')
+    })
+
+    test('should return start of minute', () => {
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'minute' })
+      expect(result.value).toContain('2024-03-15T14:42:00')
+    })
+
+    test('should return start of second', () => {
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'second' })
+      expect(result.value).toContain('2024-03-15T14:42:12')
+    })
+
+    test('should return start of millisecond', () => {
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'millisecond' })
+      expect(result.value).toContain('2024-03-15T14:42:12.789')
+    })
+  })
+
+
+  describe('week calculation', () => {
+    test('should return start of week (Monday)', () => {
+      // 2024-03-15 is a Friday (day 5), so start of week should be Monday (2024-03-11)
+      const result = startOf('2024-03-15T14:42:12.789Z', { unit: 'week' })
+      const resultDate = new Date(result.value as unknown as string)
+      expect(resultDate.getDay()).toBe(1) // Monday
+    })
+
+    test('should return start of week for Sunday', () => {
+      // 2024-03-17 is a Sunday (day 7), so start of week should be Monday (2024-03-11)
+      const result = startOf('2024-03-17T14:42:12.789Z', { unit: 'week' })
+      const resultDate = new Date(result.value as unknown as string)
+      expect(resultDate.getDay()).toBe(1) // Monday
+    })
+
+    test('should return start of week for Monday', () => {
+      // 2024-03-11 is a Monday (day 1), so start of week should be itself
+      const result = startOf('2024-03-11T14:42:12.789Z', { unit: 'week' })
+      const resultDate = new Date(result.value as unknown as string)
+      expect(resultDate.getDay()).toBe(1) // Monday
+      expect(resultDate.toISOString()).toContain('2024-03-11')
+    })
+  })
+
+
+  describe('edge cases', () => {
+    test('should handle start of year for January 1st', () => {
+      const result = startOf('2024-01-01T00:00:00Z', { unit: 'year' }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toBe('2024-01-01T00:00:00Z')
+    })
+
+    test('should handle start of month for first day', () => {
+      const result = startOf('2024-03-01T00:00:00Z', { unit: 'month' }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toBe('2024-03-01T00:00:00Z')
+    })
+
+    test('should handle start of day at midnight', () => {
+      const result = startOf('2024-03-15T00:00:00Z', { unit: 'day' }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toBe('2024-03-15T00:00:00Z')
+    })
+
+    test('should handle start of hour at 00:00', () => {
+      const result = startOf('2024-03-15T14:00:00Z', { unit: 'hour' })
+      expect(result.value).toContain('2024-03-15T14:00:00')
+    })
+  })
+})

packages/time/src/date/withDateOperation.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from 'vitest'
+import { Temporal } from '@js-temporal/polyfill'
+import { withDateOperation } from './withDateOperation'
+
+describe('withDateOperation', () => {
+  const mockOperation = withDateOperation((zdt) => zdt)
+
+  describe('timezone handling', () => {
+    test('should use default timezone when not provided', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' })
+      expect(result.options.timeZone).toBeDefined()
+      expect(typeof result.options.timeZone).toBe('string')
+    })
+
+    test('should use custom timezone', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'Asia/Tokyo',
+      })
+      expect(result.options.timeZone).toBe('Asia/Tokyo')
+    })
+
+    test('should return timezone in options', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'Europe/London',
+      })
+      expect(result.options.timeZone).toBe('Europe/London')
+    })
+  })
+
+  describe('calendar handling', () => {
+    test('should use default calendar when not provided', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' })
+      expect(result.options.calendar).toBeDefined()
+      expect(typeof result.options.calendar).toBe('string')
+    })
+
+    test('should use custom calendar', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        calendar: 'japanese',
+      })
+      expect(result.options.calendar).toBe('japanese')
+    })
+
+    test('should return calendar in options', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        calendar: 'islamic',
+      })
+      expect(result.options.calendar).toBe('islamic')
+    })
+  })
+
+  describe('conversion methods', () => {
+    test('should have asDate method', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'UTC',
+      })
+      const date = result.asDate()
+      expect(date).toBeInstanceOf(Date)
+      expect(date.toISOString()).toContain('2024-03-15')
+    })
+
+    test('should have asEpoch method', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'UTC',
+      })
+      const epoch = result.asEpoch()
+      expect(typeof epoch).toBe('number')
+      expect(new Date(epoch).toISOString()).toContain('2024-03-15')
+    })
+
+    test('should have asString method', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'UTC',
+      })
+      const str = result.asString()
+      expect(typeof str).toBe('string')
+      expect(str).toContain('2024-03-15')
+    })
+
+    test('should have asLong method', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'America/New_York',
+        calendar: 'gregory',
+      })
+      const long = result.asLong()
+      expect(typeof long).toBe('string')
+      expect(long).toContain('2024-03-15')
+      expect(long).toContain('[America/New_York]')
+      expect(long).toContain('[u-ca=gregory]')
+    })
+
+    test('should have asZonedDateTime method', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'UTC',
+      })
+      const zdt = result.asZonedDateTime()
+      expect(zdt).toBeInstanceOf(Temporal.ZonedDateTime)
+      expect(zdt.toInstant().toString()).toContain('2024-03-15')
+    })
+  })
+
+  describe('result properties', () => {
+    test('should have value property as string', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'UTC',
+      })
+      expect(typeof result.value).toBe('string')
+      expect(result.value).toContain('2024-03-15')
+    })
+
+    test('should have options property', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' })
+      expect(result.options).toHaveProperty('timeZone')
+      expect(result.options).toHaveProperty('calendar')
+      expect(typeof result.options.timeZone).toBe('string')
+      expect(typeof result.options.calendar).toBe('string')
+    })
+
+    test('should have timeZone property', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'Asia/Tokyo',
+      })
+      expect(result.timeZone).toBe('Asia/Tokyo')
+    })
+
+    test('should have calendar property', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        calendar: 'japanese',
+      })
+      expect(result.calendar).toBe('japanese')
+    })
+
+    test('should support destructuring', () => {
+      const result = mockOperation('2024-03-15T14:42:12.789Z', { unit: 'test' }, {
+        timeZone: 'UTC',
+        calendar: 'gregory',
+      })
+      const { value, timeZone, calendar } = result
+      expect(typeof value).toBe('string')
+      expect(timeZone).toBe('UTC')
+      expect(calendar).toBe('gregory')
+    })
+  })
+
+  describe('operation execution', () => {
+    test('should execute the provided operation function', () => {
+      const addDayOperation = withDateOperation<{ days: number }>((zdt, { days }) => {
+        return zdt.add({ days })
+      })
+      const result = addDayOperation('2024-03-15T00:00:00Z', { days: 1 }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toBe('2024-03-16T00:00:00Z')
+    })
+
+    test('should pass args to the operation function', () => {
+      const customOperation = withDateOperation<{ multiplier: number }>((zdt, { multiplier }) => {
+        const days = zdt.day * multiplier
+        return zdt.with({ day: days })
+      })
+      const result = customOperation('2024-03-15T00:00:00Z', { multiplier: 2 }, {
+        timeZone: 'UTC',
+      })
+      expect(result.value).toContain('2024-03-30')
+    })
+  })
+})