ig-serialize 1.2.0 → 1.3.0

package/README.md

@@ -2,14 +2,16 @@
 
 This extends the default JSON serialization adding the following:
 - Recursive data structure serialization
+- Sparse array serialization
 - `undefined`/`NaN` serialization
-- `Set`/`Map` serialization
+- Serialization of `Infinity`, `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 can be referenced instead of 
-  reincluded in the output.
+- Repeating long strings and BigInts are referenced by default instead of 
+  being reincluded in the output.
+
 
 
 ## Motivation
@@ -23,6 +25,7 @@ and tooling design, basic parsing, among others.
 
 ## Installation
 
+For basic use:
 ```shell
 $ npm install ig-serilaize
 ```
@@ -30,6 +33,10 @@ $ npm install ig-serilaize
 Or just download and drop [serialize.js](serialize.js) into your code.
 
 
+```javascript
+serialize = require('ig-serialize')
+```
+
 
 ## Introduction
 
@@ -53,12 +60,106 @@ Thus, care must be taken when serializing structures containing function.
 
 ### `serialize(..)` / `eJSON.stringify(..)`
 
-### `deserialize(..)` / 'eJSON.parse(..)'
+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` 
 
@@ -79,23 +180,108 @@ Default: 96
 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
+Paths are used for internal references in cases when objects are 
+encountered multiple times, e.g. in recursion.
+
+A path is an array of keys, the meaning of each key depends on the data 
+structure traversed:
+- array -> number
+- object -> string
+- set -> number -- item order in set
+- map -> pair of numbers -- the first indicates item order the second 
+  if 0 selects the key, if 1 selects the value.
+
+Note that string path items are unambiguous and are always treated as 
+attributes.
+
+An empty path indicates the root object.
+
+
+### Referencing 
+
+If an object is encountered for a second time it will be serialized as 
+a reference by path to the first occurrence.
+
+Format:
+```bnf
+<ref> ::= 
+	'<REF' <path> '>'
+	
+<path> ::= 
+	'[' <path-items> ']'
+	
+<path-items> ::=
+	<item>
+	| <item> ',' <path-items>
+	
+<item> ::=
+	<number>
+	| <string> 
+```
+
+Example:
+```javascript
+// a recursive array...
+var o = []
+o.o = o
+
+// root object reference...
+serialize(o) // -> '[<REF[]>]'
+
+// array item...
+serialize([o]) // -> '[[<REF[0]>]]'
+
+// set item...
+// NOTE: the path here is the same as in the above example -- since we 
+//	use ordered topology for paths sets do not differ from arrays.
+serialize(new Set([o])) // -> 'Set([[<REF[0]>]])'
+
+// map key...
+serialize(new Map([[o, 'value']])) // -> 'Map([[[<REF[0,0]>],"value"]])'
+
+// map value...
+serialize(new Map([['key', o]])) // -> 'Map([["key",[<REF[0,1]>]]])'
+```
 
-If an object is encountered 
 
-### null types
+### Null types
+
+In addition to `null`, serialize.js adds support for `undefined` and 
+`NaN` which are stored as-is.
+
+Example:
+```javascript
+serialize([null, undefined, NaN]) // -> '[null,undefined,NaN]'
+```
+
+### Sparse arrays
+
+Sparse arrays are represented in the same way JavaScript handles them 
+syntactically.
+
+Example:
+```javascript
+serialize([,]) // -> '[,]'
+serialize([,,]) // -> '[,,]'
+```
+
+Note that trailing commas are ignored in the same way JavaScript ignores 
+them:
+```javascript
+// trailing comma...
+serialize([1,]) // -> '[1]'
+
+// sparse element...
+serialize([1,,]) // -> '[1,,]'
+```
 
 ### BigInt
 
+### Infinity
+
 ### Map / Set
 
 ### Functions
@@ -103,6 +289,24 @@ If an object is encountered
 
 
 
+## Running tests
+
+Get the development dependencies:
+```shell
+$ npm install -D
+```
+
+Run the tests:
+```shell
+$ npm test
+```
+
+To run the tests directly:
+```shell
+$ node ./test.js
+```
+
 
 
 
