chore: updated TSDocs of the Caching Module service + provider (#13696)

packages/core/types/src/caching/index.ts

@@ -1,7 +1,20 @@
 import { IModuleService, ModuleJoinerConfig } from "../modules-sdk"
 
-type Providers = string[] | { id: string; ttl?: number }[]
+type Providers = string[] | { 
+  /**
+   * The ID of the provider to use, as set in `medusa-config.ts`.
+   */
+  id: string;
+  /**
+   * Optional custom time-to-live (TTL) (in seconds) for this provider. If not provided, the default TTL configured
+   * in the provider is used.
+   */ 
+  ttl?: number
+}[]
 
+/**
+ * @since v2.11.0
+ */
 export interface ICachingModuleService extends IModuleService {
   // Static trace methods
   // traceGet: (
@@ -25,37 +38,114 @@ export interface ICachingModuleService extends IModuleService {
   // ) => Promise<any>
 
   /**
-   * This method retrieves data from the cache.
+   * This method retrieves data from the cache. If neither `key` nor `tags` are provided, or the item is not found, `null` is returned.
    * 
-   * @param key - The key of the item to retrieve.
+   * @param param0 - The options for retrieving the item.
-   * @param tags - The tags of the items to retrieve.
+   * @returns The item(s) that was stored in the cache. If no item was found, or neither `key` nor `tags` were provided, `null` is returned.
-   * @param providers - Array of providers to check in order of priority. If not provided,
-   * only the default provider will be used.
    * 
-   *  @returns The item(s) that was stored in the cache. If the item(s) was not found, null will
+   * @example
-   *  be returned.
+   * To retrieve by key:
    * 
+   * ```ts
+   * const data = await cacheModuleService.get({
+   *   key: "products",
+   * }) as { id: string; title: string; }
+   * ```
+   * 
+   * To retrieve by tags:
+   * 
+   * ```ts
+   * const data = await cacheModuleService.get({
+   *   tags: ["products-list"],
+   * }) as { id: string; title: string; }[]
+   * ```
+   *
+   * To retrieve by key from specific providers:
+   * 
+   * ```ts
+   * const data = await cacheModuleService.get({
+   *   key: "products",
+   *   providers: ["caching-redis", "caching-memcached"]
+   * }) as { id: string; title: string; }
+   * ```
+   *
+   * This example will try to get the data from the `caching-redis` provider first, and if not found, it will try to get it from the `caching-memcached` provider.
    */
   get<T>({
     key,
     tags,
     providers,
   }: {
+    /**
+     * The key of the item to retrieve.
+     * If both `key` and `tags` are provided, `key` takes precedence over `tags`.
+     */
     key?: string
+    /**
+     * The tags of the items to retrieve. Tags
+     * are useful to retrieve multiple related items at once.
+     */
     tags?: string[]
+    /**
+     * The providers to retrieve the item(s) from. You can specify an array of provider IDs.
+     * They're checked in the order they're provided in, so make sure to order them based on your priority.
+     * If not provided, the [default provider](https://docs.medusajs.com/infrastructure-modules/caching/providers#default-caching-module-provider) is used.
+     */
     providers?: string[]
   }): Promise<T | null>
 
   /**
    * This method stores data in the cache.
    *
-   * @param key - The key of the item to store.
+   * @param param0 - The options for storing the item.
-   * @param data - The data to store in the cache.
+   * @returns A promise that resolves when the item has been stored.
-   * @param ttl - The time-to-live (TTL in seconds) value in seconds. If not provided, the default TTL value
+   * 
-   * is used. The default value is based on the used Cache Module.
+   * @example
-   * @param tags - The tags of the items to store. can be used for cross invalidation.
+   * To store with key:
-   * @param options - if specified, will be stored with the item(s).
+   * 
-   * @param providers - The providers from which to store the item(s).
+   * ```ts
+   * await cacheModuleService.set({
+   *   key: "products",
+   *   data: { id: "prod_123", title: "Product 123" },
+   * })
+   * ```
+   * 
+   * To store with tags:
+   * 
+   * ```ts
+   * await cacheModuleService.set({
+   *   key: "products-list",
+   *   data: [{ id: "prod_123", title: "Product 123" }],
+   *   tags: ["products"]
+   * })
+   * ```
+   * 
+   * To disable auto-invalidation for the item:
+   * 
+   * ```ts
+   * await cacheModuleService.set({
+   *   key: "products-list",
+   *   data: [{ id: "prod_123", title: "Product 123" }],
+   *   options: { autoInvalidate: false }
+   * })
+   * ```
+   * 
+   * The item is now only invalidated when calling the `clear` method directly with the same key or tags.
+   * 
+   * To store with specific providers:
+   * 
+   * ```ts
+   * await cacheModuleService.set({
+   *   key: "products",
+   *   data: { id: "prod_123", title: "Product 123" },
+   *   providers: [
+   *     "caching-redis",
+   *     { id: "caching-memcached", ttl: 120 } // custom TTL for this provider
+   *   ]
+   * })
+   * ```
+   * 
+   * This example will store the item in both the `caching-redis` and `caching-memcached` providers, with a custom TTL of 120 seconds for the `caching-memcached` provider.
    *
    */
   set({
@@ -66,25 +156,105 @@ export interface ICachingModuleService extends IModuleService {
     options,
     providers,
   }: {
+    /**
+     * The key of the item to store.
+     */
     key: string
+    /**
+     * The data to store in the cache.
+     */
     data: object
+    /**
+     * The time-to-live (TTL in seconds) value in seconds.
+     * If not provided, the default TTL value configured in the provider should be used.
+     */
     ttl?: number
+    /**
+     * The tags of the items to store. Tags are useful to group related items 
+     * together for retrieval or invalidation.
+     */
     tags?: string[]
+    /**
+     * Options for storing the item. The options are stored with the item, allowing you to later match against them when clearing the item.
+     * For example, if you set `autoInvalidate: false`, the item will only be invalidated when calling the `clear` method directly with the same key or tags.
+     */
     options?: {
+      /**
+       * Whether to automatically invalidate the item when related data changes.
+       *
+       * @defaultValue true
+       */
       autoInvalidate?: boolean
     }
+    /**
+     * The providers to store the item(s) in. You can specify an array of provider IDs or an array of objects with provider ID and TTL.
+     * If not provided, the [default provider](https://docs.medusajs.com/infrastructure-modules/caching/providers#default-caching-module-provider) is used.
+     */
     providers?: Providers
   }): Promise<void>
 
   /**
-   * This method clears data from the cache.
+   * This method clears data from the cache. If neither `key` nor `tags` are provided, nothing is cleared.
    * 
-   * @param key - The key of the item to clear.
+   * If no options are specified, all items matching the key or tags are cleared.
-   * @param tags - The tags of the items to clear.
+   * Otherwise, only items matching the options are cleared.
-   * @param options - if specified, invalidate the item(s) that has the value of the given
-   * options stored. e.g you can invalidate the tags X if their options.autoInvalidate is false or not present.
-   * @param providers - The providers from which to clear the item(s).
    * 
+   * For example, if you set `options.autoInvalidate: true`, only items that were set with `options.autoInvalidate: true` are cleared.
+   * Items that were set with `options.autoInvalidate: false` are only cleared when you don't provide any options.
+   *
+   * @param param0 - The options for clearing the item(s).
+   * @returns A promise that resolves when the item(s) have been cleared.
+   *
+   * @example
+   * To clear by key:
+   * 
+   * ```ts
+   * await cacheModuleService.clear({
+   *  key: "products"
+   * })
+   * ```
+   * 
+   * This example will clear the item with the key `products` regardless of its `options.autoInvalidate` value.
+   * 
+   * To clear by tags:
+   * 
+   * ```ts
+   * await cacheModuleService.clear({
+   *  tags: ["products-list"]
+   * })
+   * ```
+   * 
+   * This example will clear all items with the tag `products-list` regardless of their `options.autoInvalidate` value.
+   * 
+   * To clear only items that were set to automatically invalidate:
+   * 
+   * ```ts
+   * await cacheModuleService.clear({
+   *  tags: ["products-list"],
+   *  options: { autoInvalidate: true }
+   * })
+   * ```
+   * 
+   * This example will only clear items with the tag `products-list` that were set with `options.autoInvalidate: true`.
+   * Items that were set with `options.autoInvalidate: false` will not be cleared.
+   * 
+   * :::note
+   * 
+   * Setting `options.autoInvalidate: false` when calling the `clear` method will not clear any items.
+   * To clear items that were set with `options.autoInvalidate: false`, you must call the `clear` method without any options.
+   * 
+   * :::
+   * 
+   * To clear from specific providers:
+   * 
+   * ```ts
+   * await cacheModuleService.clear({
+   *  key: "products",
+   *  providers: ["caching-redis", "caching-memcached"]
+   * })
+   * ```
+   * 
+   * This example will try to clear the data from both the `caching-redis` and `caching-memcached` providers.
    */
   clear({
     key,
@@ -92,21 +262,192 @@ export interface ICachingModuleService extends IModuleService {
     options,
     providers,
   }: {
+    /**
+     * The key of the item to clear.
+     */
     key?: string
+    /**
+     * The tags of the items to clear. Tags
+     * are useful to clear multiple related items at once.
+     */
     tags?: string[]
+    /**
+     * Options for clearing the item(s). The options are matched against the stored options when the item was set.
+     * For example, if the item was set with `autoInvalidate: true`, it will only be cleared if the `autoInvalidate` option is also set to `true`.
+     * If not provided, all items matching the key or tags are cleared regardless of their options.
+     */
     options?: {
+      /**
+       * Whether to clear item(s) that were set to automatically invalidate.
+       */
       autoInvalidate?: boolean
     }
+    /**
+     * The providers from which to clear the item(s). You can specify an array of provider IDs.
+     * If not provided, the [default provider](https://docs.medusajs.com/infrastructure-modules/caching/providers#default-caching-module-provider) is used.
+     */
     providers?: string[]
   }): Promise<void>
 
+  /**
+   * This method computes a cache key based on the input object. It's useful to generate consistent and unique keys for caching.
+   * 
+   * @param input - The input object to compute the key from.
+   * @returns The computed cache key.
+   * 
+   * @example
+   * const key = await cacheModuleService.computeKey({
+   *   id: "prod_123",
+   *   title: "Product 123"
+   * })
+   * // key will be a string like "a1b2c3d4e5f6g7h8i9j0"
+   */
   computeKey(input: object): Promise<string>
 
+  /**
+   * This method computes cache tags based on the input object. It's useful to generate consistent and relevant tags for caching.
+   * 
+   * @param input - The input object to compute the tags from.
+   * @param options - Additional options to influence tag computation.
+   * @returns An array of computed cache tags.
+   * 
+   * @example
+   * const tags = await cacheModuleService.computeTags({
+   *   products: [{ id: "prod_123" }, { id: "prod_456" }],
+   *   category: { id: "cat_123" }
+   * }, {
+   *   operation: "updated"
+   * })
+   * // tags might be ["product-prod_123", "product-prod_456", "category-cat_123"]
+   */
   computeTags(input: object, options?: Record<string, any>): Promise<string[]>
 }
 
+/**
+ * ### constructor
+ *
+ * The constructor allows you to access resources from the module's container using the first parameter,
+ * and the module's options using the second parameter.
+ *
+ * If you're creating a client or establishing a connection with a third-party service, do it in a [Loader](https://docs.medusajs.com/learn/fundamentals/modules/loaders)
+ * and store it in the Module's container. Then, you can access it in your service using the container.
+ * 
+ * :::note[Loader Example]
+ * 
+ * [Initialize MongoDB client in loader and access it in service](https://docs.medusajs.com/learn/fundamentals/modules/loaders#example-register-custom-mongodb-connection).
+ * 
+ * :::
+ *
+ * #### Example
+ *
+ * ```ts
+ * import { ICachingProviderService } from "@medusajs/framework/types"
+ * import { Logger } from "@medusajs/framework/types"
+ *
+ * type InjectedDependencies = {
+ *   logger: Logger
+ *   // assuming you initialized a client
+ *   // in a Loader and stored it in the container
+ *   client: Client
+ * }
+ *
+ * type Options = {
+ *   url: string
+ * }
+ *
+ * class MyCachingModuleProvider implements ICachingProviderService {
+ *   static identifier = "my-cache"
+ *   protected logger_: Logger
+ *   protected options_: Options
+ *   protected client
+ *
+ *   constructor (
+ *     { logger, client }: InjectedDependencies,
+ *     options: Options
+ *   ) {
+ *     this.logger_ = logger
+ *     this.options_ = options
+ *     // set the service's client to
+ *     // the client from the container
+ *     this.client = client
+ *   }
+ *
+ *   // ...
+ * }
+ *
+ * export default MyCachingModuleProvider
+ * ```
+ * 
+ * ### Identifier
+ *
+ * Every caching module provider must have an `identifier` static property. The provider's ID
+ * will be stored as `lp_{identifier}_{id}`, where `id` is the ID you set in your `medusa-config.ts` file.
+ * 
+ * For example:
+ * 
+ * ```ts
+ * class MyCachingModuleProvider implements ICachingProviderService {
+ *   static identifier = "my-cache"
+ *   // ...
+ * }
+ * ```
+ */
 export interface ICachingProviderService {
-  get({ key, tags }: { key?: string; tags?: string[] }): Promise<any>
+  /**
+   * This method retrieves data from the cache. If neither `key` nor `tags` are provided, `null` should be returned.
+   * If both `key` and `tags` are provided, `key` should take precedence over `tags`.
+   * 
+   * @param param0 - The parameters for retrieving the item.
+   * @returns The item(s) that was stored in the cache, or `null` if not found.
+   * 
+   * @example
+   * class MyCachingModuleProvider implements ICachingProviderService {
+   *   // ...
+   *   async get({ key, tags }: { key?: string; tags?: string[] }): Promise<any> {
+   *     // Assuming you're using a client to get data
+   *     if (key) {
+   *       return await this.client.get({ key })
+   *     }
+   *     if (tags) {
+   *       return await this.client.getByTags({ tags })
+   *     }
+   *     return null
+   *   }
+   * }
+   */
+  get({ key, tags }: { 
+    /**
+     * The key of the item to retrieve. If both are provided, `key` should take precedence over `tags`.
+     */
+    key?: string; 
+    /**
+     * The tags of the items to retrieve. All items with any of the provided tags should be retrieved.
+     */
+    tags?: string[]
+  }): Promise<any>
+  /**
+   * This method stores data in the cache. It should also store the options with the item, 
+   * allowing you to later to check the `autoInvalidate` option when clearing the item.
+   * 
+   * @param param0 - The parameters for storing the item.
+   * @return A promise that resolves when the item has been stored.
+   * 
+   * @example
+   * class MyCachingModuleProvider implements ICachingProviderService {
+   *   // ...
+   *   async set({ key, data, ttl, tags, options }: { 
+   *     key: string; 
+   *     data: any; 
+   *     ttl?: number; 
+   *     tags?: string[]; 
+   *     options?: { autoInvalidate?: boolean } 
+   *   }): Promise<void> {
+   *     // Assuming you're using a client to set data
+   *     await this.client.set({ key, data, ttl, tags })
+   *     await this.client.set({ key, data: options, pipeline: "options" })
+   *   }
+   * }
+   */
   set({
     key,
     data,
@@ -114,29 +455,106 @@ export interface ICachingProviderService {
     tags,
     options,
   }: {
+    /**
+     * The key of the item to store.
+     */
     key: string
+    /**
+     * The data to store in the cache.
+     */
     data: object
+    /**
+     * The time-to-live (TTL in seconds) value in seconds.
+     * If not provided, the default TTL value configured in the provider should be used.
+     */
     ttl?: number
+    /**
+     * The tags of the items to store. Items should be grouped together using tags for retrieval or invalidation.
+     */
     tags?: string[]
-    options?: { autoInvalidate?: boolean }
+    /**
+     * Options for storing the item. The options should be stored with the item, allowing you to later match against them when clearing the item.
+     * For example, if you set `autoInvalidate: false`, the item will only be invalidated when calling the `clear` method directly with the same key or tags.
+     */
+    options?: {
+      /**
+       * Whether to automatically invalidate the item when related data changes.
+       */ 
+      autoInvalidate?: boolean
+    }
   }): Promise<void>
+  /**
+   * This method clears data from the cache. If no options are specified, all items matching the key or tags should be cleared.
+   * Otherwise, if `options.autoInvalidate` is `true`, only items that were set with `options.autoInvalidate: true` should be cleared.
+   * 
+   * Items with `options.autoInvalidate: false` should only be cleared when no options are provided.
+   * 
+   * If neither `key` nor `tags` are provided, nothing should be cleared.
+   * 
+   * @param param0 - The parameters for clearing the item(s).
+   * @returns A promise that resolves when the item(s) have been cleared.
+   * 
+   * @example
+   * async clear({ key, tags, options, }: { 
+   *   key?: string; 
+   *   tags?: string[]; 
+   *   options?: { autoInvalidate?: boolean }
+   * }): Promise<void> {
+   *   if (!options) {
+   *     // clear all items
+   *     await this.client.invalidate({ key, tags })
+   *   } else if (options.autoInvalidate) {
+   *     // clear only items with autoInvalidate option set to true
+   *     const keysToDelete: string[] = []
+   *     const storedOptions = await this.client.get({ key, tags, pipeline: "options" })
+   *     storedOptions.forEach((item) => {
+   *       if (item.autoInvalidate) {
+   *         keysToDelete.push(item.key as string)
+   *       }
+   *     })
+   *     await this.client.invalidate({ keys: keysToDelete })
+   *   }
+   * }
+   */
   clear({
     key,
     tags,
     options,
   }: {
+    /**
+     * The key of the item to clear.
+     */
     key?: string
+    /**
+     * The tags of the items to clear. All items with any of the provided tags should be cleared.
+     */
     tags?: string[]
-    options?: { autoInvalidate?: boolean }
+    /**
+     * Options for clearing the item(s). The options should be matched against the stored options when the item was set.
+     * For example, if the item was set with `autoInvalidate: true`, it will only be cleared if the `autoInvalidate` option is also set to `true`.
+     * If not provided, all items matching the key or tags should be cleared regardless of their options.
+     */
+    options?: {
+      /**
+       * Whether to clear item(s) that were set to automatically invalidate.
+       */ 
+      autoInvalidate?: boolean
+    }
   }): Promise<void>
 }
 
+/**
+ * @ignore
+ */
 export interface EntityReference {
   type: string
   id: string | number
   field?: string
 }
 
+/**
+ * @ignore
+ */
 export interface ICachingStrategy {
   /**
    * This method is called when the application starts. It can be useful to set up some auto