feat: implement functions reverse, mapObject, mapKeys, mapValues, join, split, number, string

josdejong · josdejong · commit 958a31ed4cc8 · 2024-11-29T16:34:12.000+01:00
diff --git a/README.md b/README.md
@@ -10,8 +10,8 @@ Try it out on the online playground: <https://jsonquerylang.org>
 
 ## Features
 
-- Small: just `3.0 kB` when minified and gzipped! The JSON query engine without parse/stringify is only `1.4 kB`.
-- Feature rich (40+ powerful functions)
+- Small: just `3.2 kB` when minified and gzipped! The JSON query engine without parse/stringify is only `1.7 kB`.
+- Feature rich (50+ powerful functions and operators)
 - Easy to interoperate with thanks to the intermediate JSON format.
 - Expressive
 - Expandable
diff --git a/docs/index.html b/docs/index.html
@@ -115,13 +115,29 @@ <h1>JSON Query</h1>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#sort"
                     target="_blank"><code>sort(property, direction)</code></a>
                 </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#reverse"
+                    target="_blank"><code>reverse()</code></a>
+                </li>
                 <li>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#pick"
                     target="_blank"><code>pick(property1, property2, ...)</code></a>
                 </li>
                 <li>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#map"
-                    target="_blank"><code>map(query)</code></a>
+                    target="_blank"><code>map(callback)</code></a>
+                </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#mapObject"
+                    target="_blank"><code>mapObject(callback)</code></a>
+                </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#mapKeys"
+                    target="_blank"><code>mapKeys(callback)</code></a>
+                </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#mapValues"
+                    target="_blank"><code>mapValues(callback)</code></a>
                 </li>
                 <li>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#pipe"
@@ -155,6 +171,14 @@ <h1>JSON Query</h1>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#flatten"
                     target="_blank"><code>flatten()</code></a>
                 </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#join"
+                    target="_blank"><code>join(separator)</code></a>
+                </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#split"
+                    target="_blank"><code>split(separator)</code></a>
+                </li>
                 <li>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#uniq"
                     target="_blank"><code>uniq()</code></a>
@@ -218,6 +242,14 @@ <h1>JSON Query</h1>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#abs"
                      target="_blank"><code>abs(value)</code></a>
                 </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#number"
+                     target="_blank"><code>number(text)</code></a>
+                </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#string"
+                     target="_blank"><code>string(number)</code></a>
+                </li>
               </ul>
             </div>
           </details>
diff --git a/reference/functions.md b/reference/functions.md
@@ -217,6 +217,22 @@ jsonquery(values, 'sort()') // [2, 7, 9]
 jsonquery(values, 'sort(get(), "desc")') // [9, 7, 2]
 ```
 
+## reverse
+
+Create a new array with the items in reverse order.
+
+```text
+reverse()
+```
+
+Example: 
+
+```js
+const data = [1, 2, 3]
+jsonquery(data, 'reverse()')
+// [3, 2, 1]
+```
+
 ## pick
 
 Pick one or multiple properties or paths, and create a new, flat object for each of them. Can be used on both an object or an array.
@@ -255,10 +271,10 @@ jsonquery(item, 'pick(.price)') // 25
 
 ## map
 
-Map over an array and apply the provided query to each of the items in the array.
+Map over an array and apply the provided callback query to each of the items in the array.
 
 ```text
-map(query)
+map(callback)
 ```
 
 Examples:
@@ -288,6 +304,60 @@ jsonquery(data, 'map(.price * .quantity)')
 // 8.6
 ```
 
+## mapObject
+
+Map over an object, and create a new object with the entry `{ key, value }` returned by the callback for every input entry.
+
+```text
+mapObject(callback)
+```
+
+Example:
+
+```js
+const data = { "a": 2, "b": 3 }
+jsonquery(data, `mapObject({
+  key: (.key + " times two"),
+  value: (.value * 2)
+})`)
+// {
+//   "a times two": 4,
+//   "b times two": 6
+// }
+```
+
+## mapKeys
+
+Map over an object, and create a new object with the keys returned by the callback having the value of the original key.
+
+```text
+mapKeys(callback)
+```
+
+Example:
+
+```js
+const data = { "a": 2, "b": 3 }
+jsonquery(data, 'mapKeys("#" + get())')
+// { "#a": 2, "#b": 3 }
+```
+
+## mapValues
+
+Map over an object, and create a new object with the values updated by the return value of callback.
+
+```text
+mapValues(callback)
+```
+
+Example:
+
+```js
+const data = { "a": 2, "b": 3 }
+jsonquery(data, 'mapValues(get() * 2)')
+// { "a": 4, "b": 6 }
+```
+
 ## groupBy
 
 Group a list with objects grouped by the value of given path. This creates an object with the different properties as key, and an array with all items having that property as value.
@@ -416,6 +486,45 @@ const data2 = [[1, 2, [3, 4]]]
 jsonquery(data2, 'flatten()') // [1, 2, [3, 4]]
 ```
 
+## join
+
+Concatenate array items into a string with an optional separator.
+
+```text
+join()
+join(separator)
+```
+
+Example:
+
+```js
+const data = [
+  { "name": "Chris", "age": 16 },
+  { "name": "Emily", "age": 32 },
+  { "name": "Joe", "age": 18 }
+]
+
+jsonquery(data, 'map(.name) | join(", ")')
+// "Chris, Emily, Joe"
+```
+
+## split
+
+Divide a string into an array substrings, separated by a separator.
+
+```text
+split()
+split(separator)
+```
+
+Example:
+
+```js
+const data = "hi there how are you doing?"
+jsonquery(data, 'split(" ")')
+// ["hi", "there", "how", "are", "you", "doing?"]
+```
+
 ## uniq
 
 Create a copy of an array where all duplicates are removed.
@@ -479,7 +588,7 @@ jsonquery(data, 'limit(4)') // [1, 2, 3, 4]
 
 ## size
 
-Return the size of an array.
+Return the size of an array or the length of a string.
 
 ```text
 size()
