Financial Calendar
Market calendar and trading hours.
Support for equity markets from 2015 until 2020 in:
- New York
- London
- Paris
- Frankfurt
- Copenhagen
- Hong Kong
- Shanghai
- Tokyo
- Sydney
How do I get it?
Install with npm:
npm install fincal
Clone repo with git:
git clone https://github.com/triploc/fincal.git
Download over HTTPS:
wget https://github.com/triploc/fincal/archive/master.zip
unzip master.zip
How do I use it?
var fincal = require("fincal");
var calendar = fincal.calendar("new_york") = fincal["new_york"] = fincal.new_york;
calendar.areMarketsOpenToday();
calendar.areMarketsOpenOn([date]);
calendar.areMarketsOpenNow();
calendar.areMarketsOpenAt([date], [extended]);
calendar.areMarketsOpenOn("next monday");
calendar.areMarketsOpenOn({ year: 2015, month: 1, day: 1 });
calendar.areMarketsOpenAt("Sep 1st, 2015 8:35am", true);
calendar.areMarketsOpenAt(new Date("December 17, 1995 03:24:00"));
calendar.areMarketsOpenAt(calendar.here("Sep 1st, 2015 8:35am"));
Parameters
date
Flexible-format anchor date for the calculation. When optional and omitted, calls use currentTime().
Absolute datetime formats are converted to the local timezone of the calendar. Relative datetime formats
are interpreted as in the local timezone of the calendar.
Value can be:
- Javascript date (i.e. new Date() or equivalent)
- Unix time (milliseconds since the epoch)
Javascript dates and unix timestamps have implicit timezones and will be converted to the calendar timezone,
changing the display time (e.g. January 1st 11pm in New York is January 2nd 4am in London).
Strings and date structures are interpreted as local to the calendar timezone (e.g. "Tuesday" means midnight on Tuesday there).
Moments and moments with timezones have explicit timezones and are converted to the calendar timezone.
TIP: Use strings and objects to talk about relative and absolute times "over there". Use javascript dates and unix offsets
to convert dates and times "here". For advanced control, use moments (described below).
extended
A boolean flag indicating whether the call applies to regular trading hours (false or omitted) or extended trading hours (true).
Simple Interface
calendar.areMarketsOpenToday();
calendar.areMarketsOpenOn(date);
calendar.areMarketsOpenNow();
calendar.areMarketsOpenAt([date], [extended]);
Trading Day Methods
calendar.isTradingDay([date])
calendar.isFullTradingDay([date])
calendar.isRegularTradingDay([date])
calendar.isPartialTradingDay([date])
calendar.isHoliday([date])
calendar.nextTradingDay([date])
calendar.nextFullTradingDay([date])
calendar.nextRegularTradingDay([date])
calendar.nextPartialTradingDay([date])
calendar.nextHoliday([date])
calendar.previousTradingDay([date])
calendar.previousFullTradingDay([date])
calendar.previousRegularTradingDay([date])
calendar.previousPartialTradingDay([date])
calendar.previousHoliday([date])
Trading Hours Methods
calendar.isRegularTradingHours([date])
calendar.isExtendedTradingHours([date])
calendar.isPartialTradingHours([date])
calendar.regularTradingHoursDuration()
calendar.extendedTradingHoursDuration()
calendar.partialTradingHoursDuration()
Trading Sessions Methods
calendar.isTradingSession([date], [extended])
calendar.isRegularTradingSession([date])
calendar.isExtendedTradingSession([date])
calendar.isPartialTradingSession([date])
calendar.tradingSession([date], [extended])
calendar.tradingSessions([date], [extended])
calendar.elapsedTradingSessions([date], [extended])
calendar.commencedTradingSessions([date], [extended])
calendar.remainingTradingSessions([date], [extended])
calendar.nextTradingSession([date], [extended])
calendar.previousTradingSession([date], [extended])
Trading Duration Methods
calendar.tradingHoursDuration([date], [extended])
calendar.timeElapsedInRegularTradingHours([date])
calendar.timeElapsedInExtendedTradingHours([date])
calendar.timeElapsedInPartialTradingHours([date])
calendar.timeElapsedInTradingDay([date], [extended])
calendar.timeRemainingInTradingDay([date], [extended])
calendar.tradingSessionDuration([date], [extended])
calendar.timeElapsedInTradingSession([date], [extended])
calendar.timeRemainingInTradingSession([date], [extended])
Moments and Timezones
Locally, dates and times are separate things. Across timezones, they are inextricably linked
and the logic gets complicated. Fincal uses sugar
and moment to simplify and enhance date parsing and comprehension.
Examples of moment creation:
calendar.currentTime();
calendar.here([date]);
fincal.here([date]);
calendar.there([date]);
calendar.there() == calendar.currentTime();
fincal.setTimezoneHere("America/Chicago");
calendar.here("Sep 1 2015 4:00 pm");
calendar.there("Monday 9:30am");
calendar.there({ year: 2015, month: 1, day: 1 });
calendar.there(calendar.here("Sep 1 2015 4:00 pm"));
calendar.here("Monday 9:30am").toDate() != calendar.there("Monday 9:30am").toDate();
calendar.here({ year: 2015, month: 1, day: 1 }).toDate() != calendar.there({ year: 2015, month: 1, day: 1 }).toDate();
var offset = (new Date()).getTime();
calendar.here(offset).toDate() == calendar.there(offset).toDate();
calendar.here("Sep 1 2015 4:00 pm").toDate() == calendar.there(calendar.here("Sep 1 2015 4:00 pm")).toDate();
calendar.here(new Date()).toDate() == calendar.there(new Date()).toDate();
How do I extend it?
The Calendar class consumes a standard market locale object interface.
var fincal = require("fincal");
var myCalendar = fincal.Calendar("name", { ... });
var locales = fincal.locales;
var someCalendar = fincal.some_locale = fincal["some_locale"] = fincal.calendar("some_locale");
fincal.import("Someplace", { ... });
var someplace = fincal.Someplace = fincal["Someplace"] = fincal.calendar("Someplace");
console.log(calendar.name);
console.log(calendar.locale);
To create a custom calendar, you just need to supply the Calendar constructor or fincal.import() method
with a compatible Locale object.
A locale begins by defining a timezone. Then regular trading days and regular trading hours are defined. There
are days and times trading USUALLY (but not necessarily) takes place. Outside of regular trading
hours, extendedTradingHours specify additional sessions (usually with limited participation). Some
regular trading days are holidays, and trading does not occur. In some markets, days before or after
holidays are partialTradingDays that observe partialTradingHours.
Example
var locale = {
timezone: "America/New_York",
regularTradingDays: "Weekday",
regularTradingHours: [
{ from: "9:30 am", to: "4:00 pm" }
],
extendedTradingHours: [
{ from: "4:00 am", to: "9:30 am" },
{ from: "4:00 pm", to: "8:00 pm" }
],
partialTradingDays: {
2015: {
November: [ 27 ],
December: [ 24 ]
}
},
partialTradingHours: [
{ from: "9:30 am", to: "1:00 pm" }
],
holidays: {
2015: {
January: [ 1 ],
April: [ 3, 6 ],
May: [ 1, 25 ],
December: [ 24, 25, 31 ]
}
}
};
var oneOff = new fincal.Calendar("new_york", locale);
fincal.import("new_york", locale);
var loaded = fincal.new_york;
License
Copyright (c) 2015, Jonathan Hollinger
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.