Node: add LINSERT command (#1544)

* Node: add LINSERT command * PR suggestions * Use backticks for cross-references * Fix doc --------- Co-authored-by: Andrew Carbonetto <[email protected]>
valkey-io · Jun 11, 2024 · da42822 · da42822
1 parent fb18f35
commit da42822
Show file tree

Hide file tree

Showing 7 changed files with 160 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,7 @@
 * Node: Added SUNIONSTORE command ([#1549](https:/aws/glide-for-redis/pull/1549))
 * Node: Added PFCOUNT command ([#1545](https:/aws/glide-for-redis/pull/1545))
 * Node: Added OBJECT FREQ command ([#1542](https:/aws/glide-for-redis/pull/1542))
+* Node: Added LINSERT command ([#1544](https:/aws/glide-for-redis/pull/1544))
 
 ### Breaking Changes
 * Node: Update XREAD to return a Map of Map ([#1494](https:/aws/glide-for-redis/pull/1494))

diff --git a/node/npm/glide/index.ts b/node/npm/glide/index.ts
@@ -87,6 +87,7 @@ function initialize() {
  Logger,
  ExpireOptions,
  InfoOptions,
+ InsertPosition,
  SetOptions,
  ZaddOptions,
  ScoreBoundry,
@@ -129,6 +130,7 @@ function initialize() {
  Logger,
  ExpireOptions,
  InfoOptions,
+ InsertPosition,
  SetOptions,
  ZaddOptions,
  ScoreBoundry,

diff --git a/node/src/BaseClient.ts b/node/src/BaseClient.ts
@@ -13,6 +13,7 @@ import { Buffer, BufferWriter, Reader, Writer } from "protobufjs";
 import {
  AggregationType,
  ExpireOptions,
+ InsertPosition,
  KeyWeight,
  RangeByIndex,
  RangeByLex,
@@ -47,6 +48,7 @@ import {
  createIncrBy,
  createIncrByFloat,
  createLIndex,
+ createLInsert,
  createLLen,
  createLPop,
  createLPush,
@@ -2306,6 +2308,37 @@ export class BaseClient {
  return this.createWritePromise(createLIndex(key, index));
  }
 
+ /**
+ * Inserts `element` in the list at `key` either before or after the `pivot`.
+ *
+ * See https://valkey.io/commands/linsert/ for more details.
+ *
+ * @param key - The key of the list.
+ * @param position - The relative position to insert into - either `InsertPosition.Before` or
+ * `InsertPosition.After` the `pivot`.
+ * @param pivot - An element of the list.
+ * @param element - The new element to insert.
+ * @returns The list length after a successful insert operation.
+ * If the `key` doesn't exist returns `-1`.
+ * If the `pivot` wasn't found, returns `0`.
+ *
+ * @example
+ * ```typescript
+ * const length = await client.linsert("my_list", InsertPosition.Before, "World", "There");
+ * console.log(length); // Output: 2 - The list has a length of 2 after performing the insert.
+ * ```
+ */
+ public linsert(
+ key: string,
+ position: InsertPosition,
+ pivot: string,
+ element: string,
+ ): Promise<number> {
+ return this.createWritePromise(
+ createLInsert(key, position, pivot, element),
+ );
+ }
+
  /** Remove the existing timeout on `key`, turning the key from volatile (a key with an expire set) to
  * persistent (a key that will never expire as no timeout is associated).
  * See https://redis.io/commands/persist/ for more details.

diff --git a/node/src/Commands.ts b/node/src/Commands.ts
@@ -1110,6 +1110,32 @@ export function createLIndex(
  return createCommand(RequestType.LIndex, [key, index.toString()]);
 }
 
+/**
+ * Defines where to insert new elements into a list.
+ */
+export enum InsertPosition {
+ /**
+ * Insert new element before the pivot.
+ */
+ Before = "before",
+ /**
+ * Insert new element after the pivot.
+ */
+ After = "after",
+}
+
+/**
+ * @internal
+ */
+export function createLInsert(
+ key: string,
+ position: InsertPosition,
+ pivot: string,
+ element: string,
+): redis_request.Command {
+ return createCommand(RequestType.LInsert, [key, position, pivot, element]);
+}
+
 /**
  * @internal
  */

diff --git a/node/src/Transaction.ts b/node/src/Transaction.ts
@@ -6,6 +6,7 @@ import {
  AggregationType,
  ExpireOptions,
  InfoOptions,
+ InsertPosition,
  KeyWeight,
  RangeByIndex,
  RangeByLex,
@@ -49,6 +50,7 @@ import {
  createIncrByFloat,
  createInfo,
  createLIndex,
+ createLInsert,
  createLLen,
  createLPop,
  createLPush,
@@ -1266,6 +1268,30 @@ export class BaseTransaction<T extends BaseTransaction<T>> {
  return this.addAndReturn(createLIndex(key, index));
  }
 
+ /**
+ * Inserts `element` in the list at `key` either before or after the `pivot`.
+ *
+ * See https://valkey.io/commands/linsert/ for more details.
+ *
+ * @param key - The key of the list.
+ * @param position - The relative position to insert into - either `InsertPosition.Before` or
+ * `InsertPosition.After` the `pivot`.
+ * @param pivot - An element of the list.
+ * @param element - The new element to insert.
+ *
+ * Command Response - The list length after a successful insert operation.
+ * If the `key` doesn't exist returns `-1`.
+ * If the `pivot` wasn't found, returns `0`.
+ */
+ public linsert(
+ key: string,
+ position: InsertPosition,
+ pivot: string,
+ element: string,
+ ): T {
+ return this.addAndReturn(createLInsert(key, position, pivot, element));
+ }
+
  /**
  * Adds an entry to the specified stream stored at `key`. If the `key` doesn't exist, the stream is created.
  * See https://redis.io/commands/xadd/ for more details.

diff --git a/node/tests/SharedTests.ts b/node/tests/SharedTests.ts
@@ -9,6 +9,7 @@ import {
  ClosingError,
  ExpireOptions,
  InfoOptions,
+ InsertPosition,
  ProtocolVersion,
  RedisClient,
  RedisClusterClient,
@@ -2176,6 +2177,69 @@ export function runBaseTests<Context>(config: {
  config.timeout,
  );
 
+ it.each([ProtocolVersion.RESP2, ProtocolVersion.RESP3])(
+ `linsert test_%p`,
+ async (protocol) => {
+ await runTest(async (client: BaseClient) => {
+ const key1 = uuidv4();
+ const stringKey = uuidv4();
+ const nonExistingKey = uuidv4();
+
+ expect(await client.lpush(key1, ["4", "3", "2", "1"])).toEqual(
+ 4,
+ );
+ expect(
+ await client.linsert(
+ key1,
+ InsertPosition.Before,
+ "2",
+ "1.5",
+ ),
+ ).toEqual(5);
+ expect(
+ await client.linsert(
+ key1,
+ InsertPosition.After,
+ "3",
+ "3.5",
+ ),
+ ).toEqual(6);
+ expect(await client.lrange(key1, 0, -1)).toEqual([
+ "1",
+ "1.5",
+ "2",
+ "3",
+ "3.5",
+ "4",
+ ]);
+
+ expect(
+ await client.linsert(
+ key1,
+ InsertPosition.Before,
+ "nonExistingPivot",
+ "4",
+ ),
+ ).toEqual(-1);
+ expect(
+ await client.linsert(
+ nonExistingKey,
+ InsertPosition.Before,
+ "pivot",
+ "elem",
+ ),
+ ).toEqual(0);
+
+ // key exists, but it is not a list
+ expect(await client.set(stringKey, "value")).toEqual("OK");
+ await expect(
+ client.linsert(stringKey, InsertPosition.Before, "a", "b"),
+ ).rejects.toThrow();
+ }, protocol);
+ },
+ config.timeout,
+ );
+
  it.each([ProtocolVersion.RESP2, ProtocolVersion.RESP3])(
  `zpopmin test_%p`,
  async (protocol) => {

diff --git a/node/tests/TestUtilities.ts b/node/tests/TestUtilities.ts
@@ -10,6 +10,7 @@ import {
  BaseClient,
  BaseClientConfiguration,
  ClusterTransaction,
+ InsertPosition,
  Logger,
  ProtocolVersion,
  RedisClient,
@@ -295,6 +296,13 @@ export async function transactionTest(
  args.push([field + "3", field + "2"]);
  baseTransaction.lpopCount(key5, 2);
  args.push([field + "3", field + "2"]);
+ baseTransaction.linsert(
+ key5,
+ InsertPosition.Before,
+ "nonExistingPivot",
+ "element",
+ );
+ args.push(0);
  baseTransaction.rpush(key6, [field + "1", field + "2", field + "3"]);
  args.push(3);
  baseTransaction.lindex(key6, 0);