Create version 3

Rewrite code in TypeScript & pure ESM
Deprecate old syntax in favor of a new one
Add new tests
Bump all dependencies
Improve README

Author: bokub

.github/workflows/run.yml

@@ -13,21 +13,25 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
       - run: npm ci
       - run: npm run lint
 
   test:
     name: Test (Node v${{ matrix.node }})
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [14, 20]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: ${{ matrix.node }}
       - run: npm ci
       - run: npm run coverage
       - name: Update code coverage
+        if: matrix.node == 20
         uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -42,7 +46,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           registry-url: https://registry.npmjs.org/
       - run: npm ci
       - name: Publish on npm

.gitignore

@@ -1,7 +1,3 @@
 node_modules
-.nyc_output
-coverage.lcov
 coverage
-
-.idea
-.vscode
+dist

.husky/pre-commit

@@ -1,4 +1 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-npm run lint
+npx lint-staged --concurrent false

.nvmrc

@@ -1 +1 @@
-v16.14.2
+v20.17.0

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Boris K
+Copyright (c) 2017 Boris K - github.com/bokub
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,15 +4,13 @@
 [![Version][version-src]][version-href]
 [![Codecov][codecov-src]][codecov-href]
 [![Downloads][downloads-src]][downloads-href]
-[![XO code style][xo-src]][xo-href]
+[![code style: prettier][code-style-src]][code-style-href]
 [![Mentioned in Awesome Node.js][awesome-src]][awesome-href]
 
