feat:a add fail and skip methods to factory ctx

Author: Julien-R44

.changeset/curvy-poets-attack.md

@@ -0,0 +1,32 @@
+---
+'bentocache': minor
+---
+
+Add two new functions in the factory callback context:
+
+```ts
+cache.getOrSet({
+  key: 'foo',
+  factory: ({ skip, fail }) => {
+    const item = await getFromDb()
+    if (!item) {
+      return skip()
+    }
+
+    if (item.isInvalid) {
+      return fail('Item is invalid')
+    }
+
+    return item
+  }
+})
+```
+
+## Skip
+
+Returning `skip` in a factory will not cache the value, and `getOrSet` will returns `undefined` even if there is a stale item in cache.
+It will force the key to be recalculated on the next call.
+
+## Fail
+
+Returning `fail` in a factory will not cache the value and will throw an error. If there is a stale item in cache, it will be used.

packages/bentocache/src/cache/factory_runner.ts

@@ -13,6 +13,7 @@ import type { CacheEntryOptions } from './cache_entry/cache_entry_options.js'
 export class FactoryRunner {
   #locks: Locks
   #stack: CacheStack
+  #skipSymbol = Symbol('bentocache.skip')
 
   constructor(stack: CacheStack, locks: Locks) {
     this.#stack = stack
@@ -29,8 +30,14 @@ export class FactoryRunner {
     try {
       const result = await factory({
         setTtl: (ttl) => options.setLogicalTtl(ttl),
+        skip: () => this.#skipSymbol as any as undefined,
+        fail: (message) => {
+          throw new Error(message ?? 'Factory failed')
+        },
       })
 
+      if (result === this.#skipSymbol) return
+
       await this.#stack.set(key, result, options)
       return result
     } catch (error) {

packages/bentocache/src/types/helpers.ts

@@ -12,18 +12,30 @@ export type Duration = number | string | null
  */
 export type Factory<T = any> = T | (() => T) | Promise<T> | (() => Promise<T>)
 
-export type GetSetFactoryOptions = {
+export type GetSetFactoryContext = {
   /**
-   * Set dynamically the TTL
-   * See Adaptive caching documentation for more information
+   * Dynamically set the TTL
+   * @see https://bentocache.dev/docs/adaptive-caching
    */
   setTtl: (ttl: Duration) => void
+
+  /**
+   * Make the factory fail with a custom error.
+   * Nothing will be cached and if a graced value is available, it will be returned
+   */
+  fail: (message?: string) => void
+
+  /**
+   * Make the factory do not cache anything. **If a graced value is available,
+   * it will not be used**
+   */
+  skip: () => undefined
 }
 
 /**
  * GetOrSet Factory
  */
-export type GetSetFactory<T = any> = (options: GetSetFactoryOptions) => T | Promise<T>
+export type GetSetFactory<T = any> = (options: GetSetFactoryContext) => T | Promise<T>
 
 /**
  * Logger interface

packages/bentocache/tests/cache/fail.spec.ts

@@ -0,0 +1,31 @@
+import { test } from '@japa/runner'
+import { sleep } from '@julr/utils/misc'
+
+import { sequentialFactory } from '../helpers/index.js'
+import { CacheFactory } from '../../factories/cache_factory.js'
+
+test.group('Fail', () => {
+  test('should use graced value', async ({ assert }) => {
+    const { cache } = new CacheFactory()
+      .merge({ grace: '2m', timeout: '2s' })
+      .withL1L2Config()
+      .create()
+
+    const factory = sequentialFactory([() => 'foo', ({ fail }) => fail('error')])
+
+    const r1 = await cache.getOrSet({ ttl: 100, key: 'foo', factory })
+    await sleep(100)
+    const r2 = await cache.getOrSet({ key: 'foo', factory })
+
+    assert.deepEqual(factory.callsCount(), 2)
+    assert.deepEqual(r1, 'foo')
+    assert.deepEqual(r2, 'foo')
+  })
+
+  test('throw error if no graced value', async ({ assert }) => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+    const factory = sequentialFactory([({ fail }) => fail()])
+
+    await assert.rejects(() => cache.getOrSet({ key: 'foo', factory }))
+  })
+})

packages/bentocache/tests/cache/skip.spec.ts

@@ -0,0 +1,37 @@
+import { test } from '@japa/runner'
+import { sleep } from '@julr/utils/misc'
+
+import { sequentialFactory } from '../helpers/index.js'
+import { CacheFactory } from '../../factories/cache_factory.js'
+
+test.group('Skip caching', () => {
+  test('do not cache if skip is returned', async ({ assert }) => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+
+    const factory = sequentialFactory([({ skip }) => skip(), () => 'bar'])
+
+    const r1 = await cache.getOrSet({ key: 'foo', factory })
+    const r2 = await cache.getOrSet({ key: 'foo', factory })
+
+    assert.deepEqual(factory.callsCount(), 2)
+    assert.deepEqual(r1, undefined)
+    assert.deepEqual(r2, 'bar')
+  })
+
+  test('do not use graced value if skip is returned', async ({ assert }) => {
+    const { cache } = new CacheFactory()
+      .merge({ timeout: '2s', grace: '2m' })
+      .withL1L2Config()
+      .create()
+
+    const factory = sequentialFactory([() => 'bar', ({ skip }) => skip()])
+
+    const r1 = await cache.getOrSet({ key: 'foo', factory, ttl: 10 })
+    await sleep(50)
+    const r2 = await cache.getOrSet({ key: 'foo', factory })
+
+    assert.deepEqual(factory.callsCount(), 2)
+    assert.deepEqual(r1, 'bar')
+    assert.deepEqual(r2, undefined)
+  })
+})

packages/bentocache/tests/drivers/dynamodb.spec.ts

@@ -14,17 +14,19 @@ const dynamoClient = new DynamoDBClient({
  * Create the table for storing the cache
  */
 async function createTable() {
-  await dynamoClient.send(
-    new CreateTableCommand({
-      TableName: 'cache',
-      KeySchema: [{ AttributeName: 'key', KeyType: 'HASH' }],
-      AttributeDefinitions: [{ AttributeName: 'key', AttributeType: 'S' }],
-      ProvisionedThroughput: {
-        ReadCapacityUnits: 4,
-        WriteCapacityUnits: 4,
-      },
-    }),
-  )
+  await dynamoClient
+    .send(
+      new CreateTableCommand({
+        TableName: 'cache',
+        KeySchema: [{ AttributeName: 'key', KeyType: 'HASH' }],
+        AttributeDefinitions: [{ AttributeName: 'key', AttributeType: 'S' }],
+        ProvisionedThroughput: {
+          ReadCapacityUnits: 4,
+          WriteCapacityUnits: 4,
+        },
+      }),
+    )
+    .catch(() => {})
 }
 
 /**

packages/bentocache/tests/helpers/index.ts

@@ -2,6 +2,8 @@ import { pino } from 'pino'
 import pinoLoki from 'pino-loki'
 import { sleep } from '@julr/utils/misc'
 
+import type { GetSetFactory, GetSetFactoryContext } from '../../src/types/helpers.js'
+
 export const BASE_URL = new URL('./tmp/', import.meta.url)
 export const REDIS_CREDENTIALS = { host: 'localhost', port: 6379 }
 
@@ -51,3 +53,17 @@ export const traceLogger = (pretty = true) => {
     }),
   )
 }
+
+export function sequentialFactory(callbacks: GetSetFactory[]) {
+  let index = 0
+
+  const sequence = (options: GetSetFactoryContext) => {
+    const cb = callbacks[index]
+    index++
+
+    return cb(options)
+  }
+
+  sequence.callsCount = () => index
+  return sequence
+}