Documentation deluxe

README.md

@@ -11,13 +11,24 @@ ENTSO-e transparency platform API Client built for Deno. Complete. Easy to use.
 *   Unzips and parses zip-file endpoints (e.g. outage documents) transparently
 *   Includes examples for getting Outages, Spot-prices, actual generation and generation forecast
 
-### Examples
+### Documentation
+
+Full documentation is available at [https://deno.land/x/entsoe_api_client/mod.ts](https://deno.land/x/entsoe_api_client/mod.ts)
+
+> **Note**
+> These are the document types currently supported:
+>
+> - Publication_MarketDocument
+> - GL_MarketDocument
+> - Unavailability_MarketDocument
+>
+> Contributions to handling more document types would be highly appreciated.
 
-See [/examples](/examples) folder for complete examples.
+### Examples
 
-Pass your entso-e API key by environment variable API_TOKEN when running the examples.
+Examples can be found in the [/examples](/examples) directory.
 
-To get todays spot prices:
+Pass your ENTSO-e API key by environment variable API_TOKEN when running the examples.
 
 Powershell
 
@@ -33,7 +44,12 @@ API_TOKEN="your-api-token" deno run -A .\spot-prices-today.ts
 
 ## Contributing
 
-All contributions are welcome. See [Contribution Guide](/CONTRIBUTING.md)
+All contributions are welcome. 
+
+See [Contribution Guide](/CONTRIBUTING.md)
+
+> **Note**
+> Please run `deno task precommit` before each commit, to make sure every file is tested/formatted/linted to standards.
 
 ## License
 

deps.js

@@ -1,2 +1,11 @@
+/**
+ * entsoe-api-client
+ * 
+ * @file Helper re-exporting all dependencies to the rest of the library
+ * 
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ */
+
 export { parse } from "https://deno.land/x/[email protected]/mod.ts";
 export { ZipReader, Uint8ArrayReader, TextWriter } from "https://deno.land/x/[email protected]/index.js"

examples/generation-forecast.ts

@@ -1,4 +1,14 @@
-import { QueryGL } from "https://deno.land/x/[email protected]/mod.ts";
+/**
+ * entsoe-api-client
+ * 
+ * @file Example on getting forecaster generation within a country
+ *       from ENTSO-e Rest API.
+ * 
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
+import { QueryGL } from "https://deno.land/x/[email protected]/mod.ts";
 
 // Prepare dates
 const

examples/generation-per-unit.ts

@@ -1,4 +1,14 @@
-import { QueryGL } from "https://deno.land/x/[email protected]/mod.ts";
+/**
+ * entsoe-api-client
+ * 
+ * @file Example on getting realised generation within a electicity price area
+ *       from ENTSO-e Rest API.
+ * 
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
+import { QueryGL } from "https://deno.land/x/[email protected]/mod.ts";
 
 // Prepare dates
 const

examples/outages.ts

@@ -1,4 +1,13 @@
-import { QueryUnavailability } from "https://deno.land/x/[email protected]/mod.ts";
+/**
+ * entsoe-api-client
+ * 
+ * @file Example on getting active outages +/- 30 days from ENTSO-e Rest API
+ * 
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
+import { QueryUnavailability } from "https://deno.land/x/[email protected]/mod.ts";
 
 // Prepare dates
 const
@@ -25,5 +34,6 @@ const result = await QueryUnavailability(
 for(const outage of result) {
     console.log("Outage: ");
     console.log(outage);
-    console.table(outage?.available);
+    // Print a table for first returned timeseries and period
+    console.table(outage?.timeseries[0].periods[0]);
 }

examples/spot-prices-today.ts

@@ -1,4 +1,13 @@
-import { QueryPublication } from "https://deno.land/x/[email protected]/mod.ts";
+/**
+ * entsoe-api-client
+ * 
+ * @file Example on getting spot prices for today and tomorrow from ENTSO-e Rest API
+ * 
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
+import { QueryPublication } from "https://deno.land/x/[email protected]/mod.ts";
 
 // Prepare dates
 const

mod.ts

@@ -1,30 +1,32 @@
-/* ------------------------------------------------------------------------------------
-
-  entsoe-api-client - MIT License - Hexagon <hexagon@GitHub>
-
-  ------------------------------------------------------------------------------------
-
-  License:
-
-	Copyright (c) 2022 Hexagon <hexagon@GitHub>
-
-	Permission is hereby granted, free of charge, to any person obtaining a copy
-	of this software and associated documentation files (the "Software"), to deal
-	in the Software without restriction, including without limitation the rights
-	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-	copies of the Software, and to permit persons to whom the Software is
-	furnished to do so, subject to the following conditions:
-	The above copyright notice and this permission notice shall be included in
-	all copies or substantial portions of the Software.
-	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
-	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-	THE SOFTWARE.
-
-  ------------------------------------------------------------------------------------  */
+/**
+ * entsoe-api-client
+ * 
+ * @file Main entrypoint of the library, exports all functions and interfaces from this library this is indended for public use. 
+ * 
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ * 
+ * Full license:
+ * 
+ * Copyright (c) 2022 Hexagon <hexagon@GitHub>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
 
 const ENTSOE_ENDPOINT = "https://web-api.tp.entsoe.eu/api";
 
@@ -35,6 +37,9 @@ import { ProcessType } from "./src/parameters/processtype.js";
 import { PsrType } from "./src/parameters/psrtype.js";
 import { ZipReader, Uint8ArrayReader, TextWriter } from "./deps.js";
 
+/**
+ * All available parameters
+ */
 interface QueryParameters {
   documentType: string;
   processType?: string;
@@ -51,6 +56,16 @@ interface QueryParameters {
   offset?: number;
 }
 
+/**
+ * Helper to validate input parameters
+ * 
+ * @private
+ * 
+ * @param securityToken - Entsoe API security token/key
+ * @param params - Object with all required parameters
+ * 
+ * @returns - Query string object ready to use
+ */
 const ComposeQuery = (securityToken: string, params: QueryParameters) : URLSearchParams => {
 
   const query = new URLSearchParams({
@@ -184,6 +199,33 @@ const ComposeQuery = (securityToken: string, params: QueryParameters) : URLSearc
   return query;
 };
 
+/**
+ * Function to request generic documents to the ENTSO-e Rest API
+ * 
+ * - Identies the fetched document, validates key features of each document,
+ *   and returns an array of typed documents
+ * 
+ * - Will throw if recieving a document other than the supported ones
+ *   
+ *   Currently supported document types:
+ * 
+ *   - Publication_MarketDocument
+ *   - GL_MarketDocument
+ *   - Unavailability_MarketDocument
+ * 
+ *  - Note: You should normally determine which document type you'll get
+ *          and use the properly typed and validated alternative.
+ * 
+ *          Example: If you expect a Publication document - use `QueryPublication()`
+ *          instead of `Query`
+ * 
+ * @public
+ * 
+ * @param securityToken - Entsoe API security token/key
+ * @param params - Object with all requested parameters
+ * 
+ * @returns - Array of typed documents 
+ */
 const Query = async (securityToken: string, params: QueryParameters): Promise<(PublicationDocument|GLDocument|UnavailabilityDocument)[]> => {
 
   const query = ComposeQuery(securityToken, params);
@@ -230,23 +272,77 @@ const Query = async (securityToken: string, params: QueryParameters): Promise<(P
   return documents;
 };
 
+/**
+ * Function to request a Publication_MarketDocument from the ENTSO-e Rest API
+ * 
+ *  - Identies the fetched docuement, validates key features of each document,
+ *    and returns an array of typed documents
+ * 
+ *  - If the query yield a document other than Publication_MarketDocument, an error 
+ *    will be thrown.
+ * 
+ * @public
+ * 
+ * @param securityToken - Entsoe API security token/key
+ * @param params - Obkect with all requested parameters
+ * 
+ * @returns - Array of typed documents 
+ */
 const QueryPublication = async (securityToken: string, params: QueryParameters): Promise<PublicationDocument[]> => {
   const result = await Query(securityToken, params);
   if (result && Array.isArray(result) && result.length && result[0].rootType === "publication") return result as PublicationDocument[];
   if (result && Array.isArray(result) && result.length && result[0].rootType !== "publication") throw new Error("Got " + result[0].rootType + " when expecting publication document")
   return [];
 };
+
+/**
+ * Function to request a GL_MarketDocument from the ENTSO-e Rest API
+ * 
+ *  - Identies the fetched docuement, validates key features of each document,
+ *    and returns an array of typed documents
+ * 
+ *  - If the query yield a document other than GL_MarketDocument, an error 
+ *    will be thrown.
+ * 
+ * @public
+ * 
+ * @param securityToken - Entsoe API security token/key
+ * @param params - Object with all requested parameters
+ * 
+ * @returns - Array of typed documents 
+ */
 const QueryGL = async (securityToken: string, params: QueryParameters): Promise<GLDocument[]> => {
   const result = await Query(securityToken, params);
   if (result && Array.isArray(result) && result.length && result[0].rootType === "gl") return result as GLDocument[];
   if (result && Array.isArray(result) && result.length && result[0].rootType !== "gl") throw new Error("Got " + result[0].rootType + " when expecting gl document")
   return [];
 };
+
+/**
+ * Function to request a Unavailability_MarketDocument from the ENTSO-e Rest API
+ * 
+ *  - Identies the fetched docuement, validates key features of each document,
+ *    and returns an array of typed documents
+ * 
+ *  - If the query yield a document other than Unavailability_MarketDocument, an error 
+ *    will be thrown.
+ * 
+ * @public
+ * 
+ * @param securityToken - Entsoe API security token/key
+ * @param params - Object with all requested parameters
+ * 
+ * @returns - Array of typed documents 
+ */
 const QueryUnavailability = async (securityToken: string, params: QueryParameters): Promise<UnavailabilityDocument[]> => {
   const result = await Query(securityToken, params);
   if (result && Array.isArray(result) && result.length && result[0].rootType === "unavailability") return result as UnavailabilityDocument[];
   if (result && Array.isArray(result) && result.length && result[0].rootType !== "unavailability") throw new Error("Got " + result[0].rootType + " when expecting unavailability document")
   return [];
 };
 
+/** Export all functions intended for public use */
 export { Query, QueryPublication, QueryGL, QueryUnavailability };
+
+/** Export all types intended for public use */
+export type { GLDocument, PublicationDocument, UnavailabilityDocument };

src/duration.ts

@@ -1,3 +1,29 @@
+/**
+ * entsoe-api-client
+ * 
+ * @file Helper for ISO8601 durations
+ * 
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
+/**
+ * Helper function which parses an ISO8601 duration
+ * 
+ * Supports all time parts, negative values and decimals, example: `PT1.5D1H5M1S`
+ * 
+ * Do currently NOT support the date-part of ISO8601 durations at the moment.
+ * Throws when supplied with date-part, example: `P1M1D`
+ * 
+ * Has internal shortcuts for common durations (e.g. PT60M, PT30M etc.), to increase performance.
+ * 
+ * Throws on any type of parsing error.
+ * 
+ * Maninly intended for internal use in this library.
+ * 
+ * @param pt - ISO8601 duration expressed as a string
+ * @returns - number of seconds
+ */
 const ISO8601DurToSec = (pt: string ) => {
 
     // Make sure pt is uppercase and trimmed

src/parameters/areas.js

@@ -1,3 +1,9 @@
+/**
+ * entsoe-api-client
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
 /**
  * Enum for ENTSO-e Areas with description
  * 

src/parameters/auctioncategory.js

@@ -1,3 +1,9 @@
+/**
+ * entsoe-api-client
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
 /**
  * Enum for ENTSO-e Auction.Category with description
  * @readonly

src/parameters/auctiontype.js

@@ -1,3 +1,9 @@
+/**
+ * entsoe-api-client
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
 /**
  * Enum for ENTSO-e Auction.Type with description
  * @readonly

src/parameters/businesstype.js

@@ -1,3 +1,9 @@
+/**
+ * entsoe-api-client
+ * @author Hexagon <hexagon@GitHub>
+ * @license MIT
+ **/
+
 /**
  * Enum for ENTSO-e Business.Type with description
  * @readonly