sec-edgar-api 0.0.1

package/README.md

@@ -0,0 +1,27 @@
+# sec-edgar-api
+
+Fetch and parse earnings reports and other documents filed with the SEC using the EDGAR API.
+This package is focused on the earnings reports for stock analysis.
+
+## Resolvers
+
+The main problem with the edgar API is that the property names and data provided are not uniform. You have to deal with companies omitting important data
+in some filings, or using different property keys for the same data point.
+
+Resolvers attempt to get information from each report and output a uniform interface. The resolvers will calculate missing data if there is other data that can be used to derive from.
+
+| Resolver                              | Formula used to derive values                                                                                            |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| resolveAssetCurrent                   | assetTotal - assetNonCurrent = assetCurrent                                                                              |
+| resolveAssetNonCurrentPpeGross        | assetNonCurrentPPENet + expenseDepreciationAccumulated = assetNonCurrentPpeGross                                         |
+| resolveCashFlowCapex                  | Q1 + Q2 + Q3 + Q4 = FY (if FY known, divides evenly between missing quarters)                                            |
+| resolveCashFlowFree                   | cashFlowOperating - cashFlowCapex = cashFlowFree                                                                         |
+| resolveCashFlowOperating              | incomeNet + expenseDepreciation - changeInWorkingCapitalNonCash = cashFlowOperating                                      |
+| resolveCashFlowWorkingCapitalNonCash  | (assetCurrent - assetCurrentCashEquivalents) - (liabilityCurrent - liabilityCurrentDebt) = cashFlowWorkingCapitalNonCash |
+| resolveEbit                           | expenseDepreciation + ebitda = ebit                                                                                      |
+| resolveExpenseDepreciation            | (expenseDepreciationFY / assetNonCurrentPpeGrossFY) x assetNonCurrentPpeGross = expenseDepreciation                      |
+| resolveExpenseOperating               | revenueTotal - incomeOperating - revenueCost = expenseOperating                                                          |
+| resolveExpenseTotal                   | revenueTotal - incomeNet = expenseTotal                                                                                  |
+| resolveFiscalYearCumulativeProperties | Q1 + Q2 + Q3 + Q4 = FY (for quarterly properties that add to annual)                                                     |
+| resolveQ4FiscalYearMatchingProperties | Q4 = FY (for non-cumulative properties such as sharesOutstanding)                                                        |
+| resolveRevenueTotal                   | revenueCost + profitGross = revenueTotal                                                                                 |

package/build/index.d.ts

@@ -0,0 +1,21 @@
+import FactFileReader from './services/FactFileReader';
+import ReportParser from './services/ReportParser';
+import SecEdgarApi from './services/SecEdgarApi';
+/**
+ * Takes company facts data from the SEC and translates them to
+ * reports as json objects.
+ */
+declare const reportParser: ReportParser;
+/**
+ * Reads files from the companyfacts directory (which can be downloaded
+ * using secEdgarApi.downloadCompanyFacts()).
+ */
+declare const factFileReader: FactFileReader;
+/**
+ * Gets company reports and filings from the SEC EDGAR API. Requests are
+ * throttled with 120ms delay between requests to avoid rate limiting.
+ *
+ * @see https://www.sec.gov/edgar/sec-api-documentation
+ */
+declare const secEdgarApi: SecEdgarApi;
+export { reportParser, factFileReader, secEdgarApi };

package/build/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secEdgarApi = exports.factFileReader = exports.reportParser = void 0;
+var FactFileReader_1 = require("./services/FactFileReader");
+var ReportParser_1 = require("./services/ReportParser");
+var SecEdgarApi_1 = require("./services/SecEdgarApi");
+/**
+ * Takes company facts data from the SEC and translates them to
+ * reports as json objects.
+ */
+var reportParser = new ReportParser_1.default();
+exports.reportParser = reportParser;
+/**
+ * Reads files from the companyfacts directory (which can be downloaded
+ * using secEdgarApi.downloadCompanyFacts()).
+ */
+var factFileReader = new FactFileReader_1.default();
+exports.factFileReader = factFileReader;
+/**
+ * Gets company reports and filings from the SEC EDGAR API. Requests are
+ * throttled with 120ms delay between requests to avoid rate limiting.
+ *
+ * @see https://www.sec.gov/edgar/sec-api-documentation
+ */
+var secEdgarApi = new SecEdgarApi_1.default();
+exports.secEdgarApi = secEdgarApi;

