effect-redis 0.0.16 → 0.0.18

package/README.md

@@ -171,6 +171,46 @@ Gives access to the raw `RedisClient` from `redis`. The connection is shared and
 
 ---
 
+## CLI Tool - redistail
+
+The package includes a CLI tool called `redistail` for monitoring Redis pub/sub channels and streams.
+
+### Version Information
+
+To display the version and build information:
+
+```bash
+redistail -v
+# or
+redistail --version
+```
+
+Output format:
+```
+redistail 0.0.17
+Build: abc1234
+```
+
+The build version is the Git commit hash of the specific build. When not in a Git repository, it will show "Build: dev".
+
+### Usage
+
+```bash
+redistail <pubsub|stream> <topic-name>
+```
+
+Options:
+- `-h, --help`: Show help information
+- `-v, --version`: Show version and build information
+
+Examples:
+```bash
+redistail pubsub my-channel
+redistail stream my-stream
+```
+
+---
+
 ## Contributing / TODO
 
 *   Expose more common redis commands (get, del, etc.)

package/dist/cli/config-service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CLI Configuration Service for redistail utility.
+ *
+ * This module provides services for parsing command-line arguments,
+ * loading environment configuration, and displaying help/version information.
+ * Built using Effect-TS patterns with proper error handling and dependency injection.
+ */
+import { Context, Effect, Layer } from 'effect';
+import { CLIConfig, RedistailConfig } from './types.js';
+import type { CLIError, ConfigError } from './types.js';
+/**
+ * CLI Configuration Service interface
+ */
+export interface CLIConfigService {
+    readonly parseArgs: (args: string[]) => Effect.Effect<CLIConfig, CLIError>;
+    readonly loadConfig: () => Effect.Effect<RedistailConfig, ConfigError>;
+    readonly showHelp: () => Effect.Effect<void, never>;
+    readonly showVersion: () => Effect.Effect<void, never>;
+}
+/**
+ * Service tag for dependency injection
+ */
+export declare const CLIConfigService: Context.Tag<CLIConfigService, CLIConfigService>;
+/**
+ * Live layer for CLI Configuration Service
+ */
+export declare const CLIConfigServiceLive: Layer.Layer<CLIConfigService>;
+/**
+ * Parse arguments and load configuration in one operation
+ */
+export declare const parseArgsAndLoadConfig: (args: string[]) => Effect.Effect<{
+    cli: CLIConfig;
+    config: RedistailConfig;
+}, CLIError | ConfigError, CLIConfigService>;
+/**
+ * Handle help and version flags, returning true if handled
+ */
+export declare const handleHelpAndVersion: (cliConfig: CLIConfig) => Effect.Effect<boolean, never, CLIConfigService>;
+/**
+ * Validate CLI configuration for runtime use
+ */
+export declare const validateCLIConfig: (cliConfig: CLIConfig) => Effect.Effect<CLIConfig, CLIError>;
+/**
+ * Create a complete configuration for the redistail application
+ */
+export declare const createCompleteConfig: (args: string[]) => Effect.Effect<{
+    cli: CLIConfig;
+    config: RedistailConfig;
+    shouldExit: boolean;
+}, CLIError | ConfigError, CLIConfigService>;

package/dist/cli/display-service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Display service for formatting and outputting Redis messages.
+ *
+ * This service handles message formatting for both PubSub and Stream messages,
+ * including timestamp formatting, color support, JSON pretty-printing,
+ * safe handling of binary content, and proper output stream separation.
+ */
+import { Context, Effect, Layer } from 'effect';
+import type { PubSubMessage, StreamMessage, RedistailError } from './types.js';
+import { RedistailConfig } from './types.js';
+/**
+ * Service interface for message display and formatting
+ */
+export interface DisplayService {
+    readonly formatPubSubMessage: (message: PubSubMessage) => Effect.Effect<string, never>;
+    readonly formatStreamMessage: (message: StreamMessage) => Effect.Effect<string, never>;
+    readonly formatError: (error: RedistailError) => Effect.Effect<string, never>;
+    readonly outputMessage: (formatted: string) => Effect.Effect<void, never>;
+    readonly outputError: (error: string) => Effect.Effect<void, never>;
+}
+/**
+ * Service tag for dependency injection
+ */
+export declare const DisplayServiceTag: Context.Tag<DisplayService, DisplayService>;
+/**
+ * Create a DisplayService layer with the given configuration
+ */
+export declare const makeDisplayServiceLayer: (config: RedistailConfig) => Layer.Layer<DisplayService>;
+/**
+ * Live layer that provides DisplayService implementation
+ * This is a convenience layer that uses default configuration
+ */
+export declare const DisplayServiceLive: Layer.Layer<DisplayService>;
+/**
+ * Create a DisplayService for testing with custom configuration
+ */
+export declare const createTestDisplayService: (config: RedistailConfig) => DisplayService;
+/**
+ * Helper to strip ANSI color codes from formatted output for testing
+ */
+export declare const stripAnsiColors: (text: string) => string;
+/**
+ * Helper to check if text contains ANSI color codes
+ */
+export declare const hasAnsiColors: (text: string) => boolean;

