`$map` does not return an array for input arrays of length 1

[vecerek]

According to the docs, $map should return an array. However, if the input data is an array containing exactly one element, it returns the value returned by the function passed to $map as the second argument.

Reproduction: https://try.jsonata.org/hW13DjVzw

In case the link stops working at some point in the future, here is the inlined version of the reproduction steps:

Data

[{ "a": 1 }]

Jsonata

$map($, function($el) {
  { "a": $el.a + 1 }
})

Expected output

[{ "a": 2 }]

Actual output

{ "a": 2 }

[vecerek]

Temporary workaround for people struggling with this in production:

(
  $correctMap := function($data, $callback) {(
    $res := $map($data, $callback);

    $type($res) = "array" ? $res : [$res]
  )};

  $correctMap($, function($el) {
    { "a": $el.a + 1 }
  })
)

Playground link: https://try.jsonata.org/sa2yM0nj8

[vecerek]

Another thing I noticed, if the input array is empty, the result is ** no match ** instead of an empty array. Are my expectations simply wrong here? The way I interpret:

Returns an array containing the results of applying the function parameter to each value in the array parameter.

from the docs is that the function returns an array in all cases, not just sometimes.

Playground link: https://try.jsonata.org/pkveSyNDj

[elviejo79]

I think your intuitions are correct.
$map should return an array in all case:

empty array -> empty array
1 element array -> 1 element array
n element array -> n element array

[netomi]

I also stumbled upon this weird behavior. Adding an array constructor at the end like $map([1], ...)[] solves it however when using the map together with a chain operator it currently does not work even with the workaround.

I created a PR to fix that also in this case to be able to use the workaround: #714

However I would like to note that the current behavior of map is not what you would expect and thus it can not really be used. The workaround for me is to use a lambda function that iterates over the elements of an array instead of using the built-in function map which should do the same.

If this behavior is wanted, you could add an additional built-in function to return a singleton if explicitly requested, but not do that be default imho.

[vecerek]

This is also an interesting behavior. However, I'm not sure if it's directly related to this bug or it should be reported separately.

[
  $map($, function($el) {
    { "a": $el.a + 1 }
  })
]

Example 1

Input

[{ "a": 1 }]

Expected output

[[{ "a": 2 }]]

Actual output

[{ "a": 2 }]

Example 2

Input

[{ "a": 1 }, { "a": 2 }]

Expected output

[[{ "a": 2 }, { "a": 3 }]]

Actual output

[{ "a": 2 }, { "a": 3 }]

[vecerek]

There might be existing code out there in production that relies on these exact behaviors. If these bugs are fixed, I believe it should be versioned as a breaking change. What do you think @mattbaileyuk?

[AndrewLipscomb]

This issue has a lot of history as seen in #462

But at the very least the docs need to reflect the current behaviour

https://docs.jsonata.org/higher-order-functions#map

Returns an array containing the results of applying the function parameter to each value in the array parameter.

Regardless of whether this behaviour is intentional or desired - it needs documentation. This is a footgun for everyone reading that and expecting an array output in all cases.

FWIW - AI tools training on the docs and outputting information on this topic insist $map outputs an array in all cases. For people like myself who have to come in, write 30 lines of JSONata to do a one-off job, and then move on - this omission turns a 30 sec job into a half day job.

[AndrewLipscomb]

Made #753 to at least try to deal with the docs side of the issue.