@the-node-forge/url-shortener
Version:
A URL shortener that generates and stores unique aliases for long URLs, with optional expiration and custom alias support.
141 lines (91 loc) • 4.1 kB
Markdown
<div align="center">
# URL Shortener
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@the-node-forge/url-shortener)
[](https://github.com/The-Node-Forge/url-shortener/actions)
[Live Documentation](https://the-node-forge.github.io/url-shortener/)
</div>
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
```bash
npm install @the-node-forge/url-shortener
```
```bash
yarn add @the-node-forge/url-shortener
```
### Redis Required
```bash
npm install redis
```
> Redis is required and should be connected externally via `createClient()`
## 🛠️ Basic Usage
```ts
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
```ts
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](https://github.com/The-Node-Forge/url-shortener)!
## 🔗 Links
- 📦 [NPM Package](https://www.npmjs.com/package/@the-node-forge/url-shortener)
- 🧾 [Live Docs](https://the-node-forge.github.io/url-shortener/)
- 🏗 [The Node Forge](https://github.com/The-Node-Forge)