[Suggestions] Improving types and expose colours as named exports about ansis

[webdiscus]

Hi,

thank you for an interesting suggestions.
I will certainly take the time to add your suggestions in new release.

Bests,
Dimitri

[webdiscus]

@panoply

according Template literals Specifications, used \n will be expected as \ and n chars in sting.

tag`string text line 1 \n string text line 2`;

expected string

string text line 1 \n string text line 2

Therefore I will not break the Specifications ;-)

[panoply]

I can't imagine that anybody will use \n \t in template string instead of native LF.

👌🏼 To reiterate, it is no issue for me personally, just confirming the intended design.

Thanks again for your brilliant work here. This project is both emancipating and a joy to leverage . These new capabilities have solidified it as breadwinner in the nexus (imo).

I'll go ahead and close this.

[panoply]

Great stuff, let me know if you need help.

[webdiscus]

Hi @panoply,

I have now time for this ticket and would like to clarify some questions.

What is your goal of Named Exports?

1. Named Exports to save the size of imported code.

The unpacked dist code size is 3.1 KB only. Here is nothing to spare. And this module is so designed, that to export separate method is impossible, because each method (red, bold, hex, etc) is dynamic getter, not object property. This is the feature for the chained syntax.
Therefore your suggestion can not work:

export const {
  red,
  green,
  blue,
  // etc etc etc
} = ansis;

Also, my answer - no, is impossible.

2. Named Exports for shortcuts to function name, e.g. using red() instead of ansis.red().
   The export could be in separate file colors.js:

import ansis from './index.js';

export const red = ansis.red;
export const green = ansis.green;
export const blue = ansis.blue;
// etc.

Usage:

import { red, green, blue } from 'ansis/colors';

console.log(red('red'));
console.log(green.bold('green'));
console.log(blue.underline.italic('blue'));

Note

• the ansis lib will be completely imported, you spare nothing
• imported shortcuts supports chained syntax

Does it make sense to create the colors.js file with shortcuts for all styles when the package size will be even bigger?
I can do it, no problem, but whether make it sense for you?

[webdiscus]

@panoply

yet two questions.

1. Type naming for list of ANSI styles & colors

Your suggestion:

export type Colors = (
  | 'cyan'
  | 'cyanBright'
  | 'bold'
  // ...
)
type StringUnion<T, B extends string> = T | (B & Record<never, never>);
export type ColorsExtend<T extends string> = StringUnion<Colors, T>;

import ansis, { Colors, ColorsExtend } from 'ansis' 

const write = (style: ColorsExtend <'pink' | 'orange'>, message: string) => {
  console.log(ansis[style](message));
}

Yes, many ANSI libs use the type name Colors, but it is too common word and can be used by other libs working with colors.
To avoid naming collision I would suggest use specific naming, e.g. AnsiColors.

What do you like as type name for list of ANSI styles & colors?

• AnsiColors (note: Ansi.., w/o (s) after i) / AnsiColorsExtend
• AnsiStyles (note: Ansi.., w/o (s) after i) / AnsiStylesExtend
• Colors / ColorsExtend
• Styles / StylesExtend
• your variant?

Or better split the list of styles & colors to separate types, like by chalk

// colors only
export type Colors = (
  | 'red'
  | 'green'
  | 'bgMagentaBright'
  // ...
)

// styles and modifiers
export type Styles = (
  | 'reset'
  | 'inverse'
  | 'bold'
  // ...
)

Should be colors splited to ForegroundColor and BackgroundColor, like by chalk?

2. How to extend default colors in ansis?

Your example:

import ansis, { ColorsExtend } from 'ansis' 

const pink = ansis.hex('#FF75D1');
const orange = ansis.hex('#FFAB40');

const write = (style: ColorsExtend <'pink' | 'orange'>, message: string) => {
    console.log(ansis[style](message));
}

But how to use the write function?

write('red', 'message'); // default style OK
write('pink', 'message'); // ERROR, the 'pink' style is not registered in 'ansis'

Do you have an idea how the ansis instance should be extended with new colors?
For example:
variant 1

/**
* @param {string} name
* @param {Ansis} style
*/
ansis.extend(name, style) {
}

// usage
const pink = ansis.hex('#FF75D1');
ansis.extend('pink', pink);

ansis.pink.bold('text');
ansis['pink']('text');

OR

variant 2

/**
* @param {string} name
* @param {string} hex
*/
ansis.extend(name, hex) {
}

// usage
ansis.extend('pink', '#FF75D1');

ansis.pink.bold('text');
ansis['pink']('text');

Your variant?

Solution that works right now:

import ansis, { Ansis } from 'ansis' 

const pink = ansis.hex('#FF75D1'); // the instance of the Ansis interface

const write = (style: Ansis, message: string) => {
    console.log(style(message));
}

write(pink, 'message'); // OK

[webdiscus]

@panoply

can you please try new version 1.5.0:

• feat: added named export of colors with supports for chained syntax:

  import { red, green, yellow } from 'ansis/colors';
  console.log(red.bold.underline`text`);

• feat: added extending of base colors with named custom truecolor
  Using in TypeScript:

import ansis, { AnsiColorsExtend } from 'ansis';

// extend base colors
ansis.extend({
  pink: '#FF75D1',
  orange: '#FFAB40',
});

const write = (style: AnsiColorsExtend<'pink' | 'orange'>, message: string) => {
  console.log(ansis[style](message));
}

write('red', 'message'); // base color OK
write('pink', 'message'); // extended color OK
write('orange', 'message'); // extended color OK
//write('unknown', 'message'); // TypeScript Error, OK

• feat: added supports the nested template literal syntax:

import { red, green, greenBright, cyan, cyanBright, bold, italic, hex } from 'ansis/colors';

// define custom colors
const pink = hex('#FF75D1');
const orange = hex('#FFAB40');

// template string
red`text`; // base color
pink`text`; // custom color
orange`text`;  // custom color

// nested
white`MakBookPro, ${cyan`RAM:`} 64 GB`;

[panoply]

@webdiscus Utterly brilliant stuff here. I was in the middle of writing a response to your questions but it seems as if you've covered everything. I will bring in the latest version and get back to you.

RE distributed bundle size

In terms of package size, you might be able to bring this size down even further (if it is a key concern of yours) by using an alternative compiler. For example, tsup leverages esbuild under the hood and treeshakes the distributed bundle with rollup. The benefits here being that you can potentially mangle methods to get the smallest possible size.

[webdiscus]

@panoply
The v1.5.0 is deprecated, because has error in CommonJS mode. Use please fixed v1.5.1.

P.S. I use the rollup with plugins to build minified treeshaked distribution bundle. The rollup-plugin-terser compile very small bundle.js compatible with ECMA 2019 (last version supported by Node.js 12).
But thanks for tip, I look this tools.

[panoply]

@webdiscus great stuff here.

Might be worth stripping literals, for example:

import { green } from 'ansis/colors'

console.log(green`\n Hello World`) // Here we denote a newline character

Though personally not a issue for me, I'd assume folks would expect characters like \n, \t etc to be stripped or escaped with double slash, so the above sample, should output (using ␊ to denote newline):

␊
Hello World

Opposed to

\n Hello World