feat: add serialize option to memory driver

Author: Julien-R44

.changeset/kind-forks-repeat.md

@@ -0,0 +1,10 @@
+---
+'bentocache': minor
+---
+
+Added a `serialize: false` to the memory driver. 
+
+It means that, the data stored in the memory cache will not be serialized/parsed using `JSON.stringify` and `JSON.parse`. This allows for a much faster throughput but at the expense of:
+- not being able to limit the size of the stored data, because we can't really know the size of an unserialized object
+- Having inconsistent return between the L1 and L2 cache. The data stored in the L2 Cache will always be serialized because it passes over the network. Therefore, depending on whether the data is retrieved from the L1 and L2, we can have data that does not have the same form. For example, a Date instance will become a string if retrieved from the L2, but will remain a Date instance if retrieved from the L1. So, you should put extra care when using this feature with an additional L2 cache.
+

docs/content/docs/cache_drivers.md

@@ -111,9 +111,19 @@ const bento = new BentoCache({
 | `maxSize`      | The maximum size of the cache **in bytes**.                                                                                                          | N/A     |
 | `maxItems`     | The maximum number of entries that the cache can contain. Note that fewer items may be stored if you are also using `maxSize` and the cache is full. | N/A     |
 | `maxEntrySize` | The maximum size of a single entry in bytes.                                                                                                         | N/A     |
+| `serialize`    | If the data stored in the memory cache should be serialized/parsed using `JSON.stringify` and `JSON.parse`.                                          | `true`  |
 
 `maxSize` and `maxEntrySize` accept human-readable strings. We use [bytes](https://www.npmjs.com/package/bytes) under the hood so make sure to ensure the format is correct. A `number` can also be passed to these options.
 
+### `serialize` option
+
+By default, the data stored in the memory cache will always be serialized using `JSON.stringify` and `JSON.parse`.
+You can disable this feature by setting `serialize` to `false`. This allows for a much faster throughput but at the expense of:
+- not being able to limit the size of the stored data, because we can't really know the size of an unserialized object. So if `maxSize` or `maxEntrySize` is set, it throws an error, but you still can use `maxItems` option.
+- **Having inconsistent return between the L1 and L2 cache**. The data stored in the L2 Cache will always be serialized because it passes over the network. Therefore, depending on whether the data is retrieved from the L1 and L2, we can have data that does not have the same form. For example, a Date instance will become a string if retrieved from the L2, but will remain a Date instance if retrieved from the L1. So, **you should put extra care when using this feature with an additional L2 cache**.
+
+We recommend never storing anything that is not serializable in the memory cache when an L2 cache is used ( `Date`, `Map`, classes instances, functions etc.. ). However, if you are only using the memory cache, it is safe to store anything you.
+
 ## DynamoDB
 
 DynamoDB is also supported by bentocache. You will need to install `@aws-sdk/client-dynamodb` to use this driver.

packages/bentocache/factories/cache_factory.ts

@@ -6,9 +6,9 @@ import { MemoryTransport } from '@boringnode/bus/transports/memory'
 import { Cache } from '../src/cache/cache.js'
 import { RedisDriver } from '../src/drivers/redis.js'
 import { MemoryDriver } from '../src/drivers/memory.js'
-import type { CacheStackDrivers } from '../src/types/main.js'
 import { CacheStack } from '../src/cache/stack/cache_stack.js'
 import { BentoCacheOptions } from '../src/bento_cache_options.js'
+import type { CacheStackDrivers, MemoryConfig } from '../src/types/main.js'
 import type { RawBentoCacheOptions } from '../src/types/options/options.js'
 
 /**
@@ -17,6 +17,7 @@ import type { RawBentoCacheOptions } from '../src/types/options/options.js'
  */
 export class CacheFactory {
   #parameters: Partial<RawBentoCacheOptions & CacheStackDrivers> = {}
+  #l1Options: MemoryConfig = {}
   enabledL1L2Config: boolean = false
 
   #cleanupCache(cache: Cache) {
@@ -40,7 +41,7 @@ export class CacheFactory {
       emitter: this.#parameters.emitter,
       lockTimeout: this.#parameters.lockTimeout,
       serializer: this.#parameters.serializer,
-    })
+    }).serializeL1Cache(this.#l1Options.serialize ?? true)
 
     const stack = new CacheStack('primary', options, {
       l1Driver: this.#parameters.l1Driver,
@@ -63,8 +64,9 @@ export class CacheFactory {
   /**
    * Adds a Memory L1 driver to the cache stack
    */
-  withMemoryL1() {
-    this.#parameters.l1Driver = new MemoryDriver({ maxSize: 100_000, prefix: 'test' })
+  withMemoryL1(options: MemoryConfig = {}) {
+    this.#l1Options = options
+    this.#parameters.l1Driver = new MemoryDriver({ prefix: 'test', ...options })
     return this
   }
 

packages/bentocache/src/bento_cache.ts

@@ -59,7 +59,10 @@ export class BentoCache<KnownCaches extends Record<string, BentoStore>> implemen
 
   #createProvider(cacheName: string, store: BentoStore): CacheProvider {
     const entry = store.entry
-    const driverItemOptions = this.#options.cloneWith(entry.options)
+    const driverItemOptions = this.#options
+      .cloneWith(entry.options)
+      .serializeL1Cache(entry.l1?.options.serialize ?? true)
+
     const cacheStack = new CacheStack(cacheName, driverItemOptions, {
       l1Driver: entry.l1?.factory({ prefix: driverItemOptions.prefix, ...entry.l1.options }),
       l2Driver: entry.l2?.factory({ prefix: driverItemOptions.prefix, ...entry.l2.options }),

packages/bentocache/src/bento_cache_options.ts

@@ -72,6 +72,11 @@ export class BentoCacheOptions {
    */
   lockTimeout?: Duration = null
 
+  /**
+   * If the L1 cache should be serialized
+   */
+  serializeL1: boolean = true
+
   constructor(options: RawBentoCacheOptions) {
     this.#options = lodash.merge({}, this, options)
 
@@ -86,9 +91,15 @@ export class BentoCacheOptions {
 
     this.emitter = this.#options.emitter!
     this.serializer = this.#options.serializer ?? defaultSerializer
+
     this.logger = this.#options.logger!.child({ pkg: 'bentocache' })
   }
 
+  serializeL1Cache(shouldSerialize: boolean = true) {
+    this.serializeL1 = shouldSerialize
+    return this
+  }
+
   cloneWith(options: RawBentoCacheOptions) {
     const newOptions = lodash.merge({}, this.#options, options)
     return new BentoCacheOptions(newOptions)

packages/bentocache/src/cache/cache_entry/cache_entry.ts

@@ -21,9 +21,9 @@ export class CacheEntry {
    */
   #logicalExpiration: number
 
-  #serializer: CacheSerializer
+  #serializer?: CacheSerializer
 
-  constructor(key: string, item: Record<string, any>, serializer: CacheSerializer) {
+  constructor(key: string, item: Record<string, any>, serializer?: CacheSerializer) {
     this.#key = key
     this.#value = item.value
     this.#logicalExpiration = item.logicalExpiration
@@ -46,8 +46,10 @@ export class CacheEntry {
     return Date.now() >= this.#logicalExpiration
   }
 
-  static fromDriver(key: string, item: string, serializer: CacheSerializer) {
-    return new CacheEntry(key, serializer.deserialize(item), serializer)
+  static fromDriver(key: string, item: string | Record<string, any>, serializer?: CacheSerializer) {
+    if (!serializer && typeof item !== 'string') return new CacheEntry(key, item, serializer)
+
+    return new CacheEntry(key, serializer!.deserialize(item) ?? item, serializer)
   }
 
   applyBackoff(duration: number) {
@@ -61,9 +63,9 @@ export class CacheEntry {
   }
 
   serialize() {
-    return this.#serializer.serialize({
-      value: this.#value,
-      logicalExpiration: this.#logicalExpiration,
-    })
+    const raw = { value: this.#value, logicalExpiration: this.#logicalExpiration }
+
+    if (this.#serializer) return this.#serializer.serialize(raw)
+    return raw
   }
 }

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

@@ -9,9 +9,9 @@ import type { Logger, L1CacheDriver, CacheSerializer } from '../../types/main.js
 export class LocalCache {
   #driver: L1CacheDriver
   #logger: Logger
-  #serializer: CacheSerializer
+  #serializer: CacheSerializer | undefined
 
-  constructor(driver: L1CacheDriver, logger: Logger, serializer: CacheSerializer) {
+  constructor(driver: L1CacheDriver, logger: Logger, serializer: CacheSerializer | undefined) {
     this.#driver = driver
     this.#serializer = serializer
     this.#logger = logger.child({ context: 'bentocache.localCache' })
@@ -41,7 +41,7 @@ export class LocalCache {
   /**
    * Set a new item in the local cache
    */
-  set(key: string, value: string, options: CacheEntryOptions) {
+  set(key: string, value: any, options: CacheEntryOptions) {
     /**
      * If grace period is disabled and Physical TTL is 0 or less, we can just delete the item.
      */
@@ -78,7 +78,7 @@ export class LocalCache {
     if (value === undefined) return
 
     const newEntry = CacheEntry.fromDriver(key, value, this.#serializer).expire().serialize()
-    return this.#driver.set(key, newEntry, this.#driver.getRemainingTtl(key))
+    return this.#driver.set(key, newEntry as any, this.#driver.getRemainingTtl(key))
   }
 
   /**

packages/bentocache/src/cache/stack/cache_stack.ts

@@ -39,7 +39,11 @@ export class CacheStack extends BaseDriver {
     this.logger = options.logger.child({ cache: this.name })
 
     if (drivers.l1Driver)
-      this.l1 = new LocalCache(drivers.l1Driver, this.logger, this.options.serializer)
+      this.l1 = new LocalCache(
+        drivers.l1Driver,
+        this.logger,
+        this.options.serializeL1 ? this.options.serializer : undefined,
+      )
     if (drivers.l2Driver)
       this.l2 = new RemoteCache(drivers.l2Driver, this.logger, this.options.serializer, !!this.l1)
 
@@ -99,14 +103,6 @@ export class CacheStack extends BaseDriver {
     return this.emitter.emit(event.name, event.data)
   }
 
-  serialize(value: any) {
-    return this.options.serializer.serialize(value)
-  }
-
-  deserialize(value: string) {
-    return this.options.serializer.deserialize(value)
-  }
-
   /**
    * Write a value in the cache stack
    * - Set value in local cache
@@ -117,12 +113,13 @@ export class CacheStack extends BaseDriver {
   async set(key: string, value: any, options: CacheEntryOptions) {
     if (is.undefined(value)) throw new UndefinedValueError(key)
 
-    const item = this.serialize({
+    const rawItem = {
       value,
       logicalExpiration: options.logicalTtlFromNow(),
-    })
+    }
+    const item = this.options.serializer.serialize(rawItem)
 
-    this.l1?.set(key, item, options)
+    this.l1?.set(key, this.options.serializeL1 ? item : rawItem, options)
     await this.l2?.set(key, item, options)
     await this.publish({ type: CacheBusMessageType.Set, keys: [key] })
 

packages/bentocache/src/drivers/memory.ts

@@ -1,5 +1,6 @@
 import { LRUCache } from 'lru-cache'
 import { bytes } from '@julr/utils/string/bytes'
+import { InvalidArgumentsException } from '@poppinss/utils'
 
 import { BaseDriver } from './base_driver.js'
 import type {
@@ -34,6 +35,12 @@ export class MemoryDriver extends BaseDriver implements L1CacheDriver {
       return
     }
 
+    if (config.serialize === false && (config.maxEntrySize || config.maxSize)) {
+      throw new InvalidArgumentsException(
+        'Cannot use maxSize or maxEntrySize when serialize is set to `false`',
+      )
+    }
+
     this.#cache = new LRUCache({
       max: config.maxItems ?? 1000,
       maxEntrySize: config.maxEntrySize ? bytes.parse(config.maxEntrySize) : undefined,

packages/bentocache/src/types/options/drivers_options.ts

@@ -78,6 +78,21 @@ export type MemoryConfig = {
    * it will NOT be stored
    */
   maxEntrySize?: Bytes
+
+  /**
+   * Should the entries be serialized before storing
+   * them in the cache.
+   *
+   * Note that, if unset, you cannot use maxSize or maxEntrySize
+   * since the size of deserialized objects cannot be calculated.
+   *
+   * **Also make sure to read the below documentation. This option
+   * can cause issues if not used correctly.**
+   *
+   * @see http://bentocache.dev/docs/cache-drivers#serialize-option
+   * @default true
+   */
+  serialize?: boolean
 } & DriverCommonOptions
 
 /**