Fix DE-849: Add HiddenIndex type

Author: pluma

.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"
   }

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

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.
    *

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;

typedoc.json

@@ -15,7 +15,7 @@
   "excludeProtected": true,
   "excludePrivate": true,
   "includeVersion": false,
-  "entryPoints": "src",
+  "entryPoints": ["src"],
   "entryPointStrategy": "expand",
   "validation": {
     "notExported": true,