fat-json 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,87 @@
+# Fat Json
+
+Stringify and parse non-standard JSON data types: _reviver_ and _replacer_ functions for the built-in `JSON` object
+
+## Install
+
+```bash
+npm i fat-json
+```
+
+## Serialising and de-serialising
+
+Transforming _standard data types_ using the built-in `JSON` object is simple, but the JavaScript language now features other types like `BigInt` which don't serialise/cannot be coerced to another type without potential data loss
+
+Serialising and de-serialising with `JSON.stringify()` and `JSON.parse()` provides _some_ opportunity to safely transform data from one type to another with _replacer_ and _reviver_ functions, but while it's not hard to argue with the simplicity of transforming from a `BigInt` to a `String` ...
+
+```javascript
+function replacer (key, value) {
+  if (typeof value === 'bigint') return String(value)
+
+  return value
+}
+```
+
+... it's harder to see how to transform back from a `String` to a `BigInt` without additional information
+
+```javascript
+function reviver (key, value) {
+  if (typeof value === 'string') return BigInt(value)
+
+  return value
+}
+```
+
+Should we use a catch block? Format the _key_ or _value_ in such away that we can test them, and then decide what to do?
+
+_Fat Json_ will supply a _[JSONPath](https://en.wikipedia.org/wiki/JSONPath)_ as the third argument to your _replacer_ or _reviver_ function. If you know the structure of your data in advance you can serialise and de-serialise safely and in one step
+
+```javascript
+import {
+  useReplacerWithPath,
+  useReviverWithPath
+} from 'fat-json'
+
+const d = {
+  id: BigInt(Number.MAX_SAFE_INTEGER)
+}
+
+const s = JSON.stringify(d, useReplacerWithPath((key, value, path) => {
+  if (if path === '$.id') return String(value)
+
+  return value
+}))
+
+const o = JSON.parse(s, useReviverWithPath((key, value, path) => {
+  if (path === '$.id') return BigInt(value)
+
+  return value
+}))
+```
+
+_Any data_ which can be represented as a `String` can be serialised and de-serialised in the same way
+
+### _[From Wikipedia](https://en.wikipedia.org/wiki/JSON)_
+
+> JSON's basic data types are:
+>
+> - Number: a signed decimal number that may contain a fractional part and may
+> use exponential E notation but cannot include non-numbers such as NaN. The
+> format makes no distinction between integer and floating-point. JavaScript
+> uses IEEE-754 double-precision floating-point format for all its numeric
+> values (later also supporting BigInt), but other languages implementing JSON
+> may encode numbers differently.
+> - String: a sequence of zero or more Unicode characters. Strings are delimited
+> with double quotation marks and support a backslash escaping syntax.
+> - Boolean: either of the values true or false
+> - Array: an ordered list of zero or more elements, each of which may be of any
+> type. Arrays use square bracket notation with comma-separated elements.
+> - Object: a collection of name–value pairs where the names (also called keys)
+> are strings. The current ECMA standard states, "The JSON syntax does not
+> impose any restrictions on the strings used as names, does not require that
+> name strings be unique, and does not assign any significance to the ordering
+> of name/value pairs." Objects are delimited with curly brackets and use
+> commas to separate each pair, while within each pair, the colon ":" character
+> separates the key or name from its value.
+> - null: an empty value, using the word null
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fat-json",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "main": "./src/index.mjs",
   "type": "module",
   "types": "./src/index.d.mts",
@@ -16,12 +16,13 @@
   },
   "scripts": {
     "lint": "eslint .",
-    "lint:fix": "npm run lint -- --fix"
+    "lint:fix": "npm run lint -- --fix",
+    "prepare": "husky",
+    "test": "mocha test --recursive"
   },
   "devDependencies": {
     "@sequencemedia/eslint-config-standard": "^0.2.82",
     "@sequencemedia/eslint-config-typescript": "^0.1.141",
-    "@sequencemedia/sinon-chai": "^0.0.186",
     "@types/chai": "^5.2.2",
     "@types/mocha": "^10.0.10",
     "@types/node": "^24.5.0",
@@ -29,12 +30,14 @@
     "chai": "^6.0.1",
     "eslint": "^9.35.0",
     "globals": "^16.4.0",
+    "husky": "^9.1.7",
     "mocha": "^11.7.2",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "sinon-chai": "^4.0.1"
   },
   "imports": {
-    "#fat-json": "./src/index.mjs",
     "#common": "./src/common/index.mjs",
+    "#fat-json": "./src/index.mjs",
     "#transformers": "./src/transformers/index.mjs"
   }
 }

package/src/common/index.d.mts

@@ -6,6 +6,10 @@ export {
   BIG_INT
 }
 
-export function iArray (v: ValueType | ValueType[]): v is any[]
+export function formatNumber (key: number): string
 
-export function isObject (v: ValueType | ValueType[]): v is object
+export function formatString (key: string): string
+
+export function isArray (value: ValueType | ValueType[]): value is any[]
+
+export function isObject (value: ValueType | ValueType[]): value is object

package/src/common/index.mjs

@@ -4,18 +4,28 @@
 
 export const BIG_INT = /^(\d+)n$/
 
+export function formatNumber (key) {
+  return `[${key}]`
+}
+
+export function formatString (key) {
+  return /[ .]/.test(key)
+    ? `.['${key}']`
+    : `.${key}`
+}
+
 /**
- *  @param {ValueType | ValueType[]} v
- *  @returns {v is any[]}
+ *  @param {ValueType | ValueType[]} value
+ *  @returns {value is any[]}
  */
