chore(adapter-nextjs): improve the inline doc (#12009)

packages/adapter-nextjs/src/runWithAmplifyServerContext.ts

@@ -14,6 +14,49 @@ import {
 	runWithAmplifyServerContext as runWithAmplifyServerContextCore,
 } from 'aws-amplify/internals/adapter-core';
 
+/**
+ * Runs the {@link operation} with the the context created from the {@link nextServerContext}.
+ *
+ * @param input The input to call the {@link runWithAmplifyServerContext}.
+ * @param input.nextServerContext The Next.js server context. It varies depends
+ *   where the {@link runWithAmplifyServerContext} is being called.
+ *   - In the [middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware):
+ *     the context consists of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Page server component](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages):
+ * 	   the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ *   - In a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers):
+ *     the context can be the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function or a combination of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#how-server-actions-work):
+ *     the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ * @param input.operation The function that contains the business logic calling
+ *   Amplify APIs. It expects a `contextSpec` parameter.
+ * @returns The result returned by the {@link operation}.
+ * @example
+ * // Use the `fetchAuthSession` API in the Next.js `middleware`.
+ * import { NextRequest, NextResponse } from "next/server";
+ * import { fetchAuthSession } from "aws-amplify/auth/server";
+ * import { runWithAmplifyServerContext } from "@aws-amplify/adapter-nextjs";
+
+ * export async function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   const authenticated = await runWithAmplifyServerContext({
+ *     nextServerContext: { request, response },
+ *     operation: async (contextSpec) => {
+ *       const session = await fetchAuthSession(contextSpec);
+ *       return session.tokens !== undefined;
+ *     }
+ *   });
+ *   if (authenticated) {
+ *     return response;
+ *   }
+ *   return NextResponse.redirect(new URL('/sign-in', request.url));
+ * }
+ */
 export const runWithAmplifyServerContext: NextServer.RunOperationWithContext =
 	async ({ nextServerContext, operation }) => {
 		// 1. get amplify config from env vars

packages/adapter-nextjs/src/types/NextServer.ts

@@ -51,12 +51,18 @@ export namespace NextServer {
 		response: NextGetServerSidePropsContext['res'];
 	};
 
+	/**
+	 * The union of possible Next.js app server context types.
+	 */
 	export type Context =
 		| NextRequestAndNextResponseContext
 		| NextRequestAndResponseContext
 		| ServerComponentContext
 		| GetServerSidePropsContext;
 
+	/**
+	 * The interface of the input of {@link RunOperationWithContext}.
+	 */
 	export interface RunWithContextInput<OperationResult> {
 		nextServerContext: Context | null;
 		operation: (

packages/adapter-nextjs/tslint.json

@@ -5,7 +5,13 @@
 	"jsRules": {},
 	"rules": {
 		"prefer-const": true,
-		"max-line-length": [true, 120],
+		"max-line-length": [
+			true,
+			{
+				"limit": 120,
+				"ignore-pattern": "^//|^ *"
+			}
+		],
 		"no-empty-interface": true,
 		"no-var-keyword": true,
 		"object-literal-shorthand": true,