docs(nest): add JSDocs (#5034)

The Nest-way is rather different than other things. So, when reviewing, take that into account.

Closes GH-4957.

Author: wooorm-arcjet

arcjet-nest/index.ts

@@ -92,18 +92,36 @@ type PlainObject = {
   [key: string]: unknown;
 };
 
+/**
+ * Configuration for {@linkcode createRemoteClient}.
+ */
 export type RemoteClientOptions = {
+  /**
+   * Base URI for HTTP requests to Decide API (optional).
+   *
+   * Defaults to the environment variable `ARCJET_BASE_URL` (if that value
+   * is known and allowed) and the standard production API otherwise.
+   */
   baseUrl?: string;
+
+  /**
+   * Timeout in milliseconds for the Decide API (optional).
+   *
+   * Defaults to `500` in production and `1000` in development.
+   */
   timeout?: number;
 };
 
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 export function createRemoteClient(options?: RemoteClientOptions) {
-  // The base URL for the Arcjet API. Will default to the standard production
-  // API unless environment variable `ARCJET_BASE_URL` is set.
   const url = options?.baseUrl ?? baseUrl(process.env);
-
-  // The timeout for the Arcjet API in milliseconds. This is set to a low value
-  // in production so calls fail open.
   const timeout = options?.timeout ?? (isDevelopment(process.env) ? 1000 : 500);
 
   // Transport is the HTTP client that the client uses to make requests.
@@ -126,21 +144,83 @@ type EventHandlerLike = (
   listener: (...args: any[]) => void,
 ) => void;
 
-// Interface of fields that the Arcjet Nest.js SDK expects on Request objects
+/**
+ * Nest request.
+ */
 export interface ArcjetNestRequest {
+  /**
+   * Headers.
+   */
   headers?: Record<string, string | string[] | undefined>;
+  /**
+   * HTTP method of the request.
+   */
   method?: string;
+  /**
+   * URL.
+   */
   url?: string;
+  /**
+   * Request body.
+   */
   body?: unknown;
-  // Will only exist for Fastify
+  /**
+   * Request ID.
+   *
+   * This field is available on Fastify requests:
+   * <https://fastify.dev/docs/latest/Reference/Request/#request>.
+   */
   id?: string;
+  /**
+   * IP address of the client.
+   */
   ip?: string;
+  /**
+   * Protocol of the request.
+   */
   protocol?: string;
+  /**
+   * Host of the request.
+   */
   host?: string;
-  // Will only exist for Express
+  /**
+   * `net.Socket` object associated with the connection.
+   *
+   * This field is available on Express requests,
+   * as those inherit from Node `http.IncomingMessage`.
+   *
+   * See <https://nodejs.org/api/http.html#messagesocket>.
+   */
   socket?: Partial<{ remoteAddress: string; encrypted: boolean }>;
+  /**
+   * Add event handlers.
+   *
+   * This field is available on Express requests,
+   * as those inherit from Node `http.IncomingMessage`,
+   * in turn from `stream.Readable` and `EventEmitter`.
+   *
+   * See <https://nodejs.org/api/events.html#emitteroneventname-listener>.
+   */
   on?: EventHandlerLike;
+  /**
+   * Remove event handlers.
+   *
+   * This field is available on Express requests,
+   * as those inherit from Node `http.IncomingMessage`,
+   * in turn from `stream.Readable` and `EventEmitter`.
+   *
+   * See <https://nodejs.org/api/events.html#emitterremovelistenereventname-listener>.
+   */
   removeListener?: EventHandlerLike;
+  /**
+   * Whether the readable stream is readable.
+   *
+   * This field is available on Express requests,
+   * as those inherit from Node `http.IncomingMessage`,
+   * in turn from `stream.Readable`.
+   *
+   * See <https://nodejs.org/api/stream.html#readablereadable>.
+   */
   readable?: boolean;
 }
 
@@ -158,34 +238,50 @@ function cookiesToString(cookies: string | string[] | undefined): string {
 }
 
 /**
- * The options used to configure an {@link ArcjetNest} client.
+ * Configuration for the Nest integration of Arcjet.
+ *
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
  */
 export type ArcjetOptions<
   Rules extends [...Array<Primitive | Product>],
   Characteristics extends readonly string[],
 > = Simplify<
   CoreOptions<Rules, Characteristics> & {
     /**
-     * One or more IP Address of trusted proxies in front of the application.
-     * These addresses will be excluded when Arcjet detects a public IP address.
+     * IP addresses and CIDR ranges of trusted load balancers and proxies
+     * (optional, example: `["100.100.100.100", "100.100.100.0/24"]`).
      */
     proxies?: Array<string>;
   }
 >;
 
 /**
- * The ArcjetNest client provides a public `protect()` method to
- * make a decision about how a NestJS request should be handled.
+ * Instance of the Nest integration of Arcjet.
+ *
+ * Primarily has a `protect()` method to make a decision about how a Nest request
+ * should be handled.
+ *
+ * @template Props
+ *   Configuration.
  */
 export interface ArcjetNest<Props extends PlainObject = {}> {
   /**
-   * Runs a request through the configured protections. The request is
-   * analyzed and then a decision made on whether to allow, deny, or challenge
-   * the request.
+   * Make a decision about how to handle a request.
+   *
+   * This will analyze the request locally where possible and otherwise call
+   * the Arcjet decision API.
    *
-   * @param req - An `IncomingMessage` provided to the request handler.
-   * @param props - Additonal properties required for running rules against a request.
-   * @returns An {@link ArcjetDecision} indicating Arcjet's decision about the request.
+   * @param request
+   *   Details about the {@linkcode ArcjetNestRequest} that Arcjet needs to make a
+   *   decision.
+   * @param props
+   *   Additional properties required for running rules against a request.
+   * @returns
+   *   Promise that resolves to an {@linkcode ArcjetDecision} indicating
+   *   Arcjet’s decision about the request.
    */
   protect(
     request: ArcjetNestRequest,
@@ -195,11 +291,17 @@ export interface ArcjetNest<Props extends PlainObject = {}> {
   ): Promise<ArcjetDecision>;
 
   /**
-   * Augments the client with another rule. Useful for varying rules based on
-   * criteria in your handler—e.g. different rate limit for logged in users.
+   * Augment the client with another rule.
    *
-   * @param rule The rule to add to this execution.
-   * @returns An augmented {@link ArcjetNest} client.
+   * Useful for varying rules based on criteria in your handler such as
+   * different rate limit for logged in users.
+   *
+   * @template Rule
+   *   Type of rule.
+   * @param rule
+   *   Rule to add to Arcjet.
+   * @returns
+   *   Arcjet instance augmented with the given rule.
    */
   withRule<Rule extends Primitive | Product>(
     rule: Rule,
@@ -405,7 +507,13 @@ function arcjet<
   return withClient(aj);
 }
 
+/**
+ * Symbol for Arcjet.
+ *
+ * Used as a label of providers that should be available in other modules.
+ */
 export const ARCJET = Symbol("ARCJET");
+
 const ARCJET_OPTIONS = Symbol("ARCJET_OPTIONS");
 const ARCJET_WITH_RULES = Symbol("ARCJET_WITH_RULES");
 
@@ -446,9 +554,22 @@ function requestFromContext(context: ExecutionContext) {
   }
 }
 
+/**
+ * Nest guard for the Arcjet Nest integration.
+ *
+ * See: <https://docs.nestjs.com/guards>.
+ */
 let ArcjetGuard = class ArcjetGuard implements CanActivate {
   aj: ArcjetNest<WithoutCustomProps>;
 
+  /**
+   * Create a Nest guard for the Arcjet.
+   *
+   * @param aj
+   *   Arcjet Nest integration.
+   * @returns
+   *   Arcjet Nest guard.
+   */
   constructor(aj: ArcjetNest<WithoutCustomProps>) {
     this.aj = aj;
   }
@@ -484,12 +605,34 @@ let ArcjetGuard = class ArcjetGuard implements CanActivate {
 ArcjetGuard = decorate([param(0, Inject(ARCJET))], ArcjetGuard);
 export { ArcjetGuard };
 
+/**
+ * Create Nest modules for the Arcjet Nest integration.
+ *
+ * See: <https://docs.nestjs.com/modules>.
+ */
 export class ArcjetModule {
+  /**
+   * Create a Nest module for the Arcjet Nest integration.
+   *
+   * You can pass your API key and any default rules that you want to apply to
+   * every route.
+   * This is usually in the `app.module.ts` file.
+   *
+   * @param options
+   *   Configuration (required).
+   * @returns
+   *   Dynamic Nest module.
+   */
   static forRoot<
     const Rules extends (Primitive | Product)[],
     const Characteristics extends readonly string[],
   >(
     options: ArcjetOptions<Rules, Characteristics> & {
+      /**
+       * Whether to make the module global-scoped (`boolean`, default: `false`).
+       *
+       * Global-scoped modules will be visible in all modules.
+       */
       isGlobal?: boolean | undefined;
     },
   ): DynamicModule {
@@ -514,13 +657,34 @@ export class ArcjetModule {
       exports: [ARCJET],
     };
   }
+
+  /**
+   * Create a Nest module for the Arcjet Nest integration,
+   * asynchronously.
+   *
+   * You can pass your API key and any default rules that you want to apply to
+   * every route.
+   * This is usually in the `app.module.ts` file.
+   *
+   * @param options
+   *   Configuration (required).
+   * @returns
+   *   Dynamic Nest module.
+   */
   static forRootAsync<
     const Rules extends (Primitive | Product)[],
     const Characteristics extends readonly string[],
   >(
     options: ConfigurableModuleAsyncOptions<
       ArcjetOptions<Rules, Characteristics>
-    > & { isGlobal?: boolean | undefined },
+    > & {
+      /**
+       * Whether to make the module global-scoped (`boolean`, default: `false`).
+       *
+       * Global-scoped modules will be visible in all modules.
+       */
+      isGlobal?: boolean | undefined;
+    },
   ): DynamicModule {
     const ArcjetProvider = {
       provide: ARCJET,
@@ -582,6 +746,21 @@ export class ArcjetModule {
   }
 }
 
+/**
+ * Decorator that binds Arcjet rules to the scope of the controller or method,
+ * depending on its context.
+ *
+ * When `@WithArcjetRules` is used at the controller level,
+ * the rules will be applied to every handler (method) in the controller.
+ *
+ * When `@WithArcjetRules` is used at the individual handler level,
+ * the rules will apply only to that specific method.
+ *
+ * @param rules
+ *   List of rules.
+ * @returns
+ *   Decorator.
+ */
 export function WithArcjetRules(rules: Array<Primitive | Product>) {
   return SetMetadata(ARCJET_WITH_RULES, rules);
 }