package/build/services/FactFileReader/FactFileReader.d.ts

@@ -0,0 +1,30 @@
+import { CompanyFactListData } from '../../types/company-facts.type';
+interface FileManager {
+    readFileSync(path: string, encoding: string | object): string;
+}
+interface FactFileReaderArgs {
+    companyFactsDirname?: string;
+    cikBySymbol?: Record<string, number>;
+    fileManager?: FileManager;
+}
+interface ReadFactFileParams {
+    symbol: string;
+    companyFactsDirname: string;
+}
+/**
+ * Reads files from companyfacts folder from sec
+ */
+export default class FactFileReader {
+    private readonly fileManager;
+    private readonly cikBySymbol;
+    constructor(args?: FactFileReaderArgs);
+    getCikBySymbol(): Record<string, number>;
+    /**
+     * opens fact file from companyfacts directory
+     *
+     * @param symbol ex: AAPL
+     * @param companyFactsDirname ex: path.resolve(__dirname, './downloads/companyfacts')
+     */
+    readFactFile(params: ReadFactFileParams): CompanyFactListData;
+}
+export {};

package/build/services/FactFileReader/FactFileReader.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var fs = require("fs");
+var cik_by_symbol_1 = require("../../util/cik-by-symbol");
+/**
+ * Reads files from companyfacts folder from sec
+ */
+var FactFileReader = /** @class */ (function () {
+    function FactFileReader(args) {
+        var _a = args !== null && args !== void 0 ? args : {}, _b = _a.fileManager, fileManager = _b === void 0 ? fs : _b, _c = _a.cikBySymbol, cikBySymbol = _c === void 0 ? cik_by_symbol_1.default : _c;
+        this.fileManager = fileManager;
+        this.cikBySymbol = cikBySymbol;
+    }
+    FactFileReader.prototype.getCikBySymbol = function () {
+        return this.cikBySymbol;
+    };
+    /**
+     * opens fact file from companyfacts directory
+     *
+     * @param symbol ex: AAPL
+     * @param companyFactsDirname ex: path.resolve(__dirname, './downloads/companyfacts')
+     */
+    FactFileReader.prototype.readFactFile = function (params) {
+        var _a;
+        var companyFactsDirname = params.companyFactsDirname, symbol = params.symbol;
+        var cik = (_a = this.cikBySymbol[symbol]) !== null && _a !== void 0 ? _a : null;
+        if (!cik) {
+            throw new Error("No cik found for symbol ".concat(symbol));
+        }
+        var cikStr = cik.toString().padStart(10, '0');
+        var result = this.fileManager.readFileSync("".concat(companyFactsDirname, "/CIK").concat(cikStr, ".json"), 'utf-8');
+        return JSON.parse(result);
+    };
+    return FactFileReader;
+}());
+exports.default = FactFileReader;

package/build/services/FactFileReader/index.d.ts

@@ -0,0 +1,2 @@
+import FactFileReader from './FactFileReader';
+export default FactFileReader;

package/build/services/FactFileReader/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var FactFileReader_1 = require("./FactFileReader");
+exports.default = FactFileReader_1.default;

package/build/services/ReportParser/FactIterator.d.ts

@@ -0,0 +1,18 @@
+import { CompanyFactListData, FactValue } from '../../types/company-facts.type';
+export interface IterateFactsCallbackData {
+    factValue: FactValue;
+    propertyName: string;
+    description: string;
+    label: string;
+    unit: string;
+    taxonomy: string;
+    stopIteration: () => void;
+}
+export default class FactIterator {
+    /**
+     * Avoids deep nesting logic while iteratating through company facts
+     *
+     * @param callback called on each company fact.
+     */
+    iterateCompanyFacts(companyFactListData: Pick<CompanyFactListData, 'facts'>, callback: (data: IterateFactsCallbackData) => void): void;
+}

