bysquare 2.0.1 → 2.2.0

package/README.md

@@ -2,18 +2,19 @@
 
 ![version][version] ![build][build]
 
-Simple `Node.js` library to generate "PAY by square" `QR` string.
+Simple JavaScript library to generate and parse "PAY by square" string.
 
 **What is `PAY by square`?**
 
-It's a national standard for payment QR codes adopted by Slovak Banking
-Association in 2013. It is part of a large number of invoices, reminders and
-other payment regulations.
+It's a national standard for QR code payments that was adopted by the Slovak
+Banking Association in 2013. It is incorporated into a variety of invoices,
+reminders and other payment regulations.
 
 **Can I generate an image?**
 
-This library is un-opinionated. Image generation from qr-code string depends on
-your implementation. See [examples](examples).
+This library doesn't have a specific opinion and how the QR code string is
+transformed into images depends on how you implement it. See
+[examples](examples).
 
 ## Install
 
@@ -31,6 +32,9 @@ npm install xseman/bysquare#master
 
 # latest unreleased changes
 npm install xseman/bysquare#develop
+
+# specific tag version, e.g. v2.1.0
+npm install xseman/bysquare#v2.1.0
 ```
 
 **CLI**
@@ -39,67 +43,95 @@ npm install xseman/bysquare#develop
 npm install --global bysquare
 ```
 
+**Deno** `v1.28+`, just import `npm:bysquare` `v2.1.0+`
+
+```
+import { generate, parse } from "npm:bysquare@2.1.0"
+```
+
 ## How it works
 
 ### Encoding sequence
 
-![logic](./docs/uml/logic.svg)
+![logic](./doc/uml/logic.svg)
 
 ## API
 
 ```ts
-generate(model: DataModel, options?: Options): Promise<string>
-parse(qr: string): Promise<DataModel>
+generate(model: DataModel, options?: Options): string
+parse(qr: string): DataModel
 detect(qr: string): Boolean
 ```
 
-**generate(model: DataModel, options?: Options): Promise\<string>**
+## Usage
+
+Generate
 
 ```ts
-import { generate, DataModel, parse, PaymentOptions } from "bysquare"
+import { DataModel, generate, PaymentOptions } from "bysquare"
 
-const model: DataModel = {
+// long string ready to be encoded to QR
+const qrString = generate({
 	invoiceId: "random-id",
 	payments: [
 		{
 			type: PaymentOptions.PaymentOrder,
 			amount: 100.0,
 			bankAccounts: [
-				{ iban: "SK9611000000002918599669" },
+				{ iban: "SK9611000000002918599669" }
 			],
 			currencyCode: "EUR",
-			variableSymbol: "123",
+			variableSymbol: "123"
 		}
 	]
-}
-
-generate(model).then((qr: string) => {
-	// your logic...
 })
 ```
 
-**parse(qr: string): Promise\<DataModel>**
+Parse
 
 ```ts
-import { parse, DataModel } from "bysquare"
-
-const qr = "0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0"
-parse(qr).then((model: DataModel) => {
-	// your logic...
-});
+import { parse } from "bysquare"
+
+const model =
+	parse("0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000")
+
+// {
+// 	invoiceId: "random-id",
+// 	payments: [
+// 		{
+// 			type: 1,
+// 			amount: 100.0,
+// 			bankAccounts: [
+// 				{ iban: "SK9611000000002918599669" },
+// 			],
+// 			currencyCode: "EUR",
+// 			variableSymbol: "123",
+// 		}
+// 	]
+// }
+//
+const qr =
+	"0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000"
+
+const model = parse(qr)
+/**
+ *  {
+ * 	invoiceId: "random-id",
+ * 	payments: [
+ * 		{
+ * 			type: PaymentOptions.PaymentOrder,
+ * 			amount: 100.0,
+ * 			bankAccounts: [
+ * 				{ iban: "SK9611000000002918599669" },
+ * 			],
+ * 			currencyCode: "EUR",
+ * 			variableSymbol: "123",
+ * 		}
+ * 	]
+ * }
+ */
 ```
 
-**detect(qr: string): Boolean**
-
-```ts
-import { detect } from "bysquare"
-
-const qr = "0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0"
-const isBysquare = detect(qr)
-```
-
-## CLI
-
 You can use json file with valid model to generate qr-string.
 
 ```sh
@@ -110,9 +142,7 @@ You can use json file with valid model to generate qr-string.
 # 		{
 # 			"type": 1,
 # 			"amount": 100.0,
-# 			"bankAccounts": [
-# 				{ "iban": "SK9611000000002918599669" }
-# 			],
+# 			"bankAccounts": [{ "iban": "SK9611000000002918599669" }],
 # 			"currencyCode": "EUR",
 # 			"variableSymbol": "123"
 # 		}
@@ -120,27 +150,26 @@ You can use json file with valid model to generate qr-string.
 # }
 
 $ npx bysquare ./example.json
-$ 0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0
+$ 0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000
 ```
 
 You can also use stdin.
 
 ```sh
-$ bysquare <<< '{
-	"invoiceId": "random-id",
-	"payments": [
-		{
-			"type": 1,
-			"amount": 100.0,
-			"bankAccounts": [
-				{ "iban": "SK9611000000002918599669" }
-			],
-			"currencyCode": "EUR",
-			"variableSymbol": "123"
-		}
-	]
+$ npx bysquare <<< '{
+    "invoiceId": "random-id",
+    "payments": [
+        {
+            "type": 1,
+            "amount": 100.0,
+            "bankAccounts": [{ "iban": "SK9611000000002918599669" }],
+            "currencyCode": "EUR",
+            "variableSymbol": "123"
+        }
+    ]
 }'
-$ 0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0
+
+$ 0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000
 ```
 
 ## Related
