@the-node-forge/url-shortener

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