@tekir/redis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tekir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+<p align="center">
+  <img src="https://tekir.io/logo.svg" width="80" alt="tekir" />
+</p>
+
+<h1 align="center">@tekir/redis</h1>
+
+<p align="center">Redis connection and client management</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@tekir/redis"><img src="https://img.shields.io/npm/v/@tekir/redis.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@tekir/redis"><img src="https://img.shields.io/npm/dm/@tekir/redis.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/tekir-io/tekir/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@tekir/redis.svg" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="https://tekir.io">Website</a> · <a href="https://docs.tekir.io">Documentation</a> · <a href="https://github.com/tekir-io/tekir">GitHub</a>
+</p>
+
+---
+
+## Installation
+
+```bash
+bun add @tekir/redis
+```
+
+For full usage and configuration, see the [documentation](https://docs.tekir.io/advanced/redis).
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Redis } from './redis';
+export { RedisManager } from './manager';
+export { RedisProvider } from './provider';

package/dist/manager.d.ts

@@ -0,0 +1,121 @@
+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 declare class RedisManager {
+    private _connections;
+    private _defaultName;
+    private _config;
+    /**
+     * Create a new RedisManager.
+     *
+     * @param config - Redis configuration with optional named connections.
+     */
+    constructor(config?: RedisConfig);
+    /**
+     * 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;
+    /**
+     * List all configured connection names.
+     *
+     * @returns An array of connection name strings.
+     *
+     * @example
+     * ```ts
+     * manager.connectionNames // ['cache', 'session']
+     * ```
+     */
+    get connectionNames(): string[];
+    /**
+     * 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;
+    /** @see {@link Redis.get} */
+    get(key: string): Promise<string | null>;
+    /** @see {@link Redis.set} */
+    set(key: string, value: string | number): Promise<void>;
+    /** @see {@link Redis.del} */
+    del(...keys: string[]): Promise<void>;
+    /** @see {@link Redis.exists} */
+    exists(key: string): Promise<boolean>;
+    /** @see {@link Redis.incr} */
+    incr(key: string): Promise<number>;
+    /** @see {@link Redis.decr} */
+    decr(key: string): Promise<number>;
+    /** @see {@link Redis.expire} */
+    expire(key: string, seconds: number): Promise<void>;
+    /** @see {@link Redis.ttl} */
+    ttl(key: string): Promise<number>;
+    /** @see {@link Redis.hget} */
+    hget(key: string, field: string): Promise<string | null>;
+    /** @see {@link Redis.hmset} */
+    hmset(key: string, fields: string[]): Promise<void>;
+    /** @see {@link Redis.hmget} */
+    hmget(key: string, fields: string[]): Promise<(string | null)[]>;
+    /** @see {@link Redis.hincrby} */
+    hincrby(key: string, field: string, increment: number): Promise<number>;
+    /** @see {@link Redis.sadd} */
+    sadd(key: string, ...members: string[]): Promise<number>;
+    /** @see {@link Redis.srem} */
+    srem(key: string, ...members: string[]): Promise<number>;
+    /** @see {@link Redis.sismember} */
+    sismember(key: string, member: string): Promise<boolean>;
+    /** @see {@link Redis.smembers} */
+    smembers(key: string): Promise<string[]>;
+    /** @see {@link Redis.publish} */
+    publish(channel: string, message: string): Promise<void>;
+    /** @see {@link Redis.subscribe} */
+    subscribe(channel: string, callback: (message: string, channel: string) => void): Promise<void>;
+    /** @see {@link Redis.unsubscribe} */
+    unsubscribe(channel?: string): Promise<void>;
+    /** @see {@link Redis.send} */
+    send(command: string, args?: string[]): Promise<any>;
+    /** @see {@link Redis.getJSON} */
+    getJSON<T = any>(key: string): Promise<T | null>;
+    /** @see {@link Redis.setJSON} */
+    setJSON(key: string, value: any, expireSeconds?: number): Promise<void>;
+    /** @see {@link Redis.remember} */
+    remember<T>(key: string, seconds: number, callback: () => Promise<T>): Promise<T>;
+    /** @see {@link Redis.flushdb} */
+    flushdb(): Promise<void>;
+    /** @see {@link Redis.connected} */
+    get connected(): boolean;
+    /** @see {@link Redis.getClient} */
+    getClient(): any;
+}

