Add jsdoctest and examples

package.json

@@ -11,7 +11,8 @@
   "scripts": {
     "build": "rimraf dist && tsc && cpy npm.md dist/README.md && package-json-minifier",
     "publish": "npm run build && cd dist && npm publish",
-    "test": "cd test && npm start"
+    "test": "cd test && npm start",
+    "doctest": "npm run build && npm --prefix packages/parser run build && npm --prefix packages/type run build && jsdoctest dist/*.js packages/*/dist/*.js"
   },
   "peerDependencies": {
     "@ansi-escape-code/type": "^3.0.0"
@@ -28,6 +29,8 @@
     "package.json-minifier": "^0.0.4",
     "rimraf": "^6.0.1",
     "typedoc": "^0.28.8",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "jsdoctest": "^1.7.1",
+    "mocha": "^10.2.0"
   }
 }

packages/parser/package.json

@@ -12,7 +12,8 @@
   "scripts": {
     "build": "rimraf dist && tsc && cpy npm.md dist/README.md && package-json-minifier",
     "publish": "npm run build && cd dist && npm publish",
-    "test": "cd test && npm start"
+    "test": "cd test && npm start",
+    "doctest": "jsdoctest src/*.ts"
   },
   "dependencies": {
     "@ansi-escape-code/type": "^3.0.0"
@@ -22,6 +23,8 @@
     "package.json-minifier": "^0.0.4",
     "rimraf": "^6.0.1",
     "typedoc": "^0.28.8",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "jsdoctest": "^1.7.1",
+    "mocha": "^10.2.0"
   }
 }

packages/parser/src/index.ts

@@ -30,6 +30,11 @@ export type ParseAnsiStringResult =
 
 /**
  * Parses a string containing ANSI escape sequences.
+ *
+ * @example
+ * const res = parseAnsiString("\x1b[31mred\x1b[39m");
+ * res.ansiString.map(s => s.content).join("");
+ * // => "red"
  */
 export function parseAnsiString(
   input: string,
@@ -127,6 +132,11 @@ export type ParseAnsiStringFlagsResult =
 
 /**
  * Parses an array of numeric SGR codes.
+ *
+ * @example
+ * const res = parseAnsiStringFlags([1, 31]);
+ * res.foregroundColor;
+ * // => [5, 1]
  */
 export function parseAnsiStringFlags(
   input: number[],

packages/type/package.json

@@ -12,13 +12,16 @@
   "scripts": {
     "build": "rimraf dist && tsc && cpy npm.md dist/README.md && package-json-minifier",
     "publish": "npm run build && cd dist && npm publish",
-    "test": "cd test && npm start"
+    "test": "cd test && npm start",
+    "doctest": "jsdoctest src/*.ts"
   },
   "devDependencies": {
     "cpy-cli": "^5.0.0",
     "package.json-minifier": "^0.0.4",
     "rimraf": "^6.0.1",
     "typedoc": "^0.28.8",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "jsdoctest": "^1.7.1",
+    "mocha": "^10.2.0"
   }
 }

packages/type/src/index.ts

@@ -45,6 +45,11 @@ export class AnsiString {
 
   /**
    * Creates a new {@link AnsiString} instance.
+   *
+   * @example
+   * const s = new AnsiString("hi", 0, null, null, null);
+   * s.content;
+   * // => "hi"
    */
   constructor(
     public readonly content: string,

src/NoopAnsi.ts

@@ -2,6 +2,11 @@ import { AnsiOptions, AnsiPart, Ansi as DefaultAnsi } from ".";
 /**
  * Variant of {@link DefaultAnsi} that ignores all styling and simply
  * concatenates the contained parts.
+ *
+ * @example
+ * const a = new NoopAnsi({}, "A", new DefaultAnsi({ foregroundColor: DefaultAnsi.STANDARD_RED }, "B"));
+ * a.toString();
+ * // => "AB"
  */
 
 export class NoopAnsi extends DefaultAnsi {

src/index.ts

@@ -33,6 +33,11 @@ export type AnsiTemplateTag = (
 
 /**
  * Represents a styled string that can contain nested {@link Ansi} parts.
+ *
+ * @example
+ * const a = new Ansi({ foregroundColor: Ansi.STANDARD_RED }, "Hi");
+ * a.toString();
+ * // => "\x1b[31mHi\x1b[39m"
  */
 export class Ansi {
   public static readonly defaultOptions: AnsiOptions = {
@@ -306,6 +311,11 @@ export class Ansi {
 
   /**
    * Returns a template tag preconfigured with the provided options.
+   *
+   * @example
+   * const red = Ansi.tt({ foregroundColor: Ansi.STANDARD_RED });
+   * red`hi`.toString();
+   * // => "\x1b[31mhi\x1b[39m"
    */
   public static tt(oprions: Partial<AnsiOptions>): AnsiTemplateTag {
     const options = (oprions ?? {}) as Partial<AnsiOptions>;

src/node.ts

@@ -1,5 +1,12 @@
 import { Ansi as DefaultAnsi } from ".";
 import { NoopAnsi } from "./NoopAnsi";
 
+/**
+ * TTY-aware Ansi class that falls back to {@link NoopAnsi} when not in TTY.
+ *
+ * @example
+ * typeof Ansi;
+ * // => "function"
+ */
 export const Ansi =
   process.stdout.isTTY && process.stderr.isTTY ? DefaultAnsi : NoopAnsi;

src/proxy-node.ts

@@ -1,6 +1,13 @@
 import { NoopAnsi } from "./NoopAnsi";
 import { ansi as defaultAnsi, internal } from "./proxy";
 
+/**
+ * TTY-aware proxy based factory. Falls back to {@link NoopAnsi} when not in TTY.
+ *
+ * @example
+ * ansi.red`hi`.toString();
+ * // => "\x1b[31mhi\x1b[39m"
+ */
 export const ansi =
   process.stdout.isTTY && process.stderr.isTTY
     ? defaultAnsi

src/proxy.ts

@@ -241,4 +241,11 @@ export function internal(
   });
 }
 
+/**
+ * Proxy based factory for styled strings.
+ *
+ * @example
+ * ansi.red`hi`.toString();
+ * // => "\x1b[31mhi\x1b[39m"
+ */
 export const ansi = internal(Ansi, {});