feat: add eval_ro and evalsha_ro commands

Author: yunusemreozdemir

Diff for: pkg/auto-pipeline.test.ts

@@ -34,7 +34,9 @@ describe("Auto pipeline", () => {
       redis.decrby(newKey(), 1),
       redis.del(newKey()),
       redis.echo("hello"),
+      redis.eval_ro("return ARGV[1]", [], ["Hello"]),
       redis.eval("return ARGV[1]", [], ["Hello"]),
+      redis.evalsha_ro(scriptHash, [], ["Hello"]),
       redis.evalsha(scriptHash, [], ["Hello"]),
       redis.exists(newKey()),
       redis.expire(newKey(), 5),
@@ -149,7 +151,7 @@ describe("Auto pipeline", () => {
       redis.json.arrappend(persistentKey3, "$.log", '"three"'),
     ]);
     expect(result).toBeTruthy();
-    expect(result.length).toBe(122); // returns
+    expect(result.length).toBe(124); // returns
     // @ts-expect-error pipelineCounter is not in type but accessible120 results
     expect(redis.pipelineCounter).toBe(1);
   });

Diff for: pkg/commands/eval_ro.test.ts

@@ -0,0 +1,41 @@
+import { EvalROCommand } from "./eval_ro";
+
+import { keygen, newHttpClient, randomID } from "../test-utils";
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { SetCommand } from "./set";
+const client = newHttpClient();
+
+const { newKey, cleanup } = keygen();
+afterAll(cleanup);
+
+describe("without keys", () => {
+  test("returns something", async () => {
+    const value = randomID();
+    const res = await new EvalROCommand(["return ARGV[1]", [], [value]]).exec(client);
+    expect(res).toEqual(value);
+  });
+});
+
+describe("with keys", () => {
+  test("returns something", async () => {
+    const value = randomID();
+    const key = newKey();
+    await new SetCommand([key, value]).exec(client);
+    const res = await new EvalROCommand([`return redis.call("GET", KEYS[1])`, [key], []]).exec(
+      client
+    );
+    expect(res).toEqual(value);
+  });
+});
+
+describe("with keys and write commands", () => {
+  test("throws", async () => {
+    const value = randomID();
+    const key = newKey();
+    await new SetCommand([key, value]).exec(client);
+    expect(async () => {
+      await new EvalROCommand([`return redis.call("DEL", KEYS[1])`, [key], []]).exec(client);
+    }).toThrow();
+  });
+});

Diff for: pkg/commands/eval_ro.ts

@@ -0,0 +1,14 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/eval_ro
+ */
+export class EvalROCommand<TArgs extends unknown[], TData> extends Command<unknown, TData> {
+  constructor(
+    [script, keys, args]: [script: string, keys: string[], args: TArgs],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(["eval_ro", script, keys.length, ...keys, ...(args ?? [])], opts);
+  }
+}

Diff for: pkg/commands/evalsha_ro.test.ts

@@ -0,0 +1,43 @@
+import { keygen, newHttpClient, randomID } from "../test-utils";
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { EvalshaROCommand } from "./evalsha_ro";
+import { ScriptLoadCommand } from "./script_load";
+import { SetCommand } from "./set";
+
+const client = newHttpClient();
+
+const { newKey, cleanup } = keygen();
+afterAll(cleanup);
+
+describe("without keys", () => {
+  test("returns something", async () => {
+    const value = randomID();
+    const sha1 = await new ScriptLoadCommand([`return {ARGV[1], "${value}"}`]).exec(client);
+    const res = await new EvalshaROCommand([sha1, [], [value]]).exec(client);
+    expect(res).toEqual([value, value]);
+  });
+});
+
+describe("with keys", () => {
+  test("returns something", async () => {
+    const value = randomID();
+    const key = newKey();
+    await new SetCommand([key, value]).exec(client);
+    const sha1 = await new ScriptLoadCommand([`return redis.call("GET", KEYS[1])`]).exec(client);
+    const res = await new EvalshaROCommand([sha1, [key], []]).exec(client);
+    expect(res).toEqual(value);
+  });
+});
+
+describe("with keys and write commands", () => {
+  test("throws", async () => {
+    const value = randomID();
+    const key = newKey();
+    await new SetCommand([key, value]).exec(client);
+    const sha1 = await new ScriptLoadCommand([`return redis.call("DEL", KEYS[1])`]).exec(client);
+    expect(async () => {
+      await new EvalshaROCommand([sha1, [key], []]).exec(client);
+    }).toThrow();
+  });
+});

Diff for: pkg/commands/evalsha_ro.ts

@@ -0,0 +1,14 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/evalsha_ro
+ */
+export class EvalshaROCommand<TArgs extends unknown[], TData> extends Command<unknown, TData> {
+  constructor(
+    [sha, keys, args]: [sha: string, keys: string[], args?: TArgs],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(["evalsha_ro", sha, keys.length, ...keys, ...(args ?? [])], opts);
+  }
+}

