bysquare 2.5.0 → 2.7.0

package/README.md

@@ -1,8 +1,9 @@
 # bysquare
 
-![version][version] ![build][build]
+![version][version]
+![build][build]
 
-Simple JavaScript library to generate and parse "PAY by square" string.
+Simple JavaScript library to encode and decode "PAY by square" string.
 
 **What is `PAY by square`?**
 
@@ -18,77 +19,84 @@ transformed into images depends on how you implement it. See
 
 ## Install
 
+**NOTE**: This package is native [ESM][mozzila-esm] and no longer provides a
+CommonJS export. If your project uses CommonJS, you will have to convert to ESM
+or use the dynamic [`import()`][mozzila-import] function.
+
 **npm registry**
 
 ```sh
 npm install bysquare
 ```
 
-**CLI**
-
-```sh
-npm install --global bysquare
-```
-
 **Browser**
 
 ```html
 <script type="module">
-	import { generate, parse } from "https://esm.sh/bysquare@2.4.0/";
+	import { encode, decode } from "https://esm.sh/bysquare@2.4.0/";
 </script>
 ```
 
 **Deno** `v1.28+`, just import `npm:bysquare` `v2.1.0+`
 
 ```ts
-import { generate, parse } from "npm:bysquare@2.1.0"
+import { encode, decode } from "npm:bysquare@2.1.0";
+```
+
+**CLI** (Node.JS `v18`+)
+
+```sh
+npm install --global bysquare
 ```
 
-## How it works
+# How it works
 
-### Encoding sequence
+## Encoding sequence
 
 ![logic](./docs/uml/logic.svg)
 
-## API
+# API
 
 ```ts
-generate(model: DataModel, options?: Options): string
-parse(qr: string): DataModel
+encode(model: DataModel, options?: Options): string
+decode(qr: string): DataModel
 detect(qr: string): Boolean
 ```
 
-## Usage
+# Usage
 
-Generate
+## Encode
 
 ```ts
-import { CurrencyCode, DataModel, generate, PaymentOptions } from "bysquare"
+import { CurrencyCode, DataModel, encode, PaymentOptions } from "bysquare";
 
-// long string ready to be encoded to QR
-const qrString = generate({
+// string ready to be encoded to QR
+const qrString = encode({
 	invoiceId: "random-id",
 	payments: [
 		{
 			type: PaymentOptions.PaymentOrder,
 			amount: 100.0,
 			bankAccounts: [
-				{ iban: "SK9611000000002918599669" }
+				{
+					iban: "SK9611000000002918599669",
+				},
 			],
 			currencyCode: CurrencyCode.EUR,
-			variableSymbol: "123"
-		}
-	]
-})
+			variableSymbol: "123",
+		},
+	],
+});
 ```
 
-Parse
+## Decode
 
 ```ts
-import { parse } from "bysquare"
+import { decode } from "bysquare";
 
-const model =
-	parse("0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000")
+const model = decode(
+	"0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000"
+);
 
 // {
 // 	invoiceId: "random-id",
@@ -107,72 +115,36 @@ const model =
 //
 ```
 
-You can use json file with valid model to generate qr-string.
+# CLI
+
+## Encode
+
+Encode JSON data from a file and print the corresponding QR code. The file
+argument should be a path to a JSON file.
 
 ```sh
-# example.json
-# {
-# 	"invoiceId": "random-id",
-# 	"payments": [
-# 		{
-# 			"type": 1,
-# 			"amount": 100.0,
-# 			"bankAccounts": [{ "iban": "SK9611000000002918599669" }],
-# 			"currencyCode": "EUR",
-# 			"variableSymbol": "123"
-# 		}
-# 	]
-# }
-
-$ npx bysquare ./example.json
-$ 0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000
+npx bysquare --encode <file>
 ```
 
-You can also use stdin.
+## Decode
+
+Decode the specified QR code string and print the corresponding JSON data. The
+qrstring argument should be a valid QR code string.
 
 ```sh
-$ npx bysquare <<< '{
-    "invoiceId": "random-id",
-    "payments": [
-        {
-            "type": 1,
-            "amount": 100.0,
-            "bankAccounts": [{ "iban": "SK9611000000002918599669" }],
-            "currencyCode": "EUR",
-            "variableSymbol": "123"
-        }
-    ]
-}'
-
-$ 0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000
+npx bysquare --decode <qrstring>
 ```
 
 ## Related
 
