@gravito/constellation 3.0.2 → 3.1.0

package/dist/index.js

@@ -1,6 +1,10 @@
 import {
-  DiskSitemapStorage
-} from "./chunk-IS2H7U6M.js";
+  DiskSitemapStorage,
+  compressToBuffer,
+  createCompressionStream,
+  fromGzipFilename,
+  toGzipFilename
+} from "./chunk-3IZTXYU7.js";
 
 // src/core/ChangeTracker.ts
 var MemoryChangeTracker = class {
@@ -10,6 +14,11 @@ var MemoryChangeTracker = class {
   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) || [];
@@ -31,15 +40,32 @@ var MemoryChangeTracker = class {
       }
     }
   }
+  /**
+   * 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.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 = [];
@@ -70,6 +96,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();
@@ -79,6 +110,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();
@@ -99,6 +136,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);
@@ -113,6 +156,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();
@@ -142,7 +190,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();
@@ -172,7 +224,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();
@@ -186,7 +242,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();
@@ -206,7 +266,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) {
@@ -230,6 +294,12 @@ 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(
@@ -253,7 +323,12 @@ var ShadowProcessor = class {
     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) {
     return this.mutex.runExclusive(async () => {
@@ -273,7 +348,10 @@ var ShadowProcessor = class {
     });
   }
   /**
-   * 提交所有影子操作
+   * 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() {
     return this.mutex.runExclusive(async () => {
@@ -295,7 +373,7 @@ var ShadowProcessor = class {
     });
   }
   /**
-   * 取消所有影子操作
+   * Cancels all staged shadow operations without committing them.
    */
   async rollback() {
     if (!this.options.enabled) {
@@ -304,13 +382,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];
@@ -327,6 +405,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 });
@@ -335,12 +419,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"?>
@@ -369,6 +464,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;");
   }
@@ -390,6 +488,12 @@ var SitemapStream = class {
       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) {
     const e = typeof entry === "string" ? { url: entry } : entry;
     this.entries.push(e);
@@ -407,16 +511,78 @@ var SitemapStream = class {
     }
     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;
+    for (const entry of this.entries) {
+      yield this.renderUrl(entry, baseUrl, pretty);
+    }
+    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);
+    }
+    yield "</urlset>";
+  }
+  /**
+   * 建立 urlset 開標籤與所有必要的 XML 命名空間。
+   */
+  buildUrlsetOpenTag() {
     const parts = [];
-    parts.push('<?xml version="1.0" encoding="UTF-8"?>\n');
     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"');
@@ -431,12 +597,11 @@ var SitemapStream = class {
       parts.push(' xmlns:xhtml="http://www.w3.org/1999/xhtml"');
     }
     parts.push(">\n");
-    for (const entry of this.entries) {
-      parts.push(this.renderUrl(entry, baseUrl, pretty));
-    }
-    parts.push("</urlset>");
     return parts.join("");
   }
