feat: error codes (#442)

* chore: update dependencies * fix: outdated options * chore: cleanup settings * docs: regenerate documentation * refactor: add `ValidationError.code` * chore: eslint fixes * chore: regenerate package-lock.json * chore: regenerate package-lock.json
schoero · Sep 1, 2024 · b8259bc · b8259bc
1 parent 78b19f1
commit b8259bc
Show file tree

Hide file tree

Showing 27 changed files with 1,125 additions and 972 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -4,7 +4,7 @@
       "args": [
         "run",
         "${relativeFileDirname}/${fileBasenameNoExtension}",
-        "--no-threads"
+        "--pool=forks"
       ],
       "autoAttachChildProcesses": true,
       "console": "integratedTerminal",
@@ -19,7 +19,7 @@
       "args": [
         "run",
         "${relativeFileDirname}/${fileBasenameNoExtension}",
-        "--no-threads"
+        "--pool=forks"
       ],
       "autoAttachChildProcesses": true,
       "console": "integratedTerminal",
@@ -37,7 +37,7 @@
       "args": [
         "run",
         "${relativeFileDirname}/${fileBasenameNoExtension}",
-        "--no-threads"
+        "--pool=forks"
       ],
       "autoAttachChildProcesses": true,
       "console": "integratedTerminal",

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,26 +1,10 @@
 {
 
   // ESLint
-  "[javascript]": {
+  "[javascript][json][json5][jsonc][typescript][html]": {
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
-  "[json]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  },
-  "[json5]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  },
-  "[jsonc]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  },
-  "[typescript]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  },
-  "[html]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  },
-  "eslint.validate": ["javascript", "typescript", "json", "jsonc", "json5", "yaml", "html"],
-  "eslint.experimental.useFlatConfig": true,
+  "eslint.validate": ["javascript", "typescript", "json", "jsonc", "json5", "yaml", "html", "github-actions-workflow"],
   "eslint.debug": true,
   "editor.formatOnSave": false,
 

diff --git a/docs/README.md b/docs/README.md
@@ -33,4 +33,5 @@ SwissQRBill exposes different classes and functions that can be used to create a
   - [SwissQRBill](./svg/index.md#class-swissqrbill)
   - [SwissQRCode](./svg/index.md#class-swissqrcode)
 - [utils](./utils/utils.md)
+- [errors](./errors/errors.md)
 - [bundle](./bundle/index.md)
diff --git a/docs/bundle/index.md b/docs/bundle/index.md
diff --git a/docs/errors/errors.md b/docs/errors/errors.md
@@ -0,0 +1,167 @@
+
+# Errors
+
+- Classes
+
+  - [ValidationError](#class-validationerror)
+
+    - Property
+      - [code](#property-validationerrorcode)
+
+  - [ValidationErrors](#enum-validationerrors)
+
+<br/>
+
+## Classes
+
+### Class: ValidationError
+
+Defined in: [src/shared/errors.ts](../../src/shared/errors.ts#L2C0)  
+
+#### Description
+
+A [`ValidationError`](#class-validationerror) is thrown when the data provided to swissqrbill is invalid.  
+
+<br/>
+
+#### Property: ValidationError.code
+
+`public`  
+
+Defined in: [src/shared/errors.ts](../../src/shared/errors.ts#L5C2)  
+
+##### Type
+
+`union`  
+
+- `"ACCOUNT_IS_QR_IBAN_BUT_REFERENCE_IS_MISSING"`
+- `"ACCOUNT_IS_QR_IBAN_BUT_REFERENCE_IS_REGULAR"`
+- `"ACCOUNT_IS_REGULAR_IBAN_BUT_REFERENCE_IS_QR"`
+- `"ACCOUNT_LENGTH_IS_INVALID"`
+- `"ADDITIONAL_INFORMATION_LENGTH_IS_INVALID"`
+- `"ADDITIONAL_INFORMATION_TYPE_IS_INVALID"`
+- `"ALTERNATIVE_SCHEME_LENGTH_IS_INVALID"`
+- `"ALTERNATIVE_SCHEME_TYPE_IS_INVALID"`
+- `"AMOUNT_LENGTH_IS_INVALID"`
+- `"AMOUNT_TYPE_IS_INVALID"`
+- `"CREDITOR_ACCOUNT_COUNTRY_IS_INVALID"`
+- `"CREDITOR_ACCOUNT_IS_INVALID"`
+- `"CREDITOR_ACCOUNT_IS_UNDEFINED"`
+- `"CREDITOR_ADDRESS_IS_UNDEFINED"`
+- `"CREDITOR_ADDRESS_LENGTH_IS_INVALID"`
+- `"CREDITOR_ADDRESS_TYPE_IS_INVALID"`
+- `"CREDITOR_BUILDING_NUMBER_LENGTH_IS_INVALID"`
+- `"CREDITOR_BUILDING_NUMBER_TYPE_IS_INVALID"`
+- `"CREDITOR_CITY_IS_UNDEFINED"`
+- `"CREDITOR_CITY_LENGTH_IS_INVALID"`
+- `"CREDITOR_CITY_TYPE_IS_INVALID"`
+- `"CREDITOR_COUNTRY_IS_UNDEFINED"`
+- `"CREDITOR_COUNTRY_LENGTH_IS_INVALID"`
+- `"CREDITOR_COUNTRY_TYPE_IS_INVALID"`
+- `"CREDITOR_IS_UNDEFINED"`
+- `"CREDITOR_NAME_IS_UNDEFINED"`
+- `"CREDITOR_NAME_LENGTH_IS_INVALID"`
+- `"CREDITOR_NAME_TYPE_IS_INVALID"`
+- `"CREDITOR_ZIP_IS_UNDEFINED"`
+- `"CREDITOR_ZIP_LENGTH_IS_INVALID"`
+- `"CREDITOR_ZIP_TYPE_IS_INVALID"`
+- `"CURRENCY_IS_UNDEFINED"`
+- `"CURRENCY_LENGTH_IS_INVALID"`
+- `"CURRENCY_STRING_IS_INVALID"`
+- `"CURRENCY_TYPE_IS_INVALID"`
+- `"DEBTOR_ADDRESS_IS_UNDEFINED"`
+- `"DEBTOR_ADDRESS_LENGTH_IS_INVALID"`
+- `"DEBTOR_ADDRESS_TYPE_IS_INVALID"`
+- `"DEBTOR_BUILDING_NUMBER_LENGTH_IS_INVALID"`
+- `"DEBTOR_BUILDING_NUMBER_TYPE_IS_INVALID"`
+- `"DEBTOR_CITY_IS_UNDEFINED"`
+- `"DEBTOR_CITY_LENGTH_IS_INVALID"`
+- `"DEBTOR_CITY_TYPE_IS_INVALID"`
+- `"DEBTOR_COUNTRY_IS_UNDEFINED"`
+- `"DEBTOR_COUNTRY_LENGTH_IS_INVALID"`
+- `"DEBTOR_COUNTRY_TYPE_IS_INVALID"`
+- `"DEBTOR_IS_UNDEFINED"`
+- `"DEBTOR_NAME_IS_UNDEFINED"`
+- `"DEBTOR_NAME_LENGTH_IS_INVALID"`
+- `"DEBTOR_NAME_TYPE_IS_INVALID"`
+- `"DEBTOR_ZIP_IS_UNDEFINED"`
+- `"DEBTOR_ZIP_LENGTH_IS_INVALID"`
+- `"DEBTOR_ZIP_TYPE_IS_INVALID"`
+- `"MESSAGE_AND_ADDITIONAL_INFORMATION_LENGTH_IS_INVALID"`
+- `"MESSAGE_LENGTH_IS_INVALID"`
+- `"MESSAGE_TYPE_IS_INVALID"`
+- `"QR_REFERENCE_IS_INVALID"`
+- `"QR_REFERENCE_LENGTH_IS_INVALID"`
+- `"REFERENCE_TYPE_IS_INVALID"`
+- `"REGULAR_REFERENCE_LENGTH_IS_INVALID"`
+
+##### Description
+
+A stable error code that can be used to identify the error programmatically.  
+
+<br/>
+
+### Enum: ValidationErrors
+
+Defined in: [src/shared/errors.ts](../../src/shared/errors.ts#L37C0)  
+
+- ACCOUNT_IS_QR_IBAN_BUT_REFERENCE_IS_MISSING `"If there is no reference, a conventional IBAN must be used."`
+- ACCOUNT_IS_QR_IBAN_BUT_REFERENCE_IS_REGULAR `"QR-IBAN requires the use of a QR-Reference."`
+- ACCOUNT_IS_REGULAR_IBAN_BUT_REFERENCE_IS_QR `"QR-Reference requires the use of a QR-IBAN."`
+- ACCOUNT_LENGTH_IS_INVALID `"The provided IBAN number '{iban}' is either too long or too short."`
+- ADDITIONAL_INFORMATION_LENGTH_IS_INVALID `"Additional information must be a maximum of 140 characters."`
+- ADDITIONAL_INFORMATION_TYPE_IS_INVALID `"Additional information must be a string."`
+- ALTERNATIVE_SCHEME_LENGTH_IS_INVALID `"{scheme} must be a maximum of 100 characters."`
+- ALTERNATIVE_SCHEME_TYPE_IS_INVALID `"{scheme} must be a string."`
+- AMOUNT_LENGTH_IS_INVALID `"Amount must be a maximum of 12 digits."`
+- AMOUNT_TYPE_IS_INVALID `"Amount must be a number."`
+- CREDITOR_ACCOUNT_COUNTRY_IS_INVALID `"Only CH and LI IBAN numbers are allowed."`
+- CREDITOR_ACCOUNT_IS_INVALID `"The provided IBAN number '{iban}' is not valid."`
+- CREDITOR_ACCOUNT_IS_UNDEFINED `"Creditor account cannot be undefined."`
+- CREDITOR_ADDRESS_IS_UNDEFINED `"Creditor address cannot be undefined."`
+- CREDITOR_ADDRESS_LENGTH_IS_INVALID `"Creditor address must be a maximum of 70 characters."`
+- CREDITOR_ADDRESS_TYPE_IS_INVALID `"Creditor address TYPE must be a string."`
+- CREDITOR_BUILDING_NUMBER_LENGTH_IS_INVALID `"Creditor buildingNumber must be a maximum of 16 characters."`
+- CREDITOR_BUILDING_NUMBER_TYPE_IS_INVALID `"Creditor buildingNumber must be either a string or a number."`
+- CREDITOR_CITY_IS_UNDEFINED `"Creditor city cannot be undefined."`
+- CREDITOR_CITY_LENGTH_IS_INVALID `"Creditor city must be a maximum of 35 characters."`
+- CREDITOR_CITY_TYPE_IS_INVALID `"Creditor city must be a string."`
+- CREDITOR_COUNTRY_IS_UNDEFINED `"Creditor country cannot be undefined."`
+- CREDITOR_COUNTRY_LENGTH_IS_INVALID `"Creditor country must be 2 characters."`
+- CREDITOR_COUNTRY_TYPE_IS_INVALID `"Creditor country must be a string."`
+- CREDITOR_IS_UNDEFINED `"Creditor cannot be undefined."`
+- CREDITOR_NAME_IS_UNDEFINED `"Creditor name cannot be undefined."`
+- CREDITOR_NAME_LENGTH_IS_INVALID `"Creditor name must be a maximum of 70 characters."`
+- CREDITOR_NAME_TYPE_IS_INVALID `"Creditor name must be a string."`
+- CREDITOR_ZIP_IS_UNDEFINED `"Creditor zip cannot be undefined."`
+- CREDITOR_ZIP_LENGTH_IS_INVALID `"Creditor zip must be a maximum of 16 characters."`
+- CREDITOR_ZIP_TYPE_IS_INVALID `"Creditor zip must be either a string or a number."`
+- CURRENCY_IS_UNDEFINED `"Currency cannot be undefined."`
+- CURRENCY_LENGTH_IS_INVALID `"Currency must be a length of 3 characters."`
+- CURRENCY_STRING_IS_INVALID `"Currency must be either 'CHF' or 'EUR'"`
+- CURRENCY_TYPE_IS_INVALID `"Currency must be a string."`
+- DEBTOR_ADDRESS_IS_UNDEFINED `"Debtor address cannot be undefined."`
+- DEBTOR_ADDRESS_LENGTH_IS_INVALID `"Debtor address must be a maximum of 70 characters."`
+- DEBTOR_ADDRESS_TYPE_IS_INVALID `"Debtor address TYPE must be a string."`
+- DEBTOR_BUILDING_NUMBER_LENGTH_IS_INVALID `"Debtor buildingNumber must be a maximum of 16 characters."`
+- DEBTOR_BUILDING_NUMBER_TYPE_IS_INVALID `"Debtor buildingNumber must be either a string or a number."`
+- DEBTOR_CITY_IS_UNDEFINED `"Debtor city cannot be undefined."`
+- DEBTOR_CITY_LENGTH_IS_INVALID `"Debtor city must be a maximum of 35 characters."`
+- DEBTOR_CITY_TYPE_IS_INVALID `"Debtor city must be a string."`
+- DEBTOR_COUNTRY_IS_UNDEFINED `"Debtor country cannot be undefined."`
+- DEBTOR_COUNTRY_LENGTH_IS_INVALID `"Debtor country must be 2 characters."`
+- DEBTOR_COUNTRY_TYPE_IS_INVALID `"Debtor country must be a string."`
+- DEBTOR_IS_UNDEFINED `"Debtor cannot be undefined."`
+- DEBTOR_NAME_IS_UNDEFINED `"Debtor name cannot be undefined."`
+- DEBTOR_NAME_LENGTH_IS_INVALID `"Debtor name must be a maximum of 70 characters."`
+- DEBTOR_NAME_TYPE_IS_INVALID `"Debtor name must be a string."`
+- DEBTOR_ZIP_IS_UNDEFINED `"Debtor zip cannot be undefined."`
+- DEBTOR_ZIP_LENGTH_IS_INVALID `"Debtor zip must be a maximum of 16 characters."`
+- DEBTOR_ZIP_TYPE_IS_INVALID `"Debtor zip must be either a string or a number."`
+- MESSAGE_AND_ADDITIONAL_INFORMATION_LENGTH_IS_INVALID `"Message and additionalInformation combined must be a maximum of 140 characters."`
+- MESSAGE_LENGTH_IS_INVALID `"Message must be a maximum of 140 characters."`
+- MESSAGE_TYPE_IS_INVALID `"Message must be a string."`
+- QR_REFERENCE_IS_INVALID `"The provided QR-Reference '{reference}' is not valid."`
+- QR_REFERENCE_LENGTH_IS_INVALID `"QR-Reference must be a must be exactly 27 characters."`
+- REFERENCE_TYPE_IS_INVALID `"Reference must be a string."`
+- REGULAR_REFERENCE_LENGTH_IS_INVALID `"Creditor reference must be a maximum of 25 characters."`
diff --git a/docs/importing.md b/docs/importing.md
@@ -88,9 +88,9 @@ The bundle exposes all exports in the global variable `SwissQRBill`.
 
 ```ts
 const SwissQRBill = {
+  errors,
   PDF,
   SVG,
-  errors,
   table,
   types,
   utils

diff --git a/docs/pdf/index.md b/docs/pdf/index.md
@@ -239,7 +239,7 @@ Attaches the Swiss QR Code to a PDF document.
 
 ### Class: Table
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L158C0)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L157C0)  
 
 #### Description
 
@@ -289,7 +289,7 @@ pdf.end();
 
 #### Constructor: new Table(data)
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L166C2)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L165C2)  
 
 ##### Parameter
 
@@ -309,7 +309,7 @@ Creates a new Table instance.
 
 `public`  
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L191C2)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L190C2)  
 
 ##### Parameters
 
@@ -334,7 +334,7 @@ every row that no longer fits on a page.
 
 ### Type alias: PDFBorderColor
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L91C0)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L90C0)  
 
 #### Type
 
@@ -361,7 +361,7 @@ Can be used to set the color of the border of a table, row or column.
 
 ### Type alias: PDFBorderWidth
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L97C0)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L96C0)  
 
 #### Type
 
@@ -388,7 +388,7 @@ Can be used to set the width of the border of a table, row or column.
 
 ### Type alias: PDFPadding
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L103C0)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L102C0)  
 
 #### Type
 
@@ -437,7 +437,7 @@ Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L1C0)
 
 ### Interface: PDFRow
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L30C0)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L29C0)  
 
 - **columns** [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Table columns.
 
@@ -462,7 +462,7 @@ Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L30C0)
 
 ### Interface: PDFColumn
 
-Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L63C0)  
+Defined in: [src/pdf/table.ts](../../src/pdf/table.ts#L62C0)  
 
 - **text** [`boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) | [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) | [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) Cell text.
 - **align** `"center"` | `"left"` | `"right"` Horizontal alignment of the text inside the cell. `optional`

diff --git a/eslint.config.js b/eslint.config.js
@@ -1,9 +1,8 @@
+import sharedRules from "@schoero/configs/eslint";
 import eslintPluginTypeScript from "@typescript-eslint/eslint-plugin";
 import eslintParserTypeScript from "@typescript-eslint/parser";
 
-import sharedRules from "@schoero/configs/eslint";
-
-/** @type { import("eslint").Linter.FlatConfig[] } */
+/** @type { import("eslint").Linter.Config[] } */
 export default [
   ...sharedRules,
 

diff --git a/examples/browser-bundling-with-webpack/src/pdf.js b/examples/browser-bundling-with-webpack/src/pdf.js
@@ -1,8 +1,9 @@
-import BlobStream from "blob-stream";
 import fs from "fs";
+
+import BlobStream from "blob-stream";
 import PDFDocument from "pdfkit";
-import Helvetica from "pdfkit/js/data/Helvetica.afm";
 import HelveticaBold from "pdfkit/js/data/Helvetica-Bold.afm";
+import Helvetica from "pdfkit/js/data/Helvetica.afm";
 import { SwissQRBill } from "swissqrbill/pdf";
 
 

diff --git a/examples/how-to-create-a-complete-qr-bill/src/index.js b/examples/how-to-create-a-complete-qr-bill/src/index.js
@@ -1,4 +1,5 @@
 import { createWriteStream } from "fs";
+
 import PDFDocument from "pdfkit";
 import { SwissQRBill, Table } from "swissqrbill/pdf";
 import { mm2pt } from "swissqrbill/utils";

diff --git a/examples/node-cjs-javascript/src/pdf.js b/examples/node-cjs-javascript/src/pdf.js
@@ -1,4 +1,5 @@
 const { createWriteStream } = require("fs");
+
 const PDFDocument = require("pdfkit");
 const { SwissQRBill } = require("swissqrbill/pdf");
 

diff --git a/examples/node-cjs-javascript/src/svg.js b/examples/node-cjs-javascript/src/svg.js
@@ -1,4 +1,5 @@
 const { writeFileSync } = require("fs");
+
 const { SwissQRBill } = require("swissqrbill/svg");
 
 const data = require("./data.js");

diff --git a/examples/node-esm-javascript/src/pdf.js b/examples/node-esm-javascript/src/pdf.js
@@ -1,4 +1,5 @@
 import { createWriteStream } from "fs";
+
 import PDFDocument from "pdfkit";
 import { SwissQRBill } from "swissqrbill/pdf";
 

diff --git a/examples/node-esm-javascript/src/svg.js b/examples/node-esm-javascript/src/svg.js
@@ -1,4 +1,5 @@
 import { writeFileSync } from "fs";
+
 import { SwissQRBill } from "swissqrbill/svg";
 
 import { data } from "./data.js";
-Original file line number
+Diff line change
@@ Expand Up @@
     ```ts
     const SwissQRBill = {
+      errors,
       PDF,
       SVG,
-      errors,
       table,
       types,
       utils
@@ Expand Down @@