@socketsecurity/lib 5.15.0 → 5.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +2 -2
  3. package/dist/abort.d.ts +13 -0
  4. package/dist/agent.d.ts +81 -0
  5. package/dist/ansi.d.ts +13 -0
  6. package/dist/archives.d.ts +31 -0
  7. package/dist/argv/flags.d.ts +91 -0
  8. package/dist/argv/parse.d.ts +31 -0
  9. package/dist/bin.d.ts +54 -0
  10. package/dist/cacache.d.ts +38 -0
  11. package/dist/cache-with-ttl.d.ts +7 -0
  12. package/dist/colors.d.ts +12 -0
  13. package/dist/cover/formatters.d.ts +18 -0
  14. package/dist/debug.d.ts +6 -0
  15. package/dist/dlx/binary.d.ts +84 -0
  16. package/dist/dlx/cache.d.ts +6 -0
  17. package/dist/dlx/detect.d.ts +33 -0
  18. package/dist/dlx/dir.d.ts +34 -0
  19. package/dist/dlx/manifest.d.ts +16 -0
  20. package/dist/dlx/package.d.ts +43 -0
  21. package/dist/dlx/packages.d.ts +36 -0
  22. package/dist/dlx/paths.d.ts +20 -0
  23. package/dist/dlx/paths.js +1 -1
  24. package/dist/effects/pulse-frames.d.ts +6 -0
  25. package/dist/effects/text-shimmer.d.ts +9 -0
  26. package/dist/effects/ultra.d.ts +6 -0
  27. package/dist/env/ci.d.ts +14 -0
  28. package/dist/env/debug.d.ts +13 -0
  29. package/dist/env/github.d.ts +80 -0
  30. package/dist/env/helpers.d.ts +45 -0
  31. package/dist/env/home.d.ts +13 -0
  32. package/dist/env/locale.d.ts +30 -0
  33. package/dist/env/node-auth-token.d.ts +13 -0
  34. package/dist/env/node-env.d.ts +13 -0
  35. package/dist/env/npm.d.ts +50 -0
  36. package/dist/env/path.d.ts +13 -0
  37. package/dist/env/pre-commit.d.ts +14 -0
  38. package/dist/env/rewire.d.ts +38 -0
  39. package/dist/env/shell.d.ts +13 -0
  40. package/dist/env/socket-cli-shadow.d.ts +43 -0
  41. package/dist/env/socket-cli.d.ts +116 -0
  42. package/dist/env/socket.d.ts +153 -0
  43. package/dist/env/temp-dir.d.ts +30 -0
  44. package/dist/env/term.d.ts +13 -0
  45. package/dist/env/test.d.ts +32 -0
  46. package/dist/env/windows.d.ts +40 -0
  47. package/dist/env/xdg.d.ts +30 -0
  48. package/dist/env.d.ts +40 -0
  49. package/dist/external/npm-pack.js +202 -291
  50. package/dist/external/tar-fs.js +27 -7
  51. package/dist/fs.d.ts +13 -0
  52. package/dist/functions.d.ts +30 -0
  53. package/dist/globs.d.ts +27 -0
  54. package/dist/http-request.d.ts +16 -0
  55. package/dist/json/format.d.ts +18 -0
  56. package/dist/memoization.d.ts +5 -0
  57. package/dist/packages/edit.d.ts +28 -0
  58. package/dist/packages/exports.d.ts +40 -0
  59. package/dist/packages/licenses.d.ts +59 -0
  60. package/dist/packages/manifest.d.ts +18 -0
  61. package/dist/packages/normalize.d.ts +22 -0
  62. package/dist/packages/operations.d.ts +51 -0
  63. package/dist/packages/provenance.d.ts +11 -0
  64. package/dist/packages/specs.d.ts +30 -0
  65. package/dist/packages/validation.d.ts +18 -0
  66. package/dist/paths/normalize.d.ts +49 -5
  67. package/dist/paths/normalize.js +13 -0
  68. package/dist/paths/rewire.js +12 -3
  69. package/dist/regexps.d.ts +7 -0
  70. package/dist/releases/github.d.ts +63 -0
  71. package/dist/releases/socket-btm.d.ts +31 -0
  72. package/dist/sea.d.ts +15 -0
  73. package/dist/shadow.d.ts +7 -0
  74. package/dist/signal-exit.d.ts +27 -0
  75. package/dist/sorts.d.ts +33 -0
  76. package/dist/spawn.d.ts +9 -0
  77. package/dist/stdio/mask.d.ts +26 -0
  78. package/dist/streams.d.ts +28 -0
  79. package/dist/suppress-warnings.d.ts +7 -0
  80. package/dist/temporary-executor.d.ts +7 -0
  81. package/dist/url.d.ts +59 -0
  82. package/dist/versions.d.ts +119 -0
  83. package/dist/words.d.ts +20 -0
  84. package/package.json +7 -57
