balance-cli v1.0.3
balance-cli
CLI tool to calculate user balances based on transactions.
Overview
Performance
Streaming
The CLI is focused on processing large amounts of data, without using too much resources. Instead of reading the whole JSON input into the memory, we rely on a streaming approach.
The file is expected to be an array of transaction objects. It is read line by line by a parser, so the memory usage is limited by the size of one transaction object, so processing huge files won't use more memory.
Date handling
We assume that the average number of transactions per user is low. This means we don't have to compare dates too often for calculating the last_activity
. For this reason preprocessing every date string into a Date
object would be a waste of time, CPU and RAM, so we store them in string format.
We assume, that the dates are in ISO8601 format, without timezone information, e.g.: 1970-01-01T00:00:00.000Z
.
A nice property of this string format is that it can be compared as a string and giving correct result. This is a consequence of the fact that dates are read from left to right and values on the left side are more significant than values on the right (e.g.: months are more significant than days).
Error handling
During the program executions, errors can happen at the following places:
- during file reading:
- the file does not exists
- the program has no permission to access the file
- other file system errors
- during file parsing
- the file has JSON syntax error
- during transaction validation
- the transaction has an incorrect structure
- e.g.: date is not in ISO8601 format without timezone info
- these errors can be ignored
- check the
--ignoreErrors
option
- check the
- the transaction has an incorrect structure
All of the mentioned errors are handled by the CLI. All of these errors stop the execution of the program, except for the transaction validation error, which can be suppressed. In this case, the execution is continuous and the incorrect transactions are ignored.
Usage
The easiest way of executing the CLI is by using npx:
npx balance-cli ./transactions.json
To check all of the available options, run it with the -h
argument:
npx balance-cli -h
The file path can be supplied via the --path
argument as well:
npx balance-cli --path ./transactions.json
Input format
The correct format of a transaction looks like this:
{
"user_id": "faf4a6fe-c839-4ee3-ac11-ee3957ac6332",
"timestamp": "1970-01-01T00:00:00.000Z",
"currency": "GBP",
"amount": "+1248.87"
}
The user_id
must be a UUID v4 identifier, the timestamp
is ISO8601 without timezone info. The accepted currency
values are "GBP"
, "EUR"
, and "USD"
. The amount
must be prefixed with a "+"
or "-"
sign and has to have exactly two decimal places.
The input file must be an array of such transaction objects, for example:
[
{
"user_id": "4a1b84f7-9756-4549-837e-9574c7ffc142",
"timestamp": "1970-01-01T00:00:00.000Z",
"currency": "GBP",
"amount": "+12.00"
},
{
"user_id": "4a1b84f7-9756-4549-837e-9574c7ffc142",
"timestamp": "1970-01-01T00:00:00.000Z",
"currency": "USD",
"amount": "-12.00"
},
{
"user_id": "faf4a6fe-c839-4ee3-ac11-ee3957ac6332",
"timestamp": "1970-01-01T00:00:00.000Z",
"currency": "EUR",
"amount": "-3.99"
},
{
"user_id": "faf4a6fe-c839-4ee3-ac11-ee3957ac6332",
"timestamp": "1970-01-01T00:00:00.000Z",
"currency": "GBP",
"amount": "+1248.87"
}
]
The transaction format mismatch is a recoverable error. By passing the --ignoreErrors
argument to the CLI, it will ignore all the faulty transactions (e.g.: different currency, amount is not prefixed, incorrect ID format, etc):
npx balance-cli ./transactions.json --ignoreErrors
Testing
First, clone the repo and install its dependencies:
git clone https://github.com/Wyctus/balance-cli.git
npm i
Run the unit tests by:
npm run test:unit
Run the integration tests by:
npm run test:integration
Run the performance tests to demonstrate the capabilities of the CLI on larges files:
npm run test:performance -- 1000000 30000
The first argument denotes the number of generated random transactions and the second is the number of users. The transactions are evenly distributed between the users.