openinf / openinf-util-text

Cross-platform terminal-friendly text utilities

@openinf/util-text

Essential cross-platform terminal-friendly text utilities

The high-level goal of @openinf/util-text is to serve as a Node.js package containing essential cross-platform text utilities that degrade gracefully when used in terminals lacking feature support. We are constantly working to improve this repository, so please feel free to contribute if you notice any omissions or errors.

Thanks!

Supported Node.js Environments

• v4：Argon (Ar)
• v6：Boron (B)
• v8：Carbon (C)
• v10：Dubnium (Db)
• v12：Erbium (Er)
• v14：Fermium (Fm)
• v16：Gallium (Ga)
• v18：Hydrogen (H)

---

Table of Contents

• Installation
• Usage
• API
• Contributing
• License

---

Installation

@openinf/util-text runs on supported versions of Node.js and is available via npm, pnpm, or yarn.

Using the npm CLI

^{See the official documentation for this command for more information.}

npm i @openinf/util-text

Using the pnpm CLI

^{See the official documentation for this command for more information.}

pnpm add @openinf/util-text

Using the Yarn 1 CLI (Classic)

^{See the official documentation for this command for more information.}

yarn add @openinf/util-text

Usage

To get started using the text utils provided by @openinf/util-text, all that needs to be done is either import/require (depending on the module format) the default export of the module or destructure the individual named helper functions exported.

import { blueify, ellipsify } from '@openinf/util-text';

console.log(blueify(ellipsify('Deserializing database tables')));

API

The “supplied string” should be supplied by app developer (not arbitrarily) because anything beyond that (e.g., in publicly-facing apps) may need be pre-processed. The next release may perform preprocessing to follow Web Platform Design Principles.

Advanced Tips

Notice that these APIs were not built for (and are potentially not good for) language models:

• Speak with a diverse mix of prospective users of your application within your target population about its intended purpose to gain a wider perspective on potential risks and have your app be adapted to those circumstances.
  

  ⓘ This tip was paraphrased from Google AI safety guidance; however, further reading on the topic of AI safety guidance may be available elsewhere.

blueify(text) ⇒ string

Returns the supplied string as blue colored if ANSI escapes are supported.

curlyQuote(text) ⇒ string

Returns the supplied string as curly quoted if Unicode is supported.

ellipsify(text) ⇒ string

Returns the supplied string as ellipsified if Unicode is supported.

italicize(text) ⇒ string

Returns the supplied string as italicized if ANSI escapes are supported.

mdCodeSpans2html(text) ⇒ string

Processes the supplied string by transforming any Markdown backtick code spans (beginning and ending with a single backtick) into HTML code elements.

redden(text) ⇒ string

Returns the supplied string as red colored if ANSI escapes are supported.

underline(text) ⇒ string

Returns the supplied string as underlined if ANSI escapes are supported.

yellow(text) ⇒ string

Returns the supplied string as yellow colored if ANSI escapes are supported.

UnicodeEscapes : enum

Kind: global enum
Properties

Name	Type	Default
infoSymbol	string	"ⓘ"
midlineEllipsis	string	"⋯"
ellipsis	string	"…"
errorSymbol	string	"ⓧ"
leftDoubleQuotes	string	"“"
rightDoubleQuotes	string	"”"
warningSymbol	string	"⚠"

blueify(text) ⇒ string

Returns the supplied string as blue colored if ANSI escapes are supported.

Kind: global function

Param	Type
text	string

curlyQuote(text) ⇒ string

Returns the supplied string as curly quoted if Unicode is supported.

Kind: global function

Param	Type
text	string

ellipsify(text) ⇒ string

Returns the supplied string as ellipsified if Unicode is supported.

Kind: global function

Param	Type
text	string

italicize(text) ⇒ string

Returns the supplied string as italicized if ANSI escapes are supported.

Kind: global function

Param	Type
text	string

mdCodeSpans2html(text) ⇒ string

