Allow Mapping Block json() util to take arguments

[gsambrotta]

Improve mapping json() utility function so that can take arguments.
This is done in order to render a prettified JSON output as user needs to copy and paste it.

DONE:

• allow json() to accept args
• write unit test for json()
• update documentation about json(), qs() and jsonParse() so is clear the difference.

json(data) BEFORE:

json(data, null, 2) AFTER - using args:

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
kendraio-app	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 29, 2025 4:17pm

[lukestanley]

Hi Gio, I thought we agreed that we didn't need this because we have existing Block functionality that's sufficient to do the same behaviour?

[CodeKrakken]

That's all good, code is clear and all tests passing. Nice!

[gsambrotta]

Hello @lukestanley, I think you are talking about JSON.parse which we discussed in this PR #534. We agreed that even if we already have a block for parsing, it was a good idea to have it in mapping utility too so we merged that PR already.

This is about making a value a string.
Right now we have two utilities to transform a value into a string.
The first one is qs() and the second one is json()
Looking at the code, they are basically using the same code:

import {parse as parseQueryString, stringify as asQueryString} from 'qs';

  qs: {
    _func: ([o]) => asQueryString(o),
    _signature: [{types: [TYPE_OBJECT]}]
  },
  
  json: {
    _func: ([v]) => stringify(v),
    _signature: [{types: [TYPE_ANY]}]
  },

As you can see they are both using qs package and actually they are both using the same stringify method form qs.
qs is a library specifically to transform values in query string.
Kendraio qs helps us to transform object in query string, json help us to transform value to string. Both of them are focus on transforming for query strings for URLs. For this reason, none of the two have the capacity to format the outputted string, which is instead pretty straight forward with the native methods of JSON, JSON.stringify.
On top of that, using qs module does other stuff behind the scenes like: Sending application/x-www-form-urlencoded requests and sanitize the value which we don't need if we simply want a value to be a stirng.

I personally find the name json and the function json misleading and a bit useless. I would have prefer to replace it with

  jsonStringify: {
   _func: ([value, replacer = null, space = 2]) => JSON.stringify(value, replacer, space),
   _signature: [
     { types: [TYPE_OBJECT, TYPE_ARRAY, TYPE_ANY] },  // value
     { optional: true, types: [TYPE_NULL, TYPE_ARRAY] }, // replacer
     { optional: true, types: [TYPE_NUMBER, TYPE_STRING] }              // space
   ]
 },

But it will break a lot of Flows if I do that, so I just introduce a new utility and changed the documentation to explained better what json() utils does.

I will now update the Issue Description so hopefully is clearer.

[lukestanley]

@gsambrotta Thanks for disambiguation from jsonParse, I don't recall agreeing, but I see that you merged it to develop. I wasn't quite sure what the motivation for it was. This feels very similar but a different direction.

Looking at your snippet and explanation, are you sure that is correct?
Surely the 'as' in the import does a rename to avoid clashing with a different stringify function from json-stringify-safe, which is not related to query strings?

Is this blocking any Flow work?

I don't see an attached GitHub issue.

Is there an agreed problem this Pull aimed at solving?

I think we need to get better at having issues to scope the work we do.

[lukestanley]

It's not clear that this is a useful, well scoped change that solves a real problem.

[gsambrotta]

Hey @lukestanley thanks for you feedback. Here are some answers:

@gsambrotta Thanks for disambiguation from jsonParse, I don't recall agreeing, but I see that you merged it to develop. I wasn't quite sure what the motivation for it was. This feels very similar but a different direction.

When I was doing the PRs cleaning, I decided to merge it (as it was approved and green). To be completely honest, I have asked for your review several times on that PR, on github and on slack. Maybe you were busy, anyway it was nothing harmful, on the contrary i felt it is an improvement.

Looking at your snippet and explanation, are you sure that is correct? Surely the 'as' in the import does a rename to avoid clashing with a different stringify function from json-stringify-safe, which is not related to query strings?

As I posted above the import rename stringify as asQueryString from 'qs'. In one function we are using asQueryString and in the other we use stringify. I did my research and this is what I discover. Am I sure is correct? to the extend of my research it is. If you want to give input on what else to research I might look more, so far I am satisfy with my findings and I feel it makes sense.

Is this blocking any Flow work?
I need to ask Daniel. Probably not blocking but it will be really nice to have.

I don't see an attached GitHub issue.
No issue, i was working on a Flow and I encounter this problem so I created a solution

Is there an agreed problem this Pull aimed at solving?
Outputting a value as JSON FORMATTED

I think we need to get better at having issues to scope the work we do.

[gsambrotta]

@lukestanley I have updated the code and the PR description as agreed in the meeting.
Let me know if you see any issues.

[lukestanley]

I think a test for the existing functionality would be good, not just the new behaviour.
We noticed in the meeting that it isn't branching off from main yet but not many files are touched so it should be straight forward to reapply.
I'm not quite sure the document change makes sense yet.