Pereira Stack

A small, type-safe Redis and queue helper package.

It provides a lightweight Redis, RateLimit, Jobs

Get Started

bun add pereiradev

init

// Option 1: Use environment variables (global instance)
const redis1 = Redis.fromEnv();
// OR
const redis1_alt = new Redis();

// Option 2: Pass a specific URL
const redis2 = new Redis({
  url: process.env.REDIS_URL || "redis://localhost:6379",
});

// Option 3: Pass an existing IORedis instance
const redis3 = new Redis({ client: existingIORedisInstance });

Rate Limiting

example: https://redis-etvd.vercel.app/

import { Ratelimit, Redis } from 'pereiradev';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "10 s"),
});

const identifier = getIpAddress();
const { success } = await ratelimit.limit(identifier);

if (!success) {
  return res.status(429).json({ "error": "Too many requests" });
}

Caching

import { Redis } from 'pereiradev';

const redis = Redis.fromEnv();

const item = await redis.get("item:123");

if (item) {
  return item;
}

Jobs & Cron

export const redis = Redis.fromEnv();

export const trigger = new TriggerClient({ id: 'my-app', redis });

export const sendEmailTask = trigger.task<{ to: string; subject: string }, void>(
  'send-email',
  { maxAttempts: 5, backoff: 'exponential', backoffDelay: 2_000, concurrency: 10 },
  async (payload, ctx) => {
    ctx.logger.info('Sending email', { to: payload.to });
    // ... send email
  },
);

// Example scheduled task
export const dailyReport = trigger.scheduleTask(
  'daily-report',
  { cron: '0 9 * * *', timezone: 'Asia/Tokyo' },
  { maxAttempts: 3 },
  async (ctx) => {
    ctx.logger.info('Generating daily report');
    // ... generate report
  },
);

About This Project

This package is designed for applications that want a clean Redis abstraction without giving up direct access to Redis behavior.

It includes:

• A typed Redis client wrapper with JSON-aware helpers
• A chainable pipeline API
• A Ratelimit class with support for timeout handling, ephemeral blocking, analytics, and blockUntilReady
• QueueMonitor and TriggerClient helpers
• Example usage for cache and rate limiting flows

The package exports from src/index.ts, so consumers can import from @pereira/stack after build.

How To Run

1. Install dependencies

bun install

2. Configure Redis

Create a .env file with your Redis connection string:

REDIS_URL=redis://localhost:6379

You can also start a local Redis instance with Docker:

docker compose up -d

3. Run the project

bun run dev

TODO: package.json currently points bun run dev at a missing root index.ts; verify the intended dev entry before relying on this command.

4. Build the package

bun run build

5. Run tests

bun run test

6. Check formatting and linting

bun run check
bun run fix

Folder Structure

Package Scripts

• bun run dev - TODO: verify script target; it currently references a missing root index.ts
• bun run build - generate distributable output from src/index.ts with tsup
• bun run test - execute the test suite
• bun run lint - run Biome checks
• bun run format - format files with Biome
• bun run check - run Ultracite checks
• bun run fix - apply Ultracite fixes

Docs App

The Fumadocs/Next.js documentation app lives in docs/. Run these commands from that directory:

• bun run dev - start the docs dev server
• bun run build - build the docs app
• bun run types:check - regenerate Fumadocs output, run Next typegen, and check TypeScript