waitlist-mailer/lib/adapters/storage/MongooseStorage.ts

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.

/**
 * MongoDB Mongoose storage adapter for waitlist-mailer.
 * Provides persistent storage using Mongoose ODM.
 * Requires: mongoose peer dependency
 */

import { StorageProvider, WaitlistEntry, SearchOptions } from '../../types';

export interface MongooseStorageConfig {
  /** Mongoose model instance */
  model: any;
  /** Whether to use lowercase for email normalization */
  normalizeEmail?: boolean;
}

/**
 * Mongoose-based storage provider implementation.
 * Requires mongoose to be installed separately.
 * @template T - Optional metadata type
 */
export class MongooseStorage<T = any> implements StorageProvider<T> {
  private model: any;
  private normalizeEmail: boolean;

  /**
   * Create a new MongooseStorage instance.
   * @param config - Configuration object with mongoose model
   * @throws {Error} If mongoose is not installed or model is invalid
   */
  constructor(config: MongooseStorageConfig) {
    // Verify mongoose is available
    try {
      if (!config.model) {
        throw new Error('Mongoose model is required. Please provide a valid Mongoose model instance.');
      }
      
      if (!config.model.collection) {
        throw new Error('Invalid Mongoose model. Make sure you\'re passing a compiled Mongoose model.');
      }
    } catch (error: any) {
      if (error.message.includes('Mongoose') || error.message.includes('model')) {
        throw error;
      }
      throw new Error(
        'MongooseStorage requires mongoose to be installed. ' +
        'Install it with: npm install mongoose'
      );
    }

    this.model = config.model;
    this.normalizeEmail = config.normalizeEmail ?? true;
  }

  private normalizeEmailAddress(email: string): string {
    return this.normalizeEmail ? email.toLowerCase() : email;
  }

  /**
   * Add an email to MongoDB.
   * @param email - The email to add
   * @param data - Optional metadata
   * @throws {Error} If the email already exists or database operation fails
   */
  async add(email: string, data?: T): Promise<void> {
    const normalized = this.normalizeEmailAddress(email);
    const existingDoc = await this.model.findOne({ email: normalized }).exec();

    if (existingDoc) {
      throw new Error(`Email already exists: ${email}`);
    }

    try {
      await this.model.create({
        email: normalized,
        metadata: data,
        createdAt: new Date(),
      });
    } catch (error: any) {
      if (error.code === 11000) {
        throw new Error(`Email already exists: ${email}`);
      }
      throw error;
    }
  }

  /**
   * Remove an email from MongoDB.
   * @param email - The email to remove
   * @returns true if the email was found and removed
   */
  async remove(email: string): Promise<boolean> {
    const normalized = this.normalizeEmailAddress(email);
    const result = await this.model.deleteOne({ email: normalized }).exec();
    return result.deletedCount > 0;
  }

  /**
   * Check if an email exists in MongoDB.
   * @param email - The email to check
   * @returns true if the email exists
   */
  async exists(email: string): Promise<boolean> {
    const normalized = this.normalizeEmailAddress(email);
    const count = await this.model.countDocuments({ email: normalized }).exec();
    return count > 0;
  }

  /**
   * Retrieve all entries from MongoDB.
   * @returns Array of all WaitlistEntry objects
   */
  async getAll(): Promise<WaitlistEntry<T>[]> {
    const docs = await this.model.find().lean().exec();
    return docs.map((doc: any) => ({
      email: doc.email,
      metadata: doc.metadata,
      createdAt: doc.createdAt,
    }));
  }

  /**
   * Count total entries in MongoDB.
   * @returns Number of entries
   */
  async count(): Promise<number> {
    return this.model.countDocuments().exec();
  }

  /**
   * Clear all entries from MongoDB.
   */
  async clear(): Promise<void> {
    await this.model.deleteMany({}).exec();
  }

  /**
   * Search entries by email pattern using MongoDB $regex.
   * Delegates filtering to MongoDB for optimal performance.
   * @param pattern - The pattern to search for
   * @param options - Optional search options
   * @returns Matching entries
   */
  async search(pattern: string, options: SearchOptions = {}): Promise<WaitlistEntry<T>[]> {
    const { limit, offset = 0, caseInsensitive = true } = options;
    
    // Use MongoDB $regex for efficient server-side filtering
    // Escape special regex characters in the pattern
    const escapedPattern = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
    const regexOptions = caseInsensitive ? 'i' : '';
    
    let query = this.model.find({
      email: { $regex: escapedPattern, $options: regexOptions }
    });

    if (offset > 0) {
      query = query.skip(offset);
    }
    if (limit !== undefined && limit > 0) {
      query = query.limit(limit);
    }

    const docs = await query.lean().exec();
    return docs.map((doc: any) => ({
      email: doc.email,
      metadata: doc.metadata,
      createdAt: doc.createdAt,
    }));
  }

  /**
   * Iterate over entries using MongoDB cursor for memory-efficient streaming.
   * Uses Mongoose cursor to avoid loading all documents into memory.
   * @param batchSize - Number of entries per batch (default: 100)
   */
  async *iterate(batchSize: number = 100): AsyncIterableIterator<WaitlistEntry<T>> {
    const cursor = this.model.find().lean().batchSize(batchSize).cursor();
    
    for await (const doc of cursor) {
      yield {
        email: doc.email,
        metadata: doc.metadata,
        createdAt: doc.createdAt,
      };
    }
  }
}