@gravito/constellation 3.0.2 → 3.1.1

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,23 +93,61 @@ function sanitizeFilename(filename) {
   }
   return filename;
 }
-var import_node_fs, 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);
@@ -75,6 +156,12 @@ 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);
@@ -86,6 +173,12 @@ var init_DiskSitemapStorage = __esm({
           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);
@@ -95,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;
@@ -114,6 +213,7 @@ __export(index_exports, {
   GenerateSitemapJob: () => GenerateSitemapJob,
   IncrementalGenerator: () => IncrementalGenerator,
   MemoryChangeTracker: () => MemoryChangeTracker,
+  MemoryLock: () => MemoryLock,
   MemoryProgressStorage: () => MemoryProgressStorage,
   MemoryRedirectManager: () => MemoryRedirectManager,
   MemorySitemapStorage: () => MemorySitemapStorage,
@@ -122,6 +222,7 @@ __export(index_exports, {
   RedirectDetector: () => RedirectDetector,
   RedirectHandler: () => RedirectHandler,
   RedisChangeTracker: () => RedisChangeTracker,
+  RedisLock: () => RedisLock,
   RedisProgressStorage: () => RedisProgressStorage,
   RedisRedirectManager: () => RedisRedirectManager,
   RouteScanner: () => RouteScanner,
@@ -130,8 +231,12 @@ __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);
 
@@ -143,6 +248,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) || [];
@@ -164,15 +274,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 = [];
@@ -203,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();
@@ -212,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();
@@ -232,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);
@@ -246,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();
@@ -275,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();
@@ -305,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();
@@ -319,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();
@@ -339,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) {
@@ -363,6 +528,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(
@@ -375,6 +546,9 @@ var Mutex = class {
   }
 };
 
+// src/core/SitemapGenerator.ts
+init_Compression();
+
 // src/core/ShadowProcessor.ts
 var ShadowProcessor = class {
   options;
@@ -386,7 +560,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 () => {
@@ -406,7 +585,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 () => {
@@ -428,7 +610,7 @@ var ShadowProcessor = class {
     });
   }
   /**
-   * 取消所有影子操作
+   * Cancels all staged shadow operations without committing them.
    */
   async rollback() {
     if (!this.options.enabled) {
@@ -437,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];
@@ -460,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 });
@@ -468,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"?>
@@ -502,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;");
   }
@@ -523,6 +725,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);
@@ -540,16 +748,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"');
@@ -564,12 +834,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 ? "    " : "";
@@ -732,9 +1001,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;
   }
@@ -758,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;
@@ -775,21 +1058,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()
@@ -822,7 +1107,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(),
@@ -840,24 +1127,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;
@@ -878,6 +1170,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;
@@ -888,7 +1215,7 @@ var SitemapGenerator = class {
     return normalizedBase + normalizedPath;
   }
   /**
-   * 獲取影子處理器（如果啟用）
+   * Returns the shadow processor instance if enabled.
    */
   getShadowProcessor() {
     return this.shadowProcessor;
@@ -897,6 +1224,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;
@@ -909,6 +1242,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;
@@ -929,6 +1270,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);
@@ -951,6 +1295,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;
@@ -964,6 +1314,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, "'");
   }
@@ -986,12 +1339,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) {
@@ -1010,6 +1377,9 @@ var IncrementalGenerator = class {
       }
     }
   }
+  /**
+   * Internal implementation of incremental sitemap generation.
+   */
   async performIncrementalGeneration(since) {
     const changes = await this.changeTracker.getChanges(since);
     if (changes.length === 0) {
@@ -1033,6 +1403,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;
@@ -1042,6 +1415,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);
@@ -1054,6 +1430,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) {
@@ -1075,6 +1454,9 @@ var IncrementalGenerator = class {
     }
     return affected;
   }
