@n8io/baseline-redis 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @n8io/baseline-redis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The one Redis connection a process shares, for `@n8io/baseline-cache` and `@n8io/baseline-live`. It owns the parts every app gets wrong when it copies them: an unreachable Redis fails startup at once instead of retrying forever, a dropped connection reconnects for good after that, and the client's `error` event is always listened to, since node-redis exits the process on an unlistened one.
+
+```sh
+pnpm add @n8io/baseline-redis
+```
+
+## Exports
+
+- `redisClientCreate({ url, vendor? })`: resolves with a connected node-redis client. The connect, handshake included, gives up after 3 s and never retries, so startup fails while Redis is unreachable or not answering. Once connected, a dropped connection reconnects every min(retries × 100 ms, 2 s), for as long as it takes. A command waits at most 1 s to be sent. Errors are logged at error, never with the URL, which may carry a password.
+- `RedisClient`: what it resolves with, a node-redis client. Close it with `close()`; `await using` calls `close()` when its block ends.
+- `RedisClientVendorOptions`: `vendor`, node-redis's own client settings (`socket.ca`, `name`, `keyPrefix`), outside the contract. A key the URL or this Package sets throws: `username`, `password`, `database`, `commandOptions`, `socket.host`, `socket.port`, `socket.path`, `socket.tls`, `socket.connectTimeout` and `socket.reconnectStrategy`, and `credentialsProvider` when the URL carries a user or password.
+
+`url` is `redis://` or `rediss://` (TLS), with any user, password and database in it. One URL fits a highly available Redis whose endpoint follows the primary: a managed one, or a proxy in front of Sentinel. For Sentinel or Cluster addressed directly, `pnpm add redis` and build the client with node-redis's `createSentinel` or `createCluster` yourself, with your own `error` listener, and pass it to the cache and live adapters, which take any connected node-redis client. Nothing tests that path.
+
+## Example
+
+Open one connection per process and build the cache store and live hub on it:
+
+```ts
+import { cacheStoreRedisCreate } from "@n8io/baseline-cache";
+import { liveHubRedisCreate } from "@n8io/baseline-live";
+import { redisClientCreate } from "@n8io/baseline-redis";
+
+const redisClient = await redisClientCreate({ url: ENV.CACHE_URL });
+const cacheStore = cacheStoreRedisCreate({ redisClient });
+const liveHub = liveHubRedisCreate({ redisClient });
+
+// At shutdown, after the live hub:
+await liveHub.close();
+await redisClient.close();
+```
+
+## Tests
+
+`pnpm test` runs every test; the `*.redis.test.ts` files start a Redis container, so they need Docker.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { RedisClientOptions as RedisClientOptions$1, RedisClientType } from "redis";
+/**
+ * A connected node-redis client, for `cacheStoreRedisCreate`, `liveHubRedisCreate` and a Project's
+ * own adapters. Close it with `close()`; `await using` calls `close()` when its block ends.
+ */
+type RedisClient = RedisClientType & AsyncDisposable;
+declare const redisVendorOwnedKeys: {
+  readonly commandOptions: "this Package (1 s to send a command)";
+  readonly database: "url (redis://host/<database>)";
+  readonly password: "url (redis://user:password@host)";
+  readonly url: "url";
+  readonly username: "url (redis://user:password@host)";
+};
+/**
+ * node-redis's own client settings, passed through as they are: `socket.ca`, `name`, `keyPrefix`
+ * and the like. Outside this Package's contract: nothing here is tested, and moving off
+ * node-redis deletes it. The keys the URL and this Package set are refused, and the ones that would
+ * change the client's type are left out.
+ */
+type RedisClientVendorOptions = Omit<RedisClientOptions$1, keyof typeof redisVendorOwnedKeys | "functions" | "modules" | "RESP" | "scripts" | "typeMapping">;
+/** What `redisClientCreate` takes; not node-redis's own `RedisClientOptions`, which `vendor` carries. */
+type RedisClientOptions = {
+  /** redis:// or rediss:// (TLS). It may carry a user, a password and a database number. */
+  url: string;
+  /** Settings only node-redis has. */
+  vendor?: RedisClientVendorOptions | null;
+};
+/**
+ * Opens the one Redis connection a process shares, and resolves once it is connected, so an
+ * unreachable Redis stops startup within the 3 s connect timeout instead of retrying. After that a
+ * dropped connection reconnects every min(retries × 100 ms, 2 s), for as long as it takes. One URL
+ * fits a highly available Redis whose endpoint follows the primary (a managed one, or a proxy in
+ * front of Sentinel); Sentinel or Cluster addressed directly is not supported.
+ */
+export declare const redisClientCreate: ({ url, vendor }: RedisClientOptions) => Promise<RedisClient>;
+export type { RedisClient, RedisClientOptions, RedisClientVendorOptions };