@@ -162,9 +191,9 @@ https://github.com/dherges/npm-version-git-flow
 - Run `npm test`
 - Run `npm version <patch, minor, major>`
 - Commit and push
-- Run `npm version`
 - Follow git-flow instructions
 - Checkout to master
+- Build artefacts
 - Push commits and tag, git push && git push --tags
 - Validate with `npm publish --dry-run`
 - Publish to npm, `npm publish`

package/lib/cjs/cli.js

@@ -8,52 +8,34 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const node_readline_1 = require("node:readline");
 const generate_js_1 = require("./generate.js");
-if (process.stdin.isTTY) {
-    // bysquare "file"
+if /** bysquare "file" */ (process.stdin.isTTY) {
     handleInput(process.argv[2]);
-}
+} /** bysquare <<< "data" */
 else {
-    // echo "data" | bysquare
     ;
     (async () => {
         const stdin = await handleStdin();
-        const qr = await fromJsonString(stdin).catch((e) => {
-            console.error(e);
-            process.exit(1);
-        });
-        console.log(qr);
+        console.log(fromJsonString(stdin));
         process.exit(0);
     })();
 }
-async function handleInput(input) {
+function handleInput(input) {
     if (input === undefined || input === "-h" || input === "--help") {
         console.log(help());
         process.exit(0);
     }
     if ((0, node_fs_1.existsSync)(process.argv[2])) {
         const file = (0, node_fs_1.readFileSync)(process.argv[2], "utf8");
-        const qr = await fromJsonString(file).catch((e) => {
-            console.error(e);
-            process.exit(1);
-        });
-        console.log(qr);
+        console.log(fromJsonString(file));
     }
     else {
         console.error(`File ${process.argv[2]} doesn't exists`);
         process.exit(1);
     }
 }
-async function fromJsonString(stdin) {
-    return new Promise((resolve, reject) => {
-        try {
-            const data = JSON.parse(stdin);
-            const qrString = (0, generate_js_1.generate)(data);
-            resolve(qrString);
-        }
-        catch (e) {
-            reject(e);
-        }
-    });
+function fromJsonString(stdin) {
+    const data = JSON.parse(stdin);
+    return (0, generate_js_1.generate)(data);
 }
 async function handleStdin() {
     const readline = (0, node_readline_1.createInterface)({
@@ -90,18 +72,17 @@ function help() {
         "If <file> is omitted, reads from stdin.",
         "",
         "Examples:",
-        "   bysquare ./example.json",
-        "",
-        "   echo ",
-        "       {",
-        '           "IBAN": "SK9611000000002918599669"',
-        '           "Amount": 100.0',
-        '           "CurrencyCode": "EUR"',
-        '           "VariableSymbol": "123"',
-        '           "Payments": 1',
-        '           "PaymentOptions": 1',
-        '           "BankAccounts": 1',
-        "       }'",
-        "   | bysquare"
+        "	bysquare <<< \"{",
+        "		\"invoiceId\": \"random-id\",",
+        "		\"payments\": [",
+        "			{",
+        "				\"type\": 1,",
+        "				\"amount\": 100.0,",
+        "				\"bankAccounts\": [{ \"iban\": \"SK9611000000002918599669\" }],",
+        "				\"currencyCode\": \"EUR\",",
+        "				\"variableSymbol\": \"123\"",
+        "			}",
+        "		]",
+        "	}\""
     ].join("\n");
 }

package/lib/cjs/generate.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import { DataModel } from "./types.js";
 /**
  * Returns a 2 byte buffer that represents the header of the bysquare
@@ -13,36 +12,45 @@ import { DataModel } from "./types.js";
  * | Reserved     | 4              | 0-15            | bits reserved for future needs
  * ```
  *
- * @see 3.5. by square header
+ * @see 3.5.
  */
-export declare function bysquareHeader(header?: [
+export declare function headerBysquare(
+/** dprint-ignore */
+header?: [
     bySquareType: number,
     version: number,
     documentType: number,
     reserved: number
-]): Buffer;
+]): Uint8Array;
 /**
- * @see 3.10 Appending CRC32 checksum
+ * Creates a one-byte array that represents the length of compressed data in
+ * combination with CRC32 in bytes.
  */
-export declare function checksum(intermediate: string): Buffer;
+export declare function headerDataLength(length: number): Uint8Array;
 /**
  * Transfer object to a tabbed string and append a CRC32 checksum
  *
- * @see 3.10. Appending CRC32 checksum
+ * @see 3.10.
  */
-export declare function prepareCompression(model: DataModel): Buffer;
+export declare function addChecksum(serialized: string): Uint8Array;
 /**
  * Transform data to ordered tab-separated intermediate representation ready for
  * encoding
  *
- * @see Table 15 PAY by square sequence data model
+ * @see Table 15.
  */
-export declare function toIntermediate(data: DataModel): string;
+export declare function serialize(data: DataModel): string;
 type Options = {
+    /**
+     * Many banking apps do not support diacritics, which results in errors when
+     * serializing data from QR codes.
+     *
+     * @default true
+     */
     deburr: boolean;
 };
 /**
  * Generate QR string ready for encoding into text QR code
  */
-export declare function generate(model: DataModel, options?: Options): Promise<string>;
+export declare function generate(model: DataModel, options?: Options): string;
 export {};