@@ -490,6 +599,7 @@ Examples:
 ```js
 jsonquery([1, 2], 'size()') // 2
 jsonquery([1, 2, 3, 4], 'size()') // 4
+jsonquery("hello", 'size()') // 5
 ```
 
 ## sum
@@ -951,6 +1061,13 @@ Examples:
 const data = { "a": 6, "b": 2 }
 
 jsonquery(data, '.a + .b') // 8
+
+const user = {
+  "firstName": "José",
+  "lastName": "Carioca"
+}
+jsonquery(user, '(.firstName + " ") + .lastName')
+// "José Carioca"
 ```
 
 ## subtract (`-`)
@@ -1069,3 +1186,34 @@ jsonquery({"a": 23.1345 }, 'round(.a)') // 23
 jsonquery({"a": 23.1345 }, 'round(.a, 2)') // 23.13
 jsonquery({"a": 23.1345 }, 'round(.a, 3)') // 23.135
 ```
+
+## number
+
+Parse the numeric value in a string into a number.
+
+```text
+number(text)
+```
+
+Examples:
+
+```js
+jsonquery({"value": "2.4" }, 'number(.value)') // 2.4
+jsonquery("-4e3", 'number(get())') // -4000
+jsonquery("2,7,1", 'split(",") | map(number(get()))') // [2, 7, 1]
+```
+
+## string
+
+Format a number as a string.
+
+```text
+string(number)
+```
+
+Examples:
+
+```js
+jsonquery({"value": 2.4 }, 'string(.value)') // "2.4"
+jsonquery(42, 'string(get())') // "42"
+```
diff --git a/src/functions.ts b/src/functions.ts
@@ -1,6 +1,7 @@
 import { compile } from './compile'
 import { isArray } from './is'
 import type {
+  Entry,
   FunctionBuilder,
   FunctionBuildersMap,
   Getter,
@@ -78,6 +79,44 @@ export const functions: FunctionBuildersMap = {
     return (data: T[]) => data.map(_callback)
   },
 
+  mapObject: <T, U>(callback: JSONQuery) => {
+    const _callback = compile(callback)
+
+    return (data: Record<string, T>) => {
+      const output = {}
+      for (const key of Object.keys(data)) {
+        const updated = _callback({ key, value: data[key] }) as Entry<U>
+        output[updated.key] = updated.value
+      }
+      return output
+    }
+  },
+
+  mapKeys: <T>(callback: JSONQuery) => {
+    const _callback = compile(callback)
+
+    return (data: Record<string, T>) => {
+      const output = {}
+      for (const key of Object.keys(data)) {
+        const updatedKey = _callback(key) as string
+        output[updatedKey] = data[key]
+      }
+      return output
+    }
+  },
+
+  mapValues: <T>(callback: JSONQuery) => {
+    const _callback = compile(callback)
+
+    return (data: Record<string, T>) => {
+      const output = {}
+      for (const key of Object.keys(data)) {
+        output[key] = _callback(data[key])
+      }
+      return output
+    }
+  },
+
   filter: <T>(predicate: JSONQuery[]) => {
     const _predicate = compile(predicate)
 
@@ -97,6 +136,11 @@ export const functions: FunctionBuildersMap = {
     return (data: T[]) => data.slice().sort(compare)
   },
 
+  reverse:
+    <T>() =>
+    (data: T[]) =>
+      data.toReversed(),
+
   pick: (...properties: JSONQueryProperty[]) => {
     const getters = properties.map(
       ([_get, ...path]) => [path[path.length - 1], functions.get(...path)] as Getter
@@ -157,6 +201,18 @@ export const functions: FunctionBuildersMap = {
 
   flatten: () => (data: unknown[]) => data.flat(),
 
+  join:
+    <T>(separator = '') =>
+    (data: T[]) =>
+      data.join(separator),
+
+  split:
+    (separator = '') =>
+    (data: string) =>
+      data.split(separator as string),
+
+  substring: (start: number, end: number) => (data: string) => data.slice(Math.max(start, 0), end),
+
   uniq:
     () =>
     <T>(data: T[]) => [...new Set(data)],
@@ -246,7 +302,13 @@ export const functions: FunctionBuildersMap = {
   round: buildFunction((value: number, digits = 0) => {
     const num = Math.round(Number(`${value}e${digits}`))
     return Number(`${num}e${-digits}`)
-  })
+  }),
+
+  number: buildFunction((text: string) => {
+    const num = Number(text)
+    return Number.isNaN(Number(text)) ? null : num
+  }),
+  string: buildFunction(String)
 }
 
 const truthy = (x: unknown) => x !== null && x !== 0 && x !== false
diff --git a/src/types.ts b/src/types.ts
@@ -32,3 +32,8 @@ export type Fun = (data: unknown) => unknown
 export type FunctionBuilder = (...args: JSONQuery[]) => Fun
 export type FunctionBuildersMap = Record<string, FunctionBuilder>
 export type Getter = [key: string, Fun]
+
+export interface Entry<T> {
+  key: string
+  value: T
+}
diff --git a/test-suite/compile.test.json b/test-suite/compile.test.json
