fat-json 0.0.4 → 0.0.6

package/README.md

@@ -1,6 +1,6 @@
 # Fat Json
 
-Stringify and parse non-standard JSON data types: _reviver_ and _replacer_ functions for the built-in `JSON` object
+Stringify and parse non-standard JSON [data types](#from-wikipedia): _reviver_ and _replacer_ functions for the built-in `JSON` object
 
 ## Install
 
@@ -12,7 +12,11 @@ npm i fat-json
 
 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` ...
+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
+
+#### A typical replacer function for `BigInt`
+
+We can test the `value` and transform based on its type
 
 ```javascript
 function replacer (key, value) {
@@ -22,7 +26,11 @@ function replacer (key, value) {
 }
 ```
 
-... it's harder to see how to transform back from a `String` to a `BigInt` without additional information
+It's hard to argue with the simplicity of transforming from a `BigInt` to a `String` but it's harder to see how we should transform back from a `String` to a `BigInt` without some _additional information_
+
+#### A typical reviver function
+
+Should we transform every `String`?
 
 ```javascript
 function reviver (key, value) {
@@ -32,9 +40,11 @@ function reviver (key, 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?
+We could use a catch block. Or else format the _key_ or _value_ such that we can test one or both of them, and then decide what to do
+
+## Fat Json's third argument
 
-_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
+_Fat Json_ supplies a _[JSONPath](https://en.wikipedia.org/wiki/JSONPath)_ as the third argument to your _replacer_ or _reviver_ function so you can decide _whether to transform a value by its position in the JSON document_, not just by its `key` or `value`. If you know the structure of your data in advance you can serialise and de-serialise safely and in one step
 
 ```javascript
 import {

package/index.d.mts

@@ -0,0 +1,32 @@
+declare global {
+  namespace FatJsonTypes {
+    export type ArrayLiteralType = unknown[] | never[]
+    export type ObjectLiteralType = Record<PropertyKey, unknown> | Record<PropertyKey, never>
+    export type ValueType = string | number | boolean | null | bigint | ArrayLiteralType | ObjectLiteralType | Buffer | undefined | object
+
+    export namespace PathTypes {
+      export interface ArrayPathDescriptor {
+        key: PropertyKey
+        value: ValueType
+        path: string
+        context: ArrayLiteralType
+      }
+
+      export interface ObjectPathDescriptor {
+        key: PropertyKey
+        value: ValueType
+        path: string
+        context: ObjectLiteralType
+      }
+
+      export interface PathDescriptor {
+        key: PropertyKey
+        value: ValueType
+        path: string
+        context: ArrayLiteralType | ObjectLiteralType
+      }
+    }
+  }
+}
+
+export {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fat-json",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "keywords": [
     "JSON",
     "stringify",
@@ -12,7 +12,7 @@
   ],
   "main": "./src/index.mjs",
   "type": "module",
-  "types": "./src/index.d.mts",
+  "types": "./index.d.mts",
   "author": {
     "name": "Jonathan Perry for Sequence Media Limited",
     "email": "sequencemedia@sequencemedia.net",
@@ -30,11 +30,11 @@
     "test": "mocha test --recursive"
   },
   "devDependencies": {
-    "@sequencemedia/eslint-config-standard": "^0.2.82",
-    "@sequencemedia/eslint-config-typescript": "^0.1.141",
+    "@sequencemedia/eslint-config-standard": "^0.2.83",
+    "@sequencemedia/eslint-config-typescript": "^0.1.142",
     "@types/chai": "^5.2.2",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.5.0",
+    "@types/node": "^24.5.1",
     "@types/sinon": "^17.0.4",
     "chai": "^6.0.1",
     "eslint": "^9.35.0",
@@ -47,6 +47,10 @@
   "imports": {
     "#common": "./src/common/index.mjs",
     "#fat-json": "./src/index.mjs",
-    "#transformers": "./src/transformers/index.mjs"
+    "#transformers": "./src/transformers/index.mjs",
+    "#types": "./types/index.d.mts"
+  },
+  "exports": {
+    "./transformers": "./src/transformers/index.mjs"
   }
 }

package/src/common/index.d.mts

@@ -1,4 +1,4 @@
-type ValueType = FatJsonTypes.ValueType
+export type ValueType = FatJsonTypes.ValueType
 
 declare const BIG_INT: RegExp
 

package/src/common/index.mjs

@@ -1,5 +1,5 @@
 /**
- *  @typedef {FatJsonTypes.ValueType} ValueType
+ *  @typedef {import('#types').ValueType} ValueType
  */
 
 export const BIG_INT = /^(\d+)n$/

package/src/index.d.mts

@@ -1,9 +1,11 @@
-declare global {
-  namespace FatJsonTypes {
-    export type ArrayLiteralType = unknown[] | never[]
-    export type ObjectLiteralType = Record<PropertyKey, unknown> | Record<PropertyKey, never>
-    export type ValueType = string | number | boolean | null | bigint | ArrayLiteralType | ObjectLiteralType | Buffer | undefined | object
-  }
-}
-
-export {}
+export type ArrayLiteralType = FatJsonTypes.ArrayLiteralType
+export type ObjectLiteralType = FatJsonTypes.ObjectLiteralType
+export type ValueType = FatJsonTypes.ValueType
+
+export function useReplacerWithType (replacer: (key: PropertyKey, value: ValueType, type?: string) => ValueType): (key: PropertyKey, value: ValueType) => ValueType
+
+export function useReviverWithType (reviver: (key: PropertyKey, value: ValueType, type?: string) => ValueType): (key: PropertyKey, value: ValueType) => ValueType
+
+export function useReplacerWithPath (replacer: (key: PropertyKey, value: ValueType, path?: string) => ValueType) : (key: PropertyKey, value: ValueType) => ValueType
+
+export function useReviverWithPath (reviver: (key: PropertyKey, value: ValueType, path?: string) => ValueType): (key: PropertyKey, value: ValueType) => ValueType

package/src/index.mjs

@@ -1,6 +1,7 @@
 /**
- *  @typedef {FatJsonTypes.ValueType} ValueType
+ *  @typedef {import('#types').ValueType} ValueType
  */
+
 import getPath from './replacer/index.mjs'
 import genPath from './reviver/index.mjs'
 

package/src/replacer/index.d.mts

@@ -1,5 +1,5 @@
-type ArrayLiteralType = FatJsonTypes.ArrayLiteralType
-type ObjectLiteralType = FatJsonTypes.ObjectLiteralType
-type ValueType = FatJsonTypes.ValueType
+export type ArrayLiteralType = FatJsonTypes.ArrayLiteralType
+export type ObjectLiteralType = FatJsonTypes.ObjectLiteralType
+export type ValueType = FatJsonTypes.ValueType
 
 export default function getPath (key: PropertyKey, value: ValueType, context: ArrayLiteralType | ObjectLiteralType): string

package/src/replacer/index.mjs

@@ -1,3 +1,9 @@
+/**
+ *  @typedef {import('#types').ArrayLiteralType} ArrayLiteralType
+ *  @typedef {import('#types').ObjectLiteralType} ObjectLiteralType
+ *  @typedef {import('#types').ValueType} ValueType
+ */
+
 import {
   formatNumber,
   formatString,
@@ -5,12 +11,15 @@ import {
   isObject
 } from '#common'
 
+/**
+ *  @type {WeakMap<WeakKey, ArrayLiteralType | ObjectLiteralType>}
+ */
 const MAP = new WeakMap()
 
 /**
  *  @param {PropertyKey} key
- *  @param {unknown} value
- *  @param {any} context
+ *  @param {ValueType} value
+ *  @param {ArrayLiteralType | ObjectLiteralType} context
  *  @returns {string}
  */
 export default function getPath (key, value, context) {

package/src/reviver/index.d.mts

@@ -1,5 +1,11 @@
-type ArrayLiteralType = FatJsonTypes.ArrayLiteralType
-type ObjectLiteralType = FatJsonTypes.ObjectLiteralType
-type ValueType = FatJsonTypes.ValueType
+export type ArrayLiteralType = FatJsonTypes.ArrayLiteralType
+export type ObjectLiteralType = FatJsonTypes.ObjectLiteralType
+export type ValueType = FatJsonTypes.ValueType
 
-export default function genPath (key: PropertyKey, value: ValueType, context: ArrayLiteralType | ObjectLiteralType): IterableIterator<{ key: PropertyKey; value: ValueType; path: string; context: ArrayLiteralType | ObjectLiteralType }>
+export namespace PathTypes {
+  export type ArrayPathDescriptor = FatJsonTypes.PathTypes.ArrayPathDescriptor
+  export type ObjectPathDescriptor = FatJsonTypes.PathTypes.ObjectPathDescriptor
+  export type PathDescriptor = FatJsonTypes.PathTypes.PathDescriptor
+}
+
+export default function genPath (key: PropertyKey, value: ValueType, context: ArrayLiteralType | ObjectLiteralType): IterableIterator<PathTypes.PathDescriptor>

package/src/reviver/index.mjs

@@ -1,8 +1,10 @@
 /**
- *  @typedef {FatJsonTypes.ArrayLiteralType} ArrayLiteralType
- *  @typedef {FatJsonTypes.ObjectLiteralType} ObjectLiteralType
- *  @typedef {FatJsonTypes.ValueType} ValueType
- *  @typedef {FatJsonTypes.WeakMapType} WeakMapType
+ *  @typedef {import('#types').ArrayLiteralType} ArrayLiteralType
+ *  @typedef {import('#types').ObjectLiteralType} ObjectLiteralType
+ *  @typedef {import('#types').ValueType} ValueType
+ *  @typedef {import('#types').PathTypes.ArrayPathDescriptor} PathTypes.ArrayPathDescriptor
+ *  @typedef {import('#types').PathTypes.ObjectPathDescriptor} PathTypes.ObjectPathDescriptor
+ *  @typedef {import('#types').PathTypes.PathDescriptor} PathTypes.PathDescriptor
  */
 
 import {
@@ -13,9 +15,9 @@ import {
 } from '#common'
 
 /**
- *  @param {any[]} context
+ *  @param {ArrayLiteralType} context
  *  @param {string} contextPath
- *  @returns {IterableIterator<{ key: PropertyKey; value: unknown; path: string; context: any }>}
+ *  @returns {IterableIterator<PathTypes.ArrayPathDescriptor>}
  */
 function * genPathForArray (context, contextPath) {
   for (const [key, value] of context.entries()) {
@@ -37,9 +39,9 @@ function * genPathForArray (context, contextPath) {
 }
 
 /**
- *  @param {any} context
+ *  @param {ObjectLiteralType} context
  *  @param {string} contextPath
- *  @returns {IterableIterator<{ key: PropertyKey; value: unknown; path: string; context: any }>}
+ *  @returns {IterableIterator<PathTypes.ObjectPathDescriptor>}
  */
 function * genPathForObject (context, contextPath) {
   for (const [key, value] of Object.entries(context)) {
@@ -62,9 +64,9 @@ function * genPathForObject (context, contextPath) {
 
 /**
  *  @param {PropertyKey} key
- *  @param {unknown} value
- *  @param {any | any[]} context
- *  @returns {IterableIterator<{ key: PropertyKey; value: unknown; path: string; context: any }>}
+ *  @param {ValueType} value
+ *  @param {ArrayLiteralType | ObjectLiteralType} context
+ *  @returns {IterableIterator<PathTypes.PathDescriptor>}
  */
 export default function * genPath (key, value, context) {
   const valuePath = key

package/types/index.d.mts

@@ -0,0 +1,9 @@
+export type ArrayLiteralType = FatJsonTypes.ArrayLiteralType
+export type ObjectLiteralType = FatJsonTypes.ObjectLiteralType
+export type ValueType = FatJsonTypes.ValueType
+
+export namespace PathTypes {
+  export type ArrayPathDescriptor = FatJsonTypes.PathTypes.ArrayPathDescriptor
+  export type ObjectPathDescriptor = FatJsonTypes.PathTypes.ObjectPathDescriptor
+  export type PathDescriptor = FatJsonTypes.PathTypes.PathDescriptor
+}