@ 日期/ 工作日

测试日期是否为节假日,并管理与节假日有关的信息.

注:0.4.0版由于完全重写而更改了API. 通过安装0.3的最新补丁版本来使用旧API.

安装

npm install --save @date/holidays

用法: 添加简单假日

有些假期总是在同一天,因此很容易确定.

const Holidays = require('@date/holidays')
const holidays = Holidays()
// all in one: const holidays = require('@date/holidays')()

// at this point `holidays` is empty so all calls to isHoliday() return false.

// simplest method for fixed dates only requires the month and day.
const removerFn = holidays.add({
  // optional holiday info.
  // defaults to {}.
  // may be a function returning an object.
  mainInfo: {
    name: 'Valentine\'s Day',
    public: true,
  },
  // provide both the month and day
  month: 1,  // NOTE: I prefer using months as 1-12, but, Date uses 0-11
  day  : 14,
})

// You can remove the holiday from the holidays instance by calling its remover.
// it will remove the function and its cache (if it's a caching holiday).
removerFn()

用法: 添加复杂的假日

有些假日需要计算何时发生,以及是否还有“观察”日期.

指定假日的日期范围 is() 函数以测试是否 Date 是个节日.

// this holiday is available as: @date/IndependenceDay
// Independence Day is always on July 4th
// It has an "observed" holiday on the nearest weekday if it's on the weekend
holidays.add({
  // first way to specify the holiday's date range.
  month: 6, // July is 6 because Date because 0-11
  firstDay: 3,
  lastDay: 5,

  // // second way allows specifying multiple date ranges (as for New Year's Day)
  // dateRange: [ // each element is an array with a range or individual date.
  //   // this means July 3rd through July 5th.
  //   [ 6, 3, 5 ]
  //
  //   // an individual day would be:
  //   // [ 11, 31 ] // for December 31st (not relevant for Independence Day)
  // ],

  // optional holiday info.
  // defaults to {}.
  // may be a function returning an object.
  mainInfo: {
    name: 'Independence Day',
    public: true, // it's a public holiday in USA
    bank: true, // it's a bank holiday in USA when it's on a weekday.
  },

  // optional info for the observed days.
  // defaults to `mainInfo`.
  // may be a function returning an object.
  observedInfo: {
    name: 'Independence Day (observed)',
    public: true,
    bank: true, // the observed date is always a bank holiday.
  },

  // optional info when main date is on a weekend.
  // defaults to `mainInfo`.
  // may be a function returning an object.
  mainInfoWhenObserved: {

    name: 'Independence Day',
    public: true,
    bank: false, // when it's on the weekend it's not a bank holiday (the observed is)
  },

  // `date` is the `Date` instance.
  // the other args are taken from the Date instance and used multiple times
  // so they are provided as a convenience so you don't have to call those
  // getters again.
  // `year` is the "full year" 4-digits.
  is: function isIndependenceDay(date, day, month, year) {

    // get the weekday so we can see if it's the main, observed, or neither.
    const weekday = date.getDay()

    // return:
    //  0 - not a match
    //  1 - is the main holiday on a business day
    //  2 - is the observed holiday on a business day
    //  3 - is the main holiday on a weekend day
    switch(day) {
      // 3 for July 3rd which is the observed holiday when it's a Friday
      case 3: return (weekday === 5) ? 2 : 0  // Friday July 3rd is "observed"

      // 4 for July 4th, always a holiday, but is either main, or "main when observed"
      case 4: return (1 <= weekday && weekday <= 5) ? 1 : 3

      // 5 for July 5th which is the observed holiday when it's a Monday
      case 5: return (weekday === 1) ? 2 : 0  // Monday July 5th is "observed"

      // otherwise, not a match for the holiday.
      default: return 0
    }
  },
})

// New Year's spans multiple months and multiple years because
// it can be observed on the day before which is December 31st.
// we support this with the `dateRange` property.
holidays.add({
  // all three "info" objects are optional.
  dateRange: [
    [ 12, 31 ],  // specific day: December 31st
    [ 0, 1, 2 ], // range of days: January 1st to 2nd
  ],
  is: (date, day, month, year) => {
    // Holidays ensures the date we receive is within the range we specified.
    // so, we need to look at the day of week to determine our result.
    const weekday = date.getDay()

    switch(day) {
      case 31: // only the observed holiday if it's a Friday
        return (weekday === 5) ? 2 : 0

      case 1: // always main holiday date, might be on weekend/weekday
        return (1 <= weekday && weekday <= 5) ? 1 : 3

      case 2: // only the observed holiday if it's a Monday
        return (weekday === 1) ? 2 : 0

      default: // otherwise, not a match
        return 0
    }
  },
})