package/build/services/ReportParser/FactIterator.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var FactIterator = /** @class */ (function () {
+    function FactIterator() {
+    }
+    /**
+     * Avoids deep nesting logic while iteratating through company facts
+     *
+     * @param callback called on each company fact.
+     */
+    FactIterator.prototype.iterateCompanyFacts = function (companyFactListData, callback) {
+        var facts = companyFactListData.facts;
+        var shouldContinue = true;
+        var stopIteration = function () {
+            shouldContinue = false;
+        };
+        for (var taxonomy in facts) {
+            var factByPropertyName = facts[taxonomy];
+            for (var propertyName in factByPropertyName) {
+                var _a = factByPropertyName[propertyName], description = _a.description, label = _a.label, units = _a.units;
+                for (var unit in units) {
+                    var factValues = units[unit];
+                    for (var _i = 0, factValues_1 = factValues; _i < factValues_1.length; _i++) {
+                        var factValue = factValues_1[_i];
+                        callback({ factValue: factValue, taxonomy: taxonomy, propertyName: propertyName, unit: unit, description: description, label: label, stopIteration: stopIteration });
+                        if (!shouldContinue)
+                            return;
+                    }
+                }
+            }
+        }
+    };
+    return FactIterator;
+}());
+exports.default = FactIterator;

package/build/services/ReportParser/PropertyResolver.d.ts

@@ -0,0 +1,25 @@
+import ReportWrapper from '../ReportParser/ReportWrapper';
+import resolvers from './resolvers';
+export default class PropertyResolver {
+    private readonly resolvers;
+    constructor(args?: {
+        resolvers: {
+            resolveAssetNonCurrentPPEGross: typeof import("./resolvers/resolve-asset-non-current-ppe-gross").resolveAssetNonCurrentPPEGross;
+            resolveExpenseDepreciation: typeof import("./resolvers/resolve-expense-depreciation").resolveExpenseDepreciation;
+            resolveExpenseOperating: typeof import("./resolvers/resolve-expense-operating").resolveExpenseOperating;
+            resolveCashFlowFree: typeof import("./resolvers/resolve-cash-flow-free").resolveCashFlowFree;
+            resolveEbit: typeof import("./resolvers/resolve-ebit").resolveEbit;
+            resolveAssetCurrent: typeof import("./resolvers/resolve-asset-current").resolveAssetCurrent;
+            resolveCashFlowCapex: typeof import("./resolvers/resolve-cash-flow-capex").resolveCashFlowCapex;
+            resolveFiscalYearCumulativeProperties: typeof import("./resolvers/resolve-fiscal-year-cumulative-properties").resolveFiscalYearCumulativeProperties;
+            resolveRevenueTotal: typeof import("./resolvers/resolve-revenue-total").resolveRevenueTotal;
+            resolveExpenseTotal: typeof import("./resolvers/resolve-expense-total").resolveExpenseTotal;
+            resolveCashFlowOperating: typeof import("./resolvers/resolve-cash-flow-operating").resolveCashFlowOperating;
+            resolveLiabilityCurrent: typeof import("./resolvers/resolve-liability-current").resolveLiabilityCurrent;
+            resolveQ4FiscalYearMatchingProperties: typeof import("./resolvers/resolve-q4-fiscal-year-matching-properties").resolveQ4FiscalYearMatchingProperties;
+            resolveCashFlowWorkingCapitalNonCash: typeof import("./resolvers/resolve-cash-flow-working-capital-non-cash").resolveCashFlowWorkingCapitalNonCash;
+        };
+    });
+    getDefaultResolvers(): typeof resolvers;
+    resolveAll(reports: ReportWrapper[] | Map<string, ReportWrapper>): void;
+}

package/build/services/ReportParser/PropertyResolver.js