+  /**
+   * Renders a single sitemap entry into its XML representation.
+   */
   renderUrl(entry, baseUrl, pretty) {
     const indent = pretty ? "  " : "";
     const subIndent = pretty ? "    " : "";
@@ -599,9 +764,17 @@ var SitemapStream = class {
     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;
   }
@@ -625,6 +798,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;
@@ -642,21 +821,23 @@ var SitemapGenerator = class {
       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) {
+        actualFilename = this.options.compression?.enabled ? toGzipFilename(filename) : filename;
+        const xml = currentStream.toXML();
+        await this.shadowProcessor.addOperation({ filename: actualFilename, content: xml });
+      } else {
+        actualFilename = await this.writeSitemap(currentStream, filename);
+      }
       shards.push({
-        filename,
+        filename: actualFilename,
         from: this.normalizeUrl(entries[0].url),
         to: this.normalizeUrl(entries[entries.length - 1].url),
         count: entries.length,
         lastmod: /* @__PURE__ */ new Date()
       });
-      if (this.shadowProcessor) {
-        await this.shadowProcessor.addOperation({ filename, content: xml });
-      } else {
-        await this.options.storage.write(filename, xml);
-      }
-      const url = this.options.storage.getUrl(filename);
+      const url = this.options.storage.getUrl(actualFilename);
       index.add({
         url,
         lastmod: /* @__PURE__ */ new Date()
@@ -689,7 +870,9 @@ var SitemapGenerator = class {
       }
     }
     const writeManifest = async () => {
-      if (!this.options.generateManifest) return;
+      if (!this.options.generateManifest) {
+        return;
+      }
       const manifest = {
         version: 1,
         generatedAt: /* @__PURE__ */ new Date(),
@@ -707,24 +890,29 @@ var SitemapGenerator = class {
       }
     };
     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: actualFilename,
+          content: xml
+        });
+      } else {
+        actualFilename = await this.writeSitemap(currentStream, this.options.filename);
+      }
       shards.push({
-        filename: this.options.filename,
+        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 this.shadowProcessor.addOperation({
-          filename: this.options.filename,
-          content: xml
-        });
         await writeManifest();
         await this.shadowProcessor.commit();
       } else {
-        await this.options.storage.write(this.options.filename, xml);
         await writeManifest();
       }
       return;
@@ -745,6 +933,41 @@ var SitemapGenerator = class {
       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;
@@ -755,7 +978,7 @@ var SitemapGenerator = class {
     return normalizedBase + normalizedPath;
   }
   /**
-   * 獲取影子處理器（如果啟用）
+   * Returns the shadow processor instance if enabled.
    */
   getShadowProcessor() {
     return this.shadowProcessor;
@@ -764,6 +987,12 @@ var SitemapGenerator = class {
 
 // 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;
@@ -776,6 +1005,14 @@ var SitemapParser = class {
     }
     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;
@@ -796,6 +1033,9 @@ var SitemapParser = class {
       }
     }
   }
+  /**
+   * Parses a single `<url>` tag content into a `SitemapEntry`.
+   */
   static parseEntry(urlContent) {
     const entry = { url: "" };
     const locMatch = /<loc>(.*?)<\/loc>/.exec(urlContent);
@@ -818,6 +1058,12 @@ var SitemapParser = class {
     }
     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;
@@ -831,6 +1077,9 @@ var SitemapParser = class {
     }
     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, "'");
   }
@@ -853,12 +1102,26 @@ var IncrementalGenerator = class {
     this.diffCalculator = this.options.diffCalculator || new DiffCalculator();
     this.generator = new SitemapGenerator(this.options);
   }
+  /**
+   * 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) {
@@ -877,6 +1140,9 @@ var IncrementalGenerator = class {
       }
     }
   }
+  /**
+   * Internal implementation of incremental sitemap generation.
+   */
   async performIncrementalGeneration(since) {
     const changes = await this.changeTracker.getChanges(since);
     if (changes.length === 0) {
@@ -900,6 +1166,9 @@ var IncrementalGenerator = class {
     }
     await this.updateShards(manifest, affectedShards);
   }
+  /**
+   * Normalizes a URL to an absolute URL using the base URL.
+   */
   normalizeUrl(url) {
     if (url.startsWith("http")) {
       return url;
@@ -909,6 +1178,9 @@ var IncrementalGenerator = class {
     const normalizedPath = url.startsWith("/") ? url : `/${url}`;
     return normalizedBase + normalizedPath;
   }
+  /**
+   * Loads the sitemap shard manifest from storage.
+   */
   async loadManifest() {
     const filename = this.options.filename?.replace(/\.xml$/, "-manifest.json") || "sitemap-manifest.json";
     const content = await this.options.storage.read(filename);
@@ -921,6 +1193,9 @@ var IncrementalGenerator = class {
       return null;
     }
   }
+  /**
+   * Identifies which shards are affected by the given set of changes.
+   */
   getAffectedShards(manifest, changes) {
     const affected = /* @__PURE__ */ new Map();
     for (const change of changes) {
@@ -942,6 +1217,9 @@ var IncrementalGenerator = class {
     }
     return affected;
   }
+  /**
+   * Updates the affected shards in storage.
+   */
   async updateShards(manifest, affectedShards) {
     for (const [filename, shardChanges] of affectedShards) {
       const entries = [];
@@ -979,6 +1257,9 @@ var IncrementalGenerator = class {
       JSON.stringify(manifest, null, this.options.pretty ? 2 : 0)
     );
   }
+  /**
+   * 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) {
@@ -1001,6 +1282,9 @@ var IncrementalGenerator = class {
       (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 = [];
     for await (const item of iterable) {
@@ -1021,7 +1305,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 = {
@@ -1035,7 +1322,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) {
@@ -1057,7 +1350,7 @@ var ProgressTracker = class {
     }
   }
   /**
-   * 完成進度追蹤
+   * Marks the current job as successfully completed.
    */
   async complete() {
     if (!this.currentProgress) {
@@ -1070,7 +1363,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) {
@@ -1083,7 +1378,7 @@ var ProgressTracker = class {
     this.stop();
   }
   /**
-   * 刷新進度到儲存
+   * Flushes the current progress state to the storage backend.
    */
   async flush() {
     if (!this.currentProgress) {
@@ -1098,7 +1393,7 @@ var ProgressTracker = class {
     });
   }
   /**
-   * 停止更新計時器
+   * Stops the periodic update timer.
    */
   stop() {
     if (this.updateTimer) {
@@ -1107,7 +1402,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;
@@ -1145,6 +1442,12 @@ var GenerateSitemapJob = class extends 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 {
@@ -1175,7 +1478,9 @@ var GenerateSitemapJob = class extends 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;
@@ -1193,7 +1498,7 @@ var GenerateSitemapJob = class extends Job {
     return total;
   }
   /**
-   * 帶進度追蹤的生成
+   * Performs sitemap generation while reporting progress to the tracker and callback.
    */
   async generateWithProgress() {
     const { progressTracker, onProgress } = this.options;
@@ -1212,8 +1517,558 @@ var GenerateSitemapJob = class extends Job {
   }
 };
 
-// src/OrbitSitemap.ts
+// 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
 import { randomUUID } from "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 = 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 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
+import { randomUUID as randomUUID2 } from "crypto";
 
 // src/redirect/RedirectHandler.ts
 var RedirectHandler = class {
@@ -1222,7 +2077,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;
@@ -1253,7 +2111,7 @@ var RedirectHandler = class {
     }
   }
   /**
-   * 策略一：移除舊 URL，加入新 URL
+   * Strategy 1: Remove old URL and add the new destination URL.
    */
   handleRemoveOldAddNew(entries, redirectMap) {
     const processed = [];
@@ -1278,7 +2136,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 = [];
@@ -1301,7 +2159,7 @@ var RedirectHandler = class {
     return processed;
   }
   /**
-   * 策略三：僅更新 URL
+   * Strategy 3: Silently update the URL to the destination.
    */
   handleUpdateUrl(entries, redirectMap) {
     return entries.map((entry) => {
@@ -1321,7 +2179,7 @@ var RedirectHandler = class {
     });
   }
   /**
-   * 策略四：雙重標記
+   * Strategy 4: Include both the original and destination URLs.
    */
   handleDualMark(entries, redirectMap) {
     const processed = [];
@@ -1363,12 +2221,58 @@ var MemorySitemapStorage = class {
     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) {
@@ -1378,9 +2282,21 @@ var MemorySitemapStorage = class {
       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;
@@ -1436,7 +2352,7 @@ var OrbitSitemap = class _OrbitSitemap {
     });
   }
   /**
-   * Install the sitemap module into PlanetCore.
+   * Installs the sitemap module into PlanetCore.
    *
    * @param core - The PlanetCore instance.
    */
@@ -1447,6 +2363,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);
@@ -1504,7 +2423,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.
@@ -1516,7 +2435,7 @@ var OrbitSitemap = class _OrbitSitemap {
     const opts = this.options;
     let storage = opts.storage;
     if (!storage) {
-      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-WP6RITUN.js");
+      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-VLN5I24C.js");
       storage = new DiskSitemapStorage2(opts.outDir, opts.baseUrl);
     }
     let providers = opts.providers;
@@ -1546,7 +2465,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.
@@ -1562,7 +2481,7 @@ var OrbitSitemap = class _OrbitSitemap {
     }
     let storage = opts.storage;
     if (!storage) {
-      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-WP6RITUN.js");
+      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-VLN5I24C.js");
       storage = new DiskSitemapStorage2(opts.outDir, opts.baseUrl);
     }
     const incrementalGenerator = new IncrementalGenerator({
@@ -1577,7 +2496,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.
@@ -1588,10 +2507,10 @@ var OrbitSitemap = class _OrbitSitemap {
       throw new Error("generateAsync() can only be called in static mode");
     }
     const opts = this.options;
-    const jobId = randomUUID();
+    const jobId = randomUUID2();
     let storage = opts.storage;
     if (!storage) {
-      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-WP6RITUN.js");
+      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-VLN5I24C.js");
       storage = new DiskSitemapStorage2(opts.outDir, opts.baseUrl);
     }
     let providers = opts.providers;
@@ -1638,7 +2557,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').
@@ -1711,9 +2630,12 @@ var RouteScanner = class {
     };
   }
   /**
-   * Scan the router and return discovered entries.
+   * Scans the router and returns discovered static GET routes as 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 sitemap entries.
+   * @returns An array of `SitemapEntry` objects.
    */
   getEntries() {
     const entries = [];
@@ -1775,7 +2697,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) {
@@ -1807,7 +2732,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();
@@ -1827,7 +2755,7 @@ var RedirectDetector = class {
     return results;
   }
   /**
-   * 從資料庫偵測
+   * Detects a redirect from the configured database table.
    */
   async detectFromDatabase(url) {
     const { database } = this.options;
@@ -1845,14 +2773,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;
@@ -1870,7 +2798,7 @@ var RedirectDetector = class {
     }
   }
   /**
-   * 自動偵測（透過 HTTP 請求）
+   * Auto-detects a redirect by sending an HTTP HEAD request.
    */
   async detectAuto(url) {
     const { autoDetect, baseUrl } = this.options;
@@ -1887,7 +2815,7 @@ var RedirectDetector = class {
           method: "HEAD",
           signal: controller.signal,
           redirect: "manual"
-          // 手動處理轉址
+          // Handle redirects manually
         });
         clearTimeout(timeoutId);
         if (response.status === 301 || response.status === 302) {
@@ -1911,7 +2839,7 @@ var RedirectDetector = class {
     return null;
   }
   /**
-   * 快取結果
+   * Caches the detection result for a URL.
    */
   cacheResult(url, rule) {
     if (!this.options.autoDetect?.cache) {
@@ -1932,6 +2860,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) {
@@ -1941,17 +2874,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;
@@ -1984,6 +2941,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();
@@ -1995,11 +2957,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);
@@ -2016,6 +2989,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();
@@ -2032,6 +3010,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;
@@ -2051,6 +3037,8 @@ var RedisRedirectManager = class {
 };
 
 // src/storage/GCPSitemapStorage.ts
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
 var GCPSitemapStorage = class {
   bucket;
   prefix;
@@ -2089,6 +3077,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);
@@ -2100,6 +3094,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 = Readable.from(stream, { encoding: "utf-8" });
+    if (options?.compress) {
+      const gzip = createCompressionStream();
+      await pipeline(readable, gzip, writeStream);
+    } else {
+      await 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();
@@ -2118,6 +3147,12 @@ 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();
@@ -2142,6 +3177,12 @@ var GCPSitemapStorage = class {
       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();
@@ -2153,12 +3194,24 @@ 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);
@@ -2174,6 +3227,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;
@@ -2200,6 +3258,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 [];
@@ -2221,6 +3285,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");
@@ -2240,22 +3310,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) => {
@@ -2283,6 +3382,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);
@@ -2302,6 +3407,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();
@@ -2310,18 +3421,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();
@@ -2398,6 +3526,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);
@@ -2410,6 +3544,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();
@@ -2436,6 +3612,12 @@ 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();
@@ -2464,6 +3646,12 @@ var S3SitemapStorage = class {
       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();
@@ -2482,12 +3670,24 @@ 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);
@@ -2504,6 +3704,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;
@@ -2571,6 +3776,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 [];
@@ -2603,6 +3814,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");
@@ -2631,6 +3848,7 @@ export {
   GenerateSitemapJob,
   IncrementalGenerator,
   MemoryChangeTracker,
+  MemoryLock,
   MemoryProgressStorage,
   MemoryRedirectManager,
   MemorySitemapStorage,
@@ -2639,6 +3857,7 @@ export {
   RedirectDetector,
   RedirectHandler,
   RedisChangeTracker,
+  RedisLock,
   RedisProgressStorage,
   RedisRedirectManager,
   RouteScanner,
@@ -2647,6 +3866,10 @@ export {
   SitemapGenerator,
   SitemapIndex,
   SitemapStream,
+  compressToBuffer,
+  createCompressionStream,
+  fromGzipFilename,
   generateI18nEntries,
-  routeScanner
+  routeScanner,
+  toGzipFilename
 };