@oneunit/redis 0.0.0-stage → 1.0.0

package/examples/session.js

@@ -0,0 +1,145 @@
+/**
+ * Session store on Redis.
+ *
+ *   npm run example:session
+ *
+ * Environment:
+ *   REDIS_URL    connection URL (default redis://localhost:6379)
+ *   REDIS_SILENT set to "true" to suppress connection-event logging
+ *
+ * Sessions belong in Redis rather than in process memory for two reasons: they
+ * survive a restart, and they are visible to every instance behind a load
+ * balancer. The TTL is what bounds their lifetime, so it is set on write and
+ * refreshed on activity.
+ */
+
+import { randomUUID } from "node:crypto";
+import { createClient, health, shutdown } from "@oneunit/redis";
+import { REDIS_URL, exampleLogger, onFailure, release, run } from "./_setup.js";
+
+const SESSION_TTL_SECONDS = 3600;
+const KEY_PREFIX = "example:session:";
+
+await run("session", async () => {
+  const client = createClient({ url: REDIS_URL }, exampleLogger);
+  onFailure(() => shutdown(client, exampleLogger));
+
+  const healthResult = await health(client);
+  if (healthResult.status === "down") {
+    // Always shut down, including on this early exit: ioredis retries in the
+    // background, so a client left open keeps the event loop alive and the
+    // script never exits.
+    console.log("Redis is not reachable, stopping here.");
+    console.log("Health:", healthResult);
+    await release();
+    return;
+  }
+
+  const key = (sessionId) => `${KEY_PREFIX}${sessionId}`;
+
+  const sessions = {
+    async create(userId, data = {}) {
+      const session = {
+        id: randomUUID(),
+        userId,
+        createdAt: Date.now(),
+        ...data,
+      };
+
+      await client.setex(
+        key(session.id),
+        SESSION_TTL_SECONDS,
+        JSON.stringify(session),
+      );
+
+      return session;
+    },
+
+    async get(sessionId) {
+      // Returns null rather than throwing for a missing session, so callers
+      // treat "no session" and "expired session" the same way.
+      const raw = await client.get(key(sessionId));
+      return raw === null ? null : JSON.parse(raw);
+    },
+
+    async update(sessionId, patch) {
+      const existing = await sessions.get(sessionId);
+      if (!existing) {
+        return null;
+      }
+
+      const updated = { ...existing, ...patch, updatedAt: Date.now() };
+
+      // Rewriting with SETEX resets the TTL to the full window. Refresh on
+      // a sliding window only; an absolute-expiry session would use PERSIST
+      // here instead so the original deadline stands.
+      await client.setex(
+        key(sessionId),
+        SESSION_TTL_SECONDS,
+        JSON.stringify(updated),
+      );
+
+      return updated;
+    },
+
+    async extend(sessionId, ttlSeconds = SESSION_TTL_SECONDS) {
+      // EXPIRE on a missing key returns 0, not 1, which is the cheapest way
+      // to tell whether the session was still alive.
+      return client.expire(key(sessionId), ttlSeconds);
+    },
+
+    async touch(sessionId) {
+      // Refresh the TTL without reading or rewriting the payload.
+      return sessions.extend(sessionId);
+    },
+
+    async destroy(sessionId) {
+      return client.del(key(sessionId));
+    },
+  };
+
+  console.log("Create:");
+  const session = await sessions.create("user-123", {
+    role: "admin",
+    permissions: ["read", "write"],
+  });
+  console.log("  ", session);
+  console.log("   TTL:", await client.ttl(key(session.id)), "seconds");
+
+  console.log("\nGet:");
+  console.log("  ", await sessions.get(session.id));
+
+  console.log("\nGet a session that does not exist:");
+  console.log("  ", await sessions.get("not-a-real-session"));
+
+  console.log("\nUpdate:");
+  const updated = await sessions.update(session.id, {
+    lastActivity: Date.now(),
+  });
+  console.log(
+    "   role:",
+    updated.role,
+    "| updatedAt set:",
+    updated.updatedAt > updated.createdAt,
+  );
+
+  console.log("\nExtend the TTL to 2 hours:");
+  const extended = await sessions.extend(session.id, 7200);
+  console.log(
+    "   EXPIRE returned",
+    extended,
+    "| TTL now:",
+    await client.ttl(key(session.id)),
+  );
+
+  console.log("\nTouch (refresh TTL without rewriting the payload):");
+  await sessions.touch(session.id);
+  console.log("   TTL:", await client.ttl(key(session.id)));
+
+  console.log("\nDestroy:");
+  console.log("   DEL removed", await sessions.destroy(session.id), "key(s)");
+  console.log("   get after destroy:", await sessions.get(session.id));
+
+  await release();
+  console.log("\nDisconnected cleanly.");
+});