package/dist/index.js

@@ -0,0 +1,77 @@
+import { logger } from "@n8io/baseline-logger";
+import { createClient } from "redis";
+// src/redis-client.ts
+const redisVendorOwnedKeys = {
+	commandOptions: "this Package (1 s to send a command)",
+	database: "url (redis://host/<database>)",
+	password: "url (redis://user:password@host)",
+	url: "url",
+	username: "url (redis://user:password@host)"
+};
+const redisVendorOwnedSocketKeys = {
+	connectTimeout: "this Package (3 s)",
+	host: "url",
+	path: "url",
+	port: "url",
+	reconnectStrategy: "this Package (fail at startup, then retry for good)",
+	tls: "url (rediss:// for TLS)"
+};
+const redisConnectTimeoutMs = 3e3;
+const redisVendorAssert = ({ url, vendor }) => {
+	const { password, username } = new URL(url);
+	if ("credentialsProvider" in vendor && (password || username)) throw new TypeError("vendor.credentialsProvider is not allowed with a user or password in url: node-redis lets the URL win; set credentials in one place");
+	const owned = [[
+		vendor,
+		"vendor",
+		redisVendorOwnedKeys
+	], [
+		vendor.socket ?? {},
+		"vendor.socket",
+		redisVendorOwnedSocketKeys
+	]];
+	for (const [settings, path, keys] of owned) for (const [key, owner] of Object.entries(keys)) if (key in settings) throw new TypeError(`${path}.${key} is not allowed: it is set by ${owner}`);
+};
+/**
+* Opens the one Redis connection a process shares, and resolves once it is connected, so an
+* unreachable Redis stops startup within the 3 s connect timeout instead of retrying. After that a
+* dropped connection reconnects every min(retries × 100 ms, 2 s), for as long as it takes. One URL
+* fits a highly available Redis whose endpoint follows the primary (a managed one, or a proxy in
+* front of Sentinel); Sentinel or Cluster addressed directly is not supported.
+*/
+const redisClientCreate = async ({ url, vendor }) => {
+	const settings = vendor ?? {};
+	redisVendorAssert({
+		url,
+		vendor: settings
+	});
+	let connected = false;
+	const redisClient = createClient({
+		...settings,
+		commandOptions: { timeout: 1e3 },
+		socket: {
+			...settings.socket,
+			connectTimeout: redisConnectTimeoutMs,
+			reconnectStrategy: (retries) => connected ? Math.min(retries * 100, 2e3) : false
+		},
+		url
+	});
+	redisClient.on("error", (err) => {
+		logger.error({ err }, "Redis client error");
+	});
+	let timer;
+	try {
+		await Promise.race([redisClient.connect(), new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				reject(new DOMException(`Redis not ready within ${redisConnectTimeoutMs} ms`, "TimeoutError"));
+			}, redisConnectTimeoutMs);
+		})]);
+	} catch (err) {
+		if (redisClient.isOpen) redisClient.destroy();
+		throw err;
+	} finally {
+		clearTimeout(timer);
+	}
+	connected = true;
+	return Object.assign(redisClient, { [Symbol.asyncDispose]: () => redisClient.close() });
+};
+export { redisClientCreate };

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@n8io/baseline-redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "The one Redis connection a baseline app shares: it fails fast at startup and reconnects for good after.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/n8io/baseline.git",
+    "directory": "packages/redis"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@n8io/baseline-logger": "^3.1.0",
+    "redis": "^6.3.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc --noEmit && pnpm pack --out dist/package.tgz && publint dist/package.tgz --strict && attw dist/package.tgz --profile esm-only",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit --passWithNoTests"
+  }
 }