Merge pull request #92 from sparksuite/validate-url

Implement `validateURL`

Author: WesCossick

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "w3c-css-validator",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Easily validate CSS using W3C's public CSS validator service",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

src/build-request-url.test.ts

@@ -0,0 +1,53 @@
+// Imports
+import buildRequestURL from './build-request-url';
+
+// Tests
+describe('#buildRequestURL()', () => {
+	it('Handles parameters with text value', () => {
+		expect(
+			buildRequestURL({
+				text: '.foo { text-align: center; }',
+				medium: undefined,
+				warningLevel: undefined,
+			})
+		).toBe(
+			'https://jigsaw.w3.org/css-validator/validator?text=.foo%20%7B%20text-align%3A%20center%3B%20%7D&usermedium=all&warning=no&output=application/json&profile=css3'
+		);
+	});
+
+	it('Handles parameters with URL value', () => {
+		expect(
+			buildRequestURL({
+				url: 'https://raw.githubusercontent.com/sparksuite/w3c-css-validator/master/public/css/valid.css',
+				medium: undefined,
+				warningLevel: undefined,
+			})
+		).toBe(
+			'https://jigsaw.w3.org/css-validator/validator?uri=https%3A%2F%2Fraw.githubusercontent.com%2Fsparksuite%2Fw3c-css-validator%2Fmaster%2Fpublic%2Fcss%2Fvalid.css&usermedium=all&warning=no&output=application/json&profile=css3'
+		);
+	});
+
+	it('Uses provided parameters over default values', () => {
+		expect(
+			buildRequestURL({
+				text: '.foo { text-align: center; }',
+				medium: 'braille',
+				warningLevel: 3,
+			})
+		).toBe(
+			'https://jigsaw.w3.org/css-validator/validator?text=.foo%20%7B%20text-align%3A%20center%3B%20%7D&usermedium=braille&warning=2&output=application/json&profile=css3'
+		);
+	});
+
+	it('Complains if text and URL values are provided simultaneously', () => {
+		expect(() =>
+			buildRequestURL({
+				text: '.foo { text-align: center; }',
+				// @ts-expect-error: We're trying to force an error here
+				url: 'https://raw.githubusercontent.com/sparksuite/w3c-css-validator/master/public/css/valid.css',
+				medium: undefined,
+				warningLevel: undefined,
+			})
+		).toThrow('Only a text or a URL value can be provided');
+	});
+});

src/build-request-url.ts

@@ -0,0 +1,31 @@
+// Imports
+import { Parameters } from './types/parameters';
+
+// Helper function that takes in parameters and builds a URL to make a request with
+function buildRequestURL(parameters: Parameters): string {
+	// Validate input
+	if ('text' in parameters && 'url' in parameters) {
+		throw new Error('Only a text or a URL value can be provided');
+	}
+
+	// Return request URL
+	const params = {
+		...('text' in parameters && parameters.text !== undefined
+			? {
+					text: encodeURIComponent(parameters.text),
+			  }
+			: {
+					uri: encodeURIComponent(parameters.url),
+			  }),
+		usermedium: parameters?.medium ?? 'all',
+		warning: parameters?.warningLevel ? parameters.warningLevel - 1 : 'no',
+		output: 'application/json',
+		profile: 'css3',
+	};
+
+	return `https://jigsaw.w3.org/css-validator/validator?${Object.entries(params)
+		.map(([key, val]) => `${key}=${val}`)
+		.join('&')}`;
+}
+
+export default buildRequestURL;

src/index.ts

@@ -1,9 +1,11 @@
 // Imports
 import validateText from './validate-text';
+import validateURL from './validate-url';
 
 // Validates CSS using W3C's public CSS validator service
 const cssValidator = {
 	validateText,
+	validateURL,
 };
 
 export = cssValidator;

src/retrieve-validation/index.ts

@@ -9,11 +9,13 @@ export interface W3CCSSValidatorResponse {
 		errors?: {
 			line: number;
 			message: string;
+			source?: string;
 		}[];
 		warnings?: {
 			line: number;
 			level: 0 | 1 | 2;
 			message: string;
+			source?: string;
 		}[];
 	};
 }

src/types/options.ts

@@ -0,0 +1,14 @@
+interface OptionsBase {
+	medium?: 'all' | 'braille' | 'embossed' | 'handheld' | 'print' | 'projection' | 'screen' | 'speech' | 'tty' | 'tv';
+	timeout?: number;
+}
+
+export interface OptionsWithoutWarnings extends OptionsBase {
+	warningLevel?: 0;
+}
+
+export interface OptionsWithWarnings extends OptionsBase {
+	warningLevel: 1 | 2 | 3;
+}
+
+export type Options = OptionsWithWarnings | OptionsWithoutWarnings;

src/types/parameters.ts

@@ -0,0 +1,18 @@
+import { Options } from './options';
+
+interface ParametersBase {
+	medium: Options['medium'];
+	warningLevel: Options['warningLevel'];
+}
+
+interface TextParameters extends ParametersBase {
+	text: string;
+	uri?: never;
+}
+
+interface URLParameters extends ParametersBase {
+	url: string;
+	text?: never;
+}
+
+export type Parameters = TextParameters | URLParameters;

src/types/result.ts

@@ -0,0 +1,45 @@
+export interface ValidateTextResultBase {
+	valid: boolean;
+	errors: {
+		line: number;
+		message: string;
+	}[];
+}
+
+export interface ValidateTextResultWithWarnings extends ValidateTextResultBase {
+	warnings: {
+		line: number;
+		level: 1 | 2 | 3;
+		message: string;
+	}[];
+}
+
+export interface ValidateTextResultWithoutWarnings extends ValidateTextResultBase {
+	warnings?: never;
+}
+
+export type ValidateTextResult = ValidateTextResultWithWarnings | ValidateTextResultWithoutWarnings;
+
+export interface ValidateURLResultBase {
+	valid: boolean;
+	errors: {
+		line: number;
+		url: string | null;
+		message: string;
+	}[];
+}
+
+export interface ValidateURLResultWithWarnings extends ValidateURLResultBase {
+	warnings: {
+		line: number;
+		url: string | null;
+		level: 1 | 2 | 3;
+		message: string;
+	}[];
+}
+
+export interface ValidateURLResultWithoutWarnings extends ValidateURLResultBase {
+	warnings?: never;
+}
+
+export type ValidateURLResult = ValidateURLResultWithWarnings | ValidateURLResultWithoutWarnings;

src/validate-options.test.ts

@@ -0,0 +1,38 @@
+// Imports
+import validateOptions from './validate-options';
+
+// Tests
+describe('#validateOptions()', () => {
+	it('Ignores no options', async () => {
+		expect(() => validateOptions(undefined)).not.toThrow();
+	});
+
+	it('Ignores valid options', async () => {
+		expect(() =>
+			validateOptions({
+				medium: 'braille',
+				warningLevel: 1,
+				timeout: 1000,
+			})
+		).not.toThrow();
+	});
+
+	it('Complains about invalid medium', async () => {
+		// @ts-expect-error: We're trying to force an error here
+		expect(() => validateOptions({ medium: 'fake' })).toThrow('The medium must be one of the following:');
+	});
+
+	it('Complains about invalid warning level', async () => {
+		// @ts-expect-error: We're trying to force an error here
+		expect(() => validateOptions({ warningLevel: 'fake' })).toThrow('The warning level must be one of the following:');
+	});
+
+	it('Complains about negative timeout', async () => {
+		expect(() => validateOptions({ timeout: -1 })).toThrow('The timeout must be a positive integer');
+	});
+
+	it('Complains about non-integer times', async () => {
+		expect(() => validateOptions({ timeout: Infinity })).toThrow('The timeout must be an integer');
+		expect(() => validateOptions({ timeout: 400.1 })).toThrow('The timeout must be an integer');
+	});
+});

src/validate-options.ts

@@ -0,0 +1,45 @@
+// Imports
+import { Options } from './types/options';
+
+// Define supported mediums
+const allowedMediums: Options['medium'][] = [
+	'all',
+	'braille',
+	'embossed',
+	'handheld',
+	'print',
+	'projection',
+	'screen',
+	'speech',
+	'tty',
+	'tv',
+];
+
+// Define supported warning levels
+const allowedWarningLevels: Options['warningLevel'][] = [0, 1, 2, 3];
+
+// Helper function that validates the supported options
+function validateOptions(options?: Options): void {
+	if (options) {
+		// Validate medium option
+		if (options.medium && !allowedMediums.includes(options.medium)) {
+			throw new Error(`The medium must be one of the following: ${allowedMediums.join(', ')}`);
+		}
+
+		// Validate warning level option
+		if (options.warningLevel && !allowedWarningLevels.includes(options.warningLevel)) {
+			throw new Error(`The warning level must be one of the following: ${allowedWarningLevels.join(', ')}`);
+		}
+
+		// Validate timeout option
+		if (options.timeout !== undefined && !Number.isInteger(options.timeout)) {
+			throw new Error('The timeout must be an integer');
+		}
+
+		if (options.timeout && options.timeout < 0) {
+			throw new Error('The timeout must be a positive integer');
+		}
+	}
+}
+
+export default validateOptions;

src/validate-text.test.ts

@@ -77,27 +77,6 @@ export default function testValidateText(validateText: ValidateText): void {
 			await expect(validateText(true)).rejects.toThrow('The text to be validated must be a string');
 		});
 
-		it('Complains about invalid medium', async () => {
-			// @ts-expect-error: We're trying to force an error here
-			await expect(validateText('abc', { medium: 'fake' })).rejects.toThrow('The medium must be one of the following:');
-		});
-
-		it('Complains about invalid warning level', async () => {
-			// @ts-expect-error: We're trying to force an error here
-			await expect(validateText('abc', { warningLevel: 'fake' })).rejects.toThrow(
-				'The warning level must be one of the following:'
-			);
-		});
-
-		it('Complains about negative timeout', async () => {
-			await expect(validateText('abc', { timeout: -1 })).rejects.toThrow('The timeout must be a positive integer');
-		});
-
-		it('Complains about non-integer times', async () => {
-			await expect(validateText('abc', { timeout: Infinity })).rejects.toThrow('The timeout must be an integer');
-			await expect(validateText('abc', { timeout: 400.1 })).rejects.toThrow('The timeout must be an integer');
-		});
-
 		it('Throws when the timeout is passed', async () => {
 			await expect(validateText('abc', { timeout: 1 })).rejects.toThrow('The request took longer than 1ms');
 		});