-- <https://bysquare.com/>
-- <https://devel.cz/otazka/qr-kod-pay-by-square>
-- <https://github.com/matusf/pay-by-square>
-- <https://www.bsqr.co/schema/>
-- <https://www.sbaonline.sk/wp-content/uploads/2020/03/pay-by-square-specifications-1_1_0.pdf>
-- <https://www.vutbr.cz/studenti/zav-prace/detail/78439>
-
-<!--
-Versioning
-----------
-
-https://github.com/dherges/npm-version-git-flow
-
-- Stash unfinished work
-- Run `npm test`
-- Run `npm version <patch, minor, major>`
-- Commit and push
-- 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`
--->
+-   <https://bysquare.com/>
+-   <https://devel.cz/otazka/qr-kod-pay-by-square>
+-   <https://github.com/matusf/pay-by-square>
+-   <https://www.bsqr.co/schema/>
+-   <https://www.sbaonline.sk/wp-content/uploads/2020/03/pay-by-square-specifications-1_1_0.pdf>
+-   <https://www.vutbr.cz/studenti/zav-prace/detail/78439>
 
 [build]: https://img.shields.io/github/actions/workflow/status/xseman/bysquare/tests.yml
 [version]: https://img.shields.io/npm/v/bysquare
+[mozzila-esm]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+[mozzila-import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import

package/dist/cli.js

@@ -1,83 +1,81 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { createInterface } from "node:readline";
-import { generate } from "./generate.js";
-if /** bysquare "file" */ (process.stdin.isTTY) {
-    handleInput(process.argv[2]);
-} /** bysquare <<< "data" */
-else {
-    ;
-    (async () => {
-        const stdin = await handleStdin();
-        console.log(fromJsonString(stdin));
-        process.exit(0);
-    })();
-}
-function handleInput(input) {
-    if (input === undefined || input === "-h" || input === "--help") {
-        console.log(help());
-        process.exit(0);
+import { parseArgs } from "node:util";
+import { encode } from "./encode.js";
+import { decode } from "./decode.js";
+const args = parseArgs({
+    allowPositionals: true,
+    options: {
+        decode: {
+            type: "string",
+            short: "d"
+        },
+        encode: {
+            type: "string",
+            short: "e"
+        },
+        help: {
+            type: "boolean",
+            short: "h"
+        }
     }
-    if (existsSync(process.argv[2])) {
-        const file = readFileSync(process.argv[2], "utf8");
-        console.log(fromJsonString(file));
+});
+if (process.stdin.isTTY) {
+    /** json file */
+    if (args.values.encode) {
+        const file = args.values.encode;
+        if (existsSync(file)) {
+            const data = readFileSync(file, "utf8");
+            console.log(encode(JSON.parse(data)));
+        }
+        else {
+            console.error(`File ${file} doesn't exists`);
+            process.exit(1);
+        }
     }
-    else {
-        console.error(`File ${process.argv[2]} doesn't exists`);
-        process.exit(1);
+    /** input string */
+    if (args.values.decode) {
+        const qrstring = args.values.decode;
+        console.log(JSON.stringify(decode(qrstring), null, 4));
+    }
+    if (args.values.help || Object.keys(args.values).length === 0) {
+        console.log([
+            "NAME",
+            "	bysquare - Simple Node.js library to generate and parse PAY bysquare standard",
+            "",
+            "SYNOPSIS",
+            "	bysquare [OPTIONS]",
+            "",
+            "DESCRIPTION",
+            "	bysquare is a command-line tool that provides a simple Node.js library to generate ",
+            "	and parse PAY bysquare standard. It offers functionality to encode JSON data into a ",
+            "	corresponding QR code and decode a QR code string to obtain the associated JSON data.",
+            "",
+            "OPTIONS",
+            "	-d, --decode <qrstring>",
+            "		Decode the specified QR code string and print the corresponding JSON data.",
+            "		The qrstring argument should be a valid QR code string.",
+            "",
+            "	-e, --encode <file>",
+            "		Encode JSON data from a file and print the corresponding QR code.",
+            "		The file argument should be a path to a JSON file.",
+            "",
+            "	-h, --help",
+            "		Display the help message and exit.",
+            "",
+            "USAGE",
+            "	Encoding JSON data from a file",
+            "",
+            `	${process.argv[1]} --encode <file>`,
+            "	The <file> argument should be the path to the JSON file you want to encode.",
+            "	The tool will read the file, generate a QR code representing the JSON data",
+            "",
+            "	Decoding a QR code string",
+            "",
+            `	${process.argv[1]} --decode <qrstring>`,
+            "	Replace qrstring with the QR code string you want to decode.",
+            "	The program will parse the QR code string and print the resulting JSON data.",
+            ""
+        ].join("\n"));
     }
-}
-function fromJsonString(stdin) {
-    const data = JSON.parse(stdin);
-    return generate(data);
-}
-async function handleStdin() {
-    const readline = createInterface({
-        input: process.stdin,
-        output: process.stdout,
-        terminal: false
-    });
-    const lines = [];
-    return new Promise((resolve, reject) => {
-        readline
-            .on("line", (line) => {
-            lines.push(line);
-        })
-            .on("close", () => {
-            resolve(lines.join(""));
-        })
-            .on("SIGINT", /* CTRL+C */ reject);
-    });
-}
-function help() {
-    const exe = path.basename(process.argv[1]);
-    return [
-        "Simple Node.js library to generate 'PAY by square' QR string.",
-        "",
-        "Usage:",
-        `   ${exe} file`,
-        "",
-        "File:",
-        "   Valid json file",
-        "",
-        "Flags:",
-        "   -h, --help    display this help and exit",
-        "",
-        "If <file> is omitted, reads from stdin.",
-        "",
-        "Examples:",
-        "	bysquare <<< \"{",
-        "		\"invoiceId\": \"random-id\",",
-        "		\"payments\": [",
-        "			{",
-        "				\"type\": 1,",
-        "				\"amount\": 100.0,",
-        "				\"bankAccounts\": [{ \"iban\": \"SK9611000000002918599669\" }],",
-        "				\"currencyCode\": \"EUR\",",
-        "				\"variableSymbol\": \"123\"",
-        "			}",
-        "		]",
-        "	}\""
-    ].join("\n");
 }

