Overview
Returns the specified elements of the list stored at key. The offsets start and end are zero-based indexes. These offsets can also be negative numbers indicating offsets from the end of the list.
Method Signature
lrange<TResult = string>(key: string, start: number, end: number): Promise<TResult[]>
Parameters
The starting index (zero-based). Negative values indicate offsets from the end of the list (e.g., -1 is the last element, -2 is the second-to-last).
The ending index (zero-based, inclusive). Negative values indicate offsets from the end of the list. Use -1 to get all elements from start to the end of the list.
Return Value
An array of elements in the specified range. Returns an empty array if the list does not exist or the range is out of bounds.
Examples
Basic Usage
import { Redis } from '@upstash/redis';
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL,
token: process.env.UPSTASH_REDIS_REST_TOKEN,
});
// Set up a list
await redis.rpush('mylist', 'one', 'two', 'three', 'four', 'five');
// Get elements from index 1 to 3
const range = await redis.lrange('mylist', 1, 3);
console.log(range); // ['two', 'three', 'four']
// Get all elements
const all = await redis.lrange('mylist', 0, -1);
console.log(all); // ['one', 'two', 'three', 'four', 'five']
Using Negative Indexes
await redis.rpush('items', 'A', 'B', 'C', 'D', 'E');
// Get the last 3 elements
const lastThree = await redis.lrange('items', -3, -1);
console.log(lastThree); // ['C', 'D', 'E']
// Get all except the first element
const withoutFirst = await redis.lrange('items', 1, -1);
console.log(withoutFirst); // ['B', 'C', 'D', 'E']
// Get all except the last element
const withoutLast = await redis.lrange('items', 0, -2);
console.log(withoutLast); // ['A', 'B', 'C', 'D']
Working with Objects
interface Product {
id: string;
name: string;
price: number;
}
// Add products
await redis.rpush<Product>('products',
{ id: '1', name: 'Laptop', price: 999 },
{ id: '2', name: 'Mouse', price: 25 },
{ id: '3', name: 'Keyboard', price: 75 }
);
// Get first two products
const products = await redis.lrange<Product>('products', 0, 1);
console.log(products[0].name); // 'Laptop'
console.log(products[1].name); // 'Mouse'
const pageSize = 10;
const pageNumber = 2; // 0-based
const start = pageNumber * pageSize;
const end = start + pageSize - 1;
const page = await redis.lrange('items', start, end);
console.log(`Page ${pageNumber + 1}:`, page);
Getting Recent Items
// Get the 5 most recent items (assuming newer items are pushed with RPUSH)
const recentCount = 5;
const recentItems = await redis.lrange('recent:activity', -recentCount, -1);
console.log('Recent items:', recentItems);
Viewing Queue Contents
// View the next 10 items in a queue without removing them
const nextJobs = await redis.lrange('queue:jobs', 0, 9);
console.log('Next jobs to process:', nextJobs);
// Check if queue has items
const hasItems = nextJobs.length > 0;
See Also
- LLEN - Get the length of a list
- LINDEX - Get an element by index
- LPUSH - Insert elements at the head of a list
- RPUSH - Insert elements at the tail of a list