This API will be deprecated in the next release in favor of one that follows Web Platform Design Principles.

Processes the supplied string by transforming any Markdown backtick code spans (beginning and ending with a single backtick) into HTML code elements.

Kind: global function

Param	Type
text	string

redden(text) ⇒ string

Returns the supplied string as red colored if ANSI escapes are supported.

Kind: global function

Param	Type
text	string

underline(text) ⇒ string

Returns the supplied string as underlined if ANSI escapes are supported.

Kind: global function

Param	Type
text	string

yellow(text) ⇒ string

Returns the supplied string as yellow colored if ANSI escapes are supported.

Kind: global function

Param	Type
text	string

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.

License

This project is licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

The SPDX license identifier for this project is MIT OR Apache-2.0.

---

Show Your Support

If you like the project (or want to bookmark it) —
— give it a star ⭐️ — it will greatly encourage us.

openinf-util-text's Issues

[discussion] migrating to pnpm for the monorepo setup

We currently have a couple of deps that we need to either replace or bundle w/ the deployed package (thanks to socket for flagging them as trivial):

• #57
• #58

We also have a problem of the npm lockfile version changing from 2 to 3 in npm@9

Does this mean that we should switch to either pnpm for their lockfile at this point, or maybe Yarn?

I don't really mind either way, but the problematic lockfile bump is going to be something to watch out for:

• #142
• #143
• #144

The Snyk check was failing those PRs as the lockfile being inconsistent w/ the deps(-dev) that are listed in our package.json — we can't have this as being flagged by Snyk (unacceptable).

/cc @shellscape

[bug] `keywords` field missing from package.json published to registry

This affects the package's discoverability and should probably be enforced as required by our tooling.

Refs: https://docs.npmjs.com/cli/v8/configuring-npm/package-json#keywords

(JS-0339) Found non-null assertions

Description

Using non-null assertions cancels the benefits of the strict null-checking mode.

Occurrences

There is 1 occurrence of this issue in the repository.

See all occurrences on DeepSource → deepsource.io/gh/openinf/util-text/issue/JS-0339/occurrences/

[bug] dependency `cli-color` has licensing issues

According to Socket, cli-color has issues related to licensing. We are currently using the MIT license for the packages we publish on npm and intend to continue doing so. This is kind of a hard requirement since a lot of projects have a strict requirement of having an MIT license. It is also important that the dependencies of our dependencies are MIT licensed as well.

We may be able to swap this one out for colorette, which is MIT-licensed (silver quality) and maintained by my good friend @jorgebucaran. It has no dependencies.

Refs: DerekNonGeneric/loader339#11 (comment)

[feature request] DeepScan to use ESLint over built-in rules

DeepScan has been configured to check for ESLint config instead of using its default rules. This means that it will be ready for us once ESLint is good to go here.

You've analyzed the project with ESLint, but the ESLint analysis failed by the ESLint error.

After checking the details of error and configuring ESLint correctly, please reanalyze this project.

ESLint couldn't find a configuration file. To set up a configuration file for this project, please run:

eslint --init

[feature request] support older terminals w/ fallbacks for Unicode symbols

After stumbling upon the figures package, I realized that each figure symbol provided by this package should ideally have a fallback for terminals that do not support Unicode. The author of figures has a different idea on what these symbols should be, so we would likely not be able to depend on that package for our uses. It also seems to have more than we would need, but the current lack of fallbacks should probably be addressed by us somehow.

[bug] dependency `supports-ansi` has issues related to triviality (and more)

According to Socket, supports-ansi has several issues; the most notable of which is that it is considered a trivial package. It also does not support Cygwin, which is unacceptable. There do not appear to be any good alternatives, but the reason why we perform this check in the first place is to determine whether to use color, so we may be able to use supports-color in the near-term.

