feature/stable (#135)

* Update dependency xml2js to v0.6.2

* transform response namning

* clean up method

* improve tests

* require startDate for dayAheadPrices

* Update swc monorepo

* rename `BiddingZones` const to `BiddingZonesByCountry`

* documentation

* misc

* update `swc` config

---------

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Author: rabinage

.eslintrc.js

@@ -1,3 +1,4 @@
+/** @type {import('eslint').ESLint.ConfigData} */
 module.exports = {
   parserOptions: {
     ecmaVersion: "latest",

.github/workflows/ci.yaml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
+    branches: ["**"]
 
 jobs:
   code-check:
@@ -30,10 +30,7 @@ jobs:
         run: npm run lint:check
 
       - name: Run tests
-        run: npm run test
-        env:
-          API_TOKEN: ${{ secrets.ENTSOE_API_TOKEN }}
-          TZ: Europe/London
+        run: npm run test --verbose
 
       - name: Run build
         run: npm run build

.gitignore

@@ -44,6 +44,7 @@ build/Release
 # Build / generate output
 dist/
 lib/
+coverage/
 
 # Dependency directories
 node_modules/
@@ -62,10 +63,7 @@ node_modules/
 
 # dotenv environment variable files
 .env
-.env.development.local
-.env.test.local
-.env.production.local
-.env.local
+.env*.local
 
 # yarn v2
 .yarn/cache

.swcrc

@@ -2,8 +2,7 @@
   "jsc": {
     "parser": {
       "syntax": "ecmascript"
-    },
-    "target": "es5"
+    }
   },
   "module": {
     "type": "commonjs"

README.md

@@ -4,7 +4,7 @@
 
 ### Why this wrapper
 
-The API responses from the [ENTSO-E Transparency Platform](https://transparency.entsoe.eu) are formatted in XML, which may not be easily consumable in JavaScript applications. This wrapper automatically converts the response into the more compatible JSON format.
+The API responses from the [ENTSO-E Transparency Platform](https://transparency.entsoe.eu) are formatted in XML, which may not be easily consumable in JavaScript applications. This wrapper transforms the response into the more compatible JSON format.
 
 - [ENTSO-E Transparency Platform](https://transparency.entsoe.eu/dashboard/show)
 - [Transparency Platform API spec.](https://transparency.entsoe.eu/content/static_content/Static%20content/web%20api/Guide.html)
@@ -18,7 +18,7 @@ The API responses from the [ENTSO-E Transparency Platform](https://transparency.
 - [Public REST Endpoints](#public-rest-endpoints)
   - [dayAheadPrices](#day-ahead-prices)
 - [Miscellaneous](#miscellaneous)
-  - [BiddingZones](#bidding-zones)
+  - [Bidding zones](#bidding-zones)
 
 ### Installation
 
@@ -29,13 +29,13 @@ The API responses from the [ENTSO-E Transparency Platform](https://transparency.
 To use this wrapper, you must first register with the Transparency Platform and request access to the RESTful API by sending an email to [email protected] with 'Restful API access' in the subject line. Be sure to include the email address you used during registration in the email body. Once granted access, you can then generate a security token under the account settings.
 
 ```js
-import Entsoe, { BiddingZones } from "entsoe-api-node";
+import Entsoe, { BiddingZonesByCountry } from "entsoe-api-node";
 
 const client = Entsoe({ apiToken: "YOUR-SECURITY-TOKEN" });
 
 const result = await client.dayAheadPrices({
   startDate: new Date().toISOString(),
-  biddingZone: BiddingZones.SW4,
+  biddingZone: BiddingZonesByCountry.SE4,
 });
 ```
 
@@ -81,11 +81,11 @@ console.log(
 );
 ```
 
-| Param       | Type   | Required | Default                | Info                          |
-| ----------- | ------ | -------- | ---------------------- | ----------------------------- |
-| biddingZone | String | true     |                        |
-| startDate   | String | false    | Current locale date    | ISO 8601 formated date string |
-| endDate     | String | false    | `startDate` + next day | ISO 8601 formated date string |
+| Param       | Type   | Required | Default                | Info                                                                                                                                  |
+| ----------- | ------ | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| biddingZone | String | true     |                        | Check out the utility [`BiddingZonesByCountry`](https://github.com/rabinage/entsoe-api-node#bidding-zones) for available zones/areas. |
+| startDate   | String | true     |                        | ISO 8601 formated date string                                                                                                         |
+| endDate     | String | false    | `startDate` + next day | ISO 8601 formated date string                                                                                                         |
 
 - One year range limit applies
 - Minimum time interval between `startDate` and `endDate` is one day
@@ -158,14 +158,16 @@ console.log(
 
 ### Miscellaneous
 
-#### BiddingZones
+#### Bidding zones
 
 An utility bidding zone map is also being exported by the package in order for you to make readable request while using the API.
 
 ```js
-import { BiddingZones } from "entsoe-api-node";
+import { BiddingZonesByCountry } from "entsoe-api-node";
 
-console.log(await client.dayAheadPrices({ biddingZone: BiddingZones.SW4 }));
+console.log(
+  await client.dayAheadPrices({ biddingZone: BiddingZonesByCountry.SE4 }),
+);
 ```
 
 ##### This project is based on the [node-module-swc-cjs](https://github.com/rabinage/starters/tree/main/node-module-swc-cjs) starter. Check it out for more production ready starters!

example/custom-response-transformer.js

@@ -1,5 +1,5 @@
 import { parseStringPromise } from "xml2js";
-import Entsoe, { BiddingZones } from "../src/index";
+import Entsoe, { BiddingZonesByCountry } from "../src/index";
 
 /**
  * Example using a custom response transformer.
@@ -15,6 +15,6 @@ const customRt = async (xmlString) => {
   return json;
 };
 client
-  .dayAheadPrices({ biddingZone: BiddingZones.SW4 }, customRt)
+  .dayAheadPrices({ biddingZone: BiddingZonesByCountry.SE4 }, customRt)
   // eslint-disable-next-line no-console
   .then((res) => console.log(res));

example/day-and-night-prices.js

@@ -1,4 +1,4 @@
-import Entsoe, { BiddingZones } from "../src/index";
+import Entsoe, { BiddingZonesByCountry } from "../src/index";
 
 /**
  * Print the current day and night price.
@@ -12,7 +12,7 @@ const client = Entsoe({ apiToken: process.env.API_TOKEN });
 client
   .dayAheadPrices({
     startDate: new Date().toISOString(),
-    biddingZone: BiddingZones.SW4,
+    biddingZone: BiddingZonesByCountry.SE4,
   })
   .then((res) => {
     res.timeSeries.forEach((ts) => {

index.d.ts

@@ -1,14 +1,21 @@
 declare module "entsoe-api-node" {
+  /**
+   * Unofficial API wrapper for the ENTSO-E Transparency Platform.
+   * @see {@link https://transparency.entsoe.eu/content/static_content/Static%20content/web%20api/Guide.html} ENTSO-E Transparency Platform RESTful API documentation.
+   * @see {@link https://transparency.entsoe.eu/content/static_content/Static%20content/web%20api/Guide.html#_complete_parameter_list} Entsoe Transparency Platform RESTful API Appendix.
+   * @see {@link https://github.com/rabinage/entsoe-api-node} Wrapper documentation.
+   * @param {string} apiToken - API security token {@link https://github.com/rabinage/entsoe-api-node#getting-started}.
+   * @param {boolean} testnet - Optional. For testing purpose only.
+   */
   export default function (options?: {
     apiToken: string;
     testnet?: boolean;
   }): Entsoe;
 
-  export const enum DocumentTypes {
-    PRICE_DOCUMENT = "A44",
-  }
-
-  export const enum BiddingZones {
+  /**
+   * A.15. Areas divided into country codes, followed by potential zone number.
+   */
+  export const enum BiddingZonesByCountry {
     AL = "10YAL-KESH-----5", // Albania
     AT = "10Y1001A1001A63L", // Austria
     BA = "10YBA-JPCC-----D", // Bosnia and Herzegovina
@@ -49,10 +56,10 @@ declare module "entsoe-api-node" {
     PT = "10YPT-REN------W", // Portugal
     RO = "10YRO-TEL------P", // Romania
     RS = "10YCS-SERBIATSOV", // Serb
-    SW1 = "10Y1001A1001A44P", // Sweden zone 1
-    SW2 = "10Y1001A1001A45N", // Swden zone 2
-    SW3 = "10Y1001A1001A46L", // Swden zone 3
-    SW4 = "10Y1001A1001A47J", // Sweden zone 4
+    SE1 = "10Y1001A1001A44P", // Sweden zone 1
+    SE2 = "10Y1001A1001A45N", // Swden zone 2
+    SE3 = "10Y1001A1001A46L", // Swden zone 3
+    SE4 = "10Y1001A1001A47J", // Sweden zone 4
     SL = "10YSI-ELES-----O", // Slovenia
     SK = "10YSK-SEPS-----K", // Slovak Republic
   }
@@ -103,10 +110,15 @@ declare module "entsoe-api-node" {
   interface DayAheadPriceResponseTransformer extends ResponseTransformer {}
 
   export interface Entsoe {
-    // Article 12.1.D
+    /**
+     * A.12.1.D. Day ahead prices.
+     * @param {string} biddingZone - Bidding zone/area code.
+     * @param {string} startDate - ISO 8601 formated date string.
+     * @param {string} endDate - Optional. ISO 8601 formated date string.
+     */
     dayAheadPrices(
       payload: {
-        biddingZone: BiddingZones;
+        biddingZone: string;
         startDate?: string;
         endDate?: string;
       },

jest.config.js

@@ -1,7 +1,17 @@
+const thresholdPercentage = 80;
+
+/** @type {import('jest').Config} */
 module.exports = {
   transform: {
     "^.+\\.js?$": ["@swc/jest"],
   },
   testEnvironment: "node",
-  testMatch: ["<rootDir>/test/**/*"],
+  testMatch: ["<rootDir>/test/**/?(*.)test.js"],
+  coverageThreshold: {
+    global: {
+      functions: thresholdPercentage,
+      lines: thresholdPercentage,
+      statements: thresholdPercentage,
+    },
+  },
 };