+  /**
+   * Updates the affected shards in storage.
+   */
   async updateShards(manifest, affectedShards) {
     for (const [filename, shardChanges] of affectedShards) {
       const entries = [];
@@ -1112,6 +1494,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) {
@@ -1134,6 +1519,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) {
@@ -1154,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 = {
@@ -1168,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) {
@@ -1190,7 +1587,7 @@ var ProgressTracker = class {
     }
   }
   /**
-   * 完成進度追蹤
+   * Marks the current job as successfully completed.
    */
   async complete() {
     if (!this.currentProgress) {
@@ -1203,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) {
@@ -1216,7 +1615,7 @@ var ProgressTracker = class {
     this.stop();
   }
   /**
-   * 刷新進度到儲存
+   * Flushes the current progress state to the storage backend.
    */
   async flush() {
     if (!this.currentProgress) {
@@ -1231,7 +1630,7 @@ var ProgressTracker = class {
     });
   }
   /**
-   * 停止更新計時器
+   * Stops the periodic update timer.
    */
   stop() {
     if (this.updateTimer) {
@@ -1240,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;
@@ -1278,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 {
@@ -1308,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;
@@ -1326,7 +1735,7 @@ var GenerateSitemapJob = class extends import_stream.Job {
     return total;
   }
   /**
-   * 帶進度追蹤的生成
+   * Performs sitemap generation while reporting progress to the tracker and callback.
    */
   async generateWithProgress() {
     const { progressTracker, onProgress } = this.options;
@@ -1345,8 +1754,558 @@ var GenerateSitemapJob = class extends import_stream.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
 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 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_crypto2 = require("crypto");
 
 // src/redirect/RedirectHandler.ts
 var RedirectHandler = class {
@@ -1355,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;
@@ -1386,7 +2348,7 @@ var RedirectHandler = class {
     }
   }
   /**
-   * 策略一：移除舊 URL，加入新 URL
+   * Strategy 1: Remove old URL and add the new destination URL.
    */
   handleRemoveOldAddNew(entries, redirectMap) {
     const processed = [];
@@ -1411,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 = [];
@@ -1434,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) => {
@@ -1454,7 +2416,7 @@ var RedirectHandler = class {
     });
   }
   /**
-   * 策略四：雙重標記
+   * Strategy 4: Include both the original and destination URLs.
    */
   handleDualMark(entries, redirectMap) {
     const processed = [];
@@ -1491,17 +2453,64 @@ 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) {
@@ -1511,9 +2520,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;
@@ -1569,7 +2590,7 @@ var OrbitSitemap = class _OrbitSitemap {
     });
   }
   /**
-   * Install the sitemap module into PlanetCore.
+   * Installs the sitemap module into PlanetCore.
    *
    * @param core - The PlanetCore instance.
    */
@@ -1580,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);
@@ -1637,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.
@@ -1679,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.
@@ -1710,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.
@@ -1721,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));
@@ -1771,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').
@@ -1844,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 = [];
@@ -1908,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) {
@@ -1940,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();
@@ -1960,7 +2993,7 @@ var RedirectDetector = class {
     return results;
   }
   /**
-   * 從資料庫偵測
+   * Detects a redirect from the configured database table.
    */
   async detectFromDatabase(url) {
     const { database } = this.options;
@@ -1978,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;
@@ -2003,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;
@@ -2020,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) {
@@ -2044,7 +3077,7 @@ var RedirectDetector = class {
     return null;
   }
   /**
-   * 快取結果
+   * Caches the detection result for a URL.
    */
   cacheResult(url, rule) {
     if (!this.options.autoDetect?.cache) {
@@ -2065,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) {
@@ -2074,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;
@@ -2117,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();
@@ -2128,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);
@@ -2149,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();
@@ -2165,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;
@@ -2187,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;
@@ -2225,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);
@@ -2236,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();
@@ -2254,6 +3389,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();
@@ -2278,6 +3419,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();
@@ -2289,12 +3436,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);
@@ -2310,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;
@@ -2336,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 [];
@@ -2357,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");
@@ -2376,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) => {
@@ -2419,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);
@@ -2438,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();
@@ -2446,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();
@@ -2477,6 +3711,7 @@ var RedisProgressStorage = class {
 };
 
 // src/storage/S3SitemapStorage.ts
+init_Compression();
 var S3SitemapStorage = class {
   bucket;
   region;
@@ -2534,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);
@@ -2546,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();
@@ -2572,6 +3855,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();
@@ -2600,6 +3889,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();
@@ -2618,12 +3913,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);
@@ -2640,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;
@@ -2707,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 [];
@@ -2739,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");
@@ -2760,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,
@@ -2768,6 +4095,7 @@ var S3SitemapStorage = class {
   GenerateSitemapJob,
   IncrementalGenerator,
   MemoryChangeTracker,
+  MemoryLock,
   MemoryProgressStorage,
   MemoryRedirectManager,
   MemorySitemapStorage,
@@ -2776,6 +4104,7 @@ var S3SitemapStorage = class {
   RedirectDetector,
   RedirectHandler,
   RedisChangeTracker,
+  RedisLock,
   RedisProgressStorage,
   RedisRedirectManager,
   RouteScanner,
@@ -2784,6 +4113,10 @@ var S3SitemapStorage = class {
   SitemapGenerator,
   SitemapIndex,
   SitemapStream,
+  compressToBuffer,
+  createCompressionStream,
+  fromGzipFilename,
   generateI18nEntries,
-  routeScanner
+  routeScanner,
+  toGzipFilename
 });