// a date may not have a set number which requires more processing.
holidays.add({
  mainInfo: {
    name: 'Father\'s Day',
  },

  // it's the third Sunday in June.
  // so, month is 5 because Date uses 0-11,
  // and, the days it could be on are June 15th to 21st.
  dateRange: [
    [ 5, 15, 21 ]
  ],

  is: function isFathersDay(date, day, month, year) {
    // Holidays ensures it's within the date range we specified.
    // so, is it a Sunday?
    return (date.getDay() === 0) ? 1 : 0
  },
})

用法:帮助者

与日期合作时 @ 日期/ 生成器 财务报告和审定财务报表 @ 日期/ 业务 帮助.

我所出版的个别节日都会有一个 gen(year) 函数返回 a Date 例如,在指定年份的假期。 也可能有一个 observed 属性设置在其中 Date 当年的节日是"观察"的 这是上一个版本使用的 @date/holidays编辑 @date/generator 软件包对此很有帮助.

这个 @date/business 软件包有助于将日期改为下一个或上一个工作日。 它接受一个 Holidays 这样它就可以跳过假日了.

API 密码

API: 是Holiday( )

假返回,除非它知道指定日期的假日.

额外标准可以指定 假日 info 将测试这些值。 所有指定值必须在 info 以它返回真实.

const date = getSomeDate() // a `Date` object

// test the date without filters, returns true/false
holidays.isHoliday(date)

// test the date with a single filter, returns true/false
holidays.isHoliday(date, { some: 'thing' })

// now with two filters:
holidays.isHoliday(date, { some: 'thing', something: 'else' })

API: 获取Holiday ()

在指定日期获得所有节假日的"info"阵列.

如果日期没有节日,则返回一个空阵列.

“ info”是调用时提供的可选对象 holidays.add()。 。 。 .

见 API: 添加( )

infos = holidays.getHoliday(date)

if (infos.length > 0) {
  // then there was at least one holiday on that date.
}

// you can filter the results by supplying properties to check for in the "info".
infos = holidays.getHoliday(date, {
  some: 'prop',
  to: 'filter',
})

API: 负载( )和负载Many( )

将已公布的假日套件装入一个 Holidays 举个例子.

可以通过提供对象作为第二个参数来推翻假日的默认选项 。 它可能包含用于: 添加( )。默认选项和指定的选项将被合并.

为了方便, loadMany() 接受数组。 每个子阵列都应有包名作为第一个元素,一个可选选项将对象上覆作为第二个元素.

寻找出版的节日 @ 日期 组织.

// one-line require and build:
const holidays = require('@date/holidays')()

// load a single holiday package without overriding any options.
holidays.load('the-package-name')

// load a single holiday with some option overrides:
holidays.load('some-package-name', {
  // specify any properties used in holidays.add()
})

// to do the above for many packages at once:
holidays.loadMany([ // NOTE: argument is an array of sub-arrays.
  // sub-arrays may have only the package name:
  [ 'package-name' ],

  // or, they may also have an options override object:
  [ 'some-name', { name: 'Changed Holiday Name', cache: true } ]
])

API: 添加( 对象)

将假日添加到 holidays 举个例子.

添加接受包含假日选项的单个对象参数。 可能的选择是:

阅读后面关于特定选项的章节. 下面,让我们一起看看他们:

// the simplest holiday on a fixed date of March 3rd without info.
// the `mainInfo` will default to an empty object.
// an `is()` function will be created for it.
holidays.add({
  month: 2,
  day: 3,
})

// now returns true for any year:
holidays.isHoliday(new Date(2000, 2, 3))

// result is always an array containing holiday infos for the Date.
// in this instance, it has one element which is the default empty object.
result = holidays.getHoliday(new Date(2000, 2, 3))

if (result.length > 0) {
  // then there was at least one holiday info returned...
}

// add some info to the date to use elsewhere, or,
// use the info to filter results.
holidays.add({
  mainInfo: {
    name: 'Some Holiday',
    some: 'property',
  },
  month: 2,
  day: 3,
})

// to filter, specify the properties you want the holiday to have.
// this will return `true` because the property exists in `mainInfo`.
holidays.isHoliday(new Date(2000, 2, 3), { some: 'property' })

// can specify more than one property and both must exist and match.
holidays.isHoliday(new Date(2000, 2, 3), {
  name: 'Some Holiday',
  some: 'property',
})

// these both will return false.
holidays.isHoliday(new Date(2000, 2, 3), { some: 'thing else' })
holidays.isHoliday(new Date(2000, 2, 3), { another: 'property' })


