sec-edgar-api 0.2.3 → 0.3.0

package/README.md

@@ -149,6 +149,7 @@ Files for mapping & resolving properties:
 
 ### Resources
 
+-   XBRL Taxonomies: https://xbrl.us/xbrl-taxonomy/2024-us-gaap/
 -   Validate resolved values: https://finance.yahoo.com/
 -   Financial calculations: https://www.gurufocus.com/
 -   Calculate change in working capital: https://www.oldschoolvalue.com/stock-valuation/change-in-working-capital/

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

@@ -1,9 +1,10 @@
 import { CompanyFactListData, ReportRaw, ReportTranslated } from '../../types';
+import ReportRawBuilder from '../ReportRawBuilder';
+import { GetReportsRawParams } from '../SecEdgarApi';
 import PropertyResolver from './PropertyResolver';
-import ReportRawParser from './ReportRawParser';
 import ReportWrapper from './ReportWrapper';
 interface ReportParserArgs {
-    reportRawParser?: ReportRawParser;
+    reportBuilder?: ReportRawBuilder;
     propertyResolver?: PropertyResolver;
     keyTranslator?: Record<string, string[]>;
 }
@@ -12,28 +13,20 @@ type TranslateRawReportsCallback<T> = (report: T extends undefined ? ReportTrans
  * 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;
+    private readonly reportBuilder;
     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: CompanyFactListData, usePropertyResolver?: boolean): ReportWrapper[];
     /**
      * Same as parseReports but accepts ReportRaw[] instead of CompanyFactListData
      */
     parseReportsFromRaw(reportsRaw: ReportRaw[], usePropertyResolver?: boolean): ReportWrapper[];
     /**
-     * Note that this includes all reports by default, not just annual and quarterly. use options.reportsToInclude to filter
+     * Parse raw reports
      *
      * @see https://www.sec.gov/edgar/sec-api-documentation
      */
-    parseReportsRaw(companyFactListData: CompanyFactListData): ReportRaw[];
+    parseReportsRaw(companyFactListData: CompanyFactListData, options?: Omit<GetReportsRawParams, 'symbol'>): ReportRaw[];
     /**
      * parseReportsRaw but removes meta data from the report
      */

package/build/services/ReportParser/ReportParser.js

@@ -1,32 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 var key_translations_1 = require("../../util/key-translations");
-var ReportRawResolvable_1 = require("../ReportBuilder/ReportRawResolvable");
+var ReportRawBuilder_1 = require("../ReportRawBuilder");
 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;
+        var _a = args !== null && args !== void 0 ? args : {}, _b = _a.propertyResolver, propertyResolver = _b === void 0 ? new PropertyResolver_1.default() : _b, _c = _a.reportBuilder, reportBuilder = _c === void 0 ? new ReportRawBuilder_1.default() : _c, _d = _a.keyTranslator, keyTranslator = _d === void 0 ? key_translations_1.default : _d;
         this.keyTranslator = keyTranslator;
         this.propertyResolver = propertyResolver;
+        this.reportBuilder = reportBuilder;
     }
-    /**
-     * 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, usePropertyResolver) {
-        if (usePropertyResolver === void 0) { usePropertyResolver = true; }
-        var reportsRaw = this.reportRawParser.parseReports(companyFactListData);
-        return this.parseReportsFromRaw(reportsRaw, usePropertyResolver);
-    };
     /**
      * Same as parseReports but accepts ReportRaw[] instead of CompanyFactListData
      */
