findAvailableRegions implementation + documentation (#111)

* findAvailableRegions implementation + documentation

* update AstraFindAvailableRegionsOptions to use CommandOptions instead of WithTimeout

* add integration test for findAvailableRegions

Author: toptobes

src/administration/astra-admin.ts

@@ -17,6 +17,7 @@ import type {
   AstraDatabaseConfig,
   CreateAstraDatabaseOptions,
   ListAstraDatabasesOptions,
+  AstraAvailableRegionInfo, AstraFindAvailableRegionsOptions,
 } from '@/src/administration/types/index.js';
 import { AstraDbAdmin } from '@/src/administration/astra-db-admin.js';
 import { Db } from '@/src/db/db.js';
@@ -471,6 +472,71 @@ export class AstraAdmin extends HierarchicalLogger<AdminCommandEventMap> {
     });
   }
 
+  /**
+   * ##### Overview
+   *
+   * Finds available regions for Astra database deployments.
+   *
+   * The returned information includes details about each region such as its cloud provider,
+   * classification tier, geographic zone, and availability status.
+   *
+   * @example
+   * ```ts
+   * // Find all regions enabled for the current organization (default)
+   * const enabledRegions = await admin.findAvailableRegions();
+   *
+   * // Find AWS regions in North America
+   * const awsNaRegions = allRegions
+   *   .filter(r => r.cloudProvider === 'AWS' && r.zone === 'na');
+   * ```
+   *
+   * ---
+   *
+   * ##### Including non-org-enabled regions
+   *
+   * By default, it returns only regions that are enabled for the current organization, but this behavior can be controlled with the {@link AstraFindAvailableRegionsOptions.onlyOrgEnabledRegions} option.
+   *
+   * @example
+   * ```ts
+   * // Find all regions, including those not enabled for the current organization
+   * const allRegions = await admin.findAvailableRegions({
+   *   onlyOrgEnabledRegions: false,
+   * });
+   * ```
+   *
+   * @param options - Options for filtering the regions to return
+   *
+   * @returns A promise that resolves to an array of the region information
+   *
+   * @see AstraAvailableRegionInfo
+   * @see AstraRegionClassification
+   */
+  public async findAvailableRegions(options?: AstraFindAvailableRegionsOptions): Promise<AstraAvailableRegionInfo[]> {
+    const tm = this.#httpClient.tm.single('databaseAdminTimeoutMs', options);
+
+    const filterByOrg = options?.onlyOrgEnabledRegions !== false ? 'enabled' : 'disabled';
+
+    const resp = await this.#httpClient.request({
+      method: HttpMethods.Get,
+      path: '/regions/serverless',
+      params: {
+        'filter-by-org': filterByOrg,
+        'region-type': 'vector',
+      },
+      methodName: 'admin.findAvailableRegions',
+    }, tm);
+
+    return resp.data!.map((region: any): AstraAvailableRegionInfo => ({
+      classification: region.classification,
+      cloudProvider: region.cloudProvider,
+      displayName: region.displayName,
+      enabled: region.enabled,
+      name: region.name,
+      reservedForQualifiedUsers: region.reservedForQualifiedUsers,
+      zone: region.zone,
+    }));
+  }
+
   public get _httpClient(): OpaqueHttpClient {
     return this.#httpClient;
   }

src/administration/types/admin/find-available-regions.ts