Depending on whether we swap out cli-color for colorette and colorette were to perform this check itself, we may be able to remove this dependency entirely. There are, however, additional uses for determining whether ANSI is supported other than coloring (e.g., bold, underline, italic), which is something to consider.

Additionally, we should detect whether we are running in a browser and convert ANSI-escaped text streams to HTML for document and devconsole output (as seen in ansi-to-html), but that should only be anticipated once isomorphic support is added.

Hacktoberfest checklist: prepare project for contributions by following best practices

• Add the “hacktoberfest” topic to your repository to opt-in to Hacktoberfest and indicate you’re looking for contributions.

• Apply the “hacktoberfest” label to issues you want contributors to help within your GitHub or GitLab project.

• Add a CONTRIBUTING.md file with contribution guidelines to your repository.

• Choose issues that have a well-defined scope and are self-contained.

• Adopt a code of conduct to create a greater sense of inclusion and community for contributors.

• Be ready to review pull/merge requests, accepting those that are valid by merging them, leaving an overall approving review, or by adding the “hacktoberfest-accepted” label.

• Reject any spammy requests you receive by labeling them as “spam”, and any other invalid contributions by closing them or labeling them as “invalid”.

Refs: https://hacktoberfest.com/participation/#maintainers

build: remove build products from repo & migrate to babel for transpilation

It is preferable not to check the compiled typescript into our repo — let's remove that javascript from here. Additionally, we should use babel for this transpilation instead of the typescript compiler. We will, however, continue using tsc for type checking and type definition generation.

[feature request] doc: show a screenshot of the output

The documentation currently shows an example in the usage instructions, but the output of that example is not displayed. It would be helpful to see what that looks like without first trying it out yourself.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): bump pnpm to v9.2.0
• build(deps-dev): bump tap to v19

Detected dependencies

github-actions

.github/workflows/codeql-analysis.yml

• actions/checkout v4
• github/codeql-action v3
• github/codeql-action v3
• github/codeql-action v3

.github/workflows/semgrep.yml

• actions/checkout v4
• ubuntu 22.04

npm

package.json

• @types/node 20.x.x
• typescript 5.4.5
• pnpm 9.1.2

packages/colorette/package.json

• c8 *
• twist *

packages/has-unicode/package.json

• require-inject ^1.3.0
• tap ^2.3.1

packages/is-mingw/package.json

packages/supports-ansi/package.json

nvm

.nvmrc

• node 20

---

• Check this box to trigger a request for Renovate to run again on this repository

filling in the scaffolded packages