@@ -0,0 +1,44 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var resolvers_1 = require("./resolvers");
+var PropertyResolver = /** @class */ (function () {
+    function PropertyResolver(args) {
+        if (args === void 0) { args = { resolvers: resolvers_1.default }; }
+        this.resolvers = args.resolvers;
+    }
+    PropertyResolver.prototype.getDefaultResolvers = function () {
+        return __assign({}, this.resolvers);
+    };
+    PropertyResolver.prototype.resolveAll = function (reports) {
+        var _this = this;
+        reports.forEach(function (report) {
+            _this.resolvers.resolveQ4FiscalYearMatchingProperties(report);
+            _this.resolvers.resolveFiscalYearCumulativeProperties(report);
+            _this.resolvers.resolveRevenueTotal(report);
+            _this.resolvers.resolveExpenseTotal(report);
+            _this.resolvers.resolveAssetCurrent(report);
+            _this.resolvers.resolveLiabilityCurrent(report);
+            _this.resolvers.resolveCashFlowWorkingCapitalNonCash(report);
+            _this.resolvers.resolveExpenseOperating(report);
+            _this.resolvers.resolveAssetNonCurrentPPEGross(report);
+            _this.resolvers.resolveEbit(report);
+            _this.resolvers.resolveExpenseDepreciation(report);
+            _this.resolvers.resolveCashFlowOperating(report);
+            _this.resolvers.resolveCashFlowCapex(report);
+            _this.resolvers.resolveCashFlowFree(report);
+        });
+    };
+    return PropertyResolver;
+}());
+exports.default = PropertyResolver;

package/build/services/ReportParser/ReportParser.d.ts

@@ -0,0 +1,53 @@
+import { CompanyFactListData, ReportRaw, ReportTranslated } from '../../types';
+import { IterateFactsCallbackData } from './FactIterator';
+import PropertyResolver from './PropertyResolver';
+import ReportRawParser, { ParseReportsOptions } from './ReportRawParser';
+import ReportWrapper from './ReportWrapper';
+interface ReportParserArgs {
+    reportRawParser?: ReportRawParser;
+    propertyResolver?: PropertyResolver;
+    keyTranslator?: Record<string, string[]>;
+}
+type TranslateRawReportsCallback<T> = (report: T extends undefined ? ReportTranslated : Record<keyof T, string | number>, reportRaw: ReportRaw, keyTranslator: T) => any;
+/**
+ * Takes company facts data from the SEC and translates them to reports as json objects.
+ */
+export default class ReportParser {
+    private readonly reportRawParser;
+    private readonly keyTranslator;
+    private readonly propertyResolver;
+    constructor(args?: ReportParserArgs);
+    /**
+     * translates company facts to ReportTranslated. To translate to custom report, use parseReportsRaw and translateReportsRaw
+     *
+     * This includes only 10-K and 10-Q annual and quarterly reports. To include all reports, use parseReportsRaw
+     *
+     * @param companyFactListData This is the json file contents of CIK[number].json file from the SEC website. You can find these using their API or by downloading the companyfacts.zip file: https://www.sec.gov/edgar/sec-api-documentation
+     */
+    parseReports(companyFactListData: Pick<CompanyFactListData, 'facts'>): ReportWrapper[];
+    /**
+     * Same as parseReports but accepts ReportRaw[] instead of CompanyFactListData
+     */
+    parseReportsFromRaw(reportsRaw: ReportRaw[]): ReportWrapper[];
+    /**
+     * Note that this includes all reports by default, not just annual and quarterly. use options.reportsToInclude to filter
+     *
+     * @see https://www.sec.gov/edgar/sec-api-documentation
+     */
+    parseReportsRaw(companyFactListData: Pick<CompanyFactListData, 'facts'>, options?: ParseReportsOptions): ReportRaw[];
+    /**
+     * Avoids deep nesting logic while iteratating through company facts
+     *
+     * @param callback called on each company fact.
+     */
+    iterateCompanyFacts(companyFactListData: Pick<CompanyFactListData, 'facts'>, callback: (data: IterateFactsCallbackData) => void): void;
+    /**
+     * Translate ReportRaw to ReportTranslated by default, but can be used to translate to any object using both the callback and keyTranslator
+     *
+     * @param reportsRaw this is the output of parseReportsRaw
+     * @param callback this is called for each report and can be used to modify the report. This gets the report built by keyTranslator if provided, otherwise ReportTranslated
+     * @param keyTranslator this is iterated through to build the report using the keys. If the ReportRaw has a key that matches a key in the keyTranslator, the value is used. if not, the value is null
+     */
+    translateReportsRaw<C extends TranslateRawReportsCallback<T>, T extends undefined | object = undefined>(reportsRaw: ReportRaw[], callback?: C, keyTranslator?: T): C extends unknown ? ReportTranslated[] : ReturnType<C>[];
+}
+export {};

