UNPKG

2.32 kBTypeScriptView Raw
1import type { ContextOptions, DateArg, Interval } from "./types.js";
2/**
3 * The {@link clamp} function options.
4 */
5export interface ClampOptions<ContextDate extends Date = Date>
6 extends ContextOptions<ContextDate> {}
7/**
8 * The {@link clamp} function result type. It resolves the proper data type.
9 * It uses the first argument date object type, starting from the date argument,
10 * then the start interval date, and finally the end interval date. If
11 * a context function is passed, it uses the context function return type.
12 */
13export type ClampResult<
14 DateType extends DateArg<Date>,
15 IntervalType extends Interval,
16 Options extends ClampOptions | undefined,
17> =
18 Options extends ClampOptions<infer DateType extends Date>
19 ? DateType
20 : DateType extends Date
21 ? DateType
22 : IntervalType["start"] extends Date
23 ? IntervalType["start"]
24 : IntervalType["end"] extends Date
25 ? IntervalType["end"]
26 : Date;
27/**
28 * @name clamp
29 * @category Interval Helpers
30 * @summary Return a date bounded by the start and the end of the given interval.
31 *
32 * @description
33 * Clamps a date to the lower bound with the start of the interval and the upper
34 * bound with the end of the interval.
35 *
36 * - When the date is less than the start of the interval, the start is returned.
37 * - When the date is greater than the end of the interval, the end is returned.
38 * - Otherwise the date is returned.
39 *
40 * @typeParam DateType - Date argument type.
41 * @typeParam IntervalType - Interval argument type.
42 * @typeParam Options - Options type.
43 *
44 * @param date - The date to be bounded
45 * @param interval - The interval to bound to
46 * @param options - An object with options
47 *
48 * @returns The date bounded by the start and the end of the interval
49 *
50 * @example
51 * // What is Mar 21, 2021 bounded to an interval starting at Mar 22, 2021 and ending at Apr 01, 2021
52 * const result = clamp(new Date(2021, 2, 21), {
53 * start: new Date(2021, 2, 22),
54 * end: new Date(2021, 3, 1),
55 * })
56 * //=> Mon Mar 22 2021 00:00:00
57 */
58export declare function clamp<
59 DateType extends DateArg<Date>,
60 IntervalType extends Interval,
61 Options extends ClampOptions | undefined = undefined,
62>(
63 date: DateType,
64 interval: IntervalType,
65 options?: Options,
66): ClampResult<DateType, IntervalType, Options>;