Blue Moon allows you to create dates based on day name, day number, week, month, month-end and other date settings to return one specific date that matches your criteria. It can be in the past or future.
BlueMoon({ day: "Sunday -1", month: 5 })
This returns the last Sunday of May of the current year.
Blue Moon is useful for setting dates for reports or generally finding specific dates that can be tricky to code. Finding public holidays are another use. It can be hard finding the last Wednesday of the month, Monday last week or the second Sunday of May each year.
BlueMoon is very verbose for getting specific dates for things like reports. eg
const startThisMonth = BlueMoon({ day: 1 })
const endThisMonth = BlueMoon({ day: "monthend" })
const startNextMonth = BlueMoon({ day: 1, month: "+1" })
const endNextMonth = BlueMoon({ day: "monthend", month: "+1" })
It can be relative to the current date, a pivot date or an absolute date.
Include it in your HTML file:
<script src="https://cdn.jsdelivr.net/gh/chrisjwaddell/blue-moon@main/dist/blue-moon-min.js"></script>
Or download the file and include it in your Node project, place blue-moon.js in your directory and include:
const BlueMoon = require("./blue-moon")
To declare a start and end date that spans the start of the year to the end of the year, you can do this:
const reportStart = BlueMoon( { day: 1, month: 1 })
const reportEnd = BlueMoon( { day: "monthend", month: 12 })
There are four main date properties: day, week, month and year.
Each setting can be specific, relative or current.
relative - BlueMoon({ day: "+1" }) // tomorrow
absolute - BlueMoon({ day: 5, month: 3 }) // 5th of March this year
current - BlueMoon({ day: "current", month: "+1" }) // one month from now
The day property is mandatory. The other properties are optional.
Day can be a number such as "15", meaning the 15th of the month, it can be "+5", meaning 5 days in the future, it can be a specific dayname such as "Wednesday", it can be a dayname and week such as "Wednesday 1" or it can be "current". It can be a specific day of the month such as "Monday 2" meaning the second Monday of each month.
The day property is mandatory.
BlueMoon({ day: 5 })
Refers to the 5th of the current month.
BlueMoon({ day: 25, month: 3 })
Means 25th of March every year.
const reportMonthEnd = BlueMoon({ day: "monthend", month: 2 })
This calculates the end of month, whether it's 29th of February or 28th in this case, or 30th or 31st for other months.
BlueMoon({ day: "current", month: "+1" })
This calculates one month from now no matter how many days in the current month. If it's the 18th of February today, the result will be the 18th of March.
Day of week can combine with a Week number or a Month.
BlueMoon({ day: "Mon" })
means Monday of the current week. week is default current so it's equivalent to { day: "Mon", week: "current" }. When it goes into the next week, it's always Monday of the current week.
BlueMoon({ day: "Monday", week: 2 })
means Monday of the 2nd week of each month.
BlueMoon( {day: "Thu", week: "-1" } )
Thursday last week
BlueMoon({ day: "Monday", week: "+2" })
means Monday in two weeks. It will always give the Monday two weeks ahead of the current week.
Note - You must use quotes for relative values.
BlueMoon({ day: "current" })
Today is set like this.
"current" can be put on week, month or year. current is a relative date type, it really means "+0".
If the current date is June 30, 2022 and you have
BlueMoon({ day: "current", month: 8 })
This would return
BlueMoon({ year: 2022, month: 8, day: 30 })
but when the date is 1st July, 2022, it would return
BlueMoon({ day: 1, month: 8, year: 2022 })
For relative days, you cannot have any week, month or year settings.
BlueMoon({ day: "-90" })
90 days ago.
BlueMoon({ day: "+1" })
Tomorrow.
Note - For relative days, you must use quotes and either "+" or "-".
{ day: "+1" } is tomorrow but { day: +1 } is the first day of the current month.
{ day: 2 } is the same as { day: "2" }
There are some handy options if you are specific about full week or part week.
BlueMoon({ day: "Sunday 3" })
The third Sunday of the current month.
const marketDay = BlueMoon( { day: "Sunday 2", pivotDate: { day: 1, month: 1 }, loop: 24 } )
Market day is the second Sunday of every month.
This will find the second Sunday of every month from 1st of January this current year for the next 24 months.
BlueMoon({ day: "Wednesday -2", month: 10 })
The second last Wednesday of October of the current year.
BlueMoon( { day: "Monday 1", loop: 10 } )
The first Monday of the current month and the next 9 months
BlueMoon({ day: "Wedesday *1" })
The first Wedesday of each month that falls on a full week inside of that month. If the first Wedesday starts on the 1st or 2nd, Monday is in the previous month and so this is not considered to be a full week so Wednesday *1 would be the week after.
Week works in combination with day. week can be absolute, relative or the current week. week puts you in a seven day range.
When week is an absolute number, it is the week number for the year.
BlueMoon({ day: "Mon", week: 18 })
is considered to be the Monday of the 18th week of the year.
BlueMoon({ day: "Tuesday", week: "+2" })
Tuesday in two weeks from now.
BlueMoon({ day: "Monday", week: "current" })
Monday of this week.
BlueMoon({ day: "Sun", week: 2 })
Sunday on week 2 of the year.
It counts the first week that isn't full. 1/1 of that year is the first week even if that day is in the middle of the week.
If month is omitted, it assumed current month if other settings are specific values.
day and week work together and day can work with month.
BlueMoon({ day: "Tuesday", week: 2, month: 6 })
Tuesday in the second week of June. This specific case may be the first Tuesday in June depending on when the first week of June starts.
BlueMoon({ day: "Tuesday 2", month: 6 })
This is the second Tuesday in June.
BlueMoon({ day: 15, month: 6, year: 2023 })
The 15th of June, 2023.
So we have four main options:
<dayname> <occurrence number> - Picks the day from the month. It counts the first day occurrence regardless of whether or not the first week overlapped into the previous week. eg
BlueMoon({ day: "Fri 2" })
<dayname> -<occurrence number> - Picks the day that occurred in the month, the last being -1. eg BlueMoon({ day: "Sat -1" })
<dayname> *<occurrence number> - Picks the day from only full weeks. eg BlueMoon({ day: "Fri *2" })
<dayname> *-<occurrence number> - Full week, from the last week of the month. eg BlueMoon({ day: "Sun *-2" })
Note - There is also:
<dayname> <week>
The difference with this is that if you enter
BlueMoon({ day: "Monday", week: 1 })
Week 1 is the first of that month, and the start of the week probably is in the previous month. In this case, Monday would be the date of the previous month, something like 29th of the previous month. Using the month setting, you only get days in that month.
The picture above shows that Wed 1 and Sun 1 give you the first day within the month and Wed *1 and Sun *1 gives the day of the first full week of that month.
Year must be either a four digit specific year eg 2024, a relative number +1 or current.
BlueMoon({ day: 1, year: "2023" })
This returns the first of the current month in 2023 every time it's run.
BlueMoon({ day: 1, year: "+1" })
This returns the first of the current month of next year every time it's run.
Note - You must use quotes for relative values.
current is like a relative year, like +0. day, week, month or year can be set as current.
BlueMoon({ day: "current", month: 1 })
If the date is 15th of March, 2024, this would return
BlueMoon({ day: 15, month: 3, year: 2024 })
If you leave out month or year, it defaults to current.
BlueMoon({ day: 1 })
is the same as
BlueMoon({ day: 1, month: "current", year: "current" })
This returns the first of the current month you are in, every time you run it, it will return the first of that month of the current year you are in.
BlueMoon({ day: "Monday" })
This returns Monday of the current week. Day of the week is used in conjuction with week, if week is missing, it assumes
week: current
For day, if you set it as relative eg
BlueMoon({ day: "+14" })
You cannot have any week, month or year settings. This wouldn't make sense. Relative day is a particular number of days ahead or behind today.
You can mix and match if day is not relative, such as
BlueMoon({ day: "current", month: "+1", year: "current"})
BlueMoon({ day: "Monday", week: 2, year: "current"})
BlueMoon({ day: 15, month: "+1", year: "current"})
There are four options:
- pivotDate - the date you start from
- loop - you can loop forward or backwards, Blue Moon will return an array of dates in either the past or future
- resultAsDateObject - Default is false. Setting resultAsDateObject to true will return a Javascript date type.
- startOfWeek - the default is Monday.
- warnings - warnings in the console. It warns you when you are at a date over 28 and want to increase the date by one month and the next month may not have as many days in that month.
This is the date you want to start from. Like a reference point. You could find the first Sunday in March starting from 2000.
Pivot date is the second argument.
The default is today if pivot date is empty.
It must be an object that represents a specific date with day, month and year properties.
You could set the pivot date as:
BlueMoon({ day: "Sunday 1", month: 3, pivotDate: { day: 1, month: 1, year: 2000 } } )
This finds the first Sunday in March 2000. Without pivot date, and with year omitted, it assumed year: "current" to return the first Sunday in March for this year.
BlueMoon({ day: "Sunday 1", month: 3 })
This finds the first Sunday in March this year.
This can be a useful feature returning an array of dates. It can move backwards and forwards in time to get past or future dates.
BlueMoon({ day: "Mon 1", pivotDate: {day: 1, month: 1}, loop: 12})
Blue Moon returns an array of twelve dates, the first Monday of each month this year.
const next5MothersDays = BlueMoon({ day: "Sunday 2", month: 5, loop: 5})
Returns an array of dates of Mothers days for the next five years.
Blue Moon categorizes the frequency based on the type of day value. The date can change daily, weekly or yearly.
Daily
BlueMoon({ day: "current", loop: 10 })
This would return the next 10 days
``
Weekly
BlueMoon( { day: "Mon", loop: 5 })
The would return an array of 5 values with Monday this current week and the next 4 Mondays.
Monthly
BlueMoon( { day: 1, loop: 5 })
This returns the first of the current month and the first of the next four months.
BlueMoon( { day: "monthend", loop: -5 })
Returns the month end of this month and the last four months.
BlueMoon( { day: "Sunday 3", loop: 2 })
Returns the 3rd Sunday of this month and the 3rd Sunday of the next two months.
Yearly
BlueMoon( { day: "Mon", week: 15, loop: 2 })
Returns Monday of the 15th week of this year, and same for next year.
BlueMoon( { day: 10, month: 4, loop: 2 })
Returns 10th of April of this year and next year.
BlueMoon( { day: "Sunday 3", month: 4, loop: 2 })
Returns 3rd Sunday of April of this year and next year.
The default is to return a Blue Moon date object (which is an object with day, month and year). You can opt to return a Javascript Date. Note - If you return a Javascript date, it returns the date at the start of the day midnight ie 00:00:00 in your local time zone.
const intIndependenceDay = BlueMoon( { day: 4, month: 7, resultAsDateObject: true, loop: 5 })
This gives you the next five Independence Days as a javascript date.
To specify when the start of the week is. The default is 1 - Monday. Sunday is 0.
BlueMoon({ day: "Mon 1", startOfWeek: 0 })
Returns the first Monday of the month. The first week is the week that starts at Sunday.
Turn off warnings in the console. The default is true.
BlueMoon({ day: 31 })
You will get a warning with this setting because next month may return an incorrect date because it may not have 31 days in the month.
BlueMoon({ day: 31, warnings: false })
However, this won't give a warning.