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 = ; // Get a market calendar for a localevar calendar = fincal = fincal"new_york" = fincalnew_york; // Simple interfacecalendar;calendar;calendar;calendar; // Examplescalendar;calendar;calendar;calendar;calendar;
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).
- Sugar-y date string (e.g. "Monday", "Last Friday in July", "Sep 1 2015 4:00pm")
- Valid date structure (e.g. { year: 2015, month: 1: day: 1 })
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
// Are markets open today (where today is 'today there')calendar; // Are markets open on a given date (there).calendar; // Are markets open now (in universal terms)calendar; // Are markets open at a specific date and time, and whether extended trading sessions count.calendar;
Trading Day Methods
// Is a regular trading day and is not a holidaycalendar // Is a trading day and is not a partial trading daycalendar // Is a regular trading day (though may be a holiday or a partial trading day)calendar // Is a partial trading daycalendar // Is a holidaycalendar // Next full or partial trading daycalendar // Next full trading daycalendar // Next regular trading day (though may be a holiday or a partial trading day)calendar // Next partial trading day (or false)calendar // Next holiday (or false)calendar // Previous full or partial trading daycalendar // Previous full trading daycalendar // Previous regular trading day (though may be a holiday or a partial trading day)calendar // Previous partial trading day (or false)calendar // Previous holiday (or false)calendar
Trading Hours Methods
// Is within regular trading hours (regardless of date)calendar // Is within extended trading hours (not including regular trading hours) (regardless of date)calendar // Is within partial trading hours (regardless of date)calendar // Milliseconds of trading time during regular trading sessionscalendar // Milliseconds of trading time during extended trading sessionscalendar // Milliseconds of trading time during a partial trading daycalendar
Trading Sessions Methods
// Is a trading day and within applicable trading hourscalendar // Is full trading day and within regular trading hourscalendar // Is full trading day and within extended trading hourscalendar // Is partial trading day and within partial trading hourscalendar // Get trading sessioncalendar // Get all trading sessions for datecalendar // Get elapsed trading sessions for datecalendar // Get commenced trading sessions for datecalendar // Get remaining trading sessions for datecalendar // Get next trading sessioncalendar // Get previous trading sessioncalendar
Trading Duration Methods
// Milliseconds of trading time for datecalendar // Milliseconds elapsed of regular trading time (regardless of date)calendar // Milliseconds elapsed of extended trading time (regardless of date)calendar // Milliseconds elapsed of partial trading time (regardless of date)calendar // Milliseconds elapsed of trading for specific datecalendar // Milliseconds remaining of trading time for specific datecalendar // Milliseconds of trading time in trading sessioncalendar // Milliseconds of trading time elapsed in trading sessioncalendar // Milliseconds of trading time remaining in trading sessioncalendar
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:
// Current time in localecalendar; // Create a moment herecalendar;fincal; // Create a moment therecalendar;calendar == calendar; // Maybe the code is running somewhere else than "here".fincal; // Examplescalendar;calendar;calendar;calendar; // Relative Formatscalendar != calendar;calendar != calendar; // Universal Formatsvar offset = ;calendar == calendar;calendar == calendar;calendar == calendar;
How do I extend it?
The Calendar class consumes a standard market locale object interface.
var fincal = ; // Calendar classvar myCalendar = fincal; // Packaged locale names are put in an array and given their own root-level propertiesvar locales = fincallocales;var someCalendar = fincalsome_locale = fincal"some_locale" = fincal; // Don't like what's packaged? Roll your own. Will overwrite other calendars with same name.fincal;var someplace = fincalSomeplace = fincal"Someplace" = fincal; // Calendar metadataconsole; // > "New York"console; // > [Object]
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 = /* The timezone for the locale in format [Continent]/[City]. */ timezone: "America/New_York" /* The base assumption of what constitutes a trading day. */ regularTradingDays: "Weekday" /* The base assumption of what constitutes regular trading hours. */ regularTradingHours: from: "9:30 am" to: "4:00 pm" /* Extended trading hours on full trading days. */ extendedTradingHours: from: "4:00 am" to: "9:30 am" from: "4:00 pm" to: "8:00 pm" /* Days on which different hours than regularTradingHours are observed. */ partialTradingDays: 2015: November: 27 December: 24 /* Trading hours used on a partial trading day. */ partialTradingHours: from: "9:30 am" to: "1:00 pm" /* Days on which no trading takes place. These dates may otherwise be regularTradingDays. */ holidays: 2015: January: 1 April: 3 6 May: 1 25 December: 24 25 31 ; var oneOff = "new_york" locale; fincal;var loaded = fincalnew_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.