ig-serialize 1.3.0 → 1.3.2

package/README.md

@@ -5,13 +5,12 @@ This extends the default JSON serialization adding the following:
 - Sparse array serialization
 - `undefined`/`NaN` serialization
 - Serialization of `Infinity`, `BigInt`'s, `Set`'s, `Map`'s
-- Function serialization (off by default)
+- Function serialization
 - 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.
-
+Data not stored:
+- Attributes on arrays, maps, sets, and functions,
+- Function closures.
 
 
 ## Motivation
@@ -30,16 +29,53 @@ For basic use:
 $ npm install ig-serilaize
 ```
 
-Or just download and drop [serialize.js](serialize.js) into your code.
+Or just download and drop [serialize.js](./serialize.js) into your code.
 
 
 ```javascript
-serialize = require('ig-serialize')
+var serialize = require('ig-serialize')
 ```
 
 
 ## Introduction
 
+`serialize.js` provides two toolsets:
+
+1. A means to serialize and deserialize complex data structures into an
+   extended JSON format.  
+   ```javascript
+   var obj = {
+   	sparse_array: [,,,,1],
+	bad_number: NaN,
+	really_large_number: 99999999999999999999999n,
+   }
+   obj.recursive = obj
+   obj.re_reference = obj.sparse_array
+   
+   var str = serialize(obj)
+   
+   // ...
+   
+   var copy = deserialize(str)
+   ```
+   This is useful when requiering serialization of data structures more 
+   complex than pure JSON can handle.
+2. A means to cleanly copy deep data structures with guaranteed isolation.  
+   ```javascript
+   var obj = {
+   	// ...
+   }
+   
+   var copy = deepCopy(obj)
+   ```
+
+### Long strings and large `BigInt`'s
+
+Repeating strings and `BigInt`'s longer that `MIN_LENGTH_REF` are stored 
+by reference by default.
+
+See: [`MIN_LENGTH_REF`](#min_length_ref--optionsmin_length_ref) 
+
 
 ### Serializing functions
 
@@ -58,6 +94,12 @@ Thus, care must be taken when serializing structures containing function.
 
 ## API
 
+### `eJSON`
+
+An `JSON`-api-compatible object providing [`.stringify(..)`](#serialize--ejsonstringify) and [`.parse(..)`](#deserialize--ejsonparse)
+static methods.
+
+
 ### `serialize(..)` / `eJSON.stringify(..)`
 
 Serialize a JavaScript value into a JSON/eJSON string.
@@ -147,23 +189,38 @@ eJSON.parse(<string>, {functions: <functions>})
 
 ### `deepCopy(..)`
 
+Deep-copy an object.
+
 ```
 deepCopy(<value>)
 	-> <value>
 ```
 
+The returned object is a fully sanitized through serialization clean copy.
+
 
 ### `partialDeepCopy(..)`
 
+Partially deep-copy and object, retaining only references to functions.
+
 ```
 partialDeepCopy(<value>)
 	-> <value>
 ```
 
+The returned object is a partially sanitized through serialization clean 
+copy with function references copied as-is from the input retaining and
+"transferring" all associated function state like attributes and closures.
+
+Note that this is by definition a _controlled state leak_ from input 
+object to copy, so care must be taken to _control_ object-specific state 
+in function closures and attributes -- keeping function state independent 
+from object state is _in general_ a good practice.
+
 
 ### `MIN_LENGTH_REF` / `<options>.min_length_ref` 
 
-Defines the default minimum length of repeating string or bin-int to 
+Defines the default minimum length of repeating string or `BigInt`'s to 
 include as a reference in the output.
 
 If set to `0`, referencing will be disabled.
@@ -171,9 +228,6 @@ If set to `0`, referencing will be disabled.
 Default: 96  
 
 
-### `DEBUG`
-
-
 
 ## Format
 
@@ -186,32 +240,34 @@ while the input format is a bit more relaxed than in several details.
 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 
+A path is an array of keys, the semantics of each key depend 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.
+- `Array` expects a number
+- `Set` expects a number -- item order in set
+- `Map` expects pair of consecutive numbers -- the first indicates item 
+  order the second if `0` selects the key, if `1` selects the value.
+- `Object` expects a string
 
 An empty path indicates the root object.
 
 
+Notes:
+- String path items are unambiguous and are always treated as attributes.  
+  This enables referencing of attributes of any object like arrays, maps, ...etc.
+- Map/set paths are structured as if sets and maps are represented by 
+  arrays structured as their respective constructors expect as input.
+
+
 ### Referencing 
 
 If an object is encountered for a second time it will be serialized as 
 a reference by path to the first occurrence.
 
-Format:
+Grammar:
 ```bnf
 <ref> ::= 
-	'<REF' <path> '>'
-	
-<path> ::= 
-	'[' <path-items> ']'
+	'<REF[]>'
+	| '<REF[' <path-items> ']> 
 	
 <path-items> ::=
 	<item>
@@ -260,7 +316,7 @@ serialize([null, undefined, NaN]) // -> '[null,undefined,NaN]'
 ### Sparse arrays
 
 Sparse arrays are represented in the same way JavaScript handles them 
-syntactically.
+syntactically -- with commas separating empty "positions".
 
 Example:
 ```javascript
@@ -268,29 +324,111 @@ serialize([,]) // -> '[,]'
 serialize([,,]) // -> '[,,]'
 ```
 
