docs: add additional detail to getResource entry

Author: backlineint

packages/next-drupal/src/next-drupal.ts

@@ -290,8 +290,8 @@ export class NextDrupal extends NextDrupalBase {
   /**
    * Fetches a resource of the specified type by its UUID.
    *
-   * @param {string} type The type of the resource.
-   * @param {string} uuid The UUID of the resource.
+   * @param {string} type The resource type. Example: `node--article`, `taxonomy_term--tags`, or `block_content--basic`.
+   * @param {string} uuid The id of the resource. Example: `15486935-24bf-4be7-b858-a5b2de78d09d`.
    * @param {JsonApiOptions & JsonApiWithCacheOptions & JsonApiWithNextFetchOptions} options Options for the request.
    * @returns {Promise<T>} The fetched resource.
    * @examples
@@ -332,6 +332,27 @@ export class NextDrupal extends NextDrupalBase {
    *   cacheKey: `node--article:${id}`,
    * })
    * ```
+   * Get a page resource with time-based revalidation.
+   * ```ts
+   * const node = await drupal.getResource(
+   *   "node--page",
+   *   "07464e9f-9221-4a4f-b7f2-01389408e6c8",
+   *   { next: { revalidate: 3600 } }
+   * )
+   * ```
+   * Get a page resource with tag-based revalidation.
+   * ```ts
+   * const {slug} = params;
+   * const path = drupal.translatePath(slug)
+   *
+   * const type = path.jsonapi.resourceName
+   * const tag = `${path.entity.type}:${path.entity.id}`
+   *
+   * const node = await drupal.getResource(path, path.entity.uuid, {
+   *   params: params.getQueryObject(),
+   *   tags: [tag]
+   * })
+   * ```
    * Using DrupalNode for a node entity type.
    * ```ts
    * import { DrupalNode } from "next-drupal"

packages/next-drupal/src/types/options.ts

@@ -10,13 +10,24 @@ export interface FetchOptions extends RequestInit {
   withAuth?: boolean | NextDrupalAuth
 }
 
+/**
+ * JSON:API Related Options
+ */
 export type JsonApiOptions = {
+  /**
+   * Set to false to return the raw JSON:API response.
+   * */
   deserialize?: boolean
+  /**
+   * JSON:API params such as `filter`, `fields`, `include` or `sort`.
+   */
   params?: JsonApiParams
 } & JsonApiWithAuthOption &
   (
     | {
+        /** The locale to fetch the resource in. */
         locale: Locale
+        /** The default locale of the site. */
         defaultLocale: Locale
       }
     | {
@@ -26,11 +37,14 @@ export type JsonApiOptions = {
   )
 
 export type JsonApiWithAuthOption = {
+  /** Set to true to use the authentication method configured on the client. */
   withAuth?: boolean | NextDrupalAuth
 }
 
 export type JsonApiWithCacheOptions = {
+  /** Set `withCache` if you want to store and retrieve the resource from cache. */
   withCache?: boolean
+  /** The cache key to use. */
   cacheKey?: string
 }
 
@@ -39,5 +53,8 @@ export type JsonApiWithNextFetchOptions = {
   cache?: RequestCache
 }
 // TODO: Properly type this.
+/**
+ * JSON:API params such as filter, fields, include or sort.
+ */
 /* eslint-disable  @typescript-eslint/no-explicit-any */
 export type JsonApiParams = Record<string, any>

www/package.json

@@ -9,7 +9,8 @@
     "dev": "typedoc --tsconfig tsconfig.docs.json && next dev -p 4444",
     "build": "typedoc --tsconfig tsconfig.docs.json && next build",
     "preview": "typedoc --tsconfig tsconfig.docs.json && next build && next start -p 4444",
-    "generate:api-docs": "typedoc --tsconfig tsconfig.docs.json"
+    "generate:api-docs": "typedoc --tsconfig tsconfig.docs.json",
+    "watch:api-docs": "typedoc --tsconfig tsconfig.docs.json --watch"
   },
   "dependencies": {
     "@docsearch/react": "^3.6.0",