nilkrdg / coin-change

Coin API to track change in coins and an interactive test harness to play with the Coin API methods.

Coin Change API

Table of Contents

1. About The Project
   • Design Decisions
   • Coin API Methods
   • Coin API Response Types
2. Getting Started
   • Requirements
   • Installation
3. Usage
   • Coin CLI Commands
4. Test
5. Further Work

About The Project

The project includes an API to calculate and keep Coin change for a vending machine and an interactive test harness to play with it.

Design Decisions

The Coin API solves the following problems

1. Initialise the vending machine to a known state with given coins
   This is solved by keeping coins in a HashMap in the Coin API. HashMap has complexity of O(1) for insertion and lookup because of this reason it is preferred.
   
   
2. Register coins that have been deposited by a user
   When the user inserts coins into the machine, the user coins are saved in an array in memory. The reason to keep the user coins seperate is to return them back in case a request results in an error (e.g. not enough coins for change, not enough user coins to buy etc.).
   
   
3. Return the correct change to a user as coins when an order is received
   Although a classic HashMap doesn't keep the order, a JavaScript Object is used as a HashMap and the order is preserved in small to bigger coin types. To be able to find least number of coins for change, the hashmap is iterated over in reverse order. The iteration starts from the biggest coin or if the change amount is bigger than all coin types, it starts from the change amount. The time complexity for the getChange method is O(N) where N is the number of coin types.
   
   The buy method returns change using the least amount of coins. If there are not enough coins in the machine or the user does not insert enough coins to buy, the method returns an error message alongside all the coins the user inserted.
   
   

Coin API Methods

Method	Operation	Parameter	Response	Response Data
initialiseMachine	Initialises the machine with the given coins.	coins: Coin[]	CoinResponse	None
reset	Resets the machine and all the API states.	None	CoinResponse	None
registerUserCoins	Accepts user coins into the machine.	coins: Coin[]	CoinResponse	None
printUserCoins	Prints user coins.	None	CoinResponse	None
buy	Returns the correct change and removes coins from the machine.	amount: Number	CoinResponse	On Success: change On Error: user coins
checkCoinAmount	Returns the amount of the specified coin.	coinType: Number	CoinResponse	On Success: Coin amount
printMachineCoins	Prints the contents of the machine.	None	CoinResponse	None

Coin API Response Types

The response type CoinResponse is an object that carries the following properties:

{
  result: 'Success' | 'Error',
  message: String,
  data: Coin[] | Number
}

The response type Coin is an object that has the following properties:

{
  type: Number
  amount: Number
}

Getting Started

Requirements

The project works on Node version 12.x and greater. Before installation make sure to have Node.js (>=12.0.0) installed.

Installation

Run the following commands to install the project and start the Coin CLI.

git clone https://github.com/nilkrdg/coin-change.git

cd coin-change

npm install 

npm run start

Usage

The project includes an interactive test harness (CLI).

You can list all CLI commands:

help

You can list details of a CLI command:

help init

To initialise the machine:

init --coin-types 1,2,5 --coin-amounts 2,4,2

Output:

Success
Coins in the machine:
{ '1': 2, '2': 4, '5': 2 }

---

NOTE Please be aware that the number of coin types directly corresponds to the number of coin amounts entered and must be equal.

---

To initialise the machine with short form:

init -ct 1,2,5 -ca 2,4,2

To insert coins into the machine:

insert --coin-types 1,2,5 --coin-amounts 2,4,2

Output:

Success
Coins inserted by user:
[ { type: 1, amount: 2 }, { type: 2, amount: 4 }, { type: 5, amount: 2 }]
Coins in the machine:
{ '1': 4, '2': 8, '5': 4 }

To insert coins into the machine with short form:

insert -ct 1,2,5 -ca 2,4,2

To buy a product and receive correct change:

buy --amount 10

To buy a product and receive correct change with short form:

buy -a 10

Output:

Success
Change:
[ { type: 5, amount: 2 } ]
Coins in the machine:
{ '1': 4, '2': 8, '5': 2 }

Coin CLI Commands

Command	Arguments	Arguments short form	Operation
init	--coin-types Number[] --coin-amounts Number[]	-ct Number[] -ca Number[]	Initialises the machine with given coins.
insert	--coin-types Number[] --coin-amounts Number[]	-ct Number[] -ca Number[]	Accepts user coins in the machine.
buy	--amount Number	-a Number	Returns the correct change and removes coins from the machine.
coin	--type Number	-t Number	Returns the amount of the specified coin.
reset			Resets all the API state.
print			Prints all the coins in the machine.
quit			Terminates the Coin CLI.
help			Prints the list of commands. If command name argument is present, prints the details of the command.

Test

Run the following command to execute tests:

npm test

Further Work

• The number of coin types and amounts must be validated by CLI Module.
• There is need to add tests for CLI module.
• More cases should be covered by Coin and Parser Module tests.