chore(sdk): add Json.entries() (#4092)

Closes #3142 *By submitting this pull request, I confirm that my contribution is made under the terms of the [Wing Cloud Contribution License](https://github.com/winglang/wing/blob/main/CONTRIBUTION_LICENSE.md)*.
winglang · Sep 11, 2023 · 1dff110 · 1dff110
1 parent 081d133
commit 1dff110
Show file tree

Hide file tree

Showing 10 changed files with 216 additions and 56 deletions.
diff --git a/docs/docs/03-language-reference.md b/docs/docs/03-language-reference.md
@@ -59,12 +59,12 @@ import TOCInline from '@theme/TOCInline';
 
 #### 1.1.1 Primitive Types
 
-| Name   | Extra information                  |
-| ------ | ---------------------------------- |
-| `void` | represents the absence of a type   |
-| `num`  | represents numbers (doubles)       |
-| `str`  | UTF-16 encoded strings             |
-| `bool` | represents true or false           |
+| Name   | Extra information                |
+| ------ | -------------------------------- |
+| `void` | represents the absence of a type |
+| `num`  | represents numbers (doubles)     |
+| `str`  | UTF-16 encoded strings           |
+| `bool` | represents true or false         |
 
 > ```TS
 > let x = 1;                  // x is a num
@@ -221,23 +221,35 @@ log("${jsonObj.get("boom").get("dude").get("world")}");
 // ERROR: Cannot read properties of undefined (reading 'world')
 ```
 
-To obtain an array of all the keys within a JSON object use the `Json.keys(o)` method. 
+To obtain an array of all the keys, use `Json.keys(o)`:
 
 ```TS
-let j = Json { hello: 123, world: [ 1, 2, 3 ] };
+let j = Json { hello: 123, world: [1, 2, 3] };
 assert(Json.keys(j).at(0) == "hello");
 assert(Json.keys(j).at(1) == "world");
 ```
 
 To obtain an array of all the values, use `Json.values(o)`:
 
 ```TS
-assert(Json.values(j).equals([ Json 123, Json [ 1, 2, 3 ] ]));
+assert(Json.values(j).at(0) == 123);
+assert(Json.values(j).at(1) == [1, 2, 3]);
 ```
 
 > NOTE: `values()` returns an array inside a `Json` object because at the moment we
 > cannot represent heterogenous arrays in Wing.
 
+To obtain an array of all key/value pairs, use `Json.entries(o)`:
+
+```TS
+assert(Json.entries(j).at(0).getAt(0) == "hello");
+assert(Json.entries(j).at(0).getAt(1) == 123);
+assert(Json.entries(j).at(1).getAt(0) == "world");
+assert(Json.entries(j).at(1).getAt(1) == [1, 2, 3]);
+```
+> NOTE: `entries()` returns an array inside a `Json` object because at the moment we
+> cannot represent heterogenous arrays in Wing.
+
 ##### 1.1.4.3 Assignment from native types
 
 It is also possible to assign the native `str`, `num`, `bool` and `Array<T>` values and they will
@@ -424,7 +436,6 @@ my object is: {
 The following features are not yet implemented, but we are planning to add them in the future:
 
 * Array/Set/Map.fromJson() - see https://github.com/winglang/wing/issues/1796 to track.
-* Json.entries() - see https://github.com/winglang/wing/issues/3142 to track.
 * Equality, diff and patch - see https://github.com/winglang/wing/issues/3140 to track.
 
 [`▲ top`][top]
@@ -513,10 +524,10 @@ log("UTC: ${t1.utc.toIso())}");            // output: 2023-02-09T06:21:03.000Z
 
 ### 1.2 Utility Functions
 
-| Name     | Extra information                                        |
-| -------- | -------------------------------------------------------- |
-| `log`    | logs str                                                 |
-| `assert` | checks a condition and _throws_ if evaluated to false    |
+| Name     | Extra information                                     |
+| -------- | ----------------------------------------------------- |
+| `log`    | logs str                                              |
+| `assert` | checks a condition and _throws_ if evaluated to false |
 
 > ```TS
 > log("Hello ${name}");
@@ -1785,7 +1796,7 @@ When calling **extern** function, the parameter and return types are **assumed**
 
 
 | Built-in Wing type        | TypeScript type                                                       |
-|---------------------------|-----------------------------------------------------------------------|
+| ------------------------- | --------------------------------------------------------------------- |
 | `void`                    | `undefined`                                                           |
 | `nil`                     | `null`                                                                |
 | `any`                     | `any`                                                                 |
@@ -1797,12 +1808,12 @@ When calling **extern** function, the parameter and return types are **assumed**
 | `Array<T>`, `MutArray<T>` | `Array<T>`                                                            |
 | `Json`, `MutJson`         | `string ⏐ number ⏐ boolean ⏐ null ⏐ Json[] ⏐ { [key: string]: Json }` |
 
-| User-defined Wing type  | TypeScript type                                                                        |
-|-------------------------|----------------------------------------------------------------------------------------|
-| `class`                 | `class`, only with members whose phase is compatible with the function signature       |
-| `interface`             | `interface`, only with members whose phase is compatible with the function signature   |
-| `struct`                | `interface`                                                                            |
-| `enum`                  | `string`-based enum-like `Object`                                                      |
+| User-defined Wing type | TypeScript type                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| `class`                | `class`, only with members whose phase is compatible with the function signature     |
+| `interface`            | `interface`, only with members whose phase is compatible with the function signature |
+| `struct`               | `interface`                                                                          |
+| `enum`                 | `string`-based enum-like `Object`                                                    |
 
 [`▲ top`][top]
 
@@ -2071,7 +2082,7 @@ Ternary or conditional operators are not supported.
 | Operator             | Notes                                             |
 | -------------------- | ------------------------------------------------- |
 | ()                   | Parentheses                                       |
-| **                   | Power                                    |
+| **                   | Power                                             |
 | -x                   | Unary minus                                       |
 | \*, /, \\, %         | Multiplication, Division, Floor division, Modulus |
 | +, -                 | Addition, Subtraction                             |

diff --git a/docs/docs/04-standard-library/02-std/api-reference.md b/docs/docs/04-standard-library/02-std/api-reference.md
@@ -816,8 +816,9 @@ The index of the element in the Json Array to return.
 | <code><a href="#@winglang/sdk.std.Json.deepCopy">deepCopy</a></code> | Creates an immutable deep copy of the Json. |
 | <code><a href="#@winglang/sdk.std.Json.deepCopyMut">deepCopyMut</a></code> | Creates a mutable deep copy of the Json. |
 | <code><a href="#@winglang/sdk.std.Json.delete">delete</a></code> | Deletes a key in a given Json. |
+| <code><a href="#@winglang/sdk.std.Json.entries">entries</a></code> | Returns the entries from the Json. |
 | <code><a href="#@winglang/sdk.std.Json.has">has</a></code> | Checks if a Json object has a given key. |
-| <code><a href="#@winglang/sdk.std.Json.keys">keys</a></code> | Returns the keys from the Json object. |
+| <code><a href="#@winglang/sdk.std.Json.keys">keys</a></code> | Returns the keys from the Json. |
 | <code><a href="#@winglang/sdk.std.Json.parse">parse</a></code> | Parse a string into a Json. |
 | <code><a href="#@winglang/sdk.std.Json.stringify">stringify</a></code> | Formats Json as string. |
 | <code><a href="#@winglang/sdk.std.Json.tryParse">tryParse</a></code> | Try to parse a string into a Json. |
@@ -881,6 +882,22 @@ the key to delete.
 
 ---
 
+##### `entries` <a name="entries" id="@winglang/sdk.std.Json.entries"></a>
+
+```wing
+Json.entries(json: Json);
+```
+
+Returns the entries from the Json.
+
+###### `json`<sup>Required</sup> <a name="json" id="@winglang/sdk.std.Json.entries.parameter.json"></a>
+
+- *Type:* <a href="#@winglang/sdk.std.Json">Json</a>
+
+map to get the entries from.
+
+---
+
 ##### `has` <a name="has" id="@winglang/sdk.std.Json.has"></a>
 
 ```wing
@@ -911,13 +928,13 @@ The key to check.
 Json.keys(json: any);
 ```
 
-Returns the keys from the Json object.
+Returns the keys from the Json.
 
 ###### `json`<sup>Required</sup> <a name="json" id="@winglang/sdk.std.Json.keys.parameter.json"></a>
 
 - *Type:* any
 
-to get keys from.
+map to get the keys from.
 
 ---
 
@@ -987,7 +1004,7 @@ Returns the values from the Json.
 
 - *Type:* <a href="#@winglang/sdk.std.Json">Json</a>
 
-to get values from.
+map to get the values from.
 
 ---
 

diff --git a/examples/tests/sdk_tests/std/json.w b/examples/tests/sdk_tests/std/json.w
@@ -85,6 +85,23 @@ test "stringify()" {
   assert(stringifiedIndent == "{\n  \"a\": 1,\n  \"b\": 2\n}");
 }
 
+test "keys(), values(), entries()" {
+  let obj = Json { 
+    a: 1,
+    b: [3, 7, 9],
+    c: { foo: "bar" }
+  };
+
+  let entries = Json.entries(obj);
+  let keys = Json.keys(obj);
+  let values = Json.values(obj);
+
+  for i in 0..entries.length {
+    assert(entries.at(i).getAt(0) == keys.at(i));
+    assert(entries.at(i).getAt(1) == values.at(i));
+  }
+}
+
 //-----------------------------------------------------------------------------
 // tryParse()
 assert(Json.tryParse(nil) == nil);

diff --git a/libs/wingc/src/lsp/snapshots/completions/json_statics.snap b/libs/wingc/src/lsp/snapshots/completions/json_statics.snap
@@ -37,6 +37,18 @@ source: libs/wingc/src/lsp/completions.rs
   command:
     title: triggerParameterHints
     command: editor.action.triggerParameterHints
+- label: entries
+  kind: 2
+  detail: "(json: Json): Array<Json>"
+  documentation:
+    kind: markdown
+    value: "```wing\nstatic entries: (json: Json): Array<Json>\n```\n---\nReturns the entries from the Json.\n\n\n### Returns\nthe entries as Array<Json> consisting of enumerable [key, value] pairs"
+  sortText: ff|entries
+  insertText: entries($0)
+  insertTextFormat: 2
+  command:
+    title: triggerParameterHints
+    command: editor.action.triggerParameterHints
 - label: has
   kind: 2
   detail: "(json: Json, key: str): bool"
@@ -54,7 +66,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: any): Array<str>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json object.\n\n\n### Returns\nthe keys from the Json object as string array"
+    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json.\n\n\n### Returns\nthe keys as Array<String>"
   sortText: ff|keys
   insertText: keys($0)
   insertTextFormat: 2
@@ -102,7 +114,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: Json): Array<Json>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values from the Json as array of Json"
+    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values as Array<Json>"
   sortText: ff|values
   insertText: values($0)
   insertTextFormat: 2

diff --git a/libs/wingc/src/lsp/snapshots/completions/static_completions_after_expression.snap b/libs/wingc/src/lsp/snapshots/completions/static_completions_after_expression.snap
@@ -37,6 +37,18 @@ source: libs/wingc/src/lsp/completions.rs
   command:
     title: triggerParameterHints
     command: editor.action.triggerParameterHints
+- label: entries
+  kind: 2
+  detail: "(json: Json): Array<Json>"
+  documentation:
+    kind: markdown
+    value: "```wing\nstatic entries: (json: Json): Array<Json>\n```\n---\nReturns the entries from the Json.\n\n\n### Returns\nthe entries as Array<Json> consisting of enumerable [key, value] pairs"
+  sortText: ff|entries
+  insertText: entries($0)
+  insertTextFormat: 2
+  command:
+    title: triggerParameterHints
+    command: editor.action.triggerParameterHints
 - label: has
   kind: 2
   detail: "(json: Json, key: str): bool"
@@ -54,7 +66,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: any): Array<str>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json object.\n\n\n### Returns\nthe keys from the Json object as string array"
+    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json.\n\n\n### Returns\nthe keys as Array<String>"
   sortText: ff|keys
   insertText: keys($0)
   insertTextFormat: 2
@@ -102,7 +114,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: Json): Array<Json>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values from the Json as array of Json"
+    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values as Array<Json>"
   sortText: ff|values
   insertText: values($0)
   insertTextFormat: 2

diff --git a/libs/wingc/src/lsp/snapshots/completions/static_json_after_expression.snap b/libs/wingc/src/lsp/snapshots/completions/static_json_after_expression.snap
@@ -37,6 +37,18 @@ source: libs/wingc/src/lsp/completions.rs
   command:
     title: triggerParameterHints
     command: editor.action.triggerParameterHints
+- label: entries
+  kind: 2
+  detail: "(json: Json): Array<Json>"
+  documentation:
+    kind: markdown
+    value: "```wing\nstatic entries: (json: Json): Array<Json>\n```\n---\nReturns the entries from the Json.\n\n\n### Returns\nthe entries as Array<Json> consisting of enumerable [key, value] pairs"
+  sortText: ff|entries
+  insertText: entries($0)
+  insertTextFormat: 2
+  command:
+    title: triggerParameterHints
+    command: editor.action.triggerParameterHints
 - label: has
   kind: 2
   detail: "(json: Json, key: str): bool"
@@ -54,7 +66,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: any): Array<str>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json object.\n\n\n### Returns\nthe keys from the Json object as string array"
+    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json.\n\n\n### Returns\nthe keys as Array<String>"
   sortText: ff|keys
   insertText: keys($0)
   insertTextFormat: 2
@@ -102,7 +114,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: Json): Array<Json>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values from the Json as array of Json"
+    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values as Array<Json>"
   sortText: ff|values
   insertText: values($0)
   insertTextFormat: 2

diff --git a/libs/wingc/src/lsp/snapshots/completions/static_json_after_expression_statement.snap b/libs/wingc/src/lsp/snapshots/completions/static_json_after_expression_statement.snap
@@ -37,6 +37,18 @@ source: libs/wingc/src/lsp/completions.rs
   command:
     title: triggerParameterHints
     command: editor.action.triggerParameterHints
+- label: entries
+  kind: 2
+  detail: "(json: Json): Array<Json>"
+  documentation:
+    kind: markdown
+    value: "```wing\nstatic entries: (json: Json): Array<Json>\n```\n---\nReturns the entries from the Json.\n\n\n### Returns\nthe entries as Array<Json> consisting of enumerable [key, value] pairs"
+  sortText: ff|entries
+  insertText: entries($0)
+  insertTextFormat: 2
+  command:
+    title: triggerParameterHints
+    command: editor.action.triggerParameterHints
 - label: has
   kind: 2
   detail: "(json: Json, key: str): bool"
@@ -54,7 +66,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: any): Array<str>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json object.\n\n\n### Returns\nthe keys from the Json object as string array"
+    value: "```wing\nstatic keys: (json: any): Array<str>\n```\n---\nReturns the keys from the Json.\n\n\n### Returns\nthe keys as Array<String>"
   sortText: ff|keys
   insertText: keys($0)
   insertTextFormat: 2
@@ -102,7 +114,7 @@ source: libs/wingc/src/lsp/completions.rs
   detail: "(json: Json): Array<Json>"
   documentation:
     kind: markdown
-    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values from the Json as array of Json"
+    value: "```wing\nstatic values: (json: Json): Array<Json>\n```\n---\nReturns the values from the Json.\n\n\n### Returns\nthe values as Array<Json>"
   sortText: ff|values
   insertText: values($0)
   insertTextFormat: 2