claude.md

.github/workflows/main.yml

@@ -2,6 +2,7 @@ name: CI
 on:
   - push
   - pull_request
+  - workflow_dispatch
 jobs:
   test:
     name: Node.js ${{ matrix.node-version }}

CLAUDE.md

@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+**Testing:**
+- `npm test` - Run all tests (linting, unit tests, coverage, TypeScript definitions)
+- `npx ava test/<specific-test-file>.js` - Run a specific test file
+- `npx xo` - Run linting only
+- `npx tsd` - Run TypeScript definition tests only
+
+**Benchmarking:**
+- `npm run bench` - Run performance benchmarks
+
+## Architecture
+
+Chalk is a zero-dependency terminal string styling library built as a pure ESM module. Key architectural elements:
+
+1. **Core Files:**
+   - `source/index.js` - Main entry point with the chalk factory and chainable API implementation
+   - `source/utilities.js` - Helper functions for string manipulation and color conversion
+   - `source/vendor/` - Vendored dependencies (ansi-styles and supports-color) to avoid external dependencies
+
+2. **Internal Symbols:**
+   - `GENERATOR` - Manages chalk instance creation and configuration
+   - `STYLER` - Handles style application and chaining
+   - `IS_EMPTY` - Tracks empty string optimization
+
+3. **API Design:**
+   - Uses ES6 Proxy for dynamic property access (e.g., `chalk.red.bold`)
+   - Chainable API with lazy property definition for performance
+   - Supports nested styles with proper ANSI escape code management
+   - Template literal support via tagged template syntax
+
+4. **Color Level Detection:**
+   - Automatically detects terminal color support (levels 0-3)
+   - Separate instances for stdout and stderr with independent color levels
+   - Can be overridden via `new Chalk({level: n})` or `FORCE_COLOR` environment variable
+
+## Important Notes
+
+- This is a pure ESM package (v5+) - use `import` not `require`
+- Maintain zero production dependencies - vendor any required modules
+- All style properties are dynamically generated via Proxy - there's no hardcoded list
+- Performance is critical - run benchmarks before/after changes to core functionality
+- The codebase uses symbols for private properties to prevent collisions
+- Template literal processing has special handling for newlines and empty strings

benchmark.js

@@ -1,57 +1,64 @@
-/* globals suite, bench */
+import { Bench } from "tinybench";
-import chalk from './index.js';
+import chalk from "./source/index.js";
 
-suite('chalk', () => {
+const bench = new Bench({ time: 150 });
-	const chalkRed = chalk.red;
-	const chalkBgRed = chalk.bgRed;
-	const chalkBlueBgRed = chalk.blue.bgRed;
-	const chalkBlueBgRedBold = chalk.blue.bgRed.bold;
 
-	const blueStyledString = 'the fox jumps' + chalk.blue('over the lazy dog') + '!';
+const chalkRed = chalk.red;
+const chalkBgRed = chalk.bgRed;
+const chalkBlueBgRed = chalk.blue.bgRed;
+const chalkBlueBgRedBold = chalk.blue.bgRed.bold;
 
-	bench('1 style', () => {
+const blueStyledString =
-		chalk.red('the fox jumps over the lazy dog');
+	"the fox jumps" + chalk.blue("over the lazy dog") + "!";
-	});
 
-	bench('2 styles', () => {
+bench
-		chalk.blue.bgRed('the fox jumps over the lazy dog');
+	.add("1 style", () => {
-	});
+		chalk.red("the fox jumps over the lazy dog");
-
+	})
-	bench('3 styles', () => {
+	.add("2 styles", () => {
-		chalk.blue.bgRed.bold('the fox jumps over the lazy dog');
+		chalk.blue.bgRed("the fox jumps over the lazy dog");
-	});
+	})
-
+	.add("3 styles", () => {
-	bench('cached: 1 style', () => {
+		chalk.blue.bgRed.bold("the fox jumps over the lazy dog");
-		chalkRed('the fox jumps over the lazy dog');
+	})
-	});
+	.add("cached: 1 style", () => {
-
+		chalkRed("the fox jumps over the lazy dog");
-	bench('cached: 2 styles', () => {
+	})
-		chalkBlueBgRed('the fox jumps over the lazy dog');
+	.add("cached: 2 styles", () => {
-	});
+		chalkBlueBgRed("the fox jumps over the lazy dog");
-
+	})
-	bench('cached: 3 styles', () => {
+	.add("cached: 3 styles", () => {
-		chalkBlueBgRedBold('the fox jumps over the lazy dog');
+		chalkBlueBgRedBold("the fox jumps over the lazy dog");
-	});
+	})
-
+	.add("cached: 1 style with newline", () => {
-	bench('cached: 1 style with newline', () => {
+		chalkRed("the fox jumps\nover the lazy dog");
-		chalkRed('the fox jumps\nover the lazy dog');
+	})
-	});
+	.add("cached: 1 style nested intersecting", () => {
-
-	bench('cached: 1 style nested intersecting', () => {
 		chalkRed(blueStyledString);
-	});
+	})
-
+	.add("cached: 1 style nested non-intersecting", () => {
-	bench('cached: 1 style nested non-intersecting', () => {
 		chalkBgRed(blueStyledString);
-	});
+	})
-
+	.add("cached: 1 style template literal", () => {
-	bench('cached: 1 style template literal', () => {
 		// eslint-disable-next-line no-unused-expressions
 		chalkRed`the fox jumps over the lazy dog`;
-	});
+	})
-
+	.add("cached: nested styles template literal", () => {
-	bench('cached: nested styles template literal', () => {
 		// eslint-disable-next-line no-unused-expressions
 		chalkRed`the fox {bold jumps} over the {underline lazy} dog`;
 	});
-});
+
+await bench.run();
+
+// Custom table output without samples, latency med, or throughput med
+const customTable = bench.tasks.map((task) => ({
+	"Task name": task.name,
+	// 'Latency avg (ns)': task.result.latency.mean.toFixed(2) + ' ± ' + task.result.latency.rme.toFixed(2) + '%',
+	"Throughput avg (ops/s)":
+		task.result.throughput.mean.toFixed(0) +
+		" ± " +
+		task.result.throughput.rme.toFixed(2) +
+		"%",
+}));
+
+console.table(customTable);

package.json

@@ -21,7 +21,7 @@
 		"node": "^12.17.0 || ^14.13 || >=16.0.0"
 	},
 	"scripts": {
-		"test": "xo && c8 ava && tsd",
+		"test": "c8 ava && tsd",
 		"bench": "matcha benchmark.js"
 	},
 	"files": [
@@ -57,7 +57,7 @@
 		"color-convert": "^2.0.1",
 		"execa": "^6.0.0",
 		"log-update": "^5.0.0",
-		"matcha": "^0.7.0",
+		"tinybench": "^4.0.1",
 		"tsd": "^0.19.0",
 		"xo": "^0.57.0",
 		"yoctodelay": "^2.0.0"