feat: add support for vector sets (#2998)

* wip

* improve the vadd api

* resp3 tests

* fix some tests

* extract json helper functions in client package

* use transformJsonReply

* remove the CACHEABLE flag for all vector set commands

currently, client side caching is not supported
for vector set commands by the server

* properly transform vinfo result

* add resp3 test for vlinks

* add more tests for vrandmember

* fix vrem return types

* fix vsetattr return type

* fix vsim_withscores

* implement vlinks_withscores

* set minimum docker image version to 8

* align return types

* add RAW variant for VEMB -> VEMB_RAW

* use the new parseCommand api

Author: nkaradzhov

packages/client/lib/commands/VADD.spec.ts

@@ -0,0 +1,121 @@
+import { strict as assert } from 'node:assert';
+import testUtils, { GLOBAL } from '../test-utils';
+import VADD from './VADD';
+import { BasicCommandParser } from '../client/parser';
+
+describe('VADD', () => {
+  describe('parseCommand', () => {
+    it('basic usage', () => {
+      const parser = new BasicCommandParser();
+      VADD.parseCommand(parser, 'key', [1.0, 2.0, 3.0], 'element');
+      assert.deepEqual(
+        parser.redisArgs,
+        ['VADD', 'key', 'VALUES', '3', '1', '2', '3', 'element']
+      );
+    });
+
+    it('with REDUCE option', () => {
+      const parser = new BasicCommandParser();
+      VADD.parseCommand(parser, 'key', [1.0, 2], 'element', { REDUCE: 50 });
+      assert.deepEqual(
+        parser.redisArgs,
+        ['VADD', 'key', 'REDUCE', '50', 'VALUES', '2', '1', '2', 'element']
+      );
+    });
+
+    it('with quantization options', () => {
+      let parser = new BasicCommandParser();
+      VADD.parseCommand(parser, 'key', [1.0, 2.0], 'element', { QUANT: 'Q8' });
+      assert.deepEqual(
+        parser.redisArgs,
+        ['VADD', 'key', 'VALUES', '2', '1', '2', 'element', 'Q8']
+      );
+
+      parser = new BasicCommandParser();
+      VADD.parseCommand(parser, 'key', [1.0, 2.0], 'element', { QUANT: 'BIN' });
+      assert.deepEqual(
+        parser.redisArgs,
+        ['VADD', 'key', 'VALUES', '2', '1', '2', 'element', 'BIN']
+      );
+
+      parser = new BasicCommandParser();
+      VADD.parseCommand(parser, 'key', [1.0, 2.0], 'element', { QUANT: 'NOQUANT' });
+      assert.deepEqual(
+        parser.redisArgs,
+        ['VADD', 'key', 'VALUES', '2', '1', '2', 'element', 'NOQUANT']
+      );
+    });
+
+    it('with all options', () => {
+      const parser = new BasicCommandParser();
+      VADD.parseCommand(parser, 'key', [1.0, 2.0], 'element', {
+        REDUCE: 50,
+        CAS: true,
+        QUANT: 'Q8',
+        EF: 200,
+        SETATTR: { name: 'test', value: 42 },
+        M: 16
+      });
+      assert.deepEqual(
+        parser.redisArgs,
+        [
+          'VADD', 'key', 'REDUCE', '50', 'VALUES', '2', '1', '2', 'element',
+          'CAS', 'Q8', 'EF', '200', 'SETATTR', '{"name":"test","value":42}', 'M', '16'
+        ]
+      );
+    });
+  });
+
+  testUtils.testAll('vAdd', async client => {
+    assert.equal(
+      await client.vAdd('key', [1.0, 2.0, 3.0], 'element'),
+      true
+    );
+
+    // same element should not be added again
+    assert.equal(
+      await client.vAdd('key', [1, 2 , 3], 'element'),
+      false
+    );
+
+  }, {
+    client: { ...GLOBAL.SERVERS.OPEN, minimumDockerVersion: [8, 0] },
+    cluster: { ...GLOBAL.CLUSTERS.OPEN, minimumDockerVersion: [8, 0] },
+  });
+
+  testUtils.testWithClient('vAdd with RESP3', async client => {
+    // Test basic functionality with RESP3
+    assert.equal(
+      await client.vAdd('resp3-key', [1.5, 2.5, 3.5], 'resp3-element'),
+      true
+    );
+
+    // same element should not be added again
+    assert.equal(
+      await client.vAdd('resp3-key', [1, 2 , 3], 'resp3-element'),
+      false
+    );
+
+    // Test with options to ensure complex parameters work with RESP3
+    assert.equal(
+      await client.vAdd('resp3-key', [4.0, 5.0, 6.0], 'resp3-element2', {
+        QUANT: 'Q8',
+        CAS: true,
+        SETATTR: { type: 'test', value: 123 }
+      }),
+      true
+    );
+
+    // Verify the vector set was created correctly
+    assert.equal(
+      await client.vCard('resp3-key'),
+      2
+    );
+  }, {
+    ...GLOBAL.SERVERS.OPEN,
+    clientOptions: {
+      RESP: 3
+    },
+    minimumDockerVersion: [8, 0]
+  });
+});

packages/client/lib/commands/VADD.ts

@@ -0,0 +1,65 @@
+import { CommandParser } from '../client/parser';
+import { RedisArgument, Command } from '../RESP/types';
+import { transformBooleanReply, transformDoubleArgument } from './generic-transformers';
+
+export interface VAddOptions {
+  REDUCE?: number;
+  CAS?: boolean;
+  QUANT?: 'NOQUANT' | 'BIN' | 'Q8',
+  EF?: number;
+  SETATTR?: Record<string, any>;
+  M?: number;
+}
+
+export default {
+  /**
+   * Add a new element into the vector set specified by key
+   * 
+   * @param parser - The command parser
+   * @param key - The name of the key that will hold the vector set data
+   * @param vector - The vector data as array of numbers
+   * @param element - The name of the element being added to the vector set
+   * @param options - Optional parameters for vector addition
+   * @see https://redis.io/commands/vadd/
+   */
+  parseCommand(
+    parser: CommandParser,
+    key: RedisArgument,
+    vector: Array<number>,
+    element: RedisArgument,
+    options?: VAddOptions
+  ) {
+    parser.push('VADD');
+    parser.pushKey(key);
+
+    if (options?.REDUCE !== undefined) {
+      parser.push('REDUCE', options.REDUCE.toString());
+    }
+
+    parser.push('VALUES', vector.length.toString());
+    for (const value of vector) {
+      parser.push(transformDoubleArgument(value));
+    }
+
+    parser.push(element);
+
+    if (options?.CAS) {
+      parser.push('CAS');
+    }
+
+    options?.QUANT && parser.push(options.QUANT);
+
+    if (options?.EF !== undefined) {
+      parser.push('EF', options.EF.toString());
+    }
+
+    if (options?.SETATTR) {
+      parser.push('SETATTR', JSON.stringify(options.SETATTR));
+    }
+
+    if (options?.M !== undefined) {
+      parser.push('M', options.M.toString());
+    }
+  },
+  transformReply: transformBooleanReply
+} as const satisfies Command;

packages/client/lib/commands/VCARD.spec.ts

@@ -0,0 +1,60 @@
+import { strict as assert } from 'node:assert';
+import testUtils, { GLOBAL } from '../test-utils';
+import VCARD from './VCARD';
+import { BasicCommandParser } from '../client/parser';
+
+describe('VCARD', () => {
+  it('parseCommand', () => {
+    const parser = new BasicCommandParser();
+    VCARD.parseCommand(parser, 'key')
+    assert.deepEqual(
+      parser.redisArgs,
+      ['VCARD', 'key']
+    );
+  });
+
+  testUtils.testAll('vCard', async client => {
+    await client.vAdd('key', [1.0, 2.0, 3.0], 'element1');
+    await client.vAdd('key', [4.0, 5.0, 6.0], 'element2');
+
+    assert.equal(
+      await client.vCard('key'),
+      2
+    );
+
+    assert.equal(await client.vCard('unknown'), 0);
+  }, {
+    client: { ...GLOBAL.SERVERS.OPEN, minimumDockerVersion: [8, 0] },
+    cluster: { ...GLOBAL.CLUSTERS.OPEN, minimumDockerVersion: [8, 0] }
+  });
+
+  testUtils.testWithClient('vCard with RESP3', async client => {
+    // Test empty vector set
+    assert.equal(
+      await client.vCard('resp3-empty-key'),
+      0
+    );
+
+    // Add elements and test cardinality
+    await client.vAdd('resp3-key', [1.0, 2.0], 'elem1');
+    assert.equal(
+      await client.vCard('resp3-key'),
+      1
+    );
+
+    await client.vAdd('resp3-key', [3.0, 4.0], 'elem2');
+    await client.vAdd('resp3-key', [5.0, 6.0], 'elem3');
+    assert.equal(
+      await client.vCard('resp3-key'),
+      3
+    );
+
+    assert.equal(await client.vCard('unknown'), 0);
+  }, {
+    ...GLOBAL.SERVERS.OPEN,
+    clientOptions: {
+      RESP: 3
+    },
+    minimumDockerVersion: [8, 0]
+  });
+});

packages/client/lib/commands/VCARD.ts

@@ -0,0 +1,18 @@
+import { CommandParser } from '../client/parser';
+import { RedisArgument, NumberReply, Command } from '../RESP/types';
+
+export default {
+  IS_READ_ONLY: true,
+  /**
+   * Retrieve the number of elements in a vector set
+   * 
+   * @param parser - The command parser
+   * @param key - The key of the vector set
+   * @see https://redis.io/commands/vcard/
+   */
+  parseCommand(parser: CommandParser, key: RedisArgument) {
+    parser.push('VCARD');
+    parser.pushKey(key);
+  },
+  transformReply: undefined as unknown as () => NumberReply
+} as const satisfies Command;

packages/client/lib/commands/VDIM.spec.ts

@@ -0,0 +1,43 @@
+import { strict as assert } from 'node:assert';
+import testUtils, { GLOBAL } from '../test-utils';
+import VDIM from './VDIM';
+import { BasicCommandParser } from '../client/parser';
+
+describe('VDIM', () => {
+  it('parseCommand', () => {
+    const parser = new BasicCommandParser();
+    VDIM.parseCommand(parser, 'key');
+    assert.deepEqual(
+      parser.redisArgs,
+      ['VDIM', 'key']
+    );
+  });
+
+  testUtils.testAll('vDim', async client => {
+    await client.vAdd('key', [1.0, 2.0, 3.0], 'element');
+
+    assert.equal(
+      await client.vDim('key'),
+      3
+    );
+  }, {
+    client: { ...GLOBAL.SERVERS.OPEN, minimumDockerVersion: [8, 0] },
+    cluster: { ...GLOBAL.CLUSTERS.OPEN, minimumDockerVersion: [8, 0] }
+  });
+
+  testUtils.testWithClient('vDim with RESP3', async client => {
+    await client.vAdd('resp3-5d', [1.0, 2.0, 3.0, 4.0, 5.0], 'elem5d');
+
+    assert.equal(
+      await client.vDim('resp3-5d'),
+      5
+    );
+
+  }, {
+    ...GLOBAL.SERVERS.OPEN,
+    clientOptions: {
+      RESP: 3
+    },
+    minimumDockerVersion: [8, 0]
+  });
+});

packages/client/lib/commands/VDIM.ts

@@ -0,0 +1,18 @@
+import { CommandParser } from '../client/parser';
+import { RedisArgument, NumberReply, Command } from '../RESP/types';
+
+export default {
+  IS_READ_ONLY: true,
+  /**
+   * Retrieve the dimension of the vectors in a vector set
+   * 
+   * @param parser - The command parser
+   * @param key - The key of the vector set
+   * @see https://redis.io/commands/vdim/
+   */
+  parseCommand(parser: CommandParser, key: RedisArgument) {
+    parser.push('VDIM');
+    parser.pushKey(key);
+  },
+  transformReply: undefined as unknown as () => NumberReply
+} as const satisfies Command;

packages/client/lib/commands/VEMB.spec.ts

@@ -0,0 +1,42 @@
+import { strict as assert } from 'node:assert';
+import testUtils, { GLOBAL } from '../test-utils';
+import VEMB from './VEMB';
+import { BasicCommandParser } from '../client/parser';
+
+describe('VEMB', () => {
+  it('parseCommand', () => {
+    const parser = new BasicCommandParser();
+    VEMB.parseCommand(parser, 'key', 'element');
+    assert.deepEqual(
+      parser.redisArgs,
+      ['VEMB', 'key', 'element']
+    );
+  });
+
+  testUtils.testAll('vEmb', async client => {
+    await client.vAdd('key', [1.0, 2.0, 3.0], 'element');
+
+    const result = await client.vEmb('key', 'element');
+    assert.ok(Array.isArray(result));
+    assert.equal(result.length, 3);
+    assert.equal(typeof result[0], 'number');
+  }, {
+    client: { ...GLOBAL.SERVERS.OPEN, minimumDockerVersion: [8, 0] },
+    cluster: { ...GLOBAL.CLUSTERS.OPEN, minimumDockerVersion: [8, 0] }
+  });
+
+  testUtils.testWithClient('vEmb with RESP3', async client => {
+    await client.vAdd('resp3-key', [1.5, 2.5, 3.5, 4.5], 'resp3-element');
+
+    const result = await client.vEmb('resp3-key', 'resp3-element');
+    assert.ok(Array.isArray(result));
+    assert.equal(result.length, 4);
+    assert.equal(typeof result[0], 'number');
+  }, {
+    ...GLOBAL.SERVERS.OPEN,
+    clientOptions: {
+      RESP: 3
+    },
+    minimumDockerVersion: [8, 0]
+  });
+});

packages/client/lib/commands/VEMB.ts

@@ -0,0 +1,21 @@
+import { CommandParser } from '../client/parser';
+import { RedisArgument, Command } from '../RESP/types';
+import { transformDoubleArrayReply } from './generic-transformers';
+
+export default {
+  IS_READ_ONLY: true,
+  /**
+   * Retrieve the approximate vector associated with a vector set element
+   * 
+   * @param parser - The command parser
+   * @param key - The key of the vector set
+   * @param element - The name of the element to retrieve the vector for
+   * @see https://redis.io/commands/vemb/
+   */
+  parseCommand(parser: CommandParser, key: RedisArgument, element: RedisArgument) {
+    parser.push('VEMB');
+    parser.pushKey(key);
+    parser.push(element);
+  },
+  transformReply: transformDoubleArrayReply
+} as const satisfies Command;