Redis URL Parser (Simple)

1.0.2 · active · verified Tue Apr 21

parse-redis-url-simple is a focused JavaScript utility designed for parsing Redis connection URLs, including complex scenarios like Redis Sentinel configurations. It provides a simple, direct API for converting various URL formats into structured objects containing host, port, database, and password. Unlike several unmaintained or production-unsuitable prior art libraries mentioned in its README, this package aims to offer a robust and reliable solution for production environments. Currently at version 1.0.2, it appears to follow a stable release cadence typical of utility libraries, with updates primarily for bug fixes or minor enhancements. A key differentiator is its explicit support for ioredis-compatible Sentinel URLs, addressing a common need in distributed Redis setups.

Common errors

```
TypeError: parseRedisUrl is not a function
```
cause This error typically occurs when attempting to use `import { parseRedisUrl } from 'parse-redis-url-simple'` (named import) for a module that provides a default export, or incorrectly using `require` for a default export.

fix For ESM, use `import parseRedisUrl from 'parse-redis-url-simple';`. For CommonJS, use `const parseRedisUrl = require('parse-redis-url-simple');`.
```
Sentinel parsing returns a single host object instead of an array of multiple hosts
```
cause This happens when a comma-separated list of sentinel hosts is provided to `parseRedisUrl` but the `sentinel=true` flag is omitted or passed incorrectly as the second argument.

fix Ensure the call is `parseRedisUrl('host1:port,host2:port', true)` to correctly parse and return an array of multiple sentinel host objects.

Warnings

gotcha When parsing Sentinel URLs, the `sentinel=true` argument must be explicitly passed as a boolean `true` (or truthy value) as the second parameter to the `parseRedisUrl` function. It is not automatically inferred from the URL string format.
Fix: Ensure `parseRedisUrl('host1:port,host2:port', true)` is used for Sentinel setups, rather than attempting to embed a sentinel flag within the URL string itself.
gotcha The parser will ignore any username specified in the URL string, such as `redis://user:password@host:port/`. Only the password field (if present after a colon before the host) will be parsed and returned in the output object.
Fix: If Redis username authentication is critical, this library might not be sufficient on its own. Ensure your Redis client handles username separately if required, or confirm your Redis setup only relies on password authentication.
gotcha URLs without a host and port will default to `localhost:6379`, and the database will default to `0`. For example, calling `parseRedisUrl()` or `parseRedisUrl('redis://')` will return `[{host: 'localhost', port: 6379, database: '0', password: undefined}]`. Be aware of these implicit defaults if not providing a full URL.
Fix: Always provide a complete and explicit Redis URL string to avoid relying on implicit defaults, especially in production environments where explicit configuration is preferred.

Install

npm install parse-redis-url-simple npm
yarn add parse-redis-url-simple yarn
pnpm add parse-redis-url-simple pnpm

Imports

parseRedisUrl

wrong:

import { parseRedisUrl } from 'parse-redis-url-simple';

correct:

import parseRedisUrl from 'parse-redis-url-simple';

The library exports a default function. Use default import for ESM.

parseRedisUrl
```
const parseRedisUrl = require('parse-redis-url-simple');
```
CommonJS `require` syntax is fully supported and shown in the package's examples.
parseRedisUrl (TypeScript)
wrong:
```
import * as parseRedisUrl from 'parse-redis-url-simple';
```
correct:
```
import parseRedisUrl from 'parse-redis-url-simple';
```
The package ships with TypeScript types. The recommended usage is a default import, similar to ESM JavaScript.

Quickstart

This quickstart demonstrates how to parse various Redis URL formats, including single instances, multiple comma-separated instances, URLs with passwords, and Redis Sentinel configurations using the `parseRedisUrl` function.

import parseRedisUrl from 'parse-redis-url-simple';

// Parse a basic Redis URL with a specific database
const basicUrl = 'redis://localhost:6379/1';
console.log('Basic URL:', parseRedisUrl(basicUrl));
// => [{host: 'localhost', port: 6379, database: '1', password: undefined}]

// Parse multiple Redis instances from a comma-separated string
const multipleUrls = 'redis://barhost.com:39143/,redis://foohost.com:39143/';
console.log('Multiple URLs:', parseRedisUrl(multipleUrls));
// => [{host: 'barhost.com', port: 39143, database: '0', password: undefined}, {host: 'foohost.com', port: 39143, database: '0', password: undefined}]

// Parse a Redis URL that includes a password (username is ignored)
const passwordUrl = 'redis://user:n9y25ah7@foohost.com:39143/';
console.log('Password URL:', parseRedisUrl(passwordUrl));
// => [{host: 'foohost.com', port: 39143, database: '0', password: 'n9y25ah7'}]

// Parse Redis Sentinel URLs by passing `true` as the second argument
const sentinelHosts = 'barhost.com:39143,foohost.com:39143,foobarhost.com:39143';
console.log('Sentinel Hosts:', parseRedisUrl(sentinelHosts, true));
// => [{host: 'barhost.com', port: 39143},{host: 'foohost.com', port: 39143},{host: 'foobarhost.com', port: 39143}]

view raw JSON →