as we are in the process of satisfying the Socket requirement of not having very small package dependencies, this next step requires filling in the scaffolded packages in the packages/* dir of this repo

it's rather simple and i hope to not over-complicate, which means perhaps simplifying our dependencies too.. we will be taking a look at this tonight.

[feature request] dashes (Unicode alternatives, etc.)

[bug] npm run script for testing missed from published package

This package is currently being flagged by Socket with a Severity: Medium issue due to a lack of tests. This is negatively impacting how its quality score is performing over there. To avoid getting flagged for this by Socket, the test property of the scripts object in the package.json file of our next releases need to contain the testing command for it to run. It seems to have been omitted even though we do actually have some tests (coverage is far from complete). The lack of coverage metrics is another story entirely.

It would be a good idea if we could include a check to ensure that our packages are published with this property specifying a shell command to run for testing. It may be worth noting that a non-zero exit code would equate to test failure according to CITGM, npmlog, and elsewhere, which is something to consider when determining the command.

effort: Web Platform Design Principles

This project does not currently follow Web Platform Design Principles, and neither does it follow its naming conventions (e.g., mdCodeSpans2html); hence, certain re-developments, but very minimal deprecation (perhaps a single API namely mdCodeSpans2html).

[feature request] add new “success” symbol

After stumbling upon the log-symbols package, I realized that we should probably also include a symbol for “success”, which seems to be a reasonably common log symbol. This symbol should also have a fallback for Windows CMD, which only supports a limited character set (non-Unicode). This is somewhat related to #59, which would add fallbacks for the Unicode symbols we already offer.

[bug] dependency `has-unicode` has issues related to triviality (and more)

According to Socket, has-unicode has several issues; the most notable of which is that it is considered a trivial package. There do not appear to be any good alternatives.

• is-unicode-supported suffers from the same issue
• @ultirequiem/is-unicode-supported suffers from another issue
• Others?

The check is quite naïve according to the README of the alternative. Perhaps it can be expanded and we can publish our own non-naïve version of this dependency, which does not suffer from these issues. Alternatively, may want to perform this check ourselves to avoid depending on a seemingly trivial package.

[feature request] fully support converting Markdown-formatted strings to HTML

I have a few gripes with the mdCodeSpans2html function we are currently shipping. First, it uses the wrong naming convention for conversion functions (includes the 2 digit) rather than spelling out the word to like all the other standard methods found in the JS language. The other has to do with its very limited ability. Even though the only functionality we have needed so far has been the conversion of Markdown code spans (text enclosed in backticks) to HTML code elements, we should plan to be able to handle several other Markdownisms (e.g., bold, italic, strikethru, underline, etc.).

Interestingly, Jekyll provides the markdownify filter, which converts any Markdown-formatted string into HTML, which would be more suitable for future use cases. I am, however, not so sure about the naming of it since we are really making to conversion into HTML (i.e., HTML-izing or HTML-ifying) the string rather than the opposite (as Jekyll's naming seems to imply). We could have that coded up as a JS function with perhaps a better name and ship that instead. Other than this being a major breaking change, I see no immediate problem with doing this instead. It certainly seems like it would be a more practical function to have available. It may also be possible that since the contents of the text being fed into it are not always known, a more complete conversion of this nature would be necessary to be accurately compiled to HTML.

doc: flaky badge on README

The "view on npm" badge on the README seems to be timing out. I have seen this multiple times for this particular badge and should be corrected. See the screenshot below.

on the npm website:

on github:

[feature request] add new “cyan” color function

The color “cyan” is preferable to “blue” in most cases especially since the default background color for the PowerShell app on Windows Server 2022 Standard (and many other previous version) is a very similar shade of blue making any foreground text color difficult to read as you can see in the following image.

Similar findings elsewhere:

• npm/npmlog#92
• nodejs/node#14243
• nodejs/node#41082

---

I would prefer to call this function cyanify seeing as how the word “cyanize” already exists and seemingly has a completely different meaning.

Refs: https://www.merriam-webster.com/dictionary/cyanize

[feature request] fully support converting btwx straight and curly quotes

Jekyll provides the smartify filter, which converts a text containing straight quotes and apostrophes into their curly counterparts (aka “smart quotes”). We are going to be needing this functionality (and perhaps the inverse operation as well). This likely means that we should be adding curly single quotes to the UnicodeEscapes : enum we are presently shipping.

[feature request] enable importing helper functions in ESM-only environments

ECMAScript module (ES module) loaders like web-context-js, would benefit a great deal by being able to import the helper functions contained in this package, but this cannot currently be done due to not being distributed as a dual CommonJS/ES module package.

[feature request] prevent including unnecessary files in the deployed package

We should consider adding the "files" stanza to the package.json to create an explicit allowlist and prevent deploying any unnecessary files to the npm registry as part of our package. This would be preferable to using a .npmignore file, which we have been doing so far but is expected to quickly become unmanageable as more files are added.

[feature request] make Browser-friendly (and other environment-friendly too)

This package can be made more (or totally) isomorphic and would be of much higher value should it align with the Rome Community's Technical Philosophy on the matter, which we'll be adopting soon.

Build for generic clients. Don’t assume that output will only be consumed by a terminal and using ANSI codes. Use abstractions that could be generalized for viewing in an IDE, browser, or other environments.

— https://rome.tools/#technical