ledger-dom-js
A library for parsing files used with ledger, a double-entry accounting system, into a document object model.
This is a library for querying (and eventually writing) the text files used by the ledger, a text-based double-entry accounting system.
This was written in Typescript and includes the typings
entry in the package.json
. All of the examples are written in Typescript but can be used with normal Javascript.
This library uses Big and Moment. Big
is used to ensure that precise numbers and rounding are handled properly.
For a callback approach to working with Ledger files, consider using ledger-cli.
Setup and usage
Install ledger-dom
using npm
:
npm i ledger-dom
Ledger entities
The system is build around a small series of classes that represent the various components of the ledger
file.
Ledger
The top level object, this represents the entire ledger file.
commodities
Commodity[]
Default: []
An unordered list of commodities within the ledger.
accounts
Account[]
Default: []
An unordered list of accounts from the file.
transactions
TransactionList
Default: []
Contains a list of all transactions within the ledger. If the ledger was loaded via loadFromProcess
, then it will be sorted in date order.
Account
A class that contains information about an account, such as Expenses:Advertising
.
id
string
Contains the internal ID for a given account. This is the key used for account lookups in postings.
name
string
The name of the account without any path, such as Advertising
for Expenses:Advertising
.
path
string
The full path of the account, such as Expenses:Advertising
.
subaccounts
Account[]
Defaults: []
A list of child (or sub) accounts for this one. In the above example, the Expenses
account would have a child of Expenses:Advertising
.
Commodity
A class that represents a commodity.
flags
string
The internal flags for the commodity.
symbol
string
The system used for the commodity, such as $
.
Transaction
A class that represents a single transaction in the system. A transaction has two or more postings which represents the various accounts associated with the transaction.
date
Moment
The date of the transaction as a Moment
.
payee
string
The name of the payee line.
postings
Posting[]
Default: []
A list of postings associated with the transaction.
hasAccount(regex: RegExp)
Returns: boolean
Determines if the transaction has a posting for an account that matches the given regular expression.
Posting
A line item within a transaction.
account
Account
The account associated with this posting.
quantity
Big
A Big
number that contains the amount of the posting.
commodity
Commodity
The commodity of the posting. If there is a transaction that modifies two commodities for the same account, there will be two postings for it.
TransactionList
The TransactionList
is an intelligent list of transactions that allows for queries to be perform on them and returned as subsets of the given list.
transactions
Transaction[]
Default: []
A list of all transactions within the list.
length
The number of items in transactions
, effectively transactions.length
.
filterByAccount(regex: RegExp)
Returns: TransactionList
Create a new TransactionList
that only contains transactions that match the regular expression on the transaction's account.
filterByDate(start: Moment, end: Moment)
Returns: TransactionList
Creates a new TransactionList
that only contains transactions between the start and end date (as Moment
objects).
get(index: number)
Returns: Transaction
Returns the transaction at the given index. This is the same as transactions[index]
.
getTotals()
Returns: object
Goes through all the transactions in the list and creates a custom object that has the symbol of each currency along with the total (as a Big
) for each commodity.
push(transaction: Transaction)
Adds a transaction to the list. This is the same as transactions.push(transaction)
.
Loading ledgers
There is current no native loading of ledger files into memory. To load a ledger, the library spawns the ledger
executable and uses that output to create the nested object.
; ; ledger .loadFromProcessfilename .then;
Ledgers can also be loaded from any XML object that xml-stream can read.
ledger.loadFromXmlreadable.then...;
The load
methods all return a promise to a Ledger
object.
Building
This library uses npm
for the building.
npm run buildnpm test
Justification
There is one other NPM library for parsing ledger: ledger-cli. This is a SAX-style parser that has a callback for every posting and transaction. It also uses a spawned process to retrieve the data. There are times, however, when having the entire ledger in memory is useful such as multiple reports with relatively small data. This library for handling those type of ledgers while the ledger-cli
is more useful for streamed processing.