@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/script.ts

@@ -0,0 +1,100 @@
+import { subtle } from "uncrypto";
+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.
+ *
+ * Responses are JSON-parsed automatically: a stored "123" comes back as the number 123, "true" as
+ * true, and '{"a":1}' as an object. Pass automaticDeserialization: false to the Redis constructor
+ * to receive raw strings.
+ *
+ * @example
+ * ```ts
+ * const redis = new Redis({...})
+ *
+ * const script = redis.createScript<string>("return ARGV[1];")
+ * const arg1 = await script.eval([], ["Hello World"])
+ * expect(arg1, "Hello World")
+ * ```
+ */
+export class Script<TResult = unknown> {
+  public readonly script: string;
+  /**
+   * @deprecated This property is initialized to an empty string and will be set in the init method
+   * asynchronously. Do not use this property immidiately after the constructor.
+   *
+   * This property is only exposed for backwards compatibility and will be removed in the
+   * future major release.
+   */
+  public sha1: string;
+  private initPromise: Promise<void> | undefined;
+  private readonly redis: Redis;
+
+  constructor(redis: Redis, script: string) {
+    this.redis = redis;
+    this.script = script;
+    this.sha1 = "";
+    void this.init(script);
+  }
+
+  /**
+   * Initialize the script by computing its SHA-1 hash.
+   */
+  private init(script: string): Promise<void> {
+    if (!this.initPromise) {
+      this.initPromise = this.digest(script).then((sha1) => {
+        this.sha1 = sha1;
+      });
+    }
+    return this.initPromise;
+  }
+
+  /**
+   * Send an `EVAL` command to redis.
+   */
+  public async eval(keys: string[], args: string[]): Promise<TResult> {
+    await this.init(this.script);
+
+    return await this.redis.eval(this.script, keys, args);
+  }
+
+  /**
+   * Calculates the sha1 hash of the script and then calls `EVALSHA`.
+   */
+  public async evalsha(keys: string[], args: string[]): Promise<TResult> {
+    await this.init(this.script);
+
+    return await this.redis.evalsha(this.sha1, keys, args);
+  }
+
+  /**
+   * Optimistically try to run `EVALSHA` first.
+   * If the script is not loaded in redis, it will fall back and try again with `EVAL`.
+   *
+   * Following calls will be able to use the cached script
+   */
+  public async exec(keys: string[], args: string[]): Promise<TResult> {
+    await this.init(this.script);
+
+    const res = await this.redis.evalsha(this.sha1, keys, args).catch(async (error) => {
+      if (error instanceof Error && error.message.toLowerCase().includes("noscript")) {
+        return await this.redis.eval(this.script, keys, args);
+      }
+      throw error;
+    });
+    return res as TResult;
+  }
+
+  /**
+   * Compute the sha1 hash of the script and return its hex representation.
+   */
+  private async digest(s: string): Promise<string> {
+    const data = new TextEncoder().encode(s);
+    const hashBuffer = await subtle.digest("SHA-1", data);
+    const hashArray = [...new Uint8Array(hashBuffer)];
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+}

package/src/pkg/scriptRo.ts

@@ -0,0 +1,98 @@
+import { subtle } from "uncrypto";
+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.
+ *
+ * Responses are JSON-parsed automatically: a stored "123" comes back as the number 123, "true" as
+ * true, and '{"a":1}' as an object. Pass automaticDeserialization: false to the Redis constructor
+ * to receive raw strings.
+ *
+ * @example
+ * ```ts
+ * const redis = new Redis({...})
+ *
+ * const script = redis.createScript<string>("return ARGV[1];", { readOnly: true })
+ * const arg1 = await script.evalRo([], ["Hello World"])
+ * expect(arg1, "Hello World")
+ * ```
+ */
+export class ScriptRO<TResult = unknown> {
+  public readonly script: string;
+  /**
+   * @deprecated This property is initialized to an empty string and will be set in the init method
+   * asynchronously. Do not use this property immidiately after the constructor.
+   *
+   * This property is only exposed for backwards compatibility and will be removed in the
+   * future major release.
+   */
+  public sha1: string;
+  private initPromise: Promise<void> | undefined;
+  private readonly redis: Redis;
+
+  constructor(redis: Redis, script: string) {
+    this.redis = redis;
+    this.sha1 = "";
+    this.script = script;
+    void this.init(script);
+  }
+
+  private init(script: string): Promise<void> {
+    if (!this.initPromise) {
+      this.initPromise = this.digest(script).then((sha1) => {
+        this.sha1 = sha1;
+      });
+    }
+    return this.initPromise;
+  }
+
+  /**
+   * Send an `EVAL_RO` command to redis.
+   */
+  public async evalRo(keys: string[], args: string[]): Promise<TResult> {
+    await this.init(this.script);
+
+    return await this.redis.evalRo(this.script, keys, args);
+  }
+
+  /**
+   * Calculates the sha1 hash of the script and then calls `EVALSHA_RO`.
+   */
+  public async evalshaRo(keys: string[], args: string[]): Promise<TResult> {
+    await this.init(this.script);
+
+    return await this.redis.evalshaRo(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> {
+    await this.init(this.script);
+
+    const res = await this.redis.evalshaRo(this.sha1, keys, args).catch(async (error) => {
+      if (error instanceof Error && error.message.toLowerCase().includes("noscript")) {
+        return await this.redis.evalRo(this.script, keys, args);
+      }
+      throw error;
+    });
+    return res as TResult;
+  }
+
+  /**
+   * Compute the sha1 hash of the script and return its hex representation.
+   */
+  private async digest(s: string): Promise<string> {
+    const data = new TextEncoder().encode(s);
+    const hashBuffer = await subtle.digest("SHA-1", data);
+    const hashArray = [...new Uint8Array(hashBuffer)];
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+}

package/src/pkg/types.ts

@@ -0,0 +1,35 @@
+export type CommandArgs<TCommand extends new (..._args: any) => any> =
+  ConstructorParameters<TCommand>[0];
+
+export type Telemetry = {
+  /**
+   * Upstash-Telemetry-Sdk
+   * @example @upstash/redis@v1.1.1
+   */
+  sdk?: string;
+
+  /**
+   * Upstash-Telemetry-Platform
+   * @example cloudflare
+   */
+  platform?: string;
+
+  /**
+   * Upstash-Telemetry-Runtime
+   * @example node@v18
+   */
+  runtime?: string;
+};
+
+export type RedisOptions = {
+  /**
+   * Automatically try to deserialize the returned data from upstash using `JSON.deserialize`
+   *
+   * @default true
+   */
+  automaticDeserialization?: boolean;
+  latencyLogging?: boolean;
+  enableTelemetry?: boolean;
+  enableAutoPipelining?: boolean;
+  readYourWrites?: boolean;
+};

package/src/pkg/util.ts

@@ -0,0 +1,115 @@
+import type { ScanResultWithType } from "./commands/scan";
+
+/**
+ * JSON.parse that ignores one leading UTF-8 BOM (U+FEFF), as the base64 decoder
+ * (TextDecoder) used to strip it before deserialization. Callers keep the exact
+ * string (BOM included) when parsing fails.
+ */
+export function parseJSON(value: string): unknown {
+  return JSON.parse(stripBOM(value) as string);
+}
+
+/**
+ * Non-string values (e.g. integer replies) are returned unchanged.
+ */
+function stripBOM(value: unknown): unknown {
+  return typeof value === "string" && value.startsWith("\uFEFF") ? value.slice(1) : value;
+}
+
+function parseRecursive(obj: unknown): unknown {
+  const parsed = Array.isArray(obj)
+    ? obj.map((o) => {
+        try {
+          return parseRecursive(o);
+        } catch {
+          return o;
+        }
+      })
+    : parseJSON(obj as string);
+
+  /**
+   * Parsing very large numbers can result in MAX_SAFE_INTEGER
+   * overflow. In that case we return the number as string instead.
+   */
+  if (typeof parsed === "number" && parsed.toString() !== stripBOM(obj)) {
+    return obj;
+  }
+  return parsed;
+}
+
+export function parseResponse<TResult>(result: unknown): TResult {
+  try {
+    /**
+     * Try to parse the response if possible
+     */
+    return parseRecursive(result) as TResult;
+  } catch {
+    return result as TResult;
+  }
+}
+
+/**
+ * Deserializes a scan result, excluding the cursor
+ * which can be string "0" or a big number string.
+ * Either way, we want it to stay as a string.
+ *
+ * @param result
+ */
+export function deserializeScanResponse<TResult>(result: [string, ...any]): TResult {
+  return [result[0], ...parseResponse<any[]>(result.slice(1))] as TResult;
+}
+
+export function deserializeScanWithTypesResponse(result: [string, string[]]): ScanResultWithType {
+  const [cursor, keys] = result;
+
+  const parsedKeys: ScanResultWithType[1] = [];
+
+  for (let i = 0; i < keys.length; i += 2) {
+    parsedKeys.push({ key: keys[i], type: keys[i + 1] });
+  }
+
+  return [cursor, parsedKeys];
+}
+
+/**
+ * Merges multiple Records of headers into a single Record
+ * Later headers take precedence over earlier ones.
+ *
+ * @param headers - Array of header records to merge
+ * @returns A new Record containing all merged headers
+ *
+ * @example
+ * const defaultHeaders = { 'Content-Type': 'application/json' };
+ * const customHeaders = { 'Authorization': 'Bearer token' };
+ * const merged = mergeHeaders(defaultHeaders, customHeaders);
+ */
+export function mergeHeaders(
+  ...headers: (Record<string, string> | undefined)[]
+): Record<string, string> {
+  const merged: Record<string, string> = {};
+
+  for (const header of headers) {
+    if (!header) continue;
+
+    for (const [key, value] of Object.entries(header)) {
+      if (value !== undefined && value !== null) {
+        merged[key] = value;
+      }
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Converts a kv-array `[k1, v1, k2, v2, ...]` into a Record of { k1: v1, k2: v2, ...}.
+ */
+export function kvArrayToObject<T extends Record<string, unknown>>(v: unknown): T {
+  if (typeof v === "object" && v !== null && !Array.isArray(v)) return v as T;
+  if (!Array.isArray(v)) return {} as T;
+  const obj: T = {} as T;
+  for (let i = 0; i < v.length; i += 2) {
+    if (typeof v[i] === "string") obj[v[i] as keyof T] = v[i + 1] as T[keyof T];
+  }
+  return obj;
+}

package/src/platforms/cloudflare.ts

@@ -0,0 +1,162 @@
+import type { HttpClientConfig, RequesterConfig } from "../pkg/http";
+import { HttpClient } from "../pkg/http";
+import * as core from "../pkg/redis";
+import { VERSION } from "../version";
+
+type Env = {
+  UPSTASH_DISABLE_TELEMETRY?: string;
+};
+
+export * as errors from "../pkg/error";
+export type * from "../pkg/commands/types";
+
+/**
+ * Connection credentials for upstash redis.
+ * Get them from https://console.upstash.com/redis/<uuid>
+ */
+export type RedisConfigCloudflare = {
+  /**
+   * UPSTASH_REDIS_REST_URL
+   */
+  url: string | undefined;
+  /**
+   * UPSTASH_REDIS_REST_TOKEN
+   */
+  token: string | undefined;
+  /**
+   * The signal will allow aborting requests on the fly.
+   * For more check: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+   */
+  signal?: HttpClientConfig["signal"];
+  keepAlive?: boolean;
+
+  /**
+   * When this flag is enabled, any subsequent commands issued by this client are guaranteed to observe the effects of all earlier writes submitted by the same client.
+   */
+  readYourWrites?: boolean;
+} & core.RedisOptions &
+  RequesterConfig &
+  Env;
+
+/**
+ * Serverless redis client for upstash.
+ */
+export class Redis extends core.Redis {
+  /**
+   * Create a new redis client
+   *
+   * @example
+   * ```typescript
+   * const redis = new Redis({
+   *  url: "<UPSTASH_REDIS_REST_URL>",
+   *  token: "<UPSTASH_REDIS_REST_TOKEN>",
+   * });
+   * ```
+   */
+  constructor(config: RedisConfigCloudflare, env?: Env) {
+    if (!config.url) {
+      console.warn(
+        `[Upstash Redis] The 'url' property is missing or undefined in your Redis config. To create a database instantly (no signup needed), run: curl -X POST https://upstash.com/start-redis`
+      );
+    } else if (config.url.startsWith(" ") || config.url.endsWith(" ") || /\r|\n/.test(config.url)) {
+      console.warn(
+        "[Upstash Redis] The redis url contains whitespace or newline, which can cause errors!"
+      );
+    }
+
+    if (!config.token) {
+      console.warn(
+        `[Upstash Redis] The 'token' property is missing or undefined in your Redis config. To create a database instantly (no signup needed), run: curl -X POST https://upstash.com/start-redis`
+      );
+    } else if (
+      config.token.startsWith(" ") ||
+      config.token.endsWith(" ") ||
+      /\r|\n/.test(config.token!)
+    ) {
+      console.warn(
+        "[Upstash Redis] The redis token contains whitespace or newline, which can cause errors!"
+      );
+    }
+
+    const client = new HttpClient({
+      retry: config.retry,
+      baseUrl: config.url!,
+      headers: { authorization: `Bearer ${config.token}` },
+      responseEncoding: config.responseEncoding,
+      signal: config.signal,
+      keepAlive: config.keepAlive,
+      readYourWrites: config.readYourWrites,
+    });
+
+    super(client, {
+      enableTelemetry: config.enableTelemetry ?? !env?.UPSTASH_DISABLE_TELEMETRY,
+      automaticDeserialization: config.automaticDeserialization,
+      latencyLogging: config.latencyLogging,
+      enableAutoPipelining: config.enableAutoPipelining,
+    });
+    // This is only added of the user has not disabled telemetry
+    this.addTelemetry({
+      platform: "cloudflare",
+      sdk: `@upstash/redis@${VERSION}`,
+    });
+
+    if (this.enableAutoPipelining) {
+      return this.autoPipeline();
+    }
+  }
+
+  /*
+   * Create a new Upstash Redis instance from environment variables on cloudflare.
+   *
+   * This tries to load `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` from
+   * the global namespace
+   *
+   * If you are using a module worker, please pass in the `env` object.
+   * ```ts
+   * const redis = Redis.fromEnv(env)
+   * ```
+   */
+  static fromEnv(
+    env?: {
+      UPSTASH_REDIS_REST_URL: string;
+      UPSTASH_REDIS_REST_TOKEN: string;
+      UPSTASH_DISABLE_TELEMETRY?: string;
+    },
+    opts?: Omit<RedisConfigCloudflare, "url" | "token">
+  ): Redis {
+    const url =
+      env?.UPSTASH_REDIS_REST_URL ??
+      // @ts-expect-error These will be defined by cloudflare
+      (typeof UPSTASH_REDIS_REST_URL === "string"
+        ? // @ts-expect-error These will be defined by cloudflare
+          UPSTASH_REDIS_REST_URL
+        : undefined);
+
+    const token =
+      env?.UPSTASH_REDIS_REST_TOKEN ??
+      // @ts-expect-error These will be defined by cloudflare
+      (typeof UPSTASH_REDIS_REST_TOKEN === "string"
+        ? // @ts-expect-error These will be defined by cloudflare
+          UPSTASH_REDIS_REST_TOKEN
+        : undefined);
+
+    const missing: string[] = [];
+    if (!url) missing.push("UPSTASH_REDIS_REST_URL");
+    if (!token) missing.push("UPSTASH_REDIS_REST_TOKEN");
+
+    if (missing.length > 0) {
+      // Both can be missing at once, so the wording and the number of
+      // `wrangler secret put` commands follow how many are actually missing.
+      const plural = missing.length > 1;
+      const names = missing.map((name) => `\`${name}\``).join(" and ");
+      const commands = missing.map((name) => `\`wrangler secret put ${name}\``).join(" and ");
+      console.warn(
+        `[Upstash Redis] Unable to find environment variable${plural ? "s" : ""}: ${names}. Please add ${plural ? "them" : "it"} via ${commands} and provide ${plural ? "them as arguments" : "it as an argument"} to the \`Redis.fromEnv\` function. To create a database instantly (no signup needed), run: curl -X POST https://upstash.com/start-redis`
+      );
+    }
+    return new Redis({ ...opts, url, token }, env);
+  }
+}
+
+export { type Requester, type UpstashRequest, type UpstashResponse } from "../pkg/http";
+export { type Pipeline } from "../pkg/pipeline";

package/src/platforms/fastly.ts

@@ -0,0 +1,105 @@
+import type { RequesterConfig } from "../pkg/http";
+
+import { HttpClient } from "../pkg/http";
+import * as core from "../pkg/redis";
+import { VERSION } from "../version";
+
+export * as errors from "../pkg/error";
+export type * from "../pkg/commands/types";
+
+/**
+ * Connection credentials for upstash redis.
+ * Get them from https://console.upstash.com/redis/<uuid>
+ */
+export type RedisConfigFastly = {
+  /**
+   * UPSTASH_REDIS_REST_URL
+   */
+  url: string | undefined;
+  /**
+   * UPSTASH_REDIS_REST_TOKEN
+   */
+  token: string | undefined;
+  /**
+   * A Request can be forwarded to any backend defined on your service. Backends
+   * can be created via the Fastly CLI, API, or web interface, and are
+   * referenced by name.
+   */
+  backend: string;
+  keepAlive?: boolean;
+
+  /**
+   * When this flag is enabled, any subsequent commands issued by this client are guaranteed to observe the effects of all earlier writes submitted by the same client.
+   */
+  readYourWrites?: boolean;
+} & core.RedisOptions &
+  RequesterConfig;
+
+/**
+ * Serverless redis client for upstash.
+ */
+export class Redis extends core.Redis {
+  /**
+   * Create a new redis client
+   *
+   * @example
+   * ```typescript
+   *    const redis = new Redis({
+   *        url: "<UPSTASH_REDIS_REST_URL>",
+   *        token: "<UPSTASH_REDIS_REST_TOKEN>",
+   *        backend: "upstash-db",
+   *    });
+   * ```
+   */
+  constructor(config: RedisConfigFastly) {
+    if (!config.url) {
+      console.warn(
+        `[Upstash Redis] The 'url' property is missing or undefined in your Redis config. To create a database instantly (no signup needed), run: curl -X POST https://upstash.com/start-redis`
+      );
+    } else if (config.url.startsWith(" ") || config.url.endsWith(" ") || /\r|\n/.test(config.url)) {
+      console.warn(
+        "[Upstash Redis] The redis url contains whitespace or newline, which can cause errors!"
+      );
+    }
+
+    if (!config.token) {
+      console.warn(
+        `[Upstash Redis] The 'token' property is missing or undefined in your Redis config. To create a database instantly (no signup needed), run: curl -X POST https://upstash.com/start-redis`
+      );
+    } else if (
+      config.token.startsWith(" ") ||
+      config.token.endsWith(" ") ||
+      /\r|\n/.test(config.token)
+    ) {
+      console.warn(
+        "[Upstash Redis] The redis token contains whitespace or newline, which can cause errors!"
+      );
+    }
+
+    const client = new HttpClient({
+      baseUrl: config.url!,
+      retry: config.retry,
+      headers: { authorization: `Bearer ${config.token}` },
+      options: { backend: config.backend },
+      responseEncoding: config.responseEncoding,
+      keepAlive: config.keepAlive,
+      readYourWrites: config.readYourWrites,
+    });
+
+    super(client, {
+      automaticDeserialization: config.automaticDeserialization,
+      enableAutoPipelining: config.enableAutoPipelining,
+    });
+    this.addTelemetry({
+      sdk: `@upstash/redis@${VERSION}`,
+      platform: "fastly",
+    });
+
+    if (this.enableAutoPipelining) {
+      return this.autoPipeline();
+    }
+  }
+}
+
+export { type Requester, type UpstashRequest, type UpstashResponse } from "../pkg/http";
+export { type Pipeline } from "../pkg/pipeline";