1 | import type { ContextOptions, DateArg, Interval } from "./types.js";
|
2 | /**
|
3 | * The {@link clamp} function options.
|
4 | */
|
5 | export 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 | */
|
13 | export 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 | */
|
58 | export 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>;
|