Make breaking change to introduce ACTIVE/INACTIVE in returns but allow HOT/COLD in create/update

Author: tsmith023

src/collections/deserialize/index.ts

@@ -305,9 +305,9 @@ export class Deserialize {
   private static activityStatusGRPC(status: TenantActivityStatus): Tenant['activityStatus'] {
     switch (status) {
       case TenantActivityStatus.TENANT_ACTIVITY_STATUS_COLD:
-        return 'COLD';
+        return 'INACTIVE';
       case TenantActivityStatus.TENANT_ACTIVITY_STATUS_HOT:
-        return 'HOT';
+        return 'ACTIVE';
       case TenantActivityStatus.TENANT_ACTIVITY_STATUS_FROZEN:
         return 'OFFLOADED';
       case TenantActivityStatus.TENANT_ACTIVITY_STATUS_FREEZING:
@@ -322,15 +322,17 @@ export class Deserialize {
   public static activityStatusREST(status: TenantREST['activityStatus']): Tenant['activityStatus'] {
     switch (status) {
       case 'COLD':
-        return 'COLD';
+        return 'INACTIVE';
       case 'HOT':
-        return 'HOT';
+        return 'ACTIVE';
       case 'FROZEN':
         return 'OFFLOADED';
       case 'FREEZING':
         return 'OFFLOADING';
       case 'UNFREEZING':
         return 'ONLOADING';
+      case undefined:
+        return 'ACTIVE';
       default:
         throw new Error(`Unsupported tenant activity status: ${status}`);
     }

src/collections/query/integration.test.ts

@@ -909,7 +909,7 @@ describe('Testing of the collection.query methods with a multi-tenancy collectio
     expect(obj2.objects[0].uuid).toEqual(id2);
   });
 
-  it.skip('should find the objects in their tenants by nearObject', async () => {
+  it('should find the objects in their tenants by nearObject', async () => {
     const obj1 = await collection.withTenant(tenantOne).query.nearObject(id1);
     const obj2 = await collection.withTenant(tenantTwo).query.nearObject(id2);
     expect(obj1.objects.length).toEqual(1);

src/collections/serialize/index.ts

@@ -1,5 +1,5 @@
 import { v4 as uuidv4 } from 'uuid';
-import { TenantActivityStatus, WhereFilter } from '../../openapi/types.js';
+import { WhereFilter } from '../../openapi/types.js';
 import {
   BatchObject as BatchObjectGRPC,
   BatchObject_MultiTargetRefProps,
@@ -82,7 +82,7 @@ import {
 import { ReferenceGuards } from '../references/classes.js';
 import { Beacon } from '../references/index.js';
 import { uuidToBeacon } from '../references/utils.js';
-import { Tenant, TenantCreate, TenantUpdate } from '../tenants/types.js';
+import { TenantBC, TenantCreate, TenantUpdate } from '../tenants/types.js';
 import {
   BatchObject,
   BatchObjects,
@@ -1137,11 +1137,11 @@ export class Serialize {
     });
   };
 
-  public static tenantsCreate(tenant: Tenant | TenantCreate): {
+  public static tenantsCreate(tenant: TenantBC | TenantCreate): {
     name: string;
     activityStatus?: 'HOT' | 'COLD';
   } {
-    let activityStatus: TenantActivityStatus;
+    let activityStatus: 'HOT' | 'COLD' | undefined;
     switch (tenant.activityStatus) {
       case 'ACTIVE':
         activityStatus = 'HOT';
@@ -1154,17 +1154,13 @@ export class Serialize {
       case undefined:
         activityStatus = tenant.activityStatus;
         break;
-      case 'OFFLOADED':
-        throw new WeaviateInvalidInputError(
-          'Cannot create a tenant with activity status OFFLOADED. Add objects to the tenant first and then you can update it to OFFLOADED.'
-        );
-      case 'OFFLOADING':
+      case 'FROZEN':
         throw new WeaviateInvalidInputError(
-          'Cannot create a tenant with activity status OFFLOADING. This status is a read-only value that the server sets in the processing of making a tenant OFFLOADED.'
+          'Invalid activity status. Please provide one of the following: ACTIVE, INACTIVE, HOT, COLD.'
         );
-      case 'ONLOADING':
+      default:
         throw new WeaviateInvalidInputError(
-          'Cannot create a tenant with activity status ONLOADING. This status is a read-only value that the server sets in the processing of making a tenant HOT.'
+          'Invalid activity status. Please provide one of the following: ACTIVE, INACTIVE, HOT, COLD.'
         );
     }
     return {
@@ -1174,9 +1170,9 @@ export class Serialize {
   }
 
   public static tenantUpdate = (
-    tenant: Tenant | TenantUpdate
+    tenant: TenantBC | TenantUpdate
   ): { name: string; activityStatus: 'HOT' | 'COLD' | 'FROZEN' } => {
-    let activityStatus: TenantActivityStatus;
+    let activityStatus: 'HOT' | 'COLD' | 'FROZEN';
     switch (tenant.activityStatus) {
       case 'ACTIVE':
         activityStatus = 'HOT';
@@ -1189,15 +1185,12 @@ export class Serialize {
         break;
       case 'HOT':
       case 'COLD':
+      case 'FROZEN':
         activityStatus = tenant.activityStatus;
         break;
-      case 'OFFLOADING':
-        throw new WeaviateInvalidInputError(
-          'Cannot create a tenant with activity status OFFLOADING. This status is a read-only value that the server sets in the processing of making a tenant OFFLOADED.'
-        );
-      case 'ONLOADING':
+      default:
         throw new WeaviateInvalidInputError(
-          'Cannot create a tenant with activity status ONLOADING. This status is a read-only value that the server sets in the processing of making a tenant HOT.'
+          'Invalid activity status. Please provide one of the following: ACTIVE, INACTIVE, HOT, COLD, OFFLOADED.'
         );
     }
     return {

src/collections/tenants/index.ts

@@ -1,10 +1,11 @@
 import { ConnectionGRPC } from '../../connection/index.js';
 import { WeaviateUnsupportedFeatureError } from '../../errors.js';
+import { Tenant as TenantREST } from '../../openapi/types.js';
 import { TenantsCreator, TenantsDeleter, TenantsGetter, TenantsUpdater } from '../../schema/index.js';
 import { DbVersionSupport } from '../../utils/dbVersion.js';
 import { Deserialize } from '../deserialize/index.js';
 import { Serialize } from '../serialize/index.js';
-import { Tenant, TenantBase, TenantCreate, TenantUpdate } from './types.js';
+import { Tenant, TenantBC, TenantBase, TenantCreate, TenantUpdate } from './types.js';
 
 const checkSupportForGRPCTenantsGetEndpoint = async (dbVersionSupport: DbVersionSupport) => {
   const check = await dbVersionSupport.supportsTenantsGetGRPCMethod();
@@ -16,6 +17,13 @@ const parseValueOrValueArray = <V>(value: V | V[]) => (Array.isArray(value) ? va
 const parseStringOrTenant = <T extends TenantBase>(tenant: string | T) =>
   typeof tenant === 'string' ? tenant : tenant.name;
 
+const parseTenantREST = (tenant: TenantREST): Tenant => {
+  return {
+    name: tenant.name!,
+    activityStatus: Deserialize.activityStatusREST(tenant.activityStatus),
+  };
+};
+
 const tenants = (
   connection: ConnectionGRPC,
   collection: string,
@@ -31,20 +39,15 @@ const tenants = (
       const result: Record<string, Tenant> = {};
       tenants.forEach((tenant) => {
         if (!tenant.name) return;
-        result[tenant.name] = {
-          name: tenant.name!,
-          activityStatus: Deserialize.activityStatusREST(tenant.activityStatus),
-        };
+        result[tenant.name] = parseTenantREST(tenant);
       });
       return result;
     });
   return {
-    create: (tenants: Tenant | TenantCreate | (Tenant | TenantCreate)[]) =>
-      new TenantsCreator(
-        connection,
-        collection,
-        parseValueOrValueArray(tenants).map(Serialize.tenantsCreate)
-      ).do() as Promise<Tenant[]>,
+    create: (tenants: TenantBC | TenantCreate | (TenantBC | TenantCreate)[]) =>
+      new TenantsCreator(connection, collection, parseValueOrValueArray(tenants).map(Serialize.tenantsCreate))
+        .do()
+        .then((res) => res.map(parseTenantREST)),
     get: async function () {
       const check = await dbVersionSupport.supportsTenantsGetGRPCMethod();
       return check.supports ? getGRPC() : getREST();
@@ -60,12 +63,10 @@ const tenants = (
         collection,
         parseValueOrValueArray(tenants).map(parseStringOrTenant)
       ).do(),
-    update: (tenants: Tenant | TenantUpdate | (Tenant | TenantUpdate)[]) =>
-      new TenantsUpdater(
-        connection,
-        collection,
-        parseValueOrValueArray(tenants).map(Serialize.tenantUpdate)
-      ).do() as Promise<Tenant[]>,
+    update: (tenants: TenantBC | TenantUpdate | (TenantBC | TenantUpdate)[]) =>
+      new TenantsUpdater(connection, collection, parseValueOrValueArray(tenants).map(Serialize.tenantUpdate))
+        .do()
+        .then((res) => res.map(parseTenantREST)),
   };
 };
 
@@ -97,10 +98,10 @@ export interface Tenants {
    *
    * For details on the new activity statuses, see the docstring for the `Tenants` interface type.
    *
-   * @param {Tenant | TenantCreate | (Tenant | TenantCreate)[]} tenants The tenant or tenants to create.
+   * @param {TenantCreate | TenantCreate[]} tenants The tenant or tenants to create.
    * @returns {Promise<Tenant[]>} The created tenant(s) as a list of Tenant.
    */
-  create: (tenants: Tenant | TenantCreate | (Tenant | TenantCreate)[]) => Promise<Tenant[]>;
+  create: (tenants: TenantBC | TenantCreate | (TenantBC | TenantCreate)[]) => Promise<Tenant[]>;
   /**
    * Return all tenants currently associated with a collection in Weaviate.
    * The collection must have been created with multi-tenancy enabled.
@@ -152,5 +153,5 @@ export interface Tenants {
    * @param {TenantInput | TenantInput[]} tenants The tenant or tenants to update.
    * @returns {Promise<Tenant[]>} The updated tenant(s) as a list of Tenant.
    */
-  update: (tenants: Tenant | TenantUpdate | (Tenant | TenantUpdate)[]) => Promise<Tenant[]>;
+  update: (tenants: TenantBC | TenantUpdate | (TenantBC | TenantUpdate)[]) => Promise<Tenant[]>;
 }

src/collections/tenants/integration.test.ts

@@ -38,23 +38,23 @@ describe('Testing of the collection.tenants methods', () => {
     const result = await collection.tenants.create([{ name: tenant, activityStatus: 'HOT' }]);
     expect(result.length).toBe(1);
     expect(result[0].name).toBe(tenant);
-    expect(result[0].activityStatus).toBe('HOT');
+    expect(result[0].activityStatus).toBe('ACTIVE');
   });
 
   it('should be able to create a tenant with new nomenclature', async () => {
     const tenant = 'tenant';
     const result = await collection.tenants.create([{ name: tenant, activityStatus: 'ACTIVE' }]);
     expect(result.length).toBe(1);
     expect(result[0].name).toBe(tenant);
-    expect(result[0].activityStatus).toBe('HOT');
+    expect(result[0].activityStatus).toBe('ACTIVE');
   });
 
   it('should be able to get existing tenants', async () => {
     const result = await collection.tenants.get();
 
     expect(result).toHaveProperty('hot');
     expect(result.hot.name).toBe('hot');
-    expect(result.hot.activityStatus).toBe('HOT');
+    expect(result.hot.activityStatus).toBe('ACTIVE');
 
     expect(result).toHaveProperty('cold');
     expect(result.cold.name).toBe('cold');
@@ -72,14 +72,14 @@ describe('Testing of the collection.tenants methods', () => {
     const result = await collection.tenants.update([{ name: 'cold', activityStatus: 'HOT' }]);
     expect(result.length).toBe(1);
     expect(result[0].name).toBe('cold');
-    expect(result[0].activityStatus).toBe('HOT');
+    expect(result[0].activityStatus).toBe('ACTIVE');
   });
 
   it('should be able to update a tenant with new nomenclature', async () => {
     const result = await collection.tenants.update([{ name: 'cold-new', activityStatus: 'ACTIVE' }]);
     expect(result.length).toBe(1);
     expect(result[0].name).toBe('cold-new');
-    expect(result[0].activityStatus).toBe('HOT');
+    expect(result[0].activityStatus).toBe('ACTIVE');
   });
 
   describe('getByName and getByNames', () => {
@@ -91,7 +91,7 @@ describe('Testing of the collection.tenants methods', () => {
       }
       const result = await query();
       expect(result).toHaveProperty('name', 'hot');
-      expect(result).toHaveProperty('activityStatus', 'HOT');
+      expect(result).toHaveProperty('activityStatus', 'ACTIVE');
     });
 
     it('should be able to get a tenant by tenant object', async () => {
@@ -102,7 +102,7 @@ describe('Testing of the collection.tenants methods', () => {
       }
       const result = await query();
       expect(result).toHaveProperty('name', 'hot');
-      expect(result).toHaveProperty('activityStatus', 'HOT');
+      expect(result).toHaveProperty('activityStatus', 'ACTIVE');
     });
 
     it('should fail to get a non-existing tenant', async () => {

src/collections/tenants/types.ts

@@ -23,17 +23,20 @@ export type TenantsGetOptions = {
 
 /**
  * The expected type returned by all tenant methods.
- *
- * WARNING: The `COLD` and `HOT` statuses are deprecated and will be replaced in a future release.
- * See the docstring for the `activityStatus` field in this type for more information.
  */
 export type Tenant = TenantBase & {
-  /**
-   * `COLD` and `HOT` are included for backwards compatability purposes and are deprecated.
-   *
-   * In a future release, these will be removed in favour of the new statuses as so:
-   * - `HOT` -> `ACTIVE`
-   * - `COLD` -> `INACTIVE`
+  /** There are two statuses that are immutable: `OFFLOADED` and `ONLOADING, which are set by the server:
+   * - `ONLOADING`, which means the tenant is transitioning from the `OFFLOADED` status to `ACTIVE/INACTIVE`.
+   * - `OFFLOADING`, which means the tenant is transitioning from `ACTIVE/INACTIVE` to the `OFFLOADED` status.
+   * The other three statuses are mutable within the `.create` and `.update`, methods:
+   * - `ACTIVE`, which means loaded fully into memory and ready for use.
+   * - `INACTIVE`, which means not loaded into memory with files stored on disk.
+   * - `OFFLOADED`, which means not loaded into memory with files stored on the cloud.
    */
-  activityStatus: 'COLD' | 'HOT' | 'OFFLOADED' | 'OFFLOADING' | 'ONLOADING';
+  activityStatus: 'ACTIVE' | 'INACTIVE' | 'OFFLOADED' | 'OFFLOADING' | 'ONLOADING';
+};
+
+/** This is the type of the Tenant as defined in Weaviate's OpenAPI schema. It is included here for Backwards Compatibility. */
+export type TenantBC = TenantBase & {
+  activityStatus?: 'HOT' | 'COLD' | 'FROZEN';
 };

src/collections/tenants/unit.test.ts

@@ -84,8 +84,8 @@ describe('Mock testing of tenants.get() method with a REST server', () => {
     const collection = client.collections.get(TENANTS_COLLECTION_NAME);
     const tenants = await collection.tenants.get();
     expect(tenants).toEqual<Record<string, Tenant>>({
-      hot: { name: 'hot', activityStatus: 'HOT' },
-      cold: { name: 'cold', activityStatus: 'COLD' },
+      hot: { name: 'hot', activityStatus: 'ACTIVE' },
+      cold: { name: 'cold', activityStatus: 'INACTIVE' },
       frozen: { name: 'frozen', activityStatus: 'OFFLOADED' },
       freezing: { name: 'freezing', activityStatus: 'OFFLOADING' },
       unfreezing: { name: 'unfreezing', activityStatus: 'ONLOADING' },
@@ -110,8 +110,8 @@ describe('Mock testing of tenants.get() method with a gRPC server', () => {
     const collection = client.collections.get(TENANTS_COLLECTION_NAME);
     const tenants = await collection.tenants.get();
     expect(tenants).toEqual<Record<string, Tenant>>({
-      hot: { name: 'hot', activityStatus: 'HOT' },
-      cold: { name: 'cold', activityStatus: 'COLD' },
+      hot: { name: 'hot', activityStatus: 'ACTIVE' },
+      cold: { name: 'cold', activityStatus: 'INACTIVE' },
       frozen: { name: 'frozen', activityStatus: 'OFFLOADED' },
       freezing: { name: 'freezing', activityStatus: 'OFFLOADING' },
       unfreezing: { name: 'unfreezing', activityStatus: 'ONLOADING' },