cli-truncate 1.1.0 → 2.0.0

package/index.d.ts

@@ -0,0 +1,96 @@
+declare namespace cliTruncate {
+	interface Options {
+		/**
+		Position to truncate the string.
+
+		@default 'end'
+		*/
+		readonly position?: 'start' | 'middle' | 'end';
+
+		/**
+		Add a space between the text and the ellipsis.
+
+		@default false
+
+		@example
+		```
+		cliTruncate('unicorns', 5, {position: 'end', space: true});
+		//=> 'uni …'
+
+		cliTruncate('unicorns', 5, {position: 'end', space: false});
+		//=> 'unic…'
+
+		cliTruncate('unicorns', 6, {position: 'start', space: true});
+		//=> '… orns'
+
+		cliTruncate('unicorns', 7, {position: 'middle', space: true});
+		//=> 'uni … s'
+		```
+		*/
+		readonly space?: boolean;
+
+		/**
+		Truncate the string from a whitespace if it is within 3 characters from the actual breaking point.
+
+		@default false
+
+		@example
+		```
+		cliTruncate('unicorns rainbow dragons', 20, {position: 'start', preferTruncationOnSpace: true});
+		//=> '…rainbow dragons'
+
+		cliTruncate('unicorns rainbow dragons', 20, {position: 'middle', preferTruncationOnSpace: true});
+		//=> 'unicorns…dragons'
+
+		cliTruncate('unicorns rainbow dragons', 6, {position: 'end', preferTruncationOnSpace: true});
+		//=> 'unico…'
+		````
+		*/
+		readonly preferTruncationOnSpace?: boolean;
+	}
+}
+
+/**
+Truncate a string to a specific width in the terminal.
+
+@param text - Text to truncate.
+@param columns - Columns to occupy in the terminal.
+
+@example
+```
+import cliTruncate = require('cli-truncate');
+
+cliTruncate('unicorn', 4);
+//=> 'uni…'
+
+// Truncate at different positions
+cliTruncate('unicorn', 4, {position: 'start'});
+//=> '…orn'
+
+cliTruncate('unicorn', 4, {position: 'middle'});
+//=> 'un…n'
+
+cliTruncate('\u001B[31municorn\u001B[39m', 4);
+//=> '\u001B[31muni\u001B[39m…'
+
+// Truncate Unicode surrogate pairs
+cliTruncate('uni\uD83C\uDE00corn', 5);
+//=> 'uni\uD83C\uDE00…'
+
+// Truncate fullwidth characters
+cliTruncate('안녕하세요', 3);
+//=> '안…'
+
+// Truncate the paragraph to the terminal width
+const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.';
+cliTruncate(paragraph, process.stdout.columns));
+//=> 'Lorem ipsum dolor sit amet, consectetuer adipiscing…'
+```
+*/
+declare function cliTruncate(
+	text: string,
+	columns: number,
+	options?: cliTruncate.Options
+): string;
+
+export = cliTruncate;

package/index.js

@@ -2,16 +2,37 @@
 const sliceAnsi = require('slice-ansi');
 const stringWidth = require('string-width');
 