package/dist/cli/layers.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Layer composition and dependency injection for the redistail CLI utility.
+ *
+ * This module provides all service layers and their composition for the redistail
+ * application. It follows Effect-TS patterns for dependency injection, resource
+ * management, and proper error handling. The layers are composed to create a
+ * complete application environment with all necessary services.
+ *
+ * Requirements addressed:
+ * - 7.1: Integration with effect-redis package services
+ * - 7.2: Effect-TS patterns for error handling and resource management
+ * - 7.3: Service composition through Effect Layers
+ * - 7.4: Proper error handling and resource management
+ */
+import { Context, Effect, Layer } from 'effect';
+import { Redis, RedisPubSub, RedisStream, RedisConnectionOptions, RedisConnectionOptionsLive } from '../redis.js';
+import { CLIConfigService } from './config-service.js';
+import { DisplayServiceTag, type DisplayService } from './display-service.js';
+import { PubSubMonitorService } from './pubsub-monitor-service.js';
+import { StreamMonitorService } from './stream-monitor-service.js';
+import { SignalHandlerService } from './signal-handler-service.js';
+import type { RedistailConfig, ConfigError, RedistailError } from './types.js';
+/**
+ * Context tag for RedistailConfig dependency injection
+ */
+declare const RedistailConfigTag: Context.Tag<RedistailConfig, RedistailConfig>;
+/**
+ * Live layer that provides RedistailConfig by loading from environment
+ * This layer depends on CLIConfigService to load the configuration
+ */
+export declare const RedistailConfigLive: Layer.Layer<RedistailConfig, ConfigError, CLIConfigService>;
+/**
+ * Live layer that provides Redis connection configuration based on RedistailConfig
+ * This layer creates the appropriate Redis connection options from the loaded configuration
+ *
+ * Requirement 7.1: Integrates with effect-redis RedisConnectionOptions
+ */
+export declare const RedisConnectionLive: Layer.Layer<RedisConnectionOptions, never, RedistailConfig>;
+/**
+ * Live layer that provides DisplayService with configuration
+ * This layer depends on RedistailConfig to configure display options
+ */
+export declare const DisplayServiceLive: Layer.Layer<DisplayService, never, RedistailConfig>;
+/**
+ * Create a Redis connection layer with custom options
+ *
+ * Requirement 7.1: Provides integration with effect-redis connection system
+ */
+export declare const createRedisConnectionLayer: (host: string, port: number, options?: {
+    url?: string;
+    timeout?: number;
+    retryAttempts?: number;
+    retryDelay?: number;
+}) => Layer.Layer<RedisConnectionOptions>;
+/**
+ * Create a layer with custom Redis connection options
+ */
+export declare const createRedisOptionsLayer: (options: Parameters<typeof RedisConnectionOptionsLive>[0]) => Layer.Layer<RedisConnectionOptions>;
+/**
+ * Create a test configuration layer
+ */
+export declare const createTestConfigLayer: (config: RedistailConfig) => Layer.Layer<RedistailConfig>;
+export declare const AppLive: Layer.Layer<RedisPubSub | RedisStream | RedistailConfig | CLIConfigService | DisplayService | PubSubMonitorService | StreamMonitorService | SignalHandlerService, import("../types.js").RedisError | ConfigError, never>;
+/**
+ * Layer for PubSub-only applications
+ * Provides only the services needed for PubSub monitoring
+ *
+ * Requirement 7.3: Service composition through Effect Layers
+ */
+export declare const PubSubAppLive: Layer.Layer<RedisPubSub | RedistailConfig | CLIConfigService | DisplayService | PubSubMonitorService | SignalHandlerService, import("../types.js").RedisError | ConfigError, never>;
+/**
+ * Layer for Stream-only applications
+ * Provides only the services needed for Stream monitoring
+ *
+ * Requirement 7.3: Service composition through Effect Layers
+ */
+export declare const StreamAppLive: Layer.Layer<RedisStream | RedistailConfig | CLIConfigService | DisplayService | StreamMonitorService | SignalHandlerService, import("../types.js").RedisError | ConfigError, never>;
+/**
+ * Create a test layer with custom configuration
+ * Useful for testing with specific Redis configurations
+ *
+ * Requirement 7.4: Proper resource management for testing
+ */
+export declare const createTestAppLayer: (config: RedistailConfig) => Layer.Layer<RedisConnectionOptions | Redis | RedisPubSub | RedisStream | RedistailConfig | CLIConfigService | DisplayService | PubSubMonitorService | StreamMonitorService | SignalHandlerService, import("../types.js").RedisError | ConfigError, RedisConnectionOptions | RedisPubSub | RedisStream | RedistailConfig | CLIConfigService>;
+/**
+ * Create a minimal test layer with mock Redis connection
+ * Useful for unit testing without actual Redis connection
+ *
+ * Requirement 7.4: Resource management for testing scenarios
+ */
+export declare const createMockAppLayer: (config: RedistailConfig) => Layer.Layer<RedistailConfig | CLIConfigService | DisplayService | SignalHandlerService, never, RedistailConfig>;
+/**
+ * Helper to handle layer initialization errors gracefully
+ * Provides proper error handling and resource management (Requirement 7.4)
+ */
+export declare const handleLayerError: <E>(error: E) => Effect.Effect<never, never>;
+/**
+ * Create a default RedistailConfig for testing and development
+ *
+ * Requirement 7.4: Proper configuration management
+ */
+export declare const createDefaultConfig: (overrides?: Partial<RedistailConfig>) => RedistailConfig;
+/**
+ * Validate that all required services are available in a layer
+ * This is a compile-time check to ensure layer completeness
+ *
+ * Requirement 7.3: Service composition validation
+ */
+export declare const validateAppLayer: () => void;
+export { CLIConfigService, DisplayServiceTag, PubSubMonitorService, StreamMonitorService, SignalHandlerService, Redis, RedisPubSub, RedisStream, };
+export type { RedistailConfig, RedistailError, ConfigError };
+export { RedistailConfigTag };
+/**
+ * Example usage of the layers:
+ *
+ * ```typescript
+ * import { AppLive, runWithAppLayer } from './layers.js';
+ * import { Effect } from 'effect';
+ *
+ * const myProgram = Effect.gen(function* () {
+ *   const cliService = yield* CLIConfigService;
+ *   const config = yield* cliService.loadConfig();
+ *   // ... use other services
+ * });
+ *
+ * // Run with complete application layer
+ * Effect.runPromise(Effect.provide(myProgram, AppLive));
+ * ```
+ *
+ * For testing:
+ *
+ * ```typescript
+ * import { createTestAppLayer, createDefaultConfig } from './layers.js';
+ *
+ * const testConfig = createDefaultConfig({
+ *   redis: { host: 'localhost', port: 6380 }
+ * });
+ *
+ * const testLayer = createTestAppLayer(testConfig);
+ * Effect.runPromise(Effect.provide(myProgram, testLayer));
+ * ```
+ */