+<!-- vim:set nowrap : -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ig-serialize",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "experimental extended json serializaion...",
   "main": "serialize.js",
   "scripts": {

package/serialize.js

@@ -8,6 +8,16 @@
 * 	- get/set object by path
 * 		Object.get(..) / Object.set(..)
 *
+* XXX try removing paths from refs and use the same indexes, the same 
+* 	system as with functions...
+* 		+ this will make the refs shorter
+* 		- the deserialization would require the same "seen" logic as 
+* 			serialization -- reuse a function
+* 		- the "seen" logic can depend on settings, i.e. would either 
+* 			require a sable algorithm that would be settings-agnostic
+* 			a-la paths (preferred), or a way to transfer serialization 
+* 			settings...
+*
 * XXX the current path implementation is fully complient to the task at 
 * 	hand but it will not suite the diff task as there is no way to know
 * 	the meaning of the path element without seeing the object (map/set 
@@ -94,6 +104,29 @@ module.MIN_LENGTH_REF = REFERENCE.length * 16
 // 		-> str
 //
 //
+// options format:
+// 	{
+// 		// Indent to use for formatting output.
+// 		// Can be:
+// 		//	<number>	- number of spaces to use for indent
+// 		//	<string>	- string to use for indent
+// 		// 					NOTE: only whitespace characters are supported 
+// 		//						currently.
+// 		indent: undefined,
+//
+// 		// Top level indent.
+// 		depth: 0,
+//
+// 		// Minimum length of string/bigint to reference.
+// 		min_length_ref: MIN_LENGTH_REF,
+//
+// 		// Stored functions.
+// 		// If set to an array functions will be pushed to it and stored 
+// 		// by index.
+// 		functions: undefined,
+// 	}
+//
+//
 // Paths
 // 	A path is a chain of indexes/keys leading to a specific object in 
 // 	tree.
@@ -144,6 +177,8 @@ module.MIN_LENGTH_REF = REFERENCE.length * 16
 var _serialize = 
 module._serialize = 
 function(obj, path=[], seen=new Map(), indent, depth=0, options={}){
+	if(typeof(indent) == 'number'){
+		indent = ' '.repeat(indent) }
 	var min_length_ref = 
 		options.min_length_ref 
 			?? module.MIN_LENGTH_REF
@@ -212,11 +247,13 @@ function(obj, path=[], seen=new Map(), indent, depth=0, options={}){
 	if(obj instanceof Array){
 		pre = '['
 		post = ']'
+		elems.length = obj.length
 		for(var i=0; i < obj.length; i++){
-			elems.push(
-				i in obj ?
-					_serialize(obj[i], [...path, i], seen, indent, depth+1, options)
-					: EMPTY) }
+			if(i in obj){
+				elems[i] = _serialize(obj[i], [...path, i], seen, indent, depth+1, options) } }
+		// add trailing coma if last elem is empty...
+		if(!(elems.length-1 in elems)){
+			elems.length++ }
 	} else if(obj instanceof Map){
 		pre = 'Map(['
 		post = '])'
@@ -260,6 +297,11 @@ function(obj, path=[], seen=new Map(), indent, depth=0, options={}){
 var serialize = 
 module.serialize = 
 function(obj, indent, depth=0, options){
+	if(indent 
+			&& typeof(indent) == 'object'){
+		options = indent
+		indent = options.indent
+		depth = options.depth ?? 0 }
 	return _serialize(obj, [], new Map(), indent, depth, options) }
 
 
@@ -340,8 +382,13 @@ module.eJSON = {
 					&& i == path.length-1){
 				return [path.slice(0, -1), obj] }
 
-			obj = obj instanceof Set ?
+			obj = 
+				// special case: string key -> attribute...
+				typeof(k) == 'string' ?
+					obj[k]
+				: obj instanceof Set ?
 					[...obj][k]
+				// takes two items off the path -- [intex, key/value]...
 				: obj instanceof Map ?
 					[...obj][k][path[++i]]
 				: obj[k] }
@@ -365,6 +412,12 @@ module.eJSON = {
 	setItem: function(obj, path, value){
 		var [p, parent] = this._getItem(obj, path.slice(0, -1))
 		var k = path.at(-1)
+
+		// special case: string kye -> attr...
+		if(typeof(k) == 'string'){
+			parent[k] = value 
+			return value }
+
 		if(parent instanceof Set){
 			var elems = [...parent]
 			elems[k] = value
@@ -695,7 +748,12 @@ module.eJSON = {
 		return this[handler](state, path, match, str, i, line) },
 
 
-	parse: function(str, options={}){
+	parse: function(str, options){
+		options = 
+			options === true ?
+				{functions: true}
+				: (options 
+					?? {})
 
 		// stage 1: build the object...
 		var state = {functions: options.functions}
@@ -715,10 +773,6 @@ module.eJSON = {
 var deserialize =
 module.deserialize =
 function(str, options){
-	options = 
-		options === true ?
-			{functions: true}
-			: options
 	return eJSON.parse(str, options) }
 
 

package/test.js

@@ -82,13 +82,13 @@ var setups = test.Setups({
 	'array-empty': function(assert){
 		return ['[]', json] },
 	'array-sparse-a': function(assert){
-		return ['[<empty>]'] },
+		return ['[,]'] },
 	'array-sparse-b': function(assert){
-		return ['["a",<empty>]'] },
+		return ['["a",,]'] },
 	'array-sparse-c': function(assert){
-		return ['[<empty>,"a"]'] },
+		return ['[,"a"]'] },
 	'array-sparse-d': function(assert){
-		return ['[<empty>,1,<empty>,<empty>,2,<empty>]'] },
+		return ['[,1,,,2,,]'] },
 
 	'object-empty': function(assert){
 		return ['{}', json] },