package/dist/{parse.d.ts → decode.d.ts}

@@ -10,12 +10,15 @@ export declare class DecodeError extends Error {
     name: string;
     constructor(cause: Error, msg?: string);
 }
+/** @deprecated */
+export declare const parse: typeof decode;
 /**
  * Decoding client data from QR Code 2005 symbol
  *
  * @see 3.16.
+ *
  */
-export declare function parse(qr: string): DataModel;
+export declare function decode(qr: string): DataModel;
 /**
  * Detect if qr string contains bysquare header.
  *

package/dist/{parse.js → decode.js}

@@ -155,12 +155,15 @@ export class DecodeError extends Error {
         this.name = "DecodeError";
     }
 }
+/** @deprecated */
+export const parse = decode;
 /**
  * Decoding client data from QR Code 2005 symbol
  *
  * @see 3.16.
+ *
  */
-export function parse(qr) {
+export function decode(qr) {
     try {
         var bytes = base32hex.parse(qr, {
             loose: true

package/dist/{generate.d.ts → encode.d.ts}

@@ -49,8 +49,10 @@ type Options = {
      */
     deburr: boolean;
 };
+/** @deprecated */
+export declare const generate: typeof encode;
 /**
  * Generate QR string ready for encoding into text QR code
  */
-export declare function generate(model: DataModel, options?: Options): string;
+export declare function encode(model: DataModel, options?: Options): string;
 export {};

package/dist/{generate.js → encode.js}

@@ -137,10 +137,12 @@ function removeDiacritics(model) {
         }
     }
 }
+/** @deprecated */
+export const generate = encode;
 /**
  * Generate QR string ready for encoding into text QR code
  */
-export function generate(model, options = { deburr: true }) {
+export function encode(model, options = { deburr: true }) {
     if (options.deburr) {
         removeDiacritics(model);
     }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { generate } from "./generate.js";
-export { detect, parse } from "./parse.js";
+export { generate } from "./encode.js";
+export { detect, parse } from "./decode.js";
 export * from "./types.js";

package/dist/index.js

@@ -1,3 +1,3 @@
-export { generate } from "./generate.js";
-export { detect, parse } from "./parse.js";
+export { generate } from "./encode.js";
+export { detect, parse } from "./decode.js";
 export * from "./types.js";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "bysquare",
 	"description": "It's a national standard for payment QR codes adopted by Slovak Banking Association (SBA)",
-	"version": "2.5.0",
+	"version": "2.7.0",
 	"license": "Apache-2.0",
 	"funding": "https://github.com/sponsors/xseman",
 	"homepage": "https://github.com/xseman/bysquare#readme",
@@ -21,11 +21,10 @@
 		"build": "tsc --build",
 		"format": "dprint fmt ./src/**/*",
 		"typecheck": "tsc --noEmit",
-		"test": "xv --loader=tsx ./src",
-		"test:watch": "xv --loader=tsx --watch ./src",
-		"cli:local": "npm run build && npm link bysquare",
 		"version": "git checkout develop && npm test",
-		"postversion": "echo 'Now run npm run build && npm publish'"
+		"postversion": "echo 'Now run npm run build && npm publish'",
+		"test": "node --test --loader tsx --no-warnings src/*.test.ts",
+		"test:watch": "node --test --watch --loader tsx --no-warnings src/*.test.ts"
 	},
 	"dependencies": {
 		"crc-32": "~1.2.0",
@@ -36,15 +35,13 @@
 	"devDependencies": {
 		"@types/lodash.deburr": "~4.1.0",
 		"@types/node": ">=16.14",
-		"dprint": "~0.36.0",
+		"dprint": "~0.41.0",
 		"tsx": "~3.12.0",
-		"typescript": "~5.0.0",
-		"xv": "~2.1.0"
+		"typescript": "~5.0.0"
 	},
 	"type": "module",
 	"bin": "./dist/cli.js",
 	"types": "./dist/index.d.ts",
-	"main": "./dist/index.js",
 	"module": "./dist/index.js",
 	"exports": {
 		".": {
@@ -56,7 +53,7 @@
 		"!dist/*.test.*"
 	],
 	"engines": {
-		"node": ">=14.13.1 || >=16.0.0",
-		"npm": ">=7.0"
+		"node": ">=16",
+		"npm": ">=7"
 	}
 }