Improving documentation

[Kimblis]

First of all- props for creating this, seems cool so far.
The current problem is lack of documentation. In example you provide some numbers, like ttl, but it never says anywhere - is it seconds, is it milliseconds. Same with stale time.
Better documentation would be really useful.
Also I see exclude models, exclude methods, and then array of models, with nearly same options, so is it like "exclude overall" and exluce partialy?

[yxx4c]

Hi @Kimblis

Thanks for the feedback. You're right; the documentation needs improvement.

To clarify, the ttl and stale values are in seconds. In the example config, the User model has a ttl of 10 seconds and a stale time of 5 seconds.

For excludedModels and excludedOperations:

• excludedModels completely excludes certain models (like Post) from auto-caching.
• excludedOperations specifies operations (like findFirst, count, and findMany) that won't use auto-caching, even for included models.

The models array allows you to customize caching behavior for specific models, letting you set different ttl, stale and excludedOperations values as needed on a per-model basis.

If you'd like to know more about how auto-caching works, the isAutoCacheEnabled function determines whether auto-caching is enabled for a specific operation on a given model. Here's how it works:

1. Check for Explicit Auto-Cache Configuration per query: If the cache property of the query is defined and is a boolean, it returns that value. This allows for explicit control over auto-caching.

2. Validate Auto Caching Logic: If auto config is defined:

   • It first checks if auto config is an object.
   • It then verifies if the operation is included in the excludedOperations list. If it is, caching is disabled for that operation.
   • Next, it checks if the model is in the excludedModels list. If it is, caching is also disabled for that model.
   • Finally, it looks for any specific model configuration in the models array. If the model is found, it checks if the operation is in that model's excludedOperations. If it is, caching is disabled.

3. Default Behavior: If none of the above conditions are met, it returns true, indicating that auto-caching is enabled.

This function provides a flexible way to manage caching behavior based on both global and specific model configurations.

PS: I'll work on updating the documentation to make this clearer. If you have more questions or suggestions, let me know.

[redicides]

I like this extension a lot, and by the looks of it so do other people. I've yet to use it since I've built my own cache system, however, I do wish the documentation was a bit clearer too. Well commented examples/config options would really help.

A specific issue (for me at least) is that the docs don't make it quite clear if the cache is automatically cleared upon a mutation action, e.g delete or update.

[yxx4c]

@redicides,

Thank you for your kind words! I'm thrilled to see that many are interested in the extension. I appreciate your feedback regarding the documentation, and I'm actively working on making it clearer, including adding well-commented examples and configuration options.

To address your specific question, the cache is not automatically cleared when a mutation occurs, such as during a delete or update, unless you provide a key or pattern in the uncacheKeys array inside the uncache option for each query.Please note that uncache can only invalidate items that were cached using the cache option in read operations. I hope this helps clarify things!

[redicides]

Hey! Thanks for taking the time to answer my questions. Out of curiosity, are there any plans on adding auto cache invalidation when a mutation occurs? If that does happen eventually then this extension would become really powerful, as many people want the ability to cache prisma queries without having to manually invalidate results.

[yxx4c]

Hi @redicides,

I’m currently working on enhancing the auto-cache functionality in the extension. To achieve this, I’ll need to develop custom logic that doesn’t rely on async-cache-dedupe. Once I implement this, I plan to incorporate a new feature that utilizes primary keys or unique identifiers in the query’s where clause to invalidate the cache upon mutations. I’m aiming to create a solution that works effectively in most scenarios.

In my view, the best approach to caching is to tailor it to specific needs rather than adapting to the limitations of existing libraries. That’s why I initially created a minimal library focused on flexibility. The request for an auto-cache feature was straightforward and could be handled by async-cache-dedupe, which was added without much trouble. However, as the library’s scope expands to accommodate various use cases, I’m now working on customizing it further.

[brrock]

Just make a docs web page deploy to gh pages and add examples

[yxx4c]

I've made some improvements to the README.md for now and plan to create a dedicated documentation page soon, as soon as I have some time. In the meantime, I will convert this issue into a discussion, and I would greatly appreciate it if you could share any questions or scenarios that I can include and address in the future documentation.