diff options
Diffstat (limited to 'date-fns/src/getWeek/index.ts')
-rw-r--r-- | date-fns/src/getWeek/index.ts | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/date-fns/src/getWeek/index.ts b/date-fns/src/getWeek/index.ts new file mode 100644 index 0000000..af13a84 --- /dev/null +++ b/date-fns/src/getWeek/index.ts @@ -0,0 +1,64 @@ +import startOfWeek from '../startOfWeek/index' +import startOfWeekYear from '../startOfWeekYear/index' +import toDate from '../toDate/index' +import requiredArgs from '../_lib/requiredArgs/index' +import { LocaleOptions, WeekStartOptions, FirstWeekContainsDateOptions } from '../types' + +const MILLISECONDS_IN_WEEK = 604800000 + +/** + * @name getWeek + * @category Week Helpers + * @summary Get the local week index of the given date. + * + * @description + * Get the local week index of the given date. + * The exact calculation depends on the values of + * `options.weekStartsOn` (which is the index of the first day of the week) + * and `options.firstWeekContainsDate` (which is the day of January, which is always in + * the first week of the week-numbering year) + * + * Week numbering: https://en.wikipedia.org/wiki/Week#Week_numbering + * + * ### v2.0.0 breaking changes: + * + * - [Changes that are common for the whole library](https://github.com/date-fns/date-fns/blob/master/docs/upgradeGuide.md#Common-Changes). + * + * @param {Date|Number} date - the given date + * @param {Object} [options] - an object with options. + * @param {Locale} [options.locale=defaultLocale] - the locale object. See [Locale]{@link https://date-fns.org/docs/Locale} + * @param {0|1|2|3|4|5|6} [options.weekStartsOn=0] - the index of the first day of the week (0 - Sunday) + * @param {1|2|3|4|5|6|7} [options.firstWeekContainsDate=1] - the day of January, which is always in the first week of the year + * @returns {Number} the week + * @throws {TypeError} 1 argument required + * @throws {RangeError} `options.weekStartsOn` must be between 0 and 6 + * @throws {RangeError} `options.firstWeekContainsDate` must be between 1 and 7 + * + * @example + * // Which week of the local week numbering year is 2 January 2005 with default options? + * const result = getISOWeek(new Date(2005, 0, 2)) + * //=> 2 + * + * // Which week of the local week numbering year is 2 January 2005, + * // if Monday is the first day of the week, + * // and the first week of the year always contains 4 January? + * const result = getISOWeek(new Date(2005, 0, 2), { + * weekStartsOn: 1, + * firstWeekContainsDate: 4 + * }) + * //=> 53 + */ + +export default function getWeek(dirtyDate: Date | number, options?: LocaleOptions & WeekStartOptions & FirstWeekContainsDateOptions): number { + requiredArgs(1, arguments) + + const date = toDate(dirtyDate) + const diff = + startOfWeek(date, options).getTime() - + startOfWeekYear(date, options).getTime() + + // Round the number of days to the nearest integer + // because the number of milliseconds in a week is not constant + // (e.g. it's different in the week of the daylight saving time clock shift) + return Math.round(diff / MILLISECONDS_IN_WEEK) + 1 +} |