Diff for: pkg/commands/mod.ts

@@ -10,7 +10,9 @@ export * from "./decr";
 export * from "./decrby";
 export * from "./del";
 export * from "./echo";
+export * from "./eval_ro";
 export * from "./eval";
+export * from "./evalsha_ro";
 export * from "./evalsha";
 export * from "./exec";
 export * from "./exists";

Diff for: pkg/commands/types.ts

@@ -8,7 +8,9 @@ export { type DecrCommand } from "./decr";
 export { type DecrByCommand } from "./decrby";
 export { type DelCommand } from "./del";
 export { type EchoCommand } from "./echo";
+export { type EvalROCommand } from "./eval_ro";
 export { type EvalCommand } from "./eval";
+export { type EvalshaROCommand } from "./evalsha_ro";
 export { type EvalshaCommand } from "./evalsha";
 export { type ExistsCommand } from "./exists";
 export { type ExpireCommand } from "./expire";

Diff for: pkg/pipeline.test.ts

@@ -136,7 +136,9 @@ describe("use all the things", () => {
       .decrby(newKey(), 1)
       .del(newKey())
       .echo("hello")
+      .eval_ro("return ARGV[1]", [], ["Hello"])
       .eval("return ARGV[1]", [], ["Hello"])
+      .evalsha_ro(scriptHash, [], ["Hello"])
       .evalsha(scriptHash, [], ["Hello"])
       .exists(newKey())
       .expire(newKey(), 5)
@@ -250,7 +252,7 @@ describe("use all the things", () => {
       .json.set(newKey(), "$", { hello: "world" });
 
     const res = await p.exec();
-    expect(res.length).toEqual(122);
+    expect(res.length).toEqual(124);
   });
 });
 describe("keep errors", () => {

Diff for: pkg/pipeline.ts

@@ -18,7 +18,9 @@ import {
   DecrCommand,
   DelCommand,
   EchoCommand,
+  EvalROCommand,
   EvalCommand,
+  EvalshaROCommand,
   EvalshaCommand,
   ExistsCommand,
   ExpireAtCommand,
@@ -449,13 +451,27 @@ export class Pipeline<TCommands extends Command<any, any>[] = []> {
   echo = (...args: CommandArgs<typeof EchoCommand>) =>
     this.chain(new EchoCommand(args, this.commandOptions));
 
+  /**
+   * @see https://redis.io/commands/eval_ro
+   */
+  eval_ro = <TArgs extends unknown[], TData = unknown>(
+    ...args: [script: string, keys: string[], args: TArgs]
+  ) => this.chain(new EvalROCommand<TArgs, TData>(args, this.commandOptions));
+
   /**
    * @see https://redis.io/commands/eval
    */
   eval = <TArgs extends unknown[], TData = unknown>(
     ...args: [script: string, keys: string[], args: TArgs]
   ) => this.chain(new EvalCommand<TArgs, TData>(args, this.commandOptions));
 
+  /**
+   * @see https://redis.io/commands/evalsha_ro
+   */
+  evalsha_ro = <TArgs extends unknown[], TData = unknown>(
+    ...args: [sha1: string, keys: string[], args: TArgs]
+  ) => this.chain(new EvalshaROCommand<TArgs, TData>(args, this.commandOptions));
+
   /**
    * @see https://redis.io/commands/evalsha
    */

Diff for: pkg/redis.ts

@@ -18,7 +18,9 @@ import {
   DecrCommand,
   DelCommand,
   EchoCommand,
+  EvalROCommand,
   EvalCommand,
+  EvalshaROCommand,
   EvalshaCommand,
   ExecCommand,
   ExistsCommand,
@@ -183,7 +185,8 @@ import { ZMScoreCommand } from "./commands/zmscore";
 import type { Requester, UpstashRequest, UpstashResponse } from "./http";
 import { Pipeline } from "./pipeline";
 import { Script } from "./script";
-import type { CommandArgs, RedisOptions, Telemetry } from "./types";
+import { ScriptRO } from "./script_ro";
+import type { CommandArgs, RedisOptions, Telemetry, ScriptOptions } from "./types";
 
 // See https://github.com/upstash/upstash-redis/issues/342
 // why we need this export
@@ -393,9 +396,13 @@ export class Redis {
     }
   };
 
-  createScript(script: string): Script {
-    return new Script(this, script);
+  createScript(script: string): Script;
+  createScript(script: string, opts: ScriptOptions & { readOnly: true }): ScriptRO;
+  createScript(script: string, opts: ScriptOptions & { readOnly?: false }): Script;
+  createScript(script: string, opts?: ScriptOptions): Script | ScriptRO {
+    return opts?.readOnly ? new ScriptRO(this, script) : new Script(this, script);
   }
+
   /**
    * Create a new pipeline that allows you to send requests in bulk.
    *
@@ -520,13 +527,27 @@ export class Redis {
   echo = (...args: CommandArgs<typeof EchoCommand>) =>
     new EchoCommand(args, this.opts).exec(this.client);
 
+  /**
+   * @see https://redis.io/commands/eval_ro
+   */
+  eval_ro = <TArgs extends unknown[], TData = unknown>(
+    ...args: [script: string, keys: string[], args: TArgs]
+  ) => new EvalROCommand<TArgs, TData>(args, this.opts).exec(this.client);
+
   /**
    * @see https://redis.io/commands/eval
    */
   eval = <TArgs extends unknown[], TData = unknown>(
     ...args: [script: string, keys: string[], args: TArgs]
   ) => new EvalCommand<TArgs, TData>(args, this.opts).exec(this.client);
 
+  /**
+   * @see https://redis.io/commands/evalsha_ro
+   */
+  evalsha_ro = <TArgs extends unknown[], TData = unknown>(
+    ...args: [sha1: string, keys: string[], args: TArgs]
+  ) => new EvalshaROCommand<TArgs, TData>(args, this.opts).exec(this.client);
+
   /**
    * @see https://redis.io/commands/evalsha
    */

Diff for: pkg/script_ro.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Redis } from "./redis";
+import { keygen, newHttpClient, randomID } from "./test-utils";
+const client = newHttpClient();
+
+const { newKey, cleanup } = keygen();
+afterEach(cleanup);
+
+describe("create a new readonly script", () => {
+  test(
+    "creates a new readonly script",
+    async () => {
+      const redis = new Redis(client);
+      const value = randomID();
+      const key = newKey();
+      await redis.set(key, value);
+      const script = redis.createScript("return redis.call('GET', KEYS[1]);", { readOnly: true });
+
+      const res = await script.eval_ro([key], []);
+      expect(res).toEqual(value);
+    },
+    { timeout: 15_000 }
+  );
+
+  test(
+    "throws when write commands are used",
+    async () => {
+      const redis = new Redis(client);
+      const value = randomID();
+      const key = newKey();
+      await redis.set(key, value);
+      const script = redis.createScript("return redis.call('DEL', KEYS[1]);", { readOnly: true });
+
+      expect(async () => {
+        await script.eval_ro([key], []);
+      }).toThrow();
+    },
+    { timeout: 15_000 }
+  );
+});

Diff for: pkg/script_ro.ts

@@ -0,0 +1,68 @@
+import Hex from "crypto-js/enc-hex.js";
+import sha1 from "crypto-js/sha1.js";
+import type { Redis } from "./redis";
+
+/**
+ * Creates a new script.
+ *
+ * Scripts offer the ability to optimistically try to execute a script without having to send the
+ * entire script to the server. If the script is loaded on the server, it tries again by sending
+ * the entire script. Afterwards, the script is cached on the server.
+ *
+ * @example
+ * ```ts
+ * const redis = new Redis({...})
+ *
+ * const script = redis.createScript<string>("return ARGV[1];", { readOnly: true })
+ * const arg1 = await script.eval_ro([], ["Hello World"])
+ * expect(arg1, "Hello World")
+ * ```
+ */
+export class ScriptRO<TResult = unknown> {
+  public readonly script: string;
+  public readonly sha1: string;
+  private readonly redis: Redis;
+
+  constructor(redis: Redis, script: string) {
+    this.redis = redis;
+    this.sha1 = this.digest(script);
+    this.script = script;
+  }
+
+  /**
+   * Send an `EVAL_RO` command to redis.
+   */
+  public async eval_ro(keys: string[], args: string[]): Promise<TResult> {
+    return await this.redis.eval_ro(this.script, keys, args);
+  }
+
+  /**
+   * Calculates the sha1 hash of the script and then calls `EVALSHA_RO`.
+   */
+  public async evalsha_ro(keys: string[], args: string[]): Promise<TResult> {
+    return await this.redis.evalsha_ro(this.sha1, keys, args);
+  }
+
+  /**
+   * Optimistically try to run `EVALSHA_RO` first.
+   * If the script is not loaded in redis, it will fall back and try again with `EVAL_RO`.
+   *
+   * Following calls will be able to use the cached script
+   */
+  public async exec(keys: string[], args: string[]): Promise<TResult> {
+    const res = await this.redis.evalsha_ro(this.sha1, keys, args).catch(async (error) => {
+      if (error instanceof Error && error.message.toLowerCase().includes("noscript")) {
+        return await this.redis.eval_ro(this.script, keys, args);
+      }
+      throw error;
+    });
+    return res as TResult;
+  }
+
+  /**
+   * Compute the sha1 hash of the script and return its hex representation.
+   */
+  private digest(s: string): string {
+    return Hex.stringify(sha1(s));
+  }
+}

Diff for: pkg/types.ts

@@ -33,3 +33,7 @@ export type RedisOptions = {
   enableAutoPipelining?: boolean;
   readYourWrites?: boolean;
 };
+
+export type ScriptOptions = {
+  readOnly?: boolean;
+};