package/build/services/ReportParser/ReportParser.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var key_translations_1 = require("../../util/key-translations");
+var PropertyResolver_1 = require("./PropertyResolver");
+var ReportRawParser_1 = require("./ReportRawParser");
+var ReportWrapper_1 = require("./ReportWrapper");
+/**
+ * Takes company facts data from the SEC and translates them to reports as json objects.
+ */
+var ReportParser = /** @class */ (function () {
+    function ReportParser(args) {
+        var _a = args !== null && args !== void 0 ? args : {}, _b = _a.reportRawParser, reportRawParser = _b === void 0 ? new ReportRawParser_1.default() : _b, _c = _a.propertyResolver, propertyResolver = _c === void 0 ? new PropertyResolver_1.default() : _c, _d = _a.keyTranslator, keyTranslator = _d === void 0 ? key_translations_1.default : _d;
+        this.reportRawParser = reportRawParser;
+        this.keyTranslator = keyTranslator;
+        this.propertyResolver = propertyResolver;
+    }
+    /**
+     * translates company facts to ReportTranslated. To translate to custom report, use parseReportsRaw and translateReportsRaw
+     *
+     * This includes only 10-K and 10-Q annual and quarterly reports. To include all reports, use parseReportsRaw
+     *
+     * @param companyFactListData This is the json file contents of CIK[number].json file from the SEC website. You can find these using their API or by downloading the companyfacts.zip file: https://www.sec.gov/edgar/sec-api-documentation
+     */
+    ReportParser.prototype.parseReports = function (companyFactListData) {
+        var reportsRaw = this.reportRawParser.parseReports(companyFactListData, {
+            reportsToInclude: ['ANNUAL', 'QUARTERLY'],
+        });
+        return this.parseReportsFromRaw(reportsRaw);
+    };
+    /**
+     * Same as parseReports but accepts ReportRaw[] instead of CompanyFactListData
+     */
+    ReportParser.prototype.parseReportsFromRaw = function (reportsRaw) {
+        var reportByYearQuarter = new Map();
+        var reportsRawFiltered = reportsRaw.filter(function (reportRaw) {
+            return reportRaw.reportType === 'ANNUAL' || reportRaw.reportType === 'QUARTERLY';
+        });
+        this.translateReportsRaw(reportsRawFiltered, function (report, reportRaw) {
+            var fiscalPeriod = report.fiscalPeriod, fiscalYear = report.fiscalYear;
+            var keyReport = "".concat(fiscalYear, "_").concat(fiscalPeriod);
+            reportByYearQuarter.set(keyReport, new ReportWrapper_1.default(report, reportRaw, reportByYearQuarter));
+            return report;
+        });
+        var reportWrappers = Array.from(reportByYearQuarter.values());
+        this.propertyResolver.resolveAll(reportWrappers);
+        return reportWrappers;
+    };
+    /**
+     * Note that this includes all reports by default, not just annual and quarterly. use options.reportsToInclude to filter
+     *
+     * @see https://www.sec.gov/edgar/sec-api-documentation
+     */
+    ReportParser.prototype.parseReportsRaw = function (companyFactListData, options) {
+        return this.reportRawParser.parseReports(companyFactListData, options);
+    };
+    /**
+     * Avoids deep nesting logic while iteratating through company facts
+     *
+     * @param callback called on each company fact.
+     */
+    ReportParser.prototype.iterateCompanyFacts = function (companyFactListData, callback) {
+        this.reportRawParser.iterateCompanyFacts(companyFactListData, callback);
+    };
+    /**
+     * Translate ReportRaw to ReportTranslated by default, but can be used to translate to any object using both the callback and keyTranslator
+     *
+     * @param reportsRaw this is the output of parseReportsRaw
+     * @param callback this is called for each report and can be used to modify the report. This gets the report built by keyTranslator if provided, otherwise ReportTranslated
+     * @param keyTranslator this is iterated through to build the report using the keys. If the ReportRaw has a key that matches a key in the keyTranslator, the value is used. if not, the value is null
+     */
+    ReportParser.prototype.translateReportsRaw = function (reportsRaw, callback, keyTranslator) {
+        var keyTranslations = (keyTranslator !== null && keyTranslator !== void 0 ? keyTranslator : this.keyTranslator);
+        var reports = [];
+        reportsRaw.forEach(function (reportRaw) {
+            var reportNew = {};
+            // iterate translation keys, ensuring same order and priority
+            for (var key in keyTranslations) {
+                var keysRaw = keyTranslations[key];
+                reportNew[key] = null;
+                for (var _i = 0, keysRaw_1 = keysRaw; _i < keysRaw_1.length; _i++) {
+                    var keyRaw = keysRaw_1[_i];
+                    if (reportRaw[keyRaw] === undefined)
+                        continue;
+                    reportNew[key] = reportRaw[keyRaw];
+                    break;
+                }
+            }
+            var reportFiltered = callback
+                ? callback(reportNew, reportRaw, keyTranslations)
+                : reportNew;
+            reports.push(reportFiltered);
+        });
+        return reports;
+    };
+    return ReportParser;
+}());
+exports.default = ReportParser;

