feat(query): add weekday query methods 📆

- Add lastWeekday helper function to get last weekday occurrence in month
- Add nearestWeekday helper function to move weekends to nearest weekday
- Add nextWeekday helper function to get next weekday occurrence
- Add nthWeekday helper function to get nth weekday occurrence in month
- Add prevWeekday helper function to get previous weekday occurrence
- Add weekday query methods to Daytime class
- Add weekday query method type definitions to IDaytime interface
- Add comprehensive tests for all weekday query methods
- Fix arrow function formatting in Main test file

Author: NeaByteLab

src/Daytime.ts

@@ -469,6 +469,25 @@ export class Daytime implements Types.IDaytime {
     return this.get('month')
   }
 
+  /**
+   * Gets the last occurrence of a weekday in the month.
+   * @param weekday - The weekday (0-6, Sunday is 0)
+   * @returns A new Daytime instance representing the last occurrence of the weekday
+   */
+  lastWeekday(weekday: number): Types.IDaytime {
+    const newDate = Helpers.lastWeekday(this.date, weekday)
+    return new Daytime(newDate)
+  }
+
+  /**
+   * Gets the nearest weekday to this date (moves weekends to nearest weekday).
+   * @returns A new Daytime instance representing the nearest weekday
+   */
+  nearestWeekday(): Types.IDaytime {
+    const newDate = Helpers.nearestWeekday(this.date)
+    return new Daytime(newDate)
+  }
+
   /**
    * Gets the next business day.
    * @returns A new Daytime instance representing the next business day
@@ -478,6 +497,27 @@ export class Daytime implements Types.IDaytime {
     return new Daytime(newDate)
   }
 
+  /**
+   * Gets the next occurrence of a weekday.
+   * @param weekday - The weekday (0-6, Sunday is 0)
+   * @returns A new Daytime instance representing the next occurrence of the weekday
+   */
+  nextWeekday(weekday: number): Types.IDaytime {
+    const newDate = Helpers.nextWeekday(this.date, weekday)
+    return new Daytime(newDate)
+  }
+
+  /**
+   * Gets the nth occurrence of a weekday in the month.
+   * @param n - The occurrence number (1-based)
+   * @param weekday - The weekday (0-6, Sunday is 0)
+   * @returns A new Daytime instance representing the nth occurrence of the weekday
+   */
+  nthWeekday(n: number, weekday: number): Types.IDaytime {
+    const newDate = Helpers.nthWeekday(this.date, n, weekday)
+    return new Daytime(newDate)
+  }
+
   /**
    * Gets the previous business day.
    * @returns A new Daytime instance representing the previous business day
@@ -487,6 +527,16 @@ export class Daytime implements Types.IDaytime {
     return new Daytime(newDate)
   }
 
+  /**
+   * Gets the previous occurrence of a weekday.
+   * @param weekday - The weekday (0-6, Sunday is 0)
+   * @returns A new Daytime instance representing the previous occurrence of the weekday
+   */
+  prevWeekday(weekday: number): Types.IDaytime {
+    const newDate = Helpers.prevWeekday(this.date, weekday)
+    return new Daytime(newDate)
+  }
+
   /**
    * Gets the previous business day.
    * @returns A new Daytime instance representing the previous business day

src/Types.ts

@@ -134,10 +134,20 @@ export interface IDaytime {
   minute(): number
   /** Gets the month */
   month(): number
+  /** Gets the last occurrence of a weekday in the month */
+  lastWeekday(weekday: number): IDaytime
+  /** Gets the nearest weekday to this date */
+  nearestWeekday(): IDaytime
   /** Gets the next business day */
   nextBusinessDay(): IDaytime
+  /** Gets the next occurrence of a weekday */
+  nextWeekday(weekday: number): IDaytime
+  /** Gets the nth occurrence of a weekday in the month */
+  nthWeekday(n: number, weekday: number): IDaytime
   /** Gets the previous business day */
   prevBusinessDay(): IDaytime
+  /** Gets the previous occurrence of a weekday */
+  prevWeekday(weekday: number): IDaytime
   /** Gets the previous business day */
   previousBusinessDay(): IDaytime
   /** Gets the quarter */

src/helpers/Query.ts

@@ -61,6 +61,95 @@ export function daysInYear(date: Date): number {
   return Helpers.isLeapYear(date) ? 366 : 365
 }
 