package/dist/sorts.d.ts CHANGED
@@ -1,20 +1,47 @@
1
1
  /**
2
2
  * Compare semantic versions.
3
+ *
4
+ * @example
5
+ * ```typescript
6
+ * compareSemver('1.0.0', '2.0.0') // -1
7
+ * compareSemver('2.0.0', '1.0.0') // 1
8
+ * compareSemver('1.0.0', '1.0.0') // 0
9
+ * ```
3
10
  */
4
11
  /*@__NO_SIDE_EFFECTS__*/
5
12
  export declare function compareSemver(a: string, b: string): number;
6
13
  /**
7
14
  * Simple string comparison.
15
+ *
16
+ * @example
17
+ * ```typescript
18
+ * compareStr('a', 'b') // -1
19
+ * compareStr('b', 'a') // 1
20
+ * compareStr('a', 'a') // 0
21
+ * ```
8
22
  */
9
23
  /*@__NO_SIDE_EFFECTS__*/
10
24
  export declare function compareStr(a: string, b: string): number;
11
25
  /**
12
26
  * Compare two strings using locale-aware comparison.
27
+ *
28
+ * @example
29
+ * ```typescript
30
+ * localeCompare('a', 'b') // -1
31
+ * localeCompare('b', 'a') // 1
32
+ * localeCompare('a', 'a') // 0
33
+ * ```
13
34
  */
14
35
  /*@__NO_SIDE_EFFECTS__*/
15
36
  export declare function localeCompare(x: string, y: string): number;
16
37
  /**
17
38
  * Compare two strings using natural sorting (numeric-aware, case-insensitive).
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * naturalCompare('file2', 'file10') // negative (file2 before file10)
43
+ * naturalCompare('img10', 'img2') // positive (img10 after img2)
44
+ * ```
18
45
  */
19
46
  /*@__NO_SIDE_EFFECTS__*/
20
47
  export declare function naturalCompare(x: string, y: string): number;
@@ -22,6 +49,12 @@ export declare function naturalCompare(x: string, y: string): number;
22
49
  type FastSortFunction = ReturnType<typeof import('fast-sort').createNewSortInstance>;
23
50
  /**
24
51
  * Sort an array using natural comparison.
52
+ *
53
+ * @example
54
+ * ```typescript
55
+ * naturalSorter(['file10', 'file2', 'file1']).asc()
56
+ * // ['file1', 'file2', 'file10']
57
+ * ```
25
58
  */
26
59
  /*@__NO_SIDE_EFFECTS__*/
27
60
  export declare function naturalSorter<T>(arrayToSort: T[]): ReturnType<FastSortFunction>;
