feat: initial commit ✨

README.md

@@ -1,6 +1,10 @@
 <h1 align="center">text-table-fast</h1>
 
-<p align="center">Generates borderless text table strings suitable for printing to stdout. Fast. 🏁</p>
+<p align="center">
+	Generates borderless text table strings suitable for printing to stdout.
+	Fast.
+	🏁
+</p>
 
 <p align="center">
 	<!-- prettier-ignore-start -->
@@ -22,11 +26,132 @@ npm i text-table-fast
 ```
 
 ```ts
-import { greet } from "text-table-fast";
+import { textTable } from "text-table-fast";
+
+console.log(
+	textTable([
+		["main", "0123456789abcdef"],
+		["staging", "fedcba9876543210"],
+	]),
+);
+```
+
+```plaintext
+main     0123456789abcdef
+staging  fedcba9876543210
+```
+
+`textTable` takes in an array of arrays containing strings, numbers, or other printable values.
+
+## Options
+
+`text-table-fast`'s `textTable` can take in an optional second parameter as an object with options
+
+> 🔄 These options are equivalent to [`text-table`](https://www.npmjs.com/package/text-table)'s options, but with expanded names.
+
+### `align`
+
+- Default: `[]`
+- Type: `("center" | "left" | "right")[]`
+
+The alignment for columns, in order.
+These each default to `"left"`.
+
+```ts
+import { textTable } from "text-table-fast";
+
+console.log(
+	textTable(
+		[
+			["abc", "abcd", "ab"],
+			[1234, 12, 1234],
+		],
+		{
+			alignment: ["left", "center", "right"],
+		},
+	),
+);
+```
 
-greet("Hello, world! 💖");
+```plaintext
+abc  abcd  abc
+1234  12  1234
 ```
 
+### `horizontalSeparator`
+
+- Default: `"  "`
+- Type: `string`
+
+Characters to put between each column.
+
+```ts
+import { textTable } from "text-table-fast";
+
+console.log(
+	textTable(
+		[
+			["abc", "abcd", "ab"],
+			[1234, 12, 1234],
+		],
+		{
+			horizontalSeparator: " | ",
+		},
+	),
+);
+```
+
+```plaintext
+abc  | abcd |  abc
+1234 |  12  | 1234
+```
+
+### `stringLength`
+
+- Default: `(value) => String(value).length`
+- Type: `(value: string) => number`
+
+How to compute the length of strings, such as for stripping ANSI characters.
+
+```ts
+import color from "cli-color";
+import { textTable } from "text-table-fast";
+
+console.log(
+	textTable(
+		[
+			[color.red("abc"), color.blue("def")],
+			[12, 34],
+		],
+		{
+			stringLength: (value) => color.strip(value).length,
+		},
+	),
+);
+```
+
+```plaintext
+\x1B[31mabc\x1B[39m  \x1B[34mdef\x1B[39m
+12  34
+```
+
+## Comparison to [`text-table`](https://www.npmjs.com/package/text-table)
+
+`text-table-fast` has three advantages over `text-table`:
+
+- It is fast in almost all scenarios, and significantly faster on larger tables.
+- It is under active maintenance, whereas `text-table` hasn't been updated in over a decade.
+- It's written in TypeScript and ships with its own `.d.ts` types, whereas `text-table` requires `@types/text-table` for typings.
+
+### Performance Comparison
+
+`text-table-fast` contains two meaningful optimizations over `text-table`:
+
+- `text-table` includes usage of of [an quadratically expensive `/\s+$/`](https://ota-meshi.github.io/eslint-plugin-regexp/playground/#eJyrVkrOT0lVslLSj4kp1lbRV6oFADQgBS4=); `text-table-fast` uses [`String.prototype.trimEnd`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimEnd) instead.
+- `text-table` executes a regular expression match on each row cell for its `'.'` (decimal) alignment option; `text-table-fast` will skip that match if and when decimal alignment support is added.
+
+> ESLint issue to be filed soon with a performance comparison. ⚡️
+
 ## Contributors
 
 <!-- spellchecker: disable -->
@@ -47,6 +172,9 @@ greet("Hello, world! 💖");
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 <!-- spellchecker: enable -->
 
-<!-- You can remove this notice if you don't want it 🙂 no worries! -->
+## Acknowledgements
+
+This package is a near-drop-in replacement for venerable [`text-table`](https://www.npmjs.com/package/text-table), which has served a plethora of projects -including ESLint- well for over a decade.
+Many thanks to substack for creating the original `text-table` package! 💖
 
 > 💙 This package was templated with [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app).

cspell.json

@@ -8,5 +8,16 @@
 		"node_modules",
 		"pnpm-lock.yaml"
 	],
-	"words": ["borderless", "knip", "packagejson", "tseslint", "tsup"]
+	"words": [
+		"borderless",
+		"hsep",
+		"knip",
+		"mabc",
+		"mdef",
+		"packagejson",
+		"substack",
+		"tseslint",
+		"tsup",
+		"vitest"
+	]
 }

eslint.config.js

@@ -5,7 +5,7 @@ import jsonc from "eslint-plugin-jsonc";
 import markdown from "eslint-plugin-markdown";
 import n from "eslint-plugin-n";
 import packageJson from "eslint-plugin-package-json/configs/recommended";
-import perfectionistNatural from "eslint-plugin-perfectionist/configs/recommended-natural";
+import perfectionist from "eslint-plugin-perfectionist";
 import * as regexp from "eslint-plugin-regexp";
 import vitest from "eslint-plugin-vitest";
 import yml from "eslint-plugin-yml";
@@ -35,7 +35,9 @@ export default tseslint.config(
 	jsdoc.configs["flat/recommended-typescript-error"],
 	n.configs["flat/recommended"],
 	packageJson,
-	perfectionistNatural,
+	// After updating for https://github.com/JoshuaKGoldberg/create-typescript-app/issues/1588 ...
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access
+	perfectionist.configs["recommended-natural"],
 	regexp.configs["flat/recommended"],
 	...tseslint.config({
 		extends: [
@@ -74,7 +76,7 @@ export default tseslint.config(
 				"error",
 				{
 					order: "asc",
-					"partition-by-comment": true,
+					partitionByComment: true,
 					type: "natural",
 				},
 			],
@@ -97,6 +99,7 @@ export default tseslint.config(
 		files: ["**/*.md/*.ts"],
 		rules: {
 			"n/no-missing-import": ["error", { allowModules: ["text-table-fast"] }],
+			"n/no-unpublished-import": ["error", { allowModules: ["cli-color"] }],
 		},
 	},
 	{

knip.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://unpkg.com/knip@latest/schema.json",
-	"entry": ["src/index.ts!"],
+	"entry": ["src/index.ts!", "src/**/*.test.ts!"],
 	"ignoreExportsUsedInFile": { "interface": true, "type": true },
 	"project": ["src/**/*.ts!"]
 }

package.json

@@ -37,8 +37,11 @@
 		"@eslint-community/eslint-plugin-eslint-comments": "^4.3.0",
 		"@eslint/js": "^9.7.0",
 		"@release-it/conventional-changelog": "^8.0.1",
+		"@types/cli-color": "^2.0.6",
 		"@types/eslint-plugin-markdown": "^2.0.2",
+		"@types/eslint__js": "^8.42.3",
 		"@vitest/coverage-v8": "^2.0.4",
+		"cli-color": "^2.0.4",
 		"console-fail-test": "^0.4.4",
 		"cspell": "^8.11.0",
 		"eslint": "^9.7.0",