Cashflow is a tool designed to simplify the management of personal finances by parsing and normalizing CSV exports from Norwegian bank statements. The primary goal of Cashflow is to transform messy and inconsistent transaction descriptions into a uniform, non-unique format. This normalization makes it significantly easier to categorize and summarize expenses for household finance management across different accounts and banks.
- Exstensible Description Parsing: Handles transaction descriptions from different banks. The aim is to make it relatively easy to add custom parsers in the future.
- Normalize Transaction Sources: Converts similar transaction descriptions to a non-unique source name, facilitating easier categorization.
- Support for Multiple Currencies: Parses and extracts transactions in different currencies.
- Deno-Based: Written in Deno, providing a modern and secure runtime for JavaScript and TypeScript.
- Debugging Support: Includes a debug mode for detailed logging of the parsing process.
Cashflow's description parser uses a lexer-based approach, inspired by programming language compilers, to parse the transaction descriptions. The lexer function breaks down the parsing process into distinct stages, each responsible for extracting specific information like date, currency, value, source, and conversion rate. This method avoids the complexity and maintainability issues often associated with regular expressions for complex parsing tasks.
Given these inputs descriptions
="AniCura Grunerløkka Betalt: 29.12.23"
="*6483 19.10 NOK 112.80 JOKER ILA Kurs: 1.0000"
="*7889 25.08 DKK 120.00 REFFEN Kurs: 1.5879"
the lexer output the following:
{
raw: '="AniCura Grunerløkka Betalt: 29.12.23"',
currency: "",
local_value: "",
initiated_month: "",
initiated_day: "",
source: "AniCura Grunerløkka",
converstion_rate: "",
card: "",
paid_date: "2023-12-29",
paid_to: ""
}
{
raw: '="*6483 19.10 NOK 112.80 JOKER ILA Kurs: 1.0000"',
currency: "NOK",
local_value: "112.80",
initiated_month: "10",
initiated_day: "19",
source: "JOKER ILA",
converstion_rate: "1.0000",
card: "*6483",
paid_date: "",
paid_to: ""
}
{
raw: '="*7889 25.08 DKK 120.00 REFFEN Kurs: 1.5879"',
currency: "DKK",
local_value: "120.00",
initiated_month: "08",
initiated_day: "25",
source: "REFFEN",
converstion_rate: "1.5879",
card: "*7889",
paid_date: "",
paid_to: ""
}
The long-term vision for Cashflow is to evolve into a collection of tools that can transform CSV bank statements from various accounts into a standardized format. This standardized data can then be easily imported into Excel/Google Sheets for in-depth analysis and financial tracking.
Currently, Cashflow is tailored for personal use, focusing on the specific needs of household finance management. Future updates may expand its applicability to a broader audience.
We support CSV exports from the following Norwegian banks:
deno task run
: This will first clean the./out/
directory before starting the CLI.deno task dev
: This will start the CLI, watching for file changes.deno task lexer
: For iterating on the lexer. See details below.
The following assumes you have Deno v1.39 or newer installed.
- Clone this repo.
- Make a CSV export of your bank statement and place them in
./statements/
.
To iterate on the description lexer, copy the "description" (or similar) column
from a CSV and save it as ./lexer/descriptions-testsuite.txt
.
To see the output of parsing these lines, run deno task lexer
. This will start
a process that reads each line from the test suite and pass them through the
lexer, printing the result.
We also have a test suite to ensure that we don't break anything. To run tests,
simply run deno test --watch
.
As Cashflow is in its early stages, contributions, suggestions, and feedback are highly welcomed. Whether it's extending the parser to handle new formats, improving existing features, or providing ideas for future development, your input is invaluable.
Cashflow is released under MIT. For more details, see the LICENSE file in the repository.