UNPKG

shelving

Version:

Toolkit for using data in JavaScript.

github.com/dhoulb/shelving

dhoulb/shelving

94 lines (93 loc) • 7.09 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
import type { AnyCaller } from "./function.js"; /** Values that can be converted to dates. */ export type PossibleDate = "now" | "today" | "tomorrow" | "yesterday" | Date | number | string; /** * Is a value a valid date? * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `false` */ export declare function isDate(value: unknown): value is Date; /** Assert that a value is a `Date` instance. */ export declare function assertDate(value: unknown, caller?: AnyCaller): asserts value is Date; /** * Convert an unknown value to a valid `Date` instance, or return `undefined` if it couldn't be converted. * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `null` * * @param value Any value that we want to parse as a valid date (defaults to `undefined`). * - `Date` instance returns unchanged (BUT if the date isn't valid, `undefined` is returned). * - `null` or `undefined` or `""` empty string returns `undefined` * - The string `"now"` returns the current date (e.g. `new Date()`). * - The string `"today"` returns the current date at midnight (e.g. `getMidnight()`). * - The string `"tomorrow"` returns tomorrow's date at midnight (e.g. `addDays(getMidnight(), 1)`). * - The string `"yesterday"` returns yesterday's date at midnight (e.g. `addDays(getMidnight(), 1)`). * - Date strings (e.g. `"2003-09-12"` or `"2003 feb 20:09"`) return the corresponding date (using the user's current locale). * - Time strings (e.g. `"18:32"` or `"23:59:59.999"`) return today's date at that time (using the user's current locale). * - Numbers are return the corresponding date (using `new Date(number)`, i.e. milliseconds since 01/01/1970). * - Anything else returns `undefined` * * @returns `Date` instance if the value could be converted to a valid date, and `null` if not. */ export declare function getDate(value: unknown): Date | undefined; /** Get a date representing this exact moment. */ export declare function getNow(): Date; /** Get a date representing midnight of the previous day. */ export declare function getYesterday(): Date; /** Get a date representing midnight of the current day. */ export declare function getToday(): Date; /** Get a date representing midnight of the next day. */ export declare function getTomorrow(): Date; /** Get a Date representing exactly midnight of the specified date. */ export declare function getMidnight(target?: PossibleDate, caller?: AnyCaller): Date; /** Get a Date representing midnight on Monday of the specified week. */ export declare function getMonday(target?: PossibleDate, caller?: AnyCaller): Date; /** Get a Date representing the first day of the specified month. */ export declare function getMonthStart(target?: PossibleDate, caller?: AnyCaller): Date; /** * Convert a possible date to a `Date` instance, or throw `RequiredError` if it couldn't be converted. * @param value Any value that we want to parse as a valid date (defaults to `"now"`). */ export declare function requireDate(value?: PossibleDate, caller?: AnyCaller): Date; /** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted. */ export declare function getTimestamp(value?: unknown): number | undefined; /** Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `RequiredError` if it couldn't be converted. */ export declare function requireTimestamp(value?: PossibleDate): number; /** Convert an unknown value to a local date string like "2015-09-12T18:30:00", or `undefined` if it couldn't be converted. */ export declare function getDateTimeString(value?: unknown): string | undefined; /** Convert a possible `Date` instance to a local YMD string like "2015-09-12T18:30:00", or throw `RequiredError` if it couldn't be converted. */ export declare function requireDateTimeString(value?: PossibleDate, caller?: AnyCaller): string; /** Convert an unknown value to a local date string like "2015-09-12", or `undefined` if it couldn't be converted. */ export declare function getDateString(value?: unknown): string | undefined; /** Convert a possible `Date` instance to a local date string like "2015-09-12", or throw `RequiredError` if it couldn't be converted. */ export declare function requireDateString(value?: PossibleDate, caller?: AnyCaller): string; /** Convert an unknown value to a local time string like "18:32:00", or `undefined` if it couldn't be converted. */ export declare function getTimeString(value?: unknown): string | undefined; /** Convert a possible `Date` instance to local time string like "18:32:00", or throw `RequiredError` if it couldn't be converted. */ export declare function requireTimeString(value?: PossibleDate, caller?: AnyCaller): string; /** List of day-of-week strings. */ export declare const DAYS: readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]; /** Type listing day-of-week strings. */ export type Day = (typeof DAYS)[number]; /** Convert a `Date` instance to a day-of-week string like "Monday" */ export declare function getDay(target?: PossibleDate): Day; /** * Return a new date that increase or decreases the month based on an input date. * - February 29th is a special cased and is _rounded down_ to February 28th on non-leap years. */ export declare function addYears(change: number, target?: PossibleDate, caller?: AnyCaller): Date; /** * Return a new date that increase or decreases the month based on an input date. * - Note that with Javascript "rollover" semantics, adding a month when we're on e.g. 31st of August would normally roll _past_ September and return 1st October. * - To avoid this we clamp the date to the end of the month if rollover happens. */ export declare function addMonths(change: number, target?: PossibleDate, caller?: AnyCaller): Date; /** Return a new date that increase or decreases the week based on an input date. */ export declare function addWeeks(change: number, target?: PossibleDate, caller?: AnyCaller): Date; /** Return a new date that increase or decreases the day based on an input date. */ export declare function addDays(change: number, target?: PossibleDate, caller?: AnyCaller): Date; /** Return a new date that increase or decreases the hour based on an input date. */ export declare function addHours(change: number, target?: PossibleDate, caller?: AnyCaller): Date; /** Return a new date that increase or decreases the minute based on an input date. */ export declare function addMinutes(change: number, target?: PossibleDate, caller?: AnyCaller): Date; /** Return a new date that increase or decreases the minute based on an input date. */ export declare function addSeconds(change: number, target?: PossibleDate, caller?: AnyCaller): Date; /** Return a new date that increase or decreases the minute based on an input date. */ export declare function addMilliseconds(change: number, target?: PossibleDate, caller?: AnyCaller): Date;