migration described

README.md

@@ -182,3 +182,20 @@ changes in database.
 `logout(): Promise<void>`
 
 Logout (method: Wyloguj)
+
+## Migrating from version 1.x, 2.x to 3.x
+
+Please note that starting from version 3.0 of that library the following
+breaking changes were introduced:
+
+1. the module is now pure ESM module (previously CJS)
+2. the keys and values are returned as is (previously they were processed)
+
+   - the keys are left intact (previously they were lowercased and a bit
+     trimmed)
+   - the empty values are now returned as empty strings (previously they were
+     returned as `undefined`)
+
+   See further details in the source code of [legacy](src/normalize.ts)
+   normalize function. This function can be used to preserve the old behavior as
+   shown in the [example](examples/legacy.js).

examples/basic.js

@@ -1,9 +1,11 @@
 import Bir from 'bir1'
 
-// In order to get up to date data from production environment, you need to 
-// provide your own key. Ask for it at https://api.stat.gov.pl/Home/RegonApi
-// This sample will work also without that key, but it will return old
-// non-updated data.
+/**
+ * In order to get up to date data from production environment, you need to
+ * provide your own key. Ask for it at https://api.stat.gov.pl/Home/RegonApi
+ * This sample will work also without that key, but it will return old
+ * non-updated data.
+ */
 
 const bir = new Bir({ key: process.env.KEY })
 console.log('StanDanych: ', await bir.value('StanDanych'))

examples/legacy.js

@@ -1,10 +1,16 @@
 import Bir from 'bir1'
 import { legacy } from 'bir1/normalize'
 
-// In previous version of that library (1.0 - 2.0), there was some preprocessing
-// applied to keys. This is no longer needed, but if you want to use old 
-// approach, you can use legacy normalize function from `bir1/normalize` module.
+/**
+ * In previous version of that library (1.x, 2.x), there was some preprocessing
+ * applied to keys and values. This is no longer needed, but if you want to use
+ * old approach, you can use legacy normalize function from `bir1/normalize`.
+ * 
+ * The implementation of legacy normalize function best describes previous
+ * approach. See the source code of file://src/normalize.ts for details.
+ */
 
+// legacy approach (some preprocessing)
 const birLegacy = new Bir({ normalizeFn: legacy })
 await birLegacy.login()
 console.log(
@@ -13,3 +19,13 @@ console.log(
     report: 'BIR11OsPrawna',
   })
 )
+
+// new approach (no preprocessing)
+const birCurrent = new Bir()
+await birCurrent.login()
+console.log(
+  await birCurrent.report({
+    regon: '011417295',
+    report: 'BIR11OsPrawna',
+  })
+)