From ae9534611cfc3a57ff6876f290a2272f0a028eea Mon Sep 17 00:00:00 2001 From: Liam Tait Date: Fri, 4 Jun 2021 16:34:39 +1200 Subject: [PATCH 1/5] Add clamp function --- src/clamp/index.ts | 46 ++++++++++++++++++++++++++++++++++++++++++++++ src/clamp/test.ts | 43 +++++++++++++++++++++++++++++++++++++++++++ src/index.js | 1 + 3 files changed, 90 insertions(+) create mode 100644 src/clamp/index.ts create mode 100644 src/clamp/test.ts diff --git a/src/clamp/index.ts b/src/clamp/index.ts new file mode 100644 index 0000000000..dcc3cc36b6 --- /dev/null +++ b/src/clamp/index.ts @@ -0,0 +1,46 @@ +import max from '../max' +import min from '../min' +import toDate from '../toDate' +import requiredArgs from '../_lib/requiredArgs/index' + +/** + * @name clamp + * @category Interval Helpers + * @summary Return the date bounded by a start and end date + * + * @description + * Clamps a date to a lower bound with start and upper bound with end. + * When date is less than start, start is returned + * When date is greater than end, end is returned + * Otherwise the date is returned + * + * + * Bounds the date + * + * @example + * ```javascript + * var interval = { + * start: new Date(2020, 01, 01), + * end: new Date(2020, 05, 03) + * } + * var date = new Date(2020, 06, 04) + * var clampedDate = clamp(date, interval) + * ``` + * + * @param {Date | Number} date the date to be bounded + * @param {Interval} interval the interval to bound to + * @returns {Date} the Date value bounded by the min and max date + * @throws {TypeError} 2 arguments required + * @throws {RangeError} The start of an interval cannot be after it's end + */ +export default function clamp( + dirtyDate: Date | number, + { start, end }: Interval +): Date { + requiredArgs(2, arguments) + const date = toDate(dirtyDate) + const minDate = toDate(start) + const maxDate = toDate(end) + + return min([max([date, minDate]), maxDate]) +} diff --git a/src/clamp/test.ts b/src/clamp/test.ts new file mode 100644 index 0000000000..66376c1bb4 --- /dev/null +++ b/src/clamp/test.ts @@ -0,0 +1,43 @@ +import assert from 'assert' +import clamp from '.' + +describe('clamp', () => { + it('accepts timestamps', () => { + const start = new Date(2000, 1, 1).getTime() + const date = new Date(2000, 1, 2).getTime() + const end = new Date(2000, 1, 3).getTime() + const result = clamp(date, { start, end }) + assert.deepStrictEqual(result, new Date(2000, 1, 2)) + }) + + it('returns the start date when the date is less than start', () => { + const start = new Date(2001, 1, 1) + const date = new Date(2000, 1, 1) + const end = new Date(2020, 1, 1) + const result = clamp(date, { start, end }) + assert.deepStrictEqual(result, new Date(2001, 1, 1)) + }) + + it('returns the end date when the date is greater than the end date', () => { + const start = new Date(2000, 1, 1) + const date = new Date(2003, 1, 1) + const end = new Date(2001, 1, 1) + const result = clamp(date, { start, end }) + assert.deepStrictEqual(result, new Date(2001, 1, 1)) + }) + + it('returns the date when the date is within the bound of start and end', () => { + const start = new Date(2000, 1, 1) + const date = new Date(2001, 1, 1) + const end = new Date(2003, 1, 1) + const result = clamp(date, { start, end }) + assert.deepStrictEqual(result, new Date(2001, 1, 1)) + }) + + it('throws TypeError exception if passed less than 2 arguments', () => { + // @ts-expect-error + assert.throws(clamp.bind(null), TypeError) + // @ts-expect-error + assert.throws(clamp.bind(null, 1), TypeError) + }) +}) diff --git a/src/index.js b/src/index.js index 45095f8961..bbf7fb1c4f 100644 --- a/src/index.js +++ b/src/index.js @@ -13,6 +13,7 @@ export { default as addSeconds } from './addSeconds/index' export { default as addWeeks } from './addWeeks/index' export { default as addYears } from './addYears/index' export { default as areIntervalsOverlapping } from './areIntervalsOverlapping/index' +export { default as clamp } from './clamp/index' export { default as closestIndexTo } from './closestIndexTo/index' export { default as closestTo } from './closestTo/index' export { default as compareAsc } from './compareAsc/index' From f9b0fd54b4c728e1bc603936438b27bc1f31b701 Mon Sep 17 00:00:00 2001 From: liam-tait Date: Sat, 19 Jun 2021 16:57:02 +1200 Subject: [PATCH 2/5] Use const instead of var for clamp example --- src/clamp/index.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/clamp/index.ts b/src/clamp/index.ts index dcc3cc36b6..e4a868d9a4 100644 --- a/src/clamp/index.ts +++ b/src/clamp/index.ts @@ -19,12 +19,12 @@ import requiredArgs from '../_lib/requiredArgs/index' * * @example * ```javascript - * var interval = { + * const interval = { * start: new Date(2020, 01, 01), * end: new Date(2020, 05, 03) * } - * var date = new Date(2020, 06, 04) - * var clampedDate = clamp(date, interval) + * const date = new Date(2020, 06, 04) + * const clampedDate = clamp(date, interval) * ``` * * @param {Date | Number} date the date to be bounded From aa45c467d303b25277008d3c7180b484050ea9d8 Mon Sep 17 00:00:00 2001 From: liam-tait Date: Sat, 19 Jun 2021 17:14:06 +1200 Subject: [PATCH 3/5] Use example convention for clamp --- src/clamp/index.ts | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/clamp/index.ts b/src/clamp/index.ts index e4a868d9a4..c2f357a9b7 100644 --- a/src/clamp/index.ts +++ b/src/clamp/index.ts @@ -18,14 +18,12 @@ import requiredArgs from '../_lib/requiredArgs/index' * Bounds the date * * @example - * ```javascript - * const interval = { - * start: new Date(2020, 01, 01), - * end: new Date(2020, 05, 03) - * } - * const date = new Date(2020, 06, 04) - * const clampedDate = clamp(date, interval) - * ``` + * // What is Mar, 21, 2021 bounded to an interval starting at Mar, 22, 2021 and ending at Apr, 01, 2021 + * const result = clamp(new Date(2021, 2, 21), { + * start: new Date(2021, 2, 22), + * end: new Date(2021, 3, 1), + * }) + * //=> Mon Mar 22 2021 00:00:00 * * @param {Date | Number} date the date to be bounded * @param {Interval} interval the interval to bound to From d83b5a3e389f2c95d397431e0c7ce1714a2e588a Mon Sep 17 00:00:00 2001 From: Tetiana Date: Sat, 19 Jun 2021 21:54:12 +0100 Subject: [PATCH 4/5] Add minor changes to docs --- src/clamp/index.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/clamp/index.ts b/src/clamp/index.ts index c2f357a9b7..f847d19a49 100644 --- a/src/clamp/index.ts +++ b/src/clamp/index.ts @@ -25,8 +25,8 @@ import requiredArgs from '../_lib/requiredArgs/index' * }) * //=> Mon Mar 22 2021 00:00:00 * - * @param {Date | Number} date the date to be bounded - * @param {Interval} interval the interval to bound to + * @param {Date | Number} date - date the date to be bounded + * @param {Interval} interval - the interval to bound to * @returns {Date} the Date value bounded by the min and max date * @throws {TypeError} 2 arguments required * @throws {RangeError} The start of an interval cannot be after it's end From 9d9dfc423d22b15c97eab6b4e9f37a5f17478d07 Mon Sep 17 00:00:00 2001 From: Sasha Koss Date: Fri, 23 Jul 2021 13:30:34 +0800 Subject: [PATCH 5/5] Fix clamp function --- src/clamp/index.ts | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/src/clamp/index.ts b/src/clamp/index.ts index f847d19a49..dec410b8fc 100644 --- a/src/clamp/index.ts +++ b/src/clamp/index.ts @@ -1,44 +1,37 @@ import max from '../max' import min from '../min' -import toDate from '../toDate' import requiredArgs from '../_lib/requiredArgs/index' /** * @name clamp * @category Interval Helpers - * @summary Return the date bounded by a start and end date + * @summary Return a date bounded by the start and the end of the given interval * * @description - * Clamps a date to a lower bound with start and upper bound with end. - * When date is less than start, start is returned - * When date is greater than end, end is returned - * Otherwise the date is returned + * Clamps a date to the lower bound with the start of the interval and the upper + * bound with the end of the interval. * - * - * Bounds the date + * - When the date is less than the start of the interval, the start is returned. + * - When the date is greater than the end of the interval, the end is returned. + * - Otherwise the date is returned. * * @example - * // What is Mar, 21, 2021 bounded to an interval starting at Mar, 22, 2021 and ending at Apr, 01, 2021 + * // What is Mar, 21, 2021 bounded to an interval starting at Mar, 22, 2021 and ending at Apr, 01, 2021 * const result = clamp(new Date(2021, 2, 21), { * start: new Date(2021, 2, 22), * end: new Date(2021, 3, 1), * }) * //=> Mon Mar 22 2021 00:00:00 * - * @param {Date | Number} date - date the date to be bounded + * @param {Date | Number} date - the date to be bounded * @param {Interval} interval - the interval to bound to - * @returns {Date} the Date value bounded by the min and max date + * @returns {Date} the date bounded by the start and the end of the interval * @throws {TypeError} 2 arguments required - * @throws {RangeError} The start of an interval cannot be after it's end */ export default function clamp( - dirtyDate: Date | number, + date: Date | number, { start, end }: Interval ): Date { requiredArgs(2, arguments) - const date = toDate(dirtyDate) - const minDate = toDate(start) - const maxDate = toDate(end) - - return min([max([date, minDate]), maxDate]) + return min([max([date, start]), end]) }