feat: createUrlSchema

.github/workflows/release.yml

@@ -3,7 +3,7 @@ name: Release
 on:
   push:
     tags:
-      - "v*"
+      - "*/v*"
   workflow_dispatch: {}
 
 permissions:
@@ -56,4 +56,3 @@ jobs:
         run: pnpm -r publish --no-git-checks --tag latest --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-

apps/docs/package.json

@@ -14,7 +14,9 @@
   "license": "ISC",
   "devDependencies": {
     "vitepress": "^1.3.1",
-    "vue": "~3.4.31"
+    "vue": "~3.4.31",
+    "@opengovsg/starter-kitty-validators": "workspace:*",
+    "@opengovsg/starter-kitty-fs": "workspace:*"
   },
   "prettier": "@opengovsg/prettier-config-starter-kitty"
 }

etc/starter-kitty-validators.api.md

@@ -8,13 +8,17 @@
 
 import { z } from 'zod';
 import { ZodSchema } from 'zod';
+import { ZodTypeDef } from 'zod';
 
 // @public
 export const createEmailSchema: (options?: EmailValidatorOptions) => ZodSchema<string>;
 
 // @public
 export const createPathSchema: (options: PathValidatorOptions) => ZodSchema<string>;
 
+// @public
+export const createUrlSchema: (options?: UrlValidatorOptions) => ZodSchema<URL, ZodTypeDef, string>;
+
 // @public
 export interface EmailValidatorOptions {
     domains?: {

package.json

@@ -8,6 +8,7 @@
     "build:docs": "turbo build:docs",
     "dev": "turbo dev",
     "lint": "turbo lint",
+    "lint:fix": "turbo lint:fix",
     "test": "turbo test",
     "ci:report": "turbo ci:report",
     "format": "turbo format",

packages/safe-fs/package.json

@@ -11,6 +11,7 @@
     "build:report": "api-extractor run --local --verbose",
     "build:docs": "api-documenter markdown --input-folder ../../temp/ --output-folder ../../apps/docs/api/",
     "lint": "eslint \"**/*.{js,jsx,ts,tsx}\" --cache",
+    "lint:fix": "eslint \"**/*.{js,jsx,ts,tsx}\" --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest",

packages/validators/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengovsg/starter-kitty-validators",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -11,6 +11,7 @@
     "build:report": "api-extractor run --local --verbose",
     "build:docs": "api-documenter markdown --input-folder ../../temp/ --output-folder ../../apps/docs/api/",
     "lint": "eslint \"**/*.{js,jsx,ts,tsx}\" --cache",
+    "lint:fix": "eslint \"**/*.{js,jsx,ts,tsx}\" --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest",

packages/validators/src/__tests__/url.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
 import { OptionsError } from '@/common/errors'
-import { UrlValidator } from '@/index'
+import { createUrlSchema, UrlValidator } from '@/index'
 import { UrlValidationError } from '@/url/errors'
 
 describe('UrlValidator with default options', () => {
@@ -116,3 +116,41 @@ describe('UrlValidator with invalid options', () => {
     expect(() => new UrlValidator({ baseOrigin: 'https://example.com/path' })).toThrow(OptionsError)
   })
 })
+
+describe('createUrlSchema', () => {
+  it('should create a schema with default options', () => {
+    const schema = createUrlSchema()
+    expect(() => schema.parse('https://example.com')).not.toThrow()
+  })
+
+  it('should create a schema with custom options', () => {
+    const schema = createUrlSchema({
+      whitelist: {
+        protocols: ['http', 'https', 'mailto'],
+      },
+    })
+    expect(() => schema.parse('mailto:[email protected]')).not.toThrow()
+  })
+
+  it('should throw an error when the options are invalid', () => {
+    expect(() => createUrlSchema({ baseOrigin: 'invalid' })).toThrow(OptionsError)
+    expect(() => createUrlSchema({ baseOrigin: 'ftp://example.com' })).toThrow(OptionsError)
+    expect(() => createUrlSchema({ baseOrigin: 'https://example.com/path' })).toThrow(OptionsError)
+  })
+
+  it('should not throw an error when the options are valid', () => {
+    expect(() =>
+      createUrlSchema({
+        whitelist: {
+          protocols: ['http', 'https'],
+          hosts: ['example.com'],
+        },
+      }),
+    ).not.toThrow()
+  })
+
+  it('should reject relaative URLs when the base URL is not provided', () => {
+    const schema = createUrlSchema()
+    expect(() => schema.parse('/path')).toThrow(UrlValidationError)
+  })
+})

packages/validators/src/url/index.ts

@@ -1,10 +1,10 @@
-import { ZodError } from 'zod'
+import { ZodError, ZodSchema, ZodTypeDef } from 'zod'
 import { fromError } from 'zod-validation-error'
 
 import { OptionsError } from '@/common/errors'
 import { UrlValidationError } from '@/url/errors'
 import { defaultOptions, optionsSchema, UrlValidatorOptions } from '@/url/options'
-import { createUrlSchema } from '@/url/schema'
+import { toSchema } from '@/url/schema'
 
 /**
  * Parses URLs according to WHATWG standards and validates against a whitelist of allowed protocols and hostnames,
@@ -36,7 +36,7 @@ export class UrlValidator {
   constructor(options: UrlValidatorOptions = defaultOptions) {
     const result = optionsSchema.safeParse({ ...defaultOptions, ...options })
     if (result.success) {
-      this.schema = createUrlSchema(result.data)
+      this.schema = toSchema(result.data)
       return
     }
     throw new OptionsError(fromError(result.error).toString())
@@ -63,3 +63,21 @@ export class UrlValidator {
     }
   }
 }
+
+/**
+ * Create a schema that validates user-supplied URLs. This does the same thing as the `UrlValidator` class,
+ * but it returns a Zod schema which can be used as part of a larger schema.
+ *
+ * @param options - The options to use for validation
+ * @throws {@link OptionsError} If the options are invalid
+ * @returns A Zod schema that validates paths.
+ *
+ * @public
+ */
+export const createUrlSchema = (options: UrlValidatorOptions = defaultOptions): ZodSchema<URL, ZodTypeDef, string> => {
+  const result = optionsSchema.safeParse({ ...defaultOptions, ...options })
+  if (result.success) {
+    return toSchema(result.data)
+  }
+  throw new OptionsError(fromError(result.error).toString())
+}

packages/validators/src/url/schema.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 import { ParsedUrlValidatorOptions } from '@/url/options'
 import { isSafeUrl, resolveRelativeUrl } from '@/url/utils'
 
-export const createUrlSchema = (options: ParsedUrlValidatorOptions) => {
+export const toSchema = (options: ParsedUrlValidatorOptions) => {
   return z
     .string()
     .transform(url => resolveRelativeUrl(url, options.baseOrigin))

turbo.json

@@ -8,11 +8,14 @@
       "dependsOn": ["build"]
     },
     "build:docs": {
-      "dependsOn": ["^build:docs", "build:report"]
+      "dependsOn": ["^build:report", "^build:docs"]
     },
     "lint": {
       "dependsOn": ["^lint"]
     },
+    "lint:fix": {
+      "dependsOn": ["^lint:fix"]
+    },
     "format": {
       "dependsOn": ["^format"]
     },