npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

colorix

v2.0.2

Published

🖌️ Colorize strings with LITERAL ANSI encodings!

Downloads

21

Readme

Colorix

Colorix provides a simple way to define and layer color presets, and helps you recognize and track ANSI escape sequences in your code. Each module uses template literals (and a bit of magic 🪄) to construct a type representation of the color sequences applied to your strings.

import cx from 'colorix'

const goblinInk = cx('bgGreen', 'black', 'bold')
console.log(goblinInk('hello goblin', '!'))

goblin-example

With TypeScript, always know when a string has hidden characters

declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], ['hello goblin', '!']>
// => `\u001B[42;30;1mhello goblin!\u001B[0m`

This is useful with primitive strings as well

declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], [string, ...string[]]>
// => `\u001B[42;30;1m${string}\u001B[0m`

How it works

// create a theme by passing colors to the first function.
declare const cx: <Colors extends Color[]>(
  ...colors: Colors
) => // then pass stringifiable values to the second function to colorize them.
<Strings extends Stringifiable[]>(
  ...strings: Strings
) => // the returned value is an ansified string.
Colorix<Colors, Strings>

Installation

Add colorix to your project using your favorite package manager.

NPM

npm install colorix

PNPM

pnpm add colorix

Yarn

yarn add colorix

How to support terminals without color

safe, colorixSafe, cxs

You can use safe to check if the terminal supports color before applying a preset.

import cx, { safe } from 'colorix'
const errorInk = cx('bold', 'red')

console.log(errorInk('That tasted purple...'))
// "\u001B[mThat tasted purple...\u001B[0m"

console.log(safe(errorInk)('That tasted purple...'))
// "That tasted purple..." | "\u001B[mThat tasted purple...\u001B[0m"

Alternatively, use colorixSafe / cxs for an Ink preset that only applies colors if the terminal supports it.

import { cxs, colorixSafe } from 'colorix'

const safeErrorInk = cxs('bold', 'red') // or colorixSafe('bold', 'red')
console.log(safeErrorInk('That tasted purple...'))

Bonus Features

ColorixError

Fun way to colorize error messages without worrying about the terminal supporting color, or importing colorix / cx / safe into many files.

import { ColorixError } from 'colorix'

const BasicError = new ColorixError(
  'simple message that is always safe to display'
)
const PrettyError = new ColorixError((cx) =>
  cx(
    'white',
    'bgBlue',
    'dim',
    'bold'
  )(
    'Pretty Message',
    cx('reset')(' '),
    cx('underline', 'green')(
      'npmjs.com/package/colorix',
      cx('reset', 'italic')(' '),
      '(this message will always be stripped of color if supportsColor is false)'
    )
  )
)

throw PrettyError

PrettyError

For an "out-of-the-box" solution, use PrettyError. It provides the same naming and fallback message behavior as Colorix without an api for customizing the rest of the error.

import { PrettyError } from 'colorix'

const IOError = PrettyError('IOError', 'An unknown IO error occurred.')

try {
  throw new IOError()
} catch (err) {
  console.log(err)
}

try {
  throw new IOError('Illegal write operation.', 'more info...')
} catch (err) {
  console.log(err)
}

pretty-error-example

colorix-error-example

Exports

default, colorix, cx

| Colorix | Description | | :---------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | default / cx / colorix | Create presets for colorizing Stringifiable values. | | cxs / colorixSafe | Create presets for colorizing when the terminal supports it Stringifiable. | | safe | Call a colorix preset safely safe(cx( ...colors )). | | ColorixError | Create child Error classes with colorized messages. |

Constants

| Name | Description | | :-------------------------------- | :------------------------------------------------------------------- | | CSI | control sequence introducer ("\x1b[") | | SGRT | select graphic rendition terminator ("m") | | FOREGROUND | readonly foreground lookup object | | BACKGROUND | readonly background lookup object | | MODIFIER | readonly modifier lookup object | | COLORS | readonly color lookup object (foreground, background, and modifiers) | | hasBasicColors | boolean indicating if the terminal supports basic colors | | has256Colors | boolean indicating if the terminal supports 256 colors | | has16mColors | boolean indicating if the terminal supports 16 million colors | | supportsColor | boolean indicating if the terminal supports any color |

Types

| Generic | Description | | :---------------------------------------------- | :------------------------------------------------------ | | Colorix | utility for creating literals wrapped in ANSI sequences | | ColorSequence | utility for creating literal ANSI sequences |

| Alias | Description | | :---------------------------------------------- | :---------------------------------------------------------------------------- | | ResetSequence | literal reset sequence that is always appended to the end of a color sequence | | ColorTable | readonly record of color aliases and color codes | | Color | a foreground, background, or modifier color (keyof ColorTable) | | ColorCode | an SGR color code | | Foreground | a foreground color | | Background | a background color | | Modifier | a modifier color |

Color Tables

| Foreground | Code | Foreground Bright | Code | | :---------- | :--: | :---------------- | :--: | | "black" | 30 | "gray" | 90 | | "red" | 31 | "redBright" | 91 | | "green" | 32 | "greenBright" | 92 | | "yellow" | 33 | "yellowBright" | 93 | | "blue" | 34 | "blueBright" | 94 | | "magenta" | 35 | "magentaBright" | 95 | | "cyan" | 36 | "cyanBright" | 96 | | "white" | 37 | "whiteBright" | 97 |

| Background | Code | Background Bright | Code | | :------------ | :--: | :------------------ | :--: | | "bgBlack" | 40 | "bgGray" | 100 | | "bgRed" | 41 | "bgRedBright" | 101 | | "bgGreen" | 42 | "bgGreenBright" | 102 | | "bgYellow" | 43 | "bgYellowBright" | 103 | | "bgBlue" | 44 | "bgBlueBright" | 104 | | "bgMagenta" | 45 | "bgMagentaBright" | 105 | | "bgCyan" | 46 | "bgCyanBright" | 106 | | "bgWhite" | 47 | "bgWhiteBright" | 107 |

| Modifier | Code | | :---------------- | :--: | | "reset" | 0 | | "bold" | 1 | | "dim" | 2 | | "italic" | 3 | | "underline" | 4 | | "inverse" | 7 | | "hidden" | 8 | | "strikethrough" | 9 |