@tekir/redis 0.1.0

package/src/redis.ts

@@ -0,0 +1,349 @@
+import type { RedisConnectionConfig } from './types'
+
+/**
+ * Redis client wrapper around Bun's native RedisClient.
+ *
+ * Provides a high-level API for string, hash, set, and pub/sub operations,
+ * plus JSON helpers and a cache-aside `remember` method.
+ *
+ * @example
+ * ```ts
+ * const redis = new Redis({ url: 'redis://localhost:6379', prefix: 'app:' })
+ * await redis.set('greeting', 'hello')
+ * const val = await redis.get('greeting') // 'hello'
+ * ```
+ */
+export class Redis {
+  private client: any
+  private prefix: string
+  private config: RedisConnectionConfig
+
+  /**
+   * @param config - Redis connection configuration.
+   */
+  constructor(config: RedisConnectionConfig = {}) {
+    this.config = config
+    this.prefix = config.prefix || ''
+
+    const { RedisClient } = Bun as any
+    const url = config.url || process.env.REDIS_URL || 'redis://localhost:6379'
+
+    this.client = new RedisClient(url, {
+      connectionTimeout: config.connectionTimeout,
+      idleTimeout: config.idleTimeout,
+      autoReconnect: config.autoReconnect ?? true,
+      maxRetries: config.maxRetries ?? 10,
+      enableAutoPipelining: config.enableAutoPipelining ?? true,
+      tls: config.tls,
+    })
+  }
+
+  private key(k: string): string {
+    return this.prefix ? `${this.prefix}:${k}` : k
+  }
+
+  // ─── Connection ────────────────────────────────────────
+
+  /**
+   * Open the connection to the Redis server.
+   *
+   * @returns A promise that resolves once the connection is established.
+   *
+   * @example
+   * ```ts
+   * await redis.connect()
+   * ```
+   */
+  async connect(): Promise<void> { await this.client.connect() }
+
+  /**
+   * Close the connection to the Redis server.
+   */
+  close(): void { this.client.close() }
+
+  /**
+   * Whether the client is currently connected to Redis.
+   *
+   * @returns `true` if the connection is active.
+   */
+  get connected(): boolean { return this.client.connected }
+
+  // ─── String operations ────────────────────────────────
+
+  /**
+   * Get the value of a key.
+   *
+   * @param key - The key to retrieve.
+   * @returns The string value, or `null` if the key does not exist.
+   *
+   * @example
+   * ```ts
+   * const val = await redis.get('name') // 'Alice' | null
+   * ```
+   */
+  async get(key: string): Promise<string | null> { return this.client.get(this.key(key)) }
+
+  /**
+   * Set the value of a key.
+   *
+   * @param key - The key to set.
+   * @param value - The string or numeric value to store.
+   *
+   * @example
+   * ```ts
+   * await redis.set('counter', 42)
+   * ```
+   */
+  async set(key: string, value: string | number): Promise<void> { await this.client.set(this.key(key), String(value)) }
+
+  /**
+   * Delete one or more keys.
+   *
+   * @param keys - The keys to delete.
+   *
+   * @example
+   * ```ts
+   * await redis.del('key1', 'key2')
+   * ```
+   */
+  async del(...keys: string[]): Promise<void> { await this.client.del(...keys.map(k => this.key(k))) }
+
+  /**
+   * Check whether a key exists.
+   *
+   * @param key - The key to check.
+   * @returns `true` if the key exists.
+   */
+  async exists(key: string): Promise<boolean> { return this.client.exists(this.key(key)) }
+
+  /**
+   * Increment the integer value of a key by one.
+   *
+   * @param key - The key to increment.
+   * @returns The new value after incrementing.
+   */
+  async incr(key: string): Promise<number> { return this.client.incr(this.key(key)) }
+
+  /**
+   * Decrement the integer value of a key by one.
+   *
+   * @param key - The key to decrement.
+   * @returns The new value after decrementing.
+   */
+  async decr(key: string): Promise<number> { return this.client.decr(this.key(key)) }
+
+  /**
+   * Set a timeout on a key (in seconds).
+   *
+   * @param key - The key to set the expiry on.
+   * @param seconds - Time-to-live in seconds.
+   */
+  async expire(key: string, seconds: number): Promise<void> { await this.client.expire(this.key(key), seconds) }
+
+  /**
+   * Get the remaining time-to-live of a key in seconds.
+   *
+   * @param key - The key to query.
+   * @returns Remaining TTL in seconds, `-1` if no expiry is set, `-2` if the key does not exist.
+   */
+  async ttl(key: string): Promise<number> { return this.client.ttl(this.key(key)) }
+
+  // ─── Hash operations ──────────────────────────────────
+
+  /**
+   * Get the value of a single field in a hash.
+   *
+   * @param key - The hash key.
+   * @param field - The field name within the hash.
+   * @returns The field value, or `null` if the field or key does not exist.
+   */
+  async hget(key: string, field: string): Promise<string | null> { return this.client.hget(this.key(key), field) }
+
+  /**
+   * Set multiple field-value pairs in a hash.
+   *
+   * @param key - The hash key.
+   * @param fields - An array of alternating field names and values (e.g. `['f1', 'v1', 'f2', 'v2']`).
+   */
+  async hmset(key: string, fields: string[]): Promise<void> { await this.client.hmset(this.key(key), fields) }
+
+  /**
+   * Get the values of multiple fields in a hash.
+   *
+   * @param key - The hash key.
+   * @param fields - An array of field names to retrieve.
+   * @returns An array of values corresponding to the requested fields (`null` for missing fields).
+   */
+  async hmget(key: string, fields: string[]): Promise<(string | null)[]> { return this.client.hmget(this.key(key), fields) }
+
+  /**
+   * Increment a numeric field in a hash by a given amount.
+   *
+   * @param key - The hash key.
+   * @param field - The field name to increment.
+   * @param increment - The integer amount to add.
+   * @returns The new value of the field after incrementing.
+   */
+  async hincrby(key: string, field: string, increment: number): Promise<number> { return this.client.hincrby(this.key(key), field, increment) }
+
+  // ─── Set operations ───────────────────────────────────
+
+  /**
+   * Add one or more members to a set.
+   *
+   * @param key - The set key.
+   * @param members - The members to add.
+   * @returns The number of members that were added (excluding already-present members).
+   */
+  async sadd(key: string, ...members: string[]): Promise<number> { return this.client.sadd(this.key(key), ...members) }
+
+  /**
+   * Remove one or more members from a set.
+   *
+   * @param key - The set key.
+   * @param members - The members to remove.
+   * @returns The number of members that were removed.
+   */
+  async srem(key: string, ...members: string[]): Promise<number> { return this.client.srem(this.key(key), ...members) }
+
+  /**
+   * Check whether a value is a member of a set.
+   *
+   * @param key - The set key.
+   * @param member - The value to check for.
+   * @returns `true` if the member exists in the set.
+   */
+  async sismember(key: string, member: string): Promise<boolean> { return this.client.sismember(this.key(key), member) }
+
+  /**
+   * Get all members of a set.
+   *
+   * @param key - The set key.
+   * @returns An array of all members in the set.
+   */
+  async smembers(key: string): Promise<string[]> { return this.client.smembers(this.key(key)) }
+
+  // ─── Pub/Sub ──────────────────────────────────────────
+
+  /**
+   * Publish a message to a channel.
+   *
+   * @param channel - The channel name.
+   * @param message - The message string to publish.
+   */
+  async publish(channel: string, message: string): Promise<void> { await this.client.publish(channel, message) }
+
+  /**
+   * Subscribe to a channel and receive messages via a callback.
+   *
+   * @param channel - The channel name to subscribe to.
+   * @param callback - Invoked for each message received on the channel.
+   *
+   * @example
+   * ```ts
+   * await redis.subscribe('events', (msg, ch) => {
+   *   console.log(`Received on ${ch}: ${msg}`)
+   * })
+   * ```
+   */
+  async subscribe(channel: string, callback: (message: string, channel: string) => void): Promise<void> {
+    await this.client.subscribe(channel, callback)
+  }
+
+  /**
+   * Unsubscribe from a channel, or from all channels if none is specified.
+   *
+   * @param channel - The channel to unsubscribe from. Omit to unsubscribe from all.
+   */
+  async unsubscribe(channel?: string): Promise<void> { await this.client.unsubscribe(channel) }
+
+  // ─── Raw command ──────────────────────────────────────
+
+  /**
+   * Send a raw Redis command.
+   *
+   * @param command - The Redis command string (e.g. `'PING'`, `'INFO'`).
+   * @param args - Arguments for the command.
+   * @returns The raw response from Redis.
+   *
+   * @example
+   * ```ts
+   * const pong = await redis.send('PING') // 'PONG'
+   * ```
+   */
+  async send(command: string, args: string[] = []): Promise<any> { return this.client.send(command, args) }
+
+  // ─── JSON helpers ─────────────────────────────────────
+
+  /**
+   * Get a value from Redis and parse it as JSON.
+   *
+   * @param key - The key to retrieve.
+   * @returns The parsed object, or `null` if the key does not exist or parsing fails.
+   *
+   * @example
+   * ```ts
+   * const user = await redis.getJSON<{ name: string }>('user:1')
+   * ```
+   */
+  async getJSON<T = any>(key: string): Promise<T | null> {
+    const val = await this.get(key)
+    if (val === null) return null
+    try { return JSON.parse(val) } catch { return null }
+  }
+
+  /**
+   * Serialize a value as JSON and store it in Redis, with an optional TTL.
+   *
+   * @param key - The key to store the value under.
+   * @param value - The value to JSON-serialize and store.
+   * @param expireSeconds - Optional time-to-live in seconds.
+   *
+   * @example
+   * ```ts
+   * await redis.setJSON('user:1', { name: 'Alice' }, 3600)
+   * ```
+   */
+  async setJSON(key: string, value: any, expireSeconds?: number): Promise<void> {
+    await this.set(key, JSON.stringify(value))
+    if (expireSeconds) await this.expire(key, expireSeconds)
+  }
+
+  /**
+   * Cache-aside helper: return the cached value if it exists, otherwise execute
+   * the callback, store the result in Redis with a TTL, and return it.
+   *
+   * @param key - The cache key.
+   * @param seconds - Time-to-live in seconds for the cached value.
+   * @param callback - Async function invoked to compute the value on a cache miss.
+   * @returns The cached or freshly computed value.
+   *
+   * @example
+   * ```ts
+   * const users = await redis.remember('all-users', 60, async () => {
+   *   return db.query('SELECT * FROM users')
+   * })
+   * ```
+   */
+  async remember<T>(key: string, seconds: number, callback: () => Promise<T>): Promise<T> {
+    const cached = await this.getJSON<T>(key)
+    if (cached !== null) return cached
+    const value = await callback()
+    await this.setJSON(key, value, seconds)
+    return value
+  }
+
+  /**
+   * Delete all keys in the currently selected database.
+   *
+   * @returns A promise that resolves once the database has been flushed.
+   */
+  async flushdb(): Promise<void> { await this.send('FLUSHDB', []) }
+
+  /**
+   * Get the underlying Bun `RedisClient` instance for advanced operations.
+   *
+   * @returns The raw Bun RedisClient.
+   */
+  getClient(): any { return this.client }
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+/** Configuration for a single Redis connection. */
+export interface RedisConnectionConfig {
+  /** Redis connection URL (default: `'redis://localhost:6379'`). */
+  url?: string
+  /** Key prefix applied to all operations (e.g. `'myapp:'`). */
+  prefix?: string
+  /** Connection timeout in milliseconds. */
+  connectionTimeout?: number
+  /** Idle timeout in milliseconds before the connection is closed. */
+  idleTimeout?: number
+  /** Whether to automatically reconnect on connection loss (default: `true`). */
+  autoReconnect?: boolean
+  /** Maximum number of reconnection attempts (default: `10`). */
+  maxRetries?: number
+  /** Enable automatic pipelining for improved throughput (default: `true`). */
+  enableAutoPipelining?: boolean
+  /** Enable TLS, or provide a TLS options object. */
+  tls?: boolean | object
+}
+
+/**
+ * Redis configuration supporting both single-connection and multi-connection setups.
+ *
+ * For a single connection, specify the connection fields directly.
+ * For multiple connections, use the `connections` map and optionally set `default`.
+ */
+export type RedisConfig = RedisConnectionConfig & {
+  /** Name of the default connection (default: `'default'`). */
+  default?: string
+  /** Named connection configurations. */
+  connections?: Record<string, RedisConnectionConfig>
+}