Options
All
  • Public
  • Public/Protected
  • All
Menu

DaySpan

A date & schedule library to use for advanced calendars in TypeScript and JS.

Features

  • Schedules track how frequent events occur using 20+ properties
  • Events can last minutes, hours, days, or weeks
  • Events can occur all day, or 1 or more times during the day
  • Events can have any day & time included as an event occurrence (they don't need to match the frequency of the schedule)
  • Events can be excluded, cancelled, or have metadata (specific event occurrence, all in a given day, week, month, quarter, or year)
  • Event occurrences can be moved
  • Calendars can represent a span of days, weeks, months, or years
  • Easily list the next/previous days that occur on a schedule
  • Describe a schedule in a human friendly string
  • Export and import schedules and calendars to plain objects for easy saving and loading
  • Provides logic to help display intersecting events on a calendar

TypeScript Example

// A monthly calendar around today (string=event data type, any=schedule metadata type)
let cal = Calendar.months<string, any>();

// Every Monday 9:00 - 9:30
cal.addEvent({
  data: 'Weekly Meeting',
  schedule: {
    dayOfWeek: Weekday.MONDAY,
    times: 9,
    duration: 30,
    durationUnit: 'minutes'
  }
});

// Dr. Appointment on 01/04/2018
cal.addEvent({
  data: 'Dr. Appointment',
  visible: false,
  schedule: {
    on: Day.build(2018, Month.APRIL, 1)
  }
});

// Mother's Day
cal.addEvent({
  id: 'someUserProvidedId',
  data: "Mother's Day",
  schedule: new Schedule({
    weekspanOfMonth: 1,         // 2nd
    dayOfWeek: Weekday.SUNDAY,  // Sunday
    month: Month.MAY            // of May
  })
});

// The array of days in the month, each day has a list of the days events.
cal.days;

// Go to the next month
cal.next();

// Select this day and update the selection flags in the calendar days
cal.select(Day.build(2018, Month.APRIL, 12));

// Remove the schedule
cal.removeEvent('Weekly Meeting');

// A weekly calendar with custom MyEvent class
Calendar.weeks<MyEvent, any>();

// A daily calendar covering 3 days centered on today
Calendar.days<string, any>(3);

// A daily calendar covering 3 days starting with given date
Calendar.days<string, any>(3, Day.build(2018, Month.JUNE, 15), 0);

JS Example

You just need to append ds to the beginning of the classes:

// A monthly calendar around today
var cal = ds.Calendar.months();

// Every Monday 9:00 - 9:30
cal.addEvent({
  data: 'Weekly Meeting',
  schedule: {
    dayOfWeek: [ds.Weekday.MONDAY],
    times: 9,
    duration: 30,
    durationUnit: 'minutes'
  }
});

// Dr. Appointment on 01/04/2018
cal.addEvent({
  data: 'Dr. Appointment',
  schedule: new ds.Schedule({
    on: ds.Day.build(2018, ds.Month.APRIL, 1)
  })
});

Index

Enumerations

Classes

Interfaces

Type aliases

Variables

Functions

Object literals

Type aliases

Adder

Adder: function

Type declaration

    • (x: Date, amount: number): void
    • Parameters

      • x: Date
      • amount: number

      Returns void

CalendarMover

CalendarMover: function

A function which moves a given day by some amount and some unit. This is used to shift a calendar's frame via Calendar.next and Calendar.prev.

param

The day to move.

param

The amount to move the day by.

returns

A new day instance moved by the given amount.

Type declaration

    • (day: Day, amount: number): Day
    • Parameters

      • day: Day
      • amount: number

      Returns Day

CalendarTypeDefinitionMap

CalendarTypeDefinitionMap: object

A map of CalendarTypeDefinition keyed by the Units.

Type declaration

DayInput

DayInput: number | string | Day | number[] | object | true

All valid types which may be converted to a Day instance.

  • number: A UNIX timestamp.
  • string: A string representation of a date.
  • Day: An existing Day instance.
  • number[]: An array of numbers specifying any of: [year, month, dayOfMonth, hour, minute, second, millisecond].
  • object: An object with any of the following properties: year, month, dayOfMonth, hour, minute, second, millisecond.
  • true: This will be interpreted as Day.today

DayProperty

DayProperty: keyof DayFrequency

One of the properties on the Day object.

DescribePattern

DescribePattern: function

Describes a Pattern given a Day to base it on.

param

The day to base the description on.

returns

The description of the pattern.

Type declaration

    • (day: Day): string
    • Parameters

      Returns string

Differ

Differ: function

Type declaration

    • (a: Date, b: Date): number
    • Parameters

      • a: Date
      • b: Date

      Returns number

Ender

Ender: function

Type declaration

Formatter

Formatter: function

Type declaration

    • (item: T): string
    • Parameters

      • item: T

      Returns string

FrequencyValue

A frequency that occurs at a constant rate or only on specific values.

FrequencyValueEquals

FrequencyValueEquals: number

A frequency that occurs once.

FrequencyValueOneOf

FrequencyValueOneOf: number[]

A frequency that occurs only on specific values.

IdentifierInput

IdentifierInput: number | string

The type for identifiers. Most of the time an identifier can be stored as a number because the 4 digit year is first. However when the year is below 1000 a string will be used with zero padding. Storing identifiers as numbers enable very quick comparisons and using strings or numbers allows the identifier to be used as a key to a map.

PatternRule

PatternRule: number | number[] | boolean | FrequencyValueEvery

A rule helps parse ScheduleInput and determines whether it matches the given pattern.

  • When a number is given, the input MUST be an array of the same length and contain any values.
  • When an array of numbers is given, the input MUST be an array containing the same values.
  • When a TRUE is given the input MUST contain that property and can be any value.
  • When a FALSE is given the input MAY contain that property (optional).
  • When a property is NOT specified, the input MUST NOT contain that property.
  • When an object with every is given, the input must match the every and offset values (have the same frequency).

ScheduleEventTuple

ScheduleEventTuple: [DaySpan, Day, IdentifierInput]

A tuple which identifies an event on the schedule. The tuple contains the total span of the event occurrence, the day of the event (could be the start day, end day, or any days in between for multi-day events) as well as the identifier for the event.

SortEvent

SortEvent: function

A function which takes two CalendarEvents and returns a number which instructs a sort which event goes before the other in a list.

param

The first event.

param

The second event.

returns

When both events are considered equal 0 is returned, when the first event should go before the second event a negative number is returned, when the second event should go before the first event a positive number is returned.

Type declaration

Starter

Starter: function

Type declaration

TimeInput

TimeInput: Time | number | string | object

A value that can possibly be parsed into a Time instance.

see

Time.parse

Unit

Unit: "millis" | "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year"

UnitRecord

UnitRecord: Record<Unit, T>

Variables

Const DayFormat

DayFormat: Format<[Day, Locale]> = new Format<[Day, Locale]>({M: ([day]) => (day.month + 1) + '',Mo: ([day, locale]) => locale.suffix(day.month + 1),MM: ([day]) => fn.padNumber(day.month + 1, 2),MMm: ([day, locale]) => locale.months[3][day.month],MMM: ([day, locale]) => locale.months[2][day.month],MMMm: ([day, locale]) => locale.months[1][day.month],MMMM: ([day, locale]) => locale.months[0][day.month],Q: ([day]) => (day.quarter + 1) + '',Qo: ([day, locale]) => locale.suffix(day.quarter + 1),D: ([day]) => day.dayOfMonth + '',Do: ([day, locale]) => locale.suffix(day.dayOfMonth),DD: ([day]) => fn.padNumber(day.dayOfMonth, 2),DDD: ([day]) => day.dayOfYear + '',DDDo: ([day, locale]) => locale.suffix(day.dayOfYear),DDDD: ([day]) => fn.padNumber(day.dayOfYear, 3),d: ([day]) => day.day + '',do: ([day, locale]) => locale.suffix(day.day),dd: ([day, locale]) => locale.weekdays[3][day.day],ddd: ([day, locale]) => locale.weekdays[2][day.day],dddd: ([day, locale]) => locale.weekdays[0][day.day],e: ([day]) => day.dayOfWeek + '',E: ([day]) => (day.dayOfWeek + 1) + '',eo: ([day, locale]) => locale.suffix(day.dayOfWeek),Eo: ([day, locale]) => locale.suffix(day.dayOfWeek + 1),w: ([day]) => day.week + '',wo: ([day, locale]) => locale.suffix(day.week),ww: ([day]) => fn.padNumber(day.week, 2),W: ([day]) => day.weekOfYear + '',Wo: ([day, locale]) => locale.suffix(day.weekOfYear),WW: ([day]) => fn.padNumber(day.weekOfYear, 2),Y: ([day]) => day.year + '',YY: ([day]) => fn.padNumber(day.year % 100, 2),YYYY: ([day]) => fn.padNumber(day.year, 4, 10),gg: ([day]) => fn.padNumber(day.year % 100, 2),gggg: ([day]) => fn.padNumber(day.year, 4, 10),GG: ([day]) => fn.padNumber(day.year % 100, 2),GGGG: ([day]) => fn.padNumber(day.year, 4, 10),a: ([day, locale]) => day.hour < 12 ? locale.am : locale.pm,A: ([day, locale]) => day.hour < 12 ? locale.am.toUpperCase() : locale.pm.toUpperCase(),H: ([day]) => day.hour + '',HH: ([day]) => fn.padNumber(day.hour, 2),h: ([day]) => ((day.hour % 12) || 12) + '',hh: ([day]) => fn.padNumber((day.hour % 12) || 12, 2),k: ([day]) => (day.hour + 1) + '',kk: ([day]) => fn.padNumber(day.hour + 1, 2),m: ([day]) => day.minute + '',mm: ([day]) => fn.padNumber(day.minute, 2),s: ([day]) => day.seconds + '',ss: ([day]) => fn.padNumber(day.seconds, 2),S: ([day]) => fn.padNumber(day.millis, 3, 1),SS: ([day]) => fn.padNumber(day.millis, 3, 2),SSS: ([day]) => fn.padNumber(day.millis, 3),SSSS: ([day]) => fn.padNumber(day.millis, 3) + '0',SSSSS: ([day]) => fn.padNumber(day.millis, 3) + '00',SSSSSS: ([day]) => fn.padNumber(day.millis, 3) + '000',SSSSSSS: ([day]) => fn.padNumber(day.millis, 3) + '0000',SSSSSSSS: ([day]) => fn.padNumber(day.millis, 3) + '00000',SSSSSSSSS: ([day]) => fn.padNumber(day.millis, 3) + '000000',z: ([day]) => day.date.toLocaleTimeString('en-us', {timeZoneName:'short'}).split(' ')[2],zz: ([day]) => day.date.toLocaleTimeString('en-us', {timeZoneName:'long'}).split(' ')[2],Z: ([day]) => formatOffset(day, ':'),ZZ: ([day]) => formatOffset(day, ''),X: ([day]) => Math.floor(day.time / 1000) + '',x: ([day]) => day.time + '',LT: ([day, locale]) => day.format(locale.formatLT, true),LTS: ([day, locale]) => day.format(locale.formatLTS, true),L: ([day, locale]) => day.format(locale.formatL, true),l: ([day, locale]) => day.format(locale.formatl, true),LL: ([day, locale]) => day.format(locale.formatLL, true),ll: ([day, locale]) => day.format(locale.formatll, true),LLL: ([day, locale]) => day.format(locale.formatLLL, true),lll: ([day, locale]) => day.format(locale.formatlll, true),LLLL: ([day, locale]) => day.format(locale.formatLLLL, true),llll: ([day, locale]) => day.format(locale.formatllll, true),}, {'[': {start: '[',startEscape: '\\[',end: ']',endEscape: '\\]'},"'": {start: "'",startEscape: "''",end: "'",endEscape: "''"}})

Let PatternMap

PatternMap: object

The map of patterns keyed by their name.

see

Pattern.withName

Type declaration

Let Patterns

Patterns: Pattern[] = [new Pattern('none', true,(day) => Locales.current.patternNone(day),{year: 1,month: 1,dayOfMonth: 1}),new Pattern('daily', true,(day) => Locales.current.patternDaily(day),{}),new Pattern('weekly', true,(day) => Locales.current.patternWeekly(day),{dayOfWeek: 1}),new Pattern('monthlyWeek', true,(day) => Locales.current.patternMonthlyWeek(day),{dayOfWeek: 1,weekspanOfMonth: 1}),new Pattern('annually', true,(day) => Locales.current.patternAnnually(day),{month: 1,dayOfMonth: 1}),new Pattern('annuallyMonthWeek', true,(day) => Locales.current.patternAnnuallyMonthWeek(day),{month: 1,dayOfWeek: 1,weekspanOfMonth: 1}),new Pattern('weekday', true,(day) => Locales.current.patternWeekday(day),{dayOfWeek: [Weekday.MONDAY, Weekday.TUESDAY, Weekday.WEDNESDAY, Weekday.THURSDAY, Weekday.FRIDAY]}),new Pattern('monthly', true,(day) => Locales.current.patternMonthly(day),{dayOfMonth: 1}),new Pattern('lastDay', true,(day) => Locales.current.patternLastDay(day),{lastDayOfMonth: [1]}),new Pattern('lastDayOfMonth', true,(day) => Locales.current.patternLastDayOfMonth(day),{month: 1,lastDayOfMonth: [1]}),new Pattern('lastWeekday', true,(day) => Locales.current.patternLastWeekday(day),{lastWeekspanOfMonth: [0],dayOfWeek: 1,month: 1}),new Pattern('custom', true,(day) => Locales.current.patternCustom(day),{dayOfWeek: false,dayOfMonth: false,lastDayOfMonth: false,dayOfYear: false,year: false,month: false,week: false,weekOfYear: false,weekspanOfYear: false,fullWeekOfYear: false,lastWeekspanOfYear: false,lastFullWeekOfYear: false,weekOfMonth: false,weekspanOfMonth: false,fullWeekOfMonth: false,lastWeekspanOfMonth: false,lastFullWeekOfMonth: false})]

The list of patterns that can be searched through for matches to schedule input.

see

Pattern.findMatch

Const TimeFormat

TimeFormat: Format<Time> = new Format<Time>({A: (t: Time) => Locales.current[t.hour < 12 ? 'am' : 'pm'].toUpperCase(),a: (t: Time) => Locales.current[t.hour < 12 ? 'am' : 'pm'],H: (t: Time) => t.hour + '',h: (t: Time) => ((t.hour % 12) || 12) + '',k: (t: Time) => (t.hour + 1) + '',m: (t: Time) => t.minute + '',s: (t: Time) => t.second + '',S: (t: Time) => fn.padNumber(t.millisecond, 3, 1),HH: (t: Time) => fn.padNumber(t.hour, 2),hh: (t: Time) => fn.padNumber((t.hour % 12) || 12, 2),kk: (t: Time) => fn.padNumber(t.hour + 1, 2),mm: (t: Time) => fn.padNumber(t.minute, 2),ss: (t: Time) => fn.padNumber(t.second, 2),SS: (t: Time) => fn.padNumber(t.millisecond, 3, 2),SSS: (t: Time) => fn.padNumber(t.millisecond, 3)}, {'[': {start: '[',startEscape: '\[',end: ']',endEscape: '\]'},"'": {start: "'",startEscape: "''",end: "'",endEscape: "''"}})

Formats time into a string. The following list describes the available formatting patterns:

Hour

  • H: 0-23
  • HH: 00-23
  • h: 12,1-12,1-11
  • hh: 12,01-12,01-11
  • k: 1-24
  • kk: 01-24
  • a: am,pm
  • A: AM,PM

    Minute

  • m: 0-59
  • mm: 00-59

    Second

  • s: 0-59
  • ss: 00-59

    Millisecond

  • S: 0-9
  • SS: 00-99
  • SSS: 000-999

Functions

addDays

  • addDays(x: Date, amount: number): void

addHours

  • addHours(x: Date, amount: number): void

addMilliseconds

  • addMilliseconds(x: Date, amount: number): void

addMinutes

  • addMinutes(x: Date, amount: number): void

addMonths

  • addMonths(x: Date, amount: number): void

addQuarters

  • addQuarters(x: Date, amount: number): void

addSeconds

  • addSeconds(x: Date, amount: number): void

addWeeks

  • addWeeks(x: Date, amount: number): void

addYears

  • addYears(x: Date, amount: number): void

compare

diffDays

  • diffDays(a: Date, b: Date): number

diffHours

  • diffHours(a: Date, b: Date): number

diffMilliseconds

  • diffMilliseconds(a: Date, b: Date): number

diffMinutes

  • diffMinutes(a: Date, b: Date): number

diffMonths

  • diffMonths(a: Date, b: Date): number

diffQuarters

  • diffQuarters(a: Date, b: Date): number

diffSeconds

  • diffSeconds(a: Date, b: Date): number

diffWeeks

  • diffWeeks(a: Date, b: Date): number

diffYears

  • diffYears(a: Date, b: Date): number

endOfDay

  • endOfDay(x: Date): void

endOfHour

  • endOfHour(x: Date): void

endOfMinute

  • endOfMinute(x: Date): void

endOfMonth

  • endOfMonth(x: Date): void

endOfQuarter

  • endOfQuarter(x: Date): void

endOfSecond

  • endOfSecond(x: Date): void

endOfWeek

endOfYear

  • endOfYear(x: Date): void

getAbsoluteTimestamp

  • getAbsoluteTimestamp(a: Date): number

getDateOffset

  • getDateOffset(x: Date): number

getDayOfWeek

getDayOfYear

  • getDayOfYear(a: Date): number

getDaysInMonth

  • getDaysInMonth(x: Date): number

getDaysInYear

  • getDaysInYear(x: Date): number

getFullWeekOf

  • getFullWeekOf(start: Date, dayOfStart: number, options?: LocaleOptions): number

getFullWeekOfMonth

getFullWeekOfYear

getLastDayOfMonth

  • getLastDayOfMonth(x: Date): number

getLastFullWeekOfMonth

  • getLastFullWeekOfMonth(x: Date, options?: LocaleOptions): number

getLastFullWeekOfYear

  • getLastFullWeekOfYear(x: Date, options?: LocaleOptions): number

getLastWeekspanOfMonth

  • getLastWeekspanOfMonth(x: Date): number

getLastWeekspanOfYear

  • getLastWeekspanOfYear(x: Date): number

getQuarter

  • getQuarter(x: Date): number

getTimezoneOffsetInMilliseconds

  • getTimezoneOffsetInMilliseconds(a: Date): number

getWeek

  • getWeek(start: Date, dayOfStart: number, options: LocaleOptions): number

getWeekISO

  • getWeekISO(start: Date, dayOfStart: number, options?: LocaleOptions): number

getWeekOfMonth

getWeekOfMonthISO

getWeekOfYear

getWeekOfYearISO

getWeeksInYear

getWeekspanOfMonth

  • getWeekspanOfMonth(x: Date): number

getWeekspanOfYear

  • getWeekspanOfYear(x: Date): number

isDaylightSavingTime

  • isDaylightSavingTime(x: Date): boolean

isLeapYear

  • isLeapYear(x: Date): boolean

mutate

  • mutate(a: Date, mutator: function, options?: LocaleOptions): Date

operate

  • operate(value: number, op: Op, absolute?: boolean): number
  • Performs the requested operation on the given number, optionally taking the absolute value of the number before the operation.

    Parameters

    • value: number

      The number to operate on.

    • op: Op

      The operation to perform.

    • Default value absolute: boolean = false

      If the number should be positive before the operation.

    Returns number

    The operated result, or the original value if its not a valid number.

startOfDay

  • startOfDay(x: Date): void

startOfHour

  • startOfHour(x: Date): void

startOfMinute

  • startOfMinute(x: Date): void

startOfMonth

  • startOfMonth(x: Date): void

startOfQuarter

  • startOfQuarter(x: Date): void

startOfSecond

  • startOfSecond(x: Date): void

startOfWeek

startOfYear

  • startOfYear(x: Date): void

Object literals

Const add

add: object

day

day: addDays = addDays

hour

hour: addHours = addHours

millis

millis: addMilliseconds = addMilliseconds

minute

minute: addMinutes = addMinutes

month

month: addMonths = addMonths

quarter

quarter: addQuarters = addQuarters

second

second: addSeconds = addSeconds

week

week: addWeeks = addWeeks

year

year: addYears = addYears

Const diff

diff: object

day

day: diffDays = diffDays

hour

hour: diffHours = diffHours

millis

millis: diffMilliseconds = diffMilliseconds

minute

minute: diffMinutes = diffMinutes

month

month: diffMonths = diffMonths

quarter

quarter: diffQuarters = diffQuarters

second

second: diffSeconds = diffSeconds

week

week: diffWeeks = diffWeeks

year

year: diffYears = diffYears

Const durations

durations: object

The number of milliseconds for various duration units. These are worse case scenario and do not include DST changes.

day

day: number = Constants.MILLIS_IN_DAY

hour

hour: number = Constants.MILLIS_IN_HOUR

millis

millis: number = 1

minute

minute: number = Constants.MILLIS_IN_MINUTE

month

month: number = Constants.MILLIS_IN_DAY * Constants.DAY_MAX

quarter

quarter: number = Constants.MILLIS_IN_DAY * Constants.DAY_MAX * Constants.MONTHS_IN_QUARTER

second

second: number = Constants.MILLIS_IN_SECOND

week

week: number = Constants.MILLIS_IN_WEEK

year

year: number = Constants.MILLIS_IN_DAY * Constants.DAYS_IN_YEAR

Const endOf

endOf: object

day

day: endOfDay = endOfDay

hour

hour: endOfHour = endOfHour

minute

minute: endOfMinute = endOfMinute

month

month: endOfMonth = endOfMonth

quarter

quarter: endOfQuarter = endOfQuarter

second

second: endOfSecond = endOfSecond

week

week: endOfWeek = endOfWeek

year

year: endOfYear = endOfYear

millis

  • millis(x: Date): Date

Const startOf

startOf: object

day

day: startOfDay = startOfDay

hour

hour: startOfHour = startOfHour

minute

minute: startOfMinute = startOfMinute

month

month: startOfMonth = startOfMonth

quarter

quarter: startOfQuarter = startOfQuarter

second

second: startOfSecond = startOfSecond

week

week: startOfWeek = startOfWeek

year

year: startOfYear = startOfYear

millis

  • millis(x: Date): Date

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method

Generated using TypeDoc