feat: rename persistent cache maxGenerations to maxVersions (#14545)

Author: ahabhgk

crates/node_binding/napi-binding.d.ts

@@ -1926,6 +1926,8 @@ export interface RawCacheOptionsMemory {
 export interface RawCacheOptionsPersistent {
   buildDependencies?: Array<string>
   version?: string
+  maxAge: number
+  maxVersions: number
   snapshot?: RawSnapshotOptions
   storage?: RawStorageOptions
   portable?: boolean
@@ -3096,8 +3098,6 @@ export interface RawStatsOptions {
 export interface RawStorageOptions {
   type: "filesystem"
   directory: string
-  maxAge: number
-  maxGenerations: number
 }
 
 export interface RawSubresourceIntegrityPluginOptions {

crates/rspack_binding_api/src/raw_options/raw_cache/mod.rs

@@ -17,6 +17,8 @@ use rspack_core::{CacheOptions, cache::persistent::PersistentCacheOptions};
 pub struct RawCacheOptionsPersistent {
   pub build_dependencies: Option<Vec<String>>,
   pub version: Option<String>,
+  pub max_age: u32,
+  pub max_versions: u32,
   pub snapshot: Option<RawSnapshotOptions>,
   pub storage: Option<RawStorageOptions>,
   pub portable: Option<bool>,
@@ -27,7 +29,7 @@ impl TryFrom<RawCacheOptionsPersistent> for PersistentCacheOptions {
   type Error = rspack_error::Error;
 
   fn try_from(value: RawCacheOptionsPersistent) -> rspack_error::Result<Self> {
-    let (storage, max_age, max_generations) = value.storage.unwrap_or_default().normalize()?;
+    let storage = value.storage.unwrap_or_default().normalize()?;
     Ok(Self {
       build_dependencies: value
         .build_dependencies
@@ -40,8 +42,8 @@ impl TryFrom<RawCacheOptionsPersistent> for PersistentCacheOptions {
       storage,
       portable: value.portable.unwrap_or_default(),
       readonly: value.readonly.unwrap_or_default(),
-      max_age,
-      max_generations,
+      max_age: value.max_age.into(),
+      max_versions: value.max_versions,
     })
   }
 }

crates/rspack_binding_api/src/raw_options/raw_cache/raw_storage.rs

@@ -7,20 +7,14 @@ pub struct RawStorageOptions {
   #[napi(ts_type = r#""filesystem""#)]
   pub r#type: String,
   pub directory: String,
-  pub max_age: u32,
-  pub max_generations: u32,
 }
 
 impl RawStorageOptions {
-  pub(super) fn normalize(self) -> rspack_error::Result<(StorageOptions, u64, u32)> {
+  pub(super) fn normalize(self) -> rspack_error::Result<StorageOptions> {
     match self.r#type.as_str() {
-      "filesystem" => Ok((
-        StorageOptions::FileSystem {
-          directory: self.directory.into(),
-        },
-        self.max_age.into(),
-        self.max_generations,
-      )),
+      "filesystem" => Ok(StorageOptions::FileSystem {
+        directory: self.directory.into(),
+      }),
       storage_type => Err(rspack_error::error!(
         "unsupported storage type {storage_type}"
       )),

crates/rspack_core/src/cache/persistent/mod.rs

@@ -45,9 +45,9 @@ pub struct PersistentCacheOptions {
   /// Filesystem cache max age in seconds.
   #[cacheable(with=Skip)]
   pub max_age: u64,
-  /// Filesystem generation count limit for the current storage directory.
+  /// Filesystem version count limit for the current storage directory.
   #[cacheable(with=Skip)]
-  pub max_generations: u32,
+  pub max_versions: u32,
 }
 
 /// Persistent cache implementation
@@ -79,7 +79,6 @@ impl PersistentCache {
       None
     };
     let codec = Arc::new(CacheCodec::new(project_root));
-    let max_generations = option.max_generations;
     // use codec.encode to transform the absolute path in option,
     // it will ensure that same project in different directory have the same version.
     let option_bytes = codec
@@ -98,7 +97,7 @@ impl PersistentCache {
       option.storage.clone(),
       version,
       option.max_age,
-      max_generations,
+      option.max_versions,
       intermediate_filesystem,
     );
     let snapshot = Arc::new(Snapshot::new(

crates/rspack_core/src/cache/persistent/storage/mod.rs

@@ -22,15 +22,15 @@ pub fn create_storage(
   options: StorageOptions,
   version: String,
   max_age: u64,
-  max_generations: u32,
+  max_versions: u32,
   fs: Arc<dyn IntermediateFileSystem>,
 ) -> BoxStorage {
   match options {
     StorageOptions::FileSystem { directory } => {
       let option = FileSystemOptions {
         directory,
         version,
-        max_generations,
+        max_versions,
         max_pack_size: 500 * 1024,
         expire: max_age,
         fs,

crates/rspack_storage/src/filesystem/meta.rs

@@ -75,7 +75,7 @@ impl Meta {
     Ok(())
   }
 
-  /// Updates the active version and removes versions rejected by age or generation limits.
+  /// Updates the active version and removes versions rejected by age or version limits.
   ///
   /// Returns `(removed_versions, next_check_time)`.
   /// - `removed_versions`: version directories that should be deleted.
@@ -84,7 +84,7 @@ impl Meta {
     &mut self,
     active_version: &str,
     expire_seconds: u64,
-    max_generations: u32,
+    max_versions: u32,
     versions: &[String],
   ) -> Result<(Vec<String>, u64)> {
     let now = Self::current_timestamp();
@@ -110,9 +110,9 @@ impl Meta {
       });
     }
 
-    if max_generations != 0 {
+    if max_versions != 0 {
       // `versions` is already scoped to the current storage directory, so every
-      // non-hidden, non-active entry is a generation candidate.
+      // non-hidden, non-active entry is a version candidate.
       let mut candidates = versions
         .iter()
         .filter(|version| version.as_str() != active_version && !version.starts_with(['_', '.']))
@@ -123,10 +123,8 @@ impl Meta {
           )
         })
         .collect::<Vec<_>>();
-      let retained_inactive_generations = max_generations.saturating_sub(1) as usize;
-      let remove_count = candidates
-        .len()
-        .saturating_sub(retained_inactive_generations);
+      let retained_inactive_versions = max_versions.saturating_sub(1) as usize;
+      let remove_count = candidates.len().saturating_sub(retained_inactive_versions);
       candidates.sort_unstable_by(|(version_a, timestamp_a), (version_b, timestamp_b)| {
         timestamp_a
           .cmp(timestamp_b)

crates/rspack_storage/src/filesystem/mod.rs

@@ -19,7 +19,7 @@ async fn refresh_metadata(
   fs: ScopeFileSystem,
   version: String,
   expire: u64,
-  max_generations: u32,
+  max_versions: u32,
   next_meta_refresh_time: Arc<Mutex<u64>>,
 ) {
   let now = Meta::current_timestamp();
@@ -37,7 +37,7 @@ async fn refresh_metadata(
   // sync with versions that still exist on disk.
   let versions = fs.list_child().await.unwrap_or_default();
   let Ok((removed_versions, next_refresh_time)) = meta
-    .refresh(&version, expire, max_generations, &versions)
+    .refresh(&version, expire, max_versions, &versions)
     .await
   else {
     return;
@@ -120,12 +120,12 @@ impl Storage for FileSystemStorage {
     let fs = self.fs.clone();
     let version = self.options.version.clone();
     let expire = self.options.expire;
-    let max_generations = self.options.max_generations;
+    let max_versions = self.options.max_versions;
     let next_meta_refresh_time = self.next_meta_refresh_time.clone();
 
     self.task_queue.add_task(async move {
       if db.save(changes, max_pack_size).await {
-        refresh_metadata(fs, version, expire, max_generations, next_meta_refresh_time).await;
+        refresh_metadata(fs, version, expire, max_versions, next_meta_refresh_time).await;
       }
     });
   }

crates/rspack_storage/src/filesystem/options.rs

@@ -15,8 +15,8 @@ pub struct FileSystemOptions {
   pub max_pack_size: usize,
   /// Data expiration time (seconds), 0 means never expire
   pub expire: u64,
-  /// Maximum number of generations retained in the storage directory. 0 means disabled.
-  pub max_generations: u32,
+  /// Maximum number of versions retained in the storage directory. 0 means disabled.
+  pub max_versions: u32,
   /// File system implementation
   pub fs: Arc<dyn IntermediateFileSystem>,
 }

packages/rspack/src/config/adapter.ts

@@ -128,14 +128,11 @@ function getRawCache(cache: CacheNormalized): RawOptions['cache'] {
   };
   return {
     ...cache,
+    maxAge: toRawStorageLimit('cache.maxAge', cache.maxAge!),
+    maxVersions: toRawStorageLimit('cache.maxVersions', cache.maxVersions!),
     storage: {
       ...cache.storage,
       directory: cache.storage.directory!,
-      maxAge: toRawStorageLimit('cache.storage.maxAge', cache.storage.maxAge!),
-      maxGenerations: toRawStorageLimit(
-        'cache.storage.maxGenerations',
-        cache.storage.maxGenerations!,
-      ),
     },
     snapshot: {
       immutablePaths: cache.snapshot.immutablePaths!,

packages/rspack/src/config/defaults.ts

@@ -230,13 +230,13 @@ const applyCacheDefaults = (
       break;
     case 'persistent':
       D(cache, 'version', '');
+      D(cache, 'maxAge', DEFAULT_FILESYSTEM_CACHE_MAX_AGE_SECONDS);
+      D(cache, 'maxVersions', 3);
       F(cache, 'buildDependencies', () => []);
       F(cache.snapshot, 'immutablePaths', () => []);
       F(cache.snapshot, 'unmanagedPaths', () => []);
       F(cache.snapshot, 'managedPaths', () => [/[\\/]node_modules[\\/][^.]/]);
       D(cache.storage, 'type', 'filesystem');
-      D(cache.storage, 'maxAge', DEFAULT_FILESYSTEM_CACHE_MAX_AGE_SECONDS);
-      D(cache.storage, 'maxGenerations', 3);
       F(cache.storage, 'directory', () => {
         const modeName = mode || 'production';
         const compilerName = name ? `${name}-${modeName}` : modeName;