Built in functions are not intuitive and break on certain types

[madrussa]

https://fx.wtf/getting-started#built-in-functions
Some built in functions map directly to specific types. This is not clear on the documentation and can easily lead to confusion.

Given:

{
    "key2": "value2",
    "key1": "value1",
    "key3": "value3"
}

cat test.json | fx 'sort'

Output:

   sort 
   ^^^^

TypeError: array.sort is not a function
    at sort (/private/var/folders/wl/9j60k7xd3j5_dkk1xq7gyjph0000gn/T/fx-30.1.0.js:140:18)
    at apply (/private/var/folders/wl/9j60k7xd3j5_dkk1xq7gyjph0000gn/T/fx-30.1.0.js:119:42)
    at transform (/private/var/folders/wl/9j60k7xd3j5_dkk1xq7gyjph0000gn/T/fx-30.1.0.js:116:10)
    at runTransforms (/private/var/folders/wl/9j60k7xd3j5_dkk1xq7gyjph0000gn/T/fx-30.1.0.js:53:20)
    at async main (/private/var/folders/wl/9j60k7xd3j5_dkk1xq7gyjph0000gn/T/fx-30.1.0.js:42:7)

It's not intuitive enough that you're attempting to do something silly like sort an object, given the error suggests you're trying to sort on an array array.sort is not a function.

There are a few options in my opinion that can improve this:

1. Update the documentation to make it clear those functions are type bound
2. Produce a human readable error "Error attempting to sort a non array value, path: ."
3. Add sort behaviour to objects, given sort will sort by object value and introduce sortByKey that sorts by key. Although the latter would not be useful on a real array 🤷‍♂️ so it's a bit dubious.

To sort an object by key you can do:

cat test.json | fx -s 'sort' '.[0]'

The addition of built ins is nice and the library as a whole is great. Great job overall :)

[antonmedv]

This makes sense. A better docs for sure. Also sortBy makes sense

[antonmedv]

Done https://fx.wtf

It took me a whole evening) hope somebody can buy me a coffee ;)