@gravito/constellation 3.0.1 → 3.1.0

package/dist/index.cjs

@@ -30,6 +30,49 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/utils/Compression.ts
+async function compressToBuffer(source, config) {
+  const level = config?.level ?? 6;
+  if (level < 1 || level > 9) {
+    throw new Error(`Invalid compression level: ${level}. Must be between 1 and 9.`);
+  }
+  const chunks = [];
+  const gzip = (0, import_node_zlib.createGzip)({ level });
+  const readable = import_node_stream.Readable.from(source, { encoding: "utf-8" });
+  try {
+    readable.pipe(gzip);
+    for await (const chunk of gzip) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  } catch (error) {
+    readable.destroy();
+    gzip.destroy();
+    throw error;
+  }
+}
+function createCompressionStream(config) {
+  const level = config?.level ?? 6;
+  if (level < 1 || level > 9) {
+    throw new Error(`Invalid compression level: ${level}. Must be between 1 and 9.`);
+  }
+  return (0, import_node_zlib.createGzip)({ level });
+}
+function toGzipFilename(filename) {
+  return filename.endsWith(".gz") ? filename : `${filename}.gz`;
+}
+function fromGzipFilename(filename) {
+  return filename.endsWith(".gz") ? filename.slice(0, -3) : filename;
+}
+var import_node_stream, import_node_zlib;
+var init_Compression = __esm({
+  "src/utils/Compression.ts"() {
+    "use strict";
+    import_node_stream = require("stream");
+    import_node_zlib = require("zlib");
+  }
+});
+
 // src/storage/DiskSitemapStorage.ts
 var DiskSitemapStorage_exports = {};
 __export(DiskSitemapStorage_exports, {
@@ -50,22 +93,61 @@ function sanitizeFilename(filename) {
   }
   return filename;
 }
-var import_promises, import_node_path, DiskSitemapStorage;
+var import_node_fs, import_promises, import_node_path, import_node_stream2, import_promises2, DiskSitemapStorage;
 var init_DiskSitemapStorage = __esm({
   "src/storage/DiskSitemapStorage.ts"() {
     "use strict";
+    import_node_fs = require("fs");
     import_promises = __toESM(require("fs/promises"), 1);
     import_node_path = __toESM(require("path"), 1);
+    import_node_stream2 = require("stream");
+    import_promises2 = require("stream/promises");
+    init_Compression();
     DiskSitemapStorage = class {
       constructor(outDir, baseUrl) {
         this.outDir = outDir;
         this.baseUrl = baseUrl;
       }
+      /**
+       * Writes sitemap content to a file on the local disk.
+       *
+       * @param filename - The name of the file to write.
+       * @param content - The XML or JSON content.
+       */
       async write(filename, content) {
         const safeName = sanitizeFilename(filename);
         await import_promises.default.mkdir(this.outDir, { recursive: true });
         await import_promises.default.writeFile(import_node_path.default.join(this.outDir, safeName), content);
       }
+      /**
+       * 使用串流方式寫入 sitemap 檔案，可選擇性啟用 gzip 壓縮。
+       * 此方法可大幅降低大型 sitemap 的記憶體峰值。
+       *
+       * @param filename - 檔案名稱
+       * @param stream - XML 內容的 AsyncIterable
+       * @param options - 寫入選項（如壓縮、content type）
+       *
+       * @since 3.1.0
+       */
+      async writeStream(filename, stream, options) {
+        const safeName = sanitizeFilename(options?.compress ? toGzipFilename(filename) : filename);
+        await import_promises.default.mkdir(this.outDir, { recursive: true });
+        const filePath = import_node_path.default.join(this.outDir, safeName);
+        const writeStream = (0, import_node_fs.createWriteStream)(filePath);
+        const readable = import_node_stream2.Readable.from(stream, { encoding: "utf-8" });
+        if (options?.compress) {
+          const gzip = createCompressionStream();
+          await (0, import_promises2.pipeline)(readable, gzip, writeStream);
+        } else {
+          await (0, import_promises2.pipeline)(readable, writeStream);
+        }
+      }
+      /**
+       * Reads sitemap content from a file on the local disk.
+       *
+       * @param filename - The name of the file to read.
+       * @returns A promise resolving to the file content as a string, or null if not found.
+       */
       async read(filename) {
         try {
           const safeName = sanitizeFilename(filename);
@@ -74,6 +156,29 @@ var init_DiskSitemapStorage = __esm({
           return null;
         }
       }
+      /**
+       * Returns a readable stream for a sitemap file on the local disk.
+       *
+       * @param filename - The name of the file to stream.
+       * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+       */
+      async readStream(filename) {
+        try {
+          const safeName = sanitizeFilename(filename);
+          const fullPath = import_node_path.default.join(this.outDir, safeName);
+          await import_promises.default.access(fullPath);
+          const stream = (0, import_node_fs.createReadStream)(fullPath, { encoding: "utf-8" });
+          return stream;
+        } catch {
+          return null;
+        }
+      }
+      /**
+       * Checks if a sitemap file exists on the local disk.
+       *
+       * @param filename - The name of the file to check.
+       * @returns A promise resolving to true if the file exists, false otherwise.
+       */
       async exists(filename) {
         try {
           const safeName = sanitizeFilename(filename);
@@ -83,6 +188,12 @@ var init_DiskSitemapStorage = __esm({
           return false;
         }
       }
+      /**
+       * Returns the full public URL for a sitemap file.
+       *
+       * @param filename - The name of the sitemap file.
+       * @returns The public URL as a string.
+       */
       getUrl(filename) {
         const safeName = sanitizeFilename(filename);
         const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
@@ -102,6 +213,7 @@ __export(index_exports, {
   GenerateSitemapJob: () => GenerateSitemapJob,
   IncrementalGenerator: () => IncrementalGenerator,
   MemoryChangeTracker: () => MemoryChangeTracker,
+  MemoryLock: () => MemoryLock,
   MemoryProgressStorage: () => MemoryProgressStorage,
   MemoryRedirectManager: () => MemoryRedirectManager,
   MemorySitemapStorage: () => MemorySitemapStorage,
@@ -110,6 +222,7 @@ __export(index_exports, {
   RedirectDetector: () => RedirectDetector,
   RedirectHandler: () => RedirectHandler,
   RedisChangeTracker: () => RedisChangeTracker,
+  RedisLock: () => RedisLock,
   RedisProgressStorage: () => RedisProgressStorage,
   RedisRedirectManager: () => RedisRedirectManager,
   RouteScanner: () => RouteScanner,
@@ -118,39 +231,88 @@ __export(index_exports, {
   SitemapGenerator: () => SitemapGenerator,
   SitemapIndex: () => SitemapIndex,
   SitemapStream: () => SitemapStream,
+  compressToBuffer: () => compressToBuffer,
+  createCompressionStream: () => createCompressionStream,
+  fromGzipFilename: () => fromGzipFilename,
   generateI18nEntries: () => generateI18nEntries,
-  routeScanner: () => routeScanner
+  routeScanner: () => routeScanner,
+  toGzipFilename: () => toGzipFilename
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/core/ChangeTracker.ts
 var MemoryChangeTracker = class {
   changes = [];
+  urlIndex = /* @__PURE__ */ new Map();
   maxChanges;
   constructor(options = {}) {
     this.maxChanges = options.maxChanges || 1e5;
   }
+  /**
+   * Record a new site structure change in memory.
+   *
+   * @param change - The change event to record.
+   */
   async track(change) {
     this.changes.push(change);
+    const urlChanges = this.urlIndex.get(change.url) || [];
+    urlChanges.push(change);
+    this.urlIndex.set(change.url, urlChanges);
     if (this.changes.length > this.maxChanges) {
-      this.changes = this.changes.slice(-this.maxChanges);
+      const removed = this.changes.shift();
+      if (removed) {
+        const changes = this.urlIndex.get(removed.url);
+        if (changes) {
+          const index = changes.indexOf(removed);
+          if (index > -1) {
+            changes.splice(index, 1);
+          }
+          if (changes.length === 0) {
+            this.urlIndex.delete(removed.url);
+          }
+        }
+      }
     }
   }
+  /**
+   * Retrieve all changes recorded in memory since a specific time.
+   *
+   * @param since - Optional start date for the query.
+   * @returns An array of change events.
+   */
   async getChanges(since) {
     if (!since) {
       return [...this.changes];
     }
     return this.changes.filter((change) => change.timestamp >= since);
   }
+  /**
+   * Retrieve the full change history for a specific URL from memory.
+   *
+   * @param url - The URL to query history for.
+   * @returns An array of change events.
+   */
   async getChangesByUrl(url) {
-    return this.changes.filter((change) => change.url === url);
+    return this.urlIndex.get(url) || [];
   }
+  /**
+   * Purge old change records from memory storage.
+   *
+   * @param since - If provided, only records older than this date will be cleared.
+   */
   async clear(since) {
     if (!since) {
       this.changes = [];
+      this.urlIndex.clear();
       return;
     }
     this.changes = this.changes.filter((change) => change.timestamp < since);
+    this.urlIndex.clear();
+    for (const change of this.changes) {
+      const urlChanges = this.urlIndex.get(change.url) || [];
+      urlChanges.push(change);
+      this.urlIndex.set(change.url, urlChanges);
+    }
   }
 };
 var RedisChangeTracker = class {
@@ -168,6 +330,11 @@ var RedisChangeTracker = class {
   getListKey() {
     return `${this.keyPrefix}list`;
   }
+  /**
+   * Record a new site structure change in Redis.
+   *
+   * @param change - The change event to record.
+   */
   async track(change) {
     const key = this.getKey(change.url);
     const listKey = this.getListKey();
@@ -177,6 +344,12 @@ var RedisChangeTracker = class {
     await this.client.zadd(listKey, score, change.url);
     await this.client.expire(listKey, this.ttl);
   }
+  /**
+   * Retrieve all changes recorded in Redis since a specific time.
+   *
+   * @param since - Optional start date for the query.
+   * @returns An array of change events.
+   */
   async getChanges(since) {
     try {
       const listKey = this.getListKey();
@@ -197,6 +370,12 @@ var RedisChangeTracker = class {
       return [];
     }
   }
+  /**
+   * Retrieve the full change history for a specific URL from Redis.
+   *
+   * @param url - The URL to query history for.
+   * @returns An array of change events.
+   */
   async getChangesByUrl(url) {
     try {
       const key = this.getKey(url);
@@ -211,6 +390,11 @@ var RedisChangeTracker = class {
       return [];
     }
   }
+  /**
+   * Purge old change records from Redis storage.
+   *
+   * @param since - If provided, only records older than this date will be cleared.
+   */
   async clear(since) {
     try {
       const listKey = this.getListKey();
@@ -240,7 +424,11 @@ var DiffCalculator = class {
     this.batchSize = options.batchSize || 1e4;
   }
   /**
-   * 計算兩個 sitemap 狀態的差異
+   * Calculates the difference between two sets of sitemap entries.
+   *
+   * @param oldEntries - The previous set of sitemap entries.
+   * @param newEntries - The current set of sitemap entries.
+   * @returns A DiffResult containing added, updated, and removed entries.
    */
   calculate(oldEntries, newEntries) {
     const oldMap = /* @__PURE__ */ new Map();
@@ -270,7 +458,11 @@ var DiffCalculator = class {
     return { added, updated, removed };
   }
   /**
-   * 批次計算差異（用於大量 URL）
+   * Batch calculates differences for large datasets using async iterables.
+   *
+   * @param oldEntries - An async iterable of the previous sitemap entries.
+   * @param newEntries - An async iterable of the current sitemap entries.
+   * @returns A promise resolving to the DiffResult.
    */
   async calculateBatch(oldEntries, newEntries) {
     const oldMap = /* @__PURE__ */ new Map();
@@ -284,7 +476,11 @@ var DiffCalculator = class {
     return this.calculate(Array.from(oldMap.values()), Array.from(newMap.values()));
   }
   /**
-   * 從變更記錄計算差異
+   * Calculates differences based on a sequence of change records.
+   *
+   * @param baseEntries - The base set of sitemap entries.
+   * @param changes - An array of change records to apply to the base set.
+   * @returns A DiffResult comparing the base set with the applied changes.
    */
   calculateFromChanges(baseEntries, changes) {
     const entryMap = /* @__PURE__ */ new Map();
@@ -304,7 +500,11 @@ var DiffCalculator = class {
     return this.calculate(baseEntries, newEntries);
   }
   /**
-   * 檢查 entry 是否有變更
+   * Checks if a sitemap entry has changed by comparing its key properties.
+   *
+   * @param oldEntry - The previous sitemap entry.
+   * @param newEntry - The current sitemap entry.
+   * @returns True if the entry has changed, false otherwise.
    */
   hasChanged(oldEntry, newEntry) {
     if (oldEntry.lastmod !== newEntry.lastmod) {
@@ -325,55 +525,92 @@ var DiffCalculator = class {
   }
 };
 
+// src/utils/Mutex.ts
+var Mutex = class {
+  queue = Promise.resolve();
+  /**
+   * Executes a function exclusively, ensuring no other task can run it concurrently.
+   *
+   * @param fn - The async function to execute.
+   * @returns A promise resolving to the result of the function.
+   */
+  async runExclusive(fn) {
+    const next = this.queue.then(() => fn());
+    this.queue = next.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return next;
+  }
+};
+
+// src/core/SitemapGenerator.ts
+init_Compression();
+
 // src/core/ShadowProcessor.ts
 var ShadowProcessor = class {
   options;
   shadowId;
   operations = [];
+  mutex = new Mutex();
   constructor(options) {
     this.options = options;
-    this.shadowId = `shadow-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    this.shadowId = `shadow-${Date.now()}-${crypto.randomUUID()}`;
   }
   /**
-   * 添加一個影子操作
+   * Adds a single file write operation to the current shadow session.
+   *
+   * If shadow processing is disabled, the file is written directly to the
+   * final destination in storage. Otherwise, it is written to the shadow staging area.
+   *
+   * @param operation - The shadow write operation details.
    */
   async addOperation(operation) {
-    if (!this.options.enabled) {
-      await this.options.storage.write(operation.filename, operation.content);
-      return;
-    }
-    this.operations.push({
-      ...operation,
-      shadowId: operation.shadowId || this.shadowId
+    return this.mutex.runExclusive(async () => {
+      if (!this.options.enabled) {
+        await this.options.storage.write(operation.filename, operation.content);
+        return;
+      }
+      this.operations.push({
+        ...operation,
+        shadowId: operation.shadowId || this.shadowId
+      });
+      if (this.options.storage.writeShadow) {
+        await this.options.storage.writeShadow(operation.filename, operation.content, this.shadowId);
+      } else {
+        await this.options.storage.write(operation.filename, operation.content);
+      }
     });
-    if (this.options.storage.writeShadow) {
-      await this.options.storage.writeShadow(operation.filename, operation.content, this.shadowId);
-    } else {
-      await this.options.storage.write(operation.filename, operation.content);
-    }
   }
   /**
-   * 提交所有影子操作
+   * Commits all staged shadow operations to the final production location.
+   *
+   * Depending on the `mode`, this will either perform an atomic swap of all files
+   * or commit each file individually (potentially creating new versions).
    */
   async commit() {
-    if (!this.options.enabled) {
-      return;
-    }
-    if (this.options.mode === "atomic") {
-      if (this.options.storage.commitShadow) {
-        await this.options.storage.commitShadow(this.shadowId);
+    return this.mutex.runExclusive(async () => {
+      if (!this.options.enabled) {
+        return;
       }
-    } else {
-      for (const operation of this.operations) {
+      if (this.options.mode === "atomic") {
         if (this.options.storage.commitShadow) {
-          await this.options.storage.commitShadow(operation.shadowId || this.shadowId);
+          await this.options.storage.commitShadow(this.shadowId);
+        }
+      } else {
+        for (const operation of this.operations) {
+          if (this.options.storage.commitShadow) {
+            await this.options.storage.commitShadow(operation.shadowId || this.shadowId);
+          }
         }
       }
-    }
-    this.operations = [];
+      this.operations = [];
+    });
   }
   /**
-   * 取消所有影子操作
+   * Cancels all staged shadow operations without committing them.
    */
   async rollback() {
     if (!this.options.enabled) {
@@ -382,13 +619,13 @@ var ShadowProcessor = class {
     this.operations = [];
   }
   /**
-   * 獲取當前影子 ID
+   * Returns the unique identifier for the current shadow session.
    */
   getShadowId() {
     return this.shadowId;
   }
   /**
-   * 獲取所有操作
+   * Returns an array of all staged shadow operations.
    */
   getOperations() {
     return [...this.operations];
@@ -405,6 +642,12 @@ var SitemapIndex = class {
       this.options.baseUrl = this.options.baseUrl.slice(0, -1);
     }
   }
+  /**
+   * Adds a single entry to the sitemap index.
+   *
+   * @param entry - A sitemap filename or a `SitemapIndexEntry` object.
+   * @returns The `SitemapIndex` instance for chaining.
+   */
   add(entry) {
     if (typeof entry === "string") {
       this.entries.push({ url: entry });
@@ -413,12 +656,23 @@ var SitemapIndex = class {
     }
     return this;
   }
+  /**
+   * Adds multiple entries to the sitemap index.
+   *
+   * @param entries - An array of sitemap filenames or `SitemapIndexEntry` objects.
+   * @returns The `SitemapIndex` instance for chaining.
+   */
   addAll(entries) {
     for (const entry of entries) {
       this.add(entry);
     }
     return this;
   }
+  /**
+   * Generates the sitemap index XML content.
+   *
+   * @returns The complete XML string for the sitemap index.
+   */
   toXML() {
     const { baseUrl, pretty } = this.options;
     let xml = `<?xml version="1.0" encoding="UTF-8"?>
@@ -447,6 +701,9 @@ var SitemapIndex = class {
     xml += `</sitemapindex>`;
     return xml;
   }
+  /**
+   * Escapes special XML characters in a string.
+   */
   escape(str) {
     return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
   }
@@ -456,55 +713,137 @@ var SitemapIndex = class {
 var SitemapStream = class {
   options;
   entries = [];
+  flags = {
+    hasImages: false,
+    hasVideos: false,
+    hasNews: false,
+    hasAlternates: false
+  };
   constructor(options) {
     this.options = { ...options };
     if (this.options.baseUrl.endsWith("/")) {
       this.options.baseUrl = this.options.baseUrl.slice(0, -1);
     }
   }
+  /**
+   * Adds a single entry to the sitemap stream.
+   *
+   * @param entry - A URL string or a complete `SitemapEntry` object.
+   * @returns The `SitemapStream` instance for chaining.
+   */
   add(entry) {
-    if (typeof entry === "string") {
-      this.entries.push({ url: entry });
-    } else {
-      this.entries.push(entry);
+    const e = typeof entry === "string" ? { url: entry } : entry;
+    this.entries.push(e);
+    if (e.images && e.images.length > 0) {
+      this.flags.hasImages = true;
+    }
+    if (e.videos && e.videos.length > 0) {
+      this.flags.hasVideos = true;
+    }
+    if (e.news) {
+      this.flags.hasNews = true;
+    }
+    if (e.alternates && e.alternates.length > 0) {
+      this.flags.hasAlternates = true;
     }
     return this;
   }
+  /**
+   * Adds multiple entries to the sitemap stream.
+   *
+   * @param entries - An array of URL strings or `SitemapEntry` objects.
+   * @returns The `SitemapStream` instance for chaining.
+   */
   addAll(entries) {
     for (const entry of entries) {
       this.add(entry);
     }
     return this;
   }
+  /**
+   * Generates the sitemap XML content.
+   *
+   * Automatically includes the necessary XML namespaces for images, videos, news,
+   * and internationalization if the entries contain such metadata.
+   *
+   * @returns The complete XML string for the sitemap.
+   */
   toXML() {
+    const parts = [];
+    for (const chunk of this.toSyncIterable()) {
+      parts.push(chunk);
+    }
+    return parts.join("");
+  }
+  /**
+   * 以 AsyncGenerator 方式產生 XML 內容。
+   * 每次 yield 一個邏輯區塊，適合串流寫入場景，可減少記憶體峰值。
+   *
+   * @returns AsyncGenerator 產生 XML 字串片段
+   *
+   * @example
+   * ```typescript
+   * const stream = new SitemapStream({ baseUrl: 'https://example.com' })
+   * stream.add({ url: '/page1' })
+   * stream.add({ url: '/page2' })
+   *
+   * for await (const chunk of stream.toAsyncIterable()) {
+   *   process.stdout.write(chunk)
+   * }
+   * ```
+   *
+   * @since 3.1.0
+   */
+  async *toAsyncIterable() {
+    yield '<?xml version="1.0" encoding="UTF-8"?>\n';
+    yield this.buildUrlsetOpenTag();
     const { baseUrl, pretty } = this.options;
-    let xml = `<?xml version="1.0" encoding="UTF-8"?>
-`;
-    xml += `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"`;
-    if (this.hasImages()) {
-      xml += ` xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"`;
+    for (const entry of this.entries) {
+      yield this.renderUrl(entry, baseUrl, pretty);
     }
-    if (this.hasVideos()) {
-      xml += ` xmlns:video="http://www.google.com/schemas/sitemap-video/1.1"`;
+    yield "</urlset>";
+  }
+  /**
+   * 同步版本的 iterable，供 toXML() 使用。
+   */
+  *toSyncIterable() {
+    yield '<?xml version="1.0" encoding="UTF-8"?>\n';
+    yield this.buildUrlsetOpenTag();
+    const { baseUrl, pretty } = this.options;
+    for (const entry of this.entries) {
+      yield this.renderUrl(entry, baseUrl, pretty);
     }
-    if (this.hasNews()) {
-      xml += ` xmlns:news="http://www.google.com/schemas/sitemap-news/0.9"`;
+    yield "</urlset>";
+  }
+  /**
+   * 建立 urlset 開標籤與所有必要的 XML 命名空間。
+   */
+  buildUrlsetOpenTag() {
+    const parts = [];
+    parts.push('<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"');
+    if (this.flags.hasImages) {
+      parts.push(' xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"');
     }
-    if (this.hasAlternates()) {
-      xml += ` xmlns:xhtml="http://www.w3.org/1999/xhtml"`;
+    if (this.flags.hasVideos) {
+      parts.push(' xmlns:video="http://www.google.com/schemas/sitemap-video/1.1"');
     }
-    xml += `>
-`;
-    for (const entry of this.entries) {
-      xml += this.renderUrl(entry, baseUrl, pretty);
+    if (this.flags.hasNews) {
+      parts.push(' xmlns:news="http://www.google.com/schemas/sitemap-news/0.9"');
     }
-    xml += `</urlset>`;
-    return xml;
+    if (this.flags.hasAlternates) {
+      parts.push(' xmlns:xhtml="http://www.w3.org/1999/xhtml"');
+    }
+    parts.push(">\n");
+    return parts.join("");
   }
+  /**
+   * Renders a single sitemap entry into its XML representation.
+   */
   renderUrl(entry, baseUrl, pretty) {
     const indent = pretty ? "  " : "";
     const subIndent = pretty ? "    " : "";
     const nl = pretty ? "\n" : "";
+    const parts = [];
     let loc = entry.url;
     if (!loc.startsWith("http")) {
       if (!loc.startsWith("/")) {
@@ -512,17 +851,17 @@ var SitemapStream = class {
       }
       loc = baseUrl + loc;
     }
-    let item = `${indent}<url>${nl}`;
-    item += `${subIndent}<loc>${this.escape(loc)}</loc>${nl}`;
+    parts.push(`${indent}<url>${nl}`);
+    parts.push(`${subIndent}<loc>${this.escape(loc)}</loc>${nl}`);
     if (entry.lastmod) {
       const date = entry.lastmod instanceof Date ? entry.lastmod : new Date(entry.lastmod);
-      item += `${subIndent}<lastmod>${date.toISOString().split("T")[0]}</lastmod>${nl}`;
+      parts.push(`${subIndent}<lastmod>${date.toISOString().split("T")[0]}</lastmod>${nl}`);
     }
     if (entry.changefreq) {
-      item += `${subIndent}<changefreq>${entry.changefreq}</changefreq>${nl}`;
+      parts.push(`${subIndent}<changefreq>${entry.changefreq}</changefreq>${nl}`);
     }
     if (entry.priority !== void 0) {
-      item += `${subIndent}<priority>${entry.priority.toFixed(1)}</priority>${nl}`;
+      parts.push(`${subIndent}<priority>${entry.priority.toFixed(1)}</priority>${nl}`);
     }
     if (entry.alternates) {
       for (const alt of entry.alternates) {
@@ -533,7 +872,9 @@ var SitemapStream = class {
           }
           altLoc = baseUrl + altLoc;
         }
-        item += `${subIndent}<xhtml:link rel="alternate" hreflang="${alt.lang}" href="${this.escape(altLoc)}"/>${nl}`;
+        parts.push(
+          `${subIndent}<xhtml:link rel="alternate" hreflang="${alt.lang}" href="${this.escape(altLoc)}"/>${nl}`
+        );
       }
     }
     if (entry.redirect?.canonical) {
@@ -544,10 +885,14 @@ var SitemapStream = class {
         }
         canonicalUrl = baseUrl + canonicalUrl;
       }
-      item += `${subIndent}<xhtml:link rel="canonical" href="${this.escape(canonicalUrl)}"/>${nl}`;
+      parts.push(
+        `${subIndent}<xhtml:link rel="canonical" href="${this.escape(canonicalUrl)}"/>${nl}`
+      );
     }
     if (entry.redirect && !entry.redirect.canonical) {
-      item += `${subIndent}<!-- Redirect: ${entry.redirect.from} \u2192 ${entry.redirect.to} (${entry.redirect.type}) -->${nl}`;
+      parts.push(
+        `${subIndent}<!-- Redirect: ${entry.redirect.from} \u2192 ${entry.redirect.to} (${entry.redirect.type}) -->${nl}`
+      );
     }
     if (entry.images) {
       for (const img of entry.images) {
@@ -558,91 +903,118 @@ var SitemapStream = class {
           }
           loc2 = baseUrl + loc2;
         }
-        item += `${subIndent}<image:image>${nl}`;
-        item += `${subIndent}  <image:loc>${this.escape(loc2)}</image:loc>${nl}`;
+        parts.push(`${subIndent}<image:image>${nl}`);
+        parts.push(`${subIndent}  <image:loc>${this.escape(loc2)}</image:loc>${nl}`);
         if (img.title) {
-          item += `${subIndent}  <image:title>${this.escape(img.title)}</image:title>${nl}`;
+          parts.push(`${subIndent}  <image:title>${this.escape(img.title)}</image:title>${nl}`);
         }
         if (img.caption) {
-          item += `${subIndent}  <image:caption>${this.escape(img.caption)}</image:caption>${nl}`;
+          parts.push(
+            `${subIndent}  <image:caption>${this.escape(img.caption)}</image:caption>${nl}`
+          );
         }
         if (img.geo_location) {
-          item += `${subIndent}  <image:geo_location>${this.escape(img.geo_location)}</image:geo_location>${nl}`;
+          parts.push(
+            `${subIndent}  <image:geo_location>${this.escape(img.geo_location)}</image:geo_location>${nl}`
+          );
         }
         if (img.license) {
-          item += `${subIndent}  <image:license>${this.escape(img.license)}</image:license>${nl}`;
+          parts.push(
+            `${subIndent}  <image:license>${this.escape(img.license)}</image:license>${nl}`
+          );
         }
-        item += `${subIndent}</image:image>${nl}`;
+        parts.push(`${subIndent}</image:image>${nl}`);
       }
     }
     if (entry.videos) {
       for (const video of entry.videos) {
-        item += `${subIndent}<video:video>${nl}`;
-        item += `${subIndent}  <video:thumbnail_loc>${this.escape(video.thumbnail_loc)}</video:thumbnail_loc>${nl}`;
-        item += `${subIndent}  <video:title>${this.escape(video.title)}</video:title>${nl}`;
-        item += `${subIndent}  <video:description>${this.escape(video.description)}</video:description>${nl}`;
+        parts.push(`${subIndent}<video:video>${nl}`);
+        parts.push(
+          `${subIndent}  <video:thumbnail_loc>${this.escape(video.thumbnail_loc)}</video:thumbnail_loc>${nl}`
+        );
+        parts.push(`${subIndent}  <video:title>${this.escape(video.title)}</video:title>${nl}`);
+        parts.push(
+          `${subIndent}  <video:description>${this.escape(video.description)}</video:description>${nl}`
+        );
         if (video.content_loc) {
-          item += `${subIndent}  <video:content_loc>${this.escape(video.content_loc)}</video:content_loc>${nl}`;
+          parts.push(
+            `${subIndent}  <video:content_loc>${this.escape(video.content_loc)}</video:content_loc>${nl}`
+          );
         }
         if (video.player_loc) {
-          item += `${subIndent}  <video:player_loc>${this.escape(video.player_loc)}</video:player_loc>${nl}`;
+          parts.push(
+            `${subIndent}  <video:player_loc>${this.escape(video.player_loc)}</video:player_loc>${nl}`
+          );
         }
         if (video.duration) {
-          item += `${subIndent}  <video:duration>${video.duration}</video:duration>${nl}`;
+          parts.push(`${subIndent}  <video:duration>${video.duration}</video:duration>${nl}`);
         }
         if (video.view_count) {
-          item += `${subIndent}  <video:view_count>${video.view_count}</video:view_count>${nl}`;
+          parts.push(`${subIndent}  <video:view_count>${video.view_count}</video:view_count>${nl}`);
         }
         if (video.publication_date) {
           const pubDate = video.publication_date instanceof Date ? video.publication_date : new Date(video.publication_date);
-          item += `${subIndent}  <video:publication_date>${pubDate.toISOString()}</video:publication_date>${nl}`;
+          parts.push(
+            `${subIndent}  <video:publication_date>${pubDate.toISOString()}</video:publication_date>${nl}`
+          );
         }
         if (video.family_friendly) {
-          item += `${subIndent}  <video:family_friendly>${video.family_friendly}</video:family_friendly>${nl}`;
+          parts.push(
+            `${subIndent}  <video:family_friendly>${video.family_friendly}</video:family_friendly>${nl}`
+          );
         }
         if (video.tag) {
           for (const tag of video.tag) {
-            item += `${subIndent}  <video:tag>${this.escape(tag)}</video:tag>${nl}`;
+            parts.push(`${subIndent}  <video:tag>${this.escape(tag)}</video:tag>${nl}`);
           }
         }
-        item += `${subIndent}</video:video>${nl}`;
+        parts.push(`${subIndent}</video:video>${nl}`);
       }
     }
     if (entry.news) {
-      item += `${subIndent}<news:news>${nl}`;
-      item += `${subIndent}  <news:publication>${nl}`;
-      item += `${subIndent}    <news:name>${this.escape(entry.news.publication.name)}</news:name>${nl}`;
-      item += `${subIndent}    <news:language>${this.escape(entry.news.publication.language)}</news:language>${nl}`;
-      item += `${subIndent}  </news:publication>${nl}`;
+      parts.push(`${subIndent}<news:news>${nl}`);
+      parts.push(`${subIndent}  <news:publication>${nl}`);
+      parts.push(
+        `${subIndent}    <news:name>${this.escape(entry.news.publication.name)}</news:name>${nl}`
+      );
+      parts.push(
+        `${subIndent}    <news:language>${this.escape(entry.news.publication.language)}</news:language>${nl}`
+      );
+      parts.push(`${subIndent}  </news:publication>${nl}`);
       const pubDate = entry.news.publication_date instanceof Date ? entry.news.publication_date : new Date(entry.news.publication_date);
-      item += `${subIndent}  <news:publication_date>${pubDate.toISOString()}</news:publication_date>${nl}`;
-      item += `${subIndent}  <news:title>${this.escape(entry.news.title)}</news:title>${nl}`;
+      parts.push(
+        `${subIndent}  <news:publication_date>${pubDate.toISOString()}</news:publication_date>${nl}`
+      );
+      parts.push(`${subIndent}  <news:title>${this.escape(entry.news.title)}</news:title>${nl}`);
       if (entry.news.genres) {
-        item += `${subIndent}  <news:genres>${this.escape(entry.news.genres)}</news:genres>${nl}`;
+        parts.push(
+          `${subIndent}  <news:genres>${this.escape(entry.news.genres)}</news:genres>${nl}`
+        );
       }
       if (entry.news.keywords) {
-        item += `${subIndent}  <news:keywords>${entry.news.keywords.map((k) => this.escape(k)).join(", ")}</news:keywords>${nl}`;
+        parts.push(
+          `${subIndent}  <news:keywords>${entry.news.keywords.map((k) => this.escape(k)).join(", ")}</news:keywords>${nl}`
+        );
       }
-      item += `${subIndent}</news:news>${nl}`;
+      parts.push(`${subIndent}</news:news>${nl}`);
     }
-    item += `${indent}</url>${nl}`;
-    return item;
-  }
-  hasImages() {
-    return this.entries.some((e) => e.images && e.images.length > 0);
-  }
-  hasVideos() {
-    return this.entries.some((e) => e.videos && e.videos.length > 0);
-  }
-  hasNews() {
-    return this.entries.some((e) => !!e.news);
-  }
-  hasAlternates() {
-    return this.entries.some((e) => e.alternates && e.alternates.length > 0);
+    parts.push(`${indent}</url>${nl}`);
+    return parts.join("");
   }
+  /**
+   * Escapes special XML characters in a string.
+   */
   escape(str) {
     return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
   }
+  /**
+   * Returns all entries currently in the stream.
+   *
+   * @returns An array of `SitemapEntry` objects.
+   */
+  getEntries() {
+    return this.entries;
+  }
 };
 
 // src/core/SitemapGenerator.ts
@@ -663,6 +1035,12 @@ var SitemapGenerator = class {
       });
     }
   }
+  /**
+   * Orchestrates the sitemap generation process.
+   *
+   * This method scans all providers, handles sharding, generates the XML files,
+   * and optionally creates a sitemap index and manifest.
+   */
   async run() {
     let shardIndex = 1;
     let currentCount = 0;
@@ -674,18 +1052,29 @@ var SitemapGenerator = class {
       baseUrl: this.options.baseUrl,
       pretty: this.options.pretty
     });
+    const shards = [];
     let isMultiFile = false;
     const flushShard = async () => {
       isMultiFile = true;
       const baseName = this.options.filename?.replace(/\.xml$/, "");
       const filename = `${baseName}-${shardIndex}.xml`;
-      const xml = currentStream.toXML();
+      const entries = currentStream.getEntries();
+      let actualFilename;
       if (this.shadowProcessor) {
-        await this.shadowProcessor.addOperation({ filename, content: xml });
+        actualFilename = this.options.compression?.enabled ? toGzipFilename(filename) : filename;
+        const xml = currentStream.toXML();
+        await this.shadowProcessor.addOperation({ filename: actualFilename, content: xml });
       } else {
-        await this.options.storage.write(filename, xml);
+        actualFilename = await this.writeSitemap(currentStream, filename);
       }
-      const url = this.options.storage.getUrl(filename);
+      shards.push({
+        filename: actualFilename,
+        from: this.normalizeUrl(entries[0].url),
+        to: this.normalizeUrl(entries[entries.length - 1].url),
+        count: entries.length,
+        lastmod: /* @__PURE__ */ new Date()
+      });
+      const url = this.options.storage.getUrl(actualFilename);
       index.add({
         url,
         lastmod: /* @__PURE__ */ new Date()
@@ -717,16 +1106,51 @@ var SitemapGenerator = class {
         }
       }
     }
+    const writeManifest = async () => {
+      if (!this.options.generateManifest) {
+        return;
+      }
+      const manifest = {
+        version: 1,
+        generatedAt: /* @__PURE__ */ new Date(),
+        baseUrl: this.options.baseUrl,
+        maxEntriesPerShard: this.options.maxEntriesPerFile,
+        sort: "url-lex",
+        shards
+      };
+      const manifestFilename = this.options.filename?.replace(/\.xml$/, "-manifest.json") || "sitemap-manifest.json";
+      const content = JSON.stringify(manifest, null, this.options.pretty ? 2 : 0);
+      if (this.shadowProcessor) {
+        await this.shadowProcessor.addOperation({ filename: manifestFilename, content });
+      } else {
+        await this.options.storage.write(manifestFilename, content);
+      }
+    };
     if (!isMultiFile) {
-      const xml = currentStream.toXML();
+      const entries = currentStream.getEntries();
+      let actualFilename;
       if (this.shadowProcessor) {
+        actualFilename = this.options.compression?.enabled ? toGzipFilename(this.options.filename) : this.options.filename;
+        const xml = currentStream.toXML();
         await this.shadowProcessor.addOperation({
-          filename: this.options.filename,
+          filename: actualFilename,
           content: xml
         });
+      } else {
+        actualFilename = await this.writeSitemap(currentStream, this.options.filename);
+      }
+      shards.push({
+        filename: actualFilename,
+        from: entries[0] ? this.normalizeUrl(entries[0].url) : "",
+        to: entries[entries.length - 1] ? this.normalizeUrl(entries[entries.length - 1].url) : "",
+        count: entries.length,
+        lastmod: /* @__PURE__ */ new Date()
+      });
+      if (this.shadowProcessor) {
+        await writeManifest();
         await this.shadowProcessor.commit();
       } else {
-        await this.options.storage.write(this.options.filename, xml);
+        await writeManifest();
       }
       return;
     }
@@ -739,35 +1163,203 @@ var SitemapGenerator = class {
         filename: this.options.filename,
         content: indexXml
       });
+      await writeManifest();
       await this.shadowProcessor.commit();
     } else {
       await this.options.storage.write(this.options.filename, indexXml);
+      await writeManifest();
+    }
+  }
+  /**
+   * 統一的 sitemap 寫入方法，優先使用串流寫入以降低記憶體使用。
+   *
+   * @param stream - SitemapStream 實例
+   * @param filename - 檔案名稱（不含 .gz）
+   * @returns 實際寫入的檔名（可能包含 .gz）
+   * @since 3.1.0
+   */
+  async writeSitemap(stream, filename) {
+    const { storage, compression } = this.options;
+    const compress = compression?.enabled ?? false;
+    if (storage.writeStream) {
+      await storage.writeStream(filename, stream.toAsyncIterable(), {
+        compress,
+        contentType: "application/xml"
+      });
+    } else {
+      const xml = stream.toXML();
+      if (compress) {
+        const buffer = await compressToBuffer(
+          (async function* () {
+            yield xml;
+          })(),
+          { level: compression?.level }
+        );
+        await storage.write(toGzipFilename(filename), buffer.toString("base64"));
+      } else {
+        await storage.write(filename, xml);
+      }
+    }
+    return compress ? toGzipFilename(filename) : filename;
+  }
+  /**
+   * Normalizes a URL to an absolute URL using the base URL.
+   */
+  normalizeUrl(url) {
+    if (url.startsWith("http")) {
+      return url;
     }
+    const { baseUrl } = this.options;
+    const normalizedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    const normalizedPath = url.startsWith("/") ? url : `/${url}`;
+    return normalizedBase + normalizedPath;
   }
   /**
-   * 獲取影子處理器（如果啟用）
+   * Returns the shadow processor instance if enabled.
    */
   getShadowProcessor() {
     return this.shadowProcessor;
   }
 };
 
+// src/core/SitemapParser.ts
+var SitemapParser = class {
+  /**
+   * Parses a sitemap XML string into an array of entries.
+   *
+   * @param xml - The raw sitemap XML content.
+   * @returns An array of `SitemapEntry` objects.
+   */
+  static parse(xml) {
+    const entries = [];
+    const urlRegex = /<url>([\s\S]*?)<\/url>/g;
+    let match;
+    while ((match = urlRegex.exec(xml)) !== null) {
+      const entry = this.parseEntry(match[1]);
+      if (entry) {
+        entries.push(entry);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Parses a sitemap XML stream into an async iterable of entries.
+   *
+   * Useful for large sitemap files that should not be fully loaded into memory.
+   *
+   * @param stream - An async iterable of XML chunks.
+   * @returns An async iterable of `SitemapEntry` objects.
+   */
+  static async *parseStream(stream) {
+    let buffer = "";
+    const urlRegex = /<url>([\s\S]*?)<\/url>/g;
+    for await (const chunk of stream) {
+      buffer += chunk;
+      let match;
+      while ((match = urlRegex.exec(buffer)) !== null) {
+        const entry = this.parseEntry(match[1]);
+        if (entry) {
+          yield entry;
+        }
+        buffer = buffer.slice(match.index + match[0].length);
+        urlRegex.lastIndex = 0;
+      }
+      if (buffer.length > 1024 * 1024) {
+        const lastUrlStart = buffer.lastIndexOf("<url>");
+        buffer = lastUrlStart !== -1 ? buffer.slice(lastUrlStart) : "";
+      }
+    }
+  }
+  /**
+   * Parses a single `<url>` tag content into a `SitemapEntry`.
+   */
+  static parseEntry(urlContent) {
+    const entry = { url: "" };
+    const locMatch = /<loc>(.*?)<\/loc>/.exec(urlContent);
+    if (locMatch) {
+      entry.url = this.unescape(locMatch[1]);
+    } else {
+      return null;
+    }
+    const lastmodMatch = /<lastmod>(.*?)<\/lastmod>/.exec(urlContent);
+    if (lastmodMatch) {
+      entry.lastmod = new Date(lastmodMatch[1]);
+    }
+    const priorityMatch = /<priority>(.*?)<\/priority>/.exec(urlContent);
+    if (priorityMatch) {
+      entry.priority = parseFloat(priorityMatch[1]);
+    }
+    const changefreqMatch = /<changefreq>(.*?)<\/changefreq>/.exec(urlContent);
+    if (changefreqMatch) {
+      entry.changefreq = changefreqMatch[1];
+    }
+    return entry;
+  }
+  /**
+   * Parses a sitemap index XML string into an array of sitemap URLs.
+   *
+   * @param xml - The raw sitemap index XML content.
+   * @returns An array of sub-sitemap URLs.
+   */
+  static parseIndex(xml) {
+    const urls = [];
+    const sitemapRegex = /<sitemap>([\s\S]*?)<\/sitemap>/g;
+    let match;
+    while ((match = sitemapRegex.exec(xml)) !== null) {
+      const content = match[1];
+      const locMatch = /<loc>(.*?)<\/loc>/.exec(content);
+      if (locMatch) {
+        urls.push(this.unescape(locMatch[1]));
+      }
+    }
+    return urls;
+  }
+  /**
+   * Unescapes special XML entities in a string.
+   */
+  static unescape(str) {
+    return str.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'");
+  }
+};
+
 // src/core/IncrementalGenerator.ts
 var IncrementalGenerator = class {
   options;
   changeTracker;
   diffCalculator;
   generator;
+  mutex = new Mutex();
   constructor(options) {
-    this.options = options;
-    this.changeTracker = options.changeTracker;
-    this.diffCalculator = options.diffCalculator || new DiffCalculator();
-    this.generator = new SitemapGenerator(options);
+    this.options = {
+      autoTrack: true,
+      generateManifest: true,
+      ...options
+    };
+    this.changeTracker = this.options.changeTracker;
+    this.diffCalculator = this.options.diffCalculator || new DiffCalculator();
+    this.generator = new SitemapGenerator(this.options);
   }
   /**
-   * 生成完整的 sitemap（首次生成）
+   * Performs a full sitemap generation and optionally records all entries in the change tracker.
    */
   async generateFull() {
+    return this.mutex.runExclusive(() => this.performFullGeneration());
+  }
+  /**
+   * Performs an incremental sitemap update based on changes recorded since a specific time.
+   *
+   * If the number of changes exceeds a certain threshold (e.g., 30% of total URLs),
+   * a full generation is triggered instead to ensure consistency.
+   *
+   * @param since - Optional start date for the incremental update.
+   */
+  async generateIncremental(since) {
+    return this.mutex.runExclusive(() => this.performIncrementalGeneration(since));
+  }
+  /**
+   * Internal implementation of full sitemap generation.
+   */
+  async performFullGeneration() {
     await this.generator.run();
     if (this.options.autoTrack) {
       const { providers } = this.options;
@@ -786,50 +1378,149 @@ var IncrementalGenerator = class {
     }
   }
   /**
-   * 增量生成（只更新變更的部分）
+   * Internal implementation of incremental sitemap generation.
    */
-  async generateIncremental(since) {
+  async performIncrementalGeneration(since) {
     const changes = await this.changeTracker.getChanges(since);
     if (changes.length === 0) {
       return;
     }
-    const baseEntries = await this.loadBaseEntries();
-    const diff = this.diffCalculator.calculateFromChanges(baseEntries, changes);
-    await this.generateDiff(diff);
+    const manifest = await this.loadManifest();
+    if (!manifest) {
+      await this.performFullGeneration();
+      return;
+    }
+    const totalCount = manifest.shards.reduce((acc, s) => acc + s.count, 0);
+    const changeRatio = totalCount > 0 ? changes.length / totalCount : 1;
+    if (changeRatio > 0.3) {
+      await this.performFullGeneration();
+      return;
+    }
+    const affectedShards = this.getAffectedShards(manifest, changes);
+    if (affectedShards.size / manifest.shards.length > 0.5) {
+      await this.performFullGeneration();
+      return;
+    }
+    await this.updateShards(manifest, affectedShards);
   }
   /**
-   * 手動追蹤變更
+   * Normalizes a URL to an absolute URL using the base URL.
    */
-  async trackChange(change) {
-    await this.changeTracker.track(change);
+  normalizeUrl(url) {
+    if (url.startsWith("http")) {
+      return url;
+    }
+    const { baseUrl } = this.options;
+    const normalizedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    const normalizedPath = url.startsWith("/") ? url : `/${url}`;
+    return normalizedBase + normalizedPath;
   }
   /**
-   * 獲取變更記錄
+   * Loads the sitemap shard manifest from storage.
    */
-  async getChanges(since) {
-    return this.changeTracker.getChanges(since);
+  async loadManifest() {
+    const filename = this.options.filename?.replace(/\.xml$/, "-manifest.json") || "sitemap-manifest.json";
+    const content = await this.options.storage.read(filename);
+    if (!content) {
+      return null;
+    }
+    try {
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
   }
   /**
-   * 載入基礎 entries（從現有 sitemap）
+   * Identifies which shards are affected by the given set of changes.
    */
-  async loadBaseEntries() {
-    const entries = [];
-    const { providers } = this.options;
-    for (const provider of providers) {
-      const providerEntries = await provider.getEntries();
-      const entriesArray = Array.isArray(providerEntries) ? providerEntries : await this.toArray(providerEntries);
-      entries.push(...entriesArray);
+  getAffectedShards(manifest, changes) {
+    const affected = /* @__PURE__ */ new Map();
+    for (const change of changes) {
+      const normalizedUrl = this.normalizeUrl(change.url);
+      let shard = manifest.shards.find((s) => {
+        return normalizedUrl >= s.from && normalizedUrl <= s.to;
+      });
+      if (!shard) {
+        shard = manifest.shards.find((s) => normalizedUrl <= s.to);
+        if (!shard) {
+          shard = manifest.shards[manifest.shards.length - 1];
+        }
+      }
+      if (shard) {
+        const shardChanges = affected.get(shard.filename) || [];
+        shardChanges.push(change);
+        affected.set(shard.filename, shardChanges);
+      }
     }
-    return entries;
+    return affected;
   }
   /**
-   * 生成差異部分
+   * Updates the affected shards in storage.
    */
-  async generateDiff(_diff) {
-    await this.generator.run();
+  async updateShards(manifest, affectedShards) {
+    for (const [filename, shardChanges] of affectedShards) {
+      const entries = [];
+      const stream = await this.options.storage.readStream?.(filename);
+      if (stream) {
+        for await (const entry of SitemapParser.parseStream(stream)) {
+          entries.push(entry);
+        }
+      } else {
+        const xml = await this.options.storage.read(filename);
+        if (!xml) {
+          continue;
+        }
+        entries.push(...SitemapParser.parse(xml));
+      }
+      const updatedEntries = this.applyChanges(entries, shardChanges);
+      const outStream = new SitemapStream({
+        baseUrl: this.options.baseUrl,
+        pretty: this.options.pretty
+      });
+      outStream.addAll(updatedEntries);
+      const newXml = outStream.toXML();
+      await this.options.storage.write(filename, newXml);
+      const shardInfo = manifest.shards.find((s) => s.filename === filename);
+      if (shardInfo) {
+        shardInfo.count = updatedEntries.length;
+        shardInfo.lastmod = /* @__PURE__ */ new Date();
+        shardInfo.from = this.normalizeUrl(updatedEntries[0].url);
+        shardInfo.to = this.normalizeUrl(updatedEntries[updatedEntries.length - 1].url);
+      }
+    }
+    const manifestFilename = this.options.filename?.replace(/\.xml$/, "-manifest.json") || "sitemap-manifest.json";
+    await this.options.storage.write(
+      manifestFilename,
+      JSON.stringify(manifest, null, this.options.pretty ? 2 : 0)
+    );
   }
   /**
-   * 將 AsyncIterable 轉換為陣列
+   * Applies changes to a set of sitemap entries and returns the updated, sorted list.
+   */
+  applyChanges(entries, changes) {
+    const entryMap = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      entryMap.set(this.normalizeUrl(entry.url), entry);
+    }
+    for (const change of changes) {
+      const normalizedUrl = this.normalizeUrl(change.url);
+      if (change.type === "add" || change.type === "update") {
+        if (change.entry) {
+          entryMap.set(normalizedUrl, {
+            ...change.entry,
+            url: normalizedUrl
+          });
+        }
+      } else if (change.type === "remove") {
+        entryMap.delete(normalizedUrl);
+      }
+    }
+    return Array.from(entryMap.values()).sort(
+      (a, b) => this.normalizeUrl(a.url).localeCompare(this.normalizeUrl(b.url))
+    );
+  }
+  /**
+   * Helper to convert an async iterable into an array.
    */
   async toArray(iterable) {
     const array = [];
@@ -851,7 +1542,10 @@ var ProgressTracker = class {
     this.updateInterval = options.updateInterval || 1e3;
   }
   /**
-   * 初始化進度追蹤
+   * Initializes progress tracking for a new job.
+   *
+   * @param jobId - Unique identifier for the generation job.
+   * @param total - Total number of entries to be processed.
    */
   async init(jobId, total) {
     this.currentProgress = {
@@ -865,7 +1559,13 @@ var ProgressTracker = class {
     await this.storage.set(jobId, this.currentProgress);
   }
   /**
-   * 更新進度
+   * Updates the current progress of the job.
+   *
+   * Updates are debounced and flushed to storage at regular intervals
+   * specified by `updateInterval` to avoid excessive write operations.
+   *
+   * @param processed - Number of entries processed so far.
+   * @param status - Optional new status for the job.
    */
   async update(processed, status) {
     if (!this.currentProgress) {
@@ -887,7 +1587,7 @@ var ProgressTracker = class {
     }
   }
   /**
-   * 完成進度追蹤
+   * Marks the current job as successfully completed.
    */
   async complete() {
     if (!this.currentProgress) {
@@ -900,7 +1600,9 @@ var ProgressTracker = class {
     this.stop();
   }
   /**
-   * 標記為失敗
+   * Marks the current job as failed with an error message.
+   *
+   * @param error - The error message describing why the job failed.
    */
   async fail(error) {
     if (!this.currentProgress) {
@@ -913,7 +1615,7 @@ var ProgressTracker = class {
     this.stop();
   }
   /**
-   * 刷新進度到儲存
+   * Flushes the current progress state to the storage backend.
    */
   async flush() {
     if (!this.currentProgress) {
@@ -928,7 +1630,7 @@ var ProgressTracker = class {
     });
   }
   /**
-   * 停止更新計時器
+   * Stops the periodic update timer.
    */
   stop() {
     if (this.updateTimer) {
@@ -937,7 +1639,9 @@ var ProgressTracker = class {
     }
   }
   /**
-   * 獲取當前進度
+   * Returns a copy of the current progress state.
+   *
+   * @returns The current SitemapProgress object, or null if no job is active.
    */
   getCurrentProgress() {
     return this.currentProgress ? { ...this.currentProgress } : null;
@@ -975,6 +1679,12 @@ var GenerateSitemapJob = class extends import_stream.Job {
     this.options = options;
     this.generator = new SitemapGenerator(options.generatorOptions);
   }
+  /**
+   * Main entry point for the job execution.
+   *
+   * Orchestrates the full lifecycle of sitemap generation, including progress
+   * initialization, generation, shadow commit, and error handling.
+   */
   async handle() {
     const { progressTracker, onComplete, onError } = this.options;
     try {
@@ -1005,7 +1715,9 @@ var GenerateSitemapJob = class extends import_stream.Job {
     }
   }
   /**
-   * 計算總 URL 數
+   * Calculates the total number of URL entries from all providers.
+   *
+   * @returns A promise resolving to the total entry count.
    */
   async calculateTotal() {
     let total = 0;
@@ -1020,30 +1732,580 @@ var GenerateSitemapJob = class extends import_stream.Job {
         }
       }
     }
-    return total;
+    return total;
+  }
+  /**
+   * Performs sitemap generation while reporting progress to the tracker and callback.
+   */
+  async generateWithProgress() {
+    const { progressTracker, onProgress } = this.options;
+    await this.generator.run();
+    this.processedEntries = this.totalEntries;
+    if (progressTracker) {
+      await progressTracker.update(this.processedEntries, "processing");
+    }
+    if (onProgress) {
+      onProgress({
+        processed: this.processedEntries,
+        total: this.totalEntries,
+        percentage: this.totalEntries > 0 ? Math.round(this.processedEntries / this.totalEntries * 100) : 100
+      });
+    }
+  }
+};
+
+// src/locks/MemoryLock.ts
+var MemoryLock = class {
+  /**
+   * Internal map storing resource identifiers to their lock expiration timestamps.
+   *
+   * Keys represent unique resource identifiers (e.g., 'sitemap-generation').
+   * Values are Unix timestamps in milliseconds representing when the lock expires.
+   * Expired locks are automatically cleaned up during `acquire()` and `isLocked()` calls.
+   */
+  locks = /* @__PURE__ */ new Map();
+  /**
+   * Attempts to acquire an exclusive lock on the specified resource.
+   *
+   * Uses a test-and-set approach: checks if the lock exists and is valid, then atomically
+   * sets the lock if available. Expired locks are treated as available and automatically
+   * replaced during acquisition.
+   *
+   * **Behavior:**
+   * - Returns `true` if lock was successfully acquired
+   * - Returns `false` if resource is already locked by another caller
+   * - Automatically replaces expired locks (acts as self-healing mechanism)
+   * - Lock automatically expires after TTL milliseconds
+   *
+   * **Race condition handling:**
+   * Safe within a single process due to JavaScript's single-threaded event loop.
+   * NOT safe across multiple processes or instances (use RedisLock for that).
+   *
+   * @param resource - Unique identifier for the resource to lock (e.g., 'sitemap-generation', 'blog-index').
+   *                   Should be consistent across all callers attempting to lock the same resource.
+   * @param ttl - Time-to-live in milliseconds. Lock automatically expires after this duration.
+   *              Recommended: 2-5x the expected operation duration to prevent premature expiration.
+   * @returns Promise resolving to `true` if lock acquired, `false` if already locked.
+   *
+   * @example Preventing concurrent sitemap generation
+   * ```typescript
+   * const lock = new MemoryLock()
+   * const acquired = await lock.acquire('sitemap-generation', 60000)
+   *
+   * if (!acquired) {
+   *   console.log('Another process is already generating the sitemap')
+   *   return new Response('Generation in progress', { status: 503 })
+   * }
+   *
+   * try {
+   *   await generateSitemap()
+   * } finally {
+   *   await lock.release('sitemap-generation')
+   * }
+   * ```
+   *
+   * @example Setting appropriate TTL
+   * ```typescript
+   * // For fast operations (< 1 second), use short TTL
+   * await lock.acquire('cache-refresh', 5000)
+   *
+   * // For slow operations (minutes), use longer TTL
+   * await lock.acquire('full-reindex', 300000) // 5 minutes
+   * ```
+   */
+  async acquire(resource, ttl) {
+    const now = Date.now();
+    const expiresAt = this.locks.get(resource);
+    if (expiresAt && expiresAt > now) {
+      return false;
+    }
+    this.locks.set(resource, now + ttl);
+    return true;
+  }
+  /**
+   * Releases the lock on the specified resource, allowing others to acquire it.
+   *
+   * Immediately removes the lock from memory without any ownership validation.
+   * Unlike RedisLock, this does NOT verify that the caller is the lock owner,
+   * so callers must ensure they only release locks they acquired.
+   *
+   * **Best practices:**
+   * - Always call `release()` in a `finally` block to prevent lock leakage
+   * - Only release locks you successfully acquired
+   * - If operation fails, still release the lock to allow retry
+   *
+   * **Idempotency:**
+   * Safe to call multiple times on the same resource. Releasing a non-existent
+   * lock is a no-op.
+   *
+   * @param resource - The resource identifier to unlock. Must match the identifier
+   *                   used in the corresponding `acquire()` call.
+   *
+   * @example Proper release pattern with try-finally
+   * ```typescript
+   * const acquired = await lock.acquire('sitemap-generation', 60000)
+   * if (!acquired) return
+   *
+   * try {
+   *   await generateSitemap()
+   * } finally {
+   *   // Always release, even if operation throws
+   *   await lock.release('sitemap-generation')
+   * }
+   * ```
+   *
+   * @example Handling operation failures
+   * ```typescript
+   * const acquired = await lock.acquire('data-import', 120000)
+   * if (!acquired) return
+   *
+   * try {
+   *   await importData()
+   * } catch (error) {
+   *   console.error('Import failed:', error)
+   *   // Lock still released in finally block
+   *   throw error
+   * } finally {
+   *   await lock.release('data-import')
+   * }
+   * ```
+   */
+  async release(resource) {
+    this.locks.delete(resource);
+  }
+  /**
+   * Checks whether a resource is currently locked and has not expired.
+   *
+   * Performs automatic cleanup by removing expired locks during the check,
+   * ensuring the internal map doesn't accumulate stale entries over time.
+   *
+   * **Use cases:**
+   * - Pre-flight checks before attempting expensive operations
+   * - Status monitoring and health checks
+   * - Implementing custom retry logic
+   * - Debugging and testing
+   *
+   * **Side effects:**
+   * Automatically deletes expired locks as a garbage collection mechanism.
+   * This is intentional to prevent memory leaks from abandoned locks.
+   *
+   * @param resource - The resource identifier to check for lock status.
+   * @returns Promise resolving to `true` if resource is actively locked (not expired),
+   *          `false` if unlocked or lock has expired.
+   *
+   * @example Pre-flight check before starting work
+   * ```typescript
+   * const lock = new MemoryLock()
+   *
+   * if (await lock.isLocked('sitemap-generation')) {
+   *   console.log('Sitemap generation already in progress')
+   *   return
+   * }
+   *
+   * // Safe to proceed
+   * await lock.acquire('sitemap-generation', 60000)
+   * ```
+   *
+   * @example Health check endpoint
+   * ```typescript
+   * app.get('/health/locks', async (c) => {
+   *   const isGenerating = await lock.isLocked('sitemap-generation')
+   *   const isIndexing = await lock.isLocked('search-indexing')
+   *
+   *   return c.json({
+   *     sitemapGeneration: isGenerating ? 'in-progress' : 'idle',
+   *     searchIndexing: isIndexing ? 'in-progress' : 'idle'
+   *   })
+   * })
+   * ```
+   *
+   * @example Custom retry logic
+   * ```typescript
+   * let attempts = 0
+   * while (attempts < 5) {
+   *   if (!await lock.isLocked('resource')) {
+   *     const acquired = await lock.acquire('resource', 10000)
+   *     if (acquired) break
+   *   }
+   *   await sleep(1000)
+   *   attempts++
+   * }
+   * ```
+   */
+  async isLocked(resource) {
+    const expiresAt = this.locks.get(resource);
+    if (!expiresAt) {
+      return false;
+    }
+    const now = Date.now();
+    if (expiresAt <= now) {
+      this.locks.delete(resource);
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Clears all locks from memory, including both active and expired locks.
+   *
+   * **Use cases:**
+   * - Test cleanup between test cases to ensure isolation
+   * - Application shutdown to release all resources
+   * - Manual intervention during debugging
+   * - Resetting state after catastrophic errors
+   *
+   * **Warning:**
+   * This forcibly releases ALL locks without any ownership validation.
+   * Should not be called during normal operation in production environments.
+   *
+   * @example Test cleanup with beforeEach hook
+   * ```typescript
+   * import { describe, beforeEach, test } from 'vitest'
+   *
+   * const lock = new MemoryLock()
+   *
+   * beforeEach(async () => {
+   *   await lock.clear() // Ensure clean state for each test
+   * })
+   *
+   * test('lock acquisition', async () => {
+   *   const acquired = await lock.acquire('test-resource', 5000)
+   *   expect(acquired).toBe(true)
+   * })
+   * ```
+   *
+   * @example Graceful shutdown handler
+   * ```typescript
+   * process.on('SIGTERM', async () => {
+   *   console.log('Shutting down, releasing all locks...')
+   *   await lock.clear()
+   *   process.exit(0)
+   * })
+   * ```
+   */
+  async clear() {
+    this.locks.clear();
+  }
+  /**
+   * Returns the number of lock entries currently stored in memory.
+   *
+   * **Important:** This includes BOTH active and expired locks. Expired locks
+   * are only cleaned up during `acquire()` or `isLocked()` calls, so this count
+   * may include stale entries.
+   *
+   * **Use cases:**
+   * - Monitoring memory usage and lock accumulation
+   * - Debugging lock leakage issues
+   * - Testing lock lifecycle behavior
+   * - Detecting abnormal lock retention patterns
+   *
+   * **Not suitable for:**
+   * - Determining number of ACTIVE locks (use `isLocked()` on each resource)
+   * - Production health checks (includes expired locks)
+   *
+   * @returns The total number of lock entries in the internal Map, including expired ones.
+   *
+   * @example Monitoring lock accumulation
+   * ```typescript
+   * const lock = new MemoryLock()
+   *
+   * setInterval(() => {
+   *   const count = lock.size()
+   *   if (count > 100) {
+   *     console.warn(`High lock count detected: ${count}`)
+   *     // May indicate lock leakage or missing release() calls
+   *   }
+   * }, 60000)
+   * ```
+   *
+   * @example Testing lock cleanup behavior
+   * ```typescript
+   * import { test, expect } from 'vitest'
+   *
+   * test('expired locks are cleaned up', async () => {
+   *   const lock = new MemoryLock()
+   *
+   *   await lock.acquire('resource', 10)
+   *   expect(lock.size()).toBe(1)
+   *
+   *   await sleep(20) // Wait for expiration
+   *   expect(lock.size()).toBe(1) // Still in map (not cleaned yet)
+   *
+   *   await lock.isLocked('resource') // Triggers cleanup
+   *   expect(lock.size()).toBe(0) // Now removed
+   * })
+   * ```
+   */
+  size() {
+    return this.locks.size;
+  }
+};
+
+// src/locks/RedisLock.ts
+var import_node_crypto = require("crypto");
+var RedisLock = class {
+  /**
+   * Constructs a new RedisLock instance with the specified configuration.
+   *
+   * @param options - Configuration including Redis client and retry parameters.
+   *
+   * @example With custom retry strategy
+   * ```typescript
+   * const lock = new RedisLock({
+   *   client: redisClient,
+   *   keyPrefix: 'app:locks:',
+   *   retryCount: 10,    // More retries for high-contention scenarios
+   *   retryDelay: 50     // Shorter delay for low-latency requirements
+   * })
+   * ```
+   */
+  constructor(options) {
+    this.options = options;
+    this.keyPrefix = options.keyPrefix || "sitemap:lock:";
+    this.retryCount = options.retryCount ?? 0;
+    this.retryDelay = options.retryDelay ?? 100;
+  }
+  /**
+   * Unique identifier for this lock instance.
+   *
+   * Generated once during construction and used for all locks acquired by this instance.
+   * Enables ownership validation: only the instance that acquired the lock can release it.
+   *
+   * **Security consideration:**
+   * UUIDs are sufficiently random to prevent lock hijacking across instances.
+   * However, they are stored in plain text in Redis (not encrypted).
+   */
+  lockId = (0, import_node_crypto.randomUUID)();
+  /**
+   * Redis key prefix for all locks acquired through this instance.
+   *
+   * Combined with resource name to form full Redis key (e.g., 'sitemap:lock:generation').
+   * Allows namespace isolation and easier debugging in Redis CLI.
+   */
+  keyPrefix;
+  /**
+   * Maximum number of retry attempts when lock is held by another instance.
+   *
+   * Set to 0 for fail-fast behavior. Higher values increase acquisition success
+   * rate but also increase latency under contention.
+   */
+  retryCount;
+  /**
+   * Delay in milliseconds between consecutive retry attempts.
+   *
+   * Should be tuned based on expected lock hold time. Typical values: 50-500ms.
+   */
+  retryDelay;
+  /**
+   * Attempts to acquire a distributed lock using Redis SET NX EX command.
+   *
+   * Uses atomic Redis operations to ensure only one instance across your entire
+   * infrastructure can hold the lock at any given time. Implements retry logic
+   * with exponential backoff for handling transient contention.
+   *
+   * **Algorithm:**
+   * 1. Convert TTL from milliseconds to seconds (Redis requirement)
+   * 2. Attempt Redis SET key lockId EX ttl NX (atomic operation)
+   * 3. If successful (returns 'OK'), lock acquired
+   * 4. If failed (returns null), retry up to retryCount times with retryDelay
+   * 5. Return true if acquired, false if all attempts exhausted
+   *
+   * **Atomicity guarantee:**
+   * The combination of NX (set if Not eXists) and EX (set EXpiration) in a single
+   * Redis command ensures no race conditions. Either the lock is acquired or it isn't.
+   *
+   * **Error handling:**
+   * Redis connection errors are caught, logged to console, and treated as acquisition
+   * failure (returns false). This fail-safe behavior prevents exceptions from bubbling
+   * up to application code.
+   *
+   * **Performance:**
+   * - Single instance: O(1) Redis operation
+   * - With retry: O(retryCount) worst case
+   * - Network latency: ~1-5ms per attempt (depends on Redis location)
+   *
+   * @param resource - Unique identifier for the resource to lock.
+   *                   Combined with keyPrefix to form Redis key.
+   * @param ttl - Time-to-live in milliseconds. Lock auto-expires after this duration.
+   *              Recommended: 2-5x expected operation time to handle slowdowns.
+   *              Minimum: 1000ms (1 second) for practical use.
+   * @returns Promise resolving to `true` if lock acquired, `false` if held by another instance
+   *          or Redis connection failed.
+   *
+   * @example Basic acquisition in distributed environment
+   * ```typescript
+   * const lock = new RedisLock({ client: redisClient })
+   * const acquired = await lock.acquire('sitemap-generation', 60000)
+   *
+   * if (!acquired) {
+   *   // Another instance (e.g., different Kubernetes pod) holds the lock
+   *   console.log('Sitemap generation in progress on another instance')
+   *   return new Response('Service busy', {
+   *     status: 503,
+   *     headers: { 'Retry-After': '30' }
+   *   })
+   * }
+   *
+   * try {
+   *   await generateSitemap()
+   * } finally {
+   *   await lock.release('sitemap-generation')
+   * }
+   * ```
+   *
+   * @example With retry logic for transient contention
+   * ```typescript
+   * const lock = new RedisLock({
+   *   client: redisClient,
+   *   retryCount: 5,
+   *   retryDelay: 200
+   * })
+   *
+   * // Will retry 5 times with 200ms delay between attempts
+   * const acquired = await lock.acquire('data-import', 120000)
+   * ```
+   *
+   * @example Setting appropriate TTL
+   * ```typescript
+   * // Fast operation: short TTL
+   * await lock.acquire('cache-rebuild', 10000) // 10 seconds
+   *
+   * // Slow operation: longer TTL with buffer
+   * await lock.acquire('full-sitemap', 300000) // 5 minutes
+   *
+   * // Very slow operation: generous TTL
+   * await lock.acquire('data-migration', 1800000) // 30 minutes
+   * ```
+   */
+  async acquire(resource, ttl) {
+    const key = this.keyPrefix + resource;
+    const ttlSeconds = Math.ceil(ttl / 1e3);
+    let attempts = 0;
+    while (attempts <= this.retryCount) {
+      try {
+        const result = await this.options.client.set(key, this.lockId, "EX", ttlSeconds, "NX");
+        if (result === "OK") {
+          return true;
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.error(`[RedisLock] Failed to acquire lock for ${resource}:`, err.message);
+      }
+      attempts++;
+      if (attempts <= this.retryCount) {
+        await this.sleep(this.retryDelay);
+      }
+    }
+    return false;
   }
   /**
-   * 帶進度追蹤的生成
+   * Releases the distributed lock using Lua script for atomic ownership validation.
+   *
+   * Uses a Lua script to atomically check if the current instance owns the lock
+   * (by comparing lockId) and delete it if so. This prevents accidentally releasing
+   * locks held by other instances, which could cause data corruption in distributed systems.
+   *
+   * **Lua script logic:**
+   * ```lua
+   * if redis.call("get", KEYS[1]) == ARGV[1] then
+   *   return redis.call("del", KEYS[1])  -- Delete only if owner matches
+   * else
+   *   return 0  -- Not owner or lock expired, do nothing
+   * end
+   * ```
+   *
+   * **Why Lua scripts?**
+   * - Atomicity: GET + comparison + DEL execute as one atomic operation
+   * - Prevents race conditions: Lock cannot change between check and delete
+   * - Server-side execution: No network round trips between steps
+   *
+   * **Error handling:**
+   * Errors during release (e.g., Redis connection loss) are logged but do NOT throw.
+   * This is intentional: if instance crashed or TTL expired, lock is already released.
+   * Silent failure here prevents cascading errors in finally blocks.
+   *
+   * **Idempotency:**
+   * Safe to call multiple times. Releasing an already-released or expired lock is a no-op.
+   *
+   * @param resource - The resource identifier to unlock. Must match the identifier
+   *                   used in the corresponding `acquire()` call.
+   *
+   * @example Proper release pattern with try-finally
+   * ```typescript
+   * const acquired = await lock.acquire('sitemap-generation', 60000)
+   * if (!acquired) return
+   *
+   * try {
+   *   await generateSitemap()
+   * } finally {
+   *   // Always release, even if operation throws
+   *   await lock.release('sitemap-generation')
+   * }
+   * ```
+   *
+   * @example Handling operation failures
+   * ```typescript
+   * const acquired = await lock.acquire('data-processing', 120000)
+   * if (!acquired) {
+   *   throw new Error('Could not acquire lock')
+   * }
+   *
+   * try {
+   *   await processData()
+   * } catch (error) {
+   *   console.error('Processing failed:', error)
+   *   // Lock still released in finally block
+   *   throw error
+   * } finally {
+   *   await lock.release('data-processing')
+   * }
+   * ```
+   *
+   * @example Why ownership validation matters
+   * ```typescript
+   * // Instance A acquires lock with 10-second TTL
+   * const lockA = new RedisLock({ client: redisClientA })
+   * await lockA.acquire('task', 10000)
+   *
+   * // ... 11 seconds pass, lock auto-expires ...
+   *
+   * // Instance B acquires the now-expired lock
+   * const lockB = new RedisLock({ client: redisClientB })
+   * await lockB.acquire('task', 10000)
+   *
+   * // Instance A tries to release (after slowdown/GC pause)
+   * await lockA.release('task')
+   * // ✅ Lua script detects lockId mismatch, does NOT delete B's lock
+   * // ❌ Without Lua: Would delete B's lock, causing data corruption
+   * ```
    */
-  async generateWithProgress() {
-    const { progressTracker, onProgress } = this.options;
-    await this.generator.run();
-    this.processedEntries = this.totalEntries;
-    if (progressTracker) {
-      await progressTracker.update(this.processedEntries, "processing");
-    }
-    if (onProgress) {
-      onProgress({
-        processed: this.processedEntries,
-        total: this.totalEntries,
-        percentage: this.totalEntries > 0 ? Math.round(this.processedEntries / this.totalEntries * 100) : 100
-      });
+  async release(resource) {
+    const key = this.keyPrefix + resource;
+    try {
+      const script = `
+        if redis.call("get", KEYS[1]) == ARGV[1] then
+          return redis.call("del", KEYS[1])
+        else
+          return 0
+        end
+      `;
+      await this.options.client.eval(script, 1, key, this.lockId);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      console.error(`[RedisLock] Failed to release lock for ${resource}:`, err.message);
     }
   }
+  /**
+   * Internal utility for sleeping between retry attempts.
+   *
+   * @param ms - Duration to sleep in milliseconds
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
 };
 
 // src/OrbitSitemap.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 
 // src/redirect/RedirectHandler.ts
 var RedirectHandler = class {
@@ -1052,7 +2314,10 @@ var RedirectHandler = class {
     this.options = options;
   }
   /**
-   * 處理 entries 中的轉址
+   * Processes a list of sitemap entries and handles redirects according to the configured strategy.
+   *
+   * @param entries - The original list of sitemap entries.
+   * @returns A promise resolving to the processed list of entries.
    */
   async processEntries(entries) {
     const { manager, strategy, followChains, maxChainLength } = this.options;
@@ -1083,7 +2348,7 @@ var RedirectHandler = class {
     }
   }
   /**
-   * 策略一：移除舊 URL，加入新 URL
+   * Strategy 1: Remove old URL and add the new destination URL.
    */
   handleRemoveOldAddNew(entries, redirectMap) {
     const processed = [];
@@ -1108,7 +2373,7 @@ var RedirectHandler = class {
     return processed;
   }
   /**
-   * 策略二：保留關聯，使用 canonical link
+   * Strategy 2: Keep the original URL but mark the destination as canonical.
    */
   handleKeepRelation(entries, redirectMap) {
     const processed = [];
@@ -1131,7 +2396,7 @@ var RedirectHandler = class {
     return processed;
   }
   /**
-   * 策略三：僅更新 URL
+   * Strategy 3: Silently update the URL to the destination.
    */
   handleUpdateUrl(entries, redirectMap) {
     return entries.map((entry) => {
@@ -1151,7 +2416,7 @@ var RedirectHandler = class {
     });
   }
   /**
-   * 策略四：雙重標記
+   * Strategy 4: Include both the original and destination URLs.
    */
   handleDualMark(entries, redirectMap) {
     const processed = [];
@@ -1188,20 +2453,88 @@ var RedirectHandler = class {
 };
 
 // src/storage/MemorySitemapStorage.ts
+init_Compression();
 var MemorySitemapStorage = class {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
   }
   files = /* @__PURE__ */ new Map();
+  /**
+   * Writes sitemap content to memory.
+   *
+   * @param filename - The name of the file to store.
+   * @param content - The XML or JSON content.
+   */
   async write(filename, content) {
     this.files.set(filename, content);
   }
+  /**
+   * 使用串流方式寫入 sitemap 至記憶體，可選擇性啟用 gzip 壓縮。
+   * 記憶體儲存會收集串流為完整字串。
+   *
+   * @param filename - 檔案名稱
+   * @param stream - XML 內容的 AsyncIterable
+   * @param options - 寫入選項（如壓縮）
+   *
+   * @since 3.1.0
+   */
+  async writeStream(filename, stream, options) {
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+    const content = chunks.join("");
+    const key = options?.compress ? toGzipFilename(filename) : filename;
+    if (options?.compress) {
+      const compressed = await compressToBuffer(
+        (async function* () {
+          yield content;
+        })()
+      );
+      this.files.set(key, compressed.toString("base64"));
+    } else {
+      this.files.set(key, content);
+    }
+  }
+  /**
+   * Reads sitemap content from memory.
+   *
+   * @param filename - The name of the file to read.
+   * @returns A promise resolving to the file content as a string, or null if not found.
+   */
   async read(filename) {
     return this.files.get(filename) || null;
   }
+  /**
+   * Returns a readable stream for a sitemap file in memory.
+   *
+   * @param filename - The name of the file to stream.
+   * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+   */
+  async readStream(filename) {
+    const content = this.files.get(filename);
+    if (content === void 0) {
+      return null;
+    }
+    return (async function* () {
+      yield content;
+    })();
+  }
+  /**
+   * Checks if a sitemap file exists in memory.
+   *
+   * @param filename - The name of the file to check.
+   * @returns A promise resolving to true if the file exists, false otherwise.
+   */
   async exists(filename) {
     return this.files.has(filename);
   }
+  /**
+   * Returns the full public URL for a sitemap file.
+   *
+   * @param filename - The name of the sitemap file.
+   * @returns The public URL as a string.
+   */
   getUrl(filename) {
     const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
     const file = filename.startsWith("/") ? filename.slice(1) : filename;
@@ -1257,7 +2590,7 @@ var OrbitSitemap = class _OrbitSitemap {
     });
   }
   /**
-   * Install the sitemap module into PlanetCore.
+   * Installs the sitemap module into PlanetCore.
    *
    * @param core - The PlanetCore instance.
    */
@@ -1268,6 +2601,9 @@ var OrbitSitemap = class _OrbitSitemap {
       core.logger.info("[OrbitSitemap] Static mode configured. Use generate() to build sitemaps.");
     }
   }
+  /**
+   * Internal method to set up dynamic sitemap routes.
+   */
   installDynamic(core) {
     const opts = this.options;
     const storage = opts.storage ?? new MemorySitemapStorage(opts.baseUrl);
@@ -1325,7 +2661,7 @@ var OrbitSitemap = class _OrbitSitemap {
     core.router.get(shardRoute, handler);
   }
   /**
-   * Generate the sitemap (static mode only).
+   * Generates the sitemap (static mode only).
    *
    * @returns A promise that resolves when generation is complete.
    * @throws {Error} If called in dynamic mode.
@@ -1367,7 +2703,7 @@ var OrbitSitemap = class _OrbitSitemap {
     console.log(`[OrbitSitemap] Generated sitemap in ${opts.outDir}`);
   }
   /**
-   * Generate incremental sitemap updates (static mode only).
+   * Generates incremental sitemap updates (static mode only).
    *
    * @param since - Only include items modified since this date.
    * @returns A promise that resolves when incremental generation is complete.
@@ -1398,7 +2734,7 @@ var OrbitSitemap = class _OrbitSitemap {
     console.log(`[OrbitSitemap] Generated incremental sitemap in ${opts.outDir}`);
   }
   /**
-   * Generate sitemap asynchronously in the background (static mode only).
+   * Generates sitemap asynchronously in the background (static mode only).
    *
    * @param options - Options for the async generation job.
    * @returns A promise resolving to the job ID.
@@ -1409,7 +2745,7 @@ var OrbitSitemap = class _OrbitSitemap {
       throw new Error("generateAsync() can only be called in static mode");
     }
     const opts = this.options;
-    const jobId = (0, import_node_crypto.randomUUID)();
+    const jobId = (0, import_node_crypto2.randomUUID)();
     let storage = opts.storage;
     if (!storage) {
       const { DiskSitemapStorage: DiskSitemapStorage2 } = await Promise.resolve().then(() => (init_DiskSitemapStorage(), DiskSitemapStorage_exports));
@@ -1459,7 +2795,7 @@ var OrbitSitemap = class _OrbitSitemap {
     return jobId;
   }
   /**
-   * Install API endpoints for triggering and monitoring sitemap generation.
+   * Installs API endpoints for triggering and monitoring sitemap generation.
    *
    * @param core - The PlanetCore instance.
    * @param basePath - The base path for the API endpoints (default: '/admin/sitemap').
@@ -1532,9 +2868,12 @@ var RouteScanner = class {
     };
   }
   /**
-   * Scan the router and return discovered entries.
+   * Scans the router and returns discovered static GET routes as sitemap entries.
    *
-   * @returns An array of sitemap entries.
+   * This method iterates through all registered routes in the Gravito router,
+   * applying inclusion/exclusion filters and defaulting metadata for matching routes.
+   *
+   * @returns An array of `SitemapEntry` objects.
    */
   getEntries() {
     const entries = [];
@@ -1596,7 +2935,10 @@ var RedirectDetector = class {
     this.options = options;
   }
   /**
-   * 偵測單一 URL 的轉址
+   * Detects redirects for a single URL using multiple strategies.
+   *
+   * @param url - The URL path to probe for redirects.
+   * @returns A promise resolving to a `RedirectRule` if a redirect is found, or null.
    */
   async detect(url) {
     if (this.options.autoDetect?.cache) {
@@ -1628,7 +2970,10 @@ var RedirectDetector = class {
     return null;
   }
   /**
-   * 批次偵測轉址
+   * Batch detects redirects for multiple URLs with concurrency control.
+   *
+   * @param urls - An array of URL paths to probe.
+   * @returns A promise resolving to a Map of URLs to their respective `RedirectRule` or null.
    */
   async detectBatch(urls) {
     const results = /* @__PURE__ */ new Map();
@@ -1648,7 +2993,7 @@ var RedirectDetector = class {
     return results;
   }
   /**
-   * 從資料庫偵測
+   * Detects a redirect from the configured database table.
    */
   async detectFromDatabase(url) {
     const { database } = this.options;
@@ -1666,14 +3011,14 @@ var RedirectDetector = class {
       return {
         from: row[columns.from],
         to: row[columns.to],
-        type: parseInt(row[columns.type], 10)
+        type: Number.parseInt(row[columns.type], 10)
       };
     } catch {
       return null;
     }
   }
   /**
-   * 從設定檔偵測
+   * Detects a redirect from a static JSON configuration file.
    */
   async detectFromConfig(url) {
     const { config } = this.options;
@@ -1691,7 +3036,7 @@ var RedirectDetector = class {
     }
   }
   /**
-   * 自動偵測（透過 HTTP 請求）
+   * Auto-detects a redirect by sending an HTTP HEAD request.
    */
   async detectAuto(url) {
     const { autoDetect, baseUrl } = this.options;
@@ -1708,7 +3053,7 @@ var RedirectDetector = class {
           method: "HEAD",
           signal: controller.signal,
           redirect: "manual"
-          // 手動處理轉址
+          // Handle redirects manually
         });
         clearTimeout(timeoutId);
         if (response.status === 301 || response.status === 302) {
@@ -1732,7 +3077,7 @@ var RedirectDetector = class {
     return null;
   }
   /**
-   * 快取結果
+   * Caches the detection result for a URL.
    */
   cacheResult(url, rule) {
     if (!this.options.autoDetect?.cache) {
@@ -1753,6 +3098,11 @@ var MemoryRedirectManager = class {
   constructor(options = {}) {
     this.maxRules = options.maxRules || 1e5;
   }
+  /**
+   * Registers a single redirect rule in memory.
+   *
+   * @param redirect - The redirect rule to add.
+   */
   async register(redirect) {
     this.rules.set(redirect.from, redirect);
     if (this.rules.size > this.maxRules) {
@@ -1762,17 +3112,41 @@ var MemoryRedirectManager = class {
       }
     }
   }
+  /**
+   * Registers multiple redirect rules in memory.
+   *
+   * @param redirects - An array of redirect rules.
+   */
   async registerBatch(redirects) {
     for (const redirect of redirects) {
       await this.register(redirect);
     }
   }
+  /**
+   * Retrieves a specific redirect rule by its source path from memory.
+   *
+   * @param from - The source path.
+   * @returns A promise resolving to the redirect rule, or null if not found.
+   */
   async get(from) {
     return this.rules.get(from) || null;
   }
+  /**
+   * Retrieves all registered redirect rules from memory.
+   *
+   * @returns A promise resolving to an array of all redirect rules.
+   */
   async getAll() {
     return Array.from(this.rules.values());
   }
+  /**
+   * Resolves a URL to its final destination through the redirect table.
+   *
+   * @param url - The URL to resolve.
+   * @param followChains - Whether to recursively resolve chained redirects.
+   * @param maxChainLength - Maximum depth for chain resolution.
+   * @returns A promise resolving to the final destination URL.
+   */
   async resolve(url, followChains = false, maxChainLength = 5) {
     let current = url;
     let chainLength = 0;
@@ -1805,6 +3179,11 @@ var RedisRedirectManager = class {
   getListKey() {
     return `${this.keyPrefix}list`;
   }
+  /**
+   * Registers a single redirect rule in Redis.
+   *
+   * @param redirect - The redirect rule to add.
+   */
   async register(redirect) {
     const key = this.getKey(redirect.from);
     const listKey = this.getListKey();
@@ -1816,11 +3195,22 @@ var RedisRedirectManager = class {
     }
     await this.client.sadd(listKey, redirect.from);
   }
+  /**
+   * Registers multiple redirect rules in Redis.
+   *
+   * @param redirects - An array of redirect rules.
+   */
   async registerBatch(redirects) {
     for (const redirect of redirects) {
       await this.register(redirect);
     }
   }
+  /**
+   * Retrieves a specific redirect rule by its source path from Redis.
+   *
+   * @param from - The source path.
+   * @returns A promise resolving to the redirect rule, or null if not found.
+   */
   async get(from) {
     try {
       const key = this.getKey(from);
@@ -1837,6 +3227,11 @@ var RedisRedirectManager = class {
       return null;
     }
   }
+  /**
+   * Retrieves all registered redirect rules from Redis.
+   *
+   * @returns A promise resolving to an array of all redirect rules.
+   */
   async getAll() {
     try {
       const listKey = this.getListKey();
@@ -1853,6 +3248,14 @@ var RedisRedirectManager = class {
       return [];
     }
   }
+  /**
+   * Resolves a URL to its final destination through the Redis redirect table.
+   *
+   * @param url - The URL to resolve.
+   * @param followChains - Whether to recursively resolve chained redirects.
+   * @param maxChainLength - Maximum depth for chain resolution.
+   * @returns A promise resolving to the final destination URL.
+   */
   async resolve(url, followChains = false, maxChainLength = 5) {
     let current = url;
     let chainLength = 0;
@@ -1875,6 +3278,9 @@ var RedisRedirectManager = class {
 init_DiskSitemapStorage();
 
 // src/storage/GCPSitemapStorage.ts
+var import_node_stream3 = require("stream");
+var import_promises3 = require("stream/promises");
+init_Compression();
 var GCPSitemapStorage = class {
   bucket;
   prefix;
@@ -1913,6 +3319,12 @@ var GCPSitemapStorage = class {
     const cleanPrefix = this.prefix.endsWith("/") ? this.prefix.slice(0, -1) : this.prefix;
     return cleanPrefix ? `${cleanPrefix}/${filename}` : filename;
   }
+  /**
+   * Writes sitemap content to a Google Cloud Storage object.
+   *
+   * @param filename - The name of the file to write.
+   * @param content - The XML or JSON content.
+   */
   async write(filename, content) {
     const { bucket } = await this.getStorageClient();
     const key = this.getKey(filename);
@@ -1924,6 +3336,41 @@ var GCPSitemapStorage = class {
       }
     });
   }
+  /**
+   * 使用串流方式寫入 sitemap 至 GCP Cloud Storage，可選擇性啟用 gzip 壓縮。
+   *
+   * @param filename - 檔案名稱
+   * @param stream - XML 內容的 AsyncIterable
+   * @param options - 寫入選項（如壓縮、content type）
+   *
+   * @since 3.1.0
+   */
+  async writeStream(filename, stream, options) {
+    const { bucket } = await this.getStorageClient();
+    const key = this.getKey(options?.compress ? toGzipFilename(filename) : filename);
+    const file = bucket.file(key);
+    const writeStream = file.createWriteStream({
+      resumable: false,
+      contentType: "application/xml",
+      metadata: {
+        contentEncoding: options?.compress ? "gzip" : void 0,
+        cacheControl: "public, max-age=3600"
+      }
+    });
+    const readable = import_node_stream3.Readable.from(stream, { encoding: "utf-8" });
+    if (options?.compress) {
+      const gzip = createCompressionStream();
+      await (0, import_promises3.pipeline)(readable, gzip, writeStream);
+    } else {
+      await (0, import_promises3.pipeline)(readable, writeStream);
+    }
+  }
+  /**
+   * Reads sitemap content from a Google Cloud Storage object.
+   *
+   * @param filename - The name of the file to read.
+   * @returns A promise resolving to the file content as a string, or null if not found.
+   */
   async read(filename) {
     try {
       const { bucket } = await this.getStorageClient();
@@ -1942,6 +3389,42 @@ var GCPSitemapStorage = class {
       throw error;
     }
   }
+  /**
+   * Returns a readable stream for a Google Cloud Storage object.
+   *
+   * @param filename - The name of the file to stream.
+   * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+   */
+  async readStream(filename) {
+    try {
+      const { bucket } = await this.getStorageClient();
+      const key = this.getKey(filename);
+      const file = bucket.file(key);
+      const [exists] = await file.exists();
+      if (!exists) {
+        return null;
+      }
+      const stream = file.createReadStream();
+      return (async function* () {
+        const decoder = new TextDecoder();
+        for await (const chunk of stream) {
+          yield decoder.decode(chunk, { stream: true });
+        }
+        yield decoder.decode();
+      })();
+    } catch (error) {
+      if (error.code === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Checks if a Google Cloud Storage object exists.
+   *
+   * @param filename - The name of the file to check.
+   * @returns A promise resolving to true if the file exists, false otherwise.
+   */
   async exists(filename) {
     try {
       const { bucket } = await this.getStorageClient();
@@ -1953,18 +3436,30 @@ var GCPSitemapStorage = class {
       return false;
     }
   }
+  /**
+   * Returns the full public URL for a Google Cloud Storage object.
+   *
+   * @param filename - The name of the sitemap file.
+   * @returns The public URL as a string.
+   */
   getUrl(filename) {
     const key = this.getKey(filename);
     const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
     return `${base}/${key}`;
   }
-  // 影子處理方法
+  /**
+   * Writes content to a shadow (staged) location in Google Cloud Storage.
+   *
+   * @param filename - The name of the file to write.
+   * @param content - The XML or JSON content.
+   * @param shadowId - Optional unique session identifier.
+   */
   async writeShadow(filename, content, shadowId) {
     if (!this.shadowEnabled) {
       return this.write(filename, content);
     }
     const { bucket } = await this.getStorageClient();
-    const id = shadowId || `shadow-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    const id = shadowId || `shadow-${Date.now()}-${crypto.randomUUID()}`;
     const shadowKey = this.getKey(`${filename}.shadow.${id}`);
     const file = bucket.file(shadowKey);
     await file.save(content, {
@@ -1974,6 +3469,11 @@ var GCPSitemapStorage = class {
       }
     });
   }
+  /**
+   * Commits all staged shadow objects in a session to production in Google Cloud Storage.
+   *
+   * @param shadowId - The identifier of the session to commit.
+   */
   async commitShadow(shadowId) {
     if (!this.shadowEnabled) {
       return;
@@ -2000,6 +3500,12 @@ var GCPSitemapStorage = class {
       }
     }
   }
+  /**
+   * Lists all archived versions of a specific sitemap in Google Cloud Storage.
+   *
+   * @param filename - The sitemap filename.
+   * @returns A promise resolving to an array of version identifiers.
+   */
   async listVersions(filename) {
     if (this.shadowMode !== "versioned") {
       return [];
@@ -2021,6 +3527,12 @@ var GCPSitemapStorage = class {
       return [];
     }
   }
+  /**
+   * Reverts a sitemap to a previously archived version in Google Cloud Storage.
+   *
+   * @param filename - The sitemap filename.
+   * @param version - The version identifier to switch to.
+   */
   async switchVersion(filename, version) {
     if (this.shadowMode !== "versioned") {
       throw new Error("Version switching is only available in versioned mode");
@@ -2040,22 +3552,51 @@ var GCPSitemapStorage = class {
 // src/storage/MemoryProgressStorage.ts
 var MemoryProgressStorage = class {
   storage = /* @__PURE__ */ new Map();
+  /**
+   * Retrieves the progress of a specific generation job from memory.
+   *
+   * @param jobId - Unique identifier for the job.
+   * @returns A promise resolving to the `SitemapProgress` object, or null if not found.
+   */
   async get(jobId) {
     const progress = this.storage.get(jobId);
     return progress ? { ...progress } : null;
   }
+  /**
+   * Initializes or overwrites a progress record in memory.
+   *
+   * @param jobId - Unique identifier for the job.
+   * @param progress - The initial or current state of the job progress.
+   */
   async set(jobId, progress) {
     this.storage.set(jobId, { ...progress });
   }
+  /**
+   * Updates specific fields of an existing progress record in memory.
+   *
+   * @param jobId - Unique identifier for the job.
+   * @param updates - Object containing the fields to update.
+   */
   async update(jobId, updates) {
     const existing = this.storage.get(jobId);
     if (existing) {
       this.storage.set(jobId, { ...existing, ...updates });
     }
   }
+  /**
+   * Deletes a progress record from memory.
+   *
+   * @param jobId - Unique identifier for the job to remove.
+   */
   async delete(jobId) {
     this.storage.delete(jobId);
   }
+  /**
+   * Lists the most recent sitemap generation jobs from memory.
+   *
+   * @param limit - Maximum number of records to return.
+   * @returns A promise resolving to an array of `SitemapProgress` objects, sorted by start time.
+   */
   async list(limit) {
     const all = Array.from(this.storage.values());
     const sorted = all.sort((a, b) => {
@@ -2083,6 +3624,12 @@ var RedisProgressStorage = class {
   getListKey() {
     return `${this.keyPrefix}list`;
   }
+  /**
+   * Retrieves the progress of a specific generation job from Redis.
+   *
+   * @param jobId - Unique identifier for the job.
+   * @returns A promise resolving to the `SitemapProgress` object, or null if not found.
+   */
   async get(jobId) {
     try {
       const key = this.getKey(jobId);
@@ -2102,6 +3649,12 @@ var RedisProgressStorage = class {
       return null;
     }
   }
+  /**
+   * Initializes or overwrites a progress record in Redis.
+   *
+   * @param jobId - Unique identifier for the job.
+   * @param progress - The initial or current state of the job progress.
+   */
   async set(jobId, progress) {
     const key = this.getKey(jobId);
     const listKey = this.getListKey();
@@ -2110,18 +3663,35 @@ var RedisProgressStorage = class {
     await this.client.zadd(listKey, Date.now(), jobId);
     await this.client.expire(listKey, this.ttl);
   }
+  /**
+   * Updates specific fields of an existing progress record in Redis.
+   *
+   * @param jobId - Unique identifier for the job.
+   * @param updates - Object containing the fields to update.
+   */
   async update(jobId, updates) {
     const existing = await this.get(jobId);
     if (existing) {
       await this.set(jobId, { ...existing, ...updates });
     }
   }
+  /**
+   * Deletes a progress record from Redis.
+   *
+   * @param jobId - Unique identifier for the job to remove.
+   */
   async delete(jobId) {
     const key = this.getKey(jobId);
     const listKey = this.getListKey();
     await this.client.del(key);
     await this.client.zrem(listKey, jobId);
   }
+  /**
+   * Lists the most recent sitemap generation jobs from Redis.
+   *
+   * @param limit - Maximum number of records to return.
+   * @returns A promise resolving to an array of `SitemapProgress` objects, sorted by start time.
+   */
   async list(limit) {
     try {
       const listKey = this.getListKey();
@@ -2141,6 +3711,7 @@ var RedisProgressStorage = class {
 };
 
 // src/storage/S3SitemapStorage.ts
+init_Compression();
 var S3SitemapStorage = class {
   bucket;
   region;
@@ -2198,6 +3769,12 @@ var S3SitemapStorage = class {
     const cleanPrefix = this.prefix.endsWith("/") ? this.prefix.slice(0, -1) : this.prefix;
     return cleanPrefix ? `${cleanPrefix}/${filename}` : filename;
   }
+  /**
+   * Writes sitemap content to an S3 object.
+   *
+   * @param filename - The name of the file to write.
+   * @param content - The XML or JSON content.
+   */
   async write(filename, content) {
     const s3 = await this.getS3Client();
     const key = this.getKey(filename);
@@ -2210,6 +3787,48 @@ var S3SitemapStorage = class {
       })
     );
   }
+  /**
+   * 使用串流方式寫入 sitemap 至 S3，可選擇性啟用 gzip 壓縮。
+   * S3 需要知道 Content-Length，因此會先收集串流為 Buffer。
+   *
+   * @param filename - 檔案名稱
+   * @param stream - XML 內容的 AsyncIterable
+   * @param options - 寫入選項（如壓縮、content type）
+   *
+   * @since 3.1.0
+   */
+  async writeStream(filename, stream, options) {
+    const s3 = await this.getS3Client();
+    const key = this.getKey(options?.compress ? toGzipFilename(filename) : filename);
+    let body;
+    const contentType = options?.contentType || "application/xml";
+    let contentEncoding;
+    if (options?.compress) {
+      body = await compressToBuffer(stream);
+      contentEncoding = "gzip";
+    } else {
+      const chunks = [];
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+      body = chunks.join("");
+    }
+    await s3.client.send(
+      new s3.PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: body,
+        ContentType: contentType,
+        ContentEncoding: contentEncoding
+      })
+    );
+  }
+  /**
+   * Reads sitemap content from an S3 object.
+   *
+   * @param filename - The name of the file to read.
+   * @returns A promise resolving to the file content as a string, or null if not found.
+   */
   async read(filename) {
     try {
       const s3 = await this.getS3Client();
@@ -2236,6 +3855,46 @@ var S3SitemapStorage = class {
       throw error;
     }
   }
+  /**
+   * Returns a readable stream for an S3 object.
+   *
+   * @param filename - The name of the file to stream.
+   * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+   */
+  async readStream(filename) {
+    try {
+      const s3 = await this.getS3Client();
+      const key = this.getKey(filename);
+      const response = await s3.client.send(
+        new s3.GetObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
+      if (!response.Body) {
+        return null;
+      }
+      const body = response.Body;
+      return (async function* () {
+        const decoder = new TextDecoder();
+        for await (const chunk of body) {
+          yield decoder.decode(chunk, { stream: true });
+        }
+        yield decoder.decode();
+      })();
+    } catch (error) {
+      if (error.name === "NoSuchKey" || error.$metadata?.httpStatusCode === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Checks if an S3 object exists.
+   *
+   * @param filename - The name of the file to check.
+   * @returns A promise resolving to true if the file exists, false otherwise.
+   */
   async exists(filename) {
     try {
       const s3 = await this.getS3Client();
@@ -2254,18 +3913,30 @@ var S3SitemapStorage = class {
       throw error;
     }
   }
+  /**
+   * Returns the full public URL for an S3 object.
+   *
+   * @param filename - The name of the sitemap file.
+   * @returns The public URL as a string.
+   */
   getUrl(filename) {
     const key = this.getKey(filename);
     const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
     return `${base}/${key}`;
   }
-  // 影子處理方法
+  /**
+   * Writes content to a shadow (staged) location in S3.
+   *
+   * @param filename - The name of the file to write.
+   * @param content - The XML or JSON content.
+   * @param shadowId - Optional unique session identifier.
+   */
   async writeShadow(filename, content, shadowId) {
     if (!this.shadowEnabled) {
       return this.write(filename, content);
     }
     const s3 = await this.getS3Client();
-    const id = shadowId || `shadow-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    const id = shadowId || `shadow-${Date.now()}-${crypto.randomUUID()}`;
     const shadowKey = this.getKey(`${filename}.shadow.${id}`);
     await s3.client.send(
       new s3.PutObjectCommand({
@@ -2276,6 +3947,11 @@ var S3SitemapStorage = class {
       })
     );
   }
+  /**
+   * Commits all staged shadow objects in a session to production.
+   *
+   * @param shadowId - The identifier of the session to commit.
+   */
   async commitShadow(shadowId) {
     if (!this.shadowEnabled) {
       return;
@@ -2343,6 +4019,12 @@ var S3SitemapStorage = class {
       }
     }
   }
+  /**
+   * Lists all archived versions of a specific sitemap in S3.
+   *
+   * @param filename - The sitemap filename.
+   * @returns A promise resolving to an array of version identifiers.
+   */
   async listVersions(filename) {
     if (this.shadowMode !== "versioned") {
       return [];
@@ -2375,6 +4057,12 @@ var S3SitemapStorage = class {
       return [];
     }
   }
+  /**
+   * Reverts a sitemap to a previously archived version in S3.
+   *
+   * @param filename - The sitemap filename.
+   * @param version - The version identifier to switch to.
+   */
   async switchVersion(filename, version) {
     if (this.shadowMode !== "versioned") {
       throw new Error("Version switching is only available in versioned mode");
@@ -2396,6 +4084,9 @@ var S3SitemapStorage = class {
     );
   }
 };
+
+// src/index.ts
+init_Compression();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DiffCalculator,
@@ -2404,6 +4095,7 @@ var S3SitemapStorage = class {
   GenerateSitemapJob,
   IncrementalGenerator,
   MemoryChangeTracker,
+  MemoryLock,
   MemoryProgressStorage,
   MemoryRedirectManager,
   MemorySitemapStorage,
@@ -2412,6 +4104,7 @@ var S3SitemapStorage = class {
   RedirectDetector,
   RedirectHandler,
   RedisChangeTracker,
+  RedisLock,
   RedisProgressStorage,
   RedisRedirectManager,
   RouteScanner,
@@ -2420,6 +4113,10 @@ var S3SitemapStorage = class {
   SitemapGenerator,
   SitemapIndex,
   SitemapStream,
+  compressToBuffer,
+  createCompressionStream,
+  fromGzipFilename,
   generateI18nEntries,
-  routeScanner
+  routeScanner,
+  toGzipFilename
 });