package/examples/standalone.js

@@ -0,0 +1,58 @@
+/**
+ * Standalone client: connect, check health, read and write, disconnect.
+ *
+ *   npm run example:standalone
+ *
+ * Environment:
+ *   REDIS_URL    connection URL (default redis://localhost:6379)
+ *   REDIS_SILENT set to "true" to suppress connection-event logging
+ *
+ * `createClient` returns a plain ioredis instance, so every ioredis command is
+ * available on it. The defaults are chosen so one client works for both plain
+ * commands and BullMQ: `url` falls back to REDIS_URL, `lazyConnect` avoids
+ * opening a socket at construction, and `maxRetriesPerRequest: null` is what
+ * BullMQ requires.
+ */
+
+import { createClient, health, shutdown } from "@oneunit/redis";
+import { REDIS_URL, exampleLogger, onFailure, release, run } from "./_setup.js";
+
+await run("standalone", async () => {
+  const client = createClient({ url: REDIS_URL }, exampleLogger);
+  onFailure(() => shutdown(client, exampleLogger));
+
+  // `lazyConnect` is on, so nothing is connected until the first command.
+  // `health` issues PING and reports how long it took.
+  const healthResult = await health(client);
+
+  if (healthResult.status === "down") {
+    // Always shut the client down, including on this early exit. ioredis
+    // retries in the background, so a client left open keeps the event loop
+    // alive and the script never exits.
+    console.log("Redis is not reachable, stopping here.");
+    console.log("Set REDIS_URL if your server is not on localhost:6379.");
+    console.log("Health:", healthResult);
+    await release();
+    return;
+  }
+
+  console.log("Health:", healthResult);
+
+  await client.set("greeting", "hello from @oneunit/redis");
+  console.log("GET greeting:", await client.get("greeting"));
+
+  // INCR is atomic in Redis, so concurrent callers cannot interleave.
+  await client.set("visits", 0);
+  const visits = await client.incrby("visits", 5);
+  console.log("INCRBY visits 5 ->", visits);
+
+  // EXPIRE sets a TTL in seconds. A key with no TTL lives forever, which is
+  // the usual cause of a Redis instance quietly filling up.
+  await client.expire("greeting", 60);
+  console.log("TTL greeting:", await client.ttl("greeting"), "seconds");
+
+  await client.del("greeting", "visits");
+
+  await release();
+  console.log("\nDisconnected cleanly.");
+});

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@oneunit/redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Redis client and BullMQ job queues for Node.js. Works standalone or with any logger that has error, warn, info, and debug.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "default": "./dist/client/index.js"
+    },
+    "./queue": {
+      "types": "./dist/queue/index.d.ts",
+      "import": "./dist/queue/index.js",
+      "default": "./dist/queue/index.js"
+    },
+    "./pipeline": {
+      "types": "./dist/pipeline/index.d.ts",
+      "import": "./dist/pipeline/index.js",
+      "default": "./dist/pipeline/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "LICENSE",
+    "README.md",
+    "ARCHITECTURE.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"const fs=require('node:fs');for(const p of ['dist','tsconfig.tsbuildinfo'])fs.rmSync(p,{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "dev": "tsc -w -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:watch": "tsx --test --watch test/*.test.ts",
+    "lint": "eslint src test",
+    "example:standalone": "npm run build && node examples/standalone.js",
+    "example:cache": "npm run build && node examples/cache.js",
+    "example:session": "npm run build && node examples/session.js",
+    "example:pipeline": "npm run build && node examples/pipeline.js",
+    "example:pubsub": "npm run build && node examples/pubsub.js",
+    "example:queue-worker": "npm run build && node examples/queue-worker.js",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm test",
+    "pack:check": "npm pack --dry-run",
+    "verify": "npm run build && npm run typecheck && npm run lint && npm test && npm run pack:check"
+  },
+  "keywords": [
+    "redis",
+    "ioredis",
+    "bullmq",
+    "queue",
+    "worker",
+    "cache",
+    "session",
+    "nodejs",
+    "microservice",
+    "oneunit"
+  ],
+  "author": "mayank",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mayank040902/oneunit.git",
+    "directory": "packages/redis"
+  },
+  "bugs": {
+    "url": "https://github.com/mayank040902/oneunit/issues"
+  },
+  "homepage": "https://github.com/mayank040902/oneunit/tree/master/packages/redis#readme",
+  "dependencies": {
+    "bullmq": "^5.80.9",
+    "ioredis": "^5.11.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "eslint": "^9.22.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.8.2"
+  }
+}

