@gravito/constellation 3.0.1 → 3.0.2

package/dist/index.d.cts

@@ -205,6 +205,7 @@ interface SitemapStorage {
      * @returns The XML content as a string, or null if not found.
      */
     read(filename: string): Promise<string | null>;
+    readStream?(filename: string): Promise<AsyncIterable<string> | null>;
     /**
      * Check if a sitemap file exists in storage.
      *
@@ -441,6 +442,33 @@ interface RedirectRule {
     /** Timestamp when the redirect rule was created. */
     createdAt?: Date;
 }
+/**
+ * Represents a manifest file that tracks URL-to-shard mappings.
+ *
+ * @public
+ * @since 3.0.1
+ */
+interface ShardManifest {
+    version: number;
+    generatedAt: Date | string;
+    baseUrl: string;
+    maxEntriesPerShard: number;
+    sort: string;
+    shards: ShardInfo[];
+}
+/**
+ * Metadata about a single sitemap shard.
+ *
+ * @public
+ * @since 3.0.1
+ */
+interface ShardInfo {
+    filename: string;
+    from: string;
+    to: string;
+    count: number;
+    lastmod: Date | string;
+}
 /**
  * Manager for registering and resolving redirect rules.
  *
@@ -505,6 +533,7 @@ interface MemoryChangeTrackerOptions {
  */
 declare class MemoryChangeTracker implements ChangeTracker {
     private changes;
+    private urlIndex;
     private maxChanges;
     constructor(options?: MemoryChangeTrackerOptions);
     track(change: SitemapChange): Promise<void>;
@@ -650,6 +679,7 @@ declare class ShadowProcessor {
     private options;
     private shadowId;
     private operations;
+    private mutex;
     constructor(options: ShadowProcessorOptions);
     /**
      * 添加一個影子操作
@@ -688,6 +718,8 @@ interface SitemapGeneratorOptions extends SitemapStreamOptions {
     maxEntriesPerFile?: number;
     /** The name of the main sitemap or sitemap index file. @default 'sitemap.xml' */
     filename?: string;
+    /** Whether to generate a shard manifest file. @default false */
+    generateManifest?: boolean;
     /** Configuration for staging files before atomic deployment. */
     shadow?: {
         /** Whether shadow processing is enabled. */
@@ -727,71 +759,34 @@ declare class SitemapGenerator {
     private shadowProcessor;
     constructor(options: SitemapGeneratorOptions);
     run(): Promise<void>;
+    private normalizeUrl;
     /**
      * 獲取影子處理器（如果啟用）
      */
     getShadowProcessor(): ShadowProcessor | null;
 }
 
-/**
- * Options for configuring the `IncrementalGenerator`.
- *
- * Extends `SitemapGeneratorOptions` to include change tracking and difference
- * calculation components.
- *
- * @public
- * @since 3.0.0
- */
 interface IncrementalGeneratorOptions extends SitemapGeneratorOptions {
-    /** The change tracker used to store and retrieve sitemap changes. */
     changeTracker: ChangeTracker;
-    /** Optional difference calculator. Defaults to a new `DiffCalculator` instance. */
     diffCalculator?: DiffCalculator;
-    /** Whether to automatically track changes during full generation. @default true */
     autoTrack?: boolean;
 }
-/**
- * IncrementalGenerator optimizes sitemap updates by processing only changed URLs.
- *
- * Instead of regenerating the entire sitemap from scratch, it uses a `ChangeTracker`
- * to identify new, updated, or removed URLs and updates the sitemap incrementally.
- *
- * @public
- * @since 3.0.0
- */
 declare class IncrementalGenerator {
     private options;
     private changeTracker;
     private diffCalculator;
     private generator;
+    private mutex;
     constructor(options: IncrementalGeneratorOptions);
-    /**
-     * 生成完整的 sitemap（首次生成）
-     */
     generateFull(): Promise<void>;
-    /**
-     * 增量生成（只更新變更的部分）
-     */
     generateIncremental(since?: Date): Promise<void>;
-    /**
-     * 手動追蹤變更
-     */
-    trackChange(change: SitemapChange): Promise<void>;
-    /**
-     * 獲取變更記錄
-     */
-    getChanges(since?: Date): Promise<SitemapChange[]>;
-    /**
-     * 載入基礎 entries（從現有 sitemap）
-     */
-    private loadBaseEntries;
-    /**
-     * 生成差異部分
-     */
-    private generateDiff;
-    /**
-     * 將 AsyncIterable 轉換為陣列
-     */
+    private performFullGeneration;
+    private performIncrementalGeneration;
+    private normalizeUrl;
+    private loadManifest;
+    private getAffectedShards;
+    private updateShards;
+    private applyChanges;
     private toArray;
 }
 
@@ -902,16 +897,14 @@ declare class SitemapIndex {
 declare class SitemapStream {
     private options;
     private entries;
+    private flags;
     constructor(options: SitemapStreamOptions);
     add(entry: string | SitemapEntry): this;
     addAll(entries: (string | SitemapEntry)[]): this;
     toXML(): string;
     private renderUrl;
-    private hasImages;
-    private hasVideos;
-    private hasNews;
-    private hasAlternates;
     private escape;
+    getEntries(): SitemapEntry[];
 }
 
 /**
@@ -1484,6 +1477,7 @@ declare class DiskSitemapStorage implements SitemapStorage {
     constructor(outDir: string, baseUrl: string);
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
 }
@@ -1544,6 +1538,7 @@ declare class GCPSitemapStorage implements SitemapStorage {
     private getKey;
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
     writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
@@ -1586,6 +1581,7 @@ declare class MemorySitemapStorage implements SitemapStorage {
     constructor(baseUrl: string);
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
 }
@@ -1686,6 +1682,7 @@ declare class S3SitemapStorage implements SitemapStorage {
     private getKey;
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
     writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
@@ -1694,4 +1691,4 @@ declare class S3SitemapStorage implements SitemapStorage {
     switchVersion(filename: string, version: string): Promise<void>;
 }
 
-export { type AlternateUrl, type ChangeFreq, type ChangeTracker, type ChangeType, DiffCalculator, DiskSitemapStorage, type DynamicSitemapOptions, GCPSitemapStorage, type GCPSitemapStorageOptions, GenerateSitemapJob, type GenerateSitemapJobOptions, type I18nSitemapEntryOptions, IncrementalGenerator, type IncrementalGeneratorOptions, MemoryChangeTracker, MemoryProgressStorage, MemoryRedirectManager, type MemoryRedirectManagerOptions, MemorySitemapStorage, OrbitSitemap, ProgressTracker, type ProgressTrackerOptions, RedirectDetector, type RedirectDetectorOptions, RedirectHandler, type RedirectHandlerOptions, type RedirectHandlingStrategy, type RedirectManager, type RedirectRule, RedisChangeTracker, RedisProgressStorage, type RedisProgressStorageOptions, RedisRedirectManager, type RedisRedirectManagerOptions, RouteScanner, type RouteScannerOptions, S3SitemapStorage, type S3SitemapStorageOptions, ShadowProcessor, type ShadowProcessorOptions, type SitemapCache, type SitemapChange, type SitemapEntry, SitemapGenerator, type SitemapGeneratorOptions, type SitemapImage, SitemapIndex, type SitemapIndexEntry, type SitemapLock, type SitemapNews, type SitemapProgress, type SitemapProgressStorage, type SitemapProvider, type SitemapStorage, SitemapStream, type SitemapStreamOptions, type SitemapVideo, type StaticSitemapOptions, generateI18nEntries, routeScanner };
+export { type AlternateUrl, type ChangeFreq, type ChangeTracker, type ChangeType, DiffCalculator, DiskSitemapStorage, type DynamicSitemapOptions, GCPSitemapStorage, type GCPSitemapStorageOptions, GenerateSitemapJob, type GenerateSitemapJobOptions, type I18nSitemapEntryOptions, IncrementalGenerator, type IncrementalGeneratorOptions, MemoryChangeTracker, MemoryProgressStorage, MemoryRedirectManager, type MemoryRedirectManagerOptions, MemorySitemapStorage, OrbitSitemap, ProgressTracker, type ProgressTrackerOptions, RedirectDetector, type RedirectDetectorOptions, RedirectHandler, type RedirectHandlerOptions, type RedirectHandlingStrategy, type RedirectManager, type RedirectRule, RedisChangeTracker, RedisProgressStorage, type RedisProgressStorageOptions, RedisRedirectManager, type RedisRedirectManagerOptions, RouteScanner, type RouteScannerOptions, S3SitemapStorage, type S3SitemapStorageOptions, ShadowProcessor, type ShadowProcessorOptions, type ShardInfo, type ShardManifest, type SitemapCache, type SitemapChange, type SitemapEntry, SitemapGenerator, type SitemapGeneratorOptions, type SitemapImage, SitemapIndex, type SitemapIndexEntry, type SitemapLock, type SitemapNews, type SitemapProgress, type SitemapProgressStorage, type SitemapProvider, type SitemapStorage, SitemapStream, type SitemapStreamOptions, type SitemapVideo, type StaticSitemapOptions, generateI18nEntries, routeScanner };

package/dist/index.d.ts

@@ -205,6 +205,7 @@ interface SitemapStorage {
      * @returns The XML content as a string, or null if not found.
      */
     read(filename: string): Promise<string | null>;
+    readStream?(filename: string): Promise<AsyncIterable<string> | null>;
     /**
      * Check if a sitemap file exists in storage.
      *
@@ -441,6 +442,33 @@ interface RedirectRule {
     /** Timestamp when the redirect rule was created. */
     createdAt?: Date;
 }
+/**
+ * Represents a manifest file that tracks URL-to-shard mappings.
+ *
+ * @public
+ * @since 3.0.1
+ */
+interface ShardManifest {
+    version: number;
+    generatedAt: Date | string;
+    baseUrl: string;
+    maxEntriesPerShard: number;
+    sort: string;
+    shards: ShardInfo[];
+}
+/**
+ * Metadata about a single sitemap shard.
+ *
+ * @public
+ * @since 3.0.1
+ */
+interface ShardInfo {
+    filename: string;
+    from: string;
+    to: string;
+    count: number;
+    lastmod: Date | string;
+}
 /**
  * Manager for registering and resolving redirect rules.
  *
@@ -505,6 +533,7 @@ interface MemoryChangeTrackerOptions {
  */
 declare class MemoryChangeTracker implements ChangeTracker {
     private changes;
+    private urlIndex;
     private maxChanges;
     constructor(options?: MemoryChangeTrackerOptions);
     track(change: SitemapChange): Promise<void>;
@@ -650,6 +679,7 @@ declare class ShadowProcessor {
     private options;
     private shadowId;
     private operations;
+    private mutex;
     constructor(options: ShadowProcessorOptions);
     /**
      * 添加一個影子操作
@@ -688,6 +718,8 @@ interface SitemapGeneratorOptions extends SitemapStreamOptions {
     maxEntriesPerFile?: number;
     /** The name of the main sitemap or sitemap index file. @default 'sitemap.xml' */
     filename?: string;
+    /** Whether to generate a shard manifest file. @default false */
+    generateManifest?: boolean;
     /** Configuration for staging files before atomic deployment. */
     shadow?: {
         /** Whether shadow processing is enabled. */
@@ -727,71 +759,34 @@ declare class SitemapGenerator {
     private shadowProcessor;
     constructor(options: SitemapGeneratorOptions);
     run(): Promise<void>;
+    private normalizeUrl;
     /**
      * 獲取影子處理器（如果啟用）
      */
     getShadowProcessor(): ShadowProcessor | null;
 }
 
-/**
- * Options for configuring the `IncrementalGenerator`.
- *
- * Extends `SitemapGeneratorOptions` to include change tracking and difference
- * calculation components.
- *
- * @public
- * @since 3.0.0
- */
 interface IncrementalGeneratorOptions extends SitemapGeneratorOptions {
-    /** The change tracker used to store and retrieve sitemap changes. */
     changeTracker: ChangeTracker;
-    /** Optional difference calculator. Defaults to a new `DiffCalculator` instance. */
     diffCalculator?: DiffCalculator;
-    /** Whether to automatically track changes during full generation. @default true */
     autoTrack?: boolean;
 }
-/**
- * IncrementalGenerator optimizes sitemap updates by processing only changed URLs.
- *
- * Instead of regenerating the entire sitemap from scratch, it uses a `ChangeTracker`
- * to identify new, updated, or removed URLs and updates the sitemap incrementally.
- *
- * @public
- * @since 3.0.0
- */
 declare class IncrementalGenerator {
     private options;
     private changeTracker;
     private diffCalculator;
     private generator;
+    private mutex;
     constructor(options: IncrementalGeneratorOptions);
-    /**
-     * 生成完整的 sitemap（首次生成）
-     */
     generateFull(): Promise<void>;
-    /**
-     * 增量生成（只更新變更的部分）
-     */
     generateIncremental(since?: Date): Promise<void>;
-    /**
-     * 手動追蹤變更
-     */
-    trackChange(change: SitemapChange): Promise<void>;
-    /**
-     * 獲取變更記錄
-     */
-    getChanges(since?: Date): Promise<SitemapChange[]>;
-    /**
-     * 載入基礎 entries（從現有 sitemap）
-     */
-    private loadBaseEntries;
-    /**
-     * 生成差異部分
-     */
-    private generateDiff;
-    /**
-     * 將 AsyncIterable 轉換為陣列
-     */
+    private performFullGeneration;
+    private performIncrementalGeneration;
+    private normalizeUrl;
+    private loadManifest;
+    private getAffectedShards;
+    private updateShards;
+    private applyChanges;
     private toArray;
 }
 
@@ -902,16 +897,14 @@ declare class SitemapIndex {
 declare class SitemapStream {
     private options;
     private entries;
+    private flags;
     constructor(options: SitemapStreamOptions);
     add(entry: string | SitemapEntry): this;
     addAll(entries: (string | SitemapEntry)[]): this;
     toXML(): string;
     private renderUrl;
-    private hasImages;
-    private hasVideos;
-    private hasNews;
-    private hasAlternates;
     private escape;
+    getEntries(): SitemapEntry[];
 }
 
 /**
@@ -1484,6 +1477,7 @@ declare class DiskSitemapStorage implements SitemapStorage {
     constructor(outDir: string, baseUrl: string);
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
 }
@@ -1544,6 +1538,7 @@ declare class GCPSitemapStorage implements SitemapStorage {
     private getKey;
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
     writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
@@ -1586,6 +1581,7 @@ declare class MemorySitemapStorage implements SitemapStorage {
     constructor(baseUrl: string);
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
 }
@@ -1686,6 +1682,7 @@ declare class S3SitemapStorage implements SitemapStorage {
     private getKey;
     write(filename: string, content: string): Promise<void>;
     read(filename: string): Promise<string | null>;
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
     exists(filename: string): Promise<boolean>;
     getUrl(filename: string): string;
     writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
@@ -1694,4 +1691,4 @@ declare class S3SitemapStorage implements SitemapStorage {
     switchVersion(filename: string, version: string): Promise<void>;
 }
 
-export { type AlternateUrl, type ChangeFreq, type ChangeTracker, type ChangeType, DiffCalculator, DiskSitemapStorage, type DynamicSitemapOptions, GCPSitemapStorage, type GCPSitemapStorageOptions, GenerateSitemapJob, type GenerateSitemapJobOptions, type I18nSitemapEntryOptions, IncrementalGenerator, type IncrementalGeneratorOptions, MemoryChangeTracker, MemoryProgressStorage, MemoryRedirectManager, type MemoryRedirectManagerOptions, MemorySitemapStorage, OrbitSitemap, ProgressTracker, type ProgressTrackerOptions, RedirectDetector, type RedirectDetectorOptions, RedirectHandler, type RedirectHandlerOptions, type RedirectHandlingStrategy, type RedirectManager, type RedirectRule, RedisChangeTracker, RedisProgressStorage, type RedisProgressStorageOptions, RedisRedirectManager, type RedisRedirectManagerOptions, RouteScanner, type RouteScannerOptions, S3SitemapStorage, type S3SitemapStorageOptions, ShadowProcessor, type ShadowProcessorOptions, type SitemapCache, type SitemapChange, type SitemapEntry, SitemapGenerator, type SitemapGeneratorOptions, type SitemapImage, SitemapIndex, type SitemapIndexEntry, type SitemapLock, type SitemapNews, type SitemapProgress, type SitemapProgressStorage, type SitemapProvider, type SitemapStorage, SitemapStream, type SitemapStreamOptions, type SitemapVideo, type StaticSitemapOptions, generateI18nEntries, routeScanner };
+export { type AlternateUrl, type ChangeFreq, type ChangeTracker, type ChangeType, DiffCalculator, DiskSitemapStorage, type DynamicSitemapOptions, GCPSitemapStorage, type GCPSitemapStorageOptions, GenerateSitemapJob, type GenerateSitemapJobOptions, type I18nSitemapEntryOptions, IncrementalGenerator, type IncrementalGeneratorOptions, MemoryChangeTracker, MemoryProgressStorage, MemoryRedirectManager, type MemoryRedirectManagerOptions, MemorySitemapStorage, OrbitSitemap, ProgressTracker, type ProgressTrackerOptions, RedirectDetector, type RedirectDetectorOptions, RedirectHandler, type RedirectHandlerOptions, type RedirectHandlingStrategy, type RedirectManager, type RedirectRule, RedisChangeTracker, RedisProgressStorage, type RedisProgressStorageOptions, RedisRedirectManager, type RedisRedirectManagerOptions, RouteScanner, type RouteScannerOptions, S3SitemapStorage, type S3SitemapStorageOptions, ShadowProcessor, type ShadowProcessorOptions, type ShardInfo, type ShardManifest, type SitemapCache, type SitemapChange, type SitemapEntry, SitemapGenerator, type SitemapGeneratorOptions, type SitemapImage, SitemapIndex, type SitemapIndexEntry, type SitemapLock, type SitemapNews, type SitemapProgress, type SitemapProgressStorage, type SitemapProvider, type SitemapStorage, SitemapStream, type SitemapStreamOptions, type SitemapVideo, type StaticSitemapOptions, generateI18nEntries, routeScanner };