waitlist-mailer
Version:
Modern, modular TypeScript library for managing waitlists with pluggable storage and mail providers. Supports MongoDB, SQL databases, and custom adapters with zero required dependencies for basic usage.
151 lines (97 loc) • 4.06 kB
Markdown
A **modern, modular, and lightweight** TypeScript library for managing email waitlists with **zero required dependencies** for basic usage. Built with clean architecture principles: **dependency injection**, **adapter pattern**, and **event-driven design**.
- ✅ **Modular Adapters**: Pluggable storage and mail providers
- ✅ **Zero Bloat**: No forced dependencies unless you use them
- ✅ **Dependency Injection**: Clean, testable architecture
- ✅ **TypeScript-First**: Full type safety with generic support
- ✅ **Event-Driven**: Rich event system for integrations
- ✅ **Production-Ready**: 44+ tests, comprehensive coverage
- ✅ **Smart Defaults**: Works out of the box with in-memory storage
- ✅ **Scalable**: Database-level search & streaming for large datasets (NEW in v2.1)
## 📦 Installation
```
npm install waitlist-mailer
```
### For Database Support
Choose the storage adapter you need:
```
# For MongoDB
npm install mongoose
# For PostgreSQL
npm install sequelize pg
# For MySQL
npm install sequelize mysql2
# For SQLite
npm install sequelize better-sqlite3
```
## 🚀 Quick Start
### Minimal Setup (Default)
By default, `WaitlistManager` uses in-memory storage, perfect for rapid prototyping.
```
import { WaitlistManager } from 'waitlist-mailer';
// Defaults to MemoryStorage automatically
const manager = new WaitlistManager({
companyName: 'My App'
});
// Add someone to the waitlist
const result = await manager.join('user@example.com', {
name: 'John Doe',
source: 'Twitter'
});
console.log(result);
// Output: { success: true, message: 'Successfully joined...', email: 'user@example.com' }
```
To send emails, simply provide a mailer adapter.
```
import { WaitlistManager, NodemailerProvider } from 'waitlist-mailer';
const manager = new WaitlistManager({
// Storage defaults to MemoryStorage if not provided
mailer: new NodemailerProvider({
host: 'smtp.gmail.com',
port: 587,
user: 'your-email@gmail.com',
pass: 'your-app-password'
}),
companyName: 'My Startup'
});
// When users join, they'll automatically receive a confirmation email
await manager.join('alice@example.com');
```
For persistent storage, inject the Mongoose adapter.
```
import { WaitlistManager, MongooseStorage } from 'waitlist-mailer';
import mongoose from 'mongoose';
// Connect to MongoDB
await mongoose.connect('mongodb://localhost:27017/waitlist');
// Define schema
const schema = new mongoose.Schema({
email: { type: String, required: true, unique: true },
metadata: { type: mongoose.Schema.Types.Mixed },
createdAt: { type: Date, default: Date.now }
});
const WaitlistModel = mongoose.model('Waitlist', schema);
// Initialize manager
const manager = new WaitlistManager({
storage: new MongooseStorage({ model: WaitlistModel }),
companyName: 'My App'
});
```
**→** [**Complete Documentation Map**](./DOCS.md) Quick Links:
- [**API Reference**](./API.md) — Complete method documentation, event system, and type definitions
- [**Customization Guide**](./CUSTOMIZATION.md) — Email templates, custom adapters, and advanced examples
- [**Practical Examples**](./EXAMPLES.md) — Real-world scenarios: MVP setup, production patterns, campaigns
- [**Architecture**](./ARCHITECTURE.md) — Design patterns and extensibility
- [**Migration Guide**](./MIGRATION.md) — Upgrading from v1.x to v2.0
MIT License - see [LICENSE](./LICENSE) file for details.
Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/JuansesDev/waitlist-mailer).
- **Issues**: [GitHub Issues](https://github.com/JuansesDev/waitlist-mailer/issues)
- **Documentation**: See [DOCS.md](./DOCS.md) for complete reference
- **NPM**: [waitlist-mailer](https://www.npmjs.com/package/waitlist-mailer)
**Made with ❤️ by** [**JuansesDev**](https://github.com/JuansesDev)