docs

src/normalize.ts

@@ -56,12 +56,11 @@ function lowerCamelCase(name: string) {
 
 /**
  * Traverse object recursively and apply provided function `fn` to each
- * key-value pair. Function can modify key and value or return the same. Object
- * is mutated in place.
+ * key-value pair. Returns new object.
  * @param obj object to traverse
  * @param fn function to apply
  */
-export function morph(
+function morph(
   obj: any,
   fn: (key: string, value: any) => { key: string; value: any }
 ): any {
@@ -87,7 +86,8 @@ export function morph(
 }
 
 /**
- * Provides compatibility with legacy version of the API. This function:
+ * Transforms object parsed from raw API response to format compatible with
+ * earlier versions of the API. This function:
  *  - removes 'praw_' prefix from keys
  *  - lower first letter of keys
  *  - replaces empty strings with `undefined`
@@ -96,6 +96,14 @@ export function morph(
  * prefix was initial partial implementation. This is inconsistent approach and
  * thus marked as deprecated, left only for compatibility with legacy code.
  *
+ * @example
+ * ```js
+ * import Bir from 'bir1'
+ * import { legacy } from 'bir1/normalize'
+ * const bir = new Bir({normalizeFn: legacy})
+ * const result = await bir.search('010058960')
+ * ```
+ *
  * @param obj object to normalize
  * @deprecated
  */
@@ -109,6 +117,22 @@ export function legacy(obj: any) {
 }
 
 /**
+ * Transforms object parsed from raw API response to convenient format commonly
+ * used in modern JavaScript applications. This is subjective and opinionated.
+ * This function:
+ * - remove prefixes from keys
+ * - lower camel case keys
+ * - unifies some keys (e.g. `regon9` -> `regon`)
+ * - replaces empty strings with `undefined`
+ *
+ * @example
+ * ```js
+ * import Bir from 'bir1'
+ * import { modern } from 'bir1/normalize'
+ * const bir = new Bir({normalizeFn: modern})
+ * const result = await bir.search('010058960')
+ * ```
+ *
  * @param obj object to normalize
  * @beta
  */