feat: use tsdoc

packages/validators/.eslintrc

@@ -1,9 +1,10 @@
 {
   "extends": ["opengovsg"],
   "ignorePatterns": ["dist/**/*", "vitest.config.ts"],
-  "plugins": ["import"],
+  "plugins": ["import", "eslint-plugin-tsdoc"],
   "rules": {
-    "import/no-unresolved": "error"
+    "import/no-unresolved": "error",
+    "tsdoc/syntax": "error"
   },
   "parser": "@typescript-eslint/parser",
   "parserOptions": {

packages/validators/package.json

@@ -25,6 +25,7 @@
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-simple-import-sort": "^10.0.0",
+    "eslint-plugin-tsdoc": "^0.3.0",
     "prettier": "^2.8.4",
     "tsup": "^8.1.0",
     "typescript": "^5.4.5"

packages/validators/src/url/index.ts

@@ -5,9 +5,28 @@ import { OptionsError, UrlValidationError } from '@/url/errors'
 import { defaultOptions, Options, optionsSchema } from '@/url/options'
 import { createUrlSchema } from '@/url/schema'
 
+/**
+ * Validates URLs against a whitelist of allowed protocols and hostnames, preventing open redirects, XSS, SSRF, and other security vulnerabilities.
+ */
 export class UrlValidator {
   private schema
 
+  /**
+   * Creates a new UrlValidator instance. If no options are provided, the validator will use the default options:
+   *
+   * ```ts
+   * {
+   *    whitelist: {
+   *      protocols: ['http', 'https'],
+   *    },
+   * }
+   * ```
+   *
+   * @param options - The options to use for validation
+   * @throws {@link OptionsError} If the options are invalid
+   *
+   * @public
+   */
   constructor(options: Options = defaultOptions) {
     const result = optionsSchema.safeParse({ ...defaultOptions, ...options })
     if (result.success) {
@@ -17,6 +36,15 @@ export class UrlValidator {
     throw new OptionsError(fromError(result.error).toString())
   }
 
+  /**
+   * Parses a URL string.
+   *
+   * @param url - The URL to validate
+   * @returns The URL object if the URL is valid
+   * @throws {@link UrlValidationError} If the URL is invalid
+   *
+   * @public
+   */
   parse(url: string): URL {
     const result = this.schema.safeParse(url)
     if (result.success) {

packages/validators/src/url/options.ts

@@ -7,7 +7,17 @@ export const defaultOptions = {
 }
 
 export const whitelistSchema = z.object({
+  /**
+   * The list of allowed protocols.
+   * Caution: allowing `javascript` or `data` protocols can lead to XSS vulnerabilities.
+   *
+   * @defaultValue ['http', 'https']
+   */
   protocols: z.array(z.string()).default(defaultOptions.whitelist.protocols),
+  /**
+   * The list of allowed hostnames.
+   * It is recommended to provide a list of allowed hostnames to prevent open redirects.
+   */
   hosts: z.array(z.string()).optional(),
 })