feat: working implementation

Author: Julien-R44

.changeset/rich-mugs-prove.md

@@ -0,0 +1,26 @@
+---
+'bentocache': minor
+---
+
+Add **experimental** tagging support. See https://github.com/Julien-R44/bentocache/issues/53
+
+```ts
+await bento.getOrSet({
+  key: 'foo',
+  factory: getFromDb(),
+  tags: ['tag-1', 'tag-2']
+});
+
+await bento.set({ 
+  key: 'foo',
+  tags: ['tag-1']
+});
+```
+
+Then, we can delete all entries tagged with tag-1 using:
+
+```ts
+await bento.deleteByTags({ tags: ['tag-1'] });
+```
+
+As this is a rather complex feature, let's consider it experimental for now. Please report any bugs on Github issues

packages/bentocache/src/cache/cache.ts

@@ -17,6 +17,7 @@ import type {
   DeleteManyOptions,
   GetOrSetForeverOptions,
   ExpireOptions,
+  DeleteByTagOptions,
 } from '../types/main.js'
 
 export class Cache implements CacheProvider {
@@ -35,6 +36,7 @@ export class Cache implements CacheProvider {
     this.#stack = stack
     this.#options = stack.options
     this.#getSetHandler = new GetSetHandler(this.#stack)
+    this.#stack.setTagSystemGetSetHandler(this.#getSetHandler)
   }
 
   #resolveDefaultValue(defaultValue?: Factory) {
@@ -57,19 +59,21 @@ export class Cache implements CacheProvider {
     this.#options.logger.logMethod({ method: 'get', key, options, cacheName: this.name })
 
     const localItem = this.#stack.l1?.get(key, options)
-    if (localItem?.isGraced === false) {
-      this.#stack.emit(cacheEvents.hit(key, localItem.entry.getValue(), this.name))
+    const isLocalItemValid = await this.#stack.isEntryValid(localItem)
+    if (isLocalItemValid) {
+      this.#stack.emit(cacheEvents.hit(key, localItem!.entry.getValue(), this.name))
       this.#options.logger.logL1Hit({ cacheName: this.name, key, options })
-      return localItem.entry.getValue()
+      return localItem!.entry.getValue()
     }
 
     const remoteItem = await this.#stack.l2?.get(key, options)
+    const isRemoteItemValid = await this.#stack.isEntryValid(remoteItem)
 
-    if (remoteItem?.isGraced === false) {
-      this.#stack.l1?.set(key, remoteItem.entry.serialize(), options)
-      this.#stack.emit(cacheEvents.hit(key, remoteItem.entry.getValue(), this.name))
+    if (isRemoteItemValid) {
+      this.#stack.l1?.set(key, remoteItem!.entry.serialize(), options)
+      this.#stack.emit(cacheEvents.hit(key, remoteItem!.entry.getValue(), this.name))
       this.#options.logger.logL2Hit({ cacheName: this.name, key, options })
-      return remoteItem.entry.getValue()
+      return remoteItem!.entry.getValue()
     }
 
     if (remoteItem && options.isGraceEnabled()) {
@@ -193,6 +197,18 @@ export class Cache implements CacheProvider {
     return true
   }
 
+  /**
+   * Invalidate all keys with the given tags
+   */
+  async deleteByTag(rawOptions: DeleteByTagOptions): Promise<boolean> {
+    const tags = rawOptions.tags
+    const options = this.#stack.defaultOptions.cloneWith(rawOptions)
+
+    this.#options.logger.logMethod({ method: 'deleteByTag', cacheName: this.name, tags, options })
+
+    return await this.#stack.createTagInvalidations(tags)
+  }
+
   /**
    * Delete multiple keys from local and remote cache
    * Then emit cache:deleted events for each key
@@ -222,17 +238,12 @@ export class Cache implements CacheProvider {
    * Entry will not be fully deleted but expired and
    * retained for the grace period if enabled.
    */
-  async expire(rawOptions: ExpireOptions) {
+  expire(rawOptions: ExpireOptions) {
     const key = rawOptions.key
     const options = this.#stack.defaultOptions.cloneWith(rawOptions)
     this.#options.logger.logMethod({ method: 'expire', cacheName: this.name, key, options })
 
-    this.#stack.l1?.logicallyExpire(key, options)
-    await this.#stack.l2?.logicallyExpire(key, options)
-    await this.#stack.publish({ type: CacheBusMessageType.Expire, keys: [key] })
-
-    this.#stack.emit(cacheEvents.expire(key, this.name))
-    return true
+    return this.#stack.expire(key, options)
   }
 
   /**

packages/bentocache/src/cache/cache_stack.ts

@@ -3,12 +3,15 @@ import lodash from '@poppinss/utils/lodash'
 
 import { Bus } from '../bus/bus.js'
 import type { Logger } from '../logger.js'
+import { TagSystem } from './tag_system.js'
 import { UndefinedValueError } from '../errors.js'
 import { LocalCache } from './facades/local_cache.js'
 import { BaseDriver } from '../drivers/base_driver.js'
 import { RemoteCache } from './facades/remote_cache.js'
 import { cacheEvents } from '../events/cache_events.js'
+import type { GetSetHandler } from './get_set/get_set_handler.js'
 import type { BentoCacheOptions } from '../bento_cache_options.js'
+import type { GetCacheValueReturn } from '../types/internals/index.js'
 import type { CacheEntryOptions } from './cache_entry/cache_entry_options.js'
 import { createCacheEntryOptions } from './cache_entry/cache_entry_options.js'
 import {
@@ -28,6 +31,7 @@ export class CacheStack extends BaseDriver {
   logger: Logger
   #busDriver?: BusDriver
   #busOptions?: BusOptions
+  #tagSystem: TagSystem
   #namespaceCache: Map<string, CacheStack> = new Map()
 
   constructor(
@@ -51,6 +55,7 @@ export class CacheStack extends BaseDriver {
     this.bus = bus ? bus : this.#createBus(drivers.busDriver, drivers.busOptions)
     if (this.l1) this.bus?.manageCache(this.prefix, this.l1)
 
+    this.#tagSystem = new TagSystem(this)
     this.defaultOptions = createCacheEntryOptions(this.options)
   }
 
@@ -70,6 +75,10 @@ export class CacheStack extends BaseDriver {
     return new Bus(this.name, this.#busDriver, this.logger, this.emitter, this.#busOptions)
   }
 
+  setTagSystemGetSetHandler(getSetHandler: GetSetHandler) {
+    this.#tagSystem.setGetSetHandler(getSetHandler)
+  }
+
   namespace(namespace: string): CacheStack {
     if (!this.#namespaceCache.has(namespace)) {
       this.#namespaceCache.set(
@@ -143,4 +152,44 @@ export class CacheStack extends BaseDriver {
     this.emit(cacheEvents.written(key, value, this.name))
     return true
   }
+
+  /**
+   * Expire a key from the cache.
+   * Entry will not be fully deleted but expired and
+   * retained for the grace period if enabled.
+   */
+  async expire(key: string, options: CacheEntryOptions) {
+    this.l1?.logicallyExpire(key, options)
+    await this.l2?.logicallyExpire(key, options)
+    await this.publish({ type: CacheBusMessageType.Expire, keys: [key] })
+
+    this.emit(cacheEvents.expire(key, this.name))
+    return true
+  }
+
+  /**
+   * Check if an item is valid.
+   * Valid means :
+   * - Logically not expired ( not graced )
+   * - Not invalidated by a tag
+   */
+  isEntryValid(item: GetCacheValueReturn | undefined): Promise<boolean> | boolean {
+    if (!item) return false
+
+    const isGraced = item?.isGraced === true
+    if (isGraced) return false
+
+    if (item.entry.getTags().length === 0) return true
+
+    return this.#tagSystem.isTagInvalidated(item.entry).then((isTagInvalidated) => {
+      return !isTagInvalidated
+    })
+  }
+
+  /**
+   * Create invalidation keys for a list of tags
+   */
+  async createTagInvalidations(tags: string[]) {
+    return this.#tagSystem.createTagInvalidations(tags)
+  }
 }

packages/bentocache/src/cache/get_set/single_tier_handler.ts

@@ -95,14 +95,13 @@ export class SingleTierHandler {
   }
 
   async handle(key: string, factory: Factory, options: CacheEntryOptions) {
-    let remoteItem: GetCacheValueReturn | undefined
-
     /**
      * Check in the remote cache first if we have something
      */
-    remoteItem = await this.stack.l2?.get(key, options)
-    if (remoteItem?.isGraced === false) {
-      return this.#returnRemoteCacheValue(key, remoteItem, options)
+    let remoteItem = await this.stack.l2?.get(key, options)
+    let isRemoteItemValid = await this.stack.isEntryValid(remoteItem)
+    if (isRemoteItemValid) {
+      return this.#returnRemoteCacheValue(key, remoteItem!, options)
     }
 
     /**
@@ -121,9 +120,10 @@ export class SingleTierHandler {
      * already set the value
      */
     remoteItem = await this.stack.l2?.get(key, options)
-    if (remoteItem?.isGraced === false) {
+    isRemoteItemValid = await this.stack.isEntryValid(remoteItem)
+    if (isRemoteItemValid) {
       this.#locks.release(key, releaser)
-      return this.#returnRemoteCacheValue(key, remoteItem, options)
+      return this.#returnRemoteCacheValue(key, remoteItem!, options)
     }
 
     try {

packages/bentocache/src/cache/get_set/two_tier_handler.ts

@@ -122,9 +122,10 @@ export class TwoTierHandler {
      * could have written a value while we were waiting for the lock.
      */
     localItem = this.stack.l1?.get(key, options)
-    if (localItem?.isGraced === false) {
+    const isLocalItemValid = await this.stack.isEntryValid(localItem)
+    if (isLocalItemValid) {
       this.#locks.release(key, releaser)
-      return this.#returnL1Value(key, localItem)
+      return this.#returnL1Value(key, localItem!)
     }
 
     /**
@@ -133,9 +134,10 @@ export class TwoTierHandler {
      * and returns it.
      */
     const remoteItem = await this.stack.l2?.get(key, options)
-    if (remoteItem?.isGraced === false) {
+    const isRemoteItemValid = await this.stack.isEntryValid(remoteItem)
+    if (isRemoteItemValid) {
       this.#locks.release(key, releaser)
-      return this.#returnRemoteCacheValue(key, remoteItem, options)
+      return this.#returnRemoteCacheValue(key, remoteItem!, options)
     }
 
     try {
@@ -174,14 +176,25 @@ export class TwoTierHandler {
      * First we check the local cache. If we have a valid item, just
      * returns it without acquiring a lock.
      */
-    const item = this.stack.l1?.get(key, options)
-    if (item?.isGraced === false) return this.#returnL1Value(key, item)
+    const localItem = this.stack.l1?.get(key, options)
+    const isLocalItemValid = this.stack.isEntryValid(localItem)
+
+    // A bit nasty, but to keep maximum performance, we avoid async/await here.
+    // Let's check for a better way to handle this later.
+    if (isLocalItemValid instanceof Promise) {
+      return isLocalItemValid.then((valid) => {
+        if (valid) return this.#returnL1Value(key, localItem!)
+        return this.#lockAndHandle(key, factory, options, localItem)
+      })
+    }
+
+    if (isLocalItemValid) return this.#returnL1Value(key, localItem!)
 
     /**
      * Next, delegate to the lock-and-handle async method so we can keep
      * this method synchronous and avoid an overhead of async/await
      * in case we have a valid item in the local cache.
      */
-    return this.#lockAndHandle(key, factory, options, item)
+    return this.#lockAndHandle(key, factory, options, localItem)
   }
 }

packages/bentocache/src/cache/tag_system.ts

@@ -0,0 +1,88 @@
+import type { CacheStack } from './cache_stack.js'
+import type { CacheEntry } from './cache_entry/cache_entry.js'
+import type { GetSetFactoryContext } from '../types/helpers.js'
+import type { GetSetHandler } from './get_set/get_set_handler.js'
+import { createCacheEntryOptions } from './cache_entry/cache_entry_options.js'
+
+export class TagSystem {
+  #getSetHandler!: GetSetHandler
+  #kTagPrefix = '___bc:t:'
+
+  #expireOptions = createCacheEntryOptions({})
+  #getSetTagOptions = createCacheEntryOptions({
+    ttl: '10d',
+    grace: '10d',
+  })
+
+  constructor(private stack: CacheStack) {}
+
+  setGetSetHandler(handler: GetSetHandler) {
+    this.#getSetHandler = handler
+  }
+
+  /**
+   * Get the cache key for a tag
+   */
+  getTagCacheKey(tag: string) {
+    return this.#kTagPrefix + tag
+  }
+
+  /**
+   * Check if a key is a tag key
+   */
+  isTagKey(key: string) {
+    return key.startsWith(this.#kTagPrefix)
+  }
+
+  /**
+   * The GetSet factory when getting a tag from the cache.
+   */
+  #getTagFactory(ctx: GetSetFactoryContext) {
+    const result = ctx.gracedEntry?.value ?? 0
+    if (result === 0) ctx.setOptions({ skipBusNotify: true, skipL2Write: true })
+
+    return result
+  }
+
+  /**
+   * Check if an entry is invalidated by a tag and return true if it is.
+   */
+  async isTagInvalidated(entry?: CacheEntry) {
+    if (!entry) return
+    if (this.isTagKey(entry.getKey())) return false
+
+    const tags = entry.getTags()
+    if (!tags.length) return false
+
+    for (const tag of tags) {
+      const tagExpiration = await this.#getSetHandler.handle(
+        this.getTagCacheKey(tag),
+        this.#getTagFactory,
+        this.#getSetTagOptions.cloneWith({}),
+      )
+
+      if (entry.getCreatedAt() <= tagExpiration) {
+        await this.stack.expire(entry.getKey(), this.#expireOptions)
+        return true
+      }
+    }
+  }
+
+  /**
+   * Create invalidation keys for a list of tags
+   *
+   * We write a `__bc:t:<tag>` key with the current timestamp as value.
+   * When we check if a key is invalidated by a tag, we check if the key
+   * was created before the tag key value.
+   */
+  async createTagInvalidations(tags: string[]) {
+    const now = Date.now()
+
+    for (const tag of new Set(tags)) {
+      const key = this.getTagCacheKey(tag)
+      await this.stack.set(key, now, this.#getSetTagOptions)
+    }
+
+    return true
+  }
+}