new features: ISO updates

CHANGELOG.md

@@ -1,6 +1,34 @@
 # Changelog
 Strictly follows [Semantic Versioning 2.0.0.](https://semver.org/)
 
+## v1.12.0
+`2022-12-22`\
+\
+:rocket: Features:
+- [`getIso3166Countries()`](DOCUMENTATION.md#getIso3166Countries) - `"Turkey"` country name has been changed to `"Türkiye"`
+```typescript
+{
+  countryName: "Türkiye",
+  officialStateName: "The Republic of Türkiye",
+  alpha2Code: "TR",
+  alpha3Code: "TUR",
+  numericCode: 792
+}
+```
+- [`getIso4217Currencies()`](DOCUMENTATION.md#getIso4217Currencies) - from `2023-01-01` Kuna currency (HRK) will be treated as historical because Croatia joins the euro. New argument `statusForTheDay` has been introduced. When `statusForTheDay` is defined then only valid (non-historical) currencies are returned. `statusForTheDay = undefined` means today (`new Date()`). `Iso4217Currency` has two new optional properties: `historicalFrom?: DateIsoString`, `introducedIn?: DateIsoString` (for future use).
+```typescript
+getIso4217Currencies(statusForTheDay?: Date | DateIsoString): Iso4217Currency[]
+
+interface Iso4217Currency {
+  // ... old properties
+  historicalFrom?: DateIsoString; // e.g. "2023-01-01"
+  introducedIn?: DateIsoString;
+}
+```
+
+:wrench: Internal:
+- TypeScript upgrade `4.7.2` -> `4.9.4`
+
 ## v1.11.0
 `2022-10-24`\
 \

DOCUMENTATION.md

@@ -497,6 +497,8 @@ To get `currencyName` in your local culture please use [`formatCurrency()`](DOCU
 import { getIso4217Currencies } from '@dnvgl/i18n';
 
 getIso4217Currencies(); // returns [{ alpha3Code: "AED", currencyName: "UAE Dirham", numericCode: 784, minorUnit: 2 }, { alpha3Code: "AFN",...}]
+getIso4217Currencies("2023-01-01"); // e.g. Kuna (HRK) currency is not on the list
+getIso4217Currencies(new Date("2022-12-31")); // e.g. Kuna (HRK) currency is on the list
 ```
 Example integration with [`formatCurrency()`](DOCUMENTATION.md#formatCurrency):
 ```typescript

__tests__/getIso4217Currencies.test.ts

@@ -8,13 +8,32 @@ const nameof = <T>(name: keyof T) => name;
 
 describe('getIso4217Currencies', () => {
   test('all properties are properly defined', () => {
-    const countries = getIso4217Currencies();
-    expect(countries).toHaveLength(181);
+    const countries = getIso4217Currencies("2022-12-31");
     expect(countries.every(x => x.alpha3Code.length === 3 && x.alpha3Code.toUpperCase() === x.alpha3Code)).toBeTruthy();
     expect(countries.every(x => x.currencyName.length > 0)).toBeTruthy();
     expect(countries.every(x => x.minorUnit === null || (typeof x.minorUnit === "number" && x.minorUnit >= 0 && x.minorUnit <= 4 ))).toBeTruthy();
     expect(countries.every(x => typeof x.numericCode === "number" && (x.numericCode > 0 || x.numericCode < 1000))).toBeTruthy();
     expect(countries.every(x => x.isFund === undefined || x.isFund === true)).toBeTruthy();
+    expect(countries.every(x => x.historicalFrom === undefined || x.historicalFrom.length === 10)).toBeTruthy();
+    expect(countries.every(x => x.introducedIn === undefined || x.introducedIn.length === 10)).toBeTruthy();
+  });
+
+  test('Kuna currency is not returned', () => {
+    const countries = getIso4217Currencies("2023-01-01");
+    expect(countries).toHaveLength(180);
+    expect(countries.find(x => x.alpha3Code === "HRK")).toBeUndefined();
+  });
+
+  test('Kuna currency is returned', () => {
+    const countries = getIso4217Currencies("2022-12-31");
+    expect(countries).toHaveLength(181);
+    expect(countries.find(x => x.alpha3Code === "HRK")).toBeDefined();
+  });
+
+  test('function should return the same reference', () => {
+    const countries1 = getIso4217Currencies("2022-12-31");
+    const countries2 = getIso4217Currencies("2022-12-31");
+    expect(countries1 === countries2).toBeTruthy();
   });
 
   test.each([

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dnvgl/i18n",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "A set of functions to support multiple languages/cultures in a browser or Node.js",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -33,12 +33,12 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/jest": "^29.2.0",
-    "jest": "^29.2.2",
-    "jest-environment-jsdom": "^29.2.2",
+    "@types/jest": "^29.2.4",
+    "jest": "^29.3.1",
+    "jest-environment-jsdom": "^29.3.1",
     "rimraf": "^3.0.2",
     "ts-jest": "^29.0.3",
     "ts-node": "^10.8.0",
-    "typescript": "^4.7.2"
+    "typescript": "^4.9.4"
   }
 }

src/getIso4217Currencies.ts

@@ -1,6 +1,27 @@
+import { convertToDate } from "./internal/convertToDate";
 import { iso4217Currencies } from "./internal/iso4217Currencies";
+import { DateIsoString } from "./types/dateIsoString";
 import { Iso4217Currency } from "./types/iso4217";
 
-export function getIso4217Currencies(): Iso4217Currency[] {
-  return iso4217Currencies;
+const _cache: Record<string, Iso4217Currency[]> = {};
+
+export function getIso4217Currencies(statusForTheDay?: Date | DateIsoString): Iso4217Currency[] {
+  const limit = statusForTheDay ? convertToDate(statusForTheDay) : new Date(),
+    year = limit.getFullYear(),
+    month = limit.getMonth() + 1,
+    day = limit.getDate();
+
+  const dateKey = `${year}-${month.toString().padStart(2, "0")}-${day.toString().padStart(2, "0")}`;
+  const cachedResult = _cache[dateKey];
+
+  if (cachedResult) {
+    return cachedResult;
+  }
+
+  const list = iso4217Currencies.filter(x => (!x.historicalFrom || x.historicalFrom > dateKey) 
+    && (!x.introducedIn || x.introducedIn <= dateKey));
+
+  _cache[dateKey] = list;
+
+  return list;
 }

src/internal/iso3166Countries.ts

@@ -1592,8 +1592,8 @@ export const iso3166Countries: Iso3166Country[] = [
     numericCode: 788
   },
   {
-    countryName: "Turkey",
-    officialStateName: "The Republic of Turkey",
+    countryName: "Türkiye",
+    officialStateName: "The Republic of Türkiye",
     alpha2Code: "TR",
     alpha3Code: "TUR",
     numericCode: 792

src/internal/iso4217Currencies.ts

@@ -377,7 +377,8 @@ export const iso4217Currencies: Iso4217Currency[] = [
     alpha3Code: "HRK",
     currencyName: "Kuna",
     numericCode: 191,
-    minorUnit: 2
+    minorUnit: 2,
+    historicalFrom: "2023-01-01"
   },
   {
     alpha3Code: "HTG",

src/types/iso4217.ts

@@ -1,9 +1,13 @@
+import { DateIsoString } from "./dateIsoString";
+
 export interface Iso4217Currency {
   alpha3Code: Iso4217Alpha3Code;
   currencyName: string;
   numericCode: Iso4217NumericCode;
   minorUnit: number|null;
   isFund?: true;
+  historicalFrom?: DateIsoString;
+  introducedIn?: DateIsoString;
 }
 
 export type Iso4217Alpha3Code = string;