ioredis-toolkit 0.0.1

package/dist/types.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+// ============================================================================
+// Rate Limiting
+// ============================================================================
+export const RateLimitAlgorithmSchema = z.enum(["fixed", "sliding"]);
+export const RateLimitOptionsSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    duration: z.number().int().positive().default(60),
+    algorithm: RateLimitAlgorithmSchema.default("sliding"),
+    namespace: z.string().min(1).default("ratelimit"),
+});
+// ============================================================================
+// Redis Topology
+// ============================================================================
+export const RedisModeSchema = z.enum(["standalone", "sentinel", "cluster"]);
+export const RedisNodeSchema = z
+    .object({
+    host: z.string().min(1),
+    port: z.number().int().min(1).max(65_535),
+})
+    .strict();
+// ============================================================================
+// TLS
+// ============================================================================
+export const RedisTlsOptionsSchema = z
+    .object({
+    ca: z.string().optional(),
+    cert: z.string().optional(),
+    key: z.string().optional(),
+    rejectUnauthorized: z.boolean().default(true),
+})
+    .strict();
+// ============================================================================
+// Session
+// ============================================================================
+export const SessionOptionsSchema = z.custom();
+// ============================================================================
+// Common Redis Configuration
+// ============================================================================
+/**
+ * Configuration shared by all Redis topologies.
+ *
+ * IMPORTANT:
+ * - This schema describes the user-facing input.
+ * - `.default()` makes the property optional on input while guaranteeing
+ *   the value exists on output.
+ */
+export const BaseRedisConfigSchema = z
+    .object({
+    password: z.string().optional(),
+    username: z.string().optional(),
+    database: z.number().int().min(0).max(15).default(0),
+    tls: z.boolean().default(false),
+    tlsOptions: RedisTlsOptionsSchema.optional(),
+    maxRetries: z.number().int().min(0).max(10).default(3),
+    retryDelay: z.number().int().min(50).max(5_000).default(250),
+    connectionTimeout: z.number().int().min(100).default(5_000),
+    maxFanOutConcurrency: z.number().int().min(1).max(128).default(8),
+    maxBatchSize: z.number().int().min(1).max(10_000).default(500),
+    defaultTTL: z.number().int().min(0).default(3_600),
+    compressionThreshold: z.number().int().min(1).default(1_024),
+    slowCommandThreshold: z.number().int().min(0).default(1_000),
+    rateLimit: RateLimitOptionsSchema.default({
+        algorithm: "sliding",
+        duration: 60,
+        limit: 100,
+        namespace: "ratelimit",
+    }),
+    sessionOptions: z.custom().optional(),
+})
+    .strict();
+// ============================================================================
+// Standalone Configuration
+// ============================================================================
+/**
+ * Standalone Redis configuration.
+ *
+ * `mode` is optional on input because standalone is the default topology.
+ */
+export const StandaloneRedisConfigSchema = BaseRedisConfigSchema.extend({
+    mode: z.literal("standalone").optional(),
+    host: z.string().min(1).default("localhost"),
+    port: z.number().int().min(1).max(65_535).default(6379),
+    url: z.url().optional(),
+}).strict();
+// ============================================================================
+// Sentinel Configuration
+// ============================================================================
+export const SentinelRedisConfigSchema = BaseRedisConfigSchema.extend({
+    mode: z.literal("sentinel"),
+    sentinelNodes: z.array(RedisNodeSchema).min(1),
+    sentinelMasterName: z.string().min(1),
+}).strict();
+// ============================================================================
+// Cluster Configuration
+// ============================================================================
+/**
+ * Redis Cluster only supports database 0.
+ */
+export const ClusterRedisConfigSchema = BaseRedisConfigSchema.extend({
+    mode: z.literal("cluster"),
+    clusterNodes: z.array(RedisNodeSchema).min(1),
+    database: z.literal(0).default(0),
+}).strict();
+// ============================================================================
+// Public Redis Configuration
+// ============================================================================
+/**
+ * Raw configuration union.
+ *
+ * This is intentionally a normal union rather than a discriminated union
+ * because standalone allows `mode` to be omitted.
+ */
+export const RedisConfigInputSchema = z.union([
+    StandaloneRedisConfigSchema,
+    SentinelRedisConfigSchema,
+    ClusterRedisConfigSchema,
+]);
+/**
+ * Normalized configuration.
+ *
+ * After parsing:
+ *
+ * - standalone.mode === "standalone"
+ * - sentinel.mode === "sentinel"
+ * - cluster.mode === "cluster"
+ * - defaults have been materialized
+ */
+export const RedisConfigSchema = RedisConfigInputSchema.transform((config) => {
+    if (config.mode === "sentinel") {
+        return config;
+    }
+    if (config.mode === "cluster") {
+        return config;
+    }
+    return {
+        ...config,
+        mode: "standalone",
+    };
+});

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "ioredis-toolkit",
+  "version": "0.0.1",
+  "description": "Production-grade, type-safe Redis infrastructure for standalone, Sentinel, and Cluster deployments",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./cache": {
+      "types": "./dist/cache.d.ts",
+      "import": "./dist/cache.js"
+    },
+    "./pubsub": {
+      "types": "./dist/pubsub.d.ts",
+      "import": "./dist/pubsub.js"
+    },
+    "./lock": {
+      "types": "./dist/lock.d.ts",
+      "import": "./dist/lock.js"
+    },
+    "./health": {
+      "types": "./dist/health.d.ts",
+      "import": "./dist/health.js"
+    },
+    "./ratelimiter": {
+      "types": "./dist/ratelimiter.d.ts",
+      "import": "./dist/ratelimiter.js"
+    },
+    "./session": {
+      "types": "./dist/session/index.d.ts",
+      "import": "./dist/session/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.mjs",
+    "build:watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "test:coverage": "vitest run --coverage",
+    "format": "prettier --write 'src/**/*.ts'",
+    "clean:git": "git clean -xdf",
+    "changeset:init": "changeset init",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "publish": "changeset publish",
+    "release": "npm run build && changeset publish",
+    "prebuild": "npm run typecheck",
+    "test:unit": "vitest run test/cluster-slot.test.ts test/config.test.ts test/client.test.ts test/cache.test.ts test/ratelimiter.test.ts"
+  },
+  "keywords": [
+    "redis",
+    "cluster",
+    "sentinel",
+    "distributed",
+    "cache",
+    "pubsub",
+    "locking"
+  ],
+  "author": "Your Organization",
+  "license": "MIT",
+  "dependencies": {
+    "ioredis": "^5.11.1",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.1",
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}