Skip to content

Commit

Permalink
Revise Readme and Changelog files
Browse files Browse the repository at this point in the history
  • Loading branch information
@baumerdev
baumerdev committed Aug 13, 2023
1 parent 799dcc6 commit d30a8c6
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 41 deletions.
16 changes: 8 additions & 8 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@

## 2023-08-11 [v1.2301.5]

* Internally remove TypeScript enums for better compatibility with Angular ; see [#15](https://github.com/baumerdev/ibantools-germany/issues/15) and [#16](https://github.com/baumerdev/ibantools-germany/pull/16/)
* Internally removed TypeScript enums to improve compatibility with Angular ; see [#15](https://github.com/baumerdev/ibantools-germany/issues/15) and [#16](https://github.com/baumerdev/ibantools-germany/pull/16/)

## 2023-08-04 [v1.2301.4]

* Fixed method A4 ; [#14](https://github.com/baumerdev/ibantools-germany/issues/14)

## 2023-07-23 [v1.2301.3]

* Upgrade dependencies, including word-wrap and tough-cookie, see CVE-2023-26136
* Upgraded dependencies, including word-wrap and tough-cookie (CVE-2023-26136)

## 2023-05-23 [v1.2301.2]

* The Bundesbank informed that their data was faulty. Changes were made accordingly.
* The Bundesbank informed that their data was inaccurate. Changes were made accordingly.

## 2023-05-14 [v1.2301.1]

Expand All @@ -26,20 +26,20 @@

## 2023-05-13 [v1.2300.1]

* Upgrade dependencies, including yaml, see CVE-2023-2251
* Upgraded dependencies, including yaml (CVE-2023-2251)

## 2023-02-14 [v1.2300.0]

* Additionally includes data valid from 2023-03-06, removes data valid before 2022-12-05

## 2023-02-14 [v1.2201.2]

* Upgrade dependencies, including http-cache-semantics, see CVE-2022-25881 and cacheable-request, see GHSA-8x6c-cv3v-vp6g
* Upgraded dependencies, including http-cache-semantics (CVE-2022-25881) and cacheable-request (GHSA-8x6c-cv3v-vp6g)

## 2023-01-17 [v1.2201.1]

* Fix failing test for current/next BLZs
* Upgrade dependencies, including json5, see CVE-2022-46175
* Fixed failing test for current/next BLZs
* Upgraded dependencies, including (CVE-2022-46175)

## 2022-11-13 [v1.2201.0]

Expand All @@ -50,7 +50,7 @@
* Fixed methods C0 ; [#7](https://github.com/baumerdev/ibantools-germany/pull/7)
* Fixed methods 85 ; [#9](https://github.com/baumerdev/ibantools-germany/pull/9)
* Fixed methods 53 ; [#11](https://github.com/baumerdev/ibantools-germany/pull/11)
* Updated method 61: Inaccurate method definition in Bundesbank document may have led to false negatives in certain cases ; [#13](https://github.com/baumerdev/ibantools-germany/pull/13)
* Updated method 61: An inaccurate method definition in the Bundesbank document may have resulted in false negatives in specific cases ; [#13](https://github.com/baumerdev/ibantools-germany/pull/13)

## 2022-10-30 [v1.2200.2]

Expand Down
70 changes: 37 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@
[![Coverage Status](https://coveralls.io/repos/github/baumerdev/ibantools-germany/badge.svg?branch=main)](https://coveralls.io/github/baumerdev/ibantools-germany?branch=main)

This TypeScript/JavaScript library validates IBAN and German bank account
numbers. It can be used as an enhancement of IBAN validators like [IBANTools](https://simplify.github.io/ibantools/).
numbers. It can be used standalone or as an enhancement of IBAN validators, like
[IBANTools](https://simplify.github.io/ibantools/).

If you need German bank data in your project e.g. to auto-fill forms when a
user enters an IBAN, take a look the side project [BankData-Germany](https://baumerdev.github.io/bankdata-germany/).
If you need German bank data in your project, e.g., to auto-fill forms when a
user enters an IBAN, take a look at the side project [BankData-Germany](https://baumerdev.github.io/bankdata-germany/).

> _Version 1.2301.* includes the data from 2023-03-06 until 2023-06-04 and from 2023-06-05 until 2023-09-03 and validation will be performed according to the data that is valid at your system time (data will change at 2023-06-05 midnight CET)._
> _Version 1.2301.* includes data from 2023-03-06 to 2023-06-04, as well as from 2023-06-05 to 2023-09-03. Validation will be based on the data that is valid according to your system time (data changes at midnight CET on 2023-06-05)._
* [Installation](#installation)
* [Usage](#usage)
Expand All @@ -20,8 +21,8 @@ user enters an IBAN, take a look the side project [BankData-Germany](https://ba

### Package Manager

Add it to your project with your package manager like npm or yarn. You should
explicitly install the latest version since the bank data may change multiple
Add it to your project using a package manager like npm or yarn. You should
explicitly install the latest version, as the bank data may change multiple
times a year.

```sh
Expand All @@ -32,23 +33,24 @@ $ yarn add ibantools-germany@latest

### Browser / CDN

If you just want the functions in your browser, you can include the following
pre-build file.
If you only want the functions in your browser, you can include the following
pre-built file.

```html
<script src="https://cdn.jsdelivr.net/npm/ibantools-germany/dist/build/browser.js"></script>
```

## Usage

The npm package contains the code for ESM and CJS, so instead of `import`, as
shown in the usage examples below, you can use `require` as well.
The npm package contains the code for both ESM and CJS. Therefore, in addition
to using `import` as shown in the usage examples below, you can also utilize
`require`.

### Validation

You can validate the bank account number and BLZ (Bankleitzahl = bank sort
code), a BBAN or an IBAN. You can optionally restrict IBAN validation
to only allow German IBAN.
code), a BBAN, or an IBAN. Additionally, you have the option to restrict IBAN
validation to only allow German IBANs.

```javascript
import { isValidAccountNumberBLZ, isValidBBAN } from "ibantools-germany"
Expand Down Expand Up @@ -77,8 +79,8 @@ generateIBAN("foo", "bar"); // null

### Browser / CDN

If you use the pre-build version, an object `ibantoolsGermany` is globally
defined on `window` containing the functions.
When using the pre-built version, the `ibantoolsGermany` object is globally
defined on the `window`, containing the functions.

```javascript
ibantoolsGermany.generateBBAN("9290701", "10220500");
Expand All @@ -90,35 +92,37 @@ ibantoolsGermany.isValidIBAN("DE23102205000009290701");

## Data Source

Sadly there is no algorithm to verify every German bank account number or BBAN.
Each bank has its own method(s) which can change from time to time. Therefore
Unfortunately, there isn't a single algorithm to verify all German bank account
numbers or BBANs, as each bank employs its own method(s) which can change
periodically.To address this,
[Deutsche Bundesbank](https://www.bundesbank.de/en/tasks/payment-systems/services/bank-sort-codes/download-bank-sort-codes-626218)
publishes updated data every quarter.

Updates can contain technical changes (modifications in check digit methods)
and content changes (BLZ, bank names, etc). It is also possible that there
are updates that do not contain any relevant changes for this library at
all.
These updates can encompass both technical changes, such as modifications in
check digit methods, as well as content changes like alterations to BLZ, bank
names, and more. Some updates might not contain any relevant changes for this
library at all.

## Package Version

The version numbers are based on [Semantic Versioning](https://semver.org/)
with modifications.
with some modifications.

> 1.2205.3
The first number representes the Major version. If this number increases there
are updates that may not be backward compatible and you have to adjust your
code. That means the above version string is from major version **1**.
The first number represents the Major version. If this number increases, there
may be updates that are not backward compatible, requiring adjustments to your
code. In the above version string, the major version is **1**.

The first two digits of the second number stand for the year of the included
data and check digit methods. The third and fourth digit increase when there
are either minor version changes that are backward compatible or when new data
is included. That means the above version string is from year 20**22** and
has had a few minor updates, perhaps data updates for spring and summer.
The first two digits of the second number indicate the year of the included data
and check digit methods. The third and fourth digits increase either with minor
version changes that maintain backward compatibility or when new data is
included. In the provided version string, the year is 20**22**, with a few minor
updates, possibly including data updates for spring and summer.

The last number is for patches and bug fixes.
The last number is reserved for patches and bug fixes.

Since the data may change up to four times a year you should use a suitable
version string in your package.json. Since there will be only breaking changes
when the first number changes, you should be good with e.g. `"1.x"`
Considering that the data could change up to four times a year, it's advisable
to use an appropriate version string in your package.json. As breaking changes
occur only when the first number changes, specifying something like `"1.x"`
should suffice.

0 comments on commit d30a8c6

Please sign in to comment.