diff --git a/src/pages/concepts/dates-times.md b/src/pages/concepts/dates-times.md index 8219ecb9..8e33fe2d 100644 --- a/src/pages/concepts/dates-times.md +++ b/src/pages/concepts/dates-times.md @@ -2,7 +2,421 @@ ## Important Utilities -Coming soon... +### dateUtil +A utility that wraps a lot of helpful date related functionality. By default it's not timezone aware, but you can make it timezone aware by using the `DateUtilDecorator` provided by `@sprucelabs/calendar-utils`. + + +```ts +export interface DateUtil { + eventDaysOfWeek: { + sun: string; + mon: string; + tue: string; + wed: string; + thur: string; + fri: string; + sat: string; + }; + getStartOfDay(timestamp?: number): number; + getStartOfWeek(timestamp?: number): number; + getEndOfDay(timestamp?: number): number; + getEndOfWeek(timestamp: number): number; + getStartOfMonth(timestamp?: number): number; + getEndOfMonth(timestamp?: number): number; + addMinutes(startTimestamp: number, minutes: number): number; + addMilliseconds(startTimestamp: number, ms: number): number; + addDays(startTimestamp: number, days: number): number; + addWeeks(startTimestamp: number, weeks: number): number; + addMonths(timestamp: number, months: number): number; + addYears(timestamp: number, years: number): number; + getDurationMs(timestamp: number, endTimestamp: number): number; + getDurationMinutes(timestamp: number, endTimestamp: number): number; + getDurationDays(timestamp: number, endTimestamp: number): number; + getDayOfWeek(timestamp: number): DayOfWeek; + getDayOfWeekIndex(timestamp: number): number; + splitDate(timestamp: number): { + year: number; + month: number; + day: number; + hour: number; + minute: number; + }; + setTimeOfDay(timestamp: number, hours: number, minutes?: number, seconds?: number, milliseconds?: number): number; + getDateNDaysFromStartOfDay(days: number, timestamp?: number): number; + getDateNMonthsFromStartOfDay(count: number, timestamp?: number): number; + getDateNMonthsFromStartOfMonth(count: number, timestamp?: number): number; + date(date?: IDate): number; + /** + * Unit_______________Pattern___Results + * + * Era________________G..GGG____AD,BC + * + * ___________________GGGG______Anno Domini, Before Christ + * + * ___________________GGGGG_____A,B + * + * + * + * Calendar year_______y_________44, 1, 1900, 2017 + * + * ___________________yo________44th, 1st, 0th, 17th + * + * ___________________yy________44, 01, 00, 17 + * + * ___________________yyy_______044, 001, 1900, 2017 + * + * ___________________yyyy______0044, 0001, 1900, 2017 + * + * + * + * Local week_________Y_________44, 1, 1900, 2017 + * + * ___________________Yo________44th, 1st, 1900th, 2017th + * + * ___________________YY________44, 01, 00, 17 + * + * ___________________YYY_______044, 001, 1900, 2017 + * + * ___________________YYYY______0044, 0001, 1900, 2017 + * + * + * + * ISO week___________R_________-43, 0, 1, 1900, 2017 + * + * ___________________________RR________-43, 00, 01, 1900, 2017 + * + * __________________________RRR_______-043, 000, 001, 1900, 2017 + * + * _________________________RRRR______-0043, 0000, 0001, 1900, 2017 + * + * + * + * + * Extended year______u_________-43, 0, 1, 1900, 2017 + * + * ___________________uu________-43, 01, 1900, 2017 + * + * ___________________uuu_______-043, 001, 1900, 2017 + * + * ___________________uuuu______-0043, 0001, 1900, 2017 + * + * + * + * + * Quarter (pretty)_____Q_________1, 2, 3, 4 + * + * ___________________Qo________1st, 2nd, 3rd, 4th + * + * ___________________QQ________01, 02, 03, 04 + * + * ___________________QQQ_______Q1, Q2, Q3, Q4 + * + * ___________________QQQQ______1st quarter, 2nd quarter, ... + * + * ___________________QQQQQ_____1, 2, 3, 4 + * + * + * + * Quarter____________q_________1, 2, 3, 4 + * + * ___________________qo________1st, 2nd, 3rd, 4th + * + * ___________________qq________01, 02, 03, 04 + * + * ___________________qqq_______Q1, Q2, Q3, Q4 + * + * ___________________qqqq______1st quarter, 2nd quarter,... + * + * ___________________qqqqq_____1, 2, 3, 4 + * + * + * + * Month (pretty)______M_________1, 2, ..., 12 + * + * ___________________Mo________1st, 2nd, ..., 12th + * + * ___________________MM________01, 02, ..., 12 + * + * ___________________MMM_______Jan, Feb, ..., Dec + * + * ___________________MMMM______January, February, ..., December + * + * ___________________MMMMM_____J, F, ..., D + * + * + * + * Month______________L_________1, 2, ..., 12 + * + * ___________________Lo________1st, 2nd, ..., 12th + * + * ___________________LL________01, 02, ..., 12 + * + * ___________________LLL_______Jan, Feb, ..., Dec + * + * ___________________LLLL______January, February, ..., December + * + * ___________________LLLLL_____J, F, ..., D + * + * + * + * Local Week_________w_________1, 2, ..., 53 + * + * ___________________wo________1st, 2nd, ..., 53th + * + * ___________________ww________01, 02, ..., 53 + * + * + * + * ISO week of year_____I_________1, 2, ..., 53 + * + * ___________________Io________1st, 2nd, ..., 53th + * + * ___________________II________01, 02, ..., 53 + * + * + * + * Day of month_______d_________1, 2, ..., 31 + * + * ___________________do________1st, 2nd, ..., 31st + * + * ___________________dd________01, 02, ..., 31 + * + * + * + * Day of year________D_________1, 2, ..., 365, 366 + * + * ___________________Do________1st, 2nd, ..., 365th, 366th + * + * ___________________DD________01, 02, ..., 365, 366 + * + * ___________________DDD_______001, 002, ..., 365, 366 + * + * + * + * Day of week________E..EEE____Mon, Tue, Wed, ..., Sun + * + * ___________________EEEE______Monday, Tuesday, ..., Sunday + * + * ___________________EEEEE_____M, T, W, T, F, S, S + * + * ___________________EEEEEE____Mo, Tu, We, Th, Fr, Sa, Su + * + * + * + * ISO day of week_____i_________1, 2, 3, ..., 7 + * + * ___________________io________1st, 2nd, ..., 7th + * + * ___________________ii________01, 02, ..., 07 + * + * ___________________iii_______Mon, Tue, Wed, ..., Sun + * + * ___________________iiii______Monday, Tuesday, ..., Sunday + * + * ___________________iiiii_____M, T, W, T, F, S, S + * + * ___________________iiiiii____Mo, Tu, We, Th, Fr, Sa, Su + * + * + * + * Local day of week_____e_________2, 3, 4, ..., 1 + * + * ___________________eo________2nd, 3rd, ..., 1st + * + * ___________________ee________02, 03, ..., 01 + * + * ___________________eee_______Mon, Tue, Wed, ..., Sun + * + * ___________________eeee______Monday, Tuesday, ..., Sunday + * + * ___________________eeeee_____M, T, W, T, F, S, S + * + * ___________________eeeeee____Mo, Tu, We, Th, Fr, Sa, Su + * + * + * + * + * Day of week_________c_________2, 3, 4, ..., 1 + * + * ___________________co________2nd, 3rd, ..., 1st + * + * ___________________cc________02, 03, ..., 01 + * + * ___________________ccc_______Mon, Tue, Wed, ..., Sun + * + * ___________________cccc______Monday, Tuesday, ..., Sunday + * + * ___________________ccccc_____M, T, W, T, F, S, S + * + * ___________________cccccc____Mo, Tu, We, Th, Fr, Sa, Su + * + * + * + * AM,PM_____________a..aa_____AM, PM + * + * ___________________aaa_______am, pm + * + * ___________________aaaa______a.m., p.m. + * + * ___________________aaaaa_____a,p + * + * + * AM, PM, noon, mid_b..bb____AM, PM, noon, midnight + * + * _____________________bbb______am, pm, noon, midnight + * + * _____________________bbbb_____a.m.,_p.m.,_noon,_midnight + * + * _____________________bbbbb____a,_p,_n,_mi + * + * + * Flexible day period_B..BBB___at night, in the morning, ... + * + * _____________________BBBB_____at night, in the morning, ... + * + * _____________________BBBBB____at night, in the morning, ... + * + * + * + * Hour [1-12]_________h________1, 2, ..., 11, 12 + * + * ___________________ho_______1st, 2nd, ..., 11th, 12th + * + * ___________________hh_______01,_02,_...,_11,_12 + * + * + * + * Hour [0-23]______________H________0,_1,_2,_...,_23 + * + * __________________________Ho_______0th,_1st,_2nd,_...,_23rd + * + * __________________________HH_______00,_01,_02,_...,_23 + * + * + * + * Hour [0-11]______________K________1,_2,_...,_11, + * + * __________________________Ko_______1st,_2nd,_...,_11th,_0th + * + * __________________________KK_______01,_02,_...,_11,_00 + * + * + * + * Hour [1-24]______________k________24,_1,_2,_...,_23 + * + * __________________________ko_______24th,_1st,_2nd,_...,_23rd + * + * __________________________kk_______24,_01,_02,_...,_23 + * + * + * + * Minute___________________m__________0,_1,_...,_59 + * + * ___________________________mo_________0th,_1st,_...,_59th + * + * ___________________________mm_________00,_01,_...,_59 + * + * + * + * Second___________________s__________0,_1,_...,_59 + * + * ___________________________so_________0th,_1st,_...,_59th + * + * ___________________________ss_________00,_01,_...,_59 + * + * + * + * Fraction_of_second_______S__________0,_1,_..., + * + * ___________________________SS_________00,_01,_...,_99 + * + * ___________________________SSS________000,_001,_...,_999 + * + * + * + * Timezone_(ISO-8601_w/_Z)_X__________-08,_+0530,_Z + * + * ___________________________XX_________-0800,_+0530,_Z + * + * ___________________________XXX________-08:00,_+05:30,_Z + * + * ___________________________XXXX_______-0800,_+0530,_Z,_+123456 + * + * ___________________________XXXXX______-08:00,_+05:30,_Z,_+12:34:56 + * + * + * + * Timezone_(ISO-8601_w/o_Z_x__________-08,_+0530,_+00 + * + * ___________________________xx_________-0800,_+0530,_+0000 + * + * ___________________________xxx________-08:00,_+05:30,_+00:00 + * + * ___________________________xxxx_______-0800,_+0530,_+0000,_+123456 + * + * ___________________________xxxxx______-08:00,_+05:30,_+00:00,_+12:34:56 + * + * + * Timezone_(GMT)___________O...OOO____GMT-8,_GMT+5:30,_GMT+0 + * + * ___________________________OOOO_______GMT-08:00,_GMT+05:30,_GMT+00:00 + * + * + * Timezone_(specific_non-l_z...zzz____GMT-8,_GMT+5:30,_GMT+0 + * + * ___________________________zzzz_______GMT-08:00,_GMT+05:30,_GMT+00:00 + * + * + * Seconds_timestamp________t__________512969520 + * + * + * Milliseconds_timestamp___T__________512969520900 + * + * + * Long localized date______P__________04/29/1453 + * + * ___________________________PP_________Apr 29, 1453 + * + * ___________________________PPP________April 29th, 1453 + * + * ___________________________PPPP_______Friday,_April_29th,_1453 + * + * + * Long_localized_time______p__________12:00_AM + * + * ___________________________pp_________12:00:00_AM + * + * ___________________________ppp________12:00:00_AM_GMT+2 + * + * ___________________________pppp_______12:00:00_AM_GMT+02:00 + * + * + * + * Date & Time_______________Pp_________04/29/1453,_12:00_AM + * + * ___________________________PPpp_______Apr_29,_1453,_12:00:00_AM + * + * ___________________________PPPppp_____April_29th,_1453_at_... + * + * ___________________________PPPPpppp___Friday,_April_29th,_1453_at_... + * + */ + format(timestamp: number, format: string): string; + formatTime(timestamp: number): string; + formatDate(timestamp: number): string; + formatDateTime(timestamp: number): string; + add(timestamp: number, count: number, unit: DateUnit): any; + isSameDay(timestamp1: number, timestamp2: number): boolean; + getTotalDaysInMonth(year: number, month: number): number; +}; + +``` + +### DateUtilDecorator +A decorator that makes the `dateUtil` timezone aware. This is done automatically for you in your Skill Views, but you'll need to do it manually in your backend. + +### durationUtil +A utility that helps you render durations in various ways. ## Timezones