// for holidays which can be on different dates or have observed dates
// then an `is()` function is necessary.
holidays.add({
  // these holidays can have different "info" for:
  //  1. the main date
  //  2. the observed date
  //  3. the main date when it's on a weekend, meaning there's an observed date.
  // for example, setting a property like { bank: true } for a bank holiday.
  // it'll only be true on the main date if it's a weekday.
  // it'll always be true for the observed date.
  // they can all be used for filtering as described above.
  // the three properties for them are:
  mainInfo: {},
  observedInfo: {},
  mainInfoWhenObserved: {},

  // method #1 of specifying a date range:
  // this is an array of arrays.
  // each sub-array must have either 2 or 3 elements.
  // 2 elements means it's specific date with the month then day.
  // 3 elements means it's a range of days with the month, first day, and last day.
  dateRange: [
    // many holidays are one a set date and may have an observed date
    // a day before or a day after it. So, a range of 3 days.
    // can be in month 1 between the 2nd and 4th:
    [ 1, 2, 4 ],
  ],

  // method #2 of specifying a date range:
  // for date ranges with only a single range it can instead be specified like this:
  month: 1,
  firstDay: 2,
  lastDay: 4,

  // this is called to check a Date.
  is: (date, day, month, year) {
    // must return:
    //  0 - not a match
    //  1 - is the main holiday on a business day
    //  2 - is the observed holiday on a business day
    //  3 - is the main holiday on a weekend day

    // get the weekday so we can see if it's the main, observed, or neither.
    const weekday = date.getDay()

    // check each day in the date range you specified.
    // based on the weekday you can determine whether it's main/observed/main-when-observed.
    switch(day) {
      // 2 for February 2nd which is the observed holiday when it's a Friday
      case 2: return (weekday === 5) ? 2 : 0

      // 3 for February 3rd, always a holiday, but is either main, or "main when observed"
      case 3: return (1 <= weekday && weekday <= 5) ? 1 : 3

      // 4 for February 4th which is the observed holiday when it's a Monday
      case 4: return (weekday === 1) ? 2 : 0

      // otherwise, not a match for the holiday.
      default: return 0
    }
  },
})

// any of the three "info" properties may specify a function instead of an Object.
// they must return an Object.
// this allows fresh objects to be returned each time it's needed.
holidays.add({
  mainInfo: () => { return { some: 'new object' } },
  month: 4,
  day: 5,
})

// by default, no caching is done. The `is()` function will be called each time.
// some holiday dates are complicated to calculate (example: Easter).
// it may be helpful to cache the results to avoid calling `is()` repeatedly.
// to do that, simply specify the `cache` property set to `true`.
holidays.add({
  cache: true,
  // ... the usual stuff here.
})

// To clear the cache of all caching holidays in a Holidays instance,
// call `purge()`.
holidays.purge()

API: 添加( ) - 信息三重奏

这个 info 用于两个位置:

1. 作为返回值 getHoliday()
2. 用于比较额外属性 isHoliday() 财务报告和审定财务报表 getHoliday() 作为"过滤"(第二个参数).

所有“ info”对象都是可选的.

若为 mainInfo 不提供默认为空对象.

两者 observedInfo 财务报告和审定财务报表 mainInfoWhenObserved 默认值为 mainInfo (默认为空对象).

如果假期总是在同一天 那么只有 mainInfo 将使用(我指那些"简单固定的日期"节假日).

如果假期可能在另一个日期,通常是"主要日期"之前的一天或之后的一天被"观察",那么"观察日期"将返回该日期 observedInfo 对象.

当年有"观察日期"时 Date 提供给 getHoliday() 或者说 isHoliday() 然后,"主要日期"是周末 它会返回 mainInfoWhenObserved 对象.

例如"情人节"总是2月14日,从未有过被观察的日期. 所以,只有一个 mainInfo 帮助.

例如,"独立日"的"主要日期"总是7月4日. 可在7月3日或7月5日观测到. 当7月4日是工作日(星期一至星期五)时 mainInfo 将于该年7月4日使用。 如果7月4日是周末的话 mainInfoWhenObserved 将于该年7月4日使用。 当3号或5号放假一年时 observedInfo 将被使用(否则那些日子不视为假日).

这有什么用? 考虑上述独立日的例子。 说得有道理 mainInfo 包含 bank: true 因为它是一个银行假日。 但是,当3号或5号节日被纪念时,4号是 没有 银行假日。 所以,这时候 mainInfoWhenObserved 因为它可以包含 bank: false编辑 observedInfo 将包含 bank: true 因为"观察日期"(在其发生的年份)总是银行假日.

API: 添加( ) - 指定日期的方法