@@ -47,12 +34,19 @@ var ReportParser = /** @class */ (function () {
         return reportWrappers;
     };
     /**
-     * Note that this includes all reports by default, not just annual and quarterly. use options.reportsToInclude to filter
+     * Parse raw reports
      *
      * @see https://www.sec.gov/edgar/sec-api-documentation
      */
-    ReportParser.prototype.parseReportsRaw = function (companyFactListData) {
-        return this.reportRawParser.parseReports(companyFactListData);
+    ReportParser.prototype.parseReportsRaw = function (companyFactListData, options) {
+        if (options === void 0) { options = {}; }
+        var adjustForSplits = options.adjustForSplits, resolvePeriodValues = options.resolvePeriodValues, includeNamePrefix = options.includeNamePrefix;
+        var facts = this.reportBuilder.createFacts(companyFactListData, includeNamePrefix).facts;
+        return this.reportBuilder.buildReports({
+            facts: facts,
+            adjustForSplits: adjustForSplits,
+            resolvePeriodValues: resolvePeriodValues,
+        });
     };
     /**
      * parseReportsRaw but removes meta data from the report
@@ -82,14 +76,13 @@ var ReportParser = /** @class */ (function () {
         var reports = [];
         reportsRaw.forEach(function (report) {
             var reportNew = {};
-            var reportRaw = new ReportRawResolvable_1.default(report);
             // 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];
-                    var value = reportRaw.get(keyRaw);
+                    var value = report[keyRaw];
                     if (value === undefined)
                         continue;
                     reportNew[key] = value;
@@ -97,7 +90,7 @@ var ReportParser = /** @class */ (function () {
                 }
             }
             var reportFiltered = callback
-                ? callback(reportNew, reportRaw.report, keyTranslations)
+                ? callback(reportNew, report, keyTranslations)
                 : reportNew;
             reports.push(reportFiltered);
         });

package/build/services/ReportRawBuilder/FactGrouper.d.ts

@@ -0,0 +1,27 @@
+import { FactItem, FactGroup, SplitData } from '../../types';
+import FactFiscalCalculator from './FactFiscalCalculator';
+/**
+ * There are many facts properties for the same period but filed at different times.
+ * This groups those together and resolves the period and trailing values for each group.
+ */
+export default class FactGrouper {
+    private preferFirstValue;
+    private createFactGroup;
+    private createGroupKey;
+    /**
+     * Map structure { 2022_Q3: { name: ... } }. NOTE: Does not include fiscal year report key.
+     * All groups contain both trailing and period values, so use trailing from Q4 to get FY values.
+     */
+    buildFactGroupsByReportKey(params: {
+        facts: FactItem[];
+        splits?: SplitData[];
+        cik: number;
+        fiscalCalculator: FactFiscalCalculator;
+        resolvePeriodValues: boolean;
+        generateMissingGroups?: boolean;
+    }): {
+        factGroupsByReportKey: Map<string, FactGroup[]>;
+        minYear: number;
+        maxYear: number;
+    };
+}

package/build/services/ReportRawBuilder/FactGrouper.js

@@ -0,0 +1,206 @@
+"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 FactPeriodResolver_1 = require("./FactPeriodResolver");
+var FactSplitAdjuster_1 = require("./FactSplitAdjuster");
+/**
+ * There are many facts properties for the same period but filed at different times.
+ * This groups those together and resolves the period and trailing values for each group.
+ */
+var FactGrouper = /** @class */ (function () {
+    function FactGrouper() {
+        this.preferFirstValue = true;
+    }
+    FactGrouper.prototype.createFactGroup = function (params) {
+        return __assign({ name: '', unit: '', reportEnd: '', accn: '', reportFiled: '', isResolverGenerated: true, fiscalYear: 0, quarter: 0, filedFirst: '', filedLast: '', endFirst: '', endLast: '', valuePeriodFirst: null, valuePeriodLast: null, valueTrailingFirst: null, valueTrailingLast: null, valuePeriodResolved: null, valueTrailingResolved: null, valueSplitAdjustedPeriod: null, valueSplitAdjustedTrailing: null, values: [], facts: [] }, params);
+    };
+    FactGrouper.prototype.createGroupKey = function (params) {
+        var fiscalYear = params.fiscalYear, quarter = params.quarter, name = params.name;
+        return "".concat(fiscalYear, "_").concat(quarter, "_").concat(name);
+    };
+    /**
+     * Map structure { 2022_Q3: { name: ... } }. NOTE: Does not include fiscal year report key.
+     * All groups contain both trailing and period values, so use trailing from Q4 to get FY values.
+     */
+    FactGrouper.prototype.buildFactGroupsByReportKey = function (params) {
+        var _this = this;
+        var _a, _b, _c;
+        var facts = params.facts, cik = params.cik, fiscalCalculator = params.fiscalCalculator, resolvePeriodValues = params.resolvePeriodValues, _d = params.generateMissingGroups, generateMissingGroups = _d === void 0 ? false : _d, splits = params.splits;
+        // min and max year will be used to sort the reports
+        var minYear = 0;
+        var maxYear = 9999;
+        var factGroupByKey = new Map();
+        var periodResolver = new FactPeriodResolver_1.default({ cik: cik });
+        var factSplitAdjuster = new FactSplitAdjuster_1.default();
+        // used for groups that need to be generated without using a fact
+        var unitByPropertyName = new Map();
+        var accnByFiled = new Map();
+        // Create groups from facts.
+        for (var _i = 0, facts_1 = facts; _i < facts_1.length; _i++) {
+            var fact = facts_1[_i];
+            var _e = fiscalCalculator.getFiscalYearQuarter({ dateStr: fact.end }), quarter = _e.quarter, year = _e.year;
+            var _f = (_a = fiscalCalculator.getDatesByYearQuarter({ quarter: quarter, year: year })) !== null && _a !== void 0 ? _a : {}, _g = _f.end, reportEnd = _g === void 0 ? '' : _g, _h = _f.filed, reportFiled = _h === void 0 ? '' : _h;
+            var groupKey = this.createGroupKey({ fiscalYear: year, quarter: quarter, name: fact.name });
+            if (year < minYear)
+                minYear = year;
+            if (year > maxYear)
+                maxYear = year;
+            // period checks to see if the fact needs to be resolved for quarterly or trailing values
+            var period = periodResolver.getPeriod(fact);
+            var isPeriodFact = period <= 3;
+            var isTrailingFact = period > 3 || (isPeriodFact && quarter === 1);
+            var factValue = Number(fact.value);
+            // if no group exists, create from fact
+            if (!factGroupByKey.has(groupKey)) {
+                var group_1 = this.createFactGroup({
+                    name: fact.name,
+                    accn: periodResolver.isOriginalFiling({ end: fact.end, filed: fact.filed }) ? fact.accn : '',
+                    unit: fact.unit,
+                    reportEnd: reportEnd,
+                    reportFiled: reportFiled,
+                    isResolverGenerated: false,
+                    fiscalYear: year,
+                    quarter: quarter,
+                    filedFirst: fact.filed,
+                    filedLast: fact.filed,
+                    endFirst: fact.end,
+                    endLast: fact.end,
+                    valuePeriodFirst: isPeriodFact ? factValue : null,
+                    valuePeriodLast: isPeriodFact ? factValue : null,
+                    valueTrailingFirst: isTrailingFact ? factValue : null,
+                    valueTrailingLast: isTrailingFact ? factValue : null,
+                    values: [factValue],
+                    facts: [fact],
+                });
+                accnByFiled.set(fact.filed, (_b = fact.accn) !== null && _b !== void 0 ? _b : '');
+                unitByPropertyName.set(fact.name, fact.unit);
+                factGroupByKey.set(groupKey, group_1);
+                continue;
+            }
+            // if group already exists, update values
+            var group = factGroupByKey.get(groupKey);
+            group.facts.push(fact);
+            group.endFirst = fact.end < group.endFirst ? fact.end : group.endFirst;
+            group.endLast = fact.end > group.endLast ? fact.end : group.endLast;
+            group.filedFirst = fact.filed < group.filedFirst ? fact.filed : group.filedFirst;
+            group.filedLast = fact.filed > group.filedLast ? fact.filed : group.filedLast;
+            if (!group.values.includes(factValue)) {
+                group.values.push(factValue);
+            }
+            if (!group.accn && periodResolver.isOriginalFiling({ end: fact.end, filed: fact.filed })) {
+                group.accn = (_c = fact.accn) !== null && _c !== void 0 ? _c : '';
+                accnByFiled.set(fact.filed, group.accn);
+            }
+            if (isPeriodFact) {
+                if (group.valuePeriodFirst === null) {
+                    group.valuePeriodFirst = factValue;
+                }
+                if (factValue !== group.valuePeriodFirst && factValue !== group.valuePeriodLast) {
+                    group.valuePeriodLast = factValue;
+                }
+            }
+            if (isTrailingFact) {
+                if (group.valueTrailingFirst === null) {
+                    group.valueTrailingFirst = factValue;
+                }
+                if (factValue !== group.valueTrailingFirst && factValue !== group.valueTrailingLast) {
+                    group.valueTrailingLast = factValue;
+                }
+            }
+        }
+        // adjust for splits
+        var factGroupsByReportKey = new Map();
+        if (splits) {
+            factSplitAdjuster.adjustForSplits({
+                factGroups: Array.from(factGroupByKey.values()),
+                splits: splits,
+            });
+        }
+        factGroupByKey.forEach(function (group) {
+            var _a, _b;
+            // add to the period resolver to resolve quarterly and trailing values
+            var preferredValuePeriod = _this.preferFirstValue ? group.valuePeriodLast : group.valuePeriodLast;
+            var preferredValueTrailing = _this.preferFirstValue ? group.valueTrailingFirst : group.valueTrailingLast;
+            var selectedFactPeriod = group.facts.find(function (fact) {
+                var period = FactPeriodResolver_1.default.getPeriod(fact);
+                return fact.value === preferredValuePeriod && period <= 3;
+            });
+            var selectedFactTrailing = group.facts.find(function (fact) {
+                var period = FactPeriodResolver_1.default.getPeriod(fact);
+                return fact.value === preferredValueTrailing && (period > 3 || period === 0);
+            });
+            if (selectedFactPeriod) {
+                periodResolver.add({
+                    end: selectedFactPeriod.end,
+                    filed: selectedFactPeriod.filed,
+                    name: selectedFactPeriod.name,
+                    quarter: group.quarter,
+                    value: Number((_a = group.valueSplitAdjustedPeriod) !== null && _a !== void 0 ? _a : preferredValuePeriod),
+                    year: group.fiscalYear,
+                    start: selectedFactPeriod.start,
+                });
+            }
+            if (selectedFactTrailing) {
+                periodResolver.add({
+                    end: selectedFactTrailing.end,
+                    filed: selectedFactTrailing.filed,
+                    name: selectedFactTrailing.name,
+                    quarter: group.quarter,
+                    value: Number((_b = group.valueSplitAdjustedTrailing) !== null && _b !== void 0 ? _b : preferredValueTrailing),
+                    year: group.fiscalYear,
+                    start: selectedFactTrailing.start,
+                });
+            }
+        });
+        // Resolve quarterly and trailing values, and if no facts present for a certain period, create a group with resolved values.
+        periodResolver.forEach(function (_a) {
+            var _b, _c, _d, _e, _f, _g;
+            var propertyName = _a.propertyName, quarter = _a.quarter, valueQuarter = _a.valueQuarter, valueTrailing = _a.valueTrailing, year = _a.year;
+            var groupKey = _this.createGroupKey({ fiscalYear: year, name: propertyName, quarter: quarter });
+            var group = factGroupByKey.get(groupKey);
+            if (!group && (!resolvePeriodValues || !generateMissingGroups))
+                return;
+            var _h = (_b = fiscalCalculator.getDatesByYearQuarter({ quarter: quarter, year: year })) !== null && _b !== void 0 ? _b : { end: '', filed: '' }, end = _h.end, filed = _h.filed;
+            var reportKey = "".concat(year, "_Q").concat(quarter);
+            var bucket = (_c = factGroupsByReportKey.get(reportKey)) !== null && _c !== void 0 ? _c : factGroupsByReportKey.set(reportKey, []).get(reportKey);
+            if (!group) {
+                group = _this.createFactGroup({
+                    reportEnd: end,
+                    reportFiled: filed,
+                    endFirst: end,
+                    endLast: end,
+                    name: propertyName,
+                    accn: (_d = accnByFiled.get(filed)) !== null && _d !== void 0 ? _d : '',
+                    unit: (_e = unitByPropertyName.get(propertyName)) !== null && _e !== void 0 ? _e : '',
+                    isResolverGenerated: true,
+                    fiscalYear: year,
+                    quarter: quarter,
+                    valuePeriodResolved: valueQuarter,
+                    valueTrailingResolved: valueTrailing,
+                });
+                factGroupByKey.set(groupKey, group);
+            }
+            else if (resolvePeriodValues) {
+                var shouldUseTrailingForQuarter = FactPeriodResolver_1.default.isAverageShares({ propertyName: group.name }) && group.quarter === 4;
+                group.valuePeriodResolved = shouldUseTrailingForQuarter ? valueTrailing : valueQuarter;
+                group.valueTrailingResolved = valueTrailing;
+                (_f = group.valuePeriodFirst) !== null && _f !== void 0 ? _f : (group.valuePeriodFirst = shouldUseTrailingForQuarter ? valueTrailing : valueQuarter);
+                (_g = group.valueTrailingFirst) !== null && _g !== void 0 ? _g : (group.valueTrailingFirst = valueTrailing);
+            }
+            bucket.push(group);
+        });
+        return { factGroupsByReportKey: factGroupsByReportKey, minYear: minYear, maxYear: maxYear };
+    };
+    return FactGrouper;
+}());
+exports.default = FactGrouper;

package/build/services/{ReportBuilder → ReportRawBuilder}/FactPeriodResolver.d.ts

@@ -17,17 +17,59 @@ export default class FactPeriodResolver {
     private readonly propertiesByYear;
     /** prevent values from being added multiple times */
     private readonly resolvedValues;
+    private readonly unresolvedReports;
     private readonly cik;
+    private readonly preferOriginalFilingValues;
     constructor(args: {
         cik: number;
+        preferOriginalFilingValues?: boolean;
     });
+    /**
+     * Some properties have a start and end that represent a period average, rather than a period total.
+     * These properties should be treated as instantaneous properties, meaning
+     * the value for Q4 and FY should be the same.
+     *
+     * I believe the only properties like this are share related:
+     * us-gaap:WeightedAverageNumberOfDilutedSharesOutstanding and us-gaap:WeightedAverageNumberOfSharesOutstandingBasic.
+     * May need to update this in the future if there are more
+     */
+    static isAverageShares(params: {
+        propertyName: string;
+    }): boolean;
+    private isAverageShares;
+    /**
+     * Used to check if this should potentially overwrite a value that has already been set.
+     */
+    private isPreferredValue;
     private getOrSetBucketArr;
     private addPropertyByYear;
     resolveValues(propertyName: string, year: number): void;
     get(propertyName: string, year: number, fiscalPeriod: FiscalPeriod): number | undefined;
     private getPropertyBuckets;
-    private getPeriod;
+    /**
+     * 0, 3, 6, 9, or 12 month period. 0 is instantaneous data that doesn't have a time period, (ex: assets)
+     * other facts have values that are for a period of time. (like revenue over the last 6 months).
+     *
+     * Use periods 0 and 3 for quarterly reports and 0 and 12 for annual reports.
+     */
+    static getPeriod(params: {
+        start?: string;
+        end: string;
+    }): 0 | 3 | 6 | 12 | 9;
+    getPeriod(params: {
+        start?: string;
+        end: string;
+    }): 0 | 3 | 6 | 12 | 9;
     private getOrSetReport;
+    /**
+     * True if the filed date is within 60 days of the end date. This indicates that it is likely
+     * the original filing of the fact because filers are required to submit within 45 days of the
+     * period end, and subsequent reports are filed 90 days apart.
+     */
+    isOriginalFiling(params: {
+        end: string;
+        filed: string;
+    }): boolean;
     add(params: {
         year: number;
         quarter: number;
@@ -37,12 +79,14 @@ export default class FactPeriodResolver {
         name: string;
         filed: string;
     }): void;
-    private readonly unresolvedReports;
     private buildUnresolvedReports;
     forEach(callback: (params: {
         year: number;
         fiscalPeriod: FiscalPeriod;
         propertyName: string;
         value: number | string;
+        valueQuarter: number;
+        valueTrailing: number;
+        quarter: number;
     }) => void): void;
 }

package/build/services/{ReportBuilder → ReportRawBuilder}/FactPeriodResolver.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-var ReportRawResolvable_1 = require("./ReportRawResolvable");
 /**
  * Resolves quarterly and annual values for a property. This is because filers provide total values for the
  * current fiscal year, rather than values for the individual quarters
@@ -21,9 +20,33 @@ var FactPeriodResolver = /** @class */ (function () {
         /** prevent values from being added multiple times */
         this.resolvedValues = new Set();
         this.unresolvedReports = new Map();
-        var cik = args.cik;
+        var cik = args.cik, _a = args.preferOriginalFilingValues, preferOriginalFilingValues = _a === void 0 ? false : _a;
         this.cik = cik;
+        this.preferOriginalFilingValues = preferOriginalFilingValues;
     }
+    /**
+     * Some properties have a start and end that represent a period average, rather than a period total.
+     * These properties should be treated as instantaneous properties, meaning
+     * the value for Q4 and FY should be the same.
+     *
+     * I believe the only properties like this are share related:
+     * us-gaap:WeightedAverageNumberOfDilutedSharesOutstanding and us-gaap:WeightedAverageNumberOfSharesOutstandingBasic.
+     * May need to update this in the future if there are more
+     */
+    FactPeriodResolver.isAverageShares = function (params) {
+        var propertyName = params.propertyName;
+        return propertyName.includes('WeightedAverage') && propertyName.includes('SharesOutstanding');
+    };
+    FactPeriodResolver.prototype.isAverageShares = function (params) {
+        return FactPeriodResolver.isAverageShares(params);
+    };
+    /**
+     * Used to check if this should potentially overwrite a value that has already been set.
+     */
+    FactPeriodResolver.prototype.isPreferredValue = function (params) {
+        var bucket = params.bucket, end = params.end, filed = params.filed, bucketIndex = params.bucketIndex;
+        return !bucket.has(bucketIndex) || this.preferOriginalFilingValues || !this.isOriginalFiling({ end: end, filed: filed });
+    };
     FactPeriodResolver.prototype.getOrSetBucketArr = function (map, year, propertyName) {
         var _a, _b;
         var propertyMap = (_a = map.get(year)) !== null && _a !== void 0 ? _a : map.set(year, new Map()).get(year);
@@ -49,8 +72,8 @@ var FactPeriodResolver = /** @class */ (function () {
             var reportKey = "".concat(year, "_").concat(i + 1);
             var unresolvedReport = this.unresolvedReports.get(reportKey);
             var unresolvedReportPrev = this.unresolvedReports.get("".concat(year, "_").concat(i));
-            var sumValue = (_b = unresolvedReport === null || unresolvedReport === void 0 ? void 0 : unresolvedReport.getNumber(propertyName)) !== null && _b !== void 0 ? _b : 0;
-            var prevSum = (_c = unresolvedReportPrev === null || unresolvedReportPrev === void 0 ? void 0 : unresolvedReportPrev.getNumber(propertyName)) !== null && _c !== void 0 ? _c : 0;
+            var sumValue = (_b = unresolvedReport === null || unresolvedReport === void 0 ? void 0 : unresolvedReport[propertyName]) !== null && _b !== void 0 ? _b : 0;
+            var prevSum = (_c = unresolvedReportPrev === null || unresolvedReportPrev === void 0 ? void 0 : unresolvedReportPrev[propertyName]) !== null && _c !== void 0 ? _c : 0;
             if (quarterValue === undefined) {
                 var bucketQuarter_1 = this.getOrSetBucketArr(this.valueByQuarterByPropertyByYear, year, propertyName);
                 bucketQuarter_1.set(i, (Number(sumValue) || 0) - (Number(prevSum) || 0));
@@ -82,7 +105,13 @@ var FactPeriodResolver = /** @class */ (function () {
         var bucketString = (_g = (_f = this.valueByQuarterByPropertyByYearString.get(year)) === null || _f === void 0 ? void 0 : _f.get(propertyName)) !== null && _g !== void 0 ? _g : new Map();
         return { bucketQuarter: bucketQuarter, bucketSum: bucketSum, bucketString: bucketString };
     };
-    FactPeriodResolver.prototype.getPeriod = function (params) {
+    /**
+     * 0, 3, 6, 9, or 12 month period. 0 is instantaneous data that doesn't have a time period, (ex: assets)
+     * other facts have values that are for a period of time. (like revenue over the last 6 months).
+     *
+     * Use periods 0 and 3 for quarterly reports and 0 and 12 for annual reports.
+     */
+    FactPeriodResolver.getPeriod = function (params) {
         var start = params.start, end = params.end;
         if (!start || start === end)
             return 0;
@@ -96,11 +125,14 @@ var FactPeriodResolver = /** @class */ (function () {
             return 9;
         return 12;
     };
+    FactPeriodResolver.prototype.getPeriod = function (params) {
+        return FactPeriodResolver.getPeriod(params);
+    };
     FactPeriodResolver.prototype.getOrSetReport = function (params) {
         var _a;
         var year = params.year, quarter = params.quarter;
         var key = "".concat(year, "_").concat(quarter);
-        var report = (_a = this.unresolvedReports.get(key)) !== null && _a !== void 0 ? _a : new ReportRawResolvable_1.default({
+        var report = (_a = this.unresolvedReports.get(key)) !== null && _a !== void 0 ? _a : {
             cik: this.cik,
             fiscalYear: year,
             fiscalPeriod: quarter === 4 ? 'FY' : "Q".concat(quarter),
@@ -109,35 +141,54 @@ var FactPeriodResolver = /** @class */ (function () {
             url: null,
             splitDate: null,
             splitRatio: null,
-        });
+        };
         if (!this.unresolvedReports.has(key)) {
             this.unresolvedReports.set(key, report);
         }
         return report;
     };
+    /**
+     * True if the filed date is within 60 days of the end date. This indicates that it is likely
+     * the original filing of the fact because filers are required to submit within 45 days of the
+     * period end, and subsequent reports are filed 90 days apart.
+     */
+    FactPeriodResolver.prototype.isOriginalFiling = function (params) {
+        var end = params.end, filed = params.filed;
+        var DAY_60_MS = 5184000000;
+        return new Date(filed).getTime() - new Date(end).getTime() < DAY_60_MS;
+    };
     FactPeriodResolver.prototype.add = function (params) {
         var year = params.year, value = params.value, propertyName = params.name, quarter = params.quarter, start = params.start, end = params.end, filed = params.filed;
-        var period = this.getPeriod({ start: start, end: end });
+        var bucketIndex = quarter - 1;
+        var period = this.isAverageShares({ propertyName: propertyName }) ? 0 : this.getPeriod({ start: start, end: end });
         this.addPropertyByYear(this.propertiesByYear, year, propertyName);
         if (typeof value === 'string') {
             var bucket = this.getOrSetBucketArr(this.valueByQuarterByPropertyByYearString, year, propertyName);
-            bucket.set(quarter - 1, value);
+            if (this.isPreferredValue({ bucket: bucket, bucketIndex: bucketIndex, end: end, filed: filed })) {
+                bucket.set(bucketIndex, value);
+            }
             return;
         }
         if (period === 0) {
             var bucket = this.getOrSetBucketArr(this.valueByQuarterByPropertyByYear, year, propertyName);
             var bucketSum = this.getOrSetBucketArr(this.sumByQuarterByPropertyByYear, year, propertyName);
-            bucket.set(quarter - 1, value);
-            bucketSum.set(quarter - 1, value);
+            if (this.isPreferredValue({ bucket: bucket, bucketIndex: bucketIndex, end: end, filed: filed })) {
+                bucket.set(bucketIndex, value);
+                bucketSum.set(bucketIndex, value);
+            }
             return;
         }
         if (period === 3) {
             var bucket = this.getOrSetBucketArr(this.valueByQuarterByPropertyByYear, year, propertyName);
-            bucket.set(quarter - 1, value);
+            if (this.isPreferredValue({ bucket: bucket, bucketIndex: bucketIndex, end: end, filed: filed })) {
+                bucket.set(bucketIndex, value);
+            }
         }
         if (quarter === 1 || period > 3) {
             var bucket = this.getOrSetBucketArr(this.sumByQuarterByPropertyByYear, year, propertyName);
-            bucket.set(quarter - 1, value);
+            if (this.isPreferredValue({ bucket: bucket, bucketIndex: bucketIndex, end: end, filed: filed })) {
+                bucket.set(bucketIndex, value);
+            }
         }
         this.addPropertyByYear(this.propertiesResolvableByYear, year, propertyName);
     };
@@ -163,7 +214,7 @@ var FactPeriodResolver = /** @class */ (function () {
                     if (value === undefined)
                         continue;
                     var report = _this.getOrSetReport({ year: year, quarter: i + 1 });
-                    report.report[propertyName] = value;
+                    report[propertyName] = value;
                 }
             });
         });
@@ -173,14 +224,24 @@ var FactPeriodResolver = /** @class */ (function () {
         this.buildUnresolvedReports();
         this.propertiesByYear.forEach(function (properties, year) {
             properties.forEach(function (propertyName) {
-                var _a;
+                var _a, _b;
                 _this.resolveValues(propertyName, year);
-                for (var i = 0; i < 5; i++) {
+                for (var i = 0; i < 4; i++) {
                     var isAnnual = i === 4;
-                    var _b = _this.getPropertyBuckets(year, propertyName), bucketQuarter = _b.bucketQuarter, bucketSum = _b.bucketSum, bucketString = _b.bucketString;
-                    var value = (_a = (isAnnual ? bucketSum.get(3) : bucketQuarter.get(i))) !== null && _a !== void 0 ? _a : bucketString.get(i);
-                    var fiscalPeriod = isAnnual ? 'FY' : "Q".concat(i + 1);
-                    callback({ year: year, fiscalPeriod: fiscalPeriod, propertyName: propertyName, value: value });
+                    var _c = _this.getPropertyBuckets(year, propertyName), bucketQuarter = _c.bucketQuarter, bucketSum = _c.bucketSum, bucketString = _c.bucketString;
+                    var valueQuarter = (_a = bucketQuarter.get(i)) !== null && _a !== void 0 ? _a : bucketString.get(i);
+                    var valueTrailing = bucketSum.get(i);
+                    var value = (_b = (isAnnual ? bucketSum.get(3) : bucketQuarter.get(i))) !== null && _b !== void 0 ? _b : bucketString.get(i);
+                    var quarter = i + 1;
+                    callback({
+                        year: year,
+                        fiscalPeriod: "Q".concat(quarter),
+                        propertyName: propertyName,
+                        value: value,
+                        quarter: quarter,
+                        valueQuarter: valueQuarter,
+                        valueTrailing: valueTrailing,
+                    });
                 }
             });
         });

package/build/services/ReportRawBuilder/FactRecordBuilder.d.ts

@@ -0,0 +1,9 @@
+import { CompanyFactListData, FactItem } from '../../types';
+/**
+ * Builds an array of fact records.
+ */
+export default class FactRecordBuilder {
+    createFacts(data: CompanyFactListData, includeNamePrefix?: boolean): {
+        facts: FactItem[];
+    };
+}