package/dist/spawn.d.ts CHANGED
@@ -161,6 +161,15 @@ export interface SpawnSyncReturns<T> {
161
161
  /**
162
162
  * Enhances spawn error with better context.
163
163
  * Converts generic "command failed" to detailed error with command, exit code, and stderr.
164
+ *
165
+ * @example
166
+ * ```typescript
167
+ * try {
168
+ * await spawn('git', ['status'])
169
+ * } catch (err) {
170
+ * throw enhanceSpawnError(err)
171
+ * }
172
+ * ```
164
173
  */
165
174
  /*@__NO_SIDE_EFFECTS__*/
166
175
  export declare function enhanceSpawnError(error: unknown): unknown;
@@ -91,6 +91,12 @@ export interface OutputMask {
91
91
  * Create an output mask for controlling command output visibility.
92
92
  * The mask tracks whether output should be shown or hidden (buffered).
93
93
  * When hidden, output is buffered and a spinner is shown instead.
94
+ *
95
+ * @example
96
+ * ```typescript
97
+ * const mask = createOutputMask({ showOutput: false })
98
+ * console.log(mask.verbose) // false
99
+ * ```
94
100
  */
95
101
  export declare function createOutputMask(options?: OutputMaskOptions): OutputMask;
96
102
  /**
@@ -99,6 +105,13 @@ export declare function createOutputMask(options?: OutputMaskOptions): OutputMas
99
105
  * - ctrl+o: Toggle between showing and hiding output.
100
106
  * - ctrl+c: Cancel the running process.
101
107
  * The handler manipulates terminal state using ANSI escape sequences.
108
+ *
109
+ * @example
110
+ * ```typescript
111
+ * const handler = createKeyboardHandler(mask, childProcess, {
112
+ * message: 'Testing...',
113
+ * })
114
+ * ```
102
115
  */
103
116
  type ReadlineKey = {
104
117
  ctrl?: boolean;
@@ -113,6 +126,12 @@ export declare function createKeyboardHandler(mask: OutputMask, child: ChildProc
113
126
  * - Buffers stdout/stderr when not in verbose mode.
114
127
  * - Shows a spinner when output is masked.
115
128
  * - Allows toggling between masked and unmasked output with ctrl+o.
129
+ *
130
+ * @example
131
+ * ```typescript
132
+ * const child = spawn("pnpm", ["test"], { stdio: ["inherit", "pipe", "pipe"] })
133
+ * const exitCode = await attachOutputMask(child, { message: 'Running tests' })
134
+ * ```
116
135
  */
117
136
  export declare function attachOutputMask(child: ChildProcess, options?: OutputMaskOptions): Promise<number>;
118
137
  /**
@@ -120,6 +139,13 @@ export declare function attachOutputMask(child: ChildProcess, options?: OutputMa
120
139
  * Convenience wrapper around spawn + attachOutputMask.
121
140
  * Spawns a child process and attaches the output masking system to it.
122
141
  * stdin is inherited, stdout and stderr are piped for masking control.
142
+ *
143
+ * @example
144
+ * ```typescript
145
+ * const exitCode = await runWithMask('pnpm', ['test'], {
146
+ * message: 'Running tests',
147
+ * })
148
+ * ```
123
149
  */
124
150
  export declare function runWithMask(command: string, args?: string[], options?: OutputMaskOptions & SpawnOptions): Promise<number>;
125
151
  export {};
package/dist/streams.d.ts CHANGED
@@ -1,16 +1,44 @@
1
1
  import type { IterationOptions } from './promises';
2
2
  /**
3
3
  * Execute a function for each item in an iterable in parallel.
4
+ *
5
+ * @example
6
+ * ```typescript
7
+ * const urls = ['https://a.io', 'https://b.io']
8
+ * await parallelEach(urls, async (url) => {
9
+ * await fetch(url)
10
+ * }, { concurrency: 4 })
11
+ * ```
4
12
  */
5
13
  /*@__NO_SIDE_EFFECTS__*/
6
14
  export declare function parallelEach<T>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<unknown>, options?: number | IterationOptions): Promise<void>;
7
15
  /**
8
16
  * Map over an iterable in parallel with concurrency control.
17
+ *
18
+ * @example
19
+ * ```typescript
20
+ * const ids = [1, 2, 3]
21
+ * for await (const result of parallelMap(ids, async (id) => {
22
+ * return await fetchData(id)
23
+ * }, 4)) {
24
+ * console.log(result)
25
+ * }
26
+ * ```
9
27
  */
10
28
  /*@__NO_SIDE_EFFECTS__*/
11
29
  export declare function parallelMap<T, U>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<U>, options?: number | IterationOptions): AsyncIterable<U>;
12
30
  /**
13
31
  * Transform an iterable with a function.
32
+ *
33
+ * @example
34
+ * ```typescript
35
+ * const lines = ['hello', 'world']
36
+ * for await (const upper of transform(lines, async (line) => {
37
+ * return line.toUpperCase()
38
+ * })) {
39
+ * console.log(upper) // 'HELLO', 'WORLD'
40
+ * }
41
+ * ```
14
42
  */
15
43
  /*@__NO_SIDE_EFFECTS__*/
16
44
  export declare function transform<T, U>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<U>, options?: number | IterationOptions): AsyncIterable<U>;
@@ -37,6 +37,13 @@ export declare function setMaxEventTargetListeners(target: EventTarget | AbortSi
37
37
  /**
38
38
  * Restore the original process.emitWarning function.
39
39
  * Call this to re-enable all warnings after suppressing them.
40
+ *
41
+ * @example
42
+ * ```typescript
43
+ * suppressMaxListenersWarning()
44
+ * // ... do work ...
45
+ * restoreWarnings() // Re-enable all warnings
46
+ * ```
40
47
  */
41
48
  export declare function restoreWarnings(): void;
42
49
  /**
@@ -5,5 +5,12 @@
5
5
  * When package managers run commands via exec/npx/dlx, they execute in temporary directories
6
6
  * that are cleaned up after execution. Creating persistent shadows or modifying PATH
7
7
  * in these contexts can break subsequent package manager commands.
8
+ *
9
+ * @example
10
+ * ```typescript
11
+ * if (isRunningInTemporaryExecutor()) {
12
+ * console.log('Running in a temporary executor context')
13
+ * }
14
+ * ```
8
15
  */
9
16
  export declare function isRunningInTemporaryExecutor(cwd?: string): boolean;
package/dist/url.d.ts CHANGED
@@ -1,15 +1,34 @@
1
1
  /**
2
2
  * Check if a value is a valid URL.
3
+ *
4
+ * @example
5
+ * ```typescript
6
+ * isUrl('https://example.com') // true
7
+ * isUrl('not a url') // false
8
+ * isUrl(null) // false
9
+ * ```
3
10
  */
4
11
  /*@__NO_SIDE_EFFECTS__*/
5
12
  export declare function isUrl(value: string | URL | null | undefined): boolean;
6
13
  /**
7
14
  * Parse a value as a URL.
15
+ *
16
+ * @example
17
+ * ```typescript
18
+ * parseUrl('https://example.com') // URL { href: 'https://example.com/' }
19
+ * parseUrl('invalid') // undefined
20
+ * ```
8
21
  */
9
22
  /*@__NO_SIDE_EFFECTS__*/
10
23
  export declare function parseUrl(value: string | URL): URL | undefined;
11
24
  /**
12
25
  * Convert a URL search parameter to an array.
26
+ *
27
+ * @example
28
+ * ```typescript
29
+ * urlSearchParamAsArray('a, b, c') // ['a', 'b', 'c']
30
+ * urlSearchParamAsArray(null) // []
31
+ * ```
13
32
  */
14
33
  /*@__NO_SIDE_EFFECTS__*/
15
34
  export declare function urlSearchParamAsArray(value: string | null | undefined): string[];
@@ -18,11 +37,24 @@ export interface UrlSearchParamAsBooleanOptions {
18
37
  }
19
38
  /**
20
39
  * Convert a URL search parameter to a boolean.
40
+ *
41
+ * @example
42
+ * ```typescript
43
+ * urlSearchParamAsBoolean('true') // true
44
+ * urlSearchParamAsBoolean('0') // false
45
+ * urlSearchParamAsBoolean(null) // false
46
+ * ```
21
47
  */
22
48
  /*@__NO_SIDE_EFFECTS__*/
23
49
  export declare function urlSearchParamAsBoolean(value: string | null | undefined, options?: UrlSearchParamAsBooleanOptions | undefined): boolean;
24
50
  /**
25
51
  * Helper to get array from URLSearchParams.
52
+ *
53
+ * @example
54
+ * ```typescript
55
+ * const params = new URLSearchParams('tags=a,b,c')
56
+ * urlSearchParamsGetArray(params, 'tags') // ['a', 'b', 'c']
57
+ * ```
26
58
  */
27
59
  /*@__NO_SIDE_EFFECTS__*/
28
60
  export declare function urlSearchParamsGetArray(params: URLSearchParams | null | undefined, key: string): string[];
@@ -31,6 +63,13 @@ export interface UrlSearchParamsGetBooleanOptions {
31
63
  }
32
64
  /**
33
65
  * Helper to get boolean from URLSearchParams.
66
+ *
67
+ * @example
68
+ * ```typescript
69
+ * const params = new URLSearchParams('debug=true')
70
+ * urlSearchParamsGetBoolean(params, 'debug') // true
71
+ * urlSearchParamsGetBoolean(params, 'other') // false
72
+ * ```
34
73
  */
35
74
  /*@__NO_SIDE_EFFECTS__*/
36
75
  export declare function urlSearchParamsGetBoolean(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamsGetBooleanOptions | undefined): boolean;
@@ -39,6 +78,12 @@ export interface CreateRelativeUrlOptions {
39
78
  }
40
79
  /**
41
80
  * Create a relative URL for testing.
81
+ *
82
+ * @example
83
+ * ```typescript
84
+ * createRelativeUrl('/api/test') // 'api/test'
85
+ * createRelativeUrl('/api/test', { base: 'https://example.com' }) // 'https://example.com/api/test'
86
+ * ```
42
87
  */
43
88
  /*@__NO_SIDE_EFFECTS__*/
44
89
  export declare function createRelativeUrl(path: string, options?: CreateRelativeUrlOptions | undefined): string;
@@ -47,6 +92,13 @@ export interface UrlSearchParamAsStringOptions {
47
92
  }
48
93
  /**
49
94
  * Get string value from URLSearchParams with a default.
95
+ *
96
+ * @example
97
+ * ```typescript
98
+ * const params = new URLSearchParams('name=socket')
99
+ * urlSearchParamAsString(params, 'name') // 'socket'
100
+ * urlSearchParamAsString(params, 'other') // ''
101
+ * ```
50
102
  */
51
103
  /*@__NO_SIDE_EFFECTS__*/
52
104
  export declare function urlSearchParamAsString(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsStringOptions | undefined): string;
@@ -55,6 +107,13 @@ export interface UrlSearchParamAsNumberOptions {
55
107
  }
56
108
  /**
57
109
  * Get number value from URLSearchParams with a default.
110
+ *
111
+ * @example
112
+ * ```typescript
113
+ * const params = new URLSearchParams('limit=10')
114
+ * urlSearchParamAsNumber(params, 'limit') // 10
115
+ * urlSearchParamAsNumber(params, 'other') // 0
116
+ * ```
58
117
  */
59
118
  /*@__NO_SIDE_EFFECTS__*/
60
119
  export declare function urlSearchParamAsNumber(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsNumberOptions | undefined): number;
@@ -1,66 +1,160 @@
1
1
  /**
2
2
  * Coerce a version string to valid semver format.
3
+ *
4
+ * @example
5
+ * ```typescript
6
+ * coerceVersion('1.2') // '1.2.0'
7
+ * coerceVersion('v3') // '3.0.0'
8
+ * coerceVersion('abc') // undefined
9
+ * ```
3
10
  */
4
11
  export declare function coerceVersion(version: string): string | undefined;
5
12
  /**
6
13
  * Compare two semantic version strings.
7
14
  * @returns -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2, or undefined if invalid.
15
+ *
16
+ * @example
17
+ * ```typescript
18
+ * compareVersions('1.0.0', '2.0.0') // -1
19
+ * compareVersions('1.0.0', '1.0.0') // 0
20
+ * compareVersions('2.0.0', '1.0.0') // 1
21
+ * ```
8
22
  */
9
23
  export declare function compareVersions(v1: string, v2: string): -1 | 0 | 1 | undefined;
10
24
  /**
11
25
  * Get all versions from an array that satisfy a semver range.
26
+ *
27
+ * @example
28
+ * ```typescript
29
+ * filterVersions(['1.0.0', '1.5.0', '2.0.0'], '>=1.0.0 <2.0.0')
30
+ * // ['1.0.0', '1.5.0']
31
+ * ```
12
32
  */
13
33
  export declare function filterVersions(versions: string[], range: string): string[];
14
34
  /**
15
35
  * Get the major version number from a version string.
36
+ *
37
+ * @example
38
+ * ```typescript
39
+ * getMajorVersion('3.2.1') // 3
40
+ * ```
16
41
  */
17
42
  export declare function getMajorVersion(version: string): number | undefined;
18
43
  /**
19
44
  * Get the minor version number from a version string.
45
+ *
46
+ * @example
47
+ * ```typescript
48
+ * getMinorVersion('3.2.1') // 2
49
+ * ```
20
50
  */
21
51
  export declare function getMinorVersion(version: string): number | undefined;
22
52
  /**
23
53
  * Get the patch version number from a version string.
54
+ *
55
+ * @example
56
+ * ```typescript
57
+ * getPatchVersion('3.2.1') // 1
58
+ * ```
24
59
  */
25
60
  export declare function getPatchVersion(version: string): number | undefined;
26
61
  /**
27
62
  * Increment a version by the specified release type.
63
+ *
64
+ * @example
65
+ * ```typescript
66
+ * incrementVersion('1.2.3', 'patch') // '1.2.4'
67
+ * incrementVersion('1.2.3', 'minor') // '1.3.0'
68
+ * incrementVersion('1.2.3', 'major') // '2.0.0'
69
+ * ```
28
70
  */
29
71
  export declare function incrementVersion(version: string, release: 'major' | 'minor' | 'patch' | 'premajor' | 'preminor' | 'prepatch' | 'prerelease', identifier?: string | undefined): string | undefined;
30
72
  /**
31
73
  * Check if version1 equals version2.
74
+ *
75
+ * @example
76
+ * ```typescript
77
+ * isEqual('1.0.0', '1.0.0') // true
78
+ * isEqual('1.0.0', '2.0.0') // false
79
+ * ```
32
80
  */
33
81
  export declare function isEqual(version1: string, version2: string): boolean;
34
82
  /**
35
83
  * Check if version1 is greater than version2.
84
+ *
85
+ * @example
86
+ * ```typescript
87
+ * isGreaterThan('2.0.0', '1.0.0') // true
88
+ * isGreaterThan('1.0.0', '2.0.0') // false
89
+ * ```
36
90
  */
37
91
  export declare function isGreaterThan(version1: string, version2: string): boolean;
38
92
  /**
39
93
  * Check if version1 is greater than or equal to version2.
94
+ *
95
+ * @example
96
+ * ```typescript
97
+ * isGreaterThanOrEqual('2.0.0', '1.0.0') // true
98
+ * isGreaterThanOrEqual('1.0.0', '1.0.0') // true
99
+ * ```
40
100
  */
41
101
  export declare function isGreaterThanOrEqual(version1: string, version2: string): boolean;
42
102
  /**
43
103
  * Check if version1 is less than version2.
104
+ *
105
+ * @example
106
+ * ```typescript
107
+ * isLessThan('1.0.0', '2.0.0') // true
108
+ * isLessThan('2.0.0', '1.0.0') // false
109
+ * ```
44
110
  */
45
111
  export declare function isLessThan(version1: string, version2: string): boolean;
46
112
  /**
47
113
  * Check if version1 is less than or equal to version2.
114
+ *
115
+ * @example
116
+ * ```typescript
117
+ * isLessThanOrEqual('1.0.0', '2.0.0') // true
118
+ * isLessThanOrEqual('1.0.0', '1.0.0') // true
119
+ * ```
48
120
  */
49
121
  export declare function isLessThanOrEqual(version1: string, version2: string): boolean;
50
122
  /**
51
123
  * Validate if a string is a valid semantic version.
124
+ *
125
+ * @example
126
+ * ```typescript
127
+ * isValidVersion('1.2.3') // true
128
+ * isValidVersion('abc') // false
129
+ * ```
52
130
  */
53
131
  export declare function isValidVersion(version: string): boolean;
54
132
  /**
55
133
  * Get the highest version from an array of versions.
134
+ *
135
+ * @example
136
+ * ```typescript
137
+ * maxVersion(['1.0.0', '2.0.0', '1.5.0']) // '2.0.0'
138
+ * ```
56
139
  */
57
140
  export declare function maxVersion(versions: string[]): string | undefined;
58
141
  /**
59
142
  * Get the lowest version from an array of versions.
143
+ *
144
+ * @example
145
+ * ```typescript
146
+ * minVersion(['1.0.0', '2.0.0', '1.5.0']) // '1.0.0'
147
+ * ```
60
148
  */
61
149
  export declare function minVersion(versions: string[]): string | undefined;
62
150
  /**
63
151
  * Parse a version string and return major, minor, patch components.
152
+ *
153
+ * @example
154
+ * ```typescript
155
+ * parseVersion('1.2.3')
156
+ * // { major: 1, minor: 2, patch: 3, prerelease: [], build: [] }
157
+ * ```
64
158
  */
65
159
  export declare function parseVersion(version: string): {
66
160
  major: number;
@@ -71,17 +165,42 @@ export declare function parseVersion(version: string): {
71
165
  } | undefined;
72
166
  /**
73
167
  * Check if a version satisfies a semver range.
168
+ *
169
+ * @example
170
+ * ```typescript
171
+ * satisfiesVersion('1.5.0', '>=1.0.0 <2.0.0') // true
172
+ * satisfiesVersion('3.0.0', '>=1.0.0 <2.0.0') // false
173
+ * ```
74
174
  */
75
175
  export declare function satisfiesVersion(version: string, range: string): boolean;
76
176
  /**
77
177
  * Sort versions in ascending order.
178
+ *
179
+ * @example
180
+ * ```typescript
181
+ * sortVersions(['2.0.0', '1.0.0', '1.5.0'])
182
+ * // ['1.0.0', '1.5.0', '2.0.0']
183
+ * ```
78
184
  */
79
185
  export declare function sortVersions(versions: string[]): string[];
80
186
  /**
81
187
  * Sort versions in descending order.
188
+ *
189
+ * @example
190
+ * ```typescript
191
+ * sortVersionsDesc(['1.0.0', '2.0.0', '1.5.0'])
192
+ * // ['2.0.0', '1.5.0', '1.0.0']
193
+ * ```
82
194
  */
83
195
  export declare function sortVersionsDesc(versions: string[]): string[];
84
196
  /**
85
197
  * Get the difference between two versions.
198
+ *
199
+ * @example
200
+ * ```typescript
201
+ * versionDiff('1.0.0', '2.0.0') // 'major'
202
+ * versionDiff('1.0.0', '1.1.0') // 'minor'
203
+ * versionDiff('1.0.0', '1.0.1') // 'patch'
204
+ * ```
86
205
  */
87
206
  export declare function versionDiff(version1: string, version2: string): 'major' | 'premajor' | 'minor' | 'preminor' | 'patch' | 'prepatch' | 'prerelease' | 'release' | undefined;
package/dist/words.d.ts CHANGED
@@ -4,11 +4,24 @@
4
4
  */
5
5
  /**
6
6
  * Capitalize the first letter of a word.
7
+ *
8
+ * @example
9
+ * ```typescript
10
+ * capitalize('hello') // 'Hello'
11
+ * capitalize('WORLD') // 'World'
12
+ * capitalize('') // ''
13
+ * ```
7
14
  */
8
15
  /*@__NO_SIDE_EFFECTS__*/
9
16
  export declare function capitalize(word: string): string;
10
17
  /**
11
18
  * Determine the appropriate article (a/an) for a word.
19
+ *
20
+ * @example
21
+ * ```typescript
22
+ * determineArticle('apple') // 'an'
23
+ * determineArticle('banana') // 'a'
24
+ * ```
12
25
  */
13
26
  /*@__NO_SIDE_EFFECTS__*/
14
27
  export declare function determineArticle(word: string): string;
@@ -17,6 +30,13 @@ export interface PluralizeOptions {
17
30
  }
18
31
  /**
19
32
  * Pluralize a word based on count.
33
+ *
34
+ * @example
35
+ * ```typescript
36
+ * pluralize('file') // 'file'
37
+ * pluralize('file', { count: 3 }) // 'files'
38
+ * pluralize('file', { count: 0 }) // 'files'
39
+ * ```
20
40
  */
21
41
  /*@__NO_SIDE_EFFECTS__*/
22
42
  export declare function pluralize(word: string, options?: PluralizeOptions | undefined): string;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@socketsecurity/lib",
3
- "version": "5.15.0",
4
- "packageManager": "pnpm@10.33.0",
3
+ "version": "5.16.0",
4
+ "packageManager": "pnpm@11.0.0-rc.0",
5
5
  "license": "MIT",
6
6
  "description": "Core utilities and infrastructure for Socket.dev security tools",
7
7
  "keywords": [
@@ -696,7 +696,7 @@
696
696
  ],
697
697
  "engines": {
698
698
  "node": ">=22",
699
- "pnpm": ">=10.25.0"
699
+ "pnpm": ">=11.0.0-rc.0"
700
700
  },
701
701
  "sideEffects": false,
702
702
  "scripts": {
@@ -705,12 +705,13 @@
705
705
  "clean": "node scripts/build/clean.mjs",
706
706
  "cover": "node scripts/test/cover.mjs",
707
707
  "dev": "node scripts/build/main.mjs --watch",
708
- "fix": "node scripts/lint.mjs --fix",
708
+ "fix": "node scripts/fix.mjs",
709
709
  "format": "oxfmt",
710
710
  "format:check": "oxfmt --check",
711
711
  "lint": "node scripts/lint.mjs",
712
712
  "lint:oxlint": "oxlint .",
713
713
  "lint:oxfmt": "oxfmt --check .",
714
+ "security": "agentshield scan && { command -v zizmor >/dev/null && zizmor .github/ || echo 'zizmor not installed — run pnpm run setup to install'; }",
714
715
  "prepare": "husky",
715
716
  "prepublishOnly": "pnpm run build",
716
717
  "test": "node scripts/test/main.mjs",
@@ -722,6 +723,7 @@
722
723
  "@babel/parser": "7.28.4",
723
724
  "@babel/traverse": "7.28.4",
724
725
  "@babel/types": "7.28.4",
726
+ "ecc-agentshield": "1.4.0",
725
727
  "@dotenvx/dotenvx": "1.49.0",
726
728
  "@inquirer/checkbox": "4.3.1",
727
729
  "@inquirer/confirm": "5.1.16",
@@ -735,7 +737,7 @@
735
737
  "@socketregistry/is-unicode-supported": "1.0.5",
736
738
  "@socketregistry/packageurl-js": "1.4.1",
737
739
  "@socketregistry/yocto-spinner": "1.0.25",
738
- "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.14.0",
740
+ "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.15.0",
739
741
  "@types/node": "24.9.2",
740
742
  "@typescript/native-preview": "7.0.0-dev.20250920.1",
741
743
  "@vitest/coverage-v8": "4.0.3",
@@ -796,57 +798,5 @@
796
798
  "typescript": {
797
799
  "optional": true
798
800
  }
799
- },
800
- "pnpm": {
801
- "overrides": {
802
- "@inquirer/ansi": "1.0.2",
803
- "@inquirer/core": "10.3.1",
804
- "@inquirer/figures": "1.0.15",
805
- "@npmcli/arborist": "9.1.6",
806
- "@npmcli/git": "6.0.3",
807
- "@npmcli/run-script": "10.0.0",
808
- "@sigstore/core": "3.1.0",
809
- "@sigstore/sign": "4.1.0",
810
- "ansi-regex": "6.2.2",
811
- "brace-expansion": "5.0.5",
812
- "chownr": "3.0.0",
813
- "debug": "4.4.3",
814
- "execa": "5.1.1",
815
- "has-flag": "5.0.1",
816
- "hosted-git-info": "8.1.0",
817
- "isexe": "3.1.1",
818
- "lru-cache": "11.2.2",
819
- "minimatch": "9.0.6",
820
- "minipass": "7.1.3",
821
- "minipass-fetch": "4.0.1",
822
- "minipass-sized": "1.0.3",
823
- "minipass@7": "7.1.3",
824
- "minizlib": "3.1.0",
825
- "npm-package-arg": "12.0.2",
826
- "npm-pick-manifest": "10.0.0",
827
- "p-map": "7.0.4",
828
- "picomatch": "4.0.4",
829
- "proc-log": "6.1.0",
830
- "semver": "7.7.2",
831
- "signal-exit": "4.1.0",
832
- "spdx-expression-parse": "4.0.0",
833
- "ssri": "12.0.0",
834
- "string-width": "8.1.0",
835
- "strip-ansi": "7.1.2",
836
- "supports-color": "10.2.2",
837
- "tar": "7.5.11",
838
- "which": "5.0.0",
839
- "wrap-ansi": "9.0.2",
840
- "yoctocolors-cjs": "2.1.3"
841
- },
842
- "patchedDependencies": {
843
- "@npmcli/run-script@10.0.0": "patches/@npmcli__run-script@10.0.0.patch",
844
- "@sigstore/sign@4.1.0": "patches/@sigstore__sign@4.1.0.patch",
845
- "execa@5.1.1": "patches/execa@5.1.1.patch",
846
- "minipass-flush@1.0.5": "patches/minipass-flush@1.0.5.patch",
847
- "minipass-pipeline@1.2.4": "patches/minipass-pipeline@1.2.4.patch",
848
- "node-gyp@11.5.0": "patches/node-gyp@11.5.0.patch",
849
- "minipass-sized@1.0.3": "patches/minipass-sized@1.0.3.patch"
850
- }
851
801
  }
852
802
  }