Add preferTruncationOnSpace option (#11)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: ammarbinfaisal

index.d.ts

@@ -28,6 +28,25 @@ declare namespace cliTruncate {
 		```
 		*/
 		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;
 	}
 }
 

index.js

@@ -5,10 +5,11 @@ const stringWidth = require('string-width');
 module.exports = (text, columns, options) => {
 	options = {
 		position: 'end',
+		preferTruncationOnSpace: false,
 		...options
 	};
 
-	const {position, space} = options;
+	const {position, space, preferTruncationOnSpace} = options;
 	let ellipsis = '…';
 	let ellipsisWidth = 1;
 
@@ -35,6 +36,11 @@ module.exports = (text, columns, options) => {
 	}
 
 	if (position === 'start') {
+		if (preferTruncationOnSpace) {
+			const nearestSpace = getIndexOfNearestSpace(text, length - columns + 1, true);
+			return ellipsis + sliceAnsi(text, nearestSpace, length).trim();
+		}
+
 		if (space === true) {
 			ellipsis += ' ';
 			ellipsisWidth = 2;
@@ -50,6 +56,13 @@ module.exports = (text, columns, options) => {
 		}
 
 		const half = Math.floor(columns / 2);
+
+		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 +
@@ -58,6 +71,11 @@ module.exports = (text, columns, options) => {
 	}
 
 	if (position === 'end') {
+		if (preferTruncationOnSpace) {
+			const nearestSpace = getIndexOfNearestSpace(text, columns - 1);
+			return sliceAnsi(text, 0, nearestSpace) + ellipsis;
+		}
+
 		if (space === true) {
 			ellipsis = ' ' + ellipsis;
 			ellipsisWidth = 2;
@@ -68,3 +86,21 @@ module.exports = (text, columns, options) => {
 
 	throw new Error(`Expected \`options.position\` to be either \`start\`, \`middle\` or \`end\`, got ${position}`);
 };
+
+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;
+}

index.test-d.ts

@@ -5,3 +5,4 @@ expectType<string>(cliTruncate('unicorn', 4));
 expectType<string>(cliTruncate('unicorn', 4, {position: 'start'}));
 expectType<string>(cliTruncate('unicorn', 4, {position: 'middle'}));
 expectType<string>(cliTruncate('unicorn', 4, {position: 'end'}));
+expectType<string>(cliTruncate('unicorn', 4, {position: 'end', preferTruncationOnSpace: true}));

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…'
 
@@ -94,6 +97,31 @@ 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
 

test.js

@@ -34,3 +34,12 @@ test('space option', t => {
 	t.is(cliTruncate('Plant a tree every day.', 14, {position: 'middle', space: true}), 'Plant a … day.');
 	t.is(cliTruncate('안녕하세요', 4, {position: 'start', space: true}), '… 요', 'wide char');
 });
+
+test('preferTruncationOnSpace option', t => {
+	t.is(cliTruncate('unicorns are awesome', 15, {position: 'start', preferTruncationOnSpace: true}), '…are awesome');
+	t.is(cliTruncate('dragons are awesome', 15, {position: 'end', preferTruncationOnSpace: true}), 'dragons are…');
+	t.is(cliTruncate('unicorns rainbow dragons', 6, {position: 'start', preferTruncationOnSpace: true}), '…agons');
+	t.is(cliTruncate('unicorns rainbow dragons', 6, {position: 'end', preferTruncationOnSpace: true}), 'unico…');
+	t.is(cliTruncate('unicorns rainbow dragons', 6, {position: 'middle', preferTruncationOnSpace: true}), 'uni…ns');
+	t.is(cliTruncate('unicorns partying with dragons', 20, {position: 'middle', preferTruncationOnSpace: true}), 'unicorns…dragons');
+});