Support JSON.ARRINDEX #486

docs/src/content/docs/commands/JSON.ARRINDEX.md

@@ -0,0 +1,153 @@
+---
+title: JSON.ARRINDEX
+description: The `JSON.ARRINDEX` command in DiceDB searches for the first occurrence of a JSON value in an array.
+---
+
+The JSON.ARRINDEX command in DiceDB provides users with the ability to search for the position of a specific element within a JSON array stored at a specified path in a document identified by a given key. By executing this command, users can efficiently locate the index of an element that matches the provided value, enabling streamlined data access and manipulation.
+
+This functionality is especially useful for developers dealing with large or nested JSON arrays who need to pinpoint the location of particular elements for further processing or validation. With support for specifying paths and flexible querying, JSON.ARRINDEX enhances the capability of managing and navigating complex JSON datasets within DiceDB.
+
+## Syntax
+
+```bash
+JSON.ARRINDEX key path value [start [stop]]
+```
+
+## Parameters
+
+| Parameter | Description                                                | Type    | Required |
+| --------- | -------------------------------------------------------    | ------  | -------- |
+| `key`     | The name of the key holding the JSON document.             | String  | Yes      |
+| `path`    | JSONPath pointing to an array within the JSON document.    | String  | Yes      |
+| `value`   | The value to search for within the array in JSON document. | Mixed   | Yes      |
+| `start`   | Optional index to start the search from. Defaults to 0.    | Integer | No       |
+| `stop`    | Optional index to end the search. Defaults to 0.           | Integer | No       |
+
+
+## Return Values
+
+| Condition                                              | Return Value                                                                                                                   |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------                        |
+| Success                                                | ([]integer) `array of integer replies for each path, the first position in the array of each JSON value that matches the path` |
+| Wrong number of arguments                              | Error: `(error) ERR wrong number of arguments for JSON.ARRINDEX command`                                                       |
+| Key has wrong type                                     | Error: `(error) ERR Existing key has wrong Dice type`                                                                          |
+| Invalid integer arguments                              | Error: `(error) ERR Couldn't parse as integer`                                                                                 |
+| Invalid jsonpath                                       | Error: `(error) ERR Path '<path>' does not exist`                                                                              |
+
+## Behaviour
+
+When the JSON.ARRINDEX command is issued, DiceDB performs the following steps:
+1. It checks if argument count is valid or not. If not, an error is thrown.
+2. It checks for the validity of value, start(optional) and stop(optional) argument passed. If not, an error is thrown.
+3. If the jsonpath passed is invalid, an error is thrown.
+4. It checks the type of value passed corresponding to the key. If it is not appropriate, error is thrown.
+5. For each value matching the path, it checks if the value is JSON array.
+6. If it is JSON array, it finds the first occurrence of the value.
+7. If value is found, it adds to array the index where the value was found. Else, -1 is added.
+8. If it is not JSON array, (nil) is added to resultant array. 
+9. The final array is returned.
+
+## Errors
+
+1. `Wrong number of arguments`:
+
+   - Error Message: `(error) ERR wrong number of arguments for JSON.ARRINDEX command`
+   - Raised if the number of arguments are less or more than expected.
+
+2. `Couldn't parse as integer`:
+
+   - Error Message: `(error) ERR Couldn't parse as integer`
+   - Raised if the optional start and stop argument are non-integer strings. 
+   - Raised if the value is not a valid integer.
+
+3. `Key has wrong Dice type`:
+
+   - Error Message: `(error) ERR Existing key has wrong Dice type`
+   - Raised if the value of the specified key doesn't match the specified value in DiceDb
+
+4. `Path '<path>' does not exist`
+
+	- Error Message: `(error) ERR Path '<path>' does not exist`
+	- Raise if the path passed is not valid.
+
+## Example Usage
+
+### Basic usage
+
+Searches for the first occurrence of a JSON value in an array
+
+```bash
+127.0.0.1:7379> JSON.SET a $ '{"name": "Alice", "age": 30, "mobile": [1902, 1903, 1904]}'
+"OK"
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1903
+1) (integer) 1
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904
+1) (integer) 2
+```
+
+### Finding the occurrence of value starting from given index
+
+Searches for the first occurrence of a JSON value in an array starting from given index
+
+```bash
+127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
+"OK"
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 0
+1) (integer) 0
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 1
+1) (integer) -1
+```
+
+### Finding the occurrence of value starting from given index and ending at given index (exclusive)
+
+Searches for the first occurrence of a JSON value in [start, stop) range
+
+```bash
+127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
+"OK"
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 0 2
+1) (integer) 0
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 1 2
+1) (integer) -1
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904 0 1
+1) (integer) -1
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904 0 2
+1) (integer) -1
+127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904 0 3
+1) (integer) 2
+```
+
+### When invalid start and stop argument is passed
+
+Error When invalid start and stop argument is passed
+
+```bash
+127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
+"OK"
+127.0.0.1:7379> JSON.ARRINDEX b $.mobile iamnotvalidinteger
+(error) ERR Couldn't parse as integer
+127.0.0.1:7379> JSON.ARRINDEX b $.mobile iamnotvalidinteger iamalsonotvalidinteger
+(error) ERR Couldn't parse as integer
+```
+
+### When the jsonpath is not array object
+
+Error When jsonpath is not array object
+
+```bash
+127.0.0.1:7379> set b '{"name":"Alice","mobile":[1902,1903,1904]}'
+"OK"
+127.0.0.1:7379> JSON.ARRINDEX b $.mobile 1902
+(error) Existing key has wrong Redis type
+```
+
+### When the jsonpath is not valid path
+
+Error When jsonpath is not valid path
+
+```bash
+127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
+"OK"
+127.0.0.1:7379> JSON.ARRINDEX b $invalid_path 3
+(error) ERR Path '$invalid_path' does not exist
+```

