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

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.