package/build/services/ReportParser/ReportRawParser.d.ts

@@ -0,0 +1,34 @@
+import { CompanyFactListData } from '../../types/company-facts.type';
+import { ReportRaw, ReportType } from '../../types/report-raw.type';
+import FactIterator, { IterateFactsCallbackData } from './FactIterator';
+interface ReportRawParserArgs {
+    factIterator?: FactIterator;
+}
+export interface ParseReportsOptions {
+    /**
+     * Instantaneous data may be filed later than the original filing date.
+     * It is flagged by "I" at the end of the frame property. defaults to true. see https://www.sec.gov/edgar/sec-api-documentation
+     * */
+    mergeInstantaneousData?: boolean;
+    reportsToInclude?: ReportType | ReportType[] | null;
+}
+/**
+ * @see https://www.sec.gov/edgar/sec-api-documentation
+ */
+export default class ReportRawParser {
+    private readonly factIterator;
+    constructor(args?: ReportRawParserArgs);
+    /**
+     * Avoids deep nesting logic while iteratating through company facts
+     *
+     * @param callback called on each company fact.
+     */
+    iterateCompanyFacts(companyFactListData: Pick<CompanyFactListData, 'facts'>, callback: (data: IterateFactsCallbackData) => void): void;
+    /**
+     * Returns raw reports in ascending order by report date. if date is the same, priority is filed date, frame, form
+     */
+    parseReports(companyFactListData: Pick<CompanyFactListData, 'facts'>, options?: ParseReportsOptions): ReportRaw[];
+    private getReportType;
+    private getFiscalYear;
+}
+export {};

package/build/services/ReportParser/ReportRawParser.js

