calcost is a Node.js module which allows you to define time-based rules for
calculating the cost of resource usage. The module provides
which are used to define the rules and their constraints. Several rules can be
defined for a resource and then used to calculate the cost of using the
Example Use Case
A compute resource has variable costs. The resource costs more to use during
peak times and costs significantly less during the off-peak times. Multiple
CostRule objects are defined to cover the peak periods: Monday-Friday, 8am-8pm.
CostRule objects are defined to cover all non-peak times.
Calculating the cost of a user's usage then requires creating
for each interval of time during which the user has used the resource. An array containing
DateSpan objects is then passed to each
CostRule for the peak times.
CostRule object determines if any of the
DateSpan objects time intervals
do overlap with any interval for which it is configured to allocate costs. The
cost is allocated to each overlapping
DateSpan and then the method
returns the total cost and arrays representing the overlapping (used) time intervals
and any remainder time intervals for which costs have not been allocated.
If there are any remaining
DateSpan objects, which have not been used to
allocate costs, these are passed to the non-peak
CostRule objects. This non-peak
cost is added to the peak cost to generate the total cost of using the compute
calcost module can be installed using
$ cd <myproject>$ npm install --save calcost
calcost module provides one functional constructor for the
CostRule object and it also provides the
var calcost = ;// functional constructor to create CostRule objectsvar costrule = calcostcostRule;// Constants object provides all of the constants defined by the modulevar calcostConstants = calcostconstants;
CostRule is an immutable object which allows a time-based rule to be defined
for the calculation of the cost of resource usage. It provides a functional
costRule and a single method
totalCost which is used to calculate
the cost of an array of
costRule function is a functional constructor therefore it should not be
called with the
new operator. The function accepts several arguments:
TimeRuleobject which defines the interval of time during which the costs can be calculated using this rule.
inRateRate per unit of time. The rate is currency-agnostic.
inRateTypeArgument describes how the costs should be calculated.
inWorkDayDurationDuration of a working day in minutes.
Valid values for
RATETYPE_PER_MILLISECONDRate is the cost per millisecond.
RATETYPE_PER_SECOND_PRORATARate is the cost per second and/or fraction of a second.
RATETYPE_PER_SECOND_ROUNDUPRate is the cost per second. Cost is rounded up to the nearest second.
RATETYPE_PER_MINUTE_PRORATARate is the cost per minute and/or fraction of a minute.
RATETYPE_PER_MINUTE_ROUNDUPRate is the cost per minute. Cost is rounded up to the nearest minute.
RATETYPE_PER_MINUTE_NATURALRate is the cost per natural minute during which the resource is used for any duration.
RATETYPE_PER_HOUR_PRORATARate is the cost per hour and/or fraction of an hour.
RATETYPE_PER_HOUR_ROUNDUPRate is the cost per hour. Cost is rounded up to the nearest hour.
RATETYPE_PER_HOUR_NATURALRate is the cost per natural hour during which the resource is used for any duration.
RATETYPE_PER_DAY_PRORATARate is the cost per working day and/or fraction of a working day. The duration of a working day must also be passed to the function when using this type of rate.
RATETYPE_PER_DAY_ROUNDUPRate is the cost per working day. Cost is rounded up to the nearest full working day. The duration of a working day must also be passed to the function when using this type of rate.
RATETYPE_PER_DAY_NATURALRate is the cost per working day during which the resource is used for any duration.
Pro-Rata Rate Types
Pro-Rata rate types have a unit of cost defined per unit of time. If the resource usage includes a fraction of the rate's unit of time, then the calculated cost will include a proportional fraction of the cost of one time unit.
Round-up Rate Types
Round-up rate types calculate the cost similarly to the Pro-Rata rate, however number of units of time used is rounded-up to the next whole integer.
Natural Rate Types
Natural rate types do not calculate the total resource usage by summing all of the durations of intervals of time during which the resource was used. This rate type requires counting all of the natural time units which overlap with intervals of resource usage.
A natural time unit is one which has a begin and end time which coincide with those defined by a clock or calendar. The natural day is the interval of time between 00:00 midnight and the subsequent occurrence of midnight. A natural minute is the interval of time on a clock from when the seconds count is zero until the following instant when the seconds count is zero.
RATETYPE_PER_DAY_PRORATA and RATETYPE_PER_DAY_ROUNDUP require that the duration of the working day interval is defined. An 8 hour work day is defined by default but this can be any value between 0 and 24 hours.
This method takes an array of
DateSpan objects, an optional timezone
identifier, and then calculates the sum of the costs due to all of the
DateSpan objects for a specific
CostRule. The method returns and object
with three data members:
cost. A number containing the total sum of all of the costs accumulated by
DateSpanobjects which overlapped with the time-spans defined by the
usedSpans: An array of
DateSpanobjects, each of which indicates an interval of time for which there was an overlap and costs were accumulated by the
remainderSpans: An array of remainder
DateSpanobjects, each of which represents an interval of time during which no costs were accrued because there was no overlap with the time interval defined by the
The following example code is based on a test case which is available in the
unit-costrule.js. Several cost rules are defined, both for peak and
non-peak times during the week. The times are defined as:
- Tuesday from 9am-6pm at a cost of 3 units per pro-rata hour of resource usage.
- Wednesday from 9am-6pm at a cost of 4 units per pro-rata hour of resource usage.
- Friday from 9am-6pm at a cost of 6 units per pro-rata hour of resource usage.
- Friday off-peak from midnight-midnight at a cost of 1 unit per pro-rata hour of resource usage.
- Saturday off-peak from midnight-midnight at a cost of 1 unit per pro-rata hour of resource usage.
- Sunday off-peak from midnight-midnight at a cost of 1 unit per pro-rata hour of resource usage.
The actual resource is used during a combination of peak and non-peak times:
- Wednesday 5.7.2017, 16:00 - 17:00. 1 hour during peak period.
- Friday 14.7.2017, 12:00 - 17:00. 5 hours during peak period.
- Friday 14.7.2017, 19:00 - 23:00. 4 hours during non-peak period.
- Saturday 15.7.2017, 10:00 - 22:00. 12 hours during non-peak period.
- Sunday 16.7.2017, 13:00 - 17:00. 4 hours during non-peak period.
CostRule objects are used in order of their priority i.e. peak cost rules are
applied before non-peak cost rules are applied. If a
CostRule does not overlap
with a date-span of resource usage, then the
totalCost() method will return
DateSpans in the array
var caltime = ;var calcost = ;/* timezones */const TZ_UTC = 'Etc/UTC'; // UTC timezone// Peak during 09:00-18:00const timespanPeak = caltime; // 09:00-18:00// Tuesday Peakconst timeruleTuesday = caltime;const costruleTuesday =;// Wednesday Peakconst timeruleWednesday = caltime;const costruleWednesday =;// Friday Peakconst timeruleFriday = caltime;const costruleFriday =;// Friday Off-peakconst timespanOffPeak = caltime; // 00:00 - 00:00+1const timeruleOffPeakFriday = caltime;const costruleOffPeakFriday =;// Saturday Off-peakconst timeruleOffPeakSaturday = caltime;const costruleOffPeakSaturday =;// Sunday Off-peakconst timeruleOffPeakSunday = caltime;const costruleOffPeakSunday =;// resource used for 6 hours during peak and 20 hours off-peak.const spanA = caltime; // Wednesday, 16:00 - 17:00, 1 hr. peakconst spanB = caltime; // Friday, 12:00 - 17:00, 5 hrs. peakconst spanC = caltime; // Friday 19:00 - 23:00, 4 hrs. off-peakconst spanD = caltime; // Saturday, 10:00 - 22:00, 12 hrs. off-peakconst spanE = caltime; // Sunday, 13:00 - 17:00, 4 hrs. off-peakconst datespans = spanA spanB spanC spanD spanE;// step through the cost rules to calculate the total costlet sumCost = 00;// Tuesdaylet ruleResult = costruleTuesday;sumCost += ruleResultcost;// WednesdayruleResult = costruleWednesday;sumCost += ruleResultcost;// FridayruleResult = costruleFriday;sumCost += ruleResultcost;// Friday off-peakruleResult = costruleOffPeakFriday;sumCost += ruleResultcost;// Saturday off-peakruleResult = costruleOffPeakSaturday;sumCost += ruleResultcost;// Sunday off-peakruleResult = costruleOffPeakSunday;sumCost += ruleResultcost;// total cost due to all cost-rulesconsole; // 54.0
The module makes several constants available in the
constants object. Each
constant is a data member of this object. These constants define the way the
costs are calculated for a specific
CostRule when they are passed to the
inRateType parameter of the
costRule functional constructor.
The latest version of the API documentation can be generated using
documentation is created in the
$ cd <calcost-git-clone>$ npm run -s doc
Bug Reports and New Feature Requests should be reported at the CalCost GitHub Issues Page.
calcost currently depends on three modules when in production. Other modules are
required to test or develop
calcost. The production dependencies are:
calcost is copyright (c) 2017-2018 Michael McCarthy email@example.com.
calcost is free software, licensed under the MIT licence. See the file
in this distribution for more information.