blue-fish-redis

library1.0.4jsnpmunverified

A Redis database component for the blue-fish framework, built on ioredis. Provides caching, message queuing, cron jobs, and distributed locks. Written in TypeScript with full type definitions. Current version 1.0.4 (released 2025). The package appears to be a fork or continuation of coa-redis, with a focus on bug fixes. Lightweight (few hundred lines) with no external dependencies beyond ioredis and blue-fish core.

database

npm install blue-fish-redis

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BLUE-FISH-REDIS

blue-fish-redis

databasejavascriptv1.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RedisBin

✓ import { RedisBin } from 'blue-fish-redis'

✗ const { RedisBin } = require('blue-fish-redis')

ESM-only. This package ships TypeScript types but does not support CommonJS.

RedisCache

✓ import { RedisCache } from 'blue-fish-redis'

✗ import RedisCache from 'blue-fish-redis'

Named export, not default. Available since v1.0.

RedisQueue

✓ import { RedisQueue } from 'blue-fish-redis'

Named export. Requires RedisBin instance as first parameter.

RedisCron

✓ import { RedisCron } from 'blue-fish-redis'

✗ import { Cron } from 'blue-fish-redis'

Exported as RedisCron. Other Cron-like names not available.

RedisLock

✓ import { RedisLock } from 'blue-fish-redis'

Distributed lock implementation. Uses Redis SETNX under the hood.

RedisQueueWorker

✓ import { RedisQueueWorker } from 'blue-fish-redis'

✗ import { Worker } from 'blue-fish-redis'

Must be named RedisQueueWorker. Worker alone is not exported.

Demonstrates RedisBin configuration, cache set/get/delete, message queue push/listen, and distributed lock acquire/release.

import { RedisBin, RedisCache, RedisQueue, RedisQueueWorker, RedisCron, RedisLock } from 'blue-fish-redis'; const redisConfig = { host: '127.0.0.1', port: 6379, password: process.env.REDIS_PASSWORD ?? '', db: 0, prefix: 'myapp_', trace: false, }; const redisBin = new RedisBin(redisConfig); // Cache example const cache = new RedisCache(redisBin); await cache.set('users', '42', { name: 'Alice' }, 300000); // 5 min try { const user = await cache.get('users', '42'); console.log('User:', user); } finally { await cache.delete('users', ['42']); } // Queue example const queue = new RedisQueue(redisBin, 'my-queue'); const worker = new RedisQueueWorker(queue); worker.on('greeting', async (id, data) => { console.log(`Message ${id}: ${data}`); }); await queue.push('greeting', 'msg-1', 'Hello!'); // Lock example const lock = new RedisLock(redisBin); const acquired = await lock.lock('resource-1', 10); // TTL 10s if (acquired) { try { // critical section } finally { await lock.unlock('resource-1'); } }

Debug

Known issues

breakingcoa-redis has been superseded by blue-fish-redis. Direct migration from coa-redis requires changing import source and possibly updating API calls.

fix

Replace 'coa-redis' with 'blue-fish-redis' in package.json and imports. Review the coa-redis API for any changes.

affects: >=1.0.0

breakingRedisCache.set() and related methods require a 'nsp' (namespace) parameter. Omitting it will cause a runtime error.

fix

Always provide a namespace string as the first argument to cache methods, e.g., cache.set('users', 'id', value, ttl).

affects: >=1.0.0

deprecatedThe 'prefix' option in RedisBin config is deprecated. Use explicit namespaces in cache and queue operations instead.

fix

Remove 'prefix' from config and use the 'nsp' parameter in RedisCache methods.

affects: >=1.0.0

gotchaRedisCron requires a queue worker and a version string. The version is used to avoid duplicate task execution during rolling updates.

fix

Instantiate RedisCron with (queueWorker, version) where version is the application's semantic version (e.g., '1.2.3').

affects: >=1.0.0

gotchaRedisQueueWorker uses an event-based API. You must call worker.on(event, listener) after construction, not before queue.push().

fix

Ensure worker.on('messageName', callback) is registered before producing messages to avoid missed events.

affects: >=1.0.0

breakingAll classes (RedisBin, RedisCache, etc.) are TypeScript classes. They cannot be used as interfaces or types without instantiation.

fix

Use constructor with 'new' keyword. For type annotations, you may use the class name as a type (e.g., let cache: RedisCache).

affects: >=1.0.0

gotchaRedisLock.unlock() does not use Redis transactions. If the lock TTL expires before unlock, the call may succeed but release a different lock.

fix

Always set an appropriate TTL. Consider using Lua scripts for atomic unlock if race conditions are a concern.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: RedisCache is not a constructor

Importing RedisCache as a default import instead of named import.

fix

Use: import { RedisCache } from 'blue-fish-redis'

Error: namespace is required

Missing 'nsp' argument in cache methods (e.g., cache.set(value)).

fix

Provide a namespace string as the first argument: cache.set('my-namespace', 'key', value, ttl)

RedisCron requires a version argument. Please provide the application version.

Instantiated RedisCron with only one argument (queue worker) instead of two.

fix

new RedisCron(queueWorker, '1.0.0') where the second argument is the app version string.

Error: cannot create Redis lock with TTL <= 0

lock.lock() called with a TTL of 0 or negative number.

fix

Use a positive TTL (in seconds): await lock.lock('resource', 30)

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

ioredisrequiredUnderlying Redis client. All Redis operations go through ioredis.

blue-fishrequiredFramework dependency for blue-fish-native environment.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ityifan/blue-fish-redis ↗

packageblue-fish-redis ↗

homepagehttps://github.com/ityifan/blue-fish-redis#readme ↗