Method syntax and chaining (#763)

Co-authored-by: Obinna Ekwuno <[email protected]>

doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/closures.mdx

@@ -11,26 +11,26 @@ import Since from '@site/src/components/Since'
 <Since v="v2.0.0" />
 
 ```surql title="SurrealQL Syntax"
-LET $@parameter = |@parameters| @expression;
+$@parameter = |@parameters| @expression;
 ```
 
-One of the powerful features now available in SurrealDB is the ability to define anonymous functions using the [`LET` statement](/docs/surrealdb/surrealql/statements/let). These functions can be used to encapsulate reusable logic and can be called from within your queries. Below are various examples demonstrating their capabilities:
+One of the powerful features now available in SurrealDB is the ability to define anonymous functions. These functions can be used to encapsulate reusable logic and can be called from within your queries. Below are some examples demonstrating their capabilities:
 
 ## Basic Function Definitions
 
 ```surql
 -- Define an anonymous function that doubles a number
-LET $double = |$n: number| $n * 2;
+$double = |$n: number| $n * 2;
 RETURN $double(2);  -- Returns 4
 
 -- Define a function that concatenates two strings
-LET $concat = |$a: string, $b: string| $a + $b;
+$concat = |$a: string, $b: string| $a + $b;
 RETURN $concat("Hello, ", "World!");  -- Returns "Hello, World!"
 ```
 
 ```surql
--- Define a function with a default parameter
-LET $greet = |$name: string| -> string { "Hello, " + $name + "!" };
+-- Define a function that greets a person
+$greet = |$name: string| -> string { "Hello, " + $name + "!" };
 RETURN $greet("Alice");   -- Returns "Hello, Alice!"
 ```
 
@@ -40,12 +40,12 @@ You can also enforce type constraints within your functions to prevent type mism
 
 ```surql
 -- Define a function with a return type
-LET $to_upper = |$text: string| -> string { string::uppercase($text) };
+$to_upper = |$text: string| -> string { string::uppercase($text) };
 RETURN $to_upper("hello");  -- Returns "HELLO"
 RETURN $to_upper(123);      -- Error: type mismatch
 
 -- Define a function that accepts only numbers
-LET $square = |$num: number| $num * $num;
+$square = |$num: number| $num * $num;
 RETURN $square(4);    -- Returns 16
 RETURN $square("4");  -- Error: type mismatch
 ```

doc-surrealdb_versioned_docs/version-latest/surrealql/functions/database/array.mdx

@@ -200,6 +200,7 @@ The `array::add` function adds an item to an array only if it doesn't exist.
 ```surql title="API DEFINITION"
 array::add(array, value) -> array
 ```
+
 The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
 
 ```surql
@@ -212,7 +213,7 @@ RETURN array::add(["one", "two"], "three");
 
 ## `array::all`
 
-The `array::all` function checks whether all array values are truthy.
+The `array::all` function checks whether all array values are [truthy](/docs/surrealdb/surrealql/datamodel/values#values-and-truthiness).
 
 ```surql title="API DEFINITION"
 array::all(array) -> bool
@@ -418,7 +419,7 @@ RETURN array::concat([1,2,3,4], [3,4,5,6]);
 The `array::clump` function returns the original array split into sub-arrays of `size`. The last sub-array may have a length less than the length of `size` if `size` does not divide equally into the original array.
 
 ```surql title="API DEFINITION"
-array::clump(array, value) -> array
+array::clump(array, size: int) -> array
 ```
 The following examples show this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
 
@@ -624,7 +625,8 @@ RETURN array::last([ 's', 'u', 'r', 'r', 'e', 'a', 'l' ]);
 
 ## `array::len`
 
-The `array::len` function calculates the length of an array, returning a number. This function includes all items when counting the number of items in the array. If you want to only count truthy values, then use the [count()](/docs/surrealdb/surrealql/functions/database/count) function.
+The `array::len` function calculates the length of an array, returning a number. This function includes all items when counting the number of items in the array. If you want to only count [truthy](/docs/surrealdb/surrealql/datamodel/values#values-and-truthiness) values, then use the [count()](/docs/surrealdb/surrealql/functions/database/count) function.
+
 ```surql title="API DEFINITION"
 array::len(array) -> number
 ```
@@ -1000,7 +1002,7 @@ RETURN array::sort::desc([ 1, 2, 1, null, "something", 3, 3, 4, 0 ]);
 
 ## `array::transpose`
 
-The `array::transpose` is used to perform 2d array transposition but it's behavior in cases of arrays of differing sizes can be best described as taking in multiple arrays and 'layering' them on top of each other.
+The `array::transpose` is used to perform 2d array transposition but its behavior in cases of arrays of differing sizes can be best described as taking in multiple arrays and 'layering' them on top of each other.
 
 
 ```surql title="API DEFINITION"
@@ -1039,7 +1041,7 @@ RETURN array::union([1,2,1,6], [1,3,4,5,6]);
 <Since v="v2.0.0" />
 
 ```surql title="API DEFINITION"
-array::windows(array, size) -> array
+array::windows(array, size: int) -> array
 ```
 
 The `array::windows` function returns a number of arrays of length `size` created by moving one index at a time down the original array. The arrays returned are guaranteed to be of length `size`. As a result, the function will return an empty array if the length of the original array is not large enough to create a single output array.
@@ -1070,3 +1072,35 @@ FOR $pair IN array::windows(["grandfather", "father", "son"], 2) {
 
 SELECT id, ->father_of->person, ->father_of->father_of->person FROM person;
 ```
+
+## Method chaining
+
+<Since v="v2.0.0" />
+
+Method chaining allows functions to be called using the `.` dot operator on a value of a certain type instead of the full path of the function followed by the value.
+
+```surql
+-- Traditional syntax
+array::push(["Again", "again"], "again");
+
+-- Method chaining syntax
+["Again", "again"].push("again");
+```
+
+```bash title="Response"
+["Again", "again", "again"]
+```
+
+This is particularly useful for readability when a function is called multiple times.
+
+```surql
+-- Traditional syntax
+array::join(array::push(["Again", "again"], "again"));
+
+-- Method chaining syntax
+["Again", "again"].push("again").join(" and ");
+```
+
+```bash title="Response"
+"Again and again and again"
+```

doc-surrealdb_versioned_docs/version-latest/surrealql/functions/database/count.mdx

@@ -31,7 +31,7 @@ The count function counts the number of times that the function is called. This
 ```surql title="API DEFINITION"
 count() -> 1
 ```
-If a value is given as the first argument, then this function checks whether a given value is truthy. This is useful for returning the total number of rows, which match a certain condition, in a [`SELECT`](/docs/surrealdb/surrealql/statements/select) statement, with a GROUP BY clause.
+If a value is given as the first argument, then this function checks whether a given value is [truthy](/docs/surrealdb/surrealql/datamodel/values#values-and-truthiness). This is useful for returning the total number of rows, which match a certain condition, in a [`SELECT`](/docs/surrealdb/surrealql/statements/select) statement, with a GROUP BY clause.
 
 ```surql title="API DEFINITION"
 count(any) -> number

doc-surrealdb_versioned_docs/version-latest/surrealql/functions/database/duration.mdx

@@ -5,6 +5,8 @@ title: Duration functions | SurrealQL
 description: These functions can be used when converting between numeric and duration data.
 ---
 
+import Since from '@site/src/components/Since'
+
 # Duration functions
 
 These functions can be used when converting between numeric and duration data.
@@ -380,4 +382,37 @@ RETURN duration::from::weeks(3);
 3w
 ```
 
-<br /><br />
+<br /><br />
+
+
+## Method chaining
+
+<Since v="v2.0.0" />
+
+Method chaining allows functions to be called using the `.` dot operator on a value of a certain type instead of the full path of the function followed by the value.
+
+```surql
+-- Traditional syntax
+duration::mins(2d6h);
+
+-- Method chaining syntax
+2d6h.mins();
+```
+
+```bash title="Response"
+3240
+```
+
+This is particularly useful for readability when a function is called multiple times.
+
+```surql
+-- Traditional syntax
+duration::mins(duration::from::millis(98734234));
+
+-- Method chaining syntax
+duration::from::millis(98734234).mins();
+```
+
+```bash title="Response"
+1645
+```