From 154ee4279446c8d55e5691cfeee504370dd4a23d Mon Sep 17 00:00:00 2001
From: Pawel Idczak <pawel.idczak@gmail.com>
Date: Tue, 27 Feb 2024 22:34:50 +0100
Subject: [PATCH] migration described

---
 README.md          | 17 +++++++++++++++++
 examples/basic.js  | 10 ++++++----
 examples/legacy.js | 22 +++++++++++++++++++---
 3 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 1159608..c6375a6 100644
--- a/README.md
+++ b/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).
diff --git a/examples/basic.js b/examples/basic.js
index 97aa86e..b25583d 100644
--- a/examples/basic.js
+++ b/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'))
diff --git a/examples/legacy.js b/examples/legacy.js
index eb45da2..084c2ec 100644
--- a/examples/legacy.js
+++ b/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',
+  })
+)
\ No newline at end of file