docs: add JSDocs to exposed API in 10 utilities (#4741)

This commit adds JSDoc documentation to everything exposed from 10 of the about 30 packages.

There’s a lot we are exposing that we don’t need to expose, but also things that are in parameters/return values/elsewhere which we should probably expose, which I noted inline.

As for `@arcjet/inspect`, that’s something that was already documented, but also (more up to date) on the website. I kept some small useful things in the code and the readme here, but mostly deferred with links to the website.

Related-to: GH-3327.

Author: wooorm-arcjet

analyze/index.ts

@@ -92,13 +92,23 @@ function createCoreImports(detect?: DetectSensitiveInfoFunction): ImportObject {
   };
 }
 
-// TODO(@wooorm-arcjet): document what is used to fingerprint.
 /**
- * Generate a fingerprint for the client. This is used to identify the client
- * across multiple requests.
- * @param context - The Arcjet Analyze context.
- * @param request - The request to fingerprint.
- * @returns A SHA-256 string fingerprint.
+ * Generate a fingerprint.
+ *
+ * Fingerprints can be used to identify the client across multiple requests.
+ *
+ * This considers different things on the `request` based on the passed
+ * `context.characteristics`.
+ *
+ * See [*Fingerprints* on
+ * `docs.arcjet.com`](https://docs.arcjet.com/fingerprints/) for more info.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @returns
+ *   Promise for a SHA-256 fingerprint.
  */
 export async function generateFingerprint(
   context: AnalyzeContext,
@@ -121,18 +131,29 @@ export async function generateFingerprint(
   return "";
 }
 
-// TODO(@wooorm-arcjet): docs.
+/**
+ * Check whether an email is valid.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
 export async function isValidEmail(
   context: AnalyzeContext,
-  candidate: string,
+  value: string,
   options: EmailValidationConfig,
 ): Promise<EmailValidationResult> {
   const { log } = context;
   const coreImports = createCoreImports();
   const analyze = await initializeWasm(coreImports);
 
   if (typeof analyze !== "undefined") {
-    return analyze.isValidEmail(candidate, options);
+    return analyze.isValidEmail(value, options);
     // Ignore the `else` branch as we test in places that have WebAssembly.
     /* node:coverage ignore next 4 */
   }
@@ -141,7 +162,18 @@ export async function isValidEmail(
   return { blocked: [], validity: "valid" };
 }
 
-// TODO(@wooorm-arcjet): docs.
+/**
+ * Detect whether a request is by a bot.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
 export async function detectBot(
   context: AnalyzeContext,
   request: AnalyzeRequest,
@@ -161,10 +193,27 @@ export async function detectBot(
   return { allowed: [], denied: [], spoofed: false, verified: false };
 }
 
-// TODO(@wooorm-arcjet): docs.
+/**
+ * Detect sensitive info in a value.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param entities
+ *   Strategy to use for detecting sensitive info;
+ *   either by denying everything and allowing certain tags or by allowing
+ *   everything and denying certain tags.
+ * @param contextWindowSize
+ *   Number of tokens to pass to `detect`.
+ * @param detect
+ *   Function to detect sensitive info (optional).
+ * @returns
+ *   Promise for a result.
+ */
 export async function detectSensitiveInfo(
   context: AnalyzeContext,
-  candidate: string,
+  value: string,
   entities: SensitiveInfoEntities,
   contextWindowSize: number,
   detect?: DetectSensitiveInfoFunction,
@@ -175,7 +224,7 @@ export async function detectSensitiveInfo(
 
   if (typeof analyze !== "undefined") {
     const skipCustomDetect = typeof detect !== "function";
-    return analyze.detectSensitiveInfo(candidate, {
+    return analyze.detectSensitiveInfo(value, {
       entities,
       contextWindowSize,
       skipCustomDetect,

body/index.ts

@@ -1,18 +1,33 @@
+/**
+ * Configuration.
+ */
 export type ReadBodyOpts = {
-  limit: number;
+  /**
+   * Length of the stream in bytes (optional);
+   * an error is returned if the contents of the stream do not add up to this length;
+   * useful when the exact size is known.
+   */
   expectedLength?: number | null | undefined;
+  /**
+   * Limit of the body in bytes (required);
+   * an error is returned if the body ends up being larger than this limit;
+   * used to prevent reading too much data from malicious clients.
+   */
+  limit: number;
 };
 
 type EventHandlerLike = (
   event: string,
   listener: (...args: any[]) => void,
 ) => void;
 
-// The fields from stream.Readable that we use
+/**
+ * Stream.
+ */
 export interface ReadableStreamLike {
   on?: EventHandlerLike | null | undefined;
-  removeListener?: EventHandlerLike | null | undefined;
   readable?: boolean | null | undefined;
+  removeListener?: EventHandlerLike | null | undefined;
 }
 
 // This `readBody` function is a derivitive of the `getRawBody` function in the `raw-body`
@@ -46,19 +61,30 @@ export interface ReadableStreamLike {
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+/**
+ * Read the body of a stream.
+ *
+ * @param stream
+ *   Stream.
+ * @param options
+ *   Configuration (required).
+ * @returns
+ *   Promise to a concatenated body.
+ */
 export async function readBody(
   stream: ReadableStreamLike,
-  opts: ReadBodyOpts,
+  // TODO(@wooorm-arcjet): make optional.
+  options: ReadBodyOpts,
 ): Promise<string> {
   const decoder = new TextDecoder("utf-8");
   let buffer = "";
   let complete = false;
   let received = 0;
-  const limit = opts.limit;
+  const limit = options.limit;
   if (typeof limit !== "number") {
     return Promise.reject(new Error("must set a limit"));
   }
-  const length = opts.expectedLength || null;
+  const length = options.expectedLength || null;
 
   if (typeof stream.readable !== "undefined" && !stream.readable) {
     return Promise.reject(new Error("stream is not readable"));

cache/index.ts

@@ -1,23 +1,33 @@
+/**
+ * Interface for a cache.
+ */
 export interface Cache<T = unknown> {
   /**
-   * Attempts to retrieve a value from the cache. If a value exists, it will be
-   * returned with the remaining time-to-live (in seconds).
+   * Retrieve a value from the cache;
+   * it will be returned with the remaining time-to-live (in seconds) if it exists.
    *
-   * @param namespace A isolated segement of the cache where keys are tracked.
-   * @param key The identifier used to retrieve the value.
-   * @returns A promise for a 2-element tuple containing the value and TTL in
-   * seconds. If no value is retrieved, the value will be `undefined` and the
-   * TTL will be `0`.
+   * @param namespace
+   *   Isolated segment of the cache where keys are tracked.
+   * @param key
+   *   Key.
+   * @returns
+   *   Promise for a tuple with the value and TTL in seconds;
+   *   value will be `undefined` and TTL will be `0` if not found.
    */
   get(namespace: string, key: string): Promise<[T | undefined, number]>;
   /**
-   * If the cache implementation supports storing values, `set` makes a best
-   * attempt at storing the value provided until the time-to-live specified.
+   * Store a value in the cache.
    *
-   * @param namespace A isolated segement of the cache where keys are tracked.
-   * @param key The identifier used to store the value.
-   * @param value The value to be stored under the key.
-   * @param ttl The amount of seconds the value stays valid in the cache.
+   * @param namespace
+   *   Isolated segment of the cache where keys are tracked.
+   * @param key
+   *   Key.
+   * @param value
+   *   Value.
+   * @param ttl
+   *   Number of seconds the entry stays valid.
+   * @returns
+   *   Nothing.
    */
   set(namespace: string, key: string, value: T, ttl: number): void;
 }
@@ -58,9 +68,18 @@ class Bucket<T> {
   }
 }
 
+/**
+ * In-memory cache.
+ */
 export class MemoryCache<T> implements Cache<T> {
+  /**
+   * Data.
+   */
   namespaces: Map<string, Bucket<T>>;
 
+  /**
+   * Create a new in-memory cache.
+   */
   constructor() {
     this.namespaces = new Map();
   }

decorate/index.ts

@@ -8,8 +8,8 @@ import {
 
 // If these are defined, we can expect to be working with `Headers` directly.
 interface HeaderLike {
-  has(name: string): boolean;
   get(name: string): string | null;
+  has(name: string): boolean;
   set(name: string, value: string): void;
 }
 
@@ -22,12 +22,12 @@ interface ResponseLike {
 // Otherwise, we'll be working with an `http.OutgoingMessage` and we'll need
 // to use these values.
 interface OutgoingMessageLike {
+  getHeader: (name: string) => string[] | number | string | undefined;
   headersSent: boolean;
   hasHeader: (name: string) => boolean;
-  getHeader: (name: string) => number | string | string[] | undefined;
   setHeader: (
     name: string,
-    value: number | string | ReadonlyArray<string>,
+    value: ReadonlyArray<string> | number | string,
   ) => unknown;
 }
 
@@ -154,14 +154,19 @@ function nearestLimit(
 }
 
 /**
- * Decorates an object with `RateLimit` and `RateLimit-Policy` headers based
- * on an {@link ArcjetDecision} and conforming to the [Rate Limit fields for
+ * Decorate something based on an Arcjet decision with rate limit headers.
+ *
+ * Sets `RateLimit-Policy` and `RateLimit` and conform to the
+ * [Rate Limit fields for
  * HTTP](https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html)
  * draft specification.
  *
- * @param value The object to decorate—must be similar to {@link Headers}, {@link Response} or
- * {@link OutgoingMessage}.
- * @param decision The {@link ArcjetDecision} that was made by calling `protect()` on the SDK.
+ * @param value
+ *   Decorable value.
+ * @param decision
+ *   Decision from `protect()`.
+ * @returns
+ *   Nothing.
  */
 export function setRateLimitHeaders(
   value: ArcjetCanDecorate,