Skip to content

@alex.garcia/libfec / Filing

Class: Filing ​

Defined in: filing.ts:157

One FEC filing, opened for streaming. Mirrors Python's libfec.Filing.

The header and the cover are read when it is constructed, so header, cover, coverRecord and the filer attributes (formType, filerId, …) are there up front. The records after the cover are streamed, a batch at a time, by itemizations (typed) or itemizationRecords (raw), one-to-one and in file order. Each call is a new pass from the top, and passes are independent: they can run one after the other or interleaved.

ts
using filing = new Filing("1805248.fec");
console.log(filing.filerName, filing.coverageThroughDate);
for (const item of filing.itemizations()) {
  switch (item.type) {
    case "ScheduleA": console.log(item.contribution_amount); break;
    case "Unknown": break; // a record with no typed class, e.g. F3PS
  }
}

using (Node 24+, Deno, Bun) closes it; elsewhere call close. A bytes source is read in place: don't modify it while the filing is open.

Throws ​

A Node-style error (code: "ENOENT", …) if the path can't be opened, or FecParseError if the header or cover can't be parsed.

Implements ​

  • Disposable

Constructors ​

Constructor ​

new Filing(source, options?): Filing

Defined in: filing.ts:209

Parameters ​

source ​

Source

A path, a file: URL, or the file's bytes.

options? ​

FilingOptions = {}

Returns ​

Filing

Properties ​

id ​

readonly id: string | null

Defined in: filing.ts:162

The filing ID: FilingOptions.id if given, else from the file name ("1805248" for FEC-1805248.fec); null for bytes without an id.


fecVersion ​

readonly fecVersion: string

Defined in: filing.ts:164

The filing's format version: "8.4", "3.00", "P3.4" (paper).


readonly header: Header

Defined in: filing.ts:166

The filing's header.


sourceLength ​

readonly sourceLength: number

Defined in: filing.ts:168

The source's size in bytes (0 if unknown).


formType ​

readonly formType: string

Defined in: filing.ts:170

The cover's form type as filed: "F3XN", "F99".


filerId ​

readonly filerId: string

Defined in: filing.ts:172

The filer's FEC ID, whatever the form calls it.


filerName ​

readonly filerName: string

Defined in: filing.ts:174

The filer's name, whatever the form calls it.


reportCode ​

readonly reportCode: string | null

Defined in: filing.ts:176

"Q1", "M8", …; null for a form that is not a periodic report.


coverageFromDate ​

readonly coverageFromDate: string | Date | null

Defined in: filing.ts:178

First day the report covers; follows the dates option. null if absent or invalid.


coverageThroughDate ​

readonly coverageThroughDate: string | Date | null

Defined in: filing.ts:180

Last day the report covers; follows the dates option. null if absent or invalid.


cover ​

readonly cover: Cover | Unknown

Defined in: filing.ts:186

The typed cover (Form3X, Form99, …), narrowed with switch (filing.cover.type), or an Unknown for a form with no typed struct. The same object every time.


coverRecord ​

readonly coverRecord: Record

Defined in: filing.ts:188

The cover line as a raw Record. The same object every time.

Accessors ​

closed ​

Get Signature ​

get closed(): boolean

Defined in: filing.ts:318

Whether close has been called.

Returns ​

boolean

Methods ​

fromId() ​

static fromId(id, options?): Promise<Filing>

Defined in: filing.ts:275

Download an electronic filing from docquery.fec.gov (https://docquery.fec.gov/dcdev/posted/<id>.fec) into memory and open it, with Filing.id set. Mirrors Python's Filing.from_id; like it, there is no fallback to paper filings.

ts
const filing = await Filing.fromId(1721696); // or "1721696", "FEC-1721696"
console.log(filing.filerName);

In a browser, pass a FromIdOptions.proxy: docquery sends no CORS headers. Without one, the request fails with a TypeError that says so (code: "ERR_CORS").

Parameters ​

id ​

string | number

The filing ID: digits, optionally prefixed FEC- or FEC.

options? ​

FromIdOptions = {}

Returns ​

Promise<Filing>

Throws ​

TypeError for a malformed id or option, before any request; FecError ERR_FILING_NOT_FOUND (status: 404) if there is no such filing, ERR_HTTP (with status) for any other non-2xx response; the fetch() error on a network failure, an abort or the timeout (TimeoutError); otherwise as the Filing constructor.


itemizations() ​

itemizations(): Generator<Itemization | Unknown, void, undefined>

Defined in: filing.ts:336

Every record after the cover, typed, in file order: an Itemization (ScheduleA, …), or an Unknown for a record with no typed class (a summary record, a schedule not typed yet). Narrow with switch (item.type). One-to-one with itemizationRecords.

Each call is a new, independent pass from the top of the filing.

Returns ​

Generator<Itemization | Unknown, void, undefined>

Throws ​

FecError ERR_FILING_CLOSED if the filing is closed (now, or on the next step of a running pass); MissingMappingError for a record with no typed class whose row type has no column mapping; FecParseError for a row that can't be parsed.


itemizationRecords() ​

itemizationRecords(): Generator<Record, void, undefined>

Defined in: filing.ts:355

Every record after the cover as a raw Record, in file order: the same records as itemizations, one-to-one. The fast path when you only need Record.values; Record.itemization types one on demand.

Each call is a new, independent pass from the top of the filing.

Returns ​

Generator<Record, void, undefined>

Throws ​

MissingMappingError for a row type with no column mapping; otherwise as itemizations.


close() ​

close(): void

Defined in: filing.ts:368

Release the source and stop every pass: a running itemizations or itemizationRecords throws ERR_FILING_CLOSED on its next step. Idempotent; the header, cover and filer attributes stay readable.

Returns ​

void


[dispose]() ​

[dispose](): void

Defined in: filing.ts:376

= close, for using.

Returns ​

void

Implementation of ​

Disposable.[dispose]