feat: add prune() method (#85)

Author: Julien-R44

.changeset/weak-parts-pull.md

@@ -0,0 +1,5 @@
+---
+'bentocache': minor
+---
+
+Add `prune()` method for cache drivers without native TTL support as an alternative to `pruneInterval` strategy

docs/content/docs/methods.md

@@ -250,6 +250,14 @@ Clear the cache. This will delete all the keys in the cache if called from the "
 await bento.clear();
 ```
 
+## prune
+
+Prunes the cache by removing expired entries. This is useful for drivers that do not have native TTL support, such as File and Database drivers. On drivers with native TTL support, this is typically a noop.
+
+```ts
+await bento.prune();
+```
+
 ## disconnect
 
 Disconnect from the cache. This will close the connection to the cache server, if applicable.

packages/bentocache/src/bento_cache.ts

@@ -241,6 +241,16 @@ export class BentoCache<KnownCaches extends Record<string, BentoStore>> implemen
     return this.use().clear(options)
   }
 
+  /**
+   * Manually prune expired cache entries
+   *
+   * For drivers with native TTL support, this is typically a noop
+   * For drivers without native TTL (PostgreSQL, File), this will remove expired entries
+   */
+  prune(): Promise<void> {
+    return this.use().prune?.() ?? Promise.resolve()
+  }
+
   /**
    * Remove all items from all caches
    */

packages/bentocache/src/cache/cache.ts

@@ -267,6 +267,16 @@ export class Cache implements CacheProvider {
     this.#stack.emit(cacheEvents.cleared(this.name))
   }
 
+  /**
+   * Manually prune expired cache entries
+   *
+   * For drivers with native TTL support, this is typically a noop
+   * For drivers without native TTL (PostgreSQL, File), this will remove expired entries
+   */
+  prune(): Promise<void> {
+    return this.#stack.l2?.prune() ?? Promise.resolve()
+  }
+
   /**
    * Closes the connection to the cache
    */

packages/bentocache/src/cache/facades/remote_cache.ts

@@ -154,6 +154,13 @@ export class RemoteCache {
     })
   }
 
+  /**
+   * Manually prune expired cache entries
+   */
+  prune(): Promise<void> {
+    return this.#driver.prune?.() ?? Promise.resolve()
+  }
+
   /**
    * Disconnect from the remote cache
    */

packages/bentocache/src/drivers/database/database.ts

@@ -166,4 +166,12 @@ export class DatabaseDriver extends BaseDriver implements CacheDriver<true> {
 
     await this.#adapter.disconnect()
   }
+
+  /**
+   * Manually prune expired cache entries.
+   */
+  async prune() {
+    await this.#initializer()
+    await this.#adapter.pruneExpiredEntries()
+  }
 }

packages/bentocache/src/drivers/file/cleaner.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+import { join } from 'node:path'
+import { readdir, unlink, readFile } from 'node:fs/promises'
+
+/**
+ * Read the file content and delete it if it's expired
+ * @param {object} options
+ * @param {string} options.filePath
+ * @param {(err: { filePath: string, error: any }) => void} [options.onError]
+ */
+async function deleteFileIfExpired({ filePath, onError }) {
+  try {
+    const content = await readFile(filePath, 'utf-8')
+    const [, expiresAt] = JSON.parse(content)
+
+    const expiry = new Date(expiresAt).getTime()
+    if (+expiry === -1) return
+
+    if (expiry < Date.now()) await unlink(filePath)
+  } catch (error) {
+    if (onError) onError({ filePath, error })
+  }
+}
+
+/**
+ * Get recursive list of files in the cache directory and delete expired files
+ * @param {object} options
+ * @param {string} options.directory
+ * @param {(err: { filePath: string, error: any }) => void} [options.onError]
+ */
+export async function pruneExpiredFiles({ directory, onError }) {
+  const dirEntries = await readdir(directory, { recursive: true, withFileTypes: true })
+
+  for (const dirEntry of dirEntries) {
+    if (dirEntry.isDirectory()) continue
+
+    const filePath = join(dirEntry.parentPath, dirEntry.name)
+    await deleteFileIfExpired({ filePath, onError })
+  }
+}

packages/bentocache/src/drivers/file/cleaner_worker.js

@@ -1,43 +1,20 @@
 // @ts-check
 
-import { join } from 'node:path'
-import { readdir, unlink, readFile } from 'node:fs/promises'
 import { parentPort, workerData } from 'node:worker_threads'
 
+import { pruneExpiredFiles } from './cleaner.js'
+
 const directory = workerData.directory
 const pruneIntervalInMs = workerData.pruneInterval
 
-/**
- * Read the file content and delete it if it's expired
- *
- * @param {string} filePath
- */
-async function deleteFileIfExpired(filePath) {
-  const content = await readFile(filePath, 'utf-8')
-  const [, expiresAt] = JSON.parse(content)
-
-  const expiry = new Date(expiresAt).getTime()
-  if (+expiry === -1) return
-
-  if (expiry < Date.now()) {
-    await unlink(filePath)
-  }
-}
-
 /**
  * Get recursive list of files in the cache directory and delete expired files
  */
 async function prune() {
-  const dirEntries = await readdir(directory, { recursive: true, withFileTypes: true })
-
-  for (const dirEntry of dirEntries) {
-    if (dirEntry.isDirectory()) continue
-
-    const filePath = join(dirEntry.path, dirEntry.name)
-    await deleteFileIfExpired(filePath).catch((error) => {
-      parentPort?.postMessage({ type: 'error', error })
-    })
-  }
+  await pruneExpiredFiles({
+    directory,
+    onError: (err) => parentPort?.postMessage({ type: 'error', error: err }),
+  })
 }
 
 setInterval(async () => {

packages/bentocache/src/drivers/file/file.ts

@@ -234,4 +234,19 @@ export class FileDriver extends BaseDriver implements CacheDriver {
   async disconnect() {
     await this.#cleanerWorker?.terminate()
   }
+
+  /**
+   * Manually prune expired cache entries by scanning the cache directory
+   * and removing files that have expired.
+   */
+  async prune() {
+    const cacheExists = await this.#pathExists(this.#directory)
+    if (!cacheExists) return
+
+    const { pruneExpiredFiles } = await import('./cleaner.js')
+    await pruneExpiredFiles({
+      directory: this.#directory,
+      onError: (err) => this.config.logger?.error(err),
+    })
+  }
 }

packages/bentocache/src/types/driver.ts

@@ -46,6 +46,14 @@ export interface CacheDriver<Async extends boolean = true> {
    * Some drivers may not need this
    */
   disconnect(): PromiseOr<void, Async>
+
+  /**
+   * Manually prune expired cache entries
+   *
+   * For drivers with native TTL support, this is typically a noop
+   * For drivers without native TTL (PostgreSQL, File), this will remove expired entries
+   */
+  prune?(): PromiseOr<void, Async>
 }
 
 /**