package/dist/manager.js

@@ -0,0 +1,153 @@
+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 {
+    _connections = new Map();
+    _defaultName;
+    _config;
+    /**
+     * Create a new RedisManager.
+     *
+     * @param config - Redis configuration with optional named connections.
+     */
+    constructor(config = {}) {
+        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) {
+        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() {
+        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) {
+        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) { return this.connection().get(key); }
+    /** @see {@link Redis.set} */
+    set(key, value) { return this.connection().set(key, value); }
+    /** @see {@link Redis.del} */
+    del(...keys) { return this.connection().del(...keys); }
+    /** @see {@link Redis.exists} */
+    exists(key) { return this.connection().exists(key); }
+    /** @see {@link Redis.incr} */
+    incr(key) { return this.connection().incr(key); }
+    /** @see {@link Redis.decr} */
+    decr(key) { return this.connection().decr(key); }
+    /** @see {@link Redis.expire} */
+    expire(key, seconds) { return this.connection().expire(key, seconds); }
+    /** @see {@link Redis.ttl} */
+    ttl(key) { return this.connection().ttl(key); }
+    /** @see {@link Redis.hget} */
+    hget(key, field) { return this.connection().hget(key, field); }
+    /** @see {@link Redis.hmset} */
+    hmset(key, fields) { return this.connection().hmset(key, fields); }
+    /** @see {@link Redis.hmget} */
+    hmget(key, fields) { return this.connection().hmget(key, fields); }
+    /** @see {@link Redis.hincrby} */
+    hincrby(key, field, increment) { return this.connection().hincrby(key, field, increment); }
+    /** @see {@link Redis.sadd} */
+    sadd(key, ...members) { return this.connection().sadd(key, ...members); }
+    /** @see {@link Redis.srem} */
+    srem(key, ...members) { return this.connection().srem(key, ...members); }
+    /** @see {@link Redis.sismember} */
+    sismember(key, member) { return this.connection().sismember(key, member); }
+    /** @see {@link Redis.smembers} */
+    smembers(key) { return this.connection().smembers(key); }
+    /** @see {@link Redis.publish} */
+    publish(channel, message) { return this.connection().publish(channel, message); }
+    /** @see {@link Redis.subscribe} */
+    subscribe(channel, callback) { return this.connection().subscribe(channel, callback); }
+    /** @see {@link Redis.unsubscribe} */
+    unsubscribe(channel) { return this.connection().unsubscribe(channel); }
+    /** @see {@link Redis.send} */
+    send(command, args = []) { return this.connection().send(command, args); }
+    /** @see {@link Redis.getJSON} */
+    getJSON(key) { return this.connection().getJSON(key); }
+    /** @see {@link Redis.setJSON} */
+    setJSON(key, value, expireSeconds) { return this.connection().setJSON(key, value, expireSeconds); }
+    /** @see {@link Redis.remember} */
+    remember(key, seconds, callback) { return this.connection().remember(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/dist/provider.d.ts

@@ -0,0 +1,20 @@
+import type { App } from '@tekir/core';
+/**
+ * Service provider that reads the `redis` configuration and registers
+ * a {@link RedisManager} instance in the application container.
+ */
+export declare 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())
+     * ```
+     */
+    register(app: App): Promise<void>;
+}

package/dist/provider.js

@@ -0,0 +1,25 @@
+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) {
+        const config = app.use('config');
+        if (!config('redis'))
+            return;
+        app.instance('redis', new RedisManager(config('redis')));
+    }
+}

package/dist/redis.d.ts

@@ -0,0 +1,272 @@
+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 declare class Redis {
+    private client;
+    private prefix;
+    private config;
+    /**
+     * @param config - Redis connection configuration.
+     */
+    constructor(config?: RedisConnectionConfig);
+    private key;
+    /**
+     * Open the connection to the Redis server.
+     *
+     * @returns A promise that resolves once the connection is established.
+     *
+     * @example
+     * ```ts
+     * await redis.connect()
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the connection to the Redis server.
+     */
+    close(): void;
+    /**
+     * Whether the client is currently connected to Redis.
+     *
+     * @returns `true` if the connection is active.
+     */
+    get connected(): boolean;
+    /**
+     * 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
+     * ```
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * 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)
+     * ```
+     */
+    set(key: string, value: string | number): Promise<void>;
+    /**
+     * Delete one or more keys.
+     *
+     * @param keys - The keys to delete.
+     *
+     * @example
+     * ```ts
+     * await redis.del('key1', 'key2')
+     * ```
+     */
+    del(...keys: string[]): Promise<void>;
+    /**
+     * Check whether a key exists.
+     *
+     * @param key - The key to check.
+     * @returns `true` if the key exists.
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Increment the integer value of a key by one.
+     *
+     * @param key - The key to increment.
+     * @returns The new value after incrementing.
+     */
+    incr(key: string): Promise<number>;
+    /**
+     * Decrement the integer value of a key by one.
+     *
+     * @param key - The key to decrement.
+     * @returns The new value after decrementing.
+     */
+    decr(key: string): Promise<number>;
+    /**
+     * Set a timeout on a key (in seconds).
+     *
+     * @param key - The key to set the expiry on.
+     * @param seconds - Time-to-live in seconds.
+     */
+    expire(key: string, seconds: number): Promise<void>;
+    /**
+     * 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.
+     */
+    ttl(key: string): Promise<number>;
+    /**
+     * 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.
+     */
+    hget(key: string, field: string): Promise<string | null>;
+    /**
+     * 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']`).
+     */
+    hmset(key: string, fields: string[]): Promise<void>;
+    /**
+     * 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).
+     */
+    hmget(key: string, fields: string[]): Promise<(string | null)[]>;
+    /**
+     * 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.
+     */
+    hincrby(key: string, field: string, increment: number): Promise<number>;
+    /**
+     * 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).
+     */
+    sadd(key: string, ...members: string[]): Promise<number>;
+    /**
+     * 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.
+     */
+    srem(key: string, ...members: string[]): Promise<number>;
+    /**
+     * 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.
+     */
+    sismember(key: string, member: string): Promise<boolean>;
+    /**
+     * Get all members of a set.
+     *
+     * @param key - The set key.
+     * @returns An array of all members in the set.
+     */
+    smembers(key: string): Promise<string[]>;
+    /**
+     * Publish a message to a channel.
+     *
+     * @param channel - The channel name.
+     * @param message - The message string to publish.
+     */
+    publish(channel: string, message: string): Promise<void>;
+    /**
+     * 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}`)
+     * })
+     * ```
+     */
+    subscribe(channel: string, callback: (message: string, channel: string) => void): Promise<void>;
+    /**
+     * Unsubscribe from a channel, or from all channels if none is specified.
+     *
+     * @param channel - The channel to unsubscribe from. Omit to unsubscribe from all.
+     */
+    unsubscribe(channel?: string): Promise<void>;
+    /**
+     * 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'
+     * ```
+     */
+    send(command: string, args?: string[]): Promise<any>;
+    /**
+     * 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')
+     * ```
+     */
+    getJSON<T = any>(key: string): Promise<T | 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)
+     * ```
+     */
+    setJSON(key: string, value: any, expireSeconds?: number): Promise<void>;
+    /**
+     * 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')
+     * })
+     * ```
+     */
+    remember<T>(key: string, seconds: number, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Delete all keys in the currently selected database.
+     *
+     * @returns A promise that resolves once the database has been flushed.
+     */
+    flushdb(): Promise<void>;
+    /**
+     * Get the underlying Bun `RedisClient` instance for advanced operations.
+     *
+     * @returns The raw Bun RedisClient.
+     */
+    getClient(): any;
+}