diff --git a/README.md b/README.md index 96906ab..aa13e77 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ A central class in Nifty ToU is [TemporalRangesTariff](./docs/md/nifty-tou.tempo that defines a set of tariff values with a set of time-based constraints. The implication is that the tariff values apply only when all the time-based constraints are valid. -The time-based constraints are encoded as [IntRange](docs/md/nifty-tou.intrange.md) objects, +The time-based constraints are encoded as [IntRange](./docs/md/nifty-tou.intrange.md) objects, that are integer ranges with minimum and maximum values that define the bounds of the constraint. The supported time-based constraints are: @@ -207,6 +207,26 @@ new TariffRate("Morning Fixed", 125, -2); new TariffRate("Morning Variable", 1, -1); ``` +# Chronological tariffs + +The [ChronoTariff](./docs/md/nifty-tou.chronotariff.md) class can be used to model a time-based +"fixed" tariff, such as a daily or monthly charge. For example: + +```ts +// construct a chronological tariff @ 10/day +const tariff = new ChronoTariff(ChronoTariffUnit.DAYS, 10); + +// calculate the tariff cost over a 7 day time range +const cost = + tariff.rate * + tariff.quantity( + new Date("2024-01-01T00:00:00Z"), + new Date("2024-01-08T00:00:00Z"), + true + ); +cost === 70; // 7 days @ 10/day +``` + # Language support Nifty ToU supports parsing and formatting text-based range values, in different languages. For diff --git a/dist/nifty-tou.d.ts b/dist/nifty-tou.d.ts index 1d2b040..a63ed12 100644 --- a/dist/nifty-tou.d.ts +++ b/dist/nifty-tou.d.ts @@ -157,6 +157,61 @@ export declare class ChronoFieldValue { get rangeValue(): number | null; } +/** + * A chronologically-based tariff, such as a "daily" charge. + * @public + */ +export declare class ChronoTariff { + #private; + /** + * Constructor. + * + * @param chronoUnit - the chrono unit + * @param rate - the rate per chrono unit + * @param name - an optional description + */ + constructor(chronoUnit: ChronoTariffUnit, rate: number, name?: string); + /** Get the unit. */ + get unit(): ChronoTariffUnit; + /** Get the rate. */ + get rate(): number; + /** Get the optional name. */ + get name(): string | undefined; + /** + * Calcualte the count of units between two dates. + * + * The cost of this tariff can be calculated by multiplying the `rate` by the result + * of this method, for example: + * + * ```ts + * const tariff = new ChronoTariff(ChronoTariffUnit.DAYS, 10); + * tariff.rate * tariff.quantity( + * new Date('2024-01-01T00:00:00Z'), + * new Date('2024-01-08T00:00:00Z'), + * true) === 70; // 7 days @ 10/day + * ``` + * + * @param from - the starting date + * @param to - the ending date (exclusive) + * @param utc - if `true` then use UTC date components, otherwise assume the local time zone + * @returns the count of units between `from` and `to`, including any fractional component + */ + quantity(from: Date, to: Date, utc?: boolean): number; +} + +/** + * An enumeration of supported chronological tariff units of the Gregorian calendar. + * @public + */ +export declare enum ChronoTariffUnit { + /** Days */ + DAYS = 0, + /** Weeks */ + WEEKS = 1, + /** Months */ + MONTHS = 2 +} + /** * API for a comparison between similar objects. * @public diff --git a/docs/md/nifty-tou.chronotariff._constructor_.md b/docs/md/nifty-tou.chronotariff._constructor_.md new file mode 100644 index 0000000..786fb4e --- /dev/null +++ b/docs/md/nifty-tou.chronotariff._constructor_.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [nifty-tou](./nifty-tou.md) > [ChronoTariff](./nifty-tou.chronotariff.md) > [(constructor)](./nifty-tou.chronotariff._constructor_.md) + +## ChronoTariff.(constructor) + +Constructor. + +**Signature:** + +```typescript +constructor(chronoUnit: ChronoTariffUnit, rate: number, name?: string); +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| chronoUnit | [ChronoTariffUnit](./nifty-tou.chronotariffunit.md) | the chrono unit | +| rate | number | the rate per chrono unit | +| name | string | _(Optional)_ an optional description | + diff --git a/docs/md/nifty-tou.chronotariff.md b/docs/md/nifty-tou.chronotariff.md new file mode 100644 index 0000000..aa00ae3 --- /dev/null +++ b/docs/md/nifty-tou.chronotariff.md @@ -0,0 +1,42 @@ + + +[Home](./index.md) > [nifty-tou](./nifty-tou.md) > [ChronoTariff](./nifty-tou.chronotariff.md) + +## ChronoTariff class + +A chronologically-based tariff, such as a "daily" charge. + +**Signature:** + +```typescript +export default class ChronoTariff +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(chronoUnit, rate, name)](./nifty-tou.chronotariff._constructor_.md) | | Constructor. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [name](./nifty-tou.chronotariff.name.md) | readonly | string \| undefined | Get the optional name. | +| [rate](./nifty-tou.chronotariff.rate.md) | readonly | number | Get the rate. | +| [unit](./nifty-tou.chronotariff.unit.md) | readonly | [ChronoTariffUnit](./nifty-tou.chronotariffunit.md) | Get the unit. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [quantity(from, to, utc)](./nifty-tou.chronotariff.quantity.md) | |

Calcualte the count of units between two dates.

The cost of this tariff can be calculated by multiplying the rate by the result of this method, for example:

+```ts +const tariff = new ChronoTariff(ChronoTariffUnit.DAYS, 10); +tariff.rate * tariff.quantity( + new Date('2024-01-01T00:00:00Z'), + new Date('2024-01-08T00:00:00Z'), + true) === 70; // 7 days @ 10/day +``` + | + diff --git a/docs/md/nifty-tou.chronotariff.name.md b/docs/md/nifty-tou.chronotariff.name.md new file mode 100644 index 0000000..ce81483 --- /dev/null +++ b/docs/md/nifty-tou.chronotariff.name.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [nifty-tou](./nifty-tou.md) > [ChronoTariff](./nifty-tou.chronotariff.md) > [name](./nifty-tou.chronotariff.name.md) + +## ChronoTariff.name property + +Get the optional name. + +**Signature:** + +```typescript +get name(): string | undefined; +``` diff --git a/docs/md/nifty-tou.chronotariff.quantity.md b/docs/md/nifty-tou.chronotariff.quantity.md new file mode 100644 index 0000000..d6d1555 --- /dev/null +++ b/docs/md/nifty-tou.chronotariff.quantity.md @@ -0,0 +1,38 @@ + + +[Home](./index.md) > [nifty-tou](./nifty-tou.md) > [ChronoTariff](./nifty-tou.chronotariff.md) > [quantity](./nifty-tou.chronotariff.quantity.md) + +## ChronoTariff.quantity() method + +Calcualte the count of units between two dates. + +The cost of this tariff can be calculated by multiplying the `rate` by the result of this method, for example: + +```ts +const tariff = new ChronoTariff(ChronoTariffUnit.DAYS, 10); +tariff.rate * tariff.quantity( + new Date('2024-01-01T00:00:00Z'), + new Date('2024-01-08T00:00:00Z'), + true) === 70; // 7 days @ 10/day +``` + +**Signature:** + +```typescript +quantity(from: Date, to: Date, utc?: boolean): number; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| from | Date | the starting date | +| to | Date | the ending date (exclusive) | +| utc | boolean | _(Optional)_ if true then use UTC date components, otherwise assume the local time zone | + +**Returns:** + +number + +the count of units between `from` and `to`, including any fractional component + diff --git a/docs/md/nifty-tou.chronotariff.rate.md b/docs/md/nifty-tou.chronotariff.rate.md new file mode 100644 index 0000000..8ba193a --- /dev/null +++ b/docs/md/nifty-tou.chronotariff.rate.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [nifty-tou](./nifty-tou.md) > [ChronoTariff](./nifty-tou.chronotariff.md) > [rate](./nifty-tou.chronotariff.rate.md) + +## ChronoTariff.rate property + +Get the rate. + +**Signature:** + +```typescript +get rate(): number; +``` diff --git a/docs/md/nifty-tou.chronotariff.unit.md b/docs/md/nifty-tou.chronotariff.unit.md new file mode 100644 index 0000000..0e94ae7 --- /dev/null +++ b/docs/md/nifty-tou.chronotariff.unit.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [nifty-tou](./nifty-tou.md) > [ChronoTariff](./nifty-tou.chronotariff.md) > [unit](./nifty-tou.chronotariff.unit.md) + +## ChronoTariff.unit property + +Get the unit. + +**Signature:** + +```typescript +get unit(): ChronoTariffUnit; +``` diff --git a/docs/md/nifty-tou.chronotariffunit.md b/docs/md/nifty-tou.chronotariffunit.md new file mode 100644 index 0000000..c56a3eb --- /dev/null +++ b/docs/md/nifty-tou.chronotariffunit.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [nifty-tou](./nifty-tou.md) > [ChronoTariffUnit](./nifty-tou.chronotariffunit.md) + +## ChronoTariffUnit enum + +An enumeration of supported chronological tariff units of the Gregorian calendar. + +**Signature:** + +```typescript +export declare enum ChronoTariffUnit +``` + +## Enumeration Members + +| Member | Value | Description | +| --- | --- | --- | +| DAYS | 0 | Days | +| MONTHS | 2 | Months | +| WEEKS | 1 | Weeks | + diff --git a/docs/md/nifty-tou.md b/docs/md/nifty-tou.md index 1200540..5505c4d 100644 --- a/docs/md/nifty-tou.md +++ b/docs/md/nifty-tou.md @@ -12,6 +12,7 @@ A delightful little library for working with time-of-use tariffs. | --- | --- | | [ChronoFieldFormatter](./nifty-tou.chronofieldformatter.md) | Class to parse locale-specific chronological field names of the Gregorian calendar. | | [ChronoFieldValue](./nifty-tou.chronofieldvalue.md) | A chronological field value. | +| [ChronoTariff](./nifty-tou.chronotariff.md) | A chronologically-based tariff, such as a "daily" charge. | | [IntRange](./nifty-tou.intrange.md) | An immutable number range with min/max values. | | [NumberFormatter](./nifty-tou.numberformatter.md) | A locale-specific number parser. | | [TariffRate](./nifty-tou.tariffrate.md) | An identifiable tariff rate. | @@ -25,6 +26,7 @@ A delightful little library for working with time-of-use tariffs. | Enumeration | Description | | --- | --- | | [ChronoField](./nifty-tou.chronofield.md) | An enumeration of supported chronological fields of the Gregorian calendar. | +| [ChronoTariffUnit](./nifty-tou.chronotariffunit.md) | An enumeration of supported chronological tariff units of the Gregorian calendar. | ## Interfaces diff --git a/etc/nifty-tou.api.md b/etc/nifty-tou.api.md index 29cf53a..4bdf777 100644 --- a/etc/nifty-tou.api.md +++ b/etc/nifty-tou.api.md @@ -40,6 +40,22 @@ export class ChronoFieldValue { get value(): number; } +// @public +export class ChronoTariff { + constructor(chronoUnit: ChronoTariffUnit, rate: number, name?: string); + get name(): string | undefined; + quantity(from: Date, to: Date, utc?: boolean): number; + get rate(): number; + get unit(): ChronoTariffUnit; +} + +// @public +export enum ChronoTariffUnit { + DAYS = 0, + MONTHS = 2, + WEEKS = 1 +} + // @public export interface Comparable { compareTo(o: T | undefined): number;