From e1784ce2330fce9653605683b847136eade2bb91 Mon Sep 17 00:00:00 2001 From: Juyeong Maing Date: Wed, 30 Jul 2025 17:35:16 +0900 Subject: [PATCH] feat: add jsdoctest integration and examples --- package.json | 7 +++++-- packages/parser/package.json | 7 +++++-- packages/parser/src/index.ts | 10 ++++++++++ packages/type/package.json | 7 +++++-- packages/type/src/index.ts | 5 +++++ src/NoopAnsi.ts | 5 +++++ src/index.ts | 10 ++++++++++ src/node.ts | 7 +++++++ src/proxy-node.ts | 7 +++++++ src/proxy.ts | 7 +++++++ 10 files changed, 66 insertions(+), 6 deletions(-) diff --git a/package.json b/package.json index dae4c84..5d3f9b7 100644 --- a/package.json +++ b/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" } } diff --git a/packages/parser/package.json b/packages/parser/package.json index e5b60a5..0d8977b 100644 --- a/packages/parser/package.json +++ b/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" } } diff --git a/packages/parser/src/index.ts b/packages/parser/src/index.ts index a0c770a..66e8ff0 100644 --- a/packages/parser/src/index.ts +++ b/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[], diff --git a/packages/type/package.json b/packages/type/package.json index 889fad5..4ced5ca 100644 --- a/packages/type/package.json +++ b/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" } } diff --git a/packages/type/src/index.ts b/packages/type/src/index.ts index 67b1a8c..51b66ff 100644 --- a/packages/type/src/index.ts +++ b/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, diff --git a/src/NoopAnsi.ts b/src/NoopAnsi.ts index 4f59480..344cb50 100644 --- a/src/NoopAnsi.ts +++ b/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 { diff --git a/src/index.ts b/src/index.ts index d0c01a7..ecef507 100644 --- a/src/index.ts +++ b/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 = { @@ -274,6 +279,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): AnsiTemplateTag { const options = (oprions ?? {}) as Partial; diff --git a/src/node.ts b/src/node.ts index a674a9f..72c98ba 100644 --- a/src/node.ts +++ b/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; diff --git a/src/proxy-node.ts b/src/proxy-node.ts index 62458fe..cff4679 100644 --- a/src/proxy-node.ts +++ b/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 diff --git a/src/proxy.ts b/src/proxy.ts index 0202d1d..d382e50 100644 --- a/src/proxy.ts +++ b/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, {});