From a906466ece3c7e8584fde7f5c1ca5459541671b0 Mon Sep 17 00:00:00 2001
From: Alan Plum <alan.plum-extern@arangodb.com>
Date: Thu, 19 Sep 2024 18:29:51 +0200
Subject: [PATCH] Fix DE-849: Add HiddenIndex type

---
 .eslintrc         | 10 ++++++++--
 CHANGELOG.md      | 16 ++++++++++++++++
 src/collection.ts | 21 ++++++++++++++++++---
 src/indexes.ts    | 46 ++++++++++++++++++++++++++++++++++++++++++----
 typedoc.json      |  2 +-
 5 files changed, 85 insertions(+), 10 deletions(-)

diff --git a/.eslintrc b/.eslintrc
index 572917b27..d3277e4f2 100644
--- a/.eslintrc
+++ b/.eslintrc
@@ -8,7 +8,11 @@
     "sourceType": "module",
     "project": "./tsconfig.json"
   },
-  "plugins": ["@typescript-eslint", "prettier", "security"],
+  "plugins": [
+    "@typescript-eslint",
+    "prettier",
+    "security"
+  ],
   "extends": [
     "plugin:@typescript-eslint/recommended",
     "plugin:security/recommended",
@@ -26,7 +30,9 @@
     "@typescript-eslint/no-non-null-assertion": "off",
     "@typescript-eslint/no-unused-vars": [
       "error",
-      { "argsIgnorePattern": "^_" }
+      {
+        "argsIgnorePattern": "^_"
+      }
     ],
     "security/detect-object-injection": "off"
   }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43f7230d4..950f3356d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,21 @@ This driver uses semantic versioning:
 - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_
   changes that require changes in your code to upgrade.
 
+## [Unreleased]
+
+### Changed
+
+- Removed `progress` property from `Index` type
+
+  This property is only available when fetching indexes with the `withHidden`
+  option set to `true`.
+
+- Added `HiddenIndex` type (DE-849)
+
+  This type is used to represent an index returned by `collection.indexes` when
+  the `withHidden` option is set to `true` and includes the `progress` property
+  in addition to internal indexes.
+
 ## [9.0.0] - 2024-07-31
 
 This is a major release and breaks backwards compatibility.
@@ -1904,6 +1919,7 @@ For a detailed list of changes between pre-release versions of v7 see the
 
   Graph methods now only return the relevant part of the response body.
 
+[unreleased]: https://github.com/arangodb/arangojs/compare/v9.0.0...HEAD
 [9.0.0]: https://github.com/arangodb/arangojs/compare/v8.8.1...v9.0.0
 [8.8.1]: https://github.com/arangodb/arangojs/compare/v8.8.0...v8.8.1
 [8.8.0]: https://github.com/arangodb/arangojs/compare/v8.7.0...v8.8.0
diff --git a/src/collection.ts b/src/collection.ts
index edb9aa65f..79599e7b9 100644
--- a/src/collection.ts
+++ b/src/collection.ts
@@ -41,6 +41,7 @@ import {
   MdiIndex,
   _indexHandle,
   EnsureIndexOptions,
+  HiddenIndex,
 } from "./indexes.js";
 import { COLLECTION_NOT_FOUND, DOCUMENT_NOT_FOUND } from "./lib/codes.js";
 
@@ -978,8 +979,11 @@ export type IndexListOptions = {
    */
   withStats?: boolean;
   /**
-   * If set to `true`, includes indexes that are not yet fully built but are
-   * in the building phase.
+   * If set to `true`, includes internal indexes as well as indexes that are
+   * not yet fully built but are in the building phase.
+   *
+   * You should cast the resulting indexes to `HiddenIndex` to ensure internal
+   * and incomplete indexes are accurately represented.
    *
    * Default: `false`.
    */
@@ -1879,8 +1883,19 @@ export interface DocumentCollection<
    * const collection = db.collection("some-collection");
    * const indexes = await collection.indexes();
    * ```
+   *
+   * @example
+   * ```js
+   * const db = new Database();
+   * const collection = db.collection("some-collection");
+   * const allIndexes = await collection.indexes<HiddenIndex>({
+   *   withHidden: true
+   * });
+   * ```
    */
-  indexes(options?: IndexListOptions): Promise<Index[]>;
+  indexes<IndexType extends Index | HiddenIndex = Index>(
+    options?: IndexListOptions
+  ): Promise<IndexType[]>;
   /**
    * Returns an index description by name or `id` if it exists.
    *
diff --git a/src/indexes.ts b/src/indexes.ts
index 8c824ea28..4324b0ef0 100644
--- a/src/indexes.ts
+++ b/src/indexes.ts
@@ -553,10 +553,6 @@ export type GenericIndex = {
    * Additional stats about this index.
    */
   figures?: Record<string, any>;
-  /**
-   * Progress of this index if it is still being created.
-   */
-  progress?: number;
 };
 
 /**
@@ -670,6 +666,21 @@ export type InvertedIndex = GenericIndex & {
   optimizeTopK: string[];
 };
 
+/**
+ * An object representing an arangosearch index.
+ */
+export type InternalArangosearchIndex = {
+  id: string;
+  type: "arangosearch";
+  view: string;
+  figures?: Record<string, any>;
+  analyzers: string[];
+  fields: Record<string, Record<string, any>>;
+  includeAllFields: boolean;
+  trackListPositions: boolean;
+  storeValues: "none" | "id";
+};
+
 /**
  * An object representing an index.
  */
@@ -681,6 +692,33 @@ export type Index =
   | MdiIndex
   | InvertedIndex;
 
+/**
+ * An object representing an internal index.
+ */
+export type InternalIndex = InternalArangosearchIndex;
+
+/**
+ * An object representing a potentially hidden index.
+ *
+ * This type can be used to cast the result of `collection.indexes` to better
+ * reflect the actual data returned by the server when using the `withHidden`
+ * option:
+ *
+ * ```ts
+ * const indexes = await collection.indexes<HiddenIndex>({
+ *   withHidden: true
+ * }));
+ * // indexes may include internal indexes and indexes with a "progress"
+ * // property
+ * ```
+ */
+export type HiddenIndex = (Index | InternalArangosearchIndex) & {
+  /**
+   * Progress of this index if it is still being created.
+   */
+  progress?: number;
+};
+
 export type IndexDetails = Index & {
   figures?: Record<string, any>;
   progress?: number;
diff --git a/typedoc.json b/typedoc.json
index 5ae0ebfe9..9749391b2 100644
--- a/typedoc.json
+++ b/typedoc.json
@@ -15,7 +15,7 @@
   "excludeProtected": true,
   "excludePrivate": true,
   "includeVersion": false,
-  "entryPoints": "src",
+  "entryPoints": ["src"],
   "entryPointStrategy": "expand",
   "validation": {
     "notExported": true,