@@ -0,0 +1,154 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var FactIterator_1 = require("./FactIterator");
+/**
+ * @see https://www.sec.gov/edgar/sec-api-documentation
+ */
+var ReportRawParser = /** @class */ (function () {
+    function ReportRawParser(args) {
+        var _a = (args !== null && args !== void 0 ? args : {}).factIterator, factIterator = _a === void 0 ? new FactIterator_1.default() : _a;
+        this.factIterator = factIterator;
+    }
+    /**
+     * Avoids deep nesting logic while iteratating through company facts
+     *
+     * @param callback called on each company fact.
+     */
+    ReportRawParser.prototype.iterateCompanyFacts = function (companyFactListData, callback) {
+        this.factIterator.iterateCompanyFacts(companyFactListData, callback);
+    };
+    /**
+     * Returns raw reports in ascending order by report date. if date is the same, priority is filed date, frame, form
+     */
+    ReportRawParser.prototype.parseReports = function (companyFactListData, options) {
+        var _this = this;
+        var _a = options !== null && options !== void 0 ? options : {}, reportsToInclude = _a.reportsToInclude, mergeInstantaneousData = _a.mergeInstantaneousData;
+        // default to all report types
+        var reportsToIncludeSet = reportsToInclude
+            ? new Set(Array.isArray(reportsToInclude) ? reportsToInclude : [reportsToInclude])
+            : null;
+        // for getting the earliest filed date for each report
+        var datesFiledByDateForm = new Map();
+        // for mapping individual properties to the report
+        var reportsByKey = new Map();
+        // fiscal period only provided for filed date, used to map to later assign for quarter end date
+        var monthsFiledByFiscalPeriod = new Map();
+        // iterate individual properties AKA "facts"
+        this.iterateCompanyFacts(companyFactListData, function (_a) {
+            var _b, _c, _d, _e, _f, _g, _h;
+            var factValue = _a.factValue, propertyName = _a.propertyName, taxonomy = _a.taxonomy;
+            var filed = factValue.filed, val = factValue.val, form = factValue.form, fp = factValue.fp, dateReport = factValue.end;
+            // get frame for keys and to merge instantaneous data
+            var isInstantaneousData = (_c = (_b = factValue.frame) === null || _b === void 0 ? void 0 : _b.endsWith('I')) !== null && _c !== void 0 ? _c : false;
+            var isMergableFrame = (mergeInstantaneousData !== null && mergeInstantaneousData !== void 0 ? mergeInstantaneousData : true) && isInstantaneousData;
+            var frame = isMergableFrame ? (_d = factValue.frame) === null || _d === void 0 ? void 0 : _d.substring(0, factValue.frame.length - 1) : factValue.frame;
+            // keys to map report and file dates
+            var keyDateForm = "".concat(dateReport, "_").concat(form);
+            var keyReport = "".concat(frame, "_").concat(keyDateForm);
+            // set earliest date filed
+            var dateFiledPrev = (_e = datesFiledByDateForm.get(keyDateForm)) !== null && _e !== void 0 ? _e : filed;
+            var dateFiled = filed < dateFiledPrev ? filed : dateFiledPrev;
+            datesFiledByDateForm.set(keyDateForm, dateFiled);
+            // if frame is undefined, the value is no longer the most recent
+            if (!frame)
+                return;
+            var isTTM = frame.substring(6, 8).length !== 2;
+            var reportType = _this.getReportType({ form: form, taxonomy: taxonomy, isTTM: isTTM });
+            var isReportToInclude = (_f = reportsToIncludeSet === null || reportsToIncludeSet === void 0 ? void 0 : reportsToIncludeSet.has(reportType)) !== null && _f !== void 0 ? _f : true;
+            if (!isReportToInclude)
+                return;
+            // set the month filed, will be used to get the fiscal period and year
+            if (reportType === 'QUARTERLY' || reportType === 'ANNUAL') {
+                var monthFiled = Number(filed.substring(5, 7));
+                monthsFiledByFiscalPeriod.set(fp, ((_g = monthsFiledByFiscalPeriod.get(fp)) !== null && _g !== void 0 ? _g : new Set()).add(monthFiled));
+            }
+            var report = (_h = reportsByKey.get(keyReport)) !== null && _h !== void 0 ? _h : {
+                dateReport: dateReport,
+                dateFiled: dateFiled,
+                form: form,
+                isTTM: isTTM,
+                frame: frame,
+                taxonomy: taxonomy,
+                reportType: reportType,
+                // these will be updated
+                fiscalPeriod: 'FY',
+                fiscalYear: 0,
+            };
+            reportsByKey.set(keyReport, report);
+            // update earliest date filed
+            report.dateFiled = dateFiled;
+            report[propertyName] = val;
+        });
+        // end date is typically the month before the filed date, so subtract 1, set to 12 if 0
+        var fiscalPeriodsByMonth = new Map();
+        monthsFiledByFiscalPeriod.forEach(function (monthsSet, fiscalPeriod) {
+            monthsSet.forEach(function (month) { return fiscalPeriodsByMonth.set(month - 1 || 12, fiscalPeriod); });
+        });
+        // set fiscal period and year, then merge by year_quarter, because some reports have end dates a couple days apart
+        var reportsByYearPeriod = new Map();
+        reportsByKey.forEach(function (report) {
+            var _a;
+            var dateReport = report.dateReport, reportType = report.reportType;
+            var monthReport = Number(dateReport.substring(5, 7));
+            var fiscalPeriod = (_a = fiscalPeriodsByMonth.get(monthReport)) !== null && _a !== void 0 ? _a : 'FY';
+            // Q4 is always FY, so needs to be changed to Q4 (comes from fp property in fact)
+            report.fiscalPeriod = reportType === 'QUARTERLY' && fiscalPeriod === 'FY' ? 'Q4' : fiscalPeriod;
+            report.fiscalYear = _this.getFiscalYear({ dateReport: dateReport, reportType: reportType, fiscalPeriod: report.fiscalPeriod });
+            var keyReport = "".concat(report.fiscalYear, "_").concat(report.fiscalPeriod);
+            var reportPrev = reportsByYearPeriod.get(keyReport);
+            // if a report was already assigned to this key, merge and use the latest dateReport
+            if (reportPrev) {
+                var dateReport_1 = report.dateReport > reportPrev.dateReport ? report.dateReport : reportPrev.dateReport;
+                reportPrev.dateReport = dateReport_1;
+                reportsByYearPeriod.set(keyReport, __assign(__assign({}, reportPrev), report));
+            }
+            else {
+                reportsByYearPeriod.set(keyReport, report);
+            }
+        });
+        // return in ascending order by date report, date filed, frame, form
+        return Array.from(reportsByYearPeriod.values()).sort(function (a, b) {
+            var keyA = "".concat(a.fiscalYear, "_").concat(a.isTTM ? 'Q5' : a.fiscalPeriod, "_").concat(a.dateReport, "_").concat(a.dateFiled);
+            var keyB = "".concat(b.fiscalYear, "_").concat(b.isTTM ? 'Q5' : b.fiscalPeriod, "_").concat(b.dateReport, "_").concat(b.dateFiled);
+            return keyA > keyB ? 1 : -1;
+        });
+    };
+    ReportRawParser.prototype.getReportType = function (data) {
+        var form = data.form, taxonomy = data.taxonomy, isTTM = data.isTTM;
+        if (form === '8-K')
+            return '8K';
+        else if (taxonomy === 'dei')
+            return 'DOCUMENT_ENTITY_INFO';
+        else if (isTTM)
+            return 'ANNUAL';
+        return 'QUARTERLY';
+    };
+    ReportRawParser.prototype.getFiscalYear = function (data) {
+        var dateReport = data.dateReport, reportType = data.reportType, fiscalPeriod = data.fiscalPeriod;
+        var date = new Date("".concat(dateReport, "T00:00:00"));
+        var day = date.getDate();
+        var month = day < 14 ? date.getMonth() || 12 : date.getMonth() + 1;
+        var year = date.getFullYear();
+        var monthAddMap = {
+            Q1: 9,
+            Q2: 6,
+            Q3: 3,
+            Q4: 0,
+            FY: 0,
+        };
+        return month + monthAddMap[fiscalPeriod] > 12 && reportType === 'QUARTERLY' ? year + 1 : year;
+    };
+    return ReportRawParser;
+}());
+exports.default = ReportRawParser;

package/build/services/ReportParser/ReportTranslatedProxy.d.ts

@@ -0,0 +1,9 @@
+import { ReportTranslated } from '../../types';
+type ExtendableReportProxy = {
+    new (report: ReportTranslated): ReportTranslated;
+};
+/**
+ * Used to make ReportWrapper implement ReportTranslated interface via proxy
+ */
+declare const ReportTranslatedProxy: ExtendableReportProxy;
+export default ReportTranslatedProxy;