A simple, fast, and Redis-backed URL shortener written in TypeScript. Supports custom aliases, TTL expiration, and works seamlessly in Node.js environments.
✨ Features
- ✅ Custom Aliases – Define readable slugs like
sho.rt/launch - ✅ Expiration Support – Auto-expire short links after a set TTL
- ✅ Redis Store – High-performance storage backend
- 🔀 Collision Handling – Auto-generate or error on alias conflicts
- 📚 Fully Typed – TypeScript-first design with clean API docs
📦 Installation
npm install @the-node-forge/url-shortener
yarn add @the-node-forge/url-shortener
Redis Required
npm install redis
Redis is required and should be connected externally via
createClient()
🛠️ Basic Usage
import { createClient } from 'redis';
import { RedisStore } from '@the-node-forge/url-shortener/stores/redisStore';
import { URLShortener } from '@the-node-forge/url-shortener';
const client = createClient();
await client.connect();
const store = new RedisStore(client);
const shortener = new URLShortener('https://sho.rt', store);
const shortUrl = await shortener.shorten('https://example.com/very/long/url', {
alias: 'launch',
expiresIn: '7d',
});
console.log(shortUrl); // https://sho.rt/launch
Resolve a Link
const result = await shortener.resolve('launch');
console.log(result); // https://example.com/very/long/url
📘 API Reference
new URLShortener(baseDomain, store)
| Parameter | Type | Required | Description |
|---|---|---|---|
baseDomain | string | ❌ | Domain to prefix for short URLs |
store | StoreAdapter | ✅ | Instance of RedisStore |
shorten(longUrl, options?)
| Option | Type | Required | Description |
|---|---|---|---|
longUrl | string | ✅ | The URL to shorten |
alias | string | ❌ | Custom code (e.g., "my-link") |
expiresIn | string | ❌ | TTL like "1h", "30m", "7d" |
override | boolean | ❌ | Replace alias if it already exists |
resolve(alias)
Returns the original URL string, or null if expired or missing.
🌍 Environment Compatibility
This package works in modern server-side runtimes:
- ✅ Node.js
- ✅ Deno / Bun (with bundler)
| Store | Runtime | Notes |
|---|---|---|
| RedisStore | ✅ Node-only | Requires Redis and redis package |
This is a backend utility. Frontend usage is not supported directly — build an API endpoint instead.
💡 Contributing
Contributions welcome! Open an issue or PR if you have improvements, ideas, or bug fixes.
⭐ Support
If you like this project, consider leaving a ⭐ on GitHub!