package/dist/cli/pubsub-monitor-service.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PubSub monitoring service for the redistail CLI utility.
+ *
+ * This service provides Redis Pub/Sub channel monitoring capabilities with
+ * automatic reconnection, exponential backoff, and proper error handling.
+ * It integrates with the effect-redis RedisPubSub service and follows
+ * Effect-TS patterns for dependency injection and resource management.
+ */
+import { Context, Effect, Layer, Stream } from 'effect';
+import { RedisPubSub } from '../redis';
+import { type PubSubMessage, type MonitoringError, type ConfigError } from './types';
+import { CLIConfigService } from './config-service';
+type RedisPubSubService = Context.Tag.Service<RedisPubSub>;
+/**
+ * Service interface for PubSub monitoring operations
+ */
+export interface PubSubMonitorService {
+    /**
+     * Monitor a Redis Pub/Sub channel with automatic reconnection
+     * @param channel - The channel name to monitor
+     * @returns Stream of PubSub messages with error handling and reconnection
+     */
+    readonly monitor: (channel: string) => Stream.Stream<PubSubMessage, MonitoringError>;
+    /**
+     * Subscribe to a Redis Pub/Sub channel
+     * @param channel - The channel name to subscribe to
+     * @returns Effect that yields a stream of PubSub messages
+     */
+    readonly subscribe: (channel: string) => Effect.Effect<Stream.Stream<PubSubMessage, MonitoringError>, MonitoringError>;
+}
+/**
+ * Context tag for PubSub monitoring service dependency injection
+ */
+export declare const PubSubMonitorService: Context.Tag<PubSubMonitorService, PubSubMonitorService>;
+/**
+ * Live layer for PubSub monitoring service
+ * Depends on RedisPubSub and CLIConfigService services
+ */
+export declare const PubSubMonitorServiceLive: Layer.Layer<PubSubMonitorService, ConfigError, RedisPubSub | CLIConfigService>;
+/**
+ * Helper function to create a monitoring stream with custom retry configuration
+ */
+export declare const createMonitoringStreamWithRetry: (channel: string, redisPubSubService: RedisPubSubService, maxRetries: number, baseDelaySeconds?: number) => Stream.Stream<PubSubMessage, MonitoringError>;
+/**
+ * Helper function to validate channel names
+ */
+export declare const validateChannelName: (channel: string) => Effect.Effect<string, MonitoringError>;
+/**
+ * Helper function to create a monitored channel with validation
+ */
+export declare const monitorChannelWithValidation: (channel: string, pubSubService: PubSubMonitorService) => Stream.Stream<PubSubMessage, MonitoringError>;
+export {};

package/dist/cli/redistail-launcher.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * Cross-platform launcher for redistail CLI
+ * Detects platform and runs the appropriate binary
+ */
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function launchRedistail() {
+  const args = process.argv.slice(2);
+
+  // Try to use the compiled executable first (better performance)
+  const exePath = join(__dirname, 'redistail.exe');
+  const jsPath = join(__dirname, 'redistail.js');
+
+  let command;
+  let commandArgs;
+
+  if (process.platform === 'win32' && existsSync(exePath)) {
+    // Use the compiled executable on Windows
+    command = exePath;
+    commandArgs = args;
+  } else if (existsSync(jsPath)) {
+    // Fall back to Node.js execution
+    command = 'node';
+    commandArgs = [jsPath, ...args];
+  } else {
+    console.error('Error: redistail binary not found');
+    process.exit(1);
+  }
+
+  // Spawn the process and pipe stdio
+  const child = spawn(command, commandArgs, {
+    stdio: 'inherit',
+    windowsHide: false,
+  });
+
+  // Handle process exit
+  child.on('close', (code) => {
+    process.exit(code || 0);
+  });
+
+  child.on('error', (error) => {
+    console.error('Error launching redistail:', error.message);
+    process.exit(1);
+  });
+
+  // Handle process signals
+  process.on('SIGINT', () => {
+    child.kill('SIGINT');
+  });
+
+  process.on('SIGTERM', () => {
+    child.kill('SIGTERM');
+  });
+}
+
+launchRedistail();

package/dist/cli/redistail.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Main CLI program for redistail - Redis message monitoring utility.
+ *
+ * This module implements the main program effect that combines all services
+ * to create a complete Redis monitoring application. It handles CLI argument
+ * parsing, service initialization, signal handling, and message streaming.
+ *
+ * Requirements addressed:
+ * - 1.5: Help and version flag support
+ * - 2.5: Graceful shutdown for PubSub monitoring (Ctrl+C handling)
+ * - 3.5: Graceful shutdown for Stream monitoring (Ctrl+C handling)
+ * - 6.3: Topic validation and error handling
+ * - 6.4: Redis error recovery and continued monitoring
+ */
+import { Effect } from 'effect';
+import { CLIConfigService } from './config-service.js';
+import { type DisplayService } from './display-service.js';
+import { PubSubMonitorService } from './pubsub-monitor-service.js';
+import { SignalHandlerService } from './signal-handler-service.js';
+import { StreamMonitorService } from './stream-monitor-service.js';
+import type { RedistailError } from './types.js';
+/**
+ * Main redistail program effect that combines all services
+ *
+ * This effect:
+ * 1. Parses CLI arguments and loads configuration
+ * 2. Handles help and version flags
+ * 3. Sets up signal handlers for graceful shutdown
+ * 4. Starts appropriate monitoring based on connection type
+ * 5. Streams and displays messages until interrupted
+ *
+ * Requirements 1.5, 2.5, 3.5, 6.3, 6.4
+ */
+export declare const redistailProgram: (args: string[]) => Effect.Effect<void, RedistailError, CLIConfigService | SignalHandlerService | DisplayService | PubSubMonitorService | StreamMonitorService>;
+/**
+ * CLI main function with comprehensive error handling and optimized layer selection
+ *
+ * This function provides the main entry point for the CLI binary with
+ * proper error handling, logging, and process management. It optimizes
+ * Redis connections by only loading the services needed for the specific mode:
+ *
+ * - PubSub mode: Only creates 2 Redis connections (publish + subscribe)
+ * - Stream mode: Only creates 2 Redis connections (producer + consumer)
+ * - Help/version: Uses minimal layer without Redis connections
+ * - Invalid args: Shows error without creating any connections
+ *
+ * This reduces Redis connections from 5 to just 2 per run, or 0 for help/errors.
+ */
+export declare const cliMain: (args: string[]) => Effect.Effect<void, never, never>;
+/**
+ * Re-export commonly used types and services for convenience
+ */
+export { AppLive, CLIConfigService, DisplayServiceTag, PubSubAppLive, PubSubMonitorService, SignalHandlerService, StreamAppLive, StreamMonitorService, } from './layers.js';
+export type { CLIConfig, RedistailConfig, RedistailError } from './types.js';