-export function isArray (v) {
-  return Array.isArray(v)
+export function isArray (value) {
+  return Array.isArray(value)
 }
 
 /**
- *  @param {ValueType | ValueType[]} v
- *  @returns {v is object}
+ *  @param {ValueType | ValueType[]} value
+ *  @returns {value is object}
  */
-export function isObject (v) {
-  return (v || false) instanceof Object && !Array.isArray(v)
+export function isObject (value) {
+  return (value || false) instanceof Object && !Array.isArray(value)
 }

package/src/index.mjs

@@ -1,9 +1,6 @@
 /**
  *  @typedef {FatJsonTypes.ValueType} ValueType
  */
-import {
-  BIG_INT
-} from './common/index.mjs'
 import getPath from './replacer/index.mjs'
 import genPath from './reviver/index.mjs'
 
@@ -89,63 +86,3 @@ export function useReviverWithPath (reviver) {
     return value
   }
 }
-
-/**
- *  @param {PropertyKey} key
- *  @param {ValueType} value
- *  @returns {ValueType}
- */
-export function replacer (key, value) {
-  if (typeof value === 'bigint') return String(value) + 'n'
-
-  return value
-}
-
-/**
- *  @param {PropertyKey} key
- *  @param {ValueType} value
- *  @returns {ValueType}
- */
-export function reviver (key, value) {
-  if (typeof value === 'string' && BIG_INT.test(value)) return BigInt (value.replace(BIG_INT, '$1'))
-
-  return value
-}
-
-/**
- *  @param {Set<PropertyKey>} [set]
- *  @returns {(key: PropertyKey, value: ValueType) => ValueType}
- */
-export function getReplacerFor (set = new Set()) {
-  /**
-   *  @param {PropertyKey} key
-   *  @param {ValueType} value
-   *  @returns {ValueType}
-   */
-  return function replacer (key, value) {
-    if (set.has(key)) {
-      if (typeof value === 'bigint') return String(value)
-    }
-
-    return value
-  }
-}
-
-/**
- *  @param {Set<PropertyKey>} [set]
- *  @returns {(key: PropertyKey, value: ValueType) => ValueType}
- */
-export function getReviverFor (set = new Set()) {
-  /**
-   *  @param {PropertyKey} key
-   *  @param {ValueType} value
-   *  @returns {ValueType}
-   */
-  return function reviver (key, value) {
-    if (set.has(key)) {
-      if (typeof value === 'string') return BigInt(value)
-    }
-
-    return value
-  }
-}

package/src/replacer/index.mjs

@@ -1,4 +1,6 @@
 import {
+  formatNumber,
+  formatString,
   isArray,
   isObject
 } from '#common'
@@ -20,12 +22,8 @@ export default function getPath (key, value, context) {
     valuePath = (
       contextPath + (
         Array.isArray(context)
-          ? `[${key}]`
-          : ( // valuePath.includes(SP) || valuePath.includes(ST)
-              /[ .]/.test(key)
-                ? `.['${key}']`
-                : `.${key}`
-            )
+          ? formatNumber(key)
+          : formatString(key)
       )
     )
   }

package/src/reviver/index.mjs

@@ -6,6 +6,8 @@
  */
 
 import {
+  formatNumber,
+  formatString,
   isArray,
   isObject
 } from '#common'
@@ -16,15 +18,17 @@ import {
  *  @returns {IterableIterator<{ key: PropertyKey; value: unknown; path: string; context: any }>}
  */
 function * genPathForArray (context, contextPath) {
-  for (const [index, value] of context.entries()) {
-    const valuePath = contextPath + `[${index}]`
+  for (const [key, value] of context.entries()) {
+    const valuePath = (
+      contextPath + formatNumber(key)
+    )
 
     if (isArray(value)) yield * genPathForArray(value, valuePath)
 
     if (isObject(value)) yield * genPathForObject(value, valuePath)
 
     yield {
-      key: String(index),
+      key: String(key),
       value,
       path: valuePath,
       context
@@ -40,11 +44,7 @@ function * genPathForArray (context, contextPath) {
 function * genPathForObject (context, contextPath) {
   for (const [key, value] of Object.entries(context)) {
     const valuePath = (
-      contextPath + (
-        /[ .]/.test(key)
-          ? `.['${key}']`
-          : `.${key}`
-      )
+      contextPath + formatString(key)
     )
 
     if (isArray(value)) yield * genPathForArray(value, valuePath)
@@ -69,12 +69,8 @@ function * genPathForObject (context, contextPath) {
 export default function * genPath (key, value, context) {
   const valuePath = key
     ? typeof key === 'number'
-      ? `[${key}]`
-      : (
-          /[ .]/.test(key)
-            ? `.['${key}']`
-            : `.${key}`
-        )
+      ? formatNumber(key)
+      : formatString(key)
     : '$'
 
   if (isArray(value)) yield * genPathForArray(value, valuePath)

package/src/transformers/index.mjs

@@ -10,7 +10,7 @@ export function fromBigIntToString (value) {
  *  @param {string} value
  *  @returns {BigInt}
  */
-export function fromStringToBigInt (value) {
+export function formatStringToBigInt (value) {
   return BigInt(value)
 }
 
@@ -18,10 +18,8 @@ export function fromStringToBigInt (value) {
  * @param {string} b
  * @returns {number}
  */
-function toCodePoint (b) {
-  const c = b.codePointAt(0)
-
-  return Number(c)
+function toInteger (b) {
+  return b.codePointAt(0) ?? 0
 }
 
 /**
@@ -33,7 +31,7 @@ function toCodePoint (b) {
  */
 export function fromBase64ToBuffer (base64) {
   const binary = atob(base64) // base64 string to binary string
-  const uint8Array = Uint8Array.from(binary, toCodePoint) // binary string to code point integer
+  const uint8Array = Uint8Array.from(binary, toInteger) // binary string to code point integer
   return Buffer.from(uint8Array)
 }