effect-redis 0.0.20 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-redis",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Simple Effect wrapper for Redis.",
   "module": "dist/index.js",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
   "type": "module",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "src"
   ],
   "scripts": {
     "build:main": "bun build --minify-syntax --minify-whitespace ./src/index.ts --outdir ./dist --target node --format esm",
@@ -29,7 +30,7 @@
     "vitest": "^4.0.16"
   },
   "peerDependencies": {
-    "effect": "^3.19.9",
+    "effect": "^3.19.14",
     "redis": "^5.1.0",
     "typescript": "^5"
   },
@@ -37,4 +38,4 @@
     "@effect/experimental": "^0.58.0",
     "@effect/platform-bun": "^0.87.0"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// Re-export all Redis services and utilities from the modular structure
+export * from './redis';
+
+// Re-export types
+export * from './types';

package/src/redis/config.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Redis configuration validation and utilities
+ */
+
+import { Effect } from 'effect';
+import type { RedisConfig } from '../types';
+import { RedisConnectionError } from '../types';
+
+/**
+ * Default Redis configuration values
+ */
+export const DEFAULT_REDIS_CONFIG = {
+  host: 'localhost',
+  port: 6379,
+  connectTimeout: 10000,
+  commandTimeout: 5000,
+} as const;
+
+/**
+ * Validates Redis URL format
+ */
+const isValidRedisUrl = (url: string): boolean => {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'redis:' || parsed.protocol === 'rediss:';
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Validates Redis host configuration
+ */
+const validateHostConfig = (config: {
+  readonly host: string;
+  readonly port: number;
+  readonly username?: string;
+  readonly password?: string;
+  readonly database?: number;
+  readonly ssl?: boolean;
+  readonly connectTimeout?: number;
+  readonly commandTimeout?: number;
+}): Effect.Effect<void, RedisConnectionError> => {
+  if (!config.host || config.host.trim() === '') {
+    return Effect.fail(
+      new RedisConnectionError({
+        cause: new Error('Invalid host'),
+        message: 'Redis host cannot be empty',
+      }),
+    );
+  }
+
+  if (config.port <= 0 || config.port > 65535) {
+    return Effect.fail(
+      new RedisConnectionError({
+        cause: new Error('Invalid port'),
+        message: `Redis port must be between 1 and 65535, got ${config.port}`,
+      }),
+    );
+  }
+
+  if (
+    config.database !== undefined &&
+    (config.database < 0 || config.database > 15)
+  ) {
+    return Effect.fail(
+      new RedisConnectionError({
+        cause: new Error('Invalid database'),
+        message: `Redis database must be between 0 and 15, got ${config.database}`,
+      }),
+    );
+  }
+
+  return Effect.void;
+};
+
+/**
+ * Validates Redis URL configuration
+ */
+const validateUrlConfig = (config: {
+  readonly url: string;
+  readonly connectTimeout?: number;
+  readonly commandTimeout?: number;
+}): Effect.Effect<void, RedisConnectionError> => {
+  if (!isValidRedisUrl(config.url)) {
+    return Effect.fail(
+      new RedisConnectionError({
+        cause: new Error('Invalid URL'),
+        message: `Invalid Redis URL format: ${config.url}`,
+      }),
+    );
+  }
+
+  return Effect.void;
+};
+
+/**
+ * Validates Redis configuration
+ */
+export const validateRedisConfig = (
+  config: RedisConfig,
+): Effect.Effect<RedisConfig, RedisConnectionError> =>
+  Effect.gen(function* () {
+    if ('url' in config) {
+      yield* validateUrlConfig(config);
+    } else {
+      yield* validateHostConfig(config);
+    }
+    return config;
+  });
+
+/**
+ * Merges user configuration with defaults
+ */
+export const mergeWithDefaults = (
+  userConfig?: Partial<RedisConfig>,
+): RedisConfig => {
+  if (!userConfig) {
+    return DEFAULT_REDIS_CONFIG;
+  }
+
+  if ('url' in userConfig && userConfig.url) {
+    return {
+      url: userConfig.url,
+      connectTimeout:
+        userConfig.connectTimeout ?? DEFAULT_REDIS_CONFIG.connectTimeout,
+      commandTimeout:
+        userConfig.commandTimeout ?? DEFAULT_REDIS_CONFIG.commandTimeout,
+    };
+  }
+
+  // Type assertion to handle the union type properly
+  const hostConfig = userConfig as Partial<
+    Extract<RedisConfig, { host: string }>
+  >;
+
+  return {
+    host: hostConfig.host ?? DEFAULT_REDIS_CONFIG.host,
+    port: hostConfig.port ?? DEFAULT_REDIS_CONFIG.port,
+    username: hostConfig.username,
+    password: hostConfig.password,
+    database: hostConfig.database,
+    ssl: hostConfig.ssl,
+    connectTimeout:
+      hostConfig.connectTimeout ?? DEFAULT_REDIS_CONFIG.connectTimeout,
+    commandTimeout:
+      hostConfig.commandTimeout ?? DEFAULT_REDIS_CONFIG.commandTimeout,
+  };
+};
+
+/**
+ * Extracts connection info for logging (without sensitive data)
+ */
+export const getConnectionInfo = (config: RedisConfig): string => {
+  if ('url' in config) {
+    try {
+      const url = new URL(config.url);
+      return `${url.protocol}//${url.hostname}:${url.port}${url.pathname}`;
+    } catch {
+      return 'redis://[invalid-url]';
+    }
+  }
+
+  return `redis://${config.host}:${config.port}${config.database ? `/${config.database}` : ''}`;
+};

package/src/redis/connection.ts

@@ -0,0 +1,69 @@
+import { Context, Effect, type Scope } from 'effect';
+import { createClient } from 'redis';
+import type { RedisError } from '../types';
+import { RedisConnectionError } from '../types';
+
+// Shape interface for Redis connection configuration options
+// Uses Parameters to extract the constructor options type from createClient
+export interface RedisConnectionOptionsShape {
+  readonly options?: Parameters<typeof createClient>[0] | undefined;
+  readonly createClient?:
+    | ((
+        options?: Parameters<typeof createClient>[0],
+      ) => ReturnType<typeof createClient>)
+    | undefined;
+}
+
+// Context tag for dependency injection of Redis connection options
+// Allows configuration to be provided through Effect's dependency injection system
+export class RedisConnectionOptions extends Context.Tag(
+  'RedisConnectionOptions',
+)<RedisConnectionOptions, RedisConnectionOptionsShape>() {}
+
+export const redisClientEffect: Effect.Effect<
+  ReturnType<typeof createClient>,
+  RedisError,
+  Scope.Scope | RedisConnectionOptions
+> = Effect.gen(function* () {
+  // Retrieve Redis connection options from the context
+  const { options, createClient: createClientFromContext } =
+    yield* RedisConnectionOptions;
+  const create = createClientFromContext ?? createClient;
+
+  // Create a managed Redis client with automatic resource cleanup
+  return yield* Effect.acquireRelease(
+    Effect.gen(function* () {
+      yield* Effect.log('Connecting to Redis');
+      const client = yield* Effect.tryPromise({
+        try: () => create(options).connect(),
+        catch: (error) =>
+          new RedisConnectionError({
+            cause: error,
+            message: 'Error while connecting to Redis',
+          }),
+      });
+
+      // Set up error handling/monitoring for the Redis connection
+      client.on('error', (error) => {
+        Effect.runSync(
+          Effect.logError(`Redis connection error: ${error.message}`),
+        );
+        client.destroy();
+      });
+
+      client.on('end', () => {
+        Effect.runSync(Effect.logInfo('Redis connection ended'));
+      });
+
+      return client;
+    }),
+    // Cleanup function: properly close Redis connection when scope exits
+    (client) =>
+      Effect.gen(function* () {
+        yield* Effect.log('Cleaning up Redis connection');
+        yield* Effect.tryPromise(() => client.close()).pipe(
+          Effect.catchAll(() => Effect.void),
+        );
+      }),
+  );
+});

package/src/redis/constants.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Redis constants and configuration values
+ */
+
+/**
+ * Default timeout values (in milliseconds)
+ */
+export const TIMEOUTS = {
+  DEFAULT_CONNECT: 10000,
+  DEFAULT_COMMAND: 5000,
+  DEFAULT_STREAM_BLOCK: 5000,
+} as const;
+
+/**
+ * Default Redis connection values
+ */
+export const DEFAULTS = {
+  HOST: 'localhost',
+  PORT: 6379,
+  DATABASE: 0,
+  STREAM_ID: '$',
+} as const;
+
+/**
+ * Redis command names for error reporting
+ */
+export const COMMANDS = {
+  GET: 'GET',
+  SET: 'SET',
+  DEL: 'DEL',
+  EXISTS: 'EXISTS',
+  EXPIRE: 'EXPIRE',
+  TTL: 'TTL',
+  HSET: 'HSET',
+  HGET: 'HGET',
+  HGETALL: 'HGETALL',
+  HDEL: 'HDEL',
+  HEXISTS: 'HEXISTS',
+  LPUSH: 'LPUSH',
+  RPUSH: 'RPUSH',
+  LPOP: 'LPOP',
+  RPOP: 'RPOP',
+  LRANGE: 'LRANGE',
+  SADD: 'SADD',
+  SREM: 'SREM',
+  SMEMBERS: 'SMEMBERS',
+  ZADD: 'ZADD',
+  ZRANGE: 'ZRANGE',
+  ZREM: 'ZREM',
+  INCR: 'INCR',
+  DECR: 'DECR',
+  SCAN: 'SCAN',
+  PING: 'PING',
+  FLUSHDB: 'FLUSHDB',
+  FLUSHALL: 'FLUSHALL',
+  PUBLISH: 'PUBLISH',
+  SUBSCRIBE: 'SUBSCRIBE',
+  XADD: 'XADD',
+  XREAD: 'XREAD',
+  XRANGE: 'XRANGE',
+  XACK: 'XACK',
+} as const;
+
+/**
+ * Redis data type names
+ */
+export const DATA_TYPES = {
+  STRING: 'string',
+  LIST: 'list',
+  SET: 'set',
+  ZSET: 'zset',
+  HASH: 'hash',
+  STREAM: 'stream',
+} as const;
+
+/**
+ * Connection states
+ */
+export const CONNECTION_STATES = {
+  CONNECTING: 'connecting',
+  CONNECTED: 'connected',
+  DISCONNECTING: 'disconnecting',
+  DISCONNECTED: 'disconnected',
+  ERROR: 'error',
+} as const;
+
+/**
+ * Log messages
+ */
+export const LOG_MESSAGES = {
+  CONNECTING: 'Connecting to Redis...',
+  CONNECTED: 'Successfully connected to Redis',
+  CONNECTION_ENDED: 'Redis connection ended',
+  CLEANING_UP: 'Cleaning up Redis connection',
+  CONNECTION_ERROR: 'Redis connection error',
+} as const;