Skip to content

Commit 91b0d7a

Browse files
jdaltonjdalton
committed
docs(misc): add @example blocks to remaining module exports (#173)
* docs(env): add @example blocks to env module exports * docs(misc): add @example blocks to remaining module exports
1 parent a6a06ec commit 91b0d7a

20 files changed

Lines changed: 454 additions & 0 deletions

‎src/argv/flags.ts‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,13 @@ export type FlagInput = FlagValues | string[] | readonly string[] | undefined
3939
* Get the appropriate log level based on flags.
4040
* Returns 'silent', 'error', 'warn', 'info', 'verbose', or 'debug'.
4141
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
42+
*
43+
* @example
44+
* ```typescript
45+
* getLogLevel() // 'info' (default)
46+
* getLogLevel({ quiet: true }) // 'silent'
47+
* getLogLevel(['--debug']) // 'debug'
48+
* ```
4249
*/
4350
export function getLogLevel(input?: FlagInput): string {
4451
if (isQuiet(input)) {
@@ -56,6 +63,12 @@ export function getLogLevel(input?: FlagInput): string {
5663
/**
5764
* Check if all flag is set.
5865
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
66+
*
67+
* @example
68+
* ```typescript
69+
* isAll({ all: true }) // true
70+
* isAll(['--all']) // true
71+
* ```
5972
*/
6073
export function isAll(input?: FlagInput): boolean {
6174
if (!input) {
@@ -70,6 +83,12 @@ export function isAll(input?: FlagInput): boolean {
7083
/**
7184
* Check if changed files mode is enabled.
7285
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
86+
*
87+
* @example
88+
* ```typescript
89+
* isChanged({ changed: true }) // true
90+
* isChanged(['--changed']) // true
91+
* ```
7392
*/
7493
export function isChanged(input?: FlagInput): boolean {
7594
if (!input) {
@@ -85,6 +104,12 @@ export function isChanged(input?: FlagInput): boolean {
85104
* Check if coverage mode is enabled.
86105
* Checks both 'coverage' and 'cover' flags.
87106
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
107+
*
108+
* @example
109+
* ```typescript
110+
* isCoverage({ coverage: true }) // true
111+
* isCoverage(['--cover']) // true
112+
* ```
88113
*/
89114
export function isCoverage(input?: FlagInput): boolean {
90115
if (!input) {
@@ -99,6 +124,12 @@ export function isCoverage(input?: FlagInput): boolean {
99124
/**
100125
* Check if debug mode is enabled.
101126
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
127+
*
128+
* @example
129+
* ```typescript
130+
* isDebug({ debug: true }) // true
131+
* isDebug(['--debug']) // true
132+
* ```
102133
*/
103134
export function isDebug(input?: FlagInput): boolean {
104135
if (!input) {
@@ -113,6 +144,12 @@ export function isDebug(input?: FlagInput): boolean {
113144
/**
114145
* Check if dry-run mode is enabled.
115146
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
147+
*
148+
* @example
149+
* ```typescript
150+
* isDryRun({ 'dry-run': true }) // true
151+
* isDryRun(['--dry-run']) // true
152+
* ```
116153
*/
117154
export function isDryRun(input?: FlagInput): boolean {
118155
if (!input) {
@@ -127,6 +164,12 @@ export function isDryRun(input?: FlagInput): boolean {
127164
/**
128165
* Check if fix/autofix mode is enabled.
129166
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
167+
*
168+
* @example
169+
* ```typescript
170+
* isFix({ fix: true }) // true
171+
* isFix(['--fix']) // true
172+
* ```
130173
*/
131174
export function isFix(input?: FlagInput): boolean {
132175
if (!input) {
@@ -141,6 +184,12 @@ export function isFix(input?: FlagInput): boolean {
141184
/**
142185
* Check if force mode is enabled.
143186
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
187+
*
188+
* @example
189+
* ```typescript
190+
* isForce({ force: true }) // true
191+
* isForce(['--force']) // true
192+
* ```
144193
*/
145194
export function isForce(input?: FlagInput): boolean {
146195
if (!input) {
@@ -155,6 +204,12 @@ export function isForce(input?: FlagInput): boolean {
155204
/**
156205
* Check if help flag is set.
157206
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
207+
*
208+
* @example
209+
* ```typescript
210+
* isHelp({ help: true }) // true
211+
* isHelp(['-h']) // true
212+
* ```
158213
*/
159214
export function isHelp(input?: FlagInput): boolean {
160215
if (!input) {
@@ -169,6 +224,12 @@ export function isHelp(input?: FlagInput): boolean {
169224
/**
170225
* Check if JSON output is requested.
171226
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
227+
*
228+
* @example
229+
* ```typescript
230+
* isJson({ json: true }) // true
231+
* isJson(['--json']) // true
232+
* ```
172233
*/
173234
export function isJson(input?: FlagInput): boolean {
174235
if (!input) {
@@ -183,6 +244,12 @@ export function isJson(input?: FlagInput): boolean {
183244
/**
184245
* Check if quiet/silent mode is enabled.
185246
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
247+
*
248+
* @example
249+
* ```typescript
250+
* isQuiet({ quiet: true }) // true
251+
* isQuiet(['--silent']) // true
252+
* ```
186253
*/
187254
export function isQuiet(input?: FlagInput): boolean {
188255
if (!input) {
@@ -197,6 +264,12 @@ export function isQuiet(input?: FlagInput): boolean {
197264
/**
198265
* Check if staged files mode is enabled.
199266
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
267+
*
268+
* @example
269+
* ```typescript
270+
* isStaged({ staged: true }) // true
271+
* isStaged(['--staged']) // true
272+
* ```
200273
*/
201274
export function isStaged(input?: FlagInput): boolean {
202275
if (!input) {
@@ -211,6 +284,12 @@ export function isStaged(input?: FlagInput): boolean {
211284
/**
212285
* Check if update mode is enabled (for snapshots, dependencies, etc).
213286
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
287+
*
288+
* @example
289+
* ```typescript
290+
* isUpdate({ update: true }) // true
291+
* isUpdate(['-u']) // true
292+
* ```
214293
*/
215294
export function isUpdate(input?: FlagInput): boolean {
216295
if (!input) {
@@ -225,6 +304,12 @@ export function isUpdate(input?: FlagInput): boolean {
225304
/**
226305
* Check if verbose mode is enabled.
227306
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
307+
*
308+
* @example
309+
* ```typescript
310+
* isVerbose({ verbose: true }) // true
311+
* isVerbose(['--verbose']) // true
312+
* ```
228313
*/
229314
export function isVerbose(input?: FlagInput): boolean {
230315
if (!input) {
@@ -239,6 +324,12 @@ export function isVerbose(input?: FlagInput): boolean {
239324
/**
240325
* Check if watch mode is enabled.
241326
* Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
327+
*
328+
* @example
329+
* ```typescript
330+
* isWatch({ watch: true }) // true
331+
* isWatch(['-w']) // true
332+
* ```
242333
*/
243334
export function isWatch(input?: FlagInput): boolean {
244335
if (!input) {

‎src/argv/parse.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,17 @@ export interface ParsedArgs<T = Record<string, unknown>> {
9797
/**
9898
* Parse command-line arguments with a Node.js parseArgs-compatible API.
9999
* Uses yargs-parser internally for robust argument parsing.
100+
*
101+
* @example
102+
* ```typescript
103+
* const { values, positionals } = parseArgs({
104+
* args: ['--force', '--quiet', 'file.ts'],
105+
* options: {
106+
* force: { type: 'boolean' },
107+
* quiet: { type: 'boolean', short: 'q' },
108+
* },
109+
* })
110+
* ```
100111
*/
101112
export function parseArgs<T = Record<string, unknown>>(
102113
config: ParseArgsConfig = {},
@@ -206,6 +217,14 @@ export function parseArgs<T = Record<string, unknown>>(
206217
/**
207218
* Parse command-line arguments with Socket defaults.
208219
* Provides sensible defaults for Socket CLI applications.
220+
*
221+
* @example
222+
* ```typescript
223+
* const { values, positionals } = parseArgsWithDefaults({
224+
* args: ['--force', 'file.ts'],
225+
* options: { force: { type: 'boolean' } },
226+
* })
227+
* ```
209228
*/
210229
export function parseArgsWithDefaults<T = Record<string, unknown>>(
211230
config: ParseArgsConfig = {},
@@ -239,6 +258,12 @@ export const commonParseArgsConfig: ParseArgsConfig = {
239258
/**
240259
* Extract positional arguments from process.argv.
241260
* Useful for commands that accept file paths or other positional parameters.
261+
*
262+
* @example
263+
* ```typescript
264+
* // process.argv = ["node", "script.js", "src", "lib", "--verbose"]
265+
* getPositionalArgs() // ["src", "lib"]
266+
* ```
242267
*/
243268
export function getPositionalArgs(startIndex = 2): string[] {
244269
const args = process.argv.slice(startIndex)
@@ -260,6 +285,12 @@ export function getPositionalArgs(startIndex = 2): string[] {
260285

261286
/**
262287
* Check if a specific flag is present in argv.
288+
*
289+
* @example
290+
* ```typescript
291+
* hasFlag('verbose') // true if --verbose is in process.argv
292+
* hasFlag('force', ['--force', '--quiet']) // true
293+
* ```
263294
*/
264295
export function hasFlag(flag: string, argv = process.argv): boolean {
265296
return argv.includes(`--${flag}`)

‎src/cacache.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ export interface RemoveOptions {
4141

4242
/**
4343
* Get the cacache module for cache operations.
44+
*
45+
* @example
46+
* ```typescript
47+
* const cacache = getCacache()
48+
* const entries = await cacache.ls(cacheDir)
49+
* ```
4450
*/
4551
export function getCacache() {
4652
// cacache is imported at the top
@@ -167,6 +173,12 @@ export async function clear(
167173
* Get data from the Socket shared cache by key.
168174
* @throws {Error} When cache entry is not found.
169175
* @throws {TypeError} If key contains wildcards (*)
176+
*
177+
* @example
178+
* ```typescript
179+
* const entry = await get('socket-sdk:scans:abc123')
180+
* console.log(entry.data.toString('utf8'))
181+
* ```
170182
*/
171183
export async function get(
172184
key: string,
@@ -186,6 +198,11 @@ export async function get(
186198
* Put data into the Socket shared cache with a key.
187199
*
188200
* @throws {TypeError} If key contains wildcards (*)
201+
*
202+
* @example
203+
* ```typescript
204+
* await put('socket-sdk:scans:abc123', Buffer.from('result data'))
205+
* ```
189206
*/
190207
export async function put(
191208
key: string,
@@ -206,6 +223,11 @@ export async function put(
206223
* Remove an entry from the Socket shared cache by key.
207224
*
208225
* @throws {TypeError} If key contains wildcards (*)
226+
*
227+
* @example
228+
* ```typescript
229+
* await remove('socket-sdk:scans:abc123')
230+
* ```
209231
*/
210232
export async function remove(key: string): Promise<unknown> {
211233
if (key.includes('*')) {
@@ -220,6 +242,14 @@ export async function remove(key: string): Promise<unknown> {
220242

221243
/**
222244
* Get data from the Socket shared cache by key without throwing.
245+
*
246+
* @example
247+
* ```typescript
248+
* const entry = await safeGet('socket-sdk:scans:abc123')
249+
* if (entry) {
250+
* console.log(entry.data.toString('utf8'))
251+
* }
252+
* ```
223253
*/
224254
export async function safeGet(
225255
key: string,
@@ -234,6 +264,14 @@ export async function safeGet(
234264

235265
/**
236266
* Execute a callback with a temporary directory for cache operations.
267+
*
268+
* @example
269+
* ```typescript
270+
* const result = await withTmp(async (tmpDir) => {
271+
* // Use tmpDir for temporary cache work
272+
* return 'done'
273+
* })
274+
* ```
237275
*/
238276
export async function withTmp<T>(
239277
callback: (tmpDirPath: string) => Promise<T>,

‎src/cover/formatters.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ const COVERAGE_EMOJI_THRESHOLDS = [
2323

2424
/**
2525
* Get emoji for coverage percentage.
26+
*
27+
* @example
28+
* ```typescript
29+
* getCoverageEmoji(95) // ' \u{1F3AF}'
30+
* getCoverageEmoji(50) // ' \u{1F528}'
31+
* ```
2632
*/
2733
export function getCoverageEmoji(percent: number): string {
2834
const entry = COVERAGE_EMOJI_THRESHOLDS.find(
@@ -33,6 +39,18 @@ export function getCoverageEmoji(percent: number): string {
3339

3440
/**
3541
* Format coverage data for console output.
42+
*
43+
* @example
44+
* ```typescript
45+
* const output = formatCoverage({
46+
* code: {
47+
* statements: { percent: '85.00' },
48+
* branches: { percent: '80.00' },
49+
* functions: { percent: '90.00' },
50+
* lines: { percent: '88.00' },
51+
* },
52+
* })
53+
* ```
3654
*/
3755
export function formatCoverage(options: FormatCoverageOptions): string {
3856
const opts = {

‎src/debug.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -360,6 +360,12 @@ function debugCacheNs(
360360

361361
/**
362362
* Cache debug function with caller info.
363+
*
364+
* @example
365+
* ```typescript
366+
* debugCache('hit', 'socket-sdk:scans:abc123')
367+
* debugCache('miss', 'socket-sdk:scans:xyz', { ttl: 60000 })
368+
* ```
363369
*/
364370
/*@__NO_SIDE_EFFECTS__*/
365371
export function debugCache(

‎src/effects/pulse-frames.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ export type SocketFramesOptions = {
2828
* Returns a spinner definition compatible with cli-spinners format.
2929
*
3030
* @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
31+
*
32+
* @example
33+
* ```typescript
34+
* const { frames, interval } = generateSocketSpinnerFrames()
35+
* console.log(frames.length, interval) // 18 50
36+
* ```
3137
*/
3238
export function generateSocketSpinnerFrames(
3339
options?: SocketFramesOptions | undefined,

0 commit comments

Comments
 (0)