feat: wip

Author: Julien-R44

packages/bentocache/package.json

@@ -75,6 +75,7 @@
     "@boringnode/bus": "^0.7.0",
     "@julr/utils": "^1.6.2",
     "@poppinss/utils": "^6.9.2",
+    "@standard-schema/spec": "^1.0.0",
     "async-mutex": "^0.5.0",
     "hexoid": "^2.0.0",
     "lru-cache": "^11.0.2",
@@ -98,7 +99,8 @@
     "pino": "^9.6.0",
     "pino-loki": "^2.5.0",
     "sqlite3": "^5.1.7",
-    "superjson": "^2.2.2"
+    "superjson": "^2.2.2",
+    "zod": "^3.24.1"
   },
   "prettier": "@julr/tooling-configs/prettier",
   "publishConfig": {

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

@@ -3,7 +3,7 @@ import { is } from '@julr/utils/is'
 
 import { errors } from '../../errors.js'
 import { resolveTtl } from '../../helpers.js'
-import type { Duration, RawCommonOptions } from '../../types/main.js'
+import type { Duration, RawCommonOptions, ValidateOption } from '../../types/main.js'
 
 const toId = hexoid(12)
 
@@ -18,6 +18,38 @@ function resolveGrace(options: RawCommonOptions) {
   return resolveTtl(options.grace, null) ?? 0
 }
 
+/**
+ * Resolve validator
+ */
+function resolveValidate(options: RawCommonOptions & ValidateOption) {
+  const validate = options.validate
+  if (!validate) return (value: unknown) => value
+
+  if (typeof validate === 'function') {
+    return (value: unknown) => {
+      try {
+        validate(value)
+      } catch (error) {
+        throw new errors.E_VALIDATION_ERROR(error, { cause: error })
+      }
+
+      return value
+    }
+  }
+
+  if (validate && '~standard' in validate) {
+    return (value: unknown) => {
+      const result = validate['~standard'].validate(value)
+      if (result instanceof Promise) throw new TypeError('Validation must be synchronous')
+      if (result.issues) throw new errors.E_VALIDATION_ERROR(result.issues)
+
+      return result.value
+    }
+  }
+
+  return () => true
+}
+
 /**
  * Cache Entry Options. Define how a cache operation should behave
  *
@@ -27,7 +59,7 @@ function resolveGrace(options: RawCommonOptions) {
  * fake class to have way better performance.
  */
 export function createCacheEntryOptions(
-  newOptions: RawCommonOptions = {},
+  newOptions: RawCommonOptions & ValidateOption = {},
   defaults: Partial<RawCommonOptions> = {},
 ) {
   const options = { ...defaults, ...newOptions }
@@ -91,6 +123,7 @@ export function createCacheEntryOptions(
     lockTimeout,
     onFactoryError: options.onFactoryError ?? defaults.onFactoryError,
     suppressL2Errors: options.suppressL2Errors,
+    validate: resolveValidate(options),
 
     /**
      * Returns a new instance of `CacheItemOptions` with the same

packages/bentocache/src/cache/cache_stack.ts

@@ -112,9 +112,10 @@ export class CacheStack extends BaseDriver {
    */
   async set(key: string, value: any, options: ReturnType<typeof createCacheEntryOptions>) {
     if (is.undefined(value)) throw new UndefinedValueError(key)
+    const validatedValue = options.validate(value)
 
     const rawItem = {
-      value,
+      value: validatedValue,
       logicalExpiration: options.logicalTtlFromNow(),
     }
 
@@ -133,7 +134,7 @@ export class CacheStack extends BaseDriver {
     }
 
     await this.publish({ type: CacheBusMessageType.Set, keys: [key] })
-    this.emit(cacheEvents.written(key, value, this.name))
+    this.emit(cacheEvents.written(key, validatedValue, this.name))
     return true
   }
 }

packages/bentocache/src/cache/factory_runner.ts

@@ -41,6 +41,8 @@ export class FactoryRunner {
       await this.#stack.set(key, result, options)
       return result
     } catch (error) {
+      if (error instanceof errors.E_VALIDATION_ERROR) throw error
+
       if (!isBackground) throw new errors.E_FACTORY_ERROR(key, error)
 
       options.onFactoryError?.(new errors.E_FACTORY_ERROR(key, error, true))

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

@@ -43,7 +43,7 @@ export class SingleTierHandler {
     this.logger.trace({ key, cache: this.stack.name, opId: options.id }, 'remote cache hit')
 
     this.#emit(cacheEvents.hit(key, item.getValue(), this.stack.name))
-    return item.getValue()
+    return options.validate(item.getValue())
   }
 
   /**

packages/bentocache/src/errors.ts

@@ -1,4 +1,6 @@
+import { is } from '@julr/utils/is'
 import { Exception } from '@poppinss/utils/exception'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 /**
  * Thrown when a factory has timed out after waiting for soft timeout
@@ -70,8 +72,39 @@ export class UndefinedValueError extends Exception {
   }
 }
 
+/**
+ * Thrown when a validation fails
+ */
+export class ValidationError extends Exception {
+  static code = 'E_VALIDATION_ERROR'
+
+  #isStandardIssues(error: any): error is ReadonlyArray<StandardSchemaV1.Issue> {
+    return is.array(error) && is.object(error[0]) && 'message' in error[0]
+  }
+
+  #formatStandardIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>) {
+    return (
+      '\n' + issues.map((issue) => `- ${issue.message} at "${issue.path?.join('.')}"`).join('\n')
+    )
+  }
+
+  constructor(error: ReadonlyArray<StandardSchemaV1.Issue> | any, options?: ErrorOptions) {
+    super()
+
+    if (this.#isStandardIssues(error)) {
+      this.message = this.#formatStandardIssues(error)
+    } else {
+      this.message = error
+    }
+
+    this.cause = options?.cause
+  }
+}
+
 export const errors = {
   E_FACTORY_ERROR: FactoryError,
   E_FACTORY_SOFT_TIMEOUT: FactorySoftTimeout,
   E_FACTORY_HARD_TIMEOUT: FactoryHardTimeout,
+  E_UNDEFINED_VALUE: UndefinedValueError,
+  E_VALIDATION_ERROR: ValidationError,
 }

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

@@ -1,13 +1,23 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
 import type { FactoryError } from '../../errors.js'
 import type { Factory, GetSetFactory, RawCommonOptions } from '../main.js'
 
+/**
+ * Validate option
+ */
+export type ValidateOption = {
+  validate?: StandardSchemaV1 | ((value: unknown) => void)
+}
+
 /**
  * Options accepted by the `getOrSet` method
  */
 export type SetCommonOptions = Pick<
   RawCommonOptions,
   'grace' | 'graceBackoff' | 'suppressL2Errors' | 'lockTimeout' | 'ttl' | 'timeout' | 'hardTimeout'
->
+> &
+  ValidateOption
 
 /**
  * Options accepted by the `getOrSet` method when passing an object
@@ -24,10 +34,12 @@ export type GetOrSetOptions<T> = {
 export type GetOrSetForeverOptions<T> = {
   key: string
   factory: GetSetFactory<T>
+  onFactoryError?: (error: FactoryError) => void
 } & Pick<
   RawCommonOptions,
   'grace' | 'graceBackoff' | 'suppressL2Errors' | 'lockTimeout' | 'timeout' | 'hardTimeout'
->
+> &
+  ValidateOption
 
 /**
  * Options accepted by the `set` method
@@ -40,7 +52,8 @@ export type SetOptions = { key: string; value: any } & SetCommonOptions
 export type GetOptions<T> = { key: string; defaultValue?: Factory<T> } & Pick<
   RawCommonOptions,
   'grace' | 'graceBackoff' | 'suppressL2Errors'
->
+> &
+  ValidateOption
 
 /**
  * Options accepted by the `delete` method when passing an object

packages/bentocache/tests/bento_cache.spec.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod'
 import Emittery from 'emittery'
 import { Redis } from 'ioredis'
 import { test } from '@japa/runner'

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

@@ -0,0 +1,108 @@
+import { z } from 'zod'
+import { test } from '@japa/runner'
+import { is } from '@julr/utils/is'
+
+import { errors } from '../../src/errors.js'
+import { CacheFactory } from '../../factories/cache_factory.js'
+
+test.group('Validation', () => {
+  test('works with standard schema', async ({ assert }) => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+
+    await assert.rejects(async () => {
+      await cache.set({
+        key: 'foo',
+        value: { foo: 3 },
+        validate: z.object({ foo: z.string(), bar: z.number() }),
+      })
+      // @ts-ignore
+    }, errors.E_VALIDATION_ERROR)
+  })
+
+  test('works with fn', async ({ assert }) => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+
+    await assert.rejects(async () => {
+      await cache.set({
+        key: 'foo',
+        value: { foo: 3 },
+        validate: (value) => {
+          if (!is.plainObject(value)) {
+            throw new TypeError('Value must be an object')
+          }
+
+          if (typeof value.foo !== 'string') {
+            throw new TypeError('Value must be a string')
+          }
+        },
+      })
+      // @ts-ignore
+    }, errors.E_VALIDATION_ERROR)
+  })
+
+  test('doesnt throw when validation passes', async () => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+
+    await cache.set({
+      key: 'foo',
+      value: { foo: '3' },
+      validate: z.object({ foo: z.string() }),
+    })
+
+    await cache.set({
+      key: 'foo',
+      value: { foo: '3' },
+      validate: (value) => {
+        if (!is.plainObject(value)) throw new TypeError('Value must be an object')
+        if (typeof value.foo !== 'string') throw new TypeError('Value must be a string')
+      },
+    })
+  })
+
+  test('cache object transformed by schema', async ({ assert }) => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+
+    await cache.set({
+      key: 'foo',
+      value: { foo: 'wesh' },
+      validate: z.object({ foo: z.string().toUpperCase() }),
+    })
+
+    const r1 = await cache.get({ key: 'foo' })
+    assert.deepEqual(r1, { foo: 'WESH' })
+  })
+
+  test('works with getOrSet', async ({ assert }) => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+
+    await assert.rejects(async () => {
+      await cache.getOrSet({
+        key: 'foo',
+        factory: () => ({ foo: 3 }),
+        validate: z.object({ foo: z.string() }),
+      })
+      // @ts-ignore
+    }, errors.E_VALIDATION_ERROR)
+
+    const r1 = await cache.get({ key: 'foo' })
+    assert.isUndefined(r1)
+
+    await cache.getOrSet({
+      key: 'foo',
+      factory: () => ({ foo: 'foo' }),
+      validate: z.object({ foo: z.string() }),
+    })
+  })
+
+  test('validate when fetching from getOrSet', async () => {
+    const { cache } = new CacheFactory().withL1L2Config().create()
+
+    await cache.set({ key: 'foo', value: { foo: 3 } })
+
+    await cache.getOrSet({
+      key: 'foo',
+      factory: () => ({ foo: 'foo' }),
+      validate: z.object({ foo: z.string() }),
+    })
+  })
+})