Add forceFallbackSymbols() method

index.d.ts

@@ -247,7 +247,7 @@ Symbols to use on any terminal.
 export default figureSet;
 
 /**
-Replace Unicode symbols depending on the terminal.
+Returns the input with replaced fallback symbols, if the terminal has poor Unicode support.
 
 @param string - String where the Unicode symbols will be replaced with fallback symbols depending on the terminal.
 @returns The input with replaced fallback Unicode symbols.
@@ -259,10 +259,23 @@ import figures, {replaceSymbols} from 'figures';
 console.log(replaceSymbols('✔︎ check'));
 // On terminals with Unicode symbols:  ✔︎ check
 // On other terminals:                 √ check
-
-console.log(figures.tick);
-// On terminals with Unicode symbols:  ✔︎
-// On other terminals:                 √
 ```
 */
 export function replaceSymbols(string: string): string;
+
+/**
+Returns the input with replaced fallback symbols, whether the terminal has poor Unicode support or not.
+
+@param string - String where the Unicode symbols will be replaced with fallback symbols.
+@returns The input with replaced fallback Unicode symbols.
+
+@example
+```
+import figures, {forceFallbackSymbols} from 'figures';
+
+console.log(forceFallbackSymbols('✔︎ check'));
+// On terminals with Unicode symbols:  √︎ check
+// On other terminals:                 √ check
+```
+*/
+export function forceFallbackSymbols(string: string): string;

index.js

@@ -281,11 +281,9 @@ export default figures;
 const replacements = Object.entries(specialMainSymbols);
 
 // On terminals which do not support Unicode symbols, substitute them to other symbols
-export const replaceSymbols = string => {
-	if (shouldUseMain) {
-		return string;
-	}
+export const replaceSymbols = string => shouldUseMain ? string : forceFallbackSymbols(string);
 
+export const forceFallbackSymbols = string => {
 	for (const [key, mainSymbol] of replacements) {
 		string = string.replaceAll(mainSymbol, fallbackSymbols[key]);
 	}

index.test-d.ts

@@ -1,7 +1,18 @@
-import {expectType} from 'tsd';
-import figures, {replaceSymbols, mainSymbols, fallbackSymbols} from './index.js';
+import {expectType, expectError} from 'tsd';
+import figures, {mainSymbols, fallbackSymbols, replaceSymbols, forceFallbackSymbols} from './index.js';
 
-expectType<string>(replaceSymbols('✔︎ check'));
 expectType<string>(figures.tick);
+
 expectType<string>(mainSymbols.tick);
+
 expectType<string>(fallbackSymbols.tick);
+
+expectType<string>(replaceSymbols('✔︎ check'));
+expectError(replaceSymbols('', ''));
+expectError(replaceSymbols(true));
+expectError(replaceSymbols());
+
+expectType<string>(forceFallbackSymbols('✔︎ check'));
+expectError(forceFallbackSymbols('', ''));
+expectError(forceFallbackSymbols(true));
+expectError(forceFallbackSymbols());

readme.md

@@ -17,7 +17,7 @@ npm install figures
 ## Usage
 
 ```js
-import figures, {replaceSymbols, mainSymbols, fallbackSymbols} from 'figures';
+import figures, {mainSymbols, fallbackSymbols, replaceSymbols, forceFallbackSymbols} from 'figures';
 
 console.log(figures.tick);
 // On terminals with Unicode symbols:  ✔︎
@@ -32,6 +32,10 @@ console.log(fallbackSymbols.tick);
 console.log(replaceSymbols('✔︎ check'));
 // On terminals with Unicode symbols:  ✔︎ check
 // On other terminals:                 √ check
+
+console.log(forceFallbackSymbols('✔︎ check'));
+// On terminals with Unicode symbols:  √︎ check
+// On other terminals:                 √ check
 ```
 
 ## API
@@ -52,7 +56,7 @@ Symbols to use when the terminal does not support Unicode symbols.
 
 ### replaceSymbols(string)
 
-Returns the input with replaced fallback Unicode symbols on older terminals.
+Returns the input with replaced fallback symbols, if the terminal has poor Unicode support.
 
 All the below [figures](#figures) are attached to the default export as shown in the example above.
 
@@ -62,6 +66,10 @@ Type: `string`
 
 String where the Unicode symbols will be replaced with fallback symbols depending on the terminal.
 
+### forceFallbackSymbols(string)
+
+Returns the input with replaced fallback symbols, whether the terminal has poor Unicode support or not.
+
 ## Figures
 
 `Fallback` characters are only shown when they differ from the `Main` ones.

test.js

@@ -1,13 +1,14 @@
 import test from 'ava';
 import isUnicodeSupported from 'is-unicode-supported';
-import figures, {replaceSymbols, mainSymbols, fallbackSymbols} from './index.js';
+import figures, {replaceSymbols, forceFallbackSymbols, mainSymbols, fallbackSymbols} from './index.js';
 
-const result = (mainSymbols, fallbackSymbols) => isUnicodeSupported() ? mainSymbols : fallbackSymbols;
+const getCorrectSymbols = (mainSymbols, fallbackSymbols) => isUnicodeSupported() ? mainSymbols : fallbackSymbols;
+const getFallbackSymbols = (mainSymbols, fallbackSymbols) => fallbackSymbols;
 
 console.log(`  ${Object.values(figures).join('  ')}\n`);
 
 test('figures', t => {
-	t.is(figures.tick, result('✔', '√'));
+	t.is(figures.tick, getCorrectSymbols('✔', '√'));
 });
 
 test('mainSymbols', t => {
@@ -22,12 +23,19 @@ test('replaceSymbols() keep non-figures as is', t => {
 	t.is(replaceSymbols('foo'), 'foo');
 });
 
-test('replaceSymbols() replace figures', t => {
-	t.is(replaceSymbols('✔ ✔ ✔'), result('✔ ✔ ✔', '√ √ √'));
-	t.is(replaceSymbols('✔ ✘\n★ ◼'), result('✔ ✘\n★ ◼', '√ ×\n✶ ■'));
-	t.is(replaceSymbols('✔ ✘ ★ ◼'), result('✔ ✘ ★ ◼', '√ × ✶ ■'));
+test('forceFallbackSymbols() keep non-figures as is', t => {
+	t.is(forceFallbackSymbols('foo'), 'foo');
 });
 
+const testReplace = (t, method, getSymbols) => {
+	t.is(method('✔ ✔ ✔'), getSymbols('✔ ✔ ✔', '√ √ √'));
+	t.is(method('✔ ✘\n★ ◼'), getSymbols('✔ ✘\n★ ◼', '√ ×\n✶ ■'));
+	t.is(method('✔ ✘ ★ ◼'), getSymbols('✔ ✘ ★ ◼', '√ × ✶ ■'));
+};
+
+test('replaceSymbols() replace figures', testReplace, replaceSymbols, getCorrectSymbols);
+test('forceFallbackSymbols() replace figures', testReplace, forceFallbackSymbols, getFallbackSymbols);
+
 test('figures are non-empty strings', t => {
 	for (const figure of Object.values(figures)) {
 		t.true(typeof figure === 'string' && figure.trim() !== '');