@alchemy.run/redis 0.0.0 → 2.0.0-beta.85

package/lib/index.js

@@ -0,0 +1,28 @@
+/**
+ * Cloud-agnostic Redis runtime client. Fly and Railway resources bind
+ * `REDIS_URL`; this module speaks RESP over that URL. Import from
+ * `@alchemy.run/redis`.
+ *
+ * The codec is a complete RESP2 parser (plus RESP3 types) reimplemented
+ * in TypeScript after the official spec and the algorithm in
+ * `node-redis-parser`. There is no ioredis / node-redis dependency.
+ *
+ * Bindings stay on the cloud (`Fly.ReadWriteRedis`,
+ * `Railway.ReadWriteRedis`). Those layers call {@link makeReadWrite}
+ * so the RESP client is not duplicated.
+ *
+ * @example
+ * ```typescript
+ * import * as Redis from "@alchemy.run/redis";
+ *
+ * const cache = Redis.makeReadWrite(url);
+ * yield* cache.set("marker", "hello");
+ * const value = yield* cache.get("marker");
+ * const custom = yield* cache.send("ECHO", ["hi"]);
+ * ```
+ */
+export * from "./Client.js";
+export * from "./Errors.js";
+export * from "./Protocol.js";
+export * from "./Resp.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/redis",
-  "version": "0.0.0",
+  "version": "2.0.0-beta.85",
   "description": "An Effect RESP client for Redis and Valkey, shared by Alchemy's Redis bindings.",
   "keywords": [
     "alchemy",
@@ -9,12 +9,50 @@
     "resp",
     "valkey"
   ],
+  "homepage": "https://alchemy.run",
+  "bugs": {
+    "url": "https://github.com/alchemy-run/alchemy/issues"
+  },
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
-  "homepage": "https://alchemy.run",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alchemy-run/alchemy.git",
     "directory": "packages/redis"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./*": {
+      "types": "./lib/*.d.ts",
+      "bun": "./src/*.ts",
+      "default": "./lib/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.3",
+    "@types/node": "26.6.5",
+    "effect": "^4.1.0",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "effect": "^4.1.0"
+  },
+  "scripts": {
+    "build": "pnpm -r --filter \"{.}...\" run build:package",
+    "build:package": "node scripts/build.ts"
   }
-}
+}

package/src/Client.ts

@@ -0,0 +1,303 @@
+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);

package/src/Errors.ts

@@ -0,0 +1,27 @@
+import * as Data from "effect/Data";
+
+/** No `REDIS_URL` in the Function/Service environment. */
+export class UrlMissing extends Data.TaggedError("Redis.UrlMissing")<{
+  resourceName: string;
+}> {
+  override get message() {
+    return `REDIS_URL missing for ${this.resourceName}`;
+  }
+}
+
+/** A Redis command failed (RESP error, socket, or protocol). */
+export class CommandError extends Data.TaggedError("Redis.CommandError")<{
+  command: string;
+  cause: unknown;
+}> {}
+
+/** Redis replied with a RESP error (`-ERR …`, `-WRONGTYPE …`). */
+export class ReplyError extends Data.TaggedError("Redis.ReplyError")<{
+  readonly code: string;
+  readonly message: string;
+}> {}
+
+/** Bytes on the wire were not valid RESP. */
+export class ProtocolError extends Data.TaggedError("Redis.ProtocolError")<{
+  readonly message: string;
+}> {}