-Note that trailing commas are ignored in the same way JavaScript ignores 
-them:
+Trailing commas are handled in the same way JavaScript handles them:
 ```javascript
-// trailing comma...
+// trailing commas are ignored...
 serialize([1,]) // -> '[1]'
 
 // sparse element...
 serialize([1,,]) // -> '[1,,]'
 ```
 
+
 ### BigInt
 
+Serialized as represented in JavaScript.
+
+```javascript
+serialize(9999999999n) // -> '9999999999n'
+```
+
+
 ### Infinity
 
+Serialized as represented in JavaScript
+
+```javascript
+serialize(Infinity) // -> 'Infinity'
+serialize(-Infinity) // -> '-Infinity'
+```
+
+
 ### Map / Set
 
+Maps and sets are stored in the same format as their respective constructor 
+calls, dropping the `new` keyword:
+
+Grammar:
+```bnf
+<map> ::=
+	'Map([])
+	| 'Map([' <map-items> '])
+
+<map-items> ::=
+	<map-item>
+	| <map-item> ',' <map-items> 
+
+<map-item> ::=
+	'[' <value> ',' <value> ']'
+```
+
+```bnf
+<set> ::=
+	'Set([])
+	| 'Set([' <set-items> '])
+
+<set-items> ::=
+	<value>
+	| <value> ',' <set-items> 
+```
+
+Examples:
+```javascript
+serialize(new Set([1,2,3])) // -> 'Set([1,2,3])'
+serialize(new Map([['a', 1], ['b', 2]])) // -> 'Map([["a",1],["b",2]])'
+```
+
+
 ### Functions
 
+A function can be stored in one of two ways:
+1. As code (default)
+2. As a function index, if an array to store function references is given. 
+
+Grammar:
+```bnf
+<func> ::=
+	'<FUNC[' <length> ',(' <func-spec> ')]>
+
+<func-spec> ::=
+	<code>
+	| <index>
+
+<length> ::= <number>
+
+<index> ::= <number>
+```
+
+`<length>` is the length of the next block in chars, including the braces.
+
+
+```javascript
+serialize(function(){}) // -> '<FUNC[14,(function(){})]>'
+
+var functions = []
+serialize(function(){}, {functions}) // -> '<FUNC[3,(0)]>'
+```
+
+Note that deserializing functions is disabled by default as it can pose 
+a security risk if the input to `deserialize(..)` is not trusted.
+(see: [`deserialize(..)`](#deserialize--ejsonparse))
 
 
 
 ## Running tests
 
+`serialize.js` uses ['test.js'](/flynx/test.js) for testing.
+
 Get the development dependencies:
 ```shell
 $ npm install -D
@@ -303,10 +441,22 @@ $ npm test
 
 To run the tests directly:
 ```shell
-$ node ./test.js
+$ ./test.js
+```
+
+To run the tests with modifier chains of length 3:
+```shell
+$ ./test.js -m 3
 ```
 
 
 
+## License
+
+[BSD 3-Clause License](./LICENSE)
+
+Copyright (c) 2014-2026, Alex A. Naanou,  
+All rights reserved.
+
 
 <!-- vim:set nowrap : -->

package/package.json

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

package/serialize.js

@@ -54,7 +54,6 @@
 /*********************************************************************/
 
 
-var EMPTY = '<empty>'
 var NULL = 'null'
 var UNDEFINED = 'undefined'
 var NAN = 'NaN'
@@ -334,7 +333,6 @@ module.eJSON = {
 		undefined: undefined,
 		NaN: NaN,
 
-		'<empty>': 'empty',
 		'<REF': 'reference',
 
 		'<FUNC[': 'func',
@@ -558,15 +556,6 @@ module.eJSON = {
 				initial instanceof Array
 					&& initial.length++
 				continue }
-			if(str.slice(i, i+EMPTY.length) == EMPTY){
-				index++
-				i += EMPTY.length
-				if(str[i] == ','){
-					i++ }
-				// XXX this feels hackish -- can this be deligated to the handler???
-				initial instanceof Array
-					&& initial.length++
-				continue }
 
 			// end of input...
 			if(i >= str.length-1){
@@ -782,7 +771,7 @@ function(str, options){
 
 var deepCopy =
 module.deepCopy =
-function(obj, funcs){
+function(obj, funcs=true){
 	var options = {functions: funcs}
 	return deserialize(
 		serialize(obj, null, 0, options), 
@@ -792,10 +781,7 @@ function(obj, funcs){
 var partialDeepCopy =
 module.partialDeepCopy =
 function(obj, funcs=[]){
-	var options = {functions: funcs}
-	return deserialize(
-		serialize(obj, null, 0, options), 
-		options) }
+	return deepCopy(obj, funcs) }
 
 
 

package/test.js

@@ -228,11 +228,6 @@ test.Cases({
 
 		// arrays...
 		['[1,2,]', '[1,2]'],
-
-		// sparse arrays...
-		['[,]', '[<empty>]'],
-		['[1,2,,]', '[1,2,<empty>]'],
-		['[1,2,<empty>,]', '[1,2,<empty>]'],
 	],
 	'syntax-simplifications': function(assert){
 		var aa, bb