URL Shortener

Live Documentation

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!

🔗 Links

• 📦 NPM Package
• 🧾 Live Docs
• 🏗 The Node Forge