@tekir/redis 0.1.0

package/dist/redis.js

@@ -0,0 +1,316 @@
+/**
+ * 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 {
+    client;
+    prefix;
+    config;
+    /**
+     * @param config - Redis connection configuration.
+     */
+    constructor(config = {}) {
+        this.config = config;
+        this.prefix = config.prefix || '';
+        const { RedisClient } = Bun;
+        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,
+        });
+    }
+    key(k) {
+        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() { await this.client.connect(); }
+    /**
+     * Close the connection to the Redis server.
+     */
+    close() { this.client.close(); }
+    /**
+     * Whether the client is currently connected to Redis.
+     *
+     * @returns `true` if the connection is active.
+     */
+    get connected() { 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) { 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, value) { 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) { 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) { 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) { 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) { 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, seconds) { 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) { 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, field) { 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, fields) { 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, fields) { 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, field, increment) { 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, ...members) { 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, ...members) { 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, member) { 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) { 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, message) { 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, callback) {
+        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) { 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, args = []) { 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(key) {
+        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, value, expireSeconds) {
+        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(key, seconds, callback) {
+        const cached = await this.getJSON(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() { await this.send('FLUSHDB', []); }
+    /**
+     * Get the underlying Bun `RedisClient` instance for advanced operations.
+     *
+     * @returns The raw Bun RedisClient.
+     */
+    getClient() { return this.client; }
+}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+/** 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>;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@tekir/redis",
+  "version": "0.1.0",
+  "description": "Redis connection and client management",
+  "author": "dev@tekir.io",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tekir-io/tekir.git",
+    "directory": "packages/tekir-redis"
+  },
+  "homepage": "https://github.com/tekir-io/tekir/tree/main/packages/tekir-redis",
+  "keywords": [
+    "tekir",
+    "bun",
+    "typescript",
+    "framework",
+    "nodejs",
+    "fullstack"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "types": "dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@tekir/core": "^0.1.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc --noEmit false",
+    "prepublishOnly": "bun run build"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { Redis } from './redis'
+export { RedisManager } from './manager'
+export { RedisProvider } from './provider'
+export type { RedisConfig, RedisConnectionConfig } from './types'

package/src/manager.ts

@@ -0,0 +1,161 @@
+import type { RedisConfig } from './types'
+import { Redis } from './redis'
+
+/**
+ * Manages multiple named Redis connections with lazy initialization.
+ *
+ * Provides proxy methods that delegate to the default connection for convenience,
+ * while also allowing access to any named connection via {@link RedisManager.connection}.
+ *
+ * @example
+ * ```ts
+ * const manager = new RedisManager({
+ *   default: 'cache',
+ *   connections: {
+ *     cache: { url: 'redis://localhost:6379/0' },
+ *     session: { url: 'redis://localhost:6379/1' },
+ *   },
+ * })
+ * await manager.set('key', 'value')               // uses 'cache'
+ * await manager.connection('session').set('k', 'v') // uses 'session'
+ * ```
+ */
+export class RedisManager {
+  private _connections = new Map<string, Redis>()
+  private _defaultName: string
+  private _config: RedisConfig
+
+  /**
+   * Create a new RedisManager.
+   *
+   * @param config - Redis configuration with optional named connections.
+   */
+  constructor(config: RedisConfig = {}) {
+    this._config = config
+    this._defaultName = config.default || 'default'
+
+    // If no connections map, treat the whole config as a single connection
+    if (!config.connections) {
+      this._connections.set(this._defaultName, new Redis(config))
+    }
+  }
+
+  /**
+   * Get a named Redis connection. The connection is lazy-initialized on first access.
+   *
+   * @param name - The connection name. Defaults to the configured default connection.
+   * @returns The {@link Redis} instance for the named connection.
+   * @throws If the named connection is not configured.
+   *
+   * @example
+   * ```ts
+   * const cache = manager.connection('cache')
+   * await cache.get('key')
+   * ```
+   */
+  connection(name?: string): Redis {
+    const connName = name || this._defaultName
+    if (!this._connections.has(connName)) {
+      const connConfig = this._config.connections?.[connName]
+      if (!connConfig) {
+        throw new Error(
+          `[@tekir/redis] Connection "${connName}" is not configured. ` +
+          `Available: ${this.connectionNames.join(', ')}`
+        )
+      }
+      this._connections.set(connName, new Redis(connConfig))
+    }
+    return this._connections.get(connName)!
+  }
+
+  /**
+   * List all configured connection names.
+   *
+   * @returns An array of connection name strings.
+   *
+   * @example
+   * ```ts
+   * manager.connectionNames // ['cache', 'session']
+   * ```
+   */
+  get connectionNames(): string[] {
+    if (this._config.connections) return Object.keys(this._config.connections)
+    return [this._defaultName]
+  }
+
+  /**
+   * Close a specific named connection, or all connections if no name is given.
+   *
+   * @param name - The connection name to close. Omit to close all connections.
+   *
+   * @example
+   * ```ts
+   * manager.close('session') // close one connection
+   * manager.close()          // close all connections
+   * ```
+   */
+  close(name?: string): void {
+    if (name) {
+      this._connections.get(name)?.close()
+      this._connections.delete(name)
+    } else {
+      for (const [, conn] of this._connections) conn.close()
+      this._connections.clear()
+    }
+  }
+
+  // ─── Proxy methods delegating to the default connection ───
+
+  /** @see {@link Redis.get} */
+  get(key: string) { return this.connection().get(key) }
+  /** @see {@link Redis.set} */
+  set(key: string, value: string | number) { return this.connection().set(key, value) }
+  /** @see {@link Redis.del} */
+  del(...keys: string[]) { return this.connection().del(...keys) }
+  /** @see {@link Redis.exists} */
+  exists(key: string) { return this.connection().exists(key) }
+  /** @see {@link Redis.incr} */
+  incr(key: string) { return this.connection().incr(key) }
+  /** @see {@link Redis.decr} */
+  decr(key: string) { return this.connection().decr(key) }
+  /** @see {@link Redis.expire} */
+  expire(key: string, seconds: number) { return this.connection().expire(key, seconds) }
+  /** @see {@link Redis.ttl} */
+  ttl(key: string) { return this.connection().ttl(key) }
+  /** @see {@link Redis.hget} */
+  hget(key: string, field: string) { return this.connection().hget(key, field) }
+  /** @see {@link Redis.hmset} */
+  hmset(key: string, fields: string[]) { return this.connection().hmset(key, fields) }
+  /** @see {@link Redis.hmget} */
+  hmget(key: string, fields: string[]) { return this.connection().hmget(key, fields) }
+  /** @see {@link Redis.hincrby} */
+  hincrby(key: string, field: string, increment: number) { return this.connection().hincrby(key, field, increment) }
+  /** @see {@link Redis.sadd} */
+  sadd(key: string, ...members: string[]) { return this.connection().sadd(key, ...members) }
+  /** @see {@link Redis.srem} */
+  srem(key: string, ...members: string[]) { return this.connection().srem(key, ...members) }
+  /** @see {@link Redis.sismember} */
+  sismember(key: string, member: string) { return this.connection().sismember(key, member) }
+  /** @see {@link Redis.smembers} */
+  smembers(key: string) { return this.connection().smembers(key) }
+  /** @see {@link Redis.publish} */
+  publish(channel: string, message: string) { return this.connection().publish(channel, message) }
+  /** @see {@link Redis.subscribe} */
+  subscribe(channel: string, callback: (message: string, channel: string) => void) { return this.connection().subscribe(channel, callback) }
+  /** @see {@link Redis.unsubscribe} */
+  unsubscribe(channel?: string) { return this.connection().unsubscribe(channel) }
+  /** @see {@link Redis.send} */
+  send(command: string, args: string[] = []) { return this.connection().send(command, args) }
+  /** @see {@link Redis.getJSON} */
+  getJSON<T = any>(key: string) { return this.connection().getJSON<T>(key) }
+  /** @see {@link Redis.setJSON} */
+  setJSON(key: string, value: any, expireSeconds?: number) { return this.connection().setJSON(key, value, expireSeconds) }
+  /** @see {@link Redis.remember} */
+  remember<T>(key: string, seconds: number, callback: () => Promise<T>) { return this.connection().remember<T>(key, seconds, callback) }
+  /** @see {@link Redis.flushdb} */
+  flushdb() { return this.connection().flushdb() }
+  /** @see {@link Redis.connected} */
+  get connected() { return this.connection().connected }
+  /** @see {@link Redis.getClient} */
+  getClient() { return this.connection().getClient() }
+}

package/src/provider.ts

@@ -0,0 +1,26 @@
+import type { App } from '@tekir/core'
+import { RedisManager } from './manager'
+
+/**
+ * Service provider that reads the `redis` configuration and registers
+ * a {@link RedisManager} instance in the application container.
+ */
+export class RedisProvider {
+  /**
+   * Register the Redis manager into the application container.
+   *
+   * @param app - The Tekir application instance.
+   * @returns A promise that resolves once registration is complete.
+   *
+   * @example
+   * ```ts
+   * // In your providers list:
+   * app.register(new RedisProvider())
+   * ```
+   */
+  async register(app: App) {
+    const config = app.use('config')
+    if (!config('redis')) return
+    app.instance('redis', new RedisManager(config('redis')))
+  }
+}