arangojs 7.8.0 → 8.0.0

package/aql.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.aql = exports.isAqlLiteral = exports.isGeneratedAqlQuery = exports.isAqlQuery = void 0;
+exports.join = exports.literal = exports.aql = exports.isAqlLiteral = exports.isGeneratedAqlQuery = exports.isAqlQuery = void 0;
 /**
  * ```js
  * import { aql } from "arangojs/aql";
@@ -13,6 +13,7 @@ exports.aql = exports.isAqlLiteral = exports.isGeneratedAqlQuery = exports.isAql
  *
  * @packageDocumentation
  */
+const analyzer_1 = require("./analyzer");
 const collection_1 = require("./collection");
 const graph_1 = require("./graph");
 const view_1 = require("./view");
@@ -31,7 +32,6 @@ exports.isAqlQuery = isAqlQuery;
  * @param query - A value that might be a `GeneratedAqlQuery`.
  *
  * @internal
- * @hidden
  */
 function isGeneratedAqlQuery(query) {
     return isAqlQuery(query) && typeof query._source === "function";
@@ -56,8 +56,8 @@ exports.isAqlLiteral = isAqlLiteral;
  * Tagged template strings will return an {@link AqlQuery} object with
  * `query` and `bindVars` attributes reflecting any interpolated values.
  *
- * Any {@link ArangoCollection} instance used in a query string will be
- * recognized as a collection reference and generate an AQL collection bind
+ * Any {@link collection.ArangoCollection} instance used in a query string will
+ * be recognized as a collection reference and generate an AQL collection bind
  * parameter instead of a regular AQL value bind parameter.
  *
  * **Note**: you should always use the `aql` template tag when writing
@@ -169,9 +169,10 @@ function aql(templateStrings, ...args) {
         const index = bindValues.indexOf(rawValue);
         const isKnown = index !== -1;
         let name = `value${isKnown ? index : bindValues.length}`;
-        if (collection_1.isArangoCollection(rawValue) ||
-            graph_1.isArangoGraph(rawValue) ||
-            view_1.isArangoView(rawValue)) {
+        if ((0, collection_1.isArangoCollection)(rawValue) ||
+            (0, graph_1.isArangoGraph)(rawValue) ||
+            (0, view_1.isArangoView)(rawValue) ||
+            (0, analyzer_1.isArangoAnalyzer)(rawValue)) {
             name = `@${name}`;
             value = rawValue.name;
         }
@@ -188,147 +189,144 @@ function aql(templateStrings, ...args) {
     };
 }
 exports.aql = aql;
-// eslint-disable-next-line @typescript-eslint/no-namespace
-(function (aql) {
-    /**
-     * Marks an arbitrary scalar value (i.e. a string, number or boolean) as
-     * safe for being inlined directly into AQL queries when used in an `aql`
-     * template string, rather than being converted into a bind parameter.
-     *
-     * **Note**: Nesting `aql` template strings is a much safer alternative for
-     * most use cases. This low-level helper function only exists to help with
-     * rare edge cases where a trusted AQL query fragment must be read from a
-     * string (e.g. when reading query fragments from JSON) and should only be
-     * used as a last resort.
-     *
-     * @example
-     * ```js
-     * // BAD! DO NOT DO THIS!
-     * const sortDirection = aql.literal('ASC');
-     *
-     * // GOOD! DO THIS INSTEAD!
-     * const sortDirection = aql`ASC`;
-     * ```
-     *
-     * @example
-     * ```js
-     * // BAD! DO NOT DO THIS!
-     * const filterColor = aql.literal('FILTER d.color == "green"');
-     * const result = await db.query(aql`
-     *   FOR d IN some-collection
-     *   ${filterColor}
-     *   RETURN d
-     * `);
-     *
-     * // GOOD! DO THIS INSTEAD!
-     * const color = "green";
-     * const filterColor = aql`FILTER d.color === ${color}`;
-     * const result = await db.query(aql`
-     *   FOR d IN some-collection
-     *   ${filterColor}
-     *   RETURN d
-     * `);
-     * ```
-     *
-     * @example
-     * ```js
-     * // WARNING: We explicitly trust the environment variable to be safe!
-     * const filter = aql.literal(process.env.FILTER_STATEMENT);
-     * const users = await db.query(aql`
-     *   FOR user IN users
-     *   ${filter}
-     *   RETURN user
-     * `);
-     * ```
-     */
-    function literal(value) {
-        if (isAqlLiteral(value)) {
-            return value;
-        }
-        return {
-            toAQL() {
-                if (value === undefined) {
-                    return "";
-                }
-                return String(value);
-            },
-        };
+/**
+ * Marks an arbitrary scalar value (i.e. a string, number or boolean) as
+ * safe for being inlined directly into AQL queries when used in an `aql`
+ * template string, rather than being converted into a bind parameter.
+ *
+ * **Note**: Nesting `aql` template strings is a much safer alternative for
+ * most use cases. This low-level helper function only exists to help with
+ * rare edge cases where a trusted AQL query fragment must be read from a
+ * string (e.g. when reading query fragments from JSON) and should only be
+ * used as a last resort.
+ *
+ * @example
+ * ```js
+ * // BAD! DO NOT DO THIS!
+ * const sortDirection = literal('ASC');
+ *
+ * // GOOD! DO THIS INSTEAD!
+ * const sortDirection = aql`ASC`;
+ * ```
+ *
+ * @example
+ * ```js
+ * // BAD! DO NOT DO THIS!
+ * const filterColor = literal('FILTER d.color == "green"');
+ * const result = await db.query(aql`
+ *   FOR d IN some-collection
+ *   ${filterColor}
+ *   RETURN d
+ * `);
+ *
+ * // GOOD! DO THIS INSTEAD!
+ * const color = "green";
+ * const filterColor = aql`FILTER d.color === ${color}`;
+ * const result = await db.query(aql`
+ *   FOR d IN some-collection
+ *   ${filterColor}
+ *   RETURN d
+ * `);
+ * ```
+ *
+ * @example
+ * ```js
+ * // WARNING: We explicitly trust the environment variable to be safe!
+ * const filter = literal(process.env.FILTER_STATEMENT);
+ * const users = await db.query(aql`
+ *   FOR user IN users
+ *   ${filter}
+ *   RETURN user
+ * `);
+ * ```
+ */
+function literal(value) {
+    if (isAqlLiteral(value)) {
+        return value;
     }
-    aql.literal = literal;
-    /**
-     * Constructs {@link AqlQuery} objects from an array of arbitrary values.
-     *
-     * **Note**: Nesting `aql` template strings is a much safer alternative
-     * for most use cases. This low-level helper function only exists to
-     * complement the `aql` tag when constructing complex queries from dynamic
-     * arrays of query fragments.
-     *
-     * @param values - Array of values to join. These values will behave exactly
-     * like values interpolated in an `aql` template string.
-     * @param sep - Seperator to insert between values. This value will behave
-     * exactly like a value passed to {@link aql.literal}, i.e. it will be
-     * inlined as-is, rather than being converted into a bind parameter.
-     *
-     * @example
-     * ```js
-     * const users = db.collection("users");
-     * const filters = [];
-     * if (adminsOnly) filters.push(aql`FILTER user.admin`);
-     * if (activeOnly) filters.push(aql`FILTER user.active`);
-     * const result = await db.query(aql`
-     *   FOR user IN ${users}
-     *   ${aql.join(filters)}
-     *   RETURN user
-     * `);
-     * ```
-     *
-     * @example
-     * ```js
-     * const users = db.collection("users");
-     * const keys = ["jreyes", "ghermann"];
-     *
-     * // BAD! NEEDLESSLY COMPLEX!
-     * const docs = keys.map(key => aql`DOCUMENT(${users}, ${key}`));
-     * const result = await db.query(aql`
-     *   FOR user IN [
-     *     ${aql.join(docs, ", ")}
-     *   ]
-     *   RETURN user
-     * `);
-     * // Query:
-     * //   FOR user IN [
-     * //     DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)
-     * //   ]
-     * //   RETURN user
-     * // Bind parameters:
-     * //   @value0 -> "users"
-     * //   value1 -> "jreyes"
-     * //   value2 -> "ghermann"
-     *
-     * // GOOD! MUCH SIMPLER!
-     * const result = await db.query(aql`
-     *   FOR key IN ${keys}
-     *   LET user = DOCUMENT(${users}, key)
-     *   RETURN user
-     * `);
-     * // Query:
-     * //   FOR user IN @value0
-     * //   LET user = DOCUMENT(@@value1, key)
-     * //   RETURN user
-     * // Bind parameters:
-     * //   value0 -> ["jreyes", "ghermann"]
-     * //   @value1 -> "users"
-     * ```
-     */
-    function join(values, sep = " ") {
-        if (!values.length) {
-            return aql ``;
-        }
-        if (values.length === 1) {
-            return aql `${values[0]}`;
-        }
-        return aql(["", ...Array(values.length - 1).fill(sep), ""], ...values);
+    return {
+        toAQL() {
+            if (value === undefined) {
+                return "";
+            }
+            return String(value);
+        },
+    };
+}
+exports.literal = literal;
+/**
+ * Constructs {@link AqlQuery} objects from an array of arbitrary values.
+ *
+ * **Note**: Nesting `aql` template strings is a much safer alternative
+ * for most use cases. This low-level helper function only exists to
+ * complement the `aql` tag when constructing complex queries from dynamic
+ * arrays of query fragments.
+ *
+ * @param values - Array of values to join. These values will behave exactly
+ * like values interpolated in an `aql` template string.
+ * @param sep - Seperator to insert between values. This value will behave
+ * exactly like a value passed to {@link literal}, i.e. it will be
+ * inlined as-is, rather than being converted into a bind parameter.
+ *
+ * @example
+ * ```js
+ * const users = db.collection("users");
+ * const filters = [];
+ * if (adminsOnly) filters.push(aql`FILTER user.admin`);
+ * if (activeOnly) filters.push(aql`FILTER user.active`);
+ * const result = await db.query(aql`
+ *   FOR user IN ${users}
+ *   ${join(filters)}
+ *   RETURN user
+ * `);
+ * ```
+ *
+ * @example
+ * ```js
+ * const users = db.collection("users");
+ * const keys = ["jreyes", "ghermann"];
+ *
+ * // BAD! NEEDLESSLY COMPLEX!
+ * const docs = keys.map(key => aql`DOCUMENT(${users}, ${key}`));
+ * const result = await db.query(aql`
+ *   FOR user IN [
+ *     ${join(docs, ", ")}
+ *   ]
+ *   RETURN user
+ * `);
+ * // Query:
+ * //   FOR user IN [
+ * //     DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)
+ * //   ]
+ * //   RETURN user
+ * // Bind parameters:
+ * //   @value0 -> "users"
+ * //   value1 -> "jreyes"
+ * //   value2 -> "ghermann"
+ *
+ * // GOOD! MUCH SIMPLER!
+ * const result = await db.query(aql`
+ *   FOR key IN ${keys}
+ *   LET user = DOCUMENT(${users}, key)
+ *   RETURN user
+ * `);
+ * // Query:
+ * //   FOR user IN @value0
+ * //   LET user = DOCUMENT(@@value1, key)
+ * //   RETURN user
+ * // Bind parameters:
+ * //   value0 -> ["jreyes", "ghermann"]
+ * //   @value1 -> "users"
+ * ```
+ */
+function join(values, sep = " ") {
+    if (!values.length) {
+        return aql ``;
     }
-    aql.join = join;
-})(aql = exports.aql || (exports.aql = {}));
+    if (values.length === 1) {
+        return aql `${values[0]}`;
+    }
+    return aql(["", ...Array(values.length - 1).fill(sep), ""], ...values);
+}
+exports.join = join;
 //# sourceMappingURL=aql.js.map

package/aql.js.map

@@ -1 +1 @@
-{"version":3,"file":"aql.js","sourceRoot":"","sources":["../src/aql.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ```js\n * import { aql } from \"arangojs/aql\";\n * ```\n *\n * The \"aql\" module provides the {@link aql} template string handler and\n * helper functions, as well as associated types and interfaces for TypeScript.\n *\n * The aql function and namespace is also re-exported by the \"index\" module.\n *\n * @packageDocumentation\n */\nimport { ArangoCollection, isArangoCollection } from \"./collection\";\nimport { Dict } from \"./connection\";\nimport { Graph, isArangoGraph } from \"./graph\";\nimport { isArangoView, View } from \"./view\";\n\n/**\n * Generic AQL query object consisting of an AQL query string and its bind\n * parameters.\n */\nexport interface AqlQuery {\n  /**\n   * An AQL query string.\n   */\n  query: string;\n  /**\n   * An object mapping AQL bind parameter names to their respective values.\n   *\n   * Names of parameters representing collections are prefixed with an\n   * at-symbol.\n   */\n  bindVars: Dict<any>;\n}\n\n/**\n * Derived type representing AQL query objects generated by the AQL helper\n * functions and the AQL template string handler. These objects can be fed\n * back into these helper functions to be inlined or merged in complex queries.\n *\n * @internal\n */\nexport interface GeneratedAqlQuery extends AqlQuery {\n  /**\n   * @internal\n   * @hidden\n   */\n  _source: () => { strings: string[]; args: AqlValue[] };\n}\n\n/**\n * An object representing a trusted AQL literal that will be inlined directly\n * when used in an AQL template or passed to AQL helper functions.\n *\n * Arbitrary values can be converted to trusted AQL literals by passing them\n * to the {@link aql.literal} helper function.\n */\nexport interface AqlLiteral {\n  /**\n   * @internal\n   *\n   * Returns a string representation of this AQL literal that can be inlined\n   * in an AQL template.\n   */\n  toAQL: () => string;\n}\n\n/**\n * A value that can be used in an AQL template string or passed to an AQL\n * helper function.\n */\nexport type AqlValue =\n  | ArangoCollection\n  | View\n  | Graph\n  | GeneratedAqlQuery\n  | AqlLiteral\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | Record<string, any>\n  | any[];\n\n/**\n * Indicates whether the given value is an {@link AqlQuery}.\n *\n * @param query - A value that might be an `AqlQuery`.\n */\nexport function isAqlQuery(query: any): query is AqlQuery {\n  return Boolean(query && typeof query.query === \"string\" && query.bindVars);\n}\n\n/**\n * Indicates whether the given value is a {@link GeneratedAqlQuery}.\n *\n * @param query - A value that might be a `GeneratedAqlQuery`.\n *\n * @internal\n * @hidden\n */\nexport function isGeneratedAqlQuery(query: any): query is GeneratedAqlQuery {\n  return isAqlQuery(query) && typeof (query as any)._source === \"function\";\n}\n\n/**\n * Indicates whether the given value is an {@link AqlLiteral}.\n *\n * @param literal - A value that might be an `AqlLiteral`.\n */\nexport function isAqlLiteral(literal: any): literal is AqlLiteral {\n  return Boolean(literal && typeof literal.toAQL === \"function\");\n}\n\n/**\n * Template string handler (template tag) for AQL queries.\n *\n * The `aql` tag can be used to write complex AQL queries as multi-line strings\n * without having to worry about `bindVars` and the distinction between\n * collections and regular parameters.\n *\n * Tagged template strings will return an {@link AqlQuery} object with\n * `query` and `bindVars` attributes reflecting any interpolated values.\n *\n * Any {@link ArangoCollection} instance used in a query string will be\n * recognized as a collection reference and generate an AQL collection bind\n * parameter instead of a regular AQL value bind parameter.\n *\n * **Note**: you should always use the `aql` template tag when writing\n * dynamic AQL queries instead of using untagged (normal) template strings.\n * Untagged template strings will inline any interpolated values and return\n * a plain string as result. The `aql` template tag will only inline references\n * to the interpolated values and produce an AQL query object containing both\n * the query and the values. This prevents most injection attacks when using\n * untrusted values in dynamic queries.\n *\n * @example\n * ```js\n * // Some user-supplied string that may be malicious\n * const untrustedValue = req.body.email;\n *\n * // Without aql tag: BAD! DO NOT DO THIS!\n * const badQuery = `\n *   FOR user IN users\n *   FILTER user.email == \"${untrustedValue}\"\n *   RETURN user\n * `;\n * // e.g. if untrustedValue is '\" || user.admin == true || \"':\n * // Query:\n * //   FOR user IN users\n * //   FILTER user.email == \"\" || user.admin == true || \"\"\n * //   RETURN user\n *\n * // With the aql tag: GOOD! MUCH SAFER!\n * const betterQuery = aql`\n *   FOR user IN users\n *   FILTER user.email == ${untrustedValue}\n *   RETURN user\n * `;\n * // Query:\n * //   FOR user IN users\n * //   FILTER user.email == @value0\n * //   RETURN user\n * // Bind parameters:\n * //   value0 -> untrustedValue\n * ```\n *\n * @example\n * ```js\n * const collection = db.collection(\"some-collection\");\n * const minValue = 23;\n * const result = await db.query(aql`\n *   FOR d IN ${collection}\n *   FILTER d.num > ${minValue}\n *   RETURN d\n * `);\n *\n * // Equivalent raw query object\n * const result2 = await db.query({\n *   query: `\n *     FOR d IN @@collection\n *     FILTER d.num > @minValue\n *     RETURN d\n *   `,\n *   bindVars: {\n *     \"@collection\": collection.name,\n *     minValue: minValue\n *   }\n * });\n * ```\n *\n * @example\n * ```js\n * const collection = db.collection(\"some-collection\");\n * const color = \"green\";\n * const filter = aql`FILTER d.color == ${color}'`;\n * const result = await db.query(aql`\n *   FOR d IN ${collection}\n *   ${filter}\n *   RETURN d\n * `);\n * ```\n */\nexport function aql(\n  templateStrings: TemplateStringsArray,\n  ...args: AqlValue[]\n): GeneratedAqlQuery {\n  const strings = [...templateStrings];\n  const bindVars: Dict<any> = {};\n  const bindValues = [];\n  let query = strings[0];\n  for (let i = 0; i < args.length; i++) {\n    const rawValue = args[i];\n    let value = rawValue;\n    if (isGeneratedAqlQuery(rawValue)) {\n      const src = rawValue._source();\n      if (src.args.length) {\n        query += src.strings[0];\n        args.splice(i, 1, ...src.args);\n        strings.splice(\n          i,\n          2,\n          strings[i] + src.strings[0],\n          ...src.strings.slice(1, src.args.length),\n          src.strings[src.args.length] + strings[i + 1]\n        );\n      } else {\n        query += rawValue.query + strings[i + 1];\n        args.splice(i, 1);\n        strings.splice(i, 2, strings[i] + rawValue.query + strings[i + 1]);\n      }\n      i -= 1;\n      continue;\n    }\n    if (rawValue === undefined) {\n      query += strings[i + 1];\n      continue;\n    }\n    if (isAqlLiteral(rawValue)) {\n      query += `${rawValue.toAQL()}${strings[i + 1]}`;\n      continue;\n    }\n    const index = bindValues.indexOf(rawValue);\n    const isKnown = index !== -1;\n    let name = `value${isKnown ? index : bindValues.length}`;\n    if (\n      isArangoCollection(rawValue) ||\n      isArangoGraph(rawValue) ||\n      isArangoView(rawValue)\n    ) {\n      name = `@${name}`;\n      value = rawValue.name;\n    }\n    if (!isKnown) {\n      bindValues.push(rawValue);\n      bindVars[name] = value;\n    }\n    query += `@${name}${strings[i + 1]}`;\n  }\n  return {\n    query,\n    bindVars,\n    _source: () => ({ strings, args }),\n  };\n}\n\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport namespace aql {\n  /**\n   * Marks an arbitrary scalar value (i.e. a string, number or boolean) as\n   * safe for being inlined directly into AQL queries when used in an `aql`\n   * template string, rather than being converted into a bind parameter.\n   *\n   * **Note**: Nesting `aql` template strings is a much safer alternative for\n   * most use cases. This low-level helper function only exists to help with\n   * rare edge cases where a trusted AQL query fragment must be read from a\n   * string (e.g. when reading query fragments from JSON) and should only be\n   * used as a last resort.\n   *\n   * @example\n   * ```js\n   * // BAD! DO NOT DO THIS!\n   * const sortDirection = aql.literal('ASC');\n   *\n   * // GOOD! DO THIS INSTEAD!\n   * const sortDirection = aql`ASC`;\n   * ```\n   *\n   * @example\n   * ```js\n   * // BAD! DO NOT DO THIS!\n   * const filterColor = aql.literal('FILTER d.color == \"green\"');\n   * const result = await db.query(aql`\n   *   FOR d IN some-collection\n   *   ${filterColor}\n   *   RETURN d\n   * `);\n   *\n   * // GOOD! DO THIS INSTEAD!\n   * const color = \"green\";\n   * const filterColor = aql`FILTER d.color === ${color}`;\n   * const result = await db.query(aql`\n   *   FOR d IN some-collection\n   *   ${filterColor}\n   *   RETURN d\n   * `);\n   * ```\n   *\n   * @example\n   * ```js\n   * // WARNING: We explicitly trust the environment variable to be safe!\n   * const filter = aql.literal(process.env.FILTER_STATEMENT);\n   * const users = await db.query(aql`\n   *   FOR user IN users\n   *   ${filter}\n   *   RETURN user\n   * `);\n   * ```\n   */\n  export function literal(\n    value: string | number | boolean | AqlLiteral | null | undefined\n  ): AqlLiteral {\n    if (isAqlLiteral(value)) {\n      return value;\n    }\n    return {\n      toAQL() {\n        if (value === undefined) {\n          return \"\";\n        }\n        return String(value);\n      },\n    };\n  }\n\n  /**\n   * Constructs {@link AqlQuery} objects from an array of arbitrary values.\n   *\n   * **Note**: Nesting `aql` template strings is a much safer alternative\n   * for most use cases. This low-level helper function only exists to\n   * complement the `aql` tag when constructing complex queries from dynamic\n   * arrays of query fragments.\n   *\n   * @param values - Array of values to join. These values will behave exactly\n   * like values interpolated in an `aql` template string.\n   * @param sep - Seperator to insert between values. This value will behave\n   * exactly like a value passed to {@link aql.literal}, i.e. it will be\n   * inlined as-is, rather than being converted into a bind parameter.\n   *\n   * @example\n   * ```js\n   * const users = db.collection(\"users\");\n   * const filters = [];\n   * if (adminsOnly) filters.push(aql`FILTER user.admin`);\n   * if (activeOnly) filters.push(aql`FILTER user.active`);\n   * const result = await db.query(aql`\n   *   FOR user IN ${users}\n   *   ${aql.join(filters)}\n   *   RETURN user\n   * `);\n   * ```\n   *\n   * @example\n   * ```js\n   * const users = db.collection(\"users\");\n   * const keys = [\"jreyes\", \"ghermann\"];\n   *\n   * // BAD! NEEDLESSLY COMPLEX!\n   * const docs = keys.map(key => aql`DOCUMENT(${users}, ${key}`));\n   * const result = await db.query(aql`\n   *   FOR user IN [\n   *     ${aql.join(docs, \", \")}\n   *   ]\n   *   RETURN user\n   * `);\n   * // Query:\n   * //   FOR user IN [\n   * //     DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)\n   * //   ]\n   * //   RETURN user\n   * // Bind parameters:\n   * //   @value0 -> \"users\"\n   * //   value1 -> \"jreyes\"\n   * //   value2 -> \"ghermann\"\n   *\n   * // GOOD! MUCH SIMPLER!\n   * const result = await db.query(aql`\n   *   FOR key IN ${keys}\n   *   LET user = DOCUMENT(${users}, key)\n   *   RETURN user\n   * `);\n   * // Query:\n   * //   FOR user IN @value0\n   * //   LET user = DOCUMENT(@@value1, key)\n   * //   RETURN user\n   * // Bind parameters:\n   * //   value0 -> [\"jreyes\", \"ghermann\"]\n   * //   @value1 -> \"users\"\n   * ```\n   */\n  export function join(\n    values: AqlValue[],\n    sep: string = \" \"\n  ): GeneratedAqlQuery {\n    if (!values.length) {\n      return aql``;\n    }\n    if (values.length === 1) {\n      return aql`${values[0]}`;\n    }\n    return aql(\n      [\"\", ...Array(values.length - 1).fill(sep), \"\"] as any,\n      ...values\n    );\n  }\n}\n"]}
+{"version":3,"file":"aql.js","sourceRoot":"","sources":["../src/aql.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ```js\n * import { aql } from \"arangojs/aql\";\n * ```\n *\n * The \"aql\" module provides the {@link aql} template string handler and\n * helper functions, as well as associated types and interfaces for TypeScript.\n *\n * The aql function and namespace is also re-exported by the \"index\" module.\n *\n * @packageDocumentation\n */\nimport { isArangoAnalyzer } from \"./analyzer\";\nimport { ArangoCollection, isArangoCollection } from \"./collection\";\nimport { Graph, isArangoGraph } from \"./graph\";\nimport { isArangoView, View } from \"./view\";\n\n/**\n * Generic AQL query object consisting of an AQL query string and its bind\n * parameters.\n */\nexport interface AqlQuery {\n  /**\n   * An AQL query string.\n   */\n  query: string;\n  /**\n   * An object mapping AQL bind parameter names to their respective values.\n   *\n   * Names of parameters representing collections are prefixed with an\n   * at-symbol.\n   */\n  bindVars: Record<string, any>;\n}\n\n/**\n * Derived type representing AQL query objects generated by the AQL helper\n * functions and the AQL template string handler. These objects can be fed\n * back into these helper functions to be inlined or merged in complex queries.\n *\n * @internal\n */\nexport interface GeneratedAqlQuery extends AqlQuery {\n  /**\n   * @internal\n   */\n  _source: () => { strings: string[]; args: AqlValue[] };\n}\n\n/**\n * An object representing a trusted AQL literal that will be inlined directly\n * when used in an AQL template or passed to AQL helper functions.\n *\n * Arbitrary values can be converted to trusted AQL literals by passing them\n * to the {@link literal} helper function.\n */\nexport interface AqlLiteral {\n  /**\n   * @internal\n   *\n   * Returns a string representation of this AQL literal that can be inlined\n   * in an AQL template.\n   */\n  toAQL: () => string;\n}\n\n/**\n * A value that can be used in an AQL template string or passed to an AQL\n * helper function.\n */\nexport type AqlValue =\n  | ArangoCollection\n  | View\n  | Graph\n  | GeneratedAqlQuery\n  | AqlLiteral\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | Record<string, any>\n  | any[];\n\n/**\n * Indicates whether the given value is an {@link AqlQuery}.\n *\n * @param query - A value that might be an `AqlQuery`.\n */\nexport function isAqlQuery(query: any): query is AqlQuery {\n  return Boolean(query && typeof query.query === \"string\" && query.bindVars);\n}\n\n/**\n * Indicates whether the given value is a {@link GeneratedAqlQuery}.\n *\n * @param query - A value that might be a `GeneratedAqlQuery`.\n *\n * @internal\n */\nexport function isGeneratedAqlQuery(query: any): query is GeneratedAqlQuery {\n  return isAqlQuery(query) && typeof (query as any)._source === \"function\";\n}\n\n/**\n * Indicates whether the given value is an {@link AqlLiteral}.\n *\n * @param literal - A value that might be an `AqlLiteral`.\n */\nexport function isAqlLiteral(literal: any): literal is AqlLiteral {\n  return Boolean(literal && typeof literal.toAQL === \"function\");\n}\n\n/**\n * Template string handler (template tag) for AQL queries.\n *\n * The `aql` tag can be used to write complex AQL queries as multi-line strings\n * without having to worry about `bindVars` and the distinction between\n * collections and regular parameters.\n *\n * Tagged template strings will return an {@link AqlQuery} object with\n * `query` and `bindVars` attributes reflecting any interpolated values.\n *\n * Any {@link collection.ArangoCollection} instance used in a query string will\n * be recognized as a collection reference and generate an AQL collection bind\n * parameter instead of a regular AQL value bind parameter.\n *\n * **Note**: you should always use the `aql` template tag when writing\n * dynamic AQL queries instead of using untagged (normal) template strings.\n * Untagged template strings will inline any interpolated values and return\n * a plain string as result. The `aql` template tag will only inline references\n * to the interpolated values and produce an AQL query object containing both\n * the query and the values. This prevents most injection attacks when using\n * untrusted values in dynamic queries.\n *\n * @example\n * ```js\n * // Some user-supplied string that may be malicious\n * const untrustedValue = req.body.email;\n *\n * // Without aql tag: BAD! DO NOT DO THIS!\n * const badQuery = `\n *   FOR user IN users\n *   FILTER user.email == \"${untrustedValue}\"\n *   RETURN user\n * `;\n * // e.g. if untrustedValue is '\" || user.admin == true || \"':\n * // Query:\n * //   FOR user IN users\n * //   FILTER user.email == \"\" || user.admin == true || \"\"\n * //   RETURN user\n *\n * // With the aql tag: GOOD! MUCH SAFER!\n * const betterQuery = aql`\n *   FOR user IN users\n *   FILTER user.email == ${untrustedValue}\n *   RETURN user\n * `;\n * // Query:\n * //   FOR user IN users\n * //   FILTER user.email == @value0\n * //   RETURN user\n * // Bind parameters:\n * //   value0 -> untrustedValue\n * ```\n *\n * @example\n * ```js\n * const collection = db.collection(\"some-collection\");\n * const minValue = 23;\n * const result = await db.query(aql`\n *   FOR d IN ${collection}\n *   FILTER d.num > ${minValue}\n *   RETURN d\n * `);\n *\n * // Equivalent raw query object\n * const result2 = await db.query({\n *   query: `\n *     FOR d IN @@collection\n *     FILTER d.num > @minValue\n *     RETURN d\n *   `,\n *   bindVars: {\n *     \"@collection\": collection.name,\n *     minValue: minValue\n *   }\n * });\n * ```\n *\n * @example\n * ```js\n * const collection = db.collection(\"some-collection\");\n * const color = \"green\";\n * const filter = aql`FILTER d.color == ${color}'`;\n * const result = await db.query(aql`\n *   FOR d IN ${collection}\n *   ${filter}\n *   RETURN d\n * `);\n * ```\n */\nexport function aql(\n  templateStrings: TemplateStringsArray,\n  ...args: AqlValue[]\n): GeneratedAqlQuery {\n  const strings = [...templateStrings];\n  const bindVars: Record<string, any> = {};\n  const bindValues = [];\n  let query = strings[0];\n  for (let i = 0; i < args.length; i++) {\n    const rawValue = args[i];\n    let value = rawValue;\n    if (isGeneratedAqlQuery(rawValue)) {\n      const src = rawValue._source();\n      if (src.args.length) {\n        query += src.strings[0];\n        args.splice(i, 1, ...src.args);\n        strings.splice(\n          i,\n          2,\n          strings[i] + src.strings[0],\n          ...src.strings.slice(1, src.args.length),\n          src.strings[src.args.length] + strings[i + 1]\n        );\n      } else {\n        query += rawValue.query + strings[i + 1];\n        args.splice(i, 1);\n        strings.splice(i, 2, strings[i] + rawValue.query + strings[i + 1]);\n      }\n      i -= 1;\n      continue;\n    }\n    if (rawValue === undefined) {\n      query += strings[i + 1];\n      continue;\n    }\n    if (isAqlLiteral(rawValue)) {\n      query += `${rawValue.toAQL()}${strings[i + 1]}`;\n      continue;\n    }\n    const index = bindValues.indexOf(rawValue);\n    const isKnown = index !== -1;\n    let name = `value${isKnown ? index : bindValues.length}`;\n    if (\n      isArangoCollection(rawValue) ||\n      isArangoGraph(rawValue) ||\n      isArangoView(rawValue) ||\n      isArangoAnalyzer(rawValue)\n    ) {\n      name = `@${name}`;\n      value = rawValue.name;\n    }\n    if (!isKnown) {\n      bindValues.push(rawValue);\n      bindVars[name] = value;\n    }\n    query += `@${name}${strings[i + 1]}`;\n  }\n  return {\n    query,\n    bindVars,\n    _source: () => ({ strings, args }),\n  };\n}\n\n/**\n * Marks an arbitrary scalar value (i.e. a string, number or boolean) as\n * safe for being inlined directly into AQL queries when used in an `aql`\n * template string, rather than being converted into a bind parameter.\n *\n * **Note**: Nesting `aql` template strings is a much safer alternative for\n * most use cases. This low-level helper function only exists to help with\n * rare edge cases where a trusted AQL query fragment must be read from a\n * string (e.g. when reading query fragments from JSON) and should only be\n * used as a last resort.\n *\n * @example\n * ```js\n * // BAD! DO NOT DO THIS!\n * const sortDirection = literal('ASC');\n *\n * // GOOD! DO THIS INSTEAD!\n * const sortDirection = aql`ASC`;\n * ```\n *\n * @example\n * ```js\n * // BAD! DO NOT DO THIS!\n * const filterColor = literal('FILTER d.color == \"green\"');\n * const result = await db.query(aql`\n *   FOR d IN some-collection\n *   ${filterColor}\n *   RETURN d\n * `);\n *\n * // GOOD! DO THIS INSTEAD!\n * const color = \"green\";\n * const filterColor = aql`FILTER d.color === ${color}`;\n * const result = await db.query(aql`\n *   FOR d IN some-collection\n *   ${filterColor}\n *   RETURN d\n * `);\n * ```\n *\n * @example\n * ```js\n * // WARNING: We explicitly trust the environment variable to be safe!\n * const filter = literal(process.env.FILTER_STATEMENT);\n * const users = await db.query(aql`\n *   FOR user IN users\n *   ${filter}\n *   RETURN user\n * `);\n * ```\n */\nexport function literal(\n  value: string | number | boolean | AqlLiteral | null | undefined\n): AqlLiteral {\n  if (isAqlLiteral(value)) {\n    return value;\n  }\n  return {\n    toAQL() {\n      if (value === undefined) {\n        return \"\";\n      }\n      return String(value);\n    },\n  };\n}\n\n/**\n * Constructs {@link AqlQuery} objects from an array of arbitrary values.\n *\n * **Note**: Nesting `aql` template strings is a much safer alternative\n * for most use cases. This low-level helper function only exists to\n * complement the `aql` tag when constructing complex queries from dynamic\n * arrays of query fragments.\n *\n * @param values - Array of values to join. These values will behave exactly\n * like values interpolated in an `aql` template string.\n * @param sep - Seperator to insert between values. This value will behave\n * exactly like a value passed to {@link literal}, i.e. it will be\n * inlined as-is, rather than being converted into a bind parameter.\n *\n * @example\n * ```js\n * const users = db.collection(\"users\");\n * const filters = [];\n * if (adminsOnly) filters.push(aql`FILTER user.admin`);\n * if (activeOnly) filters.push(aql`FILTER user.active`);\n * const result = await db.query(aql`\n *   FOR user IN ${users}\n *   ${join(filters)}\n *   RETURN user\n * `);\n * ```\n *\n * @example\n * ```js\n * const users = db.collection(\"users\");\n * const keys = [\"jreyes\", \"ghermann\"];\n *\n * // BAD! NEEDLESSLY COMPLEX!\n * const docs = keys.map(key => aql`DOCUMENT(${users}, ${key}`));\n * const result = await db.query(aql`\n *   FOR user IN [\n *     ${join(docs, \", \")}\n *   ]\n *   RETURN user\n * `);\n * // Query:\n * //   FOR user IN [\n * //     DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)\n * //   ]\n * //   RETURN user\n * // Bind parameters:\n * //   @value0 -> \"users\"\n * //   value1 -> \"jreyes\"\n * //   value2 -> \"ghermann\"\n *\n * // GOOD! MUCH SIMPLER!\n * const result = await db.query(aql`\n *   FOR key IN ${keys}\n *   LET user = DOCUMENT(${users}, key)\n *   RETURN user\n * `);\n * // Query:\n * //   FOR user IN @value0\n * //   LET user = DOCUMENT(@@value1, key)\n * //   RETURN user\n * // Bind parameters:\n * //   value0 -> [\"jreyes\", \"ghermann\"]\n * //   @value1 -> \"users\"\n * ```\n */\nexport function join(values: AqlValue[], sep: string = \" \"): GeneratedAqlQuery {\n  if (!values.length) {\n    return aql``;\n  }\n  if (values.length === 1) {\n    return aql`${values[0]}`;\n  }\n  return aql([\"\", ...Array(values.length - 1).fill(sep), \"\"] as any, ...values);\n}\n"]}