+/**
+ * Gets the last occurrence of a weekday in the month for the given date.
+ * @param date - The date to get last weekday for
+ * @param weekday - The weekday (0-6, Sunday is 0)
+ * @returns A new Date representing the last occurrence of the weekday in the month
+ */
+export function lastWeekday(date: Date, weekday: number): Date {
+  const lastDay = Helpers.endOfMonth(date)
+  const lastDayOfWeek = lastDay.getDay()
+  let daysToSubtract = (lastDayOfWeek - weekday + 7) % 7
+  if (daysToSubtract === 0 && lastDayOfWeek !== weekday) {
+    daysToSubtract = 7
+  }
+  const result = Helpers.cloneDate(lastDay)
+  result.setDate(result.getDate() - daysToSubtract)
+  return result
+}
+
+/**
+ * Gets the nearest weekday to the given date (moves weekends to nearest weekday).
+ * @param date - The date to get nearest weekday for
+ * @returns A new Date representing the nearest weekday
+ */
+export function nearestWeekday(date: Date): Date {
+  const dayOfWeek = date.getDay()
+  const result = Helpers.cloneDate(date)
+  if (dayOfWeek === 0) {
+    result.setDate(result.getDate() + 1)
+  } else if (dayOfWeek === 6) {
+    result.setDate(result.getDate() - 1)
+  }
+  return result
+}
+
+/**
+ * Gets the next occurrence of a weekday from the given date.
+ * @param date - The date to get next weekday for
+ * @param weekday - The weekday (0-6, Sunday is 0)
+ * @returns A new Date representing the next occurrence of the weekday
+ */
+export function nextWeekday(date: Date, weekday: number): Date {
+  const currentDayOfWeek = date.getDay()
+  let daysToAdd = (weekday - currentDayOfWeek + 7) % 7
+  if (daysToAdd === 0) {
+    daysToAdd = 7
+  }
+  const result = Helpers.cloneDate(date)
+  result.setDate(result.getDate() + daysToAdd)
+  return result
+}
+
+/**
+ * Gets the nth occurrence of a weekday in the month for the given date.
+ * @param date - The date to get nth weekday for
+ * @param n - The occurrence number (1-based)
+ * @param weekday - The weekday (0-6, Sunday is 0)
+ * @returns A new Date representing the nth occurrence of the weekday in the month
+ */
+export function nthWeekday(date: Date, n: number, weekday: number): Date {
+  const firstDayOfMonth = Helpers.startOfMonth(date)
+  const lastDayOfMonth = Helpers.endOfMonth(date)
+  const firstDayOfWeek = firstDayOfMonth.getDay()
+  const daysInMonth = lastDayOfMonth.getDate()
+  const daysToFirst = (weekday - firstDayOfWeek + 7) % 7
+  const maxOccurrences = Math.floor((daysInMonth - daysToFirst - 1) / 7) + 1
+  const targetN = Math.min(n, maxOccurrences)
+  const daysToAdd = daysToFirst + (targetN - 1) * 7
+  const result = Helpers.cloneDate(firstDayOfMonth)
+  result.setDate(result.getDate() + daysToAdd)
+  return result
+}
+
+/**
+ * Gets the previous occurrence of a weekday from the given date.
+ * @param date - The date to get previous weekday for
+ * @param weekday - The weekday (0-6, Sunday is 0)
+ * @returns A new Date representing the previous occurrence of the weekday
+ */
+export function prevWeekday(date: Date, weekday: number): Date {
+  const currentDayOfWeek = date.getDay()
+  let daysToSubtract = (currentDayOfWeek - weekday + 7) % 7
+  if (daysToSubtract === 0) {
+    daysToSubtract = 7
+  }
+  const result = Helpers.cloneDate(date)
+  result.setDate(result.getDate() - daysToSubtract)
+  return result
+}
+
 /**
  * Gets the week number within the month for the given date.
  * @param date - The date to get week of month for

tests/Daytime.test.ts

@@ -592,3 +592,117 @@ Deno.test('Daytime: all query convenience methods should return booleans', () =>
   expect(typeof daytime(now).isSameYear(future)).toBe('boolean')
   expect(typeof daytime(now).isSameQuarter(future)).toBe('boolean')
 })
+
+Deno.test('Daytime: lastWeekday - should return last weekday of month', () => {
+  const date = daytime('2026-01-15')
+  const lastMonday = date.lastWeekday(1)
+  expect(lastMonday.dayOfWeek()).toEqual(1)
+  expect(lastMonday.month()).toEqual(1)
+  expect(lastMonday.toDate().getTime()).toBeGreaterThanOrEqual(date.toDate().getTime())
+})
+
+Deno.test('Daytime: lastWeekday - should work with chaining', () => {
+  const date = daytime('2026-01-15')
+  const result = date.lastWeekday(5).add(1, 'day')
+  expect(typeof result.toDate()).toEqual('object')
+})
+
+Deno.test('Daytime: nearestWeekday - should move weekends to nearest weekday', () => {
+  const saturday = daytime('2026-01-03')
+  const sunday = daytime('2026-01-04')
+  expect(saturday.nearestWeekday().dayOfWeek()).toBeLessThan(6)
+  expect(sunday.nearestWeekday().dayOfWeek()).toBeGreaterThan(0)
+})
+
+Deno.test('Daytime: nearestWeekday - should keep weekdays unchanged', () => {
+  const monday = daytime('2026-01-05')
+  const tuesday = daytime('2026-01-06')
+  expect(monday.nearestWeekday().dayOfWeek()).toEqual(1)
+  expect(tuesday.nearestWeekday().dayOfWeek()).toEqual(2)
+})
+
+Deno.test('Daytime: nearestWeekday - should work with chaining', () => {
+  const date = daytime('2026-01-03')
+  const nearest = date.nearestWeekday()
+  expect(nearest.dayOfWeek()).toBeLessThan(6)
+  const result = nearest.add(1, 'day')
+  expect(typeof result.toDate()).toEqual('object')
+})
+
+Deno.test('Daytime: nextWeekday - should find next occurrence of weekday', () => {
+  const date = daytime('2026-01-05')
+  const nextMonday = date.nextWeekday(1)
+  expect(nextMonday.dayOfWeek()).toEqual(1)
+  expect(nextMonday.toDate().getTime()).toBeGreaterThan(date.toDate().getTime())
+})
+
+Deno.test('Daytime: nextWeekday - should work for all weekdays', () => {
+  const date = daytime('2026-01-15')
+  for (let weekday = 0; weekday <= 6; weekday++) {
+    const result = date.nextWeekday(weekday)
+    expect(result.dayOfWeek()).toEqual(weekday)
+    expect(result.toDate().getTime()).toBeGreaterThan(date.toDate().getTime())
+  }
+})
+
+Deno.test('Daytime: nextWeekday - should work with chaining', () => {
+  const date = daytime('2026-01-15')
+  const result = date.nextWeekday(1).add(1, 'day')
+  expect(typeof result.toDate()).toEqual('object')
+})
+
+Deno.test('Daytime: nthWeekday - should find nth occurrence in month', () => {
+  const date = daytime('2026-01-15')
+  const firstMonday = date.nthWeekday(1, 1)
+  expect(firstMonday.dayOfWeek()).toEqual(1)
+  expect(firstMonday.month()).toEqual(1)
+  expect(firstMonday.day()).toEqual(5)
+})
+
+Deno.test('Daytime: nthWeekday - should handle different occurrences', () => {
+  const date = daytime('2026-01-15')
+  const secondFriday = date.nthWeekday(2, 5)
+  const thirdWednesday = date.nthWeekday(3, 3)
+  expect(secondFriday.dayOfWeek()).toEqual(5)
+  expect(thirdWednesday.dayOfWeek()).toEqual(3)
+  expect(thirdWednesday.toDate().getTime()).toBeGreaterThan(secondFriday.toDate().getTime())
+})
+
+Deno.test('Daytime: nthWeekday - should work with chaining', () => {
+  const date = daytime('2026-01-15')
+  const result = date.nthWeekday(1, 1).add(1, 'week')
+  expect(typeof result.toDate()).toEqual('object')
+})
+
+Deno.test('Daytime: prevWeekday - should find previous occurrence of weekday', () => {
+  const date = daytime('2026-01-15')
+  const prevMonday = date.prevWeekday(1)
+  expect(prevMonday.dayOfWeek()).toEqual(1)
+  expect(prevMonday.toDate().getTime()).toBeLessThan(date.toDate().getTime())
+})
+
+Deno.test('Daytime: prevWeekday - should work for all weekdays', () => {
+  const date = daytime('2026-01-15')
+  for (let weekday = 0; weekday <= 6; weekday++) {
+    const result = date.prevWeekday(weekday)
+    expect(result.dayOfWeek()).toEqual(weekday)
+    expect(result.toDate().getTime()).toBeLessThan(date.toDate().getTime())
+  }
+})
+
+Deno.test('Daytime: prevWeekday - should work with chaining', () => {
+  const date = daytime('2026-01-15')
+  const result = date.prevWeekday(5).subtract(1, 'day')
+  expect(typeof result.toDate()).toEqual('object')
+})
+
+Deno.test('Daytime: weekday methods should maintain immutability', () => {
+  const date = daytime('2026-01-15')
+  const originalTime = date.toDate().getTime()
+  date.lastWeekday(1)
+  date.nearestWeekday()
+  date.nextWeekday(1)
+  date.nthWeekday(1, 1)
+  date.prevWeekday(5)
+  expect(date.toDate().getTime()).toEqual(originalTime)
+})

tests/Main.test.ts

@@ -134,7 +134,7 @@ Deno.test('Utility: valueOf - should support sorting', () => {
     new Date('2026-01-15T12:00:00Z'),
     new Date('2026-01-16T12:00:00Z')
   ]
-  const sorted = dates.map(d => daytime(d)).sort((a, b) => a.valueOf() - b.valueOf())
+  const sorted = dates.map((d) => daytime(d)).sort((a, b) => a.valueOf() - b.valueOf())
   expect(sorted[0]?.valueOf()).toEqual(dates[1]?.getTime())
   expect(sorted[1]?.valueOf()).toEqual(dates[2]?.getTime())
   expect(sorted[2]?.valueOf()).toEqual(dates[0]?.getTime())