sailfork / t3code-github / .repos/ alchemy-effect/ packages/ redis/ src/ Client.ts

import * as Effect from "effect/Effect";
import type { CommandError, UrlMissing } from "./Errors.ts";
import { command, commandPipeline } from "./Protocol.ts";
import type { Arg, Reply } from "./Resp.ts";
import type { RuntimeContext } from "./RuntimeContext.ts";

/**
 * A Redis URL that resolves from the Function/Service environment at
 * runtime (`REDIS_URL`).
 */
export type Url = Effect.Effect<string, UrlMissing, RuntimeContext>;

export type RuntimeError = CommandError | UrlMissing;

export interface SetOptions {
  readonly ex?: number;
  readonly px?: number;
  readonly exAt?: number;
  readonly pxAt?: number;
  readonly nx?: boolean;
  readonly xx?: boolean;
  readonly keepTtl?: boolean;
}

/**
 * Read-only Redis client. Any Redis command is available via {@link Client.send}
 * on the read/write client.
 */
export interface ReadClient {
  get(key: string): Effect.Effect<string | null, RuntimeError, RuntimeContext>;
  mget(...keys: string[]): Effect.Effect<Array<string | null>, RuntimeError, RuntimeContext>;
  ping(message?: string): Effect.Effect<string, RuntimeError, RuntimeContext>;
  echo(message: string): Effect.Effect<string, RuntimeError, RuntimeContext>;
  exists(...keys: string[]): Effect.Effect<number, RuntimeError, RuntimeContext>;
  ttl(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  pttl(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  type(key: string): Effect.Effect<string, RuntimeError, RuntimeContext>;
  hget(key: string, field: string): Effect.Effect<string | null, RuntimeError, RuntimeContext>;
  hmget(
    key: string,
    ...fields: string[]
  ): Effect.Effect<Array<string | null>, RuntimeError, RuntimeContext>;
  hgetall(key: string): Effect.Effect<Record<string, string>, RuntimeError, RuntimeContext>;
  hexists(key: string, field: string): Effect.Effect<boolean, RuntimeError, RuntimeContext>;
  hkeys(key: string): Effect.Effect<string[], RuntimeError, RuntimeContext>;
  hvals(key: string): Effect.Effect<string[], RuntimeError, RuntimeContext>;
  hlen(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  llen(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  lrange(
    key: string,
    start: number,
    stop: number,
  ): Effect.Effect<string[], RuntimeError, RuntimeContext>;
  lindex(key: string, index: number): Effect.Effect<string | null, RuntimeError, RuntimeContext>;
  scard(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  sismember(key: string, member: string): Effect.Effect<boolean, RuntimeError, RuntimeContext>;
  smembers(key: string): Effect.Effect<string[], RuntimeError, RuntimeContext>;
  zscore(key: string, member: string): Effect.Effect<string | null, RuntimeError, RuntimeContext>;
  zcard(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  zrange(
    key: string,
    start: number,
    stop: number,
  ): Effect.Effect<string[], RuntimeError, RuntimeContext>;
}

/**
 * Write Redis client.
 */
export interface WriteClient {
  set(
    key: string,
    value: string | Uint8Array,
    options?: SetOptions,
  ): Effect.Effect<void, RuntimeError, RuntimeContext>;
  mset(
    values: Record<string, string | Uint8Array>,
  ): Effect.Effect<void, RuntimeError, RuntimeContext>;
  del(...keys: string[]): Effect.Effect<number, RuntimeError, RuntimeContext>;
  unlink(...keys: string[]): Effect.Effect<number, RuntimeError, RuntimeContext>;
  expire(key: string, seconds: number): Effect.Effect<boolean, RuntimeError, RuntimeContext>;
  persist(key: string): Effect.Effect<boolean, RuntimeError, RuntimeContext>;
  incr(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  incrBy(key: string, amount: number): Effect.Effect<number, RuntimeError, RuntimeContext>;
  decr(key: string): Effect.Effect<number, RuntimeError, RuntimeContext>;
  hset(
    key: string,
    field: string | Record<string, string | Uint8Array>,
    value?: string | Uint8Array,
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
  hdel(key: string, ...fields: string[]): Effect.Effect<number, RuntimeError, RuntimeContext>;
  hincrBy(
    key: string,
    field: string,
    amount: number,
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
  lpush(
    key: string,
    ...values: Array<string | Uint8Array>
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
  rpush(
    key: string,
    ...values: Array<string | Uint8Array>
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
  lpop(key: string): Effect.Effect<string | null, RuntimeError, RuntimeContext>;
  rpop(key: string): Effect.Effect<string | null, RuntimeError, RuntimeContext>;
  sadd(
    key: string,
    ...members: Array<string | Uint8Array>
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
  srem(
    key: string,
    ...members: Array<string | Uint8Array>
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
  zadd(
    key: string,
    score: number,
    member: string | Uint8Array,
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
  zrem(
    key: string,
    ...members: Array<string | Uint8Array>
  ): Effect.Effect<number, RuntimeError, RuntimeContext>;
}

/**
 * Read + write Redis client. {@link send} is the total command surface —
 * every Redis command is an array of bulk strings on the wire.
 */
export interface Client extends ReadClient, WriteClient {
  send(name: string, args?: readonly Arg[]): Effect.Effect<Reply, RuntimeError, RuntimeContext>;
  pipeline(
    commands: ReadonlyArray<readonly [string, ...Arg[]]>,
  ): Effect.Effect<readonly Reply[], RuntimeError, RuntimeContext>;
}

export interface ReadWriteClient extends Client {}

const asString = (value: unknown): string => {
  if (typeof value === "string") return value;
  if (value == null) return "";
  // RESP scalars (integers, bigints, booleans) coerce to their text form.
  return String(value as number | bigint | boolean);
};

const asNullableString = (value: unknown): string | null => {
  if (value == null) return null;
  return asString(value);
};

const asNumber = (value: unknown): number => {
  if (typeof value === "number" && Number.isFinite(value)) return value;
  if (typeof value === "bigint") return Number(value);
  const parsed = Number(asString(value));
  return Number.isFinite(parsed) ? parsed : 0;
};

const asBoolean = (value: unknown): boolean => asNumber(value) !== 0;

const asStringArray = (value: unknown): string[] => {
  if (!Array.isArray(value)) return [];
  return value.map(asString);
};

const asNullableStringArray = (value: unknown): Array<string | null> => {
  if (!Array.isArray(value)) return [];
  return value.map(asNullableString);
};

const asHash = (value: unknown): Record<string, string> => {
  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
    const out: Record<string, string> = {};
    for (const [key, item] of Object.entries(value)) {
      out[key] = asString(item);
    }
    return out;
  }
  if (!Array.isArray(value)) return {};
  const out: Record<string, string> = {};
  for (let i = 0; i + 1 < value.length; i += 2) {
    out[asString(value[i])] = asString(value[i + 1]);
  }
  return out;
};

const setArgs = (key: string, value: string | Uint8Array, options?: SetOptions): Arg[] => {
  const args: Arg[] = [key, value];
  if (options?.nx) args.push("NX");
  if (options?.xx) args.push("XX");
  if (options?.ex !== undefined) args.push("EX", options.ex);
  if (options?.px !== undefined) args.push("PX", options.px);
  if (options?.exAt !== undefined) args.push("EXAT", options.exAt);
  if (options?.pxAt !== undefined) args.push("PXAT", options.pxAt);
  if (options?.keepTtl) args.push("KEEPTTL");
  return args;
};

/**
 * Read-only client over a runtime Redis URL.
 */
export const makeRead = (url: Url): ReadClient => ({
  get: (key) => command(url, "GET", [key]).pipe(Effect.map(asNullableString)),
  mget: (...keys) => command(url, "MGET", keys).pipe(Effect.map(asNullableStringArray)),
  ping: (message) =>
    command(url, "PING", message === undefined ? [] : [message]).pipe(Effect.map(asString)),
  echo: (message) => command(url, "ECHO", [message]).pipe(Effect.map(asString)),
  exists: (...keys) => command(url, "EXISTS", keys).pipe(Effect.map(asNumber)),
  ttl: (key) => command(url, "TTL", [key]).pipe(Effect.map(asNumber)),
  pttl: (key) => command(url, "PTTL", [key]).pipe(Effect.map(asNumber)),
  type: (key) => command(url, "TYPE", [key]).pipe(Effect.map(asString)),
  hget: (key, field) => command(url, "HGET", [key, field]).pipe(Effect.map(asNullableString)),
  hmget: (key, ...fields) =>
    command(url, "HMGET", [key, ...fields]).pipe(Effect.map(asNullableStringArray)),
  hgetall: (key) => command(url, "HGETALL", [key]).pipe(Effect.map(asHash)),
  hexists: (key, field) => command(url, "HEXISTS", [key, field]).pipe(Effect.map(asBoolean)),
  hkeys: (key) => command(url, "HKEYS", [key]).pipe(Effect.map(asStringArray)),
  hvals: (key) => command(url, "HVALS", [key]).pipe(Effect.map(asStringArray)),
  hlen: (key) => command(url, "HLEN", [key]).pipe(Effect.map(asNumber)),
  llen: (key) => command(url, "LLEN", [key]).pipe(Effect.map(asNumber)),
  lrange: (key, start, stop) =>
    command(url, "LRANGE", [key, start, stop]).pipe(Effect.map(asStringArray)),
  lindex: (key, index) => command(url, "LINDEX", [key, index]).pipe(Effect.map(asNullableString)),
  scard: (key) => command(url, "SCARD", [key]).pipe(Effect.map(asNumber)),
  sismember: (key, member) => command(url, "SISMEMBER", [key, member]).pipe(Effect.map(asBoolean)),
  smembers: (key) => command(url, "SMEMBERS", [key]).pipe(Effect.map(asStringArray)),
  zscore: (key, member) => command(url, "ZSCORE", [key, member]).pipe(Effect.map(asNullableString)),
  zcard: (key) => command(url, "ZCARD", [key]).pipe(Effect.map(asNumber)),
  zrange: (key, start, stop) =>
    command(url, "ZRANGE", [key, start, stop]).pipe(Effect.map(asStringArray)),
});

/**
 * Write client over a runtime Redis URL.
 */
export const makeWrite = (url: Url): WriteClient => ({
  set: (key, value, options) =>
    command(url, "SET", setArgs(key, value, options)).pipe(Effect.asVoid),
  mset: (values) => {
    const args: Arg[] = [];
    for (const [key, value] of Object.entries(values)) {
      args.push(key, value);
    }
    return command(url, "MSET", args).pipe(Effect.asVoid);
  },
  del: (...keys) => command(url, "DEL", keys).pipe(Effect.map(asNumber)),
  unlink: (...keys) => command(url, "UNLINK", keys).pipe(Effect.map(asNumber)),
  expire: (key, seconds) => command(url, "EXPIRE", [key, seconds]).pipe(Effect.map(asBoolean)),
  persist: (key) => command(url, "PERSIST", [key]).pipe(Effect.map(asBoolean)),
  incr: (key) => command(url, "INCR", [key]).pipe(Effect.map(asNumber)),
  incrBy: (key, amount) => command(url, "INCRBY", [key, amount]).pipe(Effect.map(asNumber)),
  decr: (key) => command(url, "DECR", [key]).pipe(Effect.map(asNumber)),
  hset: (key, field, value) => {
    const args: Arg[] = [key];
    if (typeof field === "string") {
      args.push(field, value ?? "");
    } else {
      for (const [name, item] of Object.entries(field)) {
        args.push(name, item);
      }
    }
    return command(url, "HSET", args).pipe(Effect.map(asNumber));
  },
  hdel: (key, ...fields) => command(url, "HDEL", [key, ...fields]).pipe(Effect.map(asNumber)),
  hincrBy: (key, field, amount) =>
    command(url, "HINCRBY", [key, field, amount]).pipe(Effect.map(asNumber)),
  lpush: (key, ...values) => command(url, "LPUSH", [key, ...values]).pipe(Effect.map(asNumber)),
  rpush: (key, ...values) => command(url, "RPUSH", [key, ...values]).pipe(Effect.map(asNumber)),
  lpop: (key) => command(url, "LPOP", [key]).pipe(Effect.map(asNullableString)),
  rpop: (key) => command(url, "RPOP", [key]).pipe(Effect.map(asNullableString)),
  sadd: (key, ...members) => command(url, "SADD", [key, ...members]).pipe(Effect.map(asNumber)),
  srem: (key, ...members) => command(url, "SREM", [key, ...members]).pipe(Effect.map(asNumber)),
  zadd: (key, score, member) =>
    command(url, "ZADD", [key, score, member]).pipe(Effect.map(asNumber)),
  zrem: (key, ...members) => command(url, "ZREM", [key, ...members]).pipe(Effect.map(asNumber)),
});

/**
 * Full Redis client over a runtime Redis URL.
 *
 * Fly and Railway `*RedisHttp` layers pass this (or {@link makeRead} /
 * {@link makeWrite}) as `makeClient`. Tests can also drive RESP
 * directly via `command` / `run` / `connect`.
 *
 * ```typescript
 * import * as Redis from "@alchemy.run/redis";
 *
 * const cache = Redis.make(url);
 * yield* cache.set("marker", "hello");
 * const value = yield* cache.get("marker");
 * const echoed = yield* cache.send("ECHO", ["hi"]);
 * ```
 */
export const make = (url: Url): Client => ({
  ...makeRead(url),
  ...makeWrite(url),
  send: (name, args = []) => command(url, name, args),
  pipeline: (commands) => commandPipeline(url, commands),
});

/**
 * Read + write client over a runtime Redis URL. Alias of {@link make}.
 */
export const makeReadWrite = (url: Url): ReadWriteClient => make(url);