假日有不同的日期配置. 这么说吧, Holidays 允许以不同方式指定它们.

1. 简单的固定日期

总是在同一天没有"观察日期". 比如情人节 指定这样一个 :

holidays.add({
  // February 14th
  month: 1,
  day: 14,
})

2. 固定日期和可能观测到的日期

"主要日期"总是在同一天,它可能在"主要日期"之前或之后的某一天有一个"观察日期". 例如,独立日总是在7月4日,但可以在7月3日或7月4日进行纪念. 指定这样一个 :

// method 1: properties
// Independence Day: remember, 6 is July for JS Dates 0-11
holidays.add({
  month: 6,
  firstDay: 3,
  lastDay: 5,
})


// method 2: date range
holidays.add({
  dateRange: [
    // [ month, firstDay, lastDay ]
    // Independence Day:   (remember, 6 is July for JS Dates 0-11)
    [ 6, 3, 5 ],
  ],
})

// New Year's may span 2 months and 2 years when it's
// observed the day before, which is December 31st.
// here's how that would be specified:
holidays.add({
  dateRange: [
    // the possible observed date of December 31st:
    [ 11, 31 ],
    // the range covering the "main date" and possible observed Date:
    // January 1st to January 2nd:
    [ 0, 1, 2 ],
  ],
})

3. 可变日期

每年的节假日必须计算. 父亲节就是一个例子,它总是在6月的第三个星期日。 另一个例子是复活节,它有一个复杂的计算算法.

// Father's day spans a week of possible dates:
// method 1: properties
holidays.add({
  month: 5, // NOTE: 5 is June for JS Dates 0-11
  firstDay: 15, // earliest date it could be on.
  lastDay: 21,  // latest date it could be on.
})

// method 2: date range array
holidays.add({
  dateRange: [
    // 5 is June for JS Dates 0-11
    // 15 - earliest date it could be on.
    // 21 - latest date it could be on.
    [ 5, 15, 21 ],
  ],
})

API: 添加( ) - 是( )

这个 is() 函数返回指定日期在0至3之间的值。 数值是指:

这个 is() 函数对“简单固定日期”是可选的。 可具体说明日期(见上文第一节)和 is() 函数将为此创建.

这些论点是: (date, day, month, year)第一个论点是 Date 对象。 以后的争论是为了方便,所以你不用在 Date 以获取它们 Holidays 已经叫他们自己 所以它让他们 is()) (中文(简体) ).

例如:

// a simple fixed date doesn't need an is().
// it'll be auto-created.
holidays.add({
  month: 1,
  day: 2,
})

// a "fixed date" holiday with a possible "observed date":
holidays.add({
  month: 6,
  firstDay: 3,
  lastDay: 5,
  is: (date, day, month, year) => {
    // this will only be called for dates within the date range specified.
    // so, at this point, we already know the month is `6`,
    // and the day is within the range 3 to 5.
    // so, use the `day` and the "day of the week" to determine return result:
    const weekday = date.getDay()

    switch(day) { // based on the day of the month for the date:
      // 3 for July 3rd which is the observed holiday when it's a Friday
      case 3: return (weekday === 5) ? 2 : 0  // Friday July 3rd is "observed"

      // 4 for July 4th, always a holiday, but is either main, or "main when observed"
      case 4: return (1 <= weekday && weekday <= 5) ? 1 : 3

      // 5 for July 5th which is the observed holiday when it's a Monday
      case 5: return (weekday === 1) ? 2 : 0  // Monday July 5th is "observed"

      // otherwise, not a match for the holiday.
      default: return 0
    }
  },
})

// a variable date holiday:
holidays.add({ // Father's day is third Sunday in June
  dateRange: [
    [ 5, 15, 21 ],
  ],
  is: (date, day, month, year) => {
    // this will only be called for dates within the date range specified.
    // so, at this point, we already know the month is `5`,
    // and the day is within the range 15 to 21.
    // so, all we care about is whether it's Sunday.
    const weekday = date.getDay()
    return (weekday === 0) ? 1 : 0
  },
})

API: 删除假日

删除假日从 a Holidays 举个例子.

这个 Holidays.add() 函数返回一个“ remover 函数”,当调用时,该函数将删除所添加的假日.

const someHolidaySpecification = getIt()

const removerFn = holidays.add(someHolidaySpecification)

removerFn()

API: 清洗( )

何时 cache:true 在假日的选项中指定了它会缓存结果以避免调用它 is() 函数在同一个日期重复.

每个缓存假日都会创建自己的缓存对象.

通话 purge() 编辑 Holidays 实例将用新的空对象取代所有缓存对象.

// creates all new empty caches.
holidays.purge()

MIT 许可证