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);
+ });
+ });
 });