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.
263 lines (167 loc) • 5.88 kB
Markdown
# WaitlistMailer API Reference
Complete API documentation for `WaitlistManager` and all methods.
## Table of Contents
- [WaitlistManager](#waitlistmanager-class)
- [Methods](#methods)
- [Event System](#event-system)
- [Storage Providers](#storage-providers)
- [Mail Providers](#mail-providers)
- [Type Definitions](#type-definitions)
## WaitlistManager Class
The main orchestrator class (generic for custom metadata types).
### Constructor
```
new WaitlistManager<T>(config: WaitlistManagerConfig<T>)
```
**Configuration Options:**
```
interface WaitlistManagerConfig<T = any> {
storage?: StorageProvider<T>; // Optional: defaults to MemoryStorage
mailer?: MailProvider; // Optional: mail provider
companyName: string; // Required: displayed in emails
autoConnect?: boolean; // Optional: auto-initialize (default: true)
}
```
## Methods
### `async join(email: string, metadata?: T): Promise<JoinResult>`
Add an email to the waitlist with optional metadata.
**Parameters:**
- `email` (string): Email address to add
- `metadata?` (T): Custom metadata object
**Returns:**
```
interface JoinResult {
success: boolean;
message: string;
email: string;
}
```
### `async leave(email: string): Promise<boolean>`
Remove an email from the waitlist.
**Parameters:**
- `email` (string): Email address to remove
**Returns:** `boolean` - True if removed, false if not found
### `async has(email: string): Promise<boolean>`
Check if an email exists in the waitlist.
### `async getAll(): Promise<WaitlistEntry<T>[]>`
Get all waitlist entries.
### `async count(): Promise<number>`
Get total count of waitlist entries.
### `async clear(): Promise<boolean>`
Remove all entries from the waitlist.
### `async search(pattern: string, options?: SearchOptions): Promise<WaitlistEntry<T>[]>`
Search for entries matching a pattern. Delegates to the storage provider for efficient database-level filtering when available.
**Parameters:**
- `pattern` (string): Pattern to search for (partial email match)
- `options?` (SearchOptions): Optional search configuration
**SearchOptions:**
```typescript
interface SearchOptions {
limit?: number; // Maximum number of results
offset?: number; // Number of results to skip (pagination)
caseInsensitive?: boolean; // Case-insensitive matching (default: true)
}
```
**Example:**
```typescript
// Simple search
const gmailUsers = await manager.search('gmail.com');
// Paginated search
const page1 = await manager.search('example', { limit: 10, offset: 0 });
const page2 = await manager.search('example', { limit: 10, offset: 10 });
```
### `async sendEmail(email: string, context: EmailContext): Promise<boolean>`
Send a custom email to an address.
**Parameters:**
- `email` (string): Recipient email
- `context` (EmailContext): Email content and metadata
### `async sendBulkEmails(contextBuilder: Function, concurrency?: number): Promise<BulkEmailResult>`
Send emails to all waitlist members with configurable concurrency.
**Parameters:**
- `contextBuilder` (Function): Function that builds email context for each entry
- `concurrency?` (number): Number of concurrent emails to send (default: 5)
## Event System
The manager extends `EventEmitter` and emits rich events for integrations and monitoring.
### Available Events
- `join:success`
- `join:duplicate`
- `join:validation-error`
- `leave:success`
- `leave:not-found`
- `mailer:sent`
- `mailer:failed`
- `bulk:start`
- `bulk:progress`
- `bulk:complete`
- `error`
## Storage Providers
### StorageProvider Interface
All storage adapters implement this interface:
```typescript
interface StorageProvider<T = any> {
connect?(): Promise<void>; // Optional: connect to storage
add(email: string, data?: T): Promise<void>;
remove(email: string): Promise<boolean>;
exists(email: string): Promise<boolean>;
getAll(): Promise<WaitlistEntry<T>[]>;
count(): Promise<number>;
clear(): Promise<void>;
disconnect?(): Promise<void>; // Optional: disconnect from storage
// NEW: Optimized methods for large datasets
search?(pattern: string, options?: SearchOptions): Promise<WaitlistEntry<T>[]>;
iterate?(batchSize?: number): AsyncIterableIterator<WaitlistEntry<T>>;
}
```
### SearchOptions
```typescript
interface SearchOptions {
limit?: number; // Maximum number of results
offset?: number; // Number of results to skip
caseInsensitive?: boolean; // Case-insensitive matching (default: true)
}
```
### Streaming with `iterate()`
For processing large datasets without loading everything into memory:
```typescript
// Process all entries without memory issues
for await (const entry of storage.iterate(100)) {
console.log(entry.email);
}
```
## Mail Providers
### MailProvider Interface
All mail adapters implement this interface:
```
interface MailProvider {
sendConfirmation(email: string, context: EmailContext): Promise<boolean>;
verify?(): Promise<boolean>;
}
```
## Type Definitions
### WaitlistEntry<T>
```typescript
interface WaitlistEntry<T = any> {
email: string;
metadata?: T;
createdAt: Date;
}
```
### SearchOptions
```typescript
interface SearchOptions {
limit?: number; // Maximum number of results to return
offset?: number; // Number of results to skip (for pagination)
caseInsensitive?: boolean; // Whether to use case-insensitive matching (default: true)
}
```
### BulkEmailResult
```typescript
interface BulkEmailResult {
sent: number; // Number of emails sent successfully
failed: number; // Number of emails that failed to send
total: number; // Total number of emails attempted
}
```
---
**Version**: 2.1.0
**Last Updated**: November 25, 2025