Add more expansive #db.f cursor documentation

docs/scripting/db/cursor/array.mdx

@@ -0,0 +1,32 @@
+---
+title: array(_and_close)
+alias: array_and_close
+---
+
+Retrieve all documents of the cursor, and close it.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.array()
+```
+
+or
+
+```
+let cursor = #db.f(query, projection)
+cursor.array_and_close()
+```
+
+### Parameters
+
+No parameters.
+
+### Return
+
+Returns all documents from the cursor, as an array of objects.
+
+## Cursor State
+
+This function closes the cursor. If this is undesirable, try [array_and_keep_open](./array_and_keep_open).

docs/scripting/db/cursor/array_and_keep_open.mdx

@@ -0,0 +1,22 @@
+Retrieve all documents of the cursor, keeping it open.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.array_and_keep_open()
+```
+
+### Parameters
+
+No parameters.
+
+### Return
+
+Returns all documents from the cursor, as an array of objects.
+
+## Cursor State
+
+This function keeps the cursor open.
+
+Try [array](./array) for a variant of this function that automatically closes the cursor.

docs/scripting/db/cursor/close.mdx

@@ -0,0 +1,34 @@
+Close the cursor.
+
+This method is ((%Fidempotent%)):
+calling it multiple times results in identical behavior to calling it once.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.close()
+```
+
+### Parameters
+
+No parameters.
+
+### Return
+
+Always returns ((%Vnull%)).
+
+## Cursor State
+
+This function closes the cursor.
+
+## Example
+
+```js
+function(context, args) {
+  let cursor = #db.f({ type: "my_data" });
+
+  // removing the following line causes an error:
+  cursor.close();
+}
+```

docs/scripting/db/cursor/count.mdx

@@ -0,0 +1,34 @@
+---
+title: count(_and_close)
+alias: count_and_close
+---
+
+Retrieve the total number of documents of the cursor, and close it.
+
+This method ignores `skip` and `limit` settings.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.count()
+```
+
+or
+
+```
+let cursor = #db.f(query, projection)
+cursor.count_and_close()
+```
+
+### Parameters
+
+No parameters.
+
+### Return
+
+The total number of documents of this cursor, as a number.
+
+## Cursor State
+
+This function closes the cursor. If this is undesirable, try [count_and_keep_open](./count_and_keep_open).

docs/scripting/db/cursor/count_and_keep_open.mdx

@@ -0,0 +1,24 @@
+Retrieve the total number of documents of the cursor, keeping it open.
+
+This method ignores `skip` and `limit` settings.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.count_and_keep_open()
+```
+
+### Parameters
+
+No parameters.
+
+### Return
+
+The total number of documents of this cursor, as a number.
+
+## Cursor State
+
+This function keeps the cursor open.
+
+Try [count](./count) for a variant of this function that automatically closes the cursor.

docs/scripting/db/cursor/distinct.mdx

@@ -0,0 +1,36 @@
+---
+title: distinct(_and_close)
+alias: distinct_and_close
+---
+
+Retrieve the unique values of a given field for all documents of the cursor, and close it.
+
+This method ignores `skip` and `limit` settings.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.distinct(field)
+```
+
+or
+
+```
+let cursor = #db.f(query, projection)
+cursor.distinct_and_close(field)
+```
+
+### Parameters
+
+#### field
+
+A string naming the field to pull unique values from.
+
+### Return
+
+The unique values of the given field from all documents of the cursor, as an array.
+
+## Cursor State
+
+This function closes the cursor. If this is undesirable, try [distinct_and_keep_open](./distinct_and_keep_open).

docs/scripting/db/cursor/distinct_and_keep_open.mdx

@@ -0,0 +1,26 @@
+Retrieve the unique values of a given field for all documents of the cursor, keeping it open.
+
+This method ignores `skip` and `limit` settings.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.distinct_and_keep_open(field)
+```
+
+### Parameters
+
+#### field
+
+A string naming the field to pull unique values from.
+
+### Return
+
+The unique values of the given field from all documents of the cursor, as an array.
+
+## Cursor State
+
+This function keeps the cursor open.
+
+Try [distinct](./distinct) for a variant of this function that automatically closes the cursor.

docs/scripting/db/cursor/each.mdx

@@ -0,0 +1,34 @@
+---
+title: each(_and_close)
+alias: each_and_close
+---
+
+Call a function on all documents of the cursor, and close it.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.each(fn)
+```
+
+or
+
+```
+let cursor = #db.f(query, projection)
+cursor.each_and_close(fn)
+```
+
+### Parameters
+
+#### fn
+
+The function to call. This function is called once per document, with the document passed as the only argument.
+
+### Return
+
+Always returns ((%Vundefined%)).
+
+## Cursor state
+
+This function closes the cursor. If this is undesirable, try [each_and_keep_open](./each_and_keep_open).

docs/scripting/db/cursor/each_and_keep_open.mdx

@@ -0,0 +1,24 @@
+Call a function on all documents of the cursor, keeping it open.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.each_and_keep_open(fn)
+```
+
+### Parameters
+
+#### fn
+
+The function to call. This function is called once per document, with the document passed as the only argument.
+
+### Return
+
+Always returns ((%Vundefined%)).
+
+## Cursor state
+
+This function keeps the cursor open.
+
+Try [each](./each) for a variant of this function that automatically closes the cursor.

docs/scripting/db/cursor/first.mdx

@@ -0,0 +1,56 @@
+---
+title: first(_and_close)
+alias: first_and_close
+---
+
+Retrieve the first document of the cursor, and close it.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.first()
+```
+
+or
+
+```
+let cursor = #db.f(query, projection)
+cursor.first_and_close()
+```
+
+### Parameters
+
+No parameters.
+
+### Return
+
+Returns the first document from the cursor as an object.
+If the cursor is empty, returns ((%Vnull%)).
+
+## Cursor State
+
+This function closes the cursor. If this is undesirable, try [first_and_keep_open](./first_and_keep_open).
+
+## Example
+
+For the following examples, assume the database contains the following documents, inserted in that order:
+
+```
+{ type: "my_data", my_key: "foo", order: 2 }
+{ type: "my_data", my_key: "bar", order: 1 }
+```
+
+```js
+function(context, args) {
+  let data = #db.f({ type: "my_data" }).first();
+  return data; // { type: "my_data", my_key: "foo", order: 2 }
+}
+```
+
+```js
+function(context, args) {
+  let data = #db.f({ type: "my_data" }).sort({ order: 1 }).first();
+  return data; // { type: "my_data", my_key: "bar", order: 1 }
+}
+```

docs/scripting/db/cursor/first_and_keep_open.mdx

@@ -0,0 +1,42 @@
+Retrieve the first document of the cursor, keeping it open.
+
+## Syntax
+
+```
+let cursor = #db.f(query, projection)
+cursor.first_and_keep_open()
+// continue using `cursor`...
+```
+
+### Parameters
+
+No parameters.
+
+### Return
+
+Returns the first document from the cursor as an object.
+If the cursor is empty, returns ((%Vnull%)).
+
+## Cursor State
+
+This function keeps the cursor open.
+
+Try [first](./first) for a variant of this function that automatically closes the cursor.
+
+## Example
+
+For the following example, assume the database contains the following documents, inserted in that order:
+
+```
+{ type: "my_data", my_key: "foo", order: 2 }
+{ type: "my_data", my_key: "bar", order: 1 }
+```
+
+```js
+function(context, args) {
+  let cursor = #db.f({ type: "my_data" });
+  let a = cursor.skip(1).first_and_keep_open();
+  let b = cursor.skip(0).first_and_close();
+  return [ a.my_key, b.my_key ]; // [ "bar", "foo" ]
+}
+```