integration_tests/commands/http/json_test.go

@@ -81,6 +81,8 @@ func runIntegrationTests(t *testing.T, exec *HTTPCommandExecutor, testCases []In
 					// fmt.Println("hi expected : ", out)
 					// fmt.Println("hi actual :", result)
 					assert.JSONEq(t, out.(string), result.(string))
+				case "deep_equal":
+					assert.ElementsMatch(t, result.([]interface{}), out.([]interface{}))
 				}
 			}
 		})
@@ -1789,3 +1791,177 @@ func TestJsonARRTRIM(t *testing.T) {
 	exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "a"}})
 	exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "b"}})
 }
+
+func TestJSONARRINDEX(t *testing.T) {
+	exec := NewHTTPCommandExecutor()
+
+	exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}})
+	defer exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}})
+
+	normalArray  := `[0,1,2,3,4,3]`
+	nestedArray  := `{"arrays":[{"arr":[1,2,3]},{"arr":[2,3,4]},{"arr":[1]}]}`
+	nestedArray2 := `{"a":[3],"nested":{"a":{"b":2,"c":1}}}`
+
+	testCases := []IntegrationTestCase{
+		{
+			name:     "should return array index when given element is present",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "value": 3}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(3)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return -1 when given element is not present",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "value": 10}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(-1)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return array index with start optional param provided",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"3", "4"}}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(5)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return array index with start and stop optional param provided",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"4", "4", "5"}}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(4)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return -1 with start and stop optional param provided where start > stop",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"3", "2", "1"}}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(-1)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return -1 with start (out of boud) and stop (out of bound) optional param provided",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"3", "6", "10"}}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(-1)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return list of array indexes for nested json",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$.arrays.*.arr", "value": 3}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(2), float64(1), float64(-1)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return list of array indexes for multiple json path",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..arr", "value": 3}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(2), float64(1), float64(-1)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return array of length 1 for nested json path, with index",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$.arrays[1].arr", "value": 3}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(1)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return empty array for nonexistent path in nested json",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..arr1", "value": 3}},
+			},
+			expected: []interface{}{"OK", []interface{}{}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return -1 for each nonexisting value in nested json",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..arr", "value": 5}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(-1), float64(-1), float64(-1)}},
+			assertType: []string{"equal", "equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return nil for non-array path and -1 for array path if value DNE",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray2)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..a", "value": 2}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(-1), nil}},
+			assertType: []string{"equal", "deep_equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+		{
+			name:     "should return nil for non-array path if value DNE and valid index for array path if value exists",
+			commands: []HTTPCommand{
+				{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray2)}},
+				{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..a", "value": 3}},
+			},
+			expected: []interface{}{"OK", []interface{}{float64(0), nil}},
+			assertType: []string{"equal", "deep_equal"},
+			cleanUp: []HTTPCommand{
+				{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
+			},
+		},
+	}
+
+	preTestChecksCommand := HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}}
+	postTestChecksCommand := HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}}
+	runIntegrationTests(t, exec, testCases, preTestChecksCommand, postTestChecksCommand)
+}