feat: create cache method for caching schema output by input

[EskiMojo14]

fixes #923

const cachedSchema = v.cache(baseSchema, { maxSize: 100, duration: 5_000 })

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
valibot	Ready	Preview	Comment	Sep 21, 2025 0:07am

[fabian-hiller]

Thanks for creating this PR. I will probably plan it for v1.2 or v1.3.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/valibot@1170

commit: 6dd73b4

[Copilot]

Pull request overview

This PR introduces a new cache method to optimize schema validation performance by caching schema output based on input values. The implementation includes both synchronous and asynchronous variants with configurable cache options (maxSize, duration) and support for custom cache instances.

Key Changes:

• Adds cache and cacheAsync methods with configurable cache options (maxSize, duration)
• Implements internal _Cache utility class with LRU eviction and expiration support
• Adds comprehensive type definitions including BaseCache, CacheOptions, and schema wrapper types

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
library/src/utils/_Cache/_Cache.ts	Implements internal LRU cache with size limits and time-based expiration
library/src/utils/_Cache/_Cache.test.ts	Test suite for _Cache utility class
library/src/methods/cache/cache.ts	Synchronous cache method implementation
library/src/methods/cache/cacheAsync.ts	Asynchronous cache method implementation
library/src/methods/cache/cache.test.ts	Test suite for synchronous cache method
library/src/methods/cache/cacheAsync.test.ts	Test suite for asynchronous cache method
library/src/methods/cache/types.ts	Type definitions for cache options
library/src/types/other.ts	Adds BaseCache interface for custom implementations
library/package.json	Adds quick-lru dev dependency for testing
pnpm-lock.yaml	Updates lockfile with quick-lru dependency
website/src/routes/api/menu.md	Adds cache methods and types to API menu
website/src/routes/api/(methods)/cache/index.mdx	Documentation for cache method
website/src/routes/api/(async)/cacheAsync/index.mdx	Documentation for cacheAsync method
website/src/routes/api/(types)/BaseCache/index.mdx	Documentation for BaseCache interface
website/src/routes/api/(types)/CacheOptions/index.mdx	Documentation for CacheOptions type
website/src/routes/api/(types)/SchemaWithCache/index.mdx	Documentation for SchemaWithCache type

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fabian-hiller]

Thank you! If I understand correctly, the cache only works for primitive values or complex values with the same reference. Providing a new object as the dataset.value would result in no caching. Is this correct?

[EskiMojo14]

Thank you! If I understand correctly, the cache only works for primitive values or complex values with the same reference. Providing a new object as the dataset.value would result in no caching. Is this correct?

correct, the default cache compares by reference - the user is free to provide a cache implementation with more complex comparisons as long as the same get/set interface is there

[vercel]

@EskiMojo14 is attempting to deploy a commit to the Open Circle Team on Vercel.

A member of the Team first needs to authorize it.