package/src/client/check.ts

@@ -0,0 +1,69 @@
+import { performance } from "node:perf_hooks";
+import { type Redis as RedisClient } from "ioredis";
+
+export interface HealthResult {
+  status: "up" | "down";
+  latency: {
+    value: number;
+    unit: "ms";
+  };
+  error?: string;
+}
+
+export interface HealthOptions {
+  /**
+   * Milliseconds to wait for PING before reporting `down`. ioredis queues
+   * commands while reconnecting, so without a bound a PING against an
+   * unreachable server never settles and health checks hang forever.
+   */
+  timeout?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 1000;
+
+export async function health(
+  client: RedisClient,
+  options: HealthOptions = {},
+): Promise<HealthResult> {
+  const requested = options.timeout ?? DEFAULT_TIMEOUT_MS;
+  // setTimeout coerces negatives to 1 and NaN to 1, and Node prints a
+  // TimeoutNegativeWarning/TimeoutNaNWarning for each. Treat any invalid
+  // budget as "no bound configured" rather than leaking warnings per call.
+  const timeout =
+    Number.isFinite(requested) && requested > 0
+      ? requested
+      : DEFAULT_TIMEOUT_MS;
+  const start = performance.now();
+
+  const elapsed = (): number => Math.round(performance.now() - start);
+
+  let timer: NodeJS.Timeout | undefined;
+  const expiry = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`Health check timed out after ${timeout}ms`));
+    }, timeout);
+  });
+
+  try {
+    await Promise.race([client.ping(), expiry]);
+
+    return {
+      status: "up",
+      latency: {
+        value: elapsed(),
+        unit: "ms",
+      },
+    };
+  } catch (error) {
+    return {
+      status: "down",
+      latency: {
+        value: elapsed(),
+        unit: "ms",
+      },
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/client/client.ts

@@ -0,0 +1,45 @@
+import { Redis } from "ioredis";
+import { attachEvents } from "./events.js";
+import { normalizeLogger, type Logger } from "../logger.js";
+import type { RedisOptions } from "ioredis";
+
+export interface RedisClientOptions extends RedisOptions {
+  url?: string;
+  lazyConnect?: boolean;
+}
+
+export function createClient(
+  options: RedisClientOptions | string = {},
+  logger?: Logger,
+): Redis {
+  // ioredis's own constructor accepts `new Redis("redis://host:port")`, so
+  // that is the form people reach for first. Destructuring the string as an
+  // options object produces no `url`, which leaves the client pointing at
+  // localhost:6379: a silent connection to the wrong server, with no error
+  // anywhere to notice it by.
+  const resolved: RedisClientOptions =
+    typeof options === "string" ? { url: options } : options;
+
+  const {
+    url = process.env.REDIS_URL,
+    lazyConnect = true,
+    // BullMQ throws unless this is null on the connections it drives, and
+    // `createQueue`/`createWorker` take this same client instance.
+    maxRetriesPerRequest = null,
+    ...restOptions
+  } = resolved;
+
+  // ioredis only reads `url` from the first positional argument; an options
+  // object carrying `url` is silently ignored and connects to localhost.
+  const client = url
+    ? new Redis(url, { ...restOptions, lazyConnect, maxRetriesPerRequest })
+    : new Redis({ ...restOptions, lazyConnect, maxRetriesPerRequest });
+
+  // A caller-supplied logger may implement only some of the levels. Completing
+  // it here keeps `attachEvents` from throwing mid-connection-event.
+  attachEvents(client, normalizeLogger(logger));
+
+  return client;
+}
+
+export type { Logger } from "../logger.js";

package/src/client/events.ts

@@ -0,0 +1,101 @@
+import { normalizeLogger, type Logger } from "../logger.js";
+import { type Redis as RedisClient } from "ioredis";
+
+/** Command names whose arguments must never be logged. */
+const SECRET_COMMANDS = new Set(["auth", "hello"]);
+
+/**
+ * Strip credentials before an error reaches a logger.
+ *
+ * ioredis attaches the failing command to its errors, and for `AUTH` that
+ * command's args are the username and the password in plaintext:
+ *
+ *   { command: { name: "auth", args: ["default", "hunter2-real-secret"] } }
+ *
+ * Logging the error as-is writes the Redis password to whatever the app logs
+ * to, on every failed authentication. The message itself is safe; only the
+ * attached command is not, so only that part is replaced.
+ */
+/** An ioredis error, which carries the failing command alongside the message. */
+type CommandError = Error & {
+  command?: { name?: unknown; args?: unknown } | null;
+};
+
+export function redactError(error: unknown): unknown {
+  if (!(error instanceof Error)) {
+    return error;
+  }
+
+  const command = (error as CommandError).command;
+
+  if (
+    typeof command === "object" &&
+    command !== null &&
+    SECRET_COMMANDS.has(String(command.name).toLowerCase())
+  ) {
+    // Copy rather than mutate: ioredis may still be using this error, and the
+    // caller has no reason to lose the original for their own handling.
+    //
+    // `message` is deliberately kept. Redis error text is what tells an
+    // operator *why* authentication failed, and it never echoes the password
+    // back. Only the attached command's args carry it.
+    const safe = new Error(error.message) as CommandError;
+    safe.name = error.name;
+    safe.stack = error.stack;
+    safe.command = { ...command, args: "[redacted]" };
+
+    return safe;
+  }
+
+  return error;
+}
+
+/**
+ * Marks a client this function has already wired up.
+ *
+ * `attachEvents` is exported and `createClient` calls it. A caller reaching for
+ * the exported helper on a client from `createClient` would otherwise get a
+ * second full set of listeners, logging every connection event twice. BullMQ
+ * adds listeners to the same client too, so crossing the default limit of 10
+ * and tripping `MaxListenersExceededWarning` should not be something a
+ * consumer causes by accident.
+ *
+ * A global symbol is used so two copies of this package in one dependency tree
+ * still recognise a client the other already wired.
+ */
+const WIRED = Symbol.for("oneunit.redis.eventsAttached");
+
+export function attachEvents(client: RedisClient, loggerInput?: Logger): void {
+  if ((client as unknown as Record<symbol, boolean>)[WIRED]) {
+    return;
+  }
+
+  Object.defineProperty(client, WIRED, {
+    value: true,
+    enumerable: false,
+  });
+
+  const logger = normalizeLogger(loggerInput);
+
+  client.on("connect", () => {
+    logger?.info("redis connect");
+  });
+
+  client.on("ready", () => {
+    logger?.info("redis ready");
+  });
+
+  client.on("reconnecting", (delay: number) => {
+    logger?.warn(
+      delay ? `redis reconnecting in ${delay}ms` : "redis reconnecting",
+    );
+  });
+
+  client.on("error", (err: Error) => {
+    logger?.error("redis error", { err: redactError(err) });
+  });
+
+  client.on("close", () => {
+    logger?.info("redis close");
+  });
+}

package/src/client/index.ts

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export type { RedisClientOptions, Logger } from "./client.js";
+export { attachEvents, redactError } from "./events.js";
+export { health, type HealthResult, type HealthOptions } from "./check.js";
+export { shutdown } from "./shutdown.js";

package/src/client/shutdown.ts

@@ -0,0 +1,97 @@
+import { normalizeLogger, type Logger } from "../logger.js";
+import { redactError } from "./events.js";
+import { type Redis as RedisClient } from "ioredis";
+
+/**
+ * How long to wait for QUIT before forcing the connection closed.
+ *
+ * QUIT is a queued command: ioredis only sends it on a live connection, so a
+ * client stuck in `reconnecting` parks it in the offline queue and the promise
+ * never settles. Without a bound, `shutdown` hangs for the lifetime of the
+ * outage, which is exactly when a process most needs to be able to exit.
+ */
+const DEFAULT_TIMEOUT_MS = 5000;
+
+const isClosed = (client: RedisClient): boolean =>
+  client.status === "end" || FORCED.has(client);
+
+/**
+ * Clients this function already tore down by force.
+ *
+ * `disconnect()` only reaches ioredis's `closeHandler` from a live connection.
+ * On a client sitting in `reconnecting` the connector has nothing to close, so
+ * the status never becomes `end` even though `disconnect()` has cleared the
+ * retry timer and the connection can never come back. Shutdown is registered on
+ * both SIGINT and SIGTERM in most apps, so the second call would otherwise wait
+ * out the full QUIT deadline again for a connection that is already gone.
+ *
+ * A `WeakSet` keeps this bookkeeping off the client object, so it does not
+ * show up in `Object.keys`, in a serialised snapshot, or in BullMQ's own
+ * inspection of the connection.
+ */
+const FORCED = new WeakSet<object>();
+
+export async function shutdown(
+  client: RedisClient | null | undefined,
+  loggerInput?: Logger,
+): Promise<void> {
+  if (!client) {
+    return;
+  }
+
+  // Completing the logger here matters more than anywhere else: shutdown runs
+  // during teardown, so `logger?.info is not a function` would replace a clean
+  // disconnect with a rejection on the way out.
+  const logger = normalizeLogger(loggerInput);
+
+  // Once ioredis reaches "end" the connection is gone for good and QUIT
+  // rejects with "Connection is closed.". Shutdown is registered on both
+  // SIGINT and SIGTERM in most apps, so a second call has to be a no-op
+  // rather than an unhandled rejection during teardown.
+  if (isClosed(client)) {
+    return;
+  }
+
+  let timer: NodeJS.Timeout | undefined;
+  const expiry = new Promise<"timeout">((resolve) => {
+    timer = setTimeout(() => resolve("timeout"), DEFAULT_TIMEOUT_MS);
+  });
+
+  try {
+    const outcome = await Promise.race([
+      client.quit().then(() => "quit" as const),
+      expiry,
+    ]);
+
+    if (outcome === "timeout") {
+      // The server never acknowledged QUIT. Tear the connection down
+      // directly so the retry loop stops and the process can exit; the
+      // caller asked to disconnect, and we are, one way or another.
+      logger?.warn(
+        `Redis did not acknowledge QUIT within ${DEFAULT_TIMEOUT_MS}ms, forcing the connection closed`,
+      );
+      client.disconnect();
+      FORCED.add(client);
+
+      return;
+    }
+
+    logger?.info("Redis disconnected");
+  } catch (error) {
+    // A connection that died mid-shutdown is already disconnected from the
+    // caller's point of view, so treat it as success but still surface it.
+    if (isClosed(client)) {
+      logger?.warn(
+        "Redis connection closed before QUIT completed",
+        redactError(error),
+      );
+      return;
+    }
+
+    logger?.error("Failed to disconnect Redis", redactError(error));
+
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./client/index.js";
+export * from "./queue/index.js";
+export * from "./logger.js";
+export * from "./pipeline/index.js";