Skip to content

Commit 32ca3dc

Browse files
jdaltonjdalton
committed
docs(system): add @example blocks to system module exports (#174)
* docs(env): add @example blocks to env module exports * docs(misc): add @example blocks to remaining module exports * docs(system): add @example blocks to system module exports
1 parent 7b2d5d9 commit 32ca3dc

6 files changed

Lines changed: 216 additions & 0 deletions

File tree

‎src/agent.ts‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,12 @@ const yarnInstallLikeCommands = new Set([
9595
*
9696
* SECURITY: Uses array-based arguments to prevent command injection. All elements
9797
* in the args array are properly escaped by Node.js when passed to spawn().
98+
*
99+
* @example
100+
* ```typescript
101+
* await execNpm(['install', '--save', 'lodash'])
102+
* await execNpm(['run', 'build'], { cwd: '/tmp/project' })
103+
* ```
98104
*/
99105
export function execNpm(args: string[], options?: SpawnOptions | undefined) {
100106
const useDebug = isDebug()
@@ -157,6 +163,12 @@ export interface PnpmOptions extends SpawnOptions {
157163
*
158164
* SECURITY: Uses array-based arguments to prevent command injection. All elements
159165
* in the args array are properly escaped by Node.js when passed to execBin().
166+
*
167+
* @example
168+
* ```typescript
169+
* await execPnpm(['install'])
170+
* await execPnpm(['add', 'lodash'], { allowLockfileUpdate: true })
171+
* ```
160172
*/
161173
export function execPnpm(args: string[], options?: PnpmOptions | undefined) {
162174
const { allowLockfileUpdate, ...extBinOpts } = {
@@ -224,6 +236,12 @@ export function execPnpm(args: string[], options?: PnpmOptions | undefined) {
224236
*
225237
* SECURITY: Uses array-based arguments to prevent command injection. All elements
226238
* in the args array are properly escaped by Node.js when passed to execBin().
239+
*
240+
* @example
241+
* ```typescript
242+
* await execYarn(['install'])
243+
* await execYarn(['add', 'lodash'], { cwd: '/tmp/project' })
244+
* ```
227245
*/
228246
export function execYarn(
229247
args: string[],
@@ -271,6 +289,13 @@ export function execYarn(
271289

272290
/**
273291
* Check if a command argument is an npm audit flag.
292+
*
293+
* @example
294+
* ```typescript
295+
* isNpmAuditFlag('--no-audit') // true
296+
* isNpmAuditFlag('--audit') // true
297+
* isNpmAuditFlag('--save') // false
298+
* ```
274299
*/
275300
/*@__NO_SIDE_EFFECTS__*/
276301
export function isNpmAuditFlag(cmdArg: string): boolean {
@@ -279,6 +304,13 @@ export function isNpmAuditFlag(cmdArg: string): boolean {
279304

280305
/**
281306
* Check if a command argument is an npm fund flag.
307+
*
308+
* @example
309+
* ```typescript
310+
* isNpmFundFlag('--no-fund') // true
311+
* isNpmFundFlag('--fund') // true
312+
* isNpmFundFlag('--save') // false
313+
* ```
282314
*/
283315
/*@__NO_SIDE_EFFECTS__*/
284316
export function isNpmFundFlag(cmdArg: string): boolean {
@@ -287,6 +319,14 @@ export function isNpmFundFlag(cmdArg: string): boolean {
287319

288320
/**
289321
* Check if a command argument is an npm loglevel flag.
322+
*
323+
* @example
324+
* ```typescript
325+
* isNpmLoglevelFlag('--loglevel') // true
326+
* isNpmLoglevelFlag('--silent') // true
327+
* isNpmLoglevelFlag('-s') // true
328+
* isNpmLoglevelFlag('--save') // false
329+
* ```
290330
*/
291331
/*@__NO_SIDE_EFFECTS__*/
292332
export function isNpmLoglevelFlag(cmdArg: string): boolean {
@@ -304,6 +344,13 @@ export function isNpmLoglevelFlag(cmdArg: string): boolean {
304344

305345
/**
306346
* Check if a command argument is an npm node-options flag.
347+
*
348+
* @example
349+
* ```typescript
350+
* isNpmNodeOptionsFlag('--node-options') // true
351+
* isNpmNodeOptionsFlag('--node-options=--max-old-space-size=4096') // true
352+
* isNpmNodeOptionsFlag('--save') // false
353+
* ```
307354
*/
308355
/*@__NO_SIDE_EFFECTS__*/
309356
export function isNpmNodeOptionsFlag(cmdArg: string): boolean {
@@ -313,6 +360,13 @@ export function isNpmNodeOptionsFlag(cmdArg: string): boolean {
313360

314361
/**
315362
* Check if a command argument is an npm progress flag.
363+
*
364+
* @example
365+
* ```typescript
366+
* isNpmProgressFlag('--no-progress') // true
367+
* isNpmProgressFlag('--progress') // true
368+
* isNpmProgressFlag('--save') // false
369+
* ```
316370
*/
317371
/*@__NO_SIDE_EFFECTS__*/
318372
export function isNpmProgressFlag(cmdArg: string): boolean {
@@ -321,6 +375,13 @@ export function isNpmProgressFlag(cmdArg: string): boolean {
321375

322376
/**
323377
* Check if a command argument is a pnpm ignore-scripts flag.
378+
*
379+
* @example
380+
* ```typescript
381+
* isPnpmIgnoreScriptsFlag('--ignore-scripts') // true
382+
* isPnpmIgnoreScriptsFlag('--no-ignore-scripts') // true
383+
* isPnpmIgnoreScriptsFlag('--save') // false
384+
* ```
324385
*/
325386
/*@__NO_SIDE_EFFECTS__*/
326387
export function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean {
@@ -329,6 +390,13 @@ export function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean {
329390

330391
/**
331392
* Check if a command argument is a pnpm frozen-lockfile flag.
393+
*
394+
* @example
395+
* ```typescript
396+
* isPnpmFrozenLockfileFlag('--frozen-lockfile') // true
397+
* isPnpmFrozenLockfileFlag('--no-frozen-lockfile') // true
398+
* isPnpmFrozenLockfileFlag('--save') // false
399+
* ```
332400
*/
333401
/*@__NO_SIDE_EFFECTS__*/
334402
export function isPnpmFrozenLockfileFlag(cmdArg: string): boolean {
@@ -337,6 +405,13 @@ export function isPnpmFrozenLockfileFlag(cmdArg: string): boolean {
337405

338406
/**
339407
* Check if a command argument is a pnpm install command.
408+
*
409+
* @example
410+
* ```typescript
411+
* isPnpmInstallCommand('install') // true
412+
* isPnpmInstallCommand('i') // true
413+
* isPnpmInstallCommand('run') // false
414+
* ```
340415
*/
341416
/*@__NO_SIDE_EFFECTS__*/
342417
export function isPnpmInstallCommand(cmdArg: string): boolean {
@@ -351,6 +426,12 @@ export const isPnpmLoglevelFlag = isNpmLoglevelFlag
351426
/**
352427
* Execute a package.json script using the appropriate package manager.
353428
* Automatically detects pnpm, yarn, or npm based on lockfiles.
429+
*
430+
* @example
431+
* ```typescript
432+
* await execScript('build')
433+
* await execScript('test', ['--coverage'], { cwd: '/tmp/project' })
434+
* ```
354435
*/
355436
export interface ExecScriptOptions extends SpawnOptions {
356437
prepost?: boolean | undefined

‎src/archives.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,13 @@ function validatePathWithinBase(
114114
*
115115
* @param filePath - Path to archive file
116116
* @returns Archive format or null if unknown
117+
*
118+
* @example
119+
* ```typescript
120+
* detectArchiveFormat('package.tar.gz') // 'tar.gz'
121+
* detectArchiveFormat('archive.zip') // 'zip'
122+
* detectArchiveFormat('data.csv') // null
123+
* ```
117124
*/
118125
export function detectArchiveFormat(filePath: string): ArchiveFormat | null {
119126
const lower = filePath.toLowerCase()
@@ -138,6 +145,12 @@ export function detectArchiveFormat(filePath: string): ArchiveFormat | null {
138145
* @param archivePath - Path to tar file
139146
* @param outputDir - Directory to extract to
140147
* @param options - Extraction options
148+
*
149+
* @example
150+
* ```typescript
151+
* await extractTar('/tmp/archive.tar', '/tmp/output')
152+
* await extractTar('/tmp/archive.tar', '/tmp/output', { strip: 1 })
153+
* ```
141154
*/
142155
export async function extractTar(
143156
archivePath: string,
@@ -264,6 +277,12 @@ export async function extractTar(
264277
* @param archivePath - Path to tar.gz or tgz file
265278
* @param outputDir - Directory to extract to
266279
* @param options - Extraction options
280+
*
281+
* @example
282+
* ```typescript
283+
* await extractTarGz('/tmp/archive.tar.gz', '/tmp/output')
284+
* await extractTarGz('/tmp/archive.tgz', '/tmp/output', { strip: 1 })
285+
* ```
267286
*/
268287
export async function extractTarGz(
269288
archivePath: string,
@@ -390,6 +409,12 @@ export async function extractTarGz(
390409
* @param archivePath - Path to zip file
391410
* @param outputDir - Directory to extract to
392411
* @param options - Extraction options
412+
*
413+
* @example
414+
* ```typescript
415+
* await extractZip('/tmp/archive.zip', '/tmp/output')
416+
* await extractZip('/tmp/archive.zip', '/tmp/output', { strip: 1 })
417+
* ```
393418
*/
394419
export async function extractZip(
395420
archivePath: string,
@@ -530,6 +555,12 @@ export async function extractZip(
530555
* @param outputDir - Directory to extract to
531556
* @param options - Extraction options
532557
* @throws Error if archive format is not supported
558+
*
559+
* @example
560+
* ```typescript
561+
* await extractArchive('/tmp/package.tar.gz', '/tmp/output')
562+
* await extractArchive('/tmp/release.zip', '/tmp/output', { strip: 1 })
563+
* ```
533564
*/
534565
export async function extractArchive(
535566
archivePath: string,

‎src/bin.ts‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,12 @@ export interface WhichOptions {
7777

7878
/**
7979
* Execute a binary with the given arguments.
80+
*
81+
* @example
82+
* ```typescript
83+
* await execBin('pnpm', ['install'])
84+
* await execBin('/usr/local/bin/node', ['script.js'], { cwd: '/tmp' })
85+
* ```
8086
*/
8187
/*@__NO_SIDE_EFFECTS__*/
8288
export async function execBin(
@@ -140,6 +146,12 @@ export async function execBin(
140146

141147
/**
142148
* Find the real executable for a binary, bypassing shadow bins.
149+
*
150+
* @example
151+
* ```typescript
152+
* const npmPath = findRealBin('npm', ['/usr/local/bin/npm'])
153+
* const gitPath = findRealBin('git')
154+
* ```
143155
*/
144156
export function findRealBin(
145157
binName: string,
@@ -184,6 +196,12 @@ export function findRealBin(
184196

185197
/**
186198
* Find the real npm executable, bypassing any aliases and shadow bins.
199+
*
200+
* @example
201+
* ```typescript
202+
* const npmPath = findRealNpm()
203+
* // e.g. '/usr/local/bin/npm'
204+
* ```
187205
*/
188206
export function findRealNpm(): string {
189207
const fs = getFs()
@@ -219,6 +237,12 @@ export function findRealNpm(): string {
219237

220238
/**
221239
* Find the real pnpm executable, bypassing any aliases and shadow bins.
240+
*
241+
* @example
242+
* ```typescript
243+
* const pnpmPath = findRealPnpm()
244+
* // e.g. '/usr/local/bin/pnpm'
245+
* ```
222246
*/
223247
export function findRealPnpm(): string {
224248
const path = getPath()
@@ -250,6 +274,12 @@ export function findRealPnpm(): string {
250274

251275
/**
252276
* Find the real yarn executable, bypassing any aliases and shadow bins.
277+
*
278+
* @example
279+
* ```typescript
280+
* const yarnPath = findRealYarn()
281+
* // e.g. '/usr/local/bin/yarn'
282+
* ```
253283
*/
254284
export function findRealYarn(): string {
255285
const path = getPath()
@@ -270,6 +300,12 @@ export function findRealYarn(): string {
270300

271301
/**
272302
* Check if a directory path contains any shadow bin patterns.
303+
*
304+
* @example
305+
* ```typescript
306+
* isShadowBinPath('/tmp/project/node_modules/.bin') // true
307+
* isShadowBinPath('/usr/local/bin') // false
308+
* ```
273309
*/
274310
export function isShadowBinPath(dirPath: string | undefined): boolean {
275311
if (!dirPath) {
@@ -284,6 +320,12 @@ export function isShadowBinPath(dirPath: string | undefined): boolean {
284320
/**
285321
* Resolve a binary path to the real underlying script file.
286322
* Handles Windows .cmd wrappers and Unix shell scripts, resolving them to the actual .js files they execute.
323+
*
324+
* @example
325+
* ```typescript
326+
* const realPath = resolveRealBinSync('/usr/local/bin/npm')
327+
* // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
328+
* ```
287329
*/
288330
export function resolveRealBinSync(binPath: string): string {
289331
const fs = getFs()
@@ -723,6 +765,12 @@ export async function which(
723765
* Find a binary in the system PATH and resolve to the real underlying script asynchronously.
724766
* Resolves wrapper scripts (.cmd, .ps1, shell scripts) to the actual .js files they execute.
725767
* @throws {Error} If the binary is not found and nothrow is false.
768+
*
769+
* @example
770+
* ```typescript
771+
* const npmPath = await whichReal('npm')
772+
* // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
773+
* ```
726774
*/
727775
export async function whichReal(
728776
binName: string,
@@ -792,6 +840,12 @@ export async function whichReal(
792840
* Find a binary in the system PATH and resolve to the real underlying script synchronously.
793841
* Resolves wrapper scripts (.cmd, .ps1, shell scripts) to the actual .js files they execute.
794842
* @throws {Error} If the binary is not found and nothrow is false.
843+
*
844+
* @example
845+
* ```typescript
846+
* const npmPath = whichRealSync('npm')
847+
* // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
848+
* ```
795849
*/
796850
export function whichRealSync(
797851
binName: string,

‎src/fs.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -609,6 +609,12 @@ export function findUpSync(
609609
* Called automatically by the paths/rewire module when paths are overridden in tests.
610610
*
611611
* @internal Used for test rewiring
612+
*
613+
* @example
614+
* ```typescript
615+
* invalidatePathCache()
616+
* // Cached allowed directories are now cleared
617+
* ```
612618
*/
613619
export function invalidatePathCache(): void {
614620
_cachedAllowedDirs = undefined
@@ -768,6 +774,13 @@ export function normalizeEncoding(
768774
*
769775
* @param enc - Encoding to normalize
770776
* @returns Normalized encoding string, defaults to 'utf8' for unknown encodings
777+
*
778+
* @example
779+
* ```typescript
780+
* normalizeEncodingSlow('ucs2') // 'utf16le'
781+
* normalizeEncodingSlow('LATIN1') // 'latin1'
782+
* normalizeEncodingSlow('binary') // 'latin1'
783+
* ```
771784
*/
772785
/*@__NO_SIDE_EFFECTS__*/
773786
export function normalizeEncodingSlow(enc: string): BufferEncoding {

‎src/spawn.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,15 @@ export interface SpawnSyncReturns<T> {
280280
/**
281281
* Enhances spawn error with better context.
282282
* Converts generic "command failed" to detailed error with command, exit code, and stderr.
283+
*
284+
* @example
285+
* ```typescript
286+
* try {
287+
* await spawn('git', ['status'])
288+
* } catch (err) {
289+
* throw enhanceSpawnError(err)
290+
* }
291+
* ```
283292
*/
284293
/*@__NO_SIDE_EFFECTS__*/
285294
export function enhanceSpawnError(error: unknown): unknown {

0 commit comments

Comments
 (0)