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.
348 lines (236 loc) • 11 kB
Markdown
# 📚 WaitlistMailer Documentation Map
**Complete guide to everything in this library.** Choose your path based on your needs.
## 🚀 I'm New — Where Do I Start?
**Your journey in 3 steps:**
1. **[README.md](./readme.md)** (10 min)
- What is this library?
- How do I install it?
- Show me 4 quick examples
2. **[EXAMPLES.md](./EXAMPLES.md)** (30-60 min)
- Pick your scenario: MVP / Production / MongoDB / PostgreSQL
- See complete working code
- Understand email templates
- Learn about database setup
3. **[API.md](./API.md)** (Reference, as needed)
- Bookmark this for all method details
- Understand events and types
- Reference while coding
## 📋 Documentation by Use Case
### I Want to Build an MVP Quickly
**Time: 15 minutes**
1. [README Quick Start](./readme.md#-quick-start) - Minimal in-memory setup
2. [EXAMPLES: Simple In-Memory Waitlist](./EXAMPLES.md#example-1-simple-in-memory-waitlist-for-mvp)
3. [API: join() method](./API.md#async-joinemail-string-metadata-t-promisejoinresult)
**Result:** Waitlist running locally with 20 lines of code
### I Need MongoDB in Production
**Time: 45 minutes**
1. [README: With MongoDB](./readme.md#with-mongodb) - Understand the setup
2. [EXAMPLES: Production MongoDB Setup](./EXAMPLES.md#example-2-production-mongodb-setup)
3. [API.md Storage Providers](./API.md#storage-providers) - Reference as needed
**Result:** MongoDB-backed production waitlist with email
### I Need PostgreSQL / MySQL
**Time: 45 minutes**
1. [README: With PostgreSQL/MySQL](./readme.md#with-postgressqlmysql) - See the pattern
2. [EXAMPLES: PostgreSQL with Sequelize](./EXAMPLES.md#example-3-postgresql-with-sequelize)
3. [API.md Storage Providers](./API.md#storage-providers) - Reference
**Result:** SQL database integration with proper schema
### I Want to Send Custom Emails
**Time: 20-30 minutes**
1. [CUSTOMIZATION: Email Customization](./CUSTOMIZATION.md#email-customization)
- Option 1: Simple HTML
- Option 2: Handlebars templates
- Option 3: Other template engines
- Option 4: Dynamic bulk emails
2. [EXAMPLES: Custom Welcome Email](./EXAMPLES.md#example-1-custom-welcome-email-with-template)
3. [EXAMPLES: Segmented Bulk Campaign](./EXAMPLES.md#example-2-segmented-bulk-email-campaign)
**Result:** Beautiful templated emails with dynamic content
### I Want to Send Bulk Emails Efficiently
**Time: 15 minutes**
1. [API: sendBulkEmails()](./API.md#async-sendbulkemailscontextbuilder-function-concurrency-number-promisebulkemailresult)
- Understand concurrency parameter (1, 5, Infinity)
2. [EXAMPLES: Bulk Email Campaign](./EXAMPLES.md#example-2-segmented-bulk-email-campaign)
3. [EXAMPLES: Scheduled Campaign with Cron](./EXAMPLES.md#example-4-scheduled-campaign-with-cron)
**Result:** Send 10,000+ emails without blocking
### I Want to Build a Custom Adapter
**Time: 60-90 minutes**
1. [CUSTOMIZATION: Custom Storage Adapters](./CUSTOMIZATION.md#custom-storage-adapters)
- See Redis, Firestore, DynamoDB examples
2. [CUSTOMIZATION: Custom Mail Providers](./CUSTOMIZATION.md#custom-mail-providers)
- See Sendgrid, Mailgun, Webhook examples
3. [API.md Storage/Mail Interfaces](./API.md#storage-providers) - Understand the contracts
4. [ARCHITECTURE.md: Adapter Pattern](./ARCHITECTURE.md) - Deep dive into design
**Result:** Custom adapter for your specific needs (Redis, Firestore, etc.)
### I'm Migrating from v1.x
**Time: 30-45 minutes**
1. [MIGRATION.md](./MIGRATION.md) - See what changed
2. [README: Best Practices](./readme.md#-best-practices) - Learn new patterns
3. [EXAMPLES: Complete Flow](./EXAMPLES.md#complete-flow-from-signup-to-campaign) - See it all together
**Result:** Successful v1 → v2 migration
### I Want to Monitor & Debug
**Time: 30-45 minutes**
1. [API.md: Event System](./API.md#event-system) - See all available events
2. [EXAMPLES: Event Integration](./EXAMPLES.md#event-integration)
- Slack notifications
- Analytics tracking
3. [EXAMPLES: Production Patterns](./EXAMPLES.md#production-patterns)
- Health checks
- Prometheus metrics
- Error handling
**Result:** Full observability for your waitlist
## 📚 Complete Documentation Reference
### Core Guides
| Document | Purpose | Length | When to Read |
|----------|---------|--------|--------------|
| **[README.md](./readme.md)** | Quick overview and getting started | 215 lines | First thing, always |
| **[EXAMPLES.md](./EXAMPLES.md)** | Real-world working code for your scenario | 400+ lines | To see practical implementations |
| **[API.md](./API.md)** | Complete method reference with examples | 831 lines | While coding, as reference |
| **[CUSTOMIZATION.md](./CUSTOMIZATION.md)** | Custom adapters, templates, extensions | 762 lines | When building custom solutions |
### Architecture & Standards
| Document | Purpose |
|----------|---------|
| **[ARCHITECTURE.md](./ARCHITECTURE.md)** | Design patterns, component interactions, future roadmap |
| **[MIGRATION.md](./MIGRATION.md)** | Upgrading from v1.x to v2.0 with comparison tables |
| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | How to contribute code and improve the library |
| **[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)** | Community guidelines |
| **[SECURITY.md](./SECURITY.md)** | How to report vulnerabilities |
## 🎯 Quick Reference: Common Tasks
### Task: Add someone to waitlist
```typescript
const result = await manager.join('user@example.com', { name: 'John' });
```
**Details:** [API.md join()](./API.md#async-joinemail-string-metadata-t-promisejoinresult)
### Task: Send email to one person
```typescript
await manager.sendEmail('user@example.com', {
subject: 'Special Offer',
customHtml: '<h1>50% Off!</h1>'
});
```
**Details:** [API.md sendEmail()](./API.md#async-sendemailemail-string-context-emailcontext-promiseboolean)
### Task: Send bulk email to everyone
```typescript
const result = await manager.sendBulkEmails(
(email, metadata) => ({
subject: `Hi ${metadata?.name}!`,
customHtml: '<p>Check this out!</p>'
}),
5 // concurrency: 5 at a time
);
```
**Details:** [API.md sendBulkEmails()](./API.md#async-sendbulkemailscontextbuilder-function-concurrency-number-promisebulkemailresult)
### Task: Track user actions
```typescript
manager.on('join:success', ({ email, metadata }) => {
console.log(`${email} joined!`);
});
```
**Details:** [API.md Event System](./API.md#event-system) | [EXAMPLES.md Event Integration](./EXAMPLES.md#event-integration)
### Task: Export all emails to CSV
```typescript
const entries = await manager.getAll();
const csv = entries.map(e => e.email).join('\n');
```
**Details:** [API.md getAll()](./API.md#async-getall-promisewaitlistentryt) | [EXAMPLES.md Search & Export](./EXAMPLES.md#example-1-search-and-export-users)
### Task: Setup with database
- **MongoDB:** [README](./readme.md#with-mongodb) | [EXAMPLES](./EXAMPLES.md#example-2-production-mongodb-setup)
- **PostgreSQL:** [README](./readme.md#with-postgressqlmysql) | [EXAMPLES](./EXAMPLES.md#example-3-postgresql-with-sequelize)
- **In-Memory:** [README Quick Start](./readme.md#minimal-setup-in-memory)
### Task: Send templated emails
- **Simple HTML:** [CUSTOMIZATION Option 1](./CUSTOMIZATION.md#option-1-simple-html-string)
- **Handlebars:** [CUSTOMIZATION Option 2](./CUSTOMIZATION.md#option-2-handlebars-templates)
- **Dynamic bulk:** [CUSTOMIZATION Option 4](./CUSTOMIZATION.md#option-4-bulk-email-with-dynamic-templates) | [EXAMPLES](./EXAMPLES.md#example-2-segmented-bulk-email-campaign)
### Task: Handle errors
```typescript
manager.on('error', ({ context, error }) => {
console.error(`Error in ${context}:`, error);
});
```
**Details:** [API.md error event](./API.md#error) | [EXAMPLES Error Notification](./EXAMPLES.md#example-2-error-notification-with-slack)
## 🤔 FAQ
**Q: Where do I find examples?**
A: [EXAMPLES.md](./EXAMPLES.md) - has MVP, production, campaigns, monitoring, and more
**Q: How do I customize emails?**
A: [CUSTOMIZATION.md Email section](./CUSTOMIZATION.md#email-customization) - 4 options from simple to complex
**Q: What databases are supported?**
A: MongoDB (Mongoose), PostgreSQL/MySQL (Sequelize), SQLite, Redis, Firestore, DynamoDB - see [EXAMPLES.md](./EXAMPLES.md)
**Q: How do I track events?**
A: [API.md Event System](./API.md#event-system) - or [EXAMPLES.md Event Integration](./EXAMPLES.md#event-integration) for real-world patterns
**Q: Can I use this in production?**
A: Yes! See [EXAMPLES.md Production Patterns](./EXAMPLES.md#production-patterns) for health checks, graceful shutdown, monitoring
**Q: I'm coming from v1.x**
A: See [MIGRATION.md](./MIGRATION.md) for what changed and how to upgrade
## 🗺️ Documentation Architecture
```
README.md
├─ Quick overview (new users start here)
├─ Link to EXAMPLES.md (pick your scenario)
├─ Link to API.md (detailed reference)
└─ Link to others
EXAMPLES.md
├─ Complete setup examples (MVP, Production, MongoDB, PostgreSQL)
├─ Email workflows (templates, bulk, segmented)
├─ Database management (search, cleanup, analytics)
├─ Event integration (analytics, error tracking, monitoring)
└─ Production patterns (health checks, graceful shutdown, prometheus)
API.md
├─ WaitlistManager class and all methods
├─ Event system with all events
├─ Storage providers (interfaces and built-in)
├─ Mail providers (interfaces and built-in)
└─ Type definitions
CUSTOMIZATION.md
├─ Email customization (4 options)
├─ Custom storage adapters (Redis, Firestore, DynamoDB)
├─ Custom mail providers (Sendgrid, Mailgun, Webhooks)
├─ TypeScript generics
└─ Advanced examples
ARCHITECTURE.md
├─ Design patterns (Adapter, DI)
├─ Component interactions
└─ Future roadmap
MIGRATION.md
└─ v1.x → v2.0 upgrade guide
Other
├─ CONTRIBUTING.md (how to contribute)
├─ CODE_OF_CONDUCT.md (community rules)
└─ SECURITY.md (vulnerability reporting)
```
## ✅ Verification Checklist
Use this to verify you have everything you need:
- [ ] I understand the basic concept (README)
- [ ] I've seen my use case in examples (EXAMPLES)
- [ ] I can call the main methods (API)
- [ ] I can customize what I need (CUSTOMIZATION)
- [ ] I understand the architecture (ARCHITECTURE)
- [ ] I can handle errors and events (API events section)
- [ ] I can run it in production (EXAMPLES production patterns)
- [ ] I know how to extend it (ARCHITECTURE + CUSTOMIZATION)
If you checked everything, **you're ready to use WaitlistMailer! 🚀**
## 📞 Need Help?
- **Questions about usage?** Check the relevant guide above
- **Found a bug?** [GitHub Issues](https://github.com/JuansesDev/waitlist-mailer/issues)
- **Security concern?** See [SECURITY.md](./SECURITY.md)
- **Want to contribute?** See [CONTRIBUTING.md](./CONTRIBUTING.md)
Happy building! 💙