deepsortobj

deepsortobj
===========

Deep-copy an object, with keys sorted. Supports circular references and custom
sort order.

Beware! JS object key order rules
---------------------------------

It's a mess. Detailed discussions on StackOverflow:
[here][stofl-1], [here][stofl-2], [here][stofl-3], [here][stofl-4].

The gist of it: The spec gives some guarantees in some cases but they
sound too complicated for me to memorize them.
However, most JS engines (test yours)
keep a tradition that results in:

* Keys that look like they could have been created by
array operations (i.e. integers 0 ≤ n ≤ 4294967294 = 2^31-2
in default notation) always go first.
* Next up are all other string-y keys, in the order they were added.
* … and thus, the numsLast code shipped in deepsortobj up to v0.1.1
was totally ineffective, besides being wrong. Starting from v0.1.2,
the keyPrefix/keySuffix hack might help in some cases.

API
---

$3

The module exports this function.

Returns a sorted deep copy of obj.

how can be a function or an options object.
If it's a function, it's treated as the sort option.
Supported options, all optional:

* isArray: How to decide whether to copy an object as an
Array (with ascending indexes)
or as a dictionary object, with keys sorted.
Supported values:
* undefined (default): Use Array.isArray
* false: Always sort.
* any function: Should accept the object as its first argument and return
the decision as boolean.
All other arguments should be ignored because I haven't decided them yet.

* dictKeys: How to enumerate a dictionary's keys.
Supported values:
* undefined (default): Use sortObj.dictKeys
* any function: The function should accept the object as its first
argument and return either false (if the object is not a dictionary)
or an Array of its keys.

* sortKeys: Determine which keys to copy from a dictionary,
and in which order. Supported values:
* undefined (default) or true: Use sortObj.numsLast
* false: Don't modify the input array.
* "fast": Just use the input array's .sort() with no arguments.
* any function: The function should accept an array of keys as its first
argument and must return an array of keys.

* keyPrefix and keySuffix:
On the result side (i.e. after sortKeys), wrap each key with these
(default: empty) strings. You can use this to nullify the built-in
priority of some number-like keys (see warning above).

* circular: How to deal with circular references. Supported values:
* undefined (default) or "congruent":
Try to maintain the structure by putting a reference to the sorted
version of the object. (Deprecated alias: "copy")
* "ign": Disable checking for CR.
This should speed up stringification of non-circular objects,
at the risk of running into infinite recursion if obj
does contain a CR.
* "err": Throw an exception when a CR is encountered.
The exception thrown will be, or inherit from, an Error object, and it
will have a circRef property with a value other than undefined.
* any function: Put the function's result instead of the CR. The function
should ignore all arguments because I haven't decided them yet.

$3

keys must be an array of strings.
.numsLast returns a copy of keys, sorted in order
"texts first, integers last, both ascending",
where "integer" is defined as

``javascript
intRgx = /^0$|^-?[1-9][0-9]*$/;
`


and a "text" is any string that's not an integer.

$3

If x is deemed some kind of dictionary,
return them as an Array, else return false.
Currently, x is considered a dictionary if it is an object but none of these:

* Array
* Buffer
* (Future versions might exclude more types, like typed arrays.)


Usage
-----

From test/usage.demo.js:



`javascript
var sortObj = require('deepsortobj'), pets = {
dog: { sounds: [ 'woof' ], colors: [ 'grey', 'white' ] },
cat: { colors: [ 'white', 'orange' ], sounds: [ 'meow', 'purr' ] },
ant: { colors: [ 'red', 'black' ], canRideOn: [ 'tree leaf' ] },
};
pets.ant.canRideOn.push(pets.dog);
pets.dog.favoritePassenger = pets.ant;
console.dir(sortObj(pets), { depth: 23 });
`


Output:



`javascript
{ ant:
{ canRideOn:
[ 'tree leaf',
{ colors: [ 'grey', 'white' ],
favoritePassenger: [Circular],
sounds: [ 'woof' ] } ],
colors: [ 'red', 'black' ] },
cat: { colors: [ 'white', 'orange' ], sounds: [ 'meow', 'purr' ] },
dog:
{ colors: [ 'grey', 'white' ],
favoritePassenger:
{ canRideOn: [ 'tree leaf', [Circular] ],
colors: [ 'red', 'black' ] },
sounds: [ 'woof' ] } }
``

Known issues
------------

* Needs more tests.

Related projects
----------------

* sortedjson
and lots of other "sorted json" modules
* sorted-object
* sort-keys
* sort-object

[stofl-1]: https://stackoverflow.com/a/23202095
[stofl-2]: https://stackoverflow.com/a/30076219
[stofl-3]: https://stackoverflow.com/a/33049762
[stofl-4]: https://stackoverflow.com/a/38218582

License
-------

ISC