feat: 🎸 Clearly distinguish between ArrayBuffer and TypedArray

Author: haozi

README.md

@@ -65,6 +65,41 @@ const restoredUnsafe = jsonWeb3.parse_UNSAFE(textUnsafe)
 - `stringify_UNSAFE(value, replacer?, space?)` (serializes `Function` payloads)
 - `parse_UNSAFE(text, reviver?)` (revives `Function` payloads via `new Function(...)`)
 
+## Type support
+
+| type                | supported by standard JSON? | supported by json-web3?               |
+| ------------------- | --------------------------- | ------------------------------------- |
+| `string`            | ✅                          | ✅                                    |
+| `number`            | ✅                          | ✅                                    |
+| `boolean`           | ✅                          | ✅                                    |
+| `null`              | ✅                          | ✅                                    |
+| `Array`             | ✅                          | ✅                                    |
+| `Object`            | ✅                          | ✅                                    |
+| `undefined`         | ❌                          | ❌                                    |
+| `Infinity`          | ❌                          | ✅                                    |
+| `-Infinity`         | ❌                          | ✅                                    |
+| `NaN`               | ❌                          | ✅                                    |
+| `BigInt`            | ❌                          | ✅                                    |
+| `Date`              | ❌                          | ✅                                    |
+| `RegExp`            | ❌                          | ✅                                    |
+| `Set`               | ❌                          | ✅                                    |
+| `Map`               | ❌                          | ✅                                    |
+| `URL`               | ❌                          | ✅                                    |
+| `ArrayBuffer`       | ❌                          | ✅                                    |
+| `Uint8Array`        | ❌                          | ✅                                    |
+| `Uint8ClampedArray` | ❌                          | ✅                                    |
+| `Uint16Array`       | ❌                          | ✅                                    |
+| `Uint32Array`       | ❌                          | ✅                                    |
+| `Int8Array`         | ❌                          | ✅                                    |
+| `Int16Array`        | ❌                          | ✅                                    |
+| `Int32Array`        | ❌                          | ✅                                    |
+| `Float16Array`      | ❌                          | ✅                                    |
+| `Float32Array`      | ❌                          | ✅                                    |
+| `Float64Array`      | ❌                          | ✅                                    |
+| `BigInt64Array`     | ❌                          | ✅                                    |
+| `BigUint64Array`    | ❌                          | ✅                                    |
+| `Function`          | ❌                          | ✅ ⚠️(use UNSAFE api, it's dangerous) |
+
 ## Note
 
 - `bigint` values are encoded as objects: `{"__@json.bigint__":"<value>"}`.
@@ -73,7 +108,8 @@ const restoredUnsafe = jsonWeb3.parse_UNSAFE(textUnsafe)
 - `Map` values are encoded as `{"__@json.map__":[[k,v],...]}` and `Set` values as `{"__@json.set__":[...]}`.
 - `RegExp` values are encoded as `{"__@json.regexp__":{"source":"...","flags":"..."}}`.
 - `URL` values are encoded as `{"__@json.url__":"..."}`.
-- `Function` values are encoded as `{"__@json.function__":"<source>"}` by `stringify_UNSAFE` and are only revived by `parse_UNSAFE` using `new Function(...)` (only do this with trusted input).
-- `ArrayBuffer`, Node `Buffer` JSON shapes, and typed arrays are encoded as `{"__@json.typedarray__":{"type":"<Name>","bytes":"0x..."}}` and decoded back to the original typed array (`Uint8Array`, `Uint8ClampedArray`, `Uint16Array`, `Uint32Array`, `Int8Array`, `Int16Array`, `Int32Array`, `Float32Array`, `Float64Array`, `BigInt64Array`, `BigUint64Array`).
+- `Function` values are encoded as `{"__@json.function__":"<source>"}` by `stringify_UNSAFE` and are only revived by `parse_UNSAFE` using `new Function(...)` (using the UNSAFE function pair is dangerous; make sure your data is trusted).
+- `ArrayBuffer` values are encoded as `{"__@json.arraybuffer__":{"bytes":"0x..."}}` and decoded back to `ArrayBuffer`.
+- Node `Buffer` JSON shapes and typed arrays are encoded as `{"__@json.typedarray__":{"type":"<Name>","bytes":"0x..."}}` and decoded back to the original typed array (`Uint8Array`, `Uint8ClampedArray`, `Uint16Array`, `Uint32Array`, `Int8Array`, `Int16Array`, `Int32Array`, `Float32Array`, `Float64Array`, `BigInt64Array`, `BigUint64Array`).
 
 Compared to libraries that require eval-based parsing (for example, `serialize-javascript`), this approach is generally safer and more efficient.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-web3",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "BigInt-safe JSON serialization and deserialization for Web3 use cases.",
   "keywords": [
     "json",

src/index.ts

@@ -1,9 +1,11 @@
 import {
+  ARRAYBUFFER_TAG,
   BIGINT_TAG,
   DATE_TAG,
   fromSerializable,
   FUNCTION_TAG,
   isArray,
+  isArrayBufferPayload,
   isDate,
   isFunction,
   isRegExpPayload,
@@ -38,7 +40,9 @@ const applyReplacer = (holder: any, key: string, value: any, replacer: Replacer)
     if (key === URL_TAG) return value
     if (key === FUNCTION_TAG) return value
     if (key === TYPEDARRAY_TAG) return value
+    if (key === ARRAYBUFFER_TAG) return value
     if (isTypedArrayPayload(holder)) return value
+    if (isArrayBufferPayload(holder)) return value
     if (isRegExpPayload(holder)) return value
     if (isArray(holder)) return value
     return replacer.includes(key) ? value : undefined

src/utils.ts

@@ -1,5 +1,6 @@
 export const BIGINT_TAG = '__@json.bigint__'
 export const TYPEDARRAY_TAG = '__@json.typedarray__'
+export const ARRAYBUFFER_TAG = '__@json.arraybuffer__'
 export const DATE_TAG = '__@json.date__'
 export const MAP_TAG = '__@json.map__'
 export const SET_TAG = '__@json.set__'
@@ -141,7 +142,7 @@ export const toSerializable = (value: any, options: { allowFunction?: boolean }
   }
 
   if (isArrayBuffer(value)) {
-    return { [TYPEDARRAY_TAG]: { type: 'Uint8Array', bytes: toHex(new Uint8Array(value)) } }
+    return { [ARRAYBUFFER_TAG]: { bytes: toHex(new Uint8Array(value)) } }
   }
 
   if (
@@ -223,6 +224,16 @@ export const fromSerializable = (value: any, options: { allowFunction?: boolean
       new Uint8Array(buffer).set(bytes)
       return new ctor(buffer)
     }
+    if (hasOwnProperty(value, ARRAYBUFFER_TAG)) {
+      const payload = value[ARRAYBUFFER_TAG]
+      if (!payload || !isObject(payload) || !isString(payload.bytes)) {
+        throw new Error('Invalid arraybuffer payload')
+      }
+      const bytes = fromHex(payload.bytes)
+      const buffer = new ArrayBuffer(bytes.byteLength)
+      new Uint8Array(buffer).set(bytes)
+      return buffer
+    }
     if (
       value.type === 'Buffer' &&
       isArray(value.data) &&
@@ -241,6 +252,9 @@ export const isTypedArrayPayload = (value: any): boolean =>
   isString(value.bytes) &&
   Object.keys(value).length === 2
 
+export const isArrayBufferPayload = (value: any): boolean =>
+  isObject(value) && isString(value.bytes) && Object.keys(value).length === 1
+
 export const isRegExpPayload = (value: any): boolean =>
   isObject(value) &&
   isString(value.source) &&

test/index.test.ts

@@ -119,15 +119,15 @@ describe('json-web3', () => {
     expect(Array.from(output)).toEqual([10, 11, 12])
   })
 
-  it('handles ArrayBuffer value as bytes', () => {
+  it('handles ArrayBuffer value as ArrayBuffer', () => {
     const ab = new ArrayBuffer(4)
     new Uint8Array(ab).set([9, 8, 7, 6])
 
     const text = stringify({ ab })
     const output = parse(text)
 
-    expect(output.ab).toBeInstanceOf(Uint8Array)
-    expect(Array.from(output.ab)).toEqual([9, 8, 7, 6])
+    expect(output.ab).toBeInstanceOf(ArrayBuffer)
+    expect(Array.from(new Uint8Array(output.ab))).toEqual([9, 8, 7, 6])
   })
 
   it('does not mutate JSON primitives and null', () => {
@@ -226,6 +226,15 @@ describe('json-web3', () => {
     expect(Array.from(output.data)).toEqual([1])
   })
 
+  it('replacer array does not drop arraybuffer tag keys', () => {
+    const input = { data: { '__@json.arraybuffer__': { bytes: '0x0102' } } }
+    const text = stringify(input, ['data'])
+    const output = parse(text)
+
+    expect(output.data).toBeInstanceOf(ArrayBuffer)
+    expect(Array.from(new Uint8Array(output.data))).toEqual([1, 2])
+  })
+
   it('replacer array does not drop new internal tag keys', () => {
     const input = {
       d: new Date('2020-01-02T03:04:05.006Z'),
@@ -298,6 +307,11 @@ describe('json-web3', () => {
     expect(() => parse_UNSAFE(text)).toThrowError()
   })
 
+  it('parse throws on invalid arraybuffer payload', () => {
+    const text = '{"x":{"__@json.arraybuffer__":{"bytes":123}}}'
+    expect(() => parse(text)).toThrowError()
+  })
+
   it('falls back to raw bytes when typed array type is unknown', () => {
     const text = '{"__@json.typedarray__":{"type":"UnknownArray","bytes":"0x01"}}'
     const output = parse(text)
@@ -441,6 +455,15 @@ describe('json-web3', () => {
     expect(output).toEqual({})
   })
 
+  it('parse_UNSAFE reviver receives decoded values', () => {
+    const text = stringify_UNSAFE({ fn: (arg: string) => arg })
+    const output = parse_UNSAFE(text, (_key, value) =>
+      typeof value === 'function' ? value('ok') : value,
+    )
+
+    expect(output.fn).toBe('ok')
+  })
+
   it('BigInt in array with replacer array filtering works as expected', () => {
     const input = { list: [1n, 2n], other: 3n }
     const text = stringify(input, ['list'])