[#293] Add documentation comments and tests for TS Definitions

Notable changes:
- Move index.d.ts from types/ to project root (needed for
  tsd-check module).
- Rename test.ts to index.test-d.ts and place it under root
  (needed for tsd-check module).
- Add tsd-check module to test Typescript Definitions.

Future Work:
The properties inverse, hidden, strikethrough and visible
of Chalk interface in index.d.ts needs to be documented.
This commit is contained in:
George Gkasdrogkas 2018-09-17 16:03:17 +03:00
parent 6a14c58e54
commit 8577e6dd58
No known key found for this signature in database
GPG key ID: 3FCA70FC54D4293F
6 changed files with 480 additions and 158 deletions

325
index.d.ts vendored Normal file
View file

@ -0,0 +1,325 @@
// Type definitions for Chalk
// Project: Chalk
// Definitions by: Thomas Sauer <https://github.com/t-sauer>
// Updated definitions by: George Gkasdrogkas <https://github.com/georgegkas>
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.
*
* @param r - red
* @param g - green
* @param b - blue
*/
rgb(r: number, g: number, b: number): this;
/**
* Use HSL values to set text color.
*
* @param h - hue
* @param s - saturation
* @param l - lightness
*/
hsl(h: number, s: number, l: number): this;
/**
* Use HSV values to set text color.
*
* @param h - hue
* @param s - saturation
* @param v - value
*/
hsv(h: number, s: number, v: number): this;
/**
* Use HWB values to set text color.
*
* @param h - hue
* @param w - whiteness
* @param b - blackness
*/
hwb(h: number, w: number, b: 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.
*
* @param r - red
* @param g - green
* @param b - blue
*/
bgRgb(r: number, g: number, b: number): this;
/**
* Use HSL values to set background color.
*
* @param h - hue
* @param s - saturation
* @param l - lightness
*/
bgHsl(h: number, s: number, l: number): this;
/**
* Use HSV values to set background color.
*
* @param h - hue
* @param s - saturation
* @param v - value
*/
bgHsv(h: number, s: number, v: number): this;
/**
* Use HWB values to set background color.
*
* @param h - hue
* @param w - whiteness
* @param b - blackness
*/
bgHwb(h: number, w: number, b: 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
*/
readonly hidden: this;
/**
* Modifier
*/
readonly strikethrough: this;
/**
* Modifier
*/
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 };
/**
* Alias Options and Constructor to preserve backwards compatibility.
*/
export type ChalkOptions = Options;
export type ChalkConstructor = Constructor;
export default chalk

148
index.test-d.ts Normal file
View file

@ -0,0 +1,148 @@
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'));

View file

@ -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,13 +54,15 @@
"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",
"xo": {
"ignores": [
"test/_flow.js"
"test/_flow.js",
"*.ts"
]
}
}

97
types/index.d.ts vendored
View file

@ -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

View file

@ -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');