@@ -0,0 +1,158 @@
+// Copyright DataStax, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { AstraDatabaseCloudProvider } from './admin-common.js';
+import type { CommandOptions } from '@/src/lib/index.js';
+
+/**
+ * ##### Overview
+ *
+ * The options for {@link AstraAdmin.findAvailableRegions}.
+ *
+ * @example
+ * ```ts
+ * const regions = await admin.findAvailableRegions({
+ *   onlyOrgEnabledRegions: false,
+ * });
+ * ```
+ *
+ * @see AstraAdmin.findAvailableRegions
+ * @see AstraAvailableRegionInfo
+ * 
+ * @public
+ */
+export interface AstraFindAvailableRegionsOptions extends CommandOptions<{ timeout: 'databaseAdminTimeoutMs' }> {
+  /**
+   * Whether to only return regions that are enabled for the current organization.
+   *
+   * - When `true` or unset: only returns regions enabled for the current organization.
+   * - When `false`: returns all available regions, including those not enabled for the organization.
+   *
+   * Note that the organization is determined by the token used to authenticate the request.
+   *
+   * Defaults to `true`.
+   */
+  onlyOrgEnabledRegions?: boolean,
+}
+
+/**
+ * ##### Overview
+ * 
+ * Represents the classification tier of an Astra database region.
+ *
+ * Region availability will depend on the user's account level.
+ *
+ * @see AstraAvailableRegionInfo
+ *
+ * @public
+ */
+export type AstraRegionClassification = 'standard' | 'premium' | 'premium_plus';
+
+/**
+ * ##### Overview
+ * 
+ * Represents the geographic zone where an Astra database region is located.
+ * 
+ * - `'na'`: North America
+ * - `'emea'`: Europe, Middle East, and Africa
+ * - `'apac'`: Asia Pacific
+ * - `'sa'`: South America
+ *
+ * @see AstraAvailableRegionInfo
+ * 
+ * @public
+ */
+export type AstraRegionZone = 'na' | 'apac' | 'emea' | 'sa';
+
+/**
+ * ##### Overview
+ * 
+ * Information about an available region for Astra database deployments.
+ * 
+ * This provides details about each available region including classification, cloud provider, display name, and availability status.
+ * 
+ * @example
+ * ```ts
+ * // Basic usage
+ * const regions = await admin.findAvailableRegions();
+ * console.log(regions[0].displayName); // 'Moncks Corner, South Carolina'
+ * 
+ * // Further filterting & transformation may be done using native list methods
+ * const awsRegions = regions.filter(region => region.cloudProvider === 'AWS');
+ * ```
+ *
+ * @see AstraAdmin.findAvailableRegions
+ * @see AstraFindAvailableRegionsOptions
+ *
+ * @public
+ */
+export interface AstraAvailableRegionInfo {
+  /**
+   * Represents the classification tier of an Astra database region.
+   *
+   * Region availability will depend on the user's account level.
+   *
+   * @example
+   * ```ts
+   * 'standard'
+   * ```
+   */
+  classification: AstraRegionClassification,
+  /**
+   * The cloud provider hosting this region.
+   *
+   * @example
+   * ```ts
+   * 'GCP'
+   * ```
+   */
+  cloudProvider: AstraDatabaseCloudProvider,
+  /**
+   * A human-readable display name for the region.
+   *
+   * @example
+   * ```ts
+   * 'Moncks Corner, South Carolina'
+   * ```
+   */
+  displayName: string,
+  /**
+   * Whether this region is currently enabled for use.
+   *
+   * > **✏️Note:** If {@link AstraFindAvailableRegionsOptions.onlyOrgEnabledRegions} is `false`, and `enabled` is still `true`, it does not guarantee that the region is usable by the current organization.
+   */
+  enabled: boolean,
+  /**
+   * The unique identifier for the region.
+   *
+   * @example
+   * ```ts
+   * 'us-east1'
+   * ```
+   */
+  name: string,
+  /**
+   * Whether this region is reserved for qualified users only, meaning special access is required to use it.
+   */
+  reservedForQualifiedUsers: boolean,
+  /**
+   * The geographic zone where this region is located.
+   *
+   * @example
+   * ```ts
+   * 'na'
+   * ```
+   */
+  zone: AstraRegionZone,
+}

src/administration/types/index.ts

@@ -17,6 +17,7 @@ export type * from './admin/create-database.js';
 export type * from './admin/drop-database.js';
 export type * from './admin/database-info.js';
 export type * from './admin/list-databases.js';
+export type * from './admin/find-available-regions.js';
 export type * from './db-admin/astra-create-keyspace.js';
 export type * from './db-admin/astra-drop-keyspace.js';
 export type * from './db-admin/local-create-keyspace.js';

src/documents/types/common.ts

@@ -85,7 +85,8 @@ export type Projection = Record<string, 1 | 0 | boolean | ProjectionSlice>;
  * Specifies the number of elements in an array to return in the query result.
  *
  * Has one of the following forms:
- * ```
+ *
+ * ```ts
  * // Return the first two elements
  * { $slice: 2 }
  *

tests/integration/administration/astra-admin.test.ts

@@ -14,13 +14,39 @@
 // noinspection DuplicatedCode
 
 import { describe, it } from '@/tests/testlib/index.js';
+import type { AstraAvailableRegionInfo } from '@/src/index.js';
 import { DataAPIClient, DevOpsAPIResponseError } from '@/src/index.js';
 import assert from 'assert';
 
-describe('integration.administration.astra-admin', () => {
+describe('(ASTRA) integration.administration.astra-admin', ({ admin }) => {
   it('should not stop you from creating an AstraAdmin without a token', async () => {
     const client = new DataAPIClient();
     const admin = client.admin();
     await assert.rejects(() => admin.listDatabases(), DevOpsAPIResponseError);
   });
+
+  describe('findAvailableRegions', () => {
+    it('should work', async () => {
+      const verifyStructure = (region: AstraAvailableRegionInfo) => {
+        assert.ok(region);
+        assert.ok(['standard', 'premium', 'premium_plus'].includes(region.classification));
+        assert.ok(['AWS', 'GCP', 'AZURE'].includes(region.cloudProvider));
+        assert.ok(typeof region.displayName as unknown === 'string');
+        assert.ok(typeof region.enabled as unknown === 'boolean');
+        assert.ok(typeof region.name as unknown === 'string');
+        assert.ok(typeof region.reservedForQualifiedUsers as unknown === 'boolean');
+        assert.ok(['na', 'apac', 'emea', 'sa'].includes(region.zone));
+      };
+
+      const regions = await admin.findAvailableRegions();
+      assert.ok(regions.length);
+      regions.forEach(verifyStructure);
+
+      const allRegions = await admin.findAvailableRegions({ onlyOrgEnabledRegions: false });
+      assert.ok(allRegions.length);
+      allRegions.forEach(verifyStructure);
+
+      assert.ok(regions.length < allRegions.length);
+    });
+  });
 });