serialize.js/README.md

# serilize.js: Extended JSON serilization

This extends the default JSON serialization adding the following:
- Recursive data structure serialization
- `undefined`/`NaN` serialization
- Serialization of `BigInt`'s, `Set`'s, `Map`'s
- Function serialization (off by default)
- Deep and partial-deep cleen object copy

Possible differences to JSON output:
- Repeating long strings and BigInts are referenced by default instead of 
  being reincluded in the output.



## Motivation

This was originally built as a companion to a testing module for a 
programming class, illustrating several concepts, including: guaranteed 
clean isolation of data structures via serialization, instrumenting code 
and tooling design, basic parsing, among others.



## Installation

```shell
$ npm install ig-serilaize
```

Or just download and drop [serialize.js](serialize.js) into your code.



## Introduction


### Serializing functions

Due to how JavaScript is designed it is not possible to trivially and 
fully clone a function with all of it's references, `.serilaize(..)` will
not attempt to clone any state a function may have, this will lead to 
loosing:

- Function closure
- Attributes set on the function or any of it's prototypes, including the
  `.__proto__` value if it was changed.
 
Thus, care must be taken when serializing structures containing function.



## API

### `serialize(..)` / `eJSON.stringify(..)`

Serialize a JavaScript value into a JSON/eJSON string.
```
serialize(<value>)
eJSON.stringify(<value>)
	-> <string>
```

More control:
```
serialize(obj, options){
serialize(obj, indent, depth=0, options){
	-> <string>
```

Options format:
```
{
	// pretty-printing indent...
	// (default: undefined)
	indent: undefined,
	
	// outout root indent...
	// (default: 0)
	depth: 0,
	
	// minimal referenced string/bigint length...
	// (default: MIN_LENGTH_REF)
	min_length_ref: MIN_LENGTH_REF,
	
	// functions list...
	// (default: undefined)
	functions: undefined,
}
```

Supported options:
- `indent` controls formatting and nested value indent, if set to a number 
  that number of spaces will be used to indent nested values if given a 
  string that string is used for indenting, note that only whitespace is 
  supported currently.
  Default: `undefined` (disabled)
- `depth` if given is a number of `indent`'s, used to set top level indent 
  depth of the returned string, this can be useful when pretty-printing 
  or nesting the output. 
  Default: `0`
- `min_length_ref` sets the minimal length of a string or big-int value
  for referencing when encountered repeatedly. 
  If set to `0` or `Infinity` referencing of strings and big-ints will 
  be is disabled. 
  Default: 'MIN_LENGTH_REF'
- `functions` if passed an array, encounterd functions will be pushed to 
  it and stored in the output by index. 
  Default: `undefined`


### `deserialize(..)` / `eJSON.parse(..)`

Deserialize a JSON/eJSON into a value.
```
deserialize(<string>)
eJSON.parse(<string>)
	-> <value>
```

Deserializing function is disabled by default as it can be a security 
risk if the eJSON came from an untrusted source.

Enable function deserialization:
```
deserialize(<string>, true)
eJSON.parse(<string>, true)
deserialize(<string>, {functions: true})
eJSON.parse(<string>, {functions: true})
	-> <value>
```

Passing a function list (generated by `serialize(<value>, {functions: <functions>})`) 
for deserialization:
```
deserialize(<string>, {functions: <functions>})
eJSON.parse(<string>, {functions: <functions>})
	-> <value>
```


### `deepCopy(..)`

```
deepCopy(<value>)
	-> <value>
```


### `partialDeepCopy(..)`

```
partialDeepCopy(<value>)
	-> <value>
```


### `MIN_LENGTH_REF` / `<options>.min_length_ref` 

Defines the default minimum length of repeating string or bin-int to 
include as a reference in the output.

If set to `0`, referencing will be disabled.

Default: 96  


### `DEBUG`



## Format

The output of `.serialize(..)` is a strict superset of [standard JSON](https://www.json.org/json-en.html), 
while the input format is a bit more relaxed than in several details.

Extensions to JSON:
- Recursion
- undefined / NaN
- BigInt
- Map / Set
- Function

### Structural paths

### Recursion

If an object is encountered 

### null types

### BigInt

### Map / Set

### Functions