feat: Collection aliasing

src/alias/index.ts

@@ -0,0 +1,79 @@
+import { ConnectionREST } from '../index.js';
+import { WeaviateAlias, WeaviateAliasResponse } from '../openapi/types.js';
+import { Alias, AliasListAllOptions, CreateAliasArgs, UpdateAliasArgs } from './types.js';
+
+export interface Aliases {
+  /**
+   * Create alias for a collection.
+   *
+   * The collection must exist prior to aliasing it.
+   * One alias cannot be created for multiple collections simultaneously.
+   *
+   * @param {string} args.collection Original collection name.
+   * @param {string} args.alias Alias for collection.
+   * @returns {Promise<void>} Awaitable promise.
+   * */
+  create: (args: CreateAliasArgs) => Promise<void>;
+
+  /**
+   * List all aliases defined in the schema.
+   *
+   * @param {string | undefined} [opts.collection] Get all aliases defined for this collection.
+   * @returns {Promise<Alias[] | undefined>} An array of aliases.
+   */
+  listAll: (opts?: AliasListAllOptions) => Promise<Alias[] | undefined>;
+
+  /**
+   * Get information about an alias.
+   *
+   * @param {string} alias Alias to fetch.
+   * @return {Promise<Alias>} Alias definition.
+   */
+  get: (alias: string) => Promise<Alias>;
+
+  /**
+   * Replace target collection the alias points to.
+   *
+   * To change the alias that points to the collection,
+   * delete the alias and create a new one.
+   *
+   * @param {string} args.alias Alias to update.
+   * @param {string} args.collection New collection the alias should point to.
+   * @return {Promise<void>} Awaitable promise.
+   */
+  update: (args: UpdateAliasArgs) => Promise<void>;
+
+  /**
+   * Delete a collection alias.
+   *
+   * @param {string} alias Alias definition to delete.
+   * @return {Promise<void>} Awaitable promise.
+   */
+  delete: (alias: string) => Promise<void>;
+}
+
+const alias = (connection: ConnectionREST): Aliases => {
+  return {
+    create: (args: CreateAliasArgs) =>
+      connection.postReturn<WeaviateAlias, void>(`/aliases/`, { ...args, class: args.collection }),
+    listAll: (opts?: AliasListAllOptions) =>
+      connection
+        .get<WeaviateAliasResponse>(
+          `/aliases${opts?.collection !== undefined ? '/?class=' + opts.collection : ''}`
+        )
+        .then((aliases) =>
+          aliases.aliases !== undefined
+            ? aliases.aliases.map((alias) => ({ alias: alias.alias, collection: alias.class }))
+            : []
+        ),
+    get: (alias: string) =>
+      connection
+        .get<WeaviateAlias>(`/aliases/${alias}`)
+        .then((alias) => ({ alias: alias.alias!, collection: alias.class! })),
+    update: (args: UpdateAliasArgs) =>
+      connection.put(`/aliases/${args.alias}`, { class: args.newTargetCollection }),
+    delete: (alias: string) => connection.delete(`/aliases/${alias}`, null),
+  };
+};
+
+export default alias;

src/alias/journey.test.ts

@@ -0,0 +1,53 @@
+import weaviate, { WeaviateClient } from '..';
+import { requireAtLeast } from '../../test/version';
+import { Alias } from './types';
+
+requireAtLeast(1, 32, 0).describe('manages collection aliases', () => {
+  let client: WeaviateClient;
+  const collectionsWithAliases = ['PaulHewson', 'GeorgeBarnes', 'ColsonBaker'];
+
+  beforeAll(async () => {
+    client = await weaviate.connectToLocal();
+    await Promise.all(collectionsWithAliases.map(client.collections.delete));
+    await Promise.all(collectionsWithAliases.map((name) => client.collections.create({ name })));
+  });
+
+  it('should create alias', () => {
+    return Promise.all([
+      client.alias.create({ collection: 'PaulHewson', alias: 'Bono' }),
+      client.alias.create({ collection: 'GeorgeBarnes', alias: 'MachineGunKelly' }),
+    ])
+      .then(() => client.alias.listAll())
+      .then((aliases) => {
+        expect(aliases).not.toBeUndefined();
+        expect(aliases).toHaveLength(2);
+        expect(aliases).toEqual<Alias[]>([
+          { collection: 'PaulHewson', alias: 'Bono' },
+          { collection: 'GeorgeBarnes', alias: 'MachineGunKelly' },
+        ]);
+      });
+  });
+
+  it('should update alias', () => {
+    return client.alias
+      .update({ alias: 'MachineGunKelly', newTargetCollection: 'ColsonBaker' })
+      .then(() => client.alias.get('MachineGunKelly'))
+      .then((alias) => {
+        expect(alias.collection).toEqual('ColsonBaker');
+      });
+  });
+
+  it('should delete alias Bono', () => {
+    return client.alias
+      .delete('Bono')
+      .then(() => client.alias.listAll({ collection: 'PaulHewson' }))
+      .then((aliases) => expect(aliases).toEqual([]));
+  });
+
+  it('should delete alias MachineGunKelly', () => {
+    return client.alias
+      .delete('MachineGunKelly')
+      .then(() => client.alias.listAll({ collection: 'ColsonBaker' }))
+      .then((aliases) => expect(aliases).toEqual([]));
+  });
+});

src/alias/types.ts

@@ -0,0 +1,18 @@
+export type Alias = {
+  collection: string;
+  alias: string;
+};
+
+export type CreateAliasArgs = {
+  collection: string;
+  alias: string;
+};
+
+export type UpdateAliasArgs = {
+  newTargetCollection: string;
+  alias: string;
+};
+
+export type AliasListAllOptions = {
+  collection?: string | undefined;
+};

src/index.ts

@@ -38,6 +38,7 @@ import { LiveChecker, OpenidConfigurationGetter, ReadyChecker } from './misc/ind
 
 import weaviateV2 from './v2/index.js';
 
+import alias, { Aliases } from './alias/index.js';
 import filter from './collections/filters/index.js';
 import { ConsistencyLevel } from './data/replication.js';
 import users, { Users } from './users/index.js';
@@ -102,6 +103,7 @@ export type ClientParams = {
 };
 
 export interface WeaviateClient {
+  alias: Aliases;
   backup: Backup;
   cluster: Cluster;
   collections: Collections;
@@ -224,6 +226,7 @@ async function client(params: ClientParams): Promise<WeaviateClient> {
   });
 
   const ifc: WeaviateClient = {
+    alias: alias(connection),
     backup: backup(connection),
     cluster: cluster(connection),
     collections: collections(connection, dbVersionSupport),