alepha 0.14.0 → 0.14.1

package/src/redis/providers/NodeRedisProvider.ts

@@ -0,0 +1,280 @@
+import {
+  createClient,
+  RESP_TYPES,
+  type RedisClientType,
+  type SetOptions,
+} from "@redis/client";
+import { $env, $hook, $inject, Alepha, type Static, t } from "alepha";
+import { $logger } from "alepha/logger";
+import { RedisProvider, type RedisSetOptions } from "./RedisProvider.ts";
+
+const envSchema = t.object({
+  REDIS_URL: t.optional(t.text()),
+  REDIS_PORT: t.integer({
+    default: "6379",
+  }),
+  REDIS_HOST: t.text({
+    default: "localhost",
+  }),
+  REDIS_PASSWORD: t.optional(t.text()),
+});
+
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+}
+
+export type NodeRedisClient = RedisClientType<
+  {},
+  {},
+  {},
+  3,
+  { 36: BufferConstructor }
+>;
+export type NodeRedisClientOptions = Parameters<typeof createClient>[0];
+
+/**
+ * Node.js Redis client provider using `@redis/client`.
+ *
+ * This provider uses the official Redis client for Node.js runtime.
+ *
+ * @example
+ * ```ts
+ * // Set REDIS_URL environment variable
+ * // REDIS_URL=redis://localhost:6379
+ *
+ * // Or configure via REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
+ *
+ * // Or configure programmatically
+ * alepha.with({
+ *   provide: RedisProvider,
+ *   use: NodeRedisProvider,
+ * });
+ * ```
+ */
+export class NodeRedisProvider extends RedisProvider {
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+  protected readonly env = $env(envSchema);
+  protected readonly client = this.createClient();
+
+  public get publisher(): NodeRedisClient {
+    if (!this.client.isReady) {
+      throw new Error("Redis client is not ready");
+    }
+
+    return this.client;
+  }
+
+  public override get isReady(): boolean {
+    return this.client.isReady;
+  }
+
+  protected readonly start = $hook({
+    on: "start",
+    handler: () => this.connect(),
+  });
+
+  protected readonly stop = $hook({
+    on: "stop",
+    handler: () => this.close(),
+  });
+
+  /**
+   * Connect to the Redis server.
+   */
+  public override async connect(): Promise<void> {
+    this.log.debug("Connecting...");
+    await this.client.connect();
+    this.log.info("Connection OK");
+  }
+
+  /**
+   * Close the connection to the Redis server.
+   */
+  public override async close(): Promise<void> {
+    this.log.debug("Closing connection...");
+    await this.client.close();
+    this.log.info("Connection closed");
+  }
+
+  public duplicate(options?: Partial<NodeRedisClientOptions>): NodeRedisClient {
+    return this.client
+      .duplicate({
+        ...options,
+        RESP: 3,
+      })
+      .withTypeMapping({
+        [RESP_TYPES.BLOB_STRING]: Buffer,
+      });
+  }
+
+  public override async get(key: string): Promise<Buffer | undefined> {
+    this.log.trace(`Getting key ${key}`);
+    const resp = await this.publisher.get(key);
+
+    if (resp === null) {
+      return undefined;
+    }
+
+    return Buffer.from(resp);
+  }
+
+  public override async set(
+    key: string,
+    value: Buffer | string,
+    options?: RedisSetOptions,
+  ): Promise<Buffer> {
+    const buf = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf-8");
+
+    // Convert RedisSetOptions to @redis/client SetOptions
+    const setOptions: SetOptions = {};
+
+    // Handle expiration object format (from alepha/cache-redis, alepha/lock-redis)
+    if (options?.expiration) {
+      if (options.expiration.type === "KEEPTTL") {
+        setOptions.KEEPTTL = true;
+      } else {
+        setOptions[options.expiration.type] = options.expiration.value;
+      }
+    }
+
+    // Handle direct expiration properties
+    if (options?.EX !== undefined) {
+      setOptions.EX = options.EX;
+    }
+    if (options?.PX !== undefined) {
+      setOptions.PX = options.PX;
+    }
+    if (options?.EXAT !== undefined) {
+      setOptions.EXAT = options.EXAT;
+    }
+    if (options?.PXAT !== undefined) {
+      setOptions.PXAT = options.PXAT;
+    }
+    if (options?.KEEPTTL) {
+      setOptions.KEEPTTL = true;
+    }
+
+    // Handle condition object format
+    if (options?.condition === "NX") {
+      setOptions.NX = true;
+    } else if (options?.condition === "XX") {
+      setOptions.XX = true;
+    }
+
+    // Handle direct condition properties
+    if (options?.NX) {
+      setOptions.NX = true;
+    }
+    if (options?.XX) {
+      setOptions.XX = true;
+    }
+    if (options?.GET) {
+      setOptions.GET = true;
+    }
+
+    const resp = await this.publisher.set(
+      key,
+      buf,
+      Object.keys(setOptions).length > 0 ? setOptions : undefined,
+    );
+
+    if (resp === "OK" || !resp) {
+      return buf;
+    }
+
+    return Buffer.from(resp);
+  }
+
+  public override async has(key: string): Promise<boolean> {
+    const resp = await this.publisher.exists(key);
+    return resp > 0;
+  }
+
+  public override async keys(pattern: string): Promise<string[]> {
+    const keys = await this.publisher.keys(pattern);
+    return keys.map((key) => key.toString());
+  }
+
+  public override async del(keys: string[]): Promise<void> {
+    if (keys.length === 0) {
+      return;
+    }
+
+    await this.publisher.del(keys);
+  }
+
+  // ---------------------------------------------------------
+  // Queue operations
+  // ---------------------------------------------------------
+
+  public override async lpush(key: string, value: string): Promise<void> {
+    await this.publisher.LPUSH(key, value);
+  }
+
+  public override async rpop(key: string): Promise<string | undefined> {
+    const value = await this.publisher.RPOP(key);
+    if (value == null) {
+      return undefined;
+    }
+    return String(value);
+  }
+
+  // ---------------------------------------------------------
+  // Pub/Sub operations
+  // ---------------------------------------------------------
+
+  public override async publish(
+    channel: string,
+    message: string,
+  ): Promise<void> {
+    await this.publisher.publish(channel, message);
+  }
+
+  /**
+   * Get the Redis connection URL.
+   */
+  protected getUrl(): string {
+    // Prefer REDIS_URL if set
+    if (this.env.REDIS_URL) {
+      return this.env.REDIS_URL;
+    }
+
+    // Build URL from components
+    const url = new URL("redis://127.0.0.1:6379");
+
+    if (this.env.REDIS_PASSWORD) {
+      url.password = this.env.REDIS_PASSWORD;
+    }
+
+    if (this.env.REDIS_HOST) {
+      url.hostname = this.env.REDIS_HOST;
+    }
+
+    if (this.env.REDIS_PORT) {
+      url.port = String(this.env.REDIS_PORT);
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Redis client factory method.
+   */
+  protected createClient(): NodeRedisClient {
+    const client = createClient({
+      url: this.getUrl(),
+      RESP: 3,
+    }).withTypeMapping({
+      [RESP_TYPES.BLOB_STRING]: Buffer,
+    });
+
+    client.on("error", (error) => {
+      if (this.alepha.isStarted()) {
+        this.log.error(error);
+      }
+    });
+
+    return client;
+  }
+}

package/src/redis/providers/NodeRedisSubscriberProvider.ts

@@ -0,0 +1,94 @@
+import { $hook, $inject, Alepha } from "alepha";
+import { $logger } from "alepha/logger";
+import {
+  type NodeRedisClient,
+  NodeRedisProvider,
+} from "./NodeRedisProvider.ts";
+import {
+  RedisSubscriberProvider,
+  type SubscribeCallback,
+} from "./RedisSubscriberProvider.ts";
+
+/**
+ * Node.js Redis subscriber provider using `@redis/client`.
+ *
+ * This provider creates a dedicated Redis connection for subscriptions,
+ * as Redis requires separate connections for pub/sub operations.
+ *
+ * @example
+ * ```ts
+ * const subscriber = alepha.inject(RedisSubscriberProvider);
+ * await subscriber.subscribe("channel", (message, channel) => {
+ *   console.log(`Received: ${message} on ${channel}`);
+ * });
+ * ```
+ */
+export class NodeRedisSubscriberProvider extends RedisSubscriberProvider {
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+  protected readonly redisProvider = $inject(NodeRedisProvider);
+  protected readonly client: NodeRedisClient = this.createClient();
+
+  public get subscriber(): NodeRedisClient {
+    if (!this.client.isReady) {
+      throw new Error("Redis subscriber client is not ready");
+    }
+
+    return this.client;
+  }
+
+  public override get isReady(): boolean {
+    return this.client.isReady;
+  }
+
+  protected readonly start = $hook({
+    on: "start",
+    handler: () => this.connect(),
+  });
+
+  protected readonly stop = $hook({
+    on: "stop",
+    handler: () => this.close(),
+  });
+
+  public override async connect(): Promise<void> {
+    this.log.debug("Connecting subscriber...");
+    await this.client.connect();
+    this.log.info("Subscriber connection OK");
+  }
+
+  public override async close(): Promise<void> {
+    this.log.debug("Closing subscriber connection...");
+    await this.subscriber.close();
+    this.log.info("Subscriber connection closed");
+  }
+
+  public override async subscribe(
+    channel: string,
+    callback: SubscribeCallback,
+  ): Promise<void> {
+    await this.subscriber.subscribe(channel, callback);
+  }
+
+  public override async unsubscribe(
+    channel: string,
+    callback?: SubscribeCallback,
+  ): Promise<void> {
+    await this.subscriber.unsubscribe(channel, callback);
+  }
+
+  /**
+   * Redis subscriber client factory method.
+   */
+  protected createClient(): NodeRedisClient {
+    const client = this.redisProvider.duplicate();
+
+    client.on("error", (error) => {
+      if (this.alepha.isStarted()) {
+        this.log.error(error);
+      }
+    });
+
+    return client;
+  }
+}

package/src/redis/providers/RedisProvider.ts

@@ -1,167 +1,161 @@
-import {
-  createClient,
-  RESP_TYPES,
-  type RedisClientType,
-  type SetOptions,
-} from "@redis/client";
-import { $env, $hook, $inject, Alepha, type Static, t } from "alepha";
-import { $logger } from "alepha/logger";
-
-const envSchema = t.object({
-  REDIS_PORT: t.integer({
-    default: "6379",
-  }),
-  REDIS_HOST: t.text({
-    default: "localhost",
-  }),
-  REDIS_PASSWORD: t.optional(t.text()),
-});
-
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-}
-
-export type RedisClient = RedisClientType<
-  {},
-  {},
-  {},
-  3,
-  { 36: BufferConstructor }
->;
-export type RedisClientOptions = Parameters<typeof createClient>[0];
-export type RedisSetOptions = SetOptions;
-
 /**
- * Redis client provider.
+ * Abstract Redis provider interface.
+ *
+ * This abstract class defines the common interface for Redis operations.
+ * Implementations include:
+ * - {@link NodeRedisProvider} - Uses `@redis/client` for Node.js runtime
+ * - {@link BunRedisProvider} - Uses Bun's native `RedisClient` for Bun runtime
+ *
+ * @example
+ * ```ts
+ * // Inject the abstract provider - runtime selects the implementation
+ * const redis = alepha.inject(RedisProvider);
+ *
+ * // Use common operations
+ * await redis.set("key", "value");
+ * const value = await redis.get("key");
+ * ```
  */
-export class RedisProvider {
-  protected readonly log = $logger();
-  protected readonly alepha = $inject(Alepha);
-  protected readonly env = $env(envSchema);
-  protected readonly client = this.createClient();
-
-  public get publisher(): RedisClient {
-    if (!this.client.isReady) {
-      throw new Error("Redis client is not ready");
-    }
-
-    return this.client;
-  }
-
-  protected readonly start = $hook({
-    on: "start",
-    handler: () => this.connect(),
-  });
-
-  protected readonly stop = $hook({
-    on: "stop",
-    handler: () => this.close(),
-  });
+export abstract class RedisProvider {
+  /**
+   * Whether the Redis client is ready to accept commands.
+   */
+  public abstract readonly isReady: boolean;
 
   /**
    * Connect to the Redis server.
    */
-  public async connect(): Promise<void> {
-    this.log.debug("Connecting...");
-    await this.client.connect();
-    this.log.info("Connection OK");
-  }
+  public abstract connect(): Promise<void>;
 
   /**
    * Close the connection to the Redis server.
    */
-  public async close(): Promise<void> {
-    this.log.debug("Closing connection...");
-    await this.client.close();
-    this.log.info("Connection closed");
-  }
-
-  public duplicate(options?: Partial<RedisClientOptions>): RedisClient {
-    return this.client
-      .duplicate({
-        ...options,
-        RESP: 3,
-      })
-      .withTypeMapping({
-        [RESP_TYPES.BLOB_STRING]: Buffer,
-      });
-  }
-
-  public async get(key: string): Promise<Buffer | undefined> {
-    this.log.trace(`Getting key ${key}`);
-    const resp = await this.publisher.get(key);
-
-    if (resp === null) {
-      return undefined;
-    }
+  public abstract close(): Promise<void>;
 
-    return Buffer.from(resp);
-  }
+  /**
+   * Get the value of a key.
+   *
+   * @param key The key to get.
+   * @returns The value as a Buffer, or undefined if the key does not exist.
+   */
+  public abstract get(key: string): Promise<Buffer | undefined>;
 
-  public async set(
+  /**
+   * Set the value of a key.
+   *
+   * @param key The key to set.
+   * @param value The value to set (Buffer or string).
+   * @param options Optional set options (EX, PX, NX, XX, etc.).
+   * @returns The value as a Buffer.
+   */
+  public abstract set(
     key: string,
     value: Buffer | string,
     options?: RedisSetOptions,
-  ): Promise<Buffer> {
-    const buf = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf-8");
-    const resp = await this.publisher.set(key, buf, options);
-
-    if (resp === "OK" || !resp) {
-      return buf;
-    }
-
-    return Buffer.from(resp);
-  }
-
-  public async has(key: string): Promise<boolean> {
-    const resp = await this.publisher.exists(key);
-    return resp > 0;
-  }
+  ): Promise<Buffer>;
 
-  public async keys(pattern: string): Promise<string[]> {
-    const keys = await this.publisher.keys(pattern);
-    return keys.map((key) => key.toString());
-  }
-
-  public async del(keys: string[]): Promise<void> {
-    if (keys.length === 0) {
-      return;
-    }
+  /**
+   * Check if a key exists.
+   *
+   * @param key The key to check.
+   * @returns True if the key exists.
+   */
+  public abstract has(key: string): Promise<boolean>;
 
-    await this.publisher.del(keys);
-  }
+  /**
+   * Get all keys matching a pattern.
+   *
+   * @param pattern The glob-style pattern to match.
+   * @returns Array of matching key names.
+   */
+  public abstract keys(pattern: string): Promise<string[]>;
 
   /**
-   * Redis subscriber client factory method.
+   * Delete one or more keys.
+   *
+   * @param keys The keys to delete.
    */
-  protected createClient(): RedisClient {
-    const url = new URL("redis://127.0.0.1:6379");
+  public abstract del(keys: string[]): Promise<void>;
 
-    if (this.env.REDIS_PASSWORD) {
-      url.password = this.env.REDIS_PASSWORD;
-    }
+  // ---------------------------------------------------------
+  // Queue operations (for alepha/queue-redis)
+  // ---------------------------------------------------------
 
-    if (this.env.REDIS_HOST) {
-      url.hostname = this.env.REDIS_HOST;
-    }
+  /**
+   * Push a value to the left (head) of a list.
+   *
+   * @param key The list key.
+   * @param value The value to push.
+   */
+  public abstract lpush(key: string, value: string): Promise<void>;
 
-    if (this.env.REDIS_PORT) {
-      url.port = String(this.env.REDIS_PORT);
-    }
+  /**
+   * Pop a value from the right (tail) of a list.
+   *
+   * @param key The list key.
+   * @returns The value, or undefined if the list is empty.
+   */
+  public abstract rpop(key: string): Promise<string | undefined>;
 
-    const client = createClient({
-      url: url.toString(),
-      RESP: 3,
-    }).withTypeMapping({
-      [RESP_TYPES.BLOB_STRING]: Buffer,
-    });
+  // ---------------------------------------------------------
+  // Pub/Sub operations (for alepha/topic-redis)
+  // ---------------------------------------------------------
 
-    client.on("error", (error) => {
-      if (this.alepha.isStarted()) {
-        this.log.error(error);
-      }
-    });
+  /**
+   * Publish a message to a channel.
+   *
+   * @param channel The channel name.
+   * @param message The message to publish.
+   */
+  public abstract publish(channel: string, message: string): Promise<void>;
+}
 
-    return client;
-  }
+/**
+ * Common Redis SET command options.
+ * Compatible with @redis/client SetOptions format.
+ */
+export interface RedisSetOptions {
+  /**
+   * Set the specified expire time, in seconds.
+   */
+  EX?: number;
+  /**
+   * Set the specified expire time, in milliseconds.
+   */
+  PX?: number;
+  /**
+   * Set the specified Unix time at which the key will expire, in seconds.
+   */
+  EXAT?: number;
+  /**
+   * Set the specified Unix time at which the key will expire, in milliseconds.
+   */
+  PXAT?: number;
+  /**
+   * Only set the key if it does not already exist.
+   */
+  NX?: boolean;
+  /**
+   * Only set the key if it already exists.
+   */
+  XX?: boolean;
+  /**
+   * Retain the time to live associated with the key.
+   */
+  KEEPTTL?: boolean;
+  /**
+   * Return the old string stored at key, or nil if key did not exist.
+   */
+  GET?: boolean;
+  /**
+   * Alternative expiration format (compatible with @redis/client).
+   */
+  expiration?: {
+    type: "EX" | "PX" | "EXAT" | "PXAT" | "KEEPTTL";
+    value: number;
+  };
+  /**
+   * Alternative condition format (compatible with @redis/client).
+   */
+  condition?: "NX" | "XX";
 }