sec-13f-holdings

Parse SEC Form 13F information tables and diff two quarters of holdings. Pure JavaScript, Node built-ins only, zero dependencies.

Usage

const { parse13FInfoTable, diffHoldings } = require('./src/core');

const previous = parse13FInfoTable(previousQuarterXml);
const current = parse13FInfoTable(currentQuarterXml);
const changes = diffHoldings(previous, current);

parse13FInfoTable(xmlString)

Input: the information-table XML of a 13F-HR filing. Default namespace, any prefix (ns1:, n1:, ...) or no namespace are all accepted.

Output: an array with one object per <infoTable> entry:

{ issuer, titleOfClass, cusip, valueUsd, shares, shareType,
  discretion, votingSole, votingShared, votingNone }

Numbers are JS numbers. Missing numeric tags become 0, missing text tags become null. It never throws on missing optional tags; non-string input returns [].

diffHoldings(previousRows, currentRows)

Input: two arrays of rows as returned by parse13FInfoTable (only cusip, issuer and shares are used).

Output: an array of { cusip, issuer, status, previousShares, currentShares, sharesDelta, pctChange }, keyed by CUSIP.

• status: new, exited, increased, decreased or unchanged
• pctChange: (delta / previousShares) * 100 rounded to 2 decimals, or null when there were no previous shares
• sorted by absolute sharesDelta descending, ties by cusip ascending

If a CUSIP appears on several lines of one filing, its shares are summed.

fetchLatest13F(cik, opts) (src/fetch.js)

Fetches the raw information-table XML of the latest 13F-HR filing(s) from EDGAR. It only contacts sec.gov hosts, sends the opts.userAgent you supply (required; the SEC asks for a descriptive value with contact details) and waits at least 250 ms between requests (at most 4 per second). opts.count selects how many recent filings to fetch (default 1). The result is an array of XML strings, newest first. It is not covered by the offline tests.

Tests

npm test

Limitations

• Regex-based extraction, not a full XML parser. It handles the structure EDGAR produces (including CDATA and standard entities) but not arbitrary XML.
• valueUsd is the <value> tag as filed. Filings before 2023 reported it in thousands of dollars; newer ones report whole dollars. It is not converted.
• Rows are matched by CUSIP only. Put/call lines and share type (SH vs PRN) are not distinguished in the diff.
• Amendments (13F-HR/A) are not fetched, and fetchLatest13F does not merge filings that split the table across several XML files.
• 13F data is delayed up to 45 days after quarter end and excludes short positions and most non-US-listed securities.

Disclaimer

This tool reports public SEC filings as-is. It is not investment advice, makes no prediction about any security, and may contain errors or omissions (13F data is delayed and excludes short positions). Use at your own risk; verify against the original filing on sec.gov.

License

MIT