-
 > Beautiful color gradients in terminal output
 
 [![gradient-string](http://bit.ly/gradient-string-preview)](http://bit.ly/gradient-string-large)
 
-
 ## Install
 
 ```
@@ -22,37 +20,34 @@ $ npm i gradient-string
 ## Usage
 
 ```javascript
-const gradient = require('gradient-string');
+import gradient from 'gradient-string';
 
-console.log(gradient('cyan', 'pink')('Hello world!'));
+console.log(gradient(['cyan', 'pink'])('Hello world!'));
 ```
 
 ### Initialize a gradient
 
 ```javascript
-// Using varargs
-let coolGradient = gradient('red', 'green', 'blue');
-
-// Using array
-let coolGradient = gradient(['#FF0000', '#00FF00', '#0000FF']);
+// Provide an array of colors
+const coolGradient = gradient(['#FF0000', '#00FF00', '#0000FF']);
 ```
 
 The colors are parsed with TinyColor, [multiple formats are accepted](https://github.com/bgrins/TinyColor/blob/master/README.md#accepted-string-input).
 
 ```javascript
-let coolGradient = gradient([
-  tinycolor('#FFBB65'),       // tinycolor object
-  {r: 0, g: 255, b: 0},       // RGB object
-  {h: 240, s: 1, v: 1, a: 1}, // HSVa object
-  'rgb(120, 120, 0)',         // RGB CSS string
-  'gold'                      // named color
+const coolGradient = gradient([
+  tinycolor('#FFBB65'), // tinycolor object
+  { r: 0, g: 255, b: 0 }, // RGB object
+  { h: 240, s: 1, v: 1, a: 1 }, // HSVa object
+  'rgb(120, 120, 0)', // RGB CSS string
+  'gold', // named color
 ]);
 ```
 
 ### Use a gradient
 
 ```javascript
-let coolString = coolGradient('This is a fancy string!');
+const coolString = coolGradient('This is a fancy string!');
 console.log(coolString);
 ```
 
@@ -61,10 +56,13 @@ console.log(coolString);
 ### Usage
 
 ```javascript
-const gradient = require('gradient-string');
+import { rainbow, pastel } from 'gradient-string';
 
-// Use the rainbow gradient
-console.log(gradient.rainbow('I love gradient-strings!'))
+// Use the pastel built-in gradient
+console.log(pastel('I love gradient-string!'));
+
+// Use the rainbow built-in gradient
+console.log(rainbow('It is so pretty! 🌈'));
 ```
 
 ### Available built-in gradients
@@ -78,29 +76,28 @@ In some cases, you may want to apply the same horizontal gradient on each line o
 You can use the `multiline()` method of a gradient to ensure that the colors are vertically aligned.
 
 ```javascript
-const gradient = require('gradient-string');
+import gradient, { rainbow } from 'gradient-string';
 
 // Use the same gradient on every line
-let duck = gradient('orange', 'yellow').multiline([
-    "  __",
-    "<(o )___",
-    " ( ._> /",
-    "  `---'",
-].join('\n'));
+const duck = gradient(['green', 'yellow']).multiline(`
+  __
+<(o )___
+ ( ._> /
+   ---
+`);
 console.log(duck);
 
 // Works with aliases
-gradient.atlas.multiline('Multi line\nstring');
+rainbow.multiline('Multi line\nstring');
 
-// Works with advanced options
-gradient('cyan', 'pink').multiline('Multi line\nstring', {interpolation: 'hsv'});
+// Works with advanced options (read below)
+gradient(['cyan', 'pink'], { interpolation: 'hsv' }).multiline('Multi line\nstring');
 ```
 
-
 ## Advanced gradients
 
 There are also more advanced options for gradient customization, such as custom color stops, or choice of color interpolation
-  
+
 ### Custom color stops
 
 By default, the gradient color stops are distributed equidistantly.
@@ -109,87 +106,104 @@ You can specify the position of each color stop (between `0` and `1`), using the
 
 ```javascript
 let coolGradient = gradient([
-  {color: '#d8e0de', pos: 0},
-  {color: '#255B53', pos: 0.8},
-  {color: '#000000', pos: 1}
+  { color: '#d8e0de', pos: 0 },
+  { color: '#255B53', pos: 0.8 },
+  { color: '#000000', pos: 1 },
 ]);
 ```
 
 ### Color interpolation
 
-When using a gradient, you can actually add a second parameter to choose how the colors will be generated.
+When creating a gradient, you can provide a second parameter to choose how the colors will be generated.
 
-Here is the full gradient API:
+Here is the full `gradient` API:
 
-#### myGradient(text, [options])
+#### `gradient([colors], options?)(text)`
+
+##### colors
+
+Type: `Array<Color>`<br>
+Colors of the gradient. [Multiple formats are accepted](https://github.com/bgrins/TinyColor/blob/master/README.md#accepted-string-input).
 
 ##### text
-Type: `string`<br>
+
+Type: `String`<br>
 String you want to color.
 
 ##### options
-Type: `Object`<br>
+
+Type: `Object` _(optional)_<br>
 
 ###### interpolation
+
 Type: `string`<br>
 The gradient can be generated using RGB or HSV interpolation. HSV usually produces brighter colors.
 `interpolation` can be set to `rgb` for RGB interpolation, or`hsv` for HSV interpolation.<br>
-Defaults to `rgb`. Case insentitive
+Defaults to `rgb`. Case-insensitive
 
 ###### hsvSpin
+
 Type: `string`<br>
 Used only in the case of HSV interpolation.<br>
 Because hue can be considered as a circle, there are two ways to go from a color to another color.<br>
 `hsvSpin` can be either `short` or `long`, depending on if you want to take the shortest or the longest way between two colors.<br>
-Defaults to `short`. Case insensitive
+Defaults to `short`. Case-insensitive
 
 #### Example
+
 ##### Code
+
 ```javascript
-const redToGreen = gradient('red', 'green');
 const str = '■'.repeat(48);
 
 // Standard RGB gradient
-console.log(redToGreen(str)); 
+const standardRGBGradient = gradient(['red', 'green']);
 
 // Short HSV gradient: red -> yellow -> green
-console.log(redToGreen(str, {interpolation: 'hsv'}));
+const shortHSVGradient = gradient(['red', 'green'], { interpolation: 'hsv' });
 
 // Long HSV gradient: red -> magenta -> blue -> cyan -> green
-console.log(redToGreen(str, {interpolation: 'hsv', hsvSpin: 'long'}));
-```
-##### Result
-![Example result](http://i.imgur.com/plQAN2Q.png)
-
-## Typescript
-
-Typescript definitions of gradient-string are available on [DefinitelyTyped](https://www.npmjs.com/package/@types/gradient-string)
+const longHSVGradient = gradient(['red', 'green'], { interpolation: 'hsv', hsvSpin: 'long' });
 
-```sh
-npm i @types/gradient-string
+console.log(standardRGBGradient(str));
+console.log(shortHSVGradient(str));
+console.log(longHSVGradient(str));
 ```
 
+##### Result
+
+![Example result](http://i.imgur.com/plQAN2Q.png)
 
 ## Dependencies
 
-- [tinygradient](https://github.com/mistic100/tinygradient) - Generate gradients
 - [chalk](https://github.com/chalk/chalk) - Output colored text to terminal
+- [tinygradient](https://github.com/mistic100/tinygradient) - Generate gradients
+
+## Who uses gradient-string?
 
+- [Shopify](https://shopify.com/) in [Shopify CLI](https://www.npmjs.com/package/@shopify/cli-kit?activeTab=dependencies#:~:text=gradient&text=string)
+- [Microsoft](https://microsoft.com) in [@lage-run/reporters](https://www.npmjs.com/package/@lage-run/reporters?activeTab=dependencies#:~:text=gradient&text=string)
+- [Tencent](https://www.tencent.com/) in [Cloudbase Framework](https://www.npmjs.com/package/@cloudbase/framework-core#:~:text=gradient&text=string)
+- [Fireship](https://fireship.io/) in [this YouTube video](https://youtu.be/_oHByo8tiEY?si=3AKfAfOMXI0d9Ay6&t=76), where he shows how he built [javascript-millionaire](https://github.com/fireship-io/javascript-millionaire)
+- [Turoborepo](https://turbo.build/) in [@turbo/workspaces](https://www.npmjs.com/package/@turbo/workspaces?activeTab=dependencies#:~:text=gradient&text=string) and [@turbo/codemod](https://www.npmjs.com/package/@turbo/codemod?activeTab=dependencies#:~:text=gradient&text=string)
+- [Magic UI](https://magicui.design/) in [Magic UI CLI](https://www.npmjs.com/package/magicui-cli?activeTab=dependencies)
+- [Myself](https://github.com/bokub) in [chalk-animation](https://github.com/bokub/chalk-animation), the animated version of gradient-string
+- [Sindre Sorhus](https://github.com/sindresorhus) in [ink-gradient](https://www.npmjs.com/package/ink-gradient?activeTab=dependencies#:~:text=gradient&text=string), the [Ink](https://github.com/vadimdemedes/ink) version of gradient-string
+- [And ![](https://flat.badgen.net/github/dependents-repo/bokub/gradient-string?color=000&label=) more...](https://github.com/bokub/gradient-string/network/dependents), who downloaded gradient-string [![Downloads](https://flat.badgen.net/npm/dt/gradient-string?color=000&label=) times!][downloads-href]
 
 ## License
 
 MIT © [Boris K](https://github.com/bokub)
 
 [build-src]: https://flat.badgen.net/github/checks/bokub/gradient-string?label=tests
-[version-src]: https://runkit.io/bokub/npm-version/branches/master/gradient-string?style=flat
-[codecov-src]: https://flat.badgen.net/codecov/c/github/bokub/gradient-string
-[downloads-src]: https://flat.badgen.net/npm/dm/gradient-string?color=FF9800
-[xo-src]: https://flat.badgen.net/badge/code%20style/XO/5ed9c7
+[version-src]: https://gradgen.bokub.workers.dev/npm/v/gradient-string?gradient=b65cff,11cbfa&style=flat&label=version
+[codecov-src]: https://img.shields.io/codecov/c/github/bokub/rgb-light-card?style=flat-square
+[downloads-src]: https://flat.badgen.net/npm/dw/gradient-string?color=FF9800
+[code-style-src]: https://flat.badgen.net/badge/code%20style/prettier/ff69b4
 [awesome-src]: https://awesome.re/mentioned-badge-flat.svg
-
 [build-href]: https://github.com/bokub/gradient-string/actions/workflows/run.yml
 [version-href]: https://www.npmjs.com/package/gradient-string
 [codecov-href]: https://codecov.io/gh/bokub/gradient-string
 [downloads-href]: https://www.npmjs.com/package/gradient-string
-[xo-href]: https://github.com/sindresorhus/xo
+[code-style-href]: https://github.com/bokub/prettier-config
 [awesome-href]: https://github.com/sindresorhus/awesome-nodejs

examples/built-in.js

@@ -1,38 +1,29 @@
 #!/usr/bin/env node
 
-// Run with npm run built-in
-const gradient = require('..');
+// Run with "npm run built-in"
+import gradient from '../dist/index.js';
 
-const {log} = console;
+const { log } = console;
 const str = '■'.repeat(48);
 
 log('');
 
 for (const t of [
-	'cristal',
-	'teen',
-	'mind',
-	'morning',
-	'vice',
-	'passion',
-	'fruit',
-	'instagram',
-	'atlas',
-	'retro',
-	'summer',
-	'pastel',
-	'rainbow'
+  'cristal',
+  'teen',
+  'mind',
+  'morning',
+  'vice',
+  'passion',
+  'fruit',
+  'instagram',
+  'atlas',
+  'retro',
+  'summer',
+  'pastel',
+  'rainbow',
 ]) {
-	log(pad(t), gradient[t](str));
+  log('  ' + t.padEnd(11, ' '), gradient[t](str));
 }
 
 log('');
-
-function pad(s) {
-	let i = -1;
-	const l = 11 - s.length;
-	while (++i < l) {
-		s += ' ';
-	}
-	return '  ' + s;
-}