npm.io
1.6.0 • Published 5 months agoCLI

longleap-tools

Licence
MIT
Version
1.6.0
Deps
3
Size
55 kB
Vulns
0
Weekly
15
SummaryDependencyVersions

LongLeap Tools

Calculate monthly stock options expiration dates with market holiday handling and fetch historical stock data from Yahoo Finance.

Features

  • Calculate monthly option expiration dates (third Friday of each month)
  • Handle market holidays and weekend adjustments
  • Support for special market closures
  • Historical data available from year 2000 onwards
  • Fetch historical stock data, dividends, and stock splits from Yahoo Finance
  • CLI utility for batch downloading historical data to CSV files
  • All data sorted by date in ascending order
  • TypeScript support with type definitions
  • Comprehensive test coverage

Installation

npm install longleap-tools

Usage

import { 
  getMonthlyOptionExpirationDates, 
  isMarketHoliday, 
  isTradingDay,
  generateHolidays, 
  getEarliestSupportedYear,
  getHistoricalData,
  getDividends,
  getStockSplits
} from 'longleap-tools';

// Market Holiday and Option Expiration functionality
const earliestYear = getEarliestSupportedYear();
console.log(earliestYear); // 2000

const dates = getMonthlyOptionExpirationDates(2024, 2024);
console.log(dates);
// ['2024-01-19', '2024-02-16', '2024-03-15', ...]

const isHoliday = isMarketHoliday(new Date('2024-01-01'));
console.log(isHoliday); // true

const isTradingDay = isTradingDay(new Date('2024-01-02'));
console.log(isTradingDay); // true

const holidays = generateHolidays(2024, 2024);
console.log(holidays);
// ['2024-01-01', '2024-01-15', '2024-02-19', ...]

// Yahoo Finance functionality
const historicalData = await getHistoricalData('AAPL', new Date('2023-01-01'), new Date('2023-12-31'));
console.log(historicalData);
// [{date: Date, open: number, high: number, low: number, close: number, volume: number, adjClose: number}, ...]

const dividends = await getDividends('AAPL', new Date('2023-01-01'), new Date('2023-12-31'));
console.log(dividends);
// [{date: Date, amount: number}, ...]

const splits = await getStockSplits('AAPL', new Date('2000-01-01'), new Date());
console.log(splits);
// [{date: Date, splitRatio: string}, ...]

CLI Utility: Historical Data Downloader

The package includes a powerful command-line utility for batch downloading historical stock data from Yahoo Finance to CSV files. This is ideal for data analysis, portfolio tracking, backtesting, and research.

Installation & Setup

To use the CLI utility globally on your system:

# Clone the repository
git clone https://github.com/yourusername/longleap-tools.git
cd longleap-tools

# Install dependencies
npm install

# Build the project
npm run build

# Link CLI tool globally (optional, for global usage)
npm link

After running npm link, the download-historical-data command will be available globally in your terminal.

Quick Start
# Download year-to-date prices for SPY
download-historical-data --symbols SPY --range YTD

# Download last 5 years of dividend data for AAPL and MSFT
download-historical-data -s AAPL,MSFT -r 5Y -d dividends -o ./my-data
Command Line Arguments
Argument Short Description Required Default
--symbols -s Comma-separated list of stock symbols ✓ Yes -
--range -r Date range specification ✓ Yes -
--data-type -d Type of data to download No prices
--output -o Output folder path No ./data
Date Range Options

The --range argument supports the following formats:

Range Description Example Start Date
YTD Year to date (Jan 1 to today) 2026-01-01
1Y Last 1 year 2025-01-12
3Y Last 3 years 2023-01-12
5Y Last 5 years 2021-01-12
10Y Last 10 years 2016-01-12
20Y Last 20 years 2006-01-12
MAX Maximum available data 2000-01-01
YYYYMMDD-YYYYMMDD Custom date range (your dates)

Note: All data is limited to dates from 2000-01-01 onwards.

Custom Date Range Examples:

  • 20240101-20241231 - All of 2024
  • 20200301-20200331 - March 2020
  • 20100101-20231231 - 2010 through 2023
Data Types

Use the --data-type (or -d) flag to specify what type of data to download:

Prices (default)

Downloads OHLCV (Open, High, Low, Close, Volume) data plus adjusted close.

CSV Columns:

  • Date - Trading date (YYYY-MM-DD)
  • Open - Opening price
  • High - Highest price
  • Low - Lowest price
  • Close - Closing price
  • Volume - Trading volume
  • AdjClose - Adjusted closing price (accounts for splits/dividends)

Filename: {SYMBOL}_historical.csv

Dividends

Downloads dividend payment information.

CSV Columns:

  • Date - Ex-dividend date (YYYY-MM-DD)
  • Amount - Dividend amount per share

Filename: {SYMBOL}_dividends.csv

Splits

Downloads stock split information.

CSV Columns:

  • Date - Split date (YYYY-MM-DD)
  • SplitRatio - Split ratio (e.g., "2:1", "3:2")

Filename: {SYMBOL}_splits.csv

Usage Examples
Basic: Download Prices (Default)
# Download YTD prices for a single symbol
download-historical-data --symbols SPY --range YTD

# Download 1-year prices for multiple symbols
download-historical-data -s SPY,QQQ,NVDA -r 1Y
Download Dividends
# Download 5 years of dividend history
download-historical-data -s AAPL -r 5Y -d dividends

# Download dividends for multiple dividend-paying stocks
download-historical-data -s KO,PEP,JNJ,PG -r 10Y -d dividends -o ./dividends
Download Stock Splits
# Download all available split history
download-historical-data -s AAPL,TSLA,NVDA -r MAX -d splits

# Download recent splits
download-historical-data -s GOOGL -r 3Y -d splits
Custom Date Ranges
# Download specific date range
download-historical-data -s SPY -r 20240101-20241231

# Download data for a specific quarter
download-historical-data -s QQQ -r 20240401-20240630 -o ./q2-2024

# Download historical period
download-historical-data -s MSFT -r 20100101-20151231
All Date Range Options
# Year to date
download-historical-data -s AAPL -r YTD

# 1 year back
download-historical-data -s AAPL -r 1Y

# 3 years back
download-historical-data -s AAPL -r 3Y

# 5 years back
download-historical-data -s AAPL -r 5Y

# 10 years back
download-historical-data -s AAPL -r 10Y

# 20 years back
download-historical-data -s AAPL -r 20Y

# Maximum available (since 2000)
download-historical-data -s AAPL -r MAX
Specify Output Folder
# Download to custom folder
download-historical-data -s SPY -r 1Y -o ./my-data

# Organize by data type
download-historical-data -s AAPL -r 5Y -d dividends -o ./income-tracking
download-historical-data -s AAPL -r 5Y -d prices -o ./price-history
download-historical-data -s AAPL -r 5Y -d splits -o ./corporate-actions
Example Workflows
Portfolio Tracking

Download complete historical data for all portfolio holdings:

download-historical-data -s AAPL,MSFT,GOOGL,AMZN,NVDA -r MAX -d prices -o ./portfolio
download-historical-data -s AAPL,MSFT,GOOGL,AMZN,NVDA -r MAX -d dividends -o ./portfolio
download-historical-data -s AAPL,MSFT,GOOGL,AMZN,NVDA -r MAX -d splits -o ./portfolio
Recent Market Analysis

Download recent price data for sector analysis:

# Technology sector
download-historical-data -s AAPL,MSFT,GOOGL,META,NVDA -r 1Y -o ./tech-sector

# Financial sector
download-historical-data -s JPM,BAC,WFC,GS,MS -r 1Y -o ./financial-sector
Dividend Income Tracking

Download dividend history for income portfolio:

download-historical-data -s JNJ,PG,KO,PEP,MCD,WMT -r 10Y -d dividends -o ./dividend-income
Historical Adjustments

Download split history for price adjustment calculations:

download-historical-data -s AAPL,TSLA,NVDA,GOOGL,AMZN -r MAX -d splits -o ./splits-history
Output Format
CSV File Structure

All CSV files include a header row followed by data rows. Dates are in YYYY-MM-DD format and data is sorted in ascending order by date.

Example Price Data (SPY_historical.csv):

Date,Open,High,Low,Close,Volume,AdjClose
2024-01-02,475.12,478.45,474.89,477.32,65234100,477.32
2024-01-03,477.50,479.88,476.23,478.91,72156300,478.91
2024-01-04,479.00,480.12,477.65,479.45,68943200,479.45

Example Dividend Data (AAPL_dividends.csv):

Date,Amount
2024-02-09,0.24
2024-05-10,0.24
2024-08-12,0.25
2024-11-08,0.25

Example Split Data (NVDA_splits.csv):

Date,SplitRatio
2021-07-20,4:1
2024-06-07,10:1
File Naming Convention
  • Prices: {SYMBOL}_historical.csv
  • Dividends: {SYMBOL}_dividends.csv
  • Splits: {SYMBOL}_splits.csv
Error Handling

The CLI utility provides clear feedback:

✓ Successfully downloaded 252 records for SPY to ./data/SPY_historical.csv
⚠️  No dividend data found for BRK.B
✗ Error downloading INVALID: Symbol not found
  • Success: Shows record count and output file path
  • Warning: Indicates when no data is available (e.g., no dividends/splits)
  • Error: Displays specific error messages for failed downloads
Notes
  • The utility requires an active internet connection to fetch data from Yahoo Finance
  • Rate limiting may apply for large batches of symbols
  • Data availability depends on Yahoo Finance's data coverage
  • Some symbols may not have dividend or split data
  • Very old or delisted stocks may have limited data availability

Market Holidays

The following market holidays are included (from year 2000 onwards):

  • New Year's Day
  • Martin Luther King Jr. Day (Third Monday in January)
  • Presidents Day (Third Monday in February)
  • Good Friday
  • Memorial Day (Last Monday in May)
  • Juneteenth National Independence Day (June 19, since 2021)
  • Independence Day (July 4)
  • Labor Day (First Monday in September)
  • Thanksgiving Day (Fourth Thursday in November)
  • Christmas Day (December 25)
Holiday Observance Rules
  • If the holiday falls on a Saturday, it is usually observed on the preceding Friday
  • If the holiday falls on a Sunday, it is usually observed on the following Monday
Special Market Closures
  • September 11-14, 2001 (September 11 attacks)
  • October 29-30, 2012 (Hurricane Sandy)
  • December 5, 2018 (President George H.W. Bush Day of Mourning)
  • March 23, 2020 (COVID-19 Trading Floor Closure)
  • January 9, 2025 (President Jimmy Carter Day of Mourning)

API Reference

Market Holiday and Option Expiration Functions
getEarliestSupportedYear(): number

Returns the earliest year (2000) for which holiday data is available.

getMonthlyOptionExpirationDates(startYear: number, endYear: number): string[]

Returns an array of monthly option expiration dates between the specified years (inclusive).

  • Dates are in YYYY-MM-DD format
  • Throws error if years are before 2000
  • Throws error if start year is greater than end year
isMarketHoliday(date: Date): boolean

Checks if a given date is a market holiday.

  • Returns true if the date is a holiday, false otherwise
  • Throws error if date is before year 2000
generateHolidays(startYear: number, endYear: number): string[]

Generates a list of market holidays between the specified years.

  • Returns array of dates in YYYY-MM-DD format
  • Includes special market closures if within range
  • Throws error if years are before 2000
isTradingDay(date: Date): boolean

Checks if a given date is a trading day (not a weekend or market holiday).

  • Returns true if the date is a trading day, false otherwise
  • Throws error if date is before year 2000
Yahoo Finance Functions
getHistoricalData(symbol: string, startDate: Date, endDate: Date): Promise<YahooFinanceData[]>

Fetches historical stock data for the given symbol and date range.

  • Returns an array of objects containing date, open, high, low, close, volume, and adjClose
  • Data is sorted by date in ascending order
getDividends(symbol: string, startDate: Date, endDate: Date): Promise<Dividend[]>

Retrieves dividend data for the given symbol and date range.

  • Returns an array of objects containing date and amount
  • Data is sorted by date in ascending order
getStockSplits(symbol: string, startDate: Date, endDate: Date): Promise<StockSplit[]>

Obtains stock split information for the given symbol and date range.

  • Returns an array of objects containing date and splitRatio
  • Data is sorted by date in ascending order
Data Structures
YahooFinanceData
interface YahooFinanceData {
    date: Date;
    open: number;
    high: number;
    low: number;
    close: number;
    volume: number;
    adjClose: number;
}
Dividend
interface Dividend {
    date: Date;
    amount: number;
}
StockSplit
interface StockSplit {
    date: Date;
    splitRatio: string;
}

Error Handling

All functions that interact with external APIs (Yahoo Finance) use try-catch blocks to handle potential errors. If an error occurs during the API call or data processing, it will be thrown and should be caught and handled by the user of this library.

Data Accuracy and Limitations

  • Historical data, dividends, and stock splits are fetched from Yahoo Finance and are subject to their data accuracy and availability.
  • The library does not provide real-time data. There may be a delay in the most recent data points.
  • For very old or less frequently traded stocks, data might be limited or less accurate.

Performance Considerations

  • The functions fetching data from Yahoo Finance are asynchronous and return Promises. For large date ranges or multiple symbols, consider the potential impact on performance and rate limiting by the Yahoo Finance API.
  • Data is sorted in memory, which could impact performance for very large datasets.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

Version 1.6.0 (2026-01-12)
  • New Feature: Added CLI utility for batch downloading historical data to CSV files
  • Supports downloading prices, dividends, and stock splits
  • Flexible date range options: YTD, 1Y, 3Y, 5Y, 10Y, 20Y, MAX, and custom ranges
  • Command: download-historical-data with configurable output folders
  • Comprehensive documentation and usage examples
Version 1.5.2 (2026-01-07)
  • Fixed Yahoo Finance data download by upgrading yahoo-finance2 from v2.x to v3.11.2
  • Added ESLint support for improved code quality and consistency
  • Fixed security vulnerabilities in dependencies
Version 1.4.0
  • Added new isTradingDay function to check if a given date is a trading day
  • Updated documentation and tests to include the new function
Version 1.3.0
  • Refactored code to improve modularity: monthly options functions are now in a separate module
  • All existing functionality remains unchanged, but import structure may be affected for users importing specific functions
Version 1.2.0
  • Added sorting of all data (historical, dividends, splits) by date in ascending order
  • Improved error handling and data validation
  • Updated documentation with more comprehensive details
Version 1.1.0
  • Added support for fetching stock split data
  • Improved date parsing for all Yahoo Finance functions
Version 1.0.0
  • Initial release with support for market holidays, option expiration dates, and basic Yahoo Finance data fetching

Keywords

optionsexpirationmarketholidays