Allow setting cursor item types on aql strings

Author: pluma

CHANGELOG.md

@@ -23,6 +23,25 @@ This driver uses semantic versioning:
   Previously these methods would make requests without a database prefix,
   implicitly using the `_system` database.
 
+- `aql` template strings now take a generic type argument
+
+  This allows explictly setting the item type of the `ArrayCursor` returned by
+  `db.query` when using `aql` template strings. Note that like when setting
+  the type on `db.query` directly, arangojs can make no guarantees that the
+  type matches the actual data returned by the query.
+
+  ```ts
+  const numbers = await db.query(aql<{ index: number; squared: number }>`
+    FOR i IN 1..1000
+    RETURN {
+      index: i,
+      squared: i * i
+    }
+  `);
+  const first = await numbers.next(); // { index: number; squared: number; }
+  console.log(first.index, first.squared); // 1 1
+  ```
+
 ### Fixed
 
 - Fixed `listUsers` behavior ([#782](https://github.com/arangodb/arangojs/issues/782))
@@ -244,7 +263,7 @@ for upgrading your code to arangojs v8.
       squared: i * i
     }
   `);
-  const first = await numbers.next();
+  const first = await numbers.next(); // { index: number; squared: number; }
   console.log(first.index, first.squared); // 1 1
   ```
 

src/aql.ts

@@ -15,11 +15,14 @@ import { ArangoCollection, isArangoCollection } from "./collection";
 import { Graph, isArangoGraph } from "./graph";
 import { isArangoView, View } from "./view";
 
+declare const type: unique symbol;
+
 /**
  * Generic AQL query object consisting of an AQL query string and its bind
  * parameters.
  */
-export interface AqlQuery {
+export interface AqlQuery<T = any> {
+  [type]?: T;
   /**
    * An AQL query string.
    */
@@ -40,7 +43,7 @@ export interface AqlQuery {
  *
  * @internal
  */
-export interface GeneratedAqlQuery extends AqlQuery {
+export interface GeneratedAqlQuery<T = any> extends AqlQuery<T> {
   /**
    * @internal
    */
@@ -200,10 +203,10 @@ export function isAqlLiteral(literal: any): literal is AqlLiteral {
  * `);
  * ```
  */
-export function aql(
+export function aql<T = any>(
   templateStrings: TemplateStringsArray,
   ...args: AqlValue[]
-): GeneratedAqlQuery {
+): GeneratedAqlQuery<T> {
   const strings = [...templateStrings];
   const bindVars: Record<string, any> = {};
   const bindValues = [];

src/database.ts

@@ -3808,7 +3808,7 @@ export class Database {
    * ```
    */
   query<T = any>(
-    query: AqlQuery,
+    query: AqlQuery<T>,
     options?: QueryOptions
   ): Promise<ArrayCursor<T>>;
   /**