Add docs comments and tests for TypeScript definitions (#299)

Fixes #293

index.d.ts

@@ -0,0 +1,282 @@
+export const enum Level {
+	/**
+	 * All colors disabled.
+	 */
+	None = 0,
+
+	/**
+	 * Basic 16 colors support.
+	 */
+	Basic = 1,
+
+	/**
+	 * ANSI 256 colors support.
+	 */
+	Ansi256 = 2,
+
+	/**
+	 * Truecolor 16 million colors support.
+	 */
+	TrueColor = 3
+}
+
+export interface Options {
+	/**
+	 * Enable or disable Chalk.
+	 *
+	 * @default true
+	 */
+	enabled?: boolean;
+
+	/**
+	 * Specify the color support for Chalk. By default,
+	 * color support is automatically detected based on
+	 * the environment.
+	 */
+	level?: Level;
+}
+
+export interface Constructor {
+	/**
+	 * Return a new Chalk instance.
+	 */
+	new (options?: Options): Chalk;
+
+	/**
+	 * Return a new Chalk instance.
+	 */
+	(options?: Options): Chalk;
+}
+
+/**
+ * Detect whether the terminal supports color.
+ */
+export interface ColorSupport {
+	/**
+	 * The color level used by Chalk.
+	 */
+	level: Level;
+
+	/**
+	 * Return whether Chalk supports basic 16 colors.
+	 */
+	hasBasic: boolean;
+
+	/**
+	 * Return whether Chalk supports ANSI 256 colors.
+	 */
+	has256: boolean;
+
+	/**
+	 * Return whether Chalk supports Truecolor 16 million colors.
+	 */
+	has16m: boolean;
+}
+
+export interface Chalk {
+	(...text: string[]): string;
+
+	(text: TemplateStringsArray, ...placeholders: string[]): string;
+
+	/**
+	 * Return a new Chalk instance.
+	 */
+	constructor: Constructor;
+
+	/**
+	 * Enable or disable Chalk.
+	 *
+	 * @default true
+	 */
+	enabled: boolean;
+
+	/**
+	 * The color support for Chalk. By default, color
+	 * support is automatically detected based on the
+	 * environment.
+	 */
+	level: Level;
+
+	/**
+	 * Use HEX value to set text color.
+	 *
+	 * @param color - Hexadecimal value representing the desired color.
+	 *
+	 * @example
+	 *
+	 * import chalk from 'chalk';
+	 *
+	 * chalk.hex('#DEADED');
+	 */
+	hex(color: string): this;
+
+	/**
+	 * Use keyword color value to set text color.
+	 *
+	 * @param color - Keyword value representing the desired color.
+	 *
+	 * @example
+	 *
+	 * import chalk from 'chalk';
+	 *
+	 * chalk.keyword('orange');
+	 */
+	keyword(color: string): this;
+
+	/**
+	 * Use RGB values to set text color.
+	 */
+	rgb(red: number, green: number, blue: number): this;
+
+	/**
+	 * Use HSL values to set text color.
+	 */
+	hsl(hue: number, saturation: number, lightness: number): this;
+
+	/**
+	 * Use HSV values to set text color.
+	 */
+	hsv(hue: number, saturation: number, value: number): this;
+
+	/**
+	 * Use HWB values to set text color.
+	 */
+	hwb(hue: number, whiteness: number, blackness: number): this;
+
+	/**
+	 * Use HEX value to set background color.
+	 *
+	 * @param color - Hexadecimal value representing the desired color.
+	 *
+	 * @example
+	 *
+	 * import chalk from 'chalk';
+	 *
+	 * chalk.bgHex('#DEADED');
+	 */
+	bgHex(color: string): this;
+
+	/**
+	 * Use keyword color value to set background color.
+	 *
+	 * @param color - Keyword value representing the desired color.
+	 *
+	 * @example
+	 *
+	 * import chalk from 'chalk';
+	 *
+	 * chalk.bgKeyword('orange');
+	 */
+	bgKeyword(color: string): this;
+
+	/**
+	 * Use RGB values to set background color.
+	 */
+	bgRgb(red: number, green: number, blue: number): this;
+
+	/**
+	 * Use HSL values to set background color.
+	 */
+	bgHsl(hue: number, saturation: number, lightness: number): this;
+
+	/**
+	 * Use HSV values to set background color.
+	 */
+	bgHsv(hue: number, saturation: number, value: number): this;
+
+	/**
+	 * Use HWB values to set background color.
+	 */
+	bgHwb(hue: number, whiteness: number, blackness: number): this;
+
+	/**
+	 * Modifier: Resets the current color chain.
+	 */
+	readonly reset: this;
+
+	/**
+	 * Modifier: Make text bold.
+	 */
+	readonly bold: this;
+
+	/**
+	 * Modifier: Emitting only a small amount of light.
+	 */
+	readonly dim: this;
+
+	/**
+	 * Modifier: Make text italic. (Not widely supported)
+	 */
+	readonly italic: this;
+
+	/**
+	 * Modifier: Make text underline. (Not widely supported)
+	 */
+	readonly underline: this;
+
+	/**
+	 * Modifier: Inverse background and foreground colors.
+	 */
+	readonly inverse: this;
+
+	/**
+	 * Modifier: Prints the text, but makes it invisible.
+	 */
+	readonly hidden: this;
+
+	/**
+	 * Modifier: Puts a horizontal line through the center of the text. (Not widely supported)
+	 */
+	readonly strikethrough: this;
+
+	/**
+	 * Modifier: Prints the text only when Chalk is enabled. Can be useful for things that are purely cosmetic.
+	 */
+	readonly visible: this;
+
+	readonly black: this;
+	readonly red: this;
+	readonly green: this;
+	readonly yellow: this;
+	readonly blue: this;
+	readonly magenta: this;
+	readonly cyan: this;
+	readonly white: this;
+	readonly gray: this;
+	readonly grey: this;
+	readonly blackBright: this;
+	readonly redBright: this;
+	readonly greenBright: this;
+	readonly yellowBright: this;
+	readonly blueBright: this;
+	readonly magentaBright: this;
+	readonly cyanBright: this;
+	readonly whiteBright: this;
+
+	readonly bgBlack: this;
+	readonly bgRed: this;
+	readonly bgGreen: this;
+	readonly bgYellow: this;
+	readonly bgBlue: this;
+	readonly bgMagenta: this;
+	readonly bgCyan: this;
+	readonly bgWhite: this;
+	readonly bgBlackBright: this;
+	readonly bgRedBright: this;
+	readonly bgGreenBright: this;
+	readonly bgYellowBright: this;
+	readonly bgBlueBright: this;
+	readonly bgMagentaBright: this;
+	readonly bgCyanBright: this;
+	readonly bgWhiteBright: this;
+}
+
+/**
+ * Main Chalk object that allows to chain styles together.
+ * Call the last one as a method with a string argument.
+ * Order doesn't matter, and later styles take precedent in case of a conflict.
+ * This simply means that `chalk.red.yellow.green` is equivalent to `chalk.green`.
+ */
+declare const chalk: Chalk & { supportsColor: ColorSupport };
+
+export default chalk;

index.js

@@ -199,7 +199,7 @@ function applyStyle(...args) {
 }
 
 function chalkTag(chalk, ...strings) {
-	const firstString = strings[0];
+	const [firstString] = strings;
 
 	if (!Array.isArray(firstString)) {
 		// If chalk() was called by itself or with a string,

index.test-d.ts

@@ -0,0 +1,139 @@
+import {expectType} from 'tsd-check';
+import chalk, {Level, Chalk, ColorSupport} from '.';
+
+// - Helpers -
+type colorReturn = Chalk & {supportsColor: ColorSupport};
+
+// - Level -
+expectType<number>(Level.None);
+expectType<number>(Level.Basic);
+expectType<number>(Level.Ansi256);
+expectType<number>(Level.TrueColor);
+
+// - supportsColor -
+expectType<boolean>(chalk.supportsColor.hasBasic);
+expectType<boolean>(chalk.supportsColor.has256);
+expectType<boolean>(chalk.supportsColor.has16m);
+
+// - Chalk -
+// -- Constructor --
+expectType<Chalk>(chalk.constructor());
+expectType<Chalk>(chalk.constructor());
+expectType<Chalk>(new chalk.constructor({level: 1}));
+
+// -- Properties --
+expectType<boolean>(chalk.enabled);
+expectType<Level>(chalk.level);
+
+// -- Template literal --
+expectType<string>(chalk``);
+const name = 'John';
+expectType<string>(chalk`Hello {bold.red ${name}}`);
+
+// -- Color methods --
+expectType<colorReturn>(chalk.hex('#DEADED'));
+expectType<colorReturn>(chalk.keyword('orange'));
+expectType<colorReturn>(chalk.rgb(0, 0, 0));
+expectType<colorReturn>(chalk.hsl(0, 0, 0));
+expectType<colorReturn>(chalk.hsv(0, 0, 0));
+expectType<colorReturn>(chalk.hwb(0, 0, 0));
+expectType<colorReturn>(chalk.bgHex('#DEADED'));
+expectType<colorReturn>(chalk.bgKeyword('orange'));
+expectType<colorReturn>(chalk.bgRgb(0, 0, 0));
+expectType<colorReturn>(chalk.bgHsl(0, 0, 0));
+expectType<colorReturn>(chalk.bgHsv(0, 0, 0));
+expectType<colorReturn>(chalk.bgHwb(0, 0, 0));
+
+// -- Modifiers --
+expectType<string>(chalk.reset('foo'));
+expectType<string>(chalk.bold('foo'));
+expectType<string>(chalk.dim('foo'));
+expectType<string>(chalk.italic('foo'));
+expectType<string>(chalk.underline('foo'));
+expectType<string>(chalk.inverse('foo'));
+expectType<string>(chalk.hidden('foo'));
+expectType<string>(chalk.strikethrough('foo'));
+expectType<string>(chalk.visible('foo'));
+expectType<string>(chalk.reset`foo`);
+expectType<string>(chalk.bold`foo`);
+expectType<string>(chalk.dim`foo`);
+expectType<string>(chalk.italic`foo`);
+expectType<string>(chalk.underline`foo`);
+expectType<string>(chalk.inverse`foo`);
+expectType<string>(chalk.hidden`foo`);
+expectType<string>(chalk.strikethrough`foo`);
+expectType<string>(chalk.visible`foo`);
+
+// -- Colors --
+expectType<string>(chalk.black('foo'));
+expectType<string>(chalk.red('foo'));
+expectType<string>(chalk.green('foo'));
+expectType<string>(chalk.yellow('foo'));
+expectType<string>(chalk.blue('foo'));
+expectType<string>(chalk.magenta('foo'));
+expectType<string>(chalk.cyan('foo'));
+expectType<string>(chalk.white('foo'));
+expectType<string>(chalk.gray('foo'));
+expectType<string>(chalk.grey('foo'));
+expectType<string>(chalk.blackBright('foo'));
+expectType<string>(chalk.redBright('foo'));
+expectType<string>(chalk.greenBright('foo'));
+expectType<string>(chalk.yellowBright('foo'));
+expectType<string>(chalk.blueBright('foo'));
+expectType<string>(chalk.magentaBright('foo'));
+expectType<string>(chalk.cyanBright('foo'));
+expectType<string>(chalk.whiteBright('foo'));
+expectType<string>(chalk.bgBlack('foo'));
+expectType<string>(chalk.bgRed('foo'));
+expectType<string>(chalk.bgGreen('foo'));
+expectType<string>(chalk.bgYellow('foo'));
+expectType<string>(chalk.bgBlue('foo'));
+expectType<string>(chalk.bgMagenta('foo'));
+expectType<string>(chalk.bgCyan('foo'));
+expectType<string>(chalk.bgWhite('foo'));
+expectType<string>(chalk.bgBlackBright('foo'));
+expectType<string>(chalk.bgRedBright('foo'));
+expectType<string>(chalk.bgGreenBright('foo'));
+expectType<string>(chalk.bgYellowBright('foo'));
+expectType<string>(chalk.bgBlueBright('foo'));
+expectType<string>(chalk.bgMagentaBright('foo'));
+expectType<string>(chalk.bgCyanBright('foo'));
+expectType<string>(chalk.bgWhiteBright('foo'));
+expectType<string>(chalk.black`foo`);
+expectType<string>(chalk.red`foo`);
+expectType<string>(chalk.green`foo`);
+expectType<string>(chalk.yellow`foo`);
+expectType<string>(chalk.blue`foo`);
+expectType<string>(chalk.magenta`foo`);
+expectType<string>(chalk.cyan`foo`);
+expectType<string>(chalk.white`foo`);
+expectType<string>(chalk.gray`foo`);
+expectType<string>(chalk.grey`foo`);
+expectType<string>(chalk.blackBright`foo`);
+expectType<string>(chalk.redBright`foo`);
+expectType<string>(chalk.greenBright`foo`);
+expectType<string>(chalk.yellowBright`foo`);
+expectType<string>(chalk.blueBright`foo`);
+expectType<string>(chalk.magentaBright`foo`);
+expectType<string>(chalk.cyanBright`foo`);
+expectType<string>(chalk.whiteBright`foo`);
+expectType<string>(chalk.bgBlack`foo`);
+expectType<string>(chalk.bgRed`foo`);
+expectType<string>(chalk.bgGreen`foo`);
+expectType<string>(chalk.bgYellow`foo`);
+expectType<string>(chalk.bgBlue`foo`);
+expectType<string>(chalk.bgMagenta`foo`);
+expectType<string>(chalk.bgCyan`foo`);
+expectType<string>(chalk.bgWhite`foo`);
+expectType<string>(chalk.bgBlackBright`foo`);
+expectType<string>(chalk.bgRedBright`foo`);
+expectType<string>(chalk.bgGreenBright`foo`);
+expectType<string>(chalk.bgYellowBright`foo`);
+expectType<string>(chalk.bgBlueBright`foo`);
+expectType<string>(chalk.bgMagentaBright`foo`);
+expectType<string>(chalk.bgCyanBright`foo`);
+expectType<string>(chalk.bgWhiteBright`foo`);
+
+// -- Complex --
+expectType<string>(chalk.red.bgGreen.underline('foo'));
+expectType<string>(chalk.underline.red.bgGreen('foo'));

package.json

@@ -8,13 +8,13 @@
 		"node": ">=6"
 	},
 	"scripts": {
-		"test": "xo && nyc ava && tsc --project types && flow --max-warnings=0",
+		"test": "xo && nyc ava && tsd-check && flow --max-warnings=0",
 		"bench": "matcha benchmark.js"
 	},
 	"files": [
 		"index.js",
 		"templates.js",
-		"types/index.d.ts",
+		"index.d.ts",
 		"index.js.flow"
 	],
 	"keywords": [
@@ -54,10 +54,11 @@
 		"matcha": "^0.7.0",
 		"nyc": "^13.0.1",
 		"resolve-from": "^4.0.0",
-		"typescript": "^3.0.3",
-		"xo": "^0.23.0"
+		"tsd-check": "^0.2.1",
+		"typescript": "^2.5.3",
+		"xo": "0.20.3"
 	},
-	"types": "types/index.d.ts",
+	"types": "index.d.ts",
 	"xo": {
 		"ignores": [
 			"test/_flow.js"

readme.md

@@ -178,15 +178,15 @@ Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=
 
 ### Modifiers
 
-- `reset`
-- `bold`
-- `dim`
-- `italic` *(Not widely supported)*
-- `underline`
-- `inverse`
-- `hidden`
-- `strikethrough` *(Not widely supported)*
-- `visible` (Text is emitted only if enabled)
+- `reset` - Resets the current color chain.
+- `bold` - Make text bold.
+- `dim` - Emitting only a small amount of light.
+- `italic` - Make text italic. *(Not widely supported)*
+- `underline` - Make text underline. *(Not widely supported)*
+- `inverse`- Inverse background and foreground colors.
+- `hidden` - Prints the text, but makes it invisible.
+- `strikethrough` - Puts a horizontal line through the center of the text. *(Not widely supported)*
+- `visible`- Prints the text only when Chalk is enabled. Can be useful for things that are purely cosmetic.
 
 ### Colors
 

templates.js

@@ -50,7 +50,7 @@ function parseStyle(style) {
 	let matches;
 
 	while ((matches = STYLE_REGEX.exec(style)) !== null) {
-		const name = matches[1];
+		const name = matches[1]; // eslint-disable-line prefer-destructuring
 
 		if (matches[2]) {
 			const args = parseArguments(name, matches[2]);

types/index.d.ts

@@ -1,97 +0,0 @@
-// Type definitions for Chalk
-// Definitions by: Thomas Sauer <https://github.com/t-sauer>
-
-export const enum Level {
-	None = 0,
-	Basic = 1,
-	Ansi256 = 2,
-	TrueColor = 3
-}
-
-export interface ChalkOptions {
-	enabled?: boolean;
-	level?: Level;
-}
-
-export interface ChalkConstructor {
-	new (options?: ChalkOptions): Chalk;
-	(options?: ChalkOptions): Chalk;
-}
-
-export interface ColorSupport {
-	level: Level;
-	hasBasic: boolean;
-	has256: boolean;
-	has16m: boolean;
-}
-
-export interface Chalk {
-	(...text: string[]): string;
-	(text: TemplateStringsArray, ...placeholders: string[]): string;
-	constructor: ChalkConstructor;
-	enabled: boolean;
-	level: Level;
-	rgb(r: number, g: number, b: number): this;
-	hsl(h: number, s: number, l: number): this;
-	hsv(h: number, s: number, v: number): this;
-	hwb(h: number, w: number, b: number): this;
-	bgHex(color: string): this;
-	bgKeyword(color: string): this;
-	bgRgb(r: number, g: number, b: number): this;
-	bgHsl(h: number, s: number, l: number): this;
-	bgHsv(h: number, s: number, v: number): this;
-	bgHwb(h: number, w: number, b: number): this;
-	hex(color: string): this;
-	keyword(color: string): this;
-
-	readonly reset: this;
-	readonly bold: this;
-	readonly dim: this;
-	readonly italic: this;
-	readonly underline: this;
-	readonly inverse: this;
-	readonly hidden: this;
-	readonly strikethrough: this;
-
-	readonly visible: this;
-
-	readonly black: this;
-	readonly red: this;
-	readonly green: this;
-	readonly yellow: this;
-	readonly blue: this;
-	readonly magenta: this;
-	readonly cyan: this;
-	readonly white: this;
-	readonly gray: this;
-	readonly grey: this;
-	readonly blackBright: this;
-	readonly redBright: this;
-	readonly greenBright: this;
-	readonly yellowBright: this;
-	readonly blueBright: this;
-	readonly magentaBright: this;
-	readonly cyanBright: this;
-	readonly whiteBright: this;
-
-	readonly bgBlack: this;
-	readonly bgRed: this;
-	readonly bgGreen: this;
-	readonly bgYellow: this;
-	readonly bgBlue: this;
-	readonly bgMagenta: this;
-	readonly bgCyan: this;
-	readonly bgWhite: this;
-	readonly bgBlackBright: this;
-	readonly bgRedBright: this;
-	readonly bgGreenBright: this;
-	readonly bgYellowBright: this;
-	readonly bgBlueBright: this;
-	readonly bgMagentaBright: this;
-	readonly bgCyanBright: this;
-	readonly bgWhiteBright: this;
-}
-
-declare const chalk: Chalk & { supportsColor: ColorSupport };
-
-export default chalk

types/test.ts

@@ -1,56 +0,0 @@
-import chalk, {Level} from '..';
-
-chalk.underline('foo');
-chalk.red('foo');
-chalk.bgRed('foo');
-
-const name = 'Josh';
-chalk`Hello {bold.red ${name}}`;
-
-chalk.red`foo`;
-chalk.underline`foo`;
-chalk`foo`;
-
-chalk.red.bgGreen.underline('foo');
-chalk.underline.red.bgGreen('foo');
-
-chalk.grey('foo');
-
-chalk.constructor({level: 1});
-const ctx = chalk.constructor({level: Level.TrueColor });
-ctx('foo');
-ctx.red('foo');
-ctx`foo`;
-
-chalk.enabled = true;
-chalk.level = 1;
-chalk.level = Level.Ansi256;
-
-chalk.level === Level.Ansi256;
-
-let chalkInstance = new chalk.constructor();
-chalkInstance = chalk.constructor();
-
-chalkInstance.blue('foo');
-chalkInstance`foo`;
-
-let x = 'imastring';
-x = chalk();
-
-chalk.enabled;
-chalk.level;
-chalk.supportsColor.level;
-chalk.supportsColor.has16m;
-chalk.supportsColor.has256;
-chalk.supportsColor.hasBasic;
-
-chalk.keyword('orange').bgBlue('foo');
-chalk.hex('#123456').bgBlue('foo');
-chalk.rgb(1, 14, 9).bgBlue('foo');
-chalk.hsl(1, 14, 9).bgBlue('foo');
-chalk.hsv(1, 14, 9).bgBlue('foo');
-chalk.hwb(1, 14, 9).bgBlue('foo');
-
-chalk.visible('foo');
-chalk.red.visible('foo');
-chalk.visible.red('foo');