-module.exports = (input, columns, opts) => {
-	opts = Object.assign({
-		position: 'end'
-	}, opts);
+function getIndexOfNearestSpace(string, index, shouldSearchRight) {
+	if (string.charAt(index) === ' ') {
+		return index;
+	}
+
+	for (let i = 1; i <= 3; i++) {
+		if (shouldSearchRight) {
+			if (string.charAt(index + i) === ' ') {
+				return index + i;
+			}
+		} else if (string.charAt(index - i) === ' ') {
+			return index - i;
+		}
+	}
+
+	return index;
+}
 
-	const position = opts.position;
-	const ellipsis = '…';
+module.exports = (text, columns, options) => {
+	options = {
+		position: 'end',
+		preferTruncationOnSpace: false,
+		...options
+	};
 
-	if (typeof input !== 'string') {
-		throw new TypeError(`Expected \`input\` to be a string, got ${typeof input}`);
+	const {position, space, preferTruncationOnSpace} = options;
+	let ellipsis = '…';
+	let ellipsisWidth = 1;
+
+	if (typeof text !== 'string') {
+		throw new TypeError(`Expected \`input\` to be a string, got ${typeof text}`);
 	}
 
 	if (typeof columns !== 'number') {
@@ -26,19 +47,59 @@ module.exports = (input, columns, opts) => {
 		return ellipsis;
 	}
 
-	const length = stringWidth(input);
+	const length = stringWidth(text);
 
 	if (length <= columns) {
-		return input;
+		return text;
 	}
 
 	if (position === 'start') {
-		return ellipsis + sliceAnsi(input, length - columns + 1, length);
-	} else if (position === 'middle') {
+		if (preferTruncationOnSpace) {
+			const nearestSpace = getIndexOfNearestSpace(text, length - columns + 1, true);
+			return ellipsis + sliceAnsi(text, nearestSpace, length).trim();
+		}
+
+		if (space === true) {
+			ellipsis += ' ';
+			ellipsisWidth = 2;
+		}
+
+		return ellipsis + sliceAnsi(text, length - columns + ellipsisWidth, length);
+	}
+
+	if (position === 'middle') {
+		if (space === true) {
+			ellipsis = ' ' + ellipsis + ' ';
+			ellipsisWidth = 3;
+		}
+
 		const half = Math.floor(columns / 2);
-		return sliceAnsi(input, 0, half) + ellipsis + sliceAnsi(input, length - (columns - half) + 1, length);
-	} else if (position === 'end') {
-		return sliceAnsi(input, 0, columns - 1) + ellipsis;
+
+		if (preferTruncationOnSpace) {
+			const spaceNearFirstBreakPoint = getIndexOfNearestSpace(text, half);
+			const spaceNearSecondBreakPoint = getIndexOfNearestSpace(text, length - (columns - half) + 1, true);
+			return sliceAnsi(text, 0, spaceNearFirstBreakPoint) + ellipsis + sliceAnsi(text, spaceNearSecondBreakPoint, length).trim();
+		}
+
+		return (
+			sliceAnsi(text, 0, half) +
+			ellipsis +
+			sliceAnsi(text, length - (columns - half) + ellipsisWidth, length)
+		);
+	}
+
+	if (position === 'end') {
+		if (preferTruncationOnSpace) {
+			const nearestSpace = getIndexOfNearestSpace(text, columns - 1);
+			return sliceAnsi(text, 0, nearestSpace) + ellipsis;
+		}
+
+		if (space === true) {
+			ellipsis = ' ' + ellipsis;
+			ellipsisWidth = 2;
+		}
+
+		return sliceAnsi(text, 0, columns - ellipsisWidth) + ellipsis;
 	}
 
 	throw new Error(`Expected \`options.position\` to be either \`start\`, \`middle\` or \`end\`, got ${position}`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cli-truncate",
-	"version": "1.1.0",
+	"version": "2.0.0",
 	"description": "Truncate a string to a specific width in the terminal",
 	"license": "MIT",
 	"repository": "sindresorhus/cli-truncate",
@@ -10,13 +10,14 @@
 		"url": "sindresorhus.com"
 	},
 	"engines": {
-		"node": ">=4"
+		"node": ">=8"
 	},
 	"scripts": {
-		"test": "xo && ava"
+		"test": "xo && ava && tsd"
 	},
 	"files": [
-		"index.js"
+		"index.js",
+		"index.d.ts"
 	],
 	"keywords": [
 		"truncate",
@@ -29,14 +30,16 @@
 		"term",
 		"shell",
 		"width",
-		"ansi"
+		"ansi",
+		"string"
 	],
 	"dependencies": {
-		"slice-ansi": "^1.0.0",
-		"string-width": "^2.0.0"
+		"slice-ansi": "^2.1.0",
+		"string-width": "^4.1.0"
 	},
 	"devDependencies": {
-		"ava": "*",
-		"xo": "*"
+		"ava": "^2.1.0",
+		"tsd": "^0.7.2",
+		"xo": "^0.24.0"
 	}
 }

package/readme.md

@@ -27,6 +27,9 @@ cliTruncate('unicorn', 4, {position: 'start'});
 cliTruncate('unicorn', 4, {position: 'middle'});
 //=> 'un…n'
 
+cliTruncate('unicorns rainbow dragons', 6, {position: 'end'})
+//=> 'unico…'
+
 cliTruncate('\u001B[31municorn\u001B[39m', 4);
 //=> '\u001B[31muni\u001B[39m…'
 
@@ -47,9 +50,9 @@ cliTruncate(paragraph, process.stdout.columns));
 
 ## API
 
-### cliTruncate(input, columns, [options])
+### cliTruncate(text, columns, options?)
 
-#### input
+#### text
 
 Type: `string`
 
@@ -63,23 +66,65 @@ Columns to occupy in the terminal.
 
 #### options
 
-Type: `Object`
+Type: `object`
 
 ##### position
 
 Type: `string`<br>
-Default: `end`<br>
-Values: `start` `middle` `end`
+Default: `'end'`<br>
+Values: `'start'` `'middle'` `'end'`
 
 Position to truncate the string.
 
+##### space
 
-## Related
+Type: `boolean`<br>
+Default: `false`
 
-- [wrap-ansi](https://github.com/chalk/wrap-ansi) - Wordwrap a string with ANSI escape codes
-- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes
+Add a space between the text and the ellipsis.
+
+```js
+cliTruncate('unicorns', 5, {space: false});
+//=> 'unic…'
 
+cliTruncate('unicorns', 5, {space: true});
+//=> 'uni …'
 
-## License
+cliTruncate('unicorns', 6, {position: 'start', space: true});
+//=> '… orns'
 
-MIT © [Sindre Sorhus](https://sindresorhus.com)
+cliTruncate('unicorns', 7, {position: 'middle', space: true});
+//=> 'uni … s'
+```
+
+##### preferTruncationOnSpace
+
+Type: `boolean`<br>
+Default: `false`
+
+Truncate the string from a whitespace if it is within 3 characters from the actual breaking point.
+
+```js
+cliTruncate('unicorns rainbow dragons', 20, {position: 'start', preferTruncationOnSpace: true})
+//=> '…rainbow dragons'
+
+// without preferTruncationOnSpace
+cliTruncate('unicorns rainbow dragons', 20, {position: 'start'})
+//=> '…rns rainbow dragons'
+
+cliTruncate('unicorns rainbow dragons', 20, {position: 'middle', preferTruncationOnSpace: true})
+//=> 'unicorns…dragons'
+
+cliTruncate('unicorns rainbow dragons', 6, {position: 'end', preferTruncationOnSpace: true})
+//=> 'unico…'
+
+// preferTruncationOnSpace would have no effect if space isn't found within next 3 indexes
+cliTruncate('unicorns rainbow dragons', 6, {position: 'middle', preferTruncationOnSpace: true})
+//=> 'uni…ns'
+```
+
+
+## Related
+
+- [wrap-ansi](https://github.com/chalk/wrap-ansi) - Wordwrap a string with ANSI escape codes
+- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes