@gravito/flare 3.3.0 → 4.0.1

package/dist/index.cjs

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,131 +30,445 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/types/middleware.ts
+var MiddlewarePriority;
+var init_middleware = __esm({
+  "src/types/middleware.ts"() {
+    "use strict";
+    MiddlewarePriority = {
+      /** 最高優先級：安全檢查 (100) */
+      SECURITY: 100,
+      /** 高優先級：限流 (80) */
+      RATE_LIMIT: 80,
+      /** 中等優先級：驗證 (50) */
+      VALIDATION: 50,
+      /** 預設優先級 (0) */
+      DEFAULT: 0,
+      /** 低優先級：日誌記錄 (-50) */
+      LOGGING: -50,
+      /** 最低優先級：監控 (-100) */
+      MONITORING: -100
+    };
+  }
+});
+
+// src/middleware/PreferenceMiddleware.ts
+var PreferenceMiddleware_exports = {};
+__export(PreferenceMiddleware_exports, {
+  PreferenceMiddleware: () => PreferenceMiddleware
+});
+var PreferenceMiddleware;
+var init_PreferenceMiddleware = __esm({
+  "src/middleware/PreferenceMiddleware.ts"() {
+    "use strict";
+    init_middleware();
+    PreferenceMiddleware = class {
+      /**
+       * Create a new PreferenceMiddleware instance.
+       *
+       * @param preferenceProvider - Optional preference provider; uses Notifiable method if not provided.
+       * @param logger - Optional logger instance for recording errors.
+       *
+       * @example
+       * ```typescript
+       * // Without provider (reads from Notifiable.getNotificationPreferences)
+       * const middleware = new PreferenceMiddleware();
+       *
+       * // Using database provider and logger
+       * const middleware = new PreferenceMiddleware(new DatabasePreferenceProvider(), logger);
+       * ```
+       */
+      constructor(preferenceProvider, logger) {
+        this.preferenceProvider = preferenceProvider;
+        this.logger = logger;
+      }
+      /**
+       * Middleware name.
+       */
+      name = "preference";
+      /**
+       * Middleware priority (medium priority for validation).
+       */
+      priority = MiddlewarePriority.VALIDATION;
+      /**
+       * Handle the notification and apply user preference filtering.
+       *
+       * Processes the notification and filters based on user preferences:
+       * 1. If notification type is in disabledNotifications, it is skipped.
+       * 2. If channel is in disabledChannels, it is skipped.
+       * 3. If enabledChannels is set, only channels in that list are allowed.
+       * 4. If preference loading fails, the notification is allowed as a fallback.
+       *
+       * @param notification - The notification to send.
+       * @param notifiable - The recipient.
+       * @param channel - The channel name.
+       * @param next - Callback to proceed to the next middleware or send operation.
+       * @returns A promise that resolves when processing is complete.
+       */
+      async handle(notification, notifiable, channel, next) {
+        try {
+          const preferences = await this.getPreferences(notifiable);
+          if (!preferences) {
+            await next();
+            return;
+          }
+          if (this.isNotificationDisabled(notification, preferences)) {
+            return;
+          }
+          if (!this.isChannelAllowed(channel, preferences)) {
+            return;
+          }
+          await next();
+        } catch (error) {
+          const errorMessage = `[PreferenceMiddleware] Failed to load preferences for ${notifiable.getNotifiableId()}, allowing notification to proceed:`;
+          if (this.logger) {
+            this.logger.error(errorMessage, error);
+          } else {
+            console.error(errorMessage, error);
+          }
+          await next();
+        }
+      }
+      /**
+       * Get user preferences from Notifiable or custom provider.
+       *
+       * Priority: Notifiable.getNotificationPreferences > preferenceProvider.
+       *
+       * @param notifiable - The recipient.
+       * @returns The user preferences or null if not found.
+       */
+      async getPreferences(notifiable) {
+        if (notifiable.getNotificationPreferences) {
+          const prefs = await notifiable.getNotificationPreferences();
+          return prefs || null;
+        }
+        if (this.preferenceProvider) {
+          const prefs = await this.preferenceProvider.getUserPreferences(notifiable);
+          return prefs || null;
+        }
+        return null;
+      }
+      /**
+       * Check if notification type is disabled by user.
+       *
+       * @param notification - The notification instance.
+       * @param preferences - User preferences.
+       * @returns True if the notification is disabled.
+       */
+      isNotificationDisabled(notification, preferences) {
+        const { disabledNotifications } = preferences;
+        if (!disabledNotifications || disabledNotifications.length === 0) {
+          return false;
+        }
+        const notificationName = notification.constructor.name;
+        return disabledNotifications.includes(notificationName);
+      }
+      /**
+       * Check if channel is allowed by user preferences.
+       *
+       * Priority:
+       * 1. disabledChannels (if listed, it is denied)
+       * 2. enabledChannels (if set, only listed are allowed)
+       * 3. Allow all if neither are set.
+       *
+       * @param channel - The channel name.
+       * @param preferences - User preferences.
+       * @returns True if the channel is allowed.
+       */
+      isChannelAllowed(channel, preferences) {
+        const { enabledChannels, disabledChannels } = preferences;
+        if (disabledChannels && disabledChannels.length > 0) {
+          if (disabledChannels.includes(channel)) {
+            return false;
+          }
+        }
+        if (enabledChannels && enabledChannels.length > 0) {
+          return enabledChannels.includes(channel);
+        }
+        if (enabledChannels !== void 0 && enabledChannels.length === 0) {
+          return false;
+        }
+        return true;
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AbortError: () => AbortError,
   BroadcastChannel: () => BroadcastChannel,
   DatabaseChannel: () => DatabaseChannel,
+  LazyNotification: () => LazyNotification,
   MailChannel: () => MailChannel,
+  MemoryStore: () => MemoryStore,
+  MiddlewarePriority: () => MiddlewarePriority,
   Notification: () => Notification,
   NotificationManager: () => NotificationManager,
   NotificationMetricsCollector: () => NotificationMetricsCollector,
   OrbitFlare: () => OrbitFlare,
+  PreferenceMiddleware: () => PreferenceMiddleware,
+  RateLimitMiddleware: () => RateLimitMiddleware,
   SlackChannel: () => SlackChannel,
   SmsChannel: () => SmsChannel,
   TemplatedNotification: () => TemplatedNotification,
+  TimeoutChannel: () => TimeoutChannel,
+  TimeoutError: () => TimeoutError,
+  TokenBucket: () => TokenBucket,
+  assertSerializable: () => assertSerializable,
+  checkSerializable: () => checkSerializable,
+  createHookEmitter: () => createHookEmitter,
+  deepDeserialize: () => deepDeserialize,
+  deepSerialize: () => deepSerialize,
   toPrometheusFormat: () => toPrometheusFormat
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/channels/TimeoutChannel.ts
+var TimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var AbortError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AbortError";
+  }
+};
+var TimeoutChannel = class {
+  constructor(inner, config) {
+    this.inner = inner;
+    this.config = config;
+  }
+  /**
+   * Sends a notification through the inner channel with a timeout guard.
+   *
+   * @param notification - The notification to send.
+   * @param notifiable - The recipient of the notification.
+   * @param options - Send options including an optional AbortSignal.
+   * @returns A promise that resolves when the notification is sent.
+   * @throws {TimeoutError} Thrown if the operation exceeds the configured timeout.
+   * @throws {AbortError} Thrown if the operation is aborted via the provided signal.
+   */
+  async send(notification, notifiable, options) {
+    if (this.config.timeout <= 0) {
+      if (this.config.onTimeout) {
+        this.config.onTimeout(this.inner.constructor.name, notification);
+      }
+      throw new TimeoutError(`Notification send timeout after ${this.config.timeout}ms`);
+    }
+    const controller = new AbortController();
+    const { signal } = controller;
+    if (options?.signal) {
+      if (options.signal.aborted) {
+        throw new AbortError("Request was aborted before sending");
+      }
+      options.signal.addEventListener("abort", () => {
+        controller.abort();
+      });
+    }
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        if (this.config.onTimeout) {
+          this.config.onTimeout(this.inner.constructor.name, notification);
+        }
+        controller.abort();
+        if (options?.signal?.aborted) {
+          reject(new AbortError("Request was aborted externally"));
+        } else {
+          reject(new TimeoutError(`Notification send timeout after ${this.config.timeout}ms`));
+        }
+      }, this.config.timeout);
+    });
+    const sendPromise = this.inner.send(notification, notifiable, { signal }).catch((error) => {
+      if (options?.signal?.aborted) {
+        throw new AbortError("Request was aborted externally");
+      }
+      if (signal.aborted) {
+        throw new TimeoutError(`Notification send timeout after ${this.config.timeout}ms`);
+      }
+      throw error;
+    });
+    return Promise.race([sendPromise, timeoutPromise]);
+  }
+};
+
 // src/channels/BroadcastChannel.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
 var BroadcastChannel = class {
-  constructor(broadcastService) {
+  constructor(broadcastService, config) {
     this.broadcastService = broadcastService;
+    this.config = config;
+    const innerChannel = {
+      send: async (notification, notifiable, _options) => {
+        if (!notification.toBroadcast) {
+          throw new Error("Notification does not implement toBroadcast method");
+        }
+        const broadcastNotification = notification.toBroadcast(notifiable);
+        const notifiableId = notifiable.getNotifiableId();
+        const notifiableType = notifiable.getNotifiableType?.() || "user";
+        const channel = `private-${notifiableType}.${notifiableId}`;
+        await this.broadcastService.broadcast(
+          channel,
+          broadcastNotification.type,
+          broadcastNotification.data
+        );
+      }
+    };
+    const timeout = this.config?.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.timeoutChannel = new TimeoutChannel(innerChannel, {
+      timeout,
+      onTimeout: this.config?.onTimeout
+    });
   }
-  async send(notification, notifiable) {
-    if (!notification.toBroadcast) {
-      throw new Error("Notification does not implement toBroadcast method");
-    }
-    const broadcastNotification = notification.toBroadcast(notifiable);
-    const notifiableId = notifiable.getNotifiableId();
-    const notifiableType = notifiable.getNotifiableType?.() || "user";
-    const channel = `private-${notifiableType}.${notifiableId}`;
-    await this.broadcastService.broadcast(
-      channel,
-      broadcastNotification.type,
-      broadcastNotification.data
-    );
+  timeoutChannel;
+  async send(notification, notifiable, options) {
+    return this.timeoutChannel.send(notification, notifiable, options);
   }
 };
 
 // src/channels/DatabaseChannel.ts
+var DEFAULT_TIMEOUT_MS2 = 1e4;
 var DatabaseChannel = class {
-  constructor(dbService) {
+  constructor(dbService, config) {
     this.dbService = dbService;
-  }
-  async send(notification, notifiable) {
-    if (!notification.toDatabase) {
-      throw new Error("Notification does not implement toDatabase method");
-    }
-    const dbNotification = notification.toDatabase(notifiable);
-    await this.dbService.insertNotification({
-      notifiableId: notifiable.getNotifiableId(),
-      notifiableType: notifiable.getNotifiableType?.() || "user",
-      type: dbNotification.type,
-      data: dbNotification.data
+    this.config = config;
+    const innerChannel = {
+      send: async (notification, notifiable, _options) => {
+        if (!notification.toDatabase) {
+          throw new Error("Notification does not implement toDatabase method");
+        }
+        const dbNotification = notification.toDatabase(notifiable);
+        await this.dbService.insertNotification({
+          notifiableId: notifiable.getNotifiableId(),
+          notifiableType: notifiable.getNotifiableType?.() || "user",
+          type: dbNotification.type,
+          data: dbNotification.data
+        });
+      }
+    };
+    const timeout = this.config?.timeout ?? DEFAULT_TIMEOUT_MS2;
+    this.timeoutChannel = new TimeoutChannel(innerChannel, {
+      timeout,
+      onTimeout: this.config?.onTimeout
     });
   }
+  timeoutChannel;
+  async send(notification, notifiable, options) {
+    return this.timeoutChannel.send(notification, notifiable, options);
+  }
 };
 
 // src/channels/MailChannel.ts
+var DEFAULT_TIMEOUT_MS3 = 3e4;
 var MailChannel = class {
-  constructor(mailService) {
+  constructor(mailService, config) {
     this.mailService = mailService;
+    this.config = config;
+    const innerChannel = {
+      send: async (notification, notifiable, _options) => {
+        if (!notification.toMail) {
+          throw new Error("Notification does not implement toMail method");
+        }
+        const message = notification.toMail(notifiable);
+        await this.mailService.send(message);
+      }
+    };
+    const timeout = this.config?.timeout ?? DEFAULT_TIMEOUT_MS3;
+    this.timeoutChannel = new TimeoutChannel(innerChannel, {
+      timeout,
+      onTimeout: this.config?.onTimeout
+    });
   }
-  async send(notification, notifiable) {
-    if (!notification.toMail) {
-      throw new Error("Notification does not implement toMail method");
-    }
-    const message = notification.toMail(notifiable);
-    await this.mailService.send(message);
+  timeoutChannel;
+  async send(notification, notifiable, options) {
+    return this.timeoutChannel.send(notification, notifiable, options);
   }
 };
 
 // src/channels/SlackChannel.ts
+var DEFAULT_TIMEOUT_MS4 = 3e4;
 var SlackChannel = class {
   constructor(config) {
     this.config = config;
-  }
-  async send(notification, notifiable) {
-    if (!notification.toSlack) {
-      throw new Error("Notification does not implement toSlack method");
-    }
-    const slackMessage = notification.toSlack(notifiable);
-    const response = await fetch(this.config.webhookUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        text: slackMessage.text,
-        channel: slackMessage.channel || this.config.defaultChannel,
-        username: slackMessage.username,
-        icon_emoji: slackMessage.iconEmoji,
-        attachments: slackMessage.attachments
-      })
+    const innerChannel = {
+      send: async (notification, notifiable, options) => {
+        if (!notification.toSlack) {
+          throw new Error("Notification does not implement toSlack method");
+        }
+        const slackMessage = notification.toSlack(notifiable);
+        const response = await fetch(this.config.webhookUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            text: slackMessage.text,
+            channel: slackMessage.channel || this.config.defaultChannel,
+            username: slackMessage.username,
+            icon_emoji: slackMessage.iconEmoji,
+            attachments: slackMessage.attachments
+          }),
+          signal: options?.signal
+          // Pass AbortSignal to fetch
+        });
+        if (!response.ok) {
+          throw new Error(`Failed to send Slack notification: ${response.statusText}`);
+        }
+      }
+    };
+    const timeout = this.config.timeout ?? DEFAULT_TIMEOUT_MS4;
+    this.timeoutChannel = new TimeoutChannel(innerChannel, {
+      timeout,
+      onTimeout: this.config.onTimeout
     });
-    if (!response.ok) {
-      throw new Error(`Failed to send Slack notification: ${response.statusText}`);
-    }
+  }
+  timeoutChannel;
+  async send(notification, notifiable, options) {
+    return this.timeoutChannel.send(notification, notifiable, options);
   }
 };
 
 // src/channels/SmsChannel.ts
+var DEFAULT_TIMEOUT_MS5 = 3e4;
 var SmsChannel = class {
   constructor(config) {
     this.config = config;
+    const innerChannel = {
+      send: async (notification, notifiable, options) => {
+        if (!notification.toSms) {
+          throw new Error("Notification does not implement toSms method");
+        }
+        const smsMessage = notification.toSms(notifiable);
+        switch (this.config.provider) {
+          case "twilio":
+            await this.sendViaTwilio(smsMessage, options?.signal);
+            break;
+          case "aws-sns":
+            await this.sendViaAwsSns(smsMessage, options?.signal);
+            break;
+          default:
+            throw new Error(`Unsupported SMS provider: ${this.config.provider}`);
+        }
+      }
+    };
+    const timeout = this.config.timeout ?? DEFAULT_TIMEOUT_MS5;
+    this.timeoutChannel = new TimeoutChannel(innerChannel, {
+      timeout,
+      onTimeout: this.config.onTimeout
+    });
   }
-  async send(notification, notifiable) {
-    if (!notification.toSms) {
-      throw new Error("Notification does not implement toSms method");
-    }
-    const smsMessage = notification.toSms(notifiable);
-    switch (this.config.provider) {
-      case "twilio":
-        await this.sendViaTwilio(smsMessage);
-        break;
-      case "aws-sns":
-        await this.sendViaAwsSns(smsMessage);
-        break;
-      default:
-        throw new Error(`Unsupported SMS provider: ${this.config.provider}`);
-    }
+  timeoutChannel;
+  async send(notification, notifiable, options) {
+    return this.timeoutChannel.send(notification, notifiable, options);
   }
   /**
-   * Send SMS via Twilio.
+   * Send SMS via Twilio with AbortSignal support.
    */
-  async sendViaTwilio(message) {
+  async sendViaTwilio(message, signal) {
     if (!this.config.apiKey || !this.config.apiSecret) {
       throw new Error("Twilio API key and secret are required");
     }
@@ -166,10 +483,12 @@ var SmsChannel = class {
           "Content-Type": "application/x-www-form-urlencoded"
         },
         body: new URLSearchParams({
-          From: this.config.from || "",
+          From: message.from || this.config.from || "",
           To: message.to,
           Body: message.message
-        })
+        }),
+        signal
+        // Pass AbortSignal to fetch
       }
     );
     if (!response.ok) {
@@ -178,9 +497,9 @@ var SmsChannel = class {
     }
   }
   /**
-   * Send SMS via AWS SNS.
+   * Send SMS via AWS SNS with AbortSignal support.
    */
-  async sendViaAwsSns(message) {
+  async sendViaAwsSns(message, signal) {
     let SNSClient;
     let PublishCommand;
     try {
@@ -216,7 +535,7 @@ var SmsChannel = class {
       }
     });
     try {
-      await client.send(command);
+      await client.send(command, { abortSignal: signal });
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       throw new Error(`Failed to send SMS via AWS SNS: ${err.message}`);
@@ -317,6 +636,338 @@ var NotificationMetricsCollector = class {
   }
 };
 
+// src/index.ts
+init_PreferenceMiddleware();
+
+// src/middleware/RateLimitMiddleware.ts
+init_middleware();
+
+// src/utils/TokenBucket.ts
+var TokenBucket = class {
+  /**
+   * 創建一個新的 TokenBucket 實例
+   *
+   * @param capacity - 桶的最大容量（tokens 上限）
+   * @param refillRate - 每秒補充的 tokens 數量
+   *
+   * @example
+   * ```typescript
+   * // 每秒最多 100 個請求
+   * const bucket = new TokenBucket(100, 100)
+   * ```
+   */
+  constructor(capacity, refillRate) {
+    this.capacity = capacity;
+    this.refillRate = refillRate;
+    this.tokens = capacity;
+    this.lastRefill = Date.now();
+  }
+  /**
+   * 當前可用的 tokens 數量
+   */
+  tokens;
+  /**
+   * 上次補充 tokens 的時間戳（毫秒）
+   */
+  lastRefill;
+  /**
+   * 嘗試從桶中消耗指定數量的 tokens
+   *
+   * 此方法會先執行 token 補充，然後檢查是否有足夠的 tokens。
+   * 如果有足夠的 tokens，則消耗並返回 true；否則返回 false 且不消耗。
+   *
+   * @param tokens - 要消耗的 tokens 數量（預設為 1）
+   * @returns 如果成功消耗則返回 true，否則返回 false
+   *
+   * @example
+   * ```typescript
+   * const bucket = new TokenBucket(10, 1)
+   *
+   * // 嘗試消耗 1 個 token
+   * if (bucket.tryConsume()) {
+   *   console.log('請求被允許')
+   * }
+   *
+   * // 嘗試消耗 3 個 tokens
+   * if (bucket.tryConsume(3)) {
+   *   console.log('批次請求被允許')
+   * }
+   * ```
+   */
+  tryConsume(tokens = 1) {
+    if (tokens <= 0) {
+      return true;
+    }
+    this.refill();
+    if (this.tokens >= tokens) {
+      this.tokens -= tokens;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * 獲取當前可用的 tokens 數量
+   *
+   * 此方法會先執行補充操作，然後返回當前的 tokens 數量。
+   *
+   * @returns 當前可用的 tokens 數量
+   *
+   * @example
+   * ```typescript
+   * const bucket = new TokenBucket(10, 1)
+   * console.log(`剩餘 ${bucket.getTokens()} 個 tokens`)
+   * ```
+   */
+  getTokens() {
+    this.refill();
+    return this.tokens;
+  }
+  /**
+   * 根據經過的時間補充 tokens
+   *
+   * 此方法計算自上次補充以來經過的時間，並根據 refillRate 補充相應數量的 tokens。
+   * tokens 數量不會超過容量上限。
+   *
+   * @private
+   */
+  refill() {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    if (elapsed <= 0 || this.refillRate <= 0) {
+      return;
+    }
+    const tokensToAdd = elapsed / 1e3 * this.refillRate;
+    if (tokensToAdd > 0) {
+      this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
+      this.lastRefill = now;
+    }
+  }
+};
+
+// src/middleware/RateLimitMiddleware.ts
+var SECONDS_PER_MINUTE = 60;
+var SECONDS_PER_HOUR = 3600;
+var DEFAULT_CLEANUP_INTERVAL_MS = 6e4;
+var MemoryStore = class {
+  cache = /* @__PURE__ */ new Map();
+  cleanupInterval;
+  constructor(cleanupIntervalMs = DEFAULT_CLEANUP_INTERVAL_MS) {
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [key, item] of this.cache.entries()) {
+        if (now > item.expiry) {
+          this.cache.delete(key);
+        }
+      }
+    }, cleanupIntervalMs);
+  }
+  async get(key) {
+    const item = this.cache.get(key);
+    if (!item) {
+      return null;
+    }
+    if (Date.now() > item.expiry) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item.value;
+  }
+  async put(key, value, ttl) {
+    this.cache.set(key, {
+      value,
+      expiry: Date.now() + ttl * 1e3
+    });
+  }
+  async forget(key) {
+    this.cache.delete(key);
+  }
+  /**
+   * 清理所有資源，停止清理計時器
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = void 0;
+    }
+    this.cache.clear();
+  }
+};
+var RateLimitMiddleware = class {
+  /**
+   * Create a new RateLimitMiddleware instance.
+   *
+   * @param config - Rate limit configuration for each channel
+   * @param store - Optional cache store for distributed rate limiting
+   *
+   * @example
+   * ```typescript
+   * // 使用預設記憶體儲存
+   * const middleware = new RateLimitMiddleware({
+   *   email: { maxPerSecond: 10 }
+   * })
+   *
+   * // 使用 Redis 儲存（分散式環境）
+   * const middleware = new RateLimitMiddleware({
+   *   email: { maxPerSecond: 10 }
+   * }, redisStore)
+   * ```
+   */
+  constructor(config, store) {
+    this.config = config;
+    this.store = store ?? new MemoryStore();
+    this.initializeBuckets();
+  }
+  /**
+   * Middleware name.
+   */
+  name = "rate-limit";
+  /**
+   * Middleware priority (high priority, executes early in the chain).
+   * 中介層優先級（高優先級，在鏈中較早執行）
+   */
+  priority = MiddlewarePriority.RATE_LIMIT;
+  /**
+   * Token buckets for each channel and time window.
+   * Key format: `{channel}:{window}` (e.g., 'email:second', 'sms:minute')
+   */
+  buckets = /* @__PURE__ */ new Map();
+  /**
+   * Cache store for distributed rate limiting.
+   * 分散式限流使用的快取儲存
+   */
+  store;
+  /**
+   * Initialize token buckets for all configured channels.
+   *
+   * 為所有配置的通道初始化 Token Bucket。
+   *
+   * @private
+   */
+  initializeBuckets() {
+    for (const [channel, limits] of Object.entries(this.config)) {
+      if (limits.maxPerSecond) {
+        const key = `${channel}:second`;
+        this.buckets.set(key, new TokenBucket(limits.maxPerSecond, limits.maxPerSecond));
+      }
+      if (limits.maxPerMinute) {
+        const key = `${channel}:minute`;
+        this.buckets.set(
+          key,
+          new TokenBucket(limits.maxPerMinute, limits.maxPerMinute / SECONDS_PER_MINUTE)
+        );
+      }
+      if (limits.maxPerHour) {
+        const key = `${channel}:hour`;
+        this.buckets.set(
+          key,
+          new TokenBucket(limits.maxPerHour, limits.maxPerHour / SECONDS_PER_HOUR)
+        );
+      }
+    }
+  }
+  /**
+   * Handle the notification and apply rate limiting.
+   *
+   * 處理通知並應用限流規則。如果超過任一時間窗口的限制，
+   * 將拋出錯誤阻止通知發送。
+   *
+   * @param notification - The notification being sent
+   * @param notifiable - The recipient
+   * @param channel - The channel name
+   * @param next - Continue to the next middleware or send the notification
+   *
+   * @throws {Error} 當超過限流時拋出錯誤
+   */
+  async handle(_notification, _notifiable, channel, next) {
+    const channelConfig = this.config[channel];
+    if (!channelConfig) {
+      await next();
+      return;
+    }
+    const windows = ["second", "minute", "hour"];
+    for (const window of windows) {
+      const key = `${channel}:${window}`;
+      const bucket = this.buckets.get(key);
+      if (bucket) {
+        const allowed = bucket.tryConsume();
+        if (!allowed) {
+          throw new Error(
+            `Rate limit exceeded for channel '${channel}' (${window}ly limit). Please try again later.`
+          );
+        }
+      }
+    }
+    await next();
+  }
+  /**
+   * Get current rate limit status for a channel.
+   *
+   * 獲取指定通道的當前限流狀態（用於除錯和監控）。
+   *
+   * @param channel - The channel name
+   * @returns Current token counts for each time window
+   *
+   * @example
+   * ```typescript
+   * const status = middleware.getStatus('email')
+   * console.log(`Email remaining: ${status.second}/${config.email.maxPerSecond}`)
+   * ```
+   */
+  getStatus(channel) {
+    const status = {};
+    const secondBucket = this.buckets.get(`${channel}:second`);
+    if (secondBucket) {
+      status.second = secondBucket.getTokens();
+    }
+    const minuteBucket = this.buckets.get(`${channel}:minute`);
+    if (minuteBucket) {
+      status.minute = minuteBucket.getTokens();
+    }
+    const hourBucket = this.buckets.get(`${channel}:hour`);
+    if (hourBucket) {
+      status.hour = hourBucket.getTokens();
+    }
+    return status;
+  }
+  /**
+   * Reset rate limit for a specific channel.
+   *
+   * 重置指定通道的限流計數（用於測試或手動重置）。
+   *
+   * @param channel - The channel name to reset
+   *
+   * @example
+   * ```typescript
+   * // 在測試中重置限流
+   * middleware.reset('email')
+   * ```
+   */
+  reset(channel) {
+    const channelConfig = this.config[channel];
+    if (!channelConfig) {
+      return;
+    }
+    if (channelConfig.maxPerSecond) {
+      const key = `${channel}:second`;
+      this.buckets.set(key, new TokenBucket(channelConfig.maxPerSecond, channelConfig.maxPerSecond));
+    }
+    if (channelConfig.maxPerMinute) {
+      const key = `${channel}:minute`;
+      this.buckets.set(
+        key,
+        new TokenBucket(channelConfig.maxPerMinute, channelConfig.maxPerMinute / SECONDS_PER_MINUTE)
+      );
+    }
+    if (channelConfig.maxPerHour) {
+      const key = `${channel}:hour`;
+      this.buckets.set(
+        key,
+        new TokenBucket(channelConfig.maxPerHour, channelConfig.maxPerHour / SECONDS_PER_HOUR)
+      );
+    }
+  }
+};
+
 // src/Notification.ts
 var Notification = class {
   /**
@@ -341,6 +992,15 @@ var Notification = class {
   }
 };
 
+// src/utils/hookEmitter.ts
+function createHookEmitter(core) {
+  return {
+    emit: async (event, payload) => {
+      await core.hooks.emit(event, payload);
+    }
+  };
+}
+
 // src/utils/retry.ts
 var DEFAULT_RETRY_OPTIONS = {
   maxAttempts: 3,
@@ -435,26 +1095,140 @@ function deepSerialize(obj, seen = /* @__PURE__ */ new WeakSet()) {
   }
   const result = {};
   for (const [key, value] of Object.entries(obj)) {
-    if (!key.startsWith("_") && typeof value !== "function") {
+    const isSpecialProperty = key.startsWith("__");
+    const isPrivateProperty = key.startsWith("_") && !isSpecialProperty;
+    if (!isPrivateProperty && typeof value !== "function") {
       result[key] = deepSerialize(value, seen);
     }
   }
   return result;
 }
+function deepDeserialize(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if ("__type" in obj) {
+    const typed = obj;
+    switch (typed.__type) {
+      case "Date":
+        return new Date(typed.value);
+      case "Map":
+        return new Map(
+          typed.value.map(([k, v]) => [
+            deepDeserialize(k),
+            deepDeserialize(v)
+          ])
+        );
+      case "Set":
+        return new Set(typed.value.map((v) => deepDeserialize(v)));
+    }
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => deepDeserialize(item));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = deepDeserialize(value);
+  }
+  return result;
+}
+
+// src/utils/serializationGuard.ts
+function checkSerializable(obj, path = "") {
+  const problematicPaths = [];
+  const warnings = [];
+  const seen = /* @__PURE__ */ new WeakSet();
+  function check(value, currentPath) {
+    if (value === null || value === void 0) {
+      return;
+    }
+    if (typeof value !== "object" && typeof value !== "function" && typeof value !== "symbol") {
+      return;
+    }
+    if (typeof value === "symbol") {
+      problematicPaths.push(currentPath);
+      warnings.push(`\u767C\u73FE\u4E0D\u53EF\u5E8F\u5217\u5316\u7684 Symbol \u65BC\u8DEF\u5F91: ${currentPath}`);
+      return;
+    }
+    if (typeof value === "function") {
+      problematicPaths.push(currentPath);
+      warnings.push(`\u767C\u73FE\u4E0D\u53EF\u5E8F\u5217\u5316\u7684 Function \u65BC\u8DEF\u5F91: ${currentPath}`);
+      return;
+    }
+    if (seen.has(value)) {
+      problematicPaths.push(currentPath);
+      warnings.push(`\u767C\u73FE\u5FAA\u74B0\u5F15\u7528\u65BC\u8DEF\u5F91: ${currentPath}`);
+      return;
+    }
+    seen.add(value);
+    if (value instanceof Date || value instanceof Map || value instanceof Set || value instanceof RegExp || value instanceof Error) {
+      return;
+    }
+    if (value instanceof Promise || value instanceof WeakMap || value instanceof WeakSet || value instanceof ArrayBuffer || value instanceof DataView || typeof Buffer !== "undefined" && value instanceof Buffer) {
+      problematicPaths.push(currentPath);
+      warnings.push(`\u767C\u73FE\u4E0D\u53EF\u5E8F\u5217\u5316\u7684 ${value.constructor.name} \u65BC\u8DEF\u5F91: ${currentPath}`);
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        const itemPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;
+        check(item, itemPath);
+      });
+      return;
+    }
+    for (const [key, val] of Object.entries(value)) {
+      if (key.startsWith("_")) {
+        continue;
+      }
+      const newPath = currentPath ? `${currentPath}.${key}` : key;
+      check(val, newPath);
+    }
+  }
+  check(obj, path);
+  return {
+    serializable: problematicPaths.length === 0,
+    problematicPaths,
+    warnings
+  };
+}
+function assertSerializable(obj) {
+  const result = checkSerializable(obj);
+  if (!result.serializable) {
+    throw new Error(
+      `\u7269\u4EF6\u5305\u542B\u4E0D\u53EF\u5E8F\u5217\u5316\u7684\u5C6C\u6027:
+\u554F\u984C\u8DEF\u5F91: ${result.problematicPaths.join(", ")}
+\u8A73\u7D30\u8CC7\u8A0A:
+${result.warnings.join("\n")}`
+    );
+  }
+}
 
 // src/NotificationManager.ts
 var NotificationManager = class {
   constructor(core) {
     this.core = core;
+    this.hookEmitter = createHookEmitter(core);
   }
   /**
    * Channel registry.
    */
   channels = /* @__PURE__ */ new Map();
+  /**
+   * Middleware stack for intercepting channel sends.
+   */
+  middlewares = [];
+  /**
+   * Indicates whether the middleware stack needs re-sorting.
+   */
+  middlewaresDirty = false;
   /**
    * Queue manager (optional, injected by `orbit-queue`).
    */
   queueManager;
+  /**
+   * Type-safe hook emitter for notification events.
+   */
+  hookEmitter;
   metrics;
   /**
    * Enable metrics collection.
@@ -483,6 +1257,30 @@ var NotificationManager = class {
   channel(name, channel) {
     this.channels.set(name, channel);
   }
+  /**
+   * Register a middleware for intercepting channel sends.
+   *
+   * Middleware will be executed in the order they are registered.
+   * Each middleware can modify, block, or monitor the notification flow.
+   *
+   * @param middleware - The middleware instance to register.
+   *
+   * @example
+   * ```typescript
+   * import { RateLimitMiddleware } from '@gravito/flare'
+   *
+   * const rateLimiter = new RateLimitMiddleware({
+   *   email: { maxPerSecond: 10 },
+   *   sms: { maxPerSecond: 5 }
+   * })
+   *
+   * manager.use(rateLimiter)
+   * ```
+   */
+  use(middleware) {
+    this.middlewares.push(middleware);
+    this.middlewaresDirty = true;
+  }
   /**
    * Register the queue manager (called by `orbit-queue`).
    *
@@ -508,13 +1306,13 @@ var NotificationManager = class {
   async send(notifiable, notification, options = {}) {
     const channels = notification.via(notifiable);
     const startTime = Date.now();
-    await this.core.hooks.emit("notification:sending", {
+    await this.hookEmitter.emit("notification:sending", {
       notification,
       notifiable,
       channels
     });
     if (notification.shouldQueue() && this.queueManager) {
-      await this.core.hooks.emit("notification:queued", {
+      await this.hookEmitter.emit("notification:queued", {
         notification,
         notifiable,
         channels
@@ -526,7 +1324,15 @@ var NotificationManager = class {
         notifiableId: notifiable.getNotifiableId(),
         notifiableType: notifiable.getNotifiableType?.() || "user",
         channels,
-        notificationData: this.serializeNotification(notification),
+        notificationData: (() => {
+          const checkResult = checkSerializable(notification);
+          if (!checkResult.serializable) {
+            this.core.logger.warn(
+              `[NotificationManager] Notification '${notification.constructor.name}' contains non-serializable properties. These will be filtered out during queuing. Problematic paths: ${checkResult.problematicPaths.join(", ")}. Advice: Use LazyNotification or keep only IDs/pure data in the constructor.`
+            );
+          }
+          return this.serializeNotification(notification);
+        })(),
         handle: async () => {
           await this.sendNow(notifiable, notification, channels);
         }
@@ -547,7 +1353,7 @@ var NotificationManager = class {
     }
     const results = await this.sendNow(notifiable, notification, channels, options);
     const totalDuration = Date.now() - startTime;
-    await this.core.hooks.emit("notification:sent", {
+    await this.hookEmitter.emit("notification:sent", {
       notification,
       notifiable,
       results,
@@ -580,7 +1386,7 @@ var NotificationManager = class {
     const { batchConcurrency = 10 } = options;
     const startTime = Date.now();
     const results = [];
-    await this.core.hooks.emit("notification:batch:start", {
+    await this.hookEmitter.emit("notification:batch:start", {
       notification,
       count: notifiables.length
     });
@@ -592,7 +1398,7 @@ var NotificationManager = class {
     }
     const duration = Date.now() - startTime;
     const successCount = results.filter((r) => r.allSuccess).length;
-    await this.core.hooks.emit("notification:batch:complete", {
+    await this.hookEmitter.emit("notification:batch:complete", {
       notification,
       total: notifiables.length,
       success: successCount,
@@ -710,7 +1516,7 @@ var NotificationManager = class {
                 `[NotificationManager] Channel '${channelName}' failed, retrying (${attempt}/${retry.maxAttempts}) in ${delay}ms`,
                 error
               );
-              this.core.hooks.emit("notification:channel:retry", {
+              this.hookEmitter.emit("notification:channel:retry", {
                 notification,
                 notifiable,
                 channel: channelName,
@@ -742,7 +1548,7 @@ var NotificationManager = class {
     } catch (error) {
       const duration = Date.now() - startTime;
       const err = error instanceof Error ? error : new Error(String(error));
-      await this.core.hooks.emit("notification:channel:failed", {
+      await this.hookEmitter.emit("notification:channel:failed", {
         notification,
         notifiable,
         channel: channelName,
@@ -772,20 +1578,76 @@ var NotificationManager = class {
     }
   }
   async executeChannelSend(channel, notification, notifiable, channelName) {
-    await this.core.hooks.emit("notification:channel:sending", {
+    await this.hookEmitter.emit("notification:channel:sending", {
       notification,
       notifiable,
       channel: channelName
     });
-    await channel.send(notification, notifiable);
+    const executeWithMiddleware = async () => {
+      await this.executeMiddlewareChain(0, notification, notifiable, channelName, async () => {
+        await channel.send(notification, notifiable);
+      });
+    };
+    await executeWithMiddleware();
     const duration = 0;
-    await this.core.hooks.emit("notification:channel:sent", {
+    await this.hookEmitter.emit("notification:channel:sent", {
       notification,
       notifiable,
       channel: channelName,
       duration
     });
   }
+  /**
+   * Retrieves the sorted list of middleware (Lazy sorting).
+   *
+   * Uses a lazy evaluation strategy: sorting only happens when needed to avoid
+   * overhead on every `use()` call.
+   * Sorting rules:
+   * 1. Higher priority (larger number) executes first.
+   * 2. Stable sort is maintained for identical priorities (registration order).
+   *
+   * @returns The sorted list of middleware.
+   * @private
+   */
+  getSortedMiddlewares() {
+    if (!this.middlewaresDirty) {
+      return this.middlewares;
+    }
+    this.middlewares.sort((a, b) => {
+      const priorityA = a.priority ?? 0;
+      const priorityB = b.priority ?? 0;
+      return priorityB - priorityA;
+    });
+    this.middlewaresDirty = false;
+    return this.middlewares;
+  }
+  /**
+   * Execute middleware chain recursively.
+   *
+   * @param index - Current middleware index
+   * @param notification - The notification being sent
+   * @param notifiable - The recipient
+   * @param channelName - The channel name
+   * @param finalHandler - The final handler to execute (actual channel.send)
+   * @private
+   */
+  async executeMiddlewareChain(index, notification, notifiable, channelName, finalHandler) {
+    const sortedMiddlewares = this.getSortedMiddlewares();
+    if (index >= sortedMiddlewares.length) {
+      await finalHandler();
+      return;
+    }
+    const middleware = sortedMiddlewares[index];
+    await middleware.handle(notification, notifiable, channelName, async () => {
+      await this.executeMiddlewareChain(
+        index + 1,
+        notification,
+        notifiable,
+        channelName,
+        finalHandler
+      );
+    });
+  }
   getRetryConfig(notification, options) {
     const notificationRetry = notification.retry;
     if (options === false || notificationRetry === void 0) {
@@ -904,6 +1766,7 @@ var OrbitFlare = class _OrbitFlare {
     if (this.options.enableSms) {
       this.setupSmsChannel(core, manager);
     }
+    this.setupMiddleware(core, manager);
     core.container.instance("notifications", manager);
     this.setupQueueIntegration(core, manager);
     core.logger.info("[OrbitFlare] Installed");
@@ -918,8 +1781,9 @@ var OrbitFlare = class _OrbitFlare {
   }
   setupDatabaseChannel(core, manager) {
     const db = core.container.make("db");
+    const config = this.options.channels?.database;
     if (db && this.isDatabaseService(db)) {
-      manager.channel("database", new DatabaseChannel(db));
+      manager.channel("database", new DatabaseChannel(db, config));
     } else {
       core.logger.warn(
         "[OrbitFlare] Database service not found or invalid, database channel disabled"
@@ -928,25 +1792,20 @@ var OrbitFlare = class _OrbitFlare {
   }
   setupBroadcastChannel(core, manager) {
     const broadcast = core.container.make("broadcast");
+    const config = this.options.channels?.broadcast;
     if (broadcast && this.isBroadcastService(broadcast)) {
-      manager.channel("broadcast", new BroadcastChannel(broadcast));
+      manager.channel("broadcast", new BroadcastChannel(broadcast, config));
     } else {
       core.logger.warn(
         "[OrbitFlare] Broadcast service not found or invalid, broadcast channel disabled"
       );
     }
   }
-  setupSlackChannel(core, manager) {
+  setupSlackChannel(_core, manager) {
     const slack = this.options.channels?.slack;
     if (slack) {
       manager.channel("slack", new SlackChannel(slack));
     }
-    if (this.options.enableSms) {
-      const sms = this.options.channels?.sms;
-      if (sms) {
-        manager.channel("sms", new SmsChannel(sms));
-      }
-    }
   }
   setupSmsChannel(core, manager) {
     const sms = this.options.channels?.sms;
@@ -966,6 +1825,19 @@ var OrbitFlare = class _OrbitFlare {
       });
     }
   }
+  setupMiddleware(core, manager) {
+    if (this.options.middleware) {
+      for (const middleware of this.options.middleware) {
+        manager.use(middleware);
+      }
+    }
+    if (this.options.enablePreference) {
+      const { PreferenceMiddleware: PreferenceMiddleware2 } = (init_PreferenceMiddleware(), __toCommonJS(PreferenceMiddleware_exports));
+      const preferenceMiddleware = new PreferenceMiddleware2(this.options.preferenceProvider);
+      manager.use(preferenceMiddleware);
+      core.logger.info("[OrbitFlare] Preference middleware enabled");
+    }
+  }
   isMailService(service) {
     return typeof service === "object" && service !== null && "send" in service && typeof service.send === "function";
   }
@@ -1019,17 +1891,84 @@ var TemplatedNotification = class extends Notification {
     throw new Error("Notifiable does not have an email property");
   }
 };
+
+// src/index.ts
+init_middleware();
+
+// src/utils/LazyNotification.ts
+var LazyNotification = class extends Notification {
+  /**
+   * 快取的資料
+   */
+  _cachedData;
+  /**
+   * 取得快取的資料
+   *
+   * @returns 快取的資料，如果尚未載入則回傳 undefined
+   */
+  getCached() {
+    return this._cachedData;
+  }
+  /**
+   * 設定快取資料
+   *
+   * @param data - 要快取的資料
+   */
+  setCached(data) {
+    this._cachedData = data;
+  }
+  /**
+   * 檢查資料是否已載入
+   *
+   * @returns 如果資料已快取則回傳 true
+   */
+  isLoaded() {
+    return this._cachedData !== void 0;
+  }
+  /**
+   * 清除快取
+   */
+  clearCache() {
+    this._cachedData = void 0;
+  }
+  /**
+   * 載入資料並快取（如果尚未載入）
+   *
+   * @param notifiable - 通知接收者
+   * @returns 載入的資料
+   */
+  async ensureLoaded(notifiable) {
+    if (this._cachedData === void 0) {
+      this._cachedData = await this.loadData(notifiable);
+    }
+    return this._cachedData;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AbortError,
   BroadcastChannel,
   DatabaseChannel,
+  LazyNotification,
   MailChannel,
+  MemoryStore,
+  MiddlewarePriority,
   Notification,
   NotificationManager,
   NotificationMetricsCollector,
   OrbitFlare,
+  PreferenceMiddleware,
+  RateLimitMiddleware,
   SlackChannel,
   SmsChannel,
   TemplatedNotification,
+  TimeoutChannel,
+  TimeoutError,
+  TokenBucket,
+  assertSerializable,
+  checkSerializable,
+  createHookEmitter,
+  deepDeserialize,
+  deepSerialize,
   toPrometheusFormat
 });