@fuzdev/fuz_util 0.54.0 → 0.56.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 (106) hide show
  1. package/dist/args.d.ts +12 -12
  2. package/dist/args.js +11 -11
  3. package/dist/async.d.ts +12 -12
  4. package/dist/async.js +12 -12
  5. package/dist/benchmark.d.ts +24 -24
  6. package/dist/benchmark.js +26 -26
  7. package/dist/benchmark_baseline.d.ts +17 -11
  8. package/dist/benchmark_baseline.d.ts.map +1 -1
  9. package/dist/benchmark_baseline.js +26 -19
  10. package/dist/benchmark_format.d.ts +15 -15
  11. package/dist/benchmark_format.js +15 -15
  12. package/dist/benchmark_stats.d.ts +30 -10
  13. package/dist/benchmark_stats.d.ts.map +1 -1
  14. package/dist/benchmark_stats.js +48 -40
  15. package/dist/benchmark_types.d.ts +7 -7
  16. package/dist/bytes.d.ts +4 -4
  17. package/dist/bytes.js +4 -4
  18. package/dist/dag.d.ts +2 -2
  19. package/dist/dag.js +2 -2
  20. package/dist/deep_equal.d.ts +2 -2
  21. package/dist/deep_equal.js +2 -2
  22. package/dist/diff.d.ts +17 -17
  23. package/dist/diff.js +17 -17
  24. package/dist/dom.d.ts +4 -4
  25. package/dist/dom.js +4 -4
  26. package/dist/fetch.d.ts +1 -1
  27. package/dist/fetch.js +1 -1
  28. package/dist/git.d.ts +1 -1
  29. package/dist/git.js +1 -1
  30. package/dist/hash.d.ts +6 -6
  31. package/dist/hash.js +8 -8
  32. package/dist/hash_blake3.d.ts +1 -1
  33. package/dist/hash_blake3.js +1 -1
  34. package/dist/hex.d.ts +4 -4
  35. package/dist/hex.js +4 -4
  36. package/dist/json.d.ts +2 -2
  37. package/dist/json.js +2 -2
  38. package/dist/log.d.ts +12 -12
  39. package/dist/log.js +11 -11
  40. package/dist/map.d.ts +1 -1
  41. package/dist/map.js +1 -1
  42. package/dist/object.d.ts +1 -1
  43. package/dist/object.js +1 -1
  44. package/dist/package_json.d.ts +1 -1
  45. package/dist/package_json.js +1 -1
  46. package/dist/path.d.ts +5 -5
  47. package/dist/path.js +5 -5
  48. package/dist/process.d.ts +22 -22
  49. package/dist/process.js +22 -22
  50. package/dist/random.d.ts +2 -2
  51. package/dist/random.js +2 -2
  52. package/dist/result.d.ts +6 -6
  53. package/dist/result.js +6 -6
  54. package/dist/sort.d.ts +3 -3
  55. package/dist/sort.js +3 -3
  56. package/dist/source_json.d.ts +3 -3
  57. package/dist/source_json.js +3 -3
  58. package/dist/stats.d.ts +17 -17
  59. package/dist/stats.js +17 -17
  60. package/dist/string.d.ts +6 -6
  61. package/dist/string.js +6 -6
  62. package/dist/svelte_preprocess_helpers.d.ts +42 -42
  63. package/dist/svelte_preprocess_helpers.js +42 -42
  64. package/dist/testing.d.ts +44 -0
  65. package/dist/testing.d.ts.map +1 -0
  66. package/dist/testing.js +59 -0
  67. package/dist/time.d.ts +19 -19
  68. package/dist/time.js +19 -19
  69. package/dist/zod.d.ts +16 -16
  70. package/dist/zod.d.ts.map +1 -1
  71. package/dist/zod.js +24 -24
  72. package/package.json +6 -6
  73. package/src/lib/args.ts +12 -12
  74. package/src/lib/async.ts +12 -12
  75. package/src/lib/benchmark.ts +28 -28
  76. package/src/lib/benchmark_baseline.ts +37 -20
  77. package/src/lib/benchmark_format.ts +15 -15
  78. package/src/lib/benchmark_stats.ts +66 -44
  79. package/src/lib/benchmark_types.ts +7 -7
  80. package/src/lib/bytes.ts +4 -4
  81. package/src/lib/dag.ts +2 -2
  82. package/src/lib/deep_equal.ts +2 -2
  83. package/src/lib/diff.ts +17 -17
  84. package/src/lib/dom.ts +4 -4
  85. package/src/lib/fetch.ts +1 -1
  86. package/src/lib/git.ts +1 -1
  87. package/src/lib/hash.ts +8 -8
  88. package/src/lib/hash_blake3.ts +1 -1
  89. package/src/lib/hex.ts +4 -4
  90. package/src/lib/json.ts +2 -2
  91. package/src/lib/log.ts +12 -12
  92. package/src/lib/map.ts +1 -1
  93. package/src/lib/object.ts +1 -1
  94. package/src/lib/package_json.ts +1 -1
  95. package/src/lib/path.ts +5 -5
  96. package/src/lib/process.ts +22 -22
  97. package/src/lib/random.ts +2 -2
  98. package/src/lib/result.ts +6 -6
  99. package/src/lib/sort.ts +3 -3
  100. package/src/lib/source_json.ts +3 -3
  101. package/src/lib/stats.ts +17 -17
  102. package/src/lib/string.ts +6 -6
  103. package/src/lib/svelte_preprocess_helpers.ts +42 -42
  104. package/src/lib/testing.ts +80 -0
  105. package/src/lib/time.ts +19 -19
  106. package/src/lib/zod.ts +24 -24
package/dist/args.d.ts CHANGED
@@ -21,7 +21,7 @@ export interface ParsedArgs extends Args {
21
21
  export type ArgValue = string | number | boolean | undefined | Array<string | number | boolean>;
22
22
  /**
23
23
  * Schema description for help text generation.
24
- * Not used by args_parse/args_serialize directly - provided for consumers
24
+ * Not used by `args_parse`/`args_serialize` directly - provided for consumers
25
25
  * building CLI help output.
26
26
  */
27
27
  export interface ArgSchema {
@@ -46,8 +46,8 @@ export interface ArgsAliasesResult {
46
46
  *
47
47
  * Results are cached per schema (WeakMap). Safe to call multiple times.
48
48
  *
49
- * @param schema Zod object schema with optional alias metadata
50
- * @returns Validation result with success flag and optional error
49
+ * @param schema - zod object schema with optional alias metadata
50
+ * @returns validation result with success flag and optional error
51
51
  */
52
52
  export declare const args_validate_schema: (schema: z.ZodType) => {
53
53
  success: true;
@@ -67,8 +67,8 @@ export declare const args_validate_schema: (schema: z.ZodType) => {
67
67
  *
68
68
  * Schema analysis is cached per schema (WeakMap) for performance.
69
69
  *
70
- * @param unparsed_args Args object from CLI parser (mri, minimist, etc.)
71
- * @param schema Zod object schema with optional alias metadata
70
+ * @param unparsed_args - args object from CLI parser (mri, minimist, etc.)
71
+ * @param schema - zod object schema with optional alias metadata
72
72
  * @returns Zod SafeParseResult with expanded/synced data on success
73
73
  */
74
74
  export declare const args_parse: <TOutput extends Record<string, ArgValue> = Args>(unparsed_args: Args, schema: z.ZodType<TOutput>) => z.ZodSafeParseResult<TOutput>;
@@ -85,9 +85,9 @@ export declare const args_parse: <TOutput extends Record<string, ArgValue> = Arg
85
85
  *
86
86
  * Schema analysis is cached per schema (WeakMap) for performance.
87
87
  *
88
- * @param args Args object to serialize
89
- * @param schema Optional zod schema to extract aliases for short form preference
90
- * @returns Array of CLI argument strings
88
+ * @param args - args object to serialize
89
+ * @param schema - optional zod schema to extract aliases for short form preference
90
+ * @returns array of CLI argument strings
91
91
  */
92
92
  export declare const args_serialize: (args: Args, schema?: z.ZodType) => Array<string>;
93
93
  /**
@@ -98,8 +98,8 @@ export declare const args_serialize: (args: Args, schema?: z.ZodType) => Array<s
98
98
  *
99
99
  * Note: Returns copies of the cached data to prevent mutation of internal cache.
100
100
  *
101
- * @param schema Zod object schema with optional `.meta({aliases})` on fields
102
- * @returns Object with aliases map and canonical_keys set
101
+ * @param schema - zod object schema with optional `.meta({aliases})` on fields
102
+ * @returns object with aliases map and canonical_keys set
103
103
  */
104
104
  export declare const args_extract_aliases: (schema: z.ZodType) => ArgsAliasesResult;
105
105
  /**
@@ -131,8 +131,8 @@ export declare const args_extract_aliases: (schema: z.ZodType) => ArgsAliasesRes
131
131
  * The returned object uses `Object.create(null)` to prevent prototype pollution
132
132
  * and allow any key name including `__proto__` and `constructor`.
133
133
  *
134
- * @param argv Raw argument array (typically process.argv.slice(2))
135
- * @returns Parsed Args object with guaranteed `_` array (null prototype)
134
+ * @param argv - raw argument array (typically process.argv.slice(2))
135
+ * @returns parsed `Args` object with guaranteed `_` array (null prototype)
136
136
  */
137
137
  export declare const argv_parse: (argv: Array<string>) => ParsedArgs;
138
138
  //# sourceMappingURL=args.d.ts.map
package/dist/args.js CHANGED
@@ -111,8 +111,8 @@ const get_schema_cache = (schema) => {
111
111
  *
112
112
  * Results are cached per schema (WeakMap). Safe to call multiple times.
113
113
  *
114
- * @param schema Zod object schema with optional alias metadata
115
- * @returns Validation result with success flag and optional error
114
+ * @param schema - zod object schema with optional alias metadata
115
+ * @returns validation result with success flag and optional error
116
116
  */
117
117
  export const args_validate_schema = (schema) => {
118
118
  const cache = get_schema_cache(schema);
@@ -133,8 +133,8 @@ export const args_validate_schema = (schema) => {
133
133
  *
134
134
  * Schema analysis is cached per schema (WeakMap) for performance.
135
135
  *
136
- * @param unparsed_args Args object from CLI parser (mri, minimist, etc.)
137
- * @param schema Zod object schema with optional alias metadata
136
+ * @param unparsed_args - args object from CLI parser (mri, minimist, etc.)
137
+ * @param schema - zod object schema with optional alias metadata
138
138
  * @returns Zod SafeParseResult with expanded/synced data on success
139
139
  */
140
140
  export const args_parse = (unparsed_args, schema) => {
@@ -193,9 +193,9 @@ export const args_parse = (unparsed_args, schema) => {
193
193
  *
194
194
  * Schema analysis is cached per schema (WeakMap) for performance.
195
195
  *
196
- * @param args Args object to serialize
197
- * @param schema Optional zod schema to extract aliases for short form preference
198
- * @returns Array of CLI argument strings
196
+ * @param args - args object to serialize
197
+ * @param schema - optional zod schema to extract aliases for short form preference
198
+ * @returns array of CLI argument strings
199
199
  */
200
200
  export const args_serialize = (args, schema) => {
201
201
  const result = [];
@@ -264,8 +264,8 @@ export const args_serialize = (args, schema) => {
264
264
  *
265
265
  * Note: Returns copies of the cached data to prevent mutation of internal cache.
266
266
  *
267
- * @param schema Zod object schema with optional `.meta({aliases})` on fields
268
- * @returns Object with aliases map and canonical_keys set
267
+ * @param schema - zod object schema with optional `.meta({aliases})` on fields
268
+ * @returns object with aliases map and canonical_keys set
269
269
  */
270
270
  export const args_extract_aliases = (schema) => {
271
271
  const cache = get_schema_cache(schema);
@@ -334,8 +334,8 @@ const set_arg = (args, key, value) => {
334
334
  * The returned object uses `Object.create(null)` to prevent prototype pollution
335
335
  * and allow any key name including `__proto__` and `constructor`.
336
336
  *
337
- * @param argv Raw argument array (typically process.argv.slice(2))
338
- * @returns Parsed Args object with guaranteed `_` array (null prototype)
337
+ * @param argv - raw argument array (typically process.argv.slice(2))
338
+ * @returns parsed `Args` object with guaranteed `_` array (null prototype)
339
339
  */
340
340
  export const argv_parse = (argv) => {
341
341
  // Use Object.create(null) to allow __proto__ as a normal key
package/dist/async.d.ts CHANGED
@@ -23,10 +23,10 @@ export declare const create_deferred: <T>() => Deferred<T>;
23
23
  * Runs a function on each item with controlled concurrency.
24
24
  * Like `map_concurrent` but doesn't collect results (more efficient for side effects).
25
25
  *
26
- * @param items items to process
27
- * @param concurrency maximum number of concurrent operations
28
- * @param fn function to apply to each item
29
- * @param signal optional `AbortSignal` to cancel processing
26
+ * @param items - items to process
27
+ * @param concurrency - maximum number of concurrent operations
28
+ * @param fn - function to apply to each item
29
+ * @param signal - optional `AbortSignal` to cancel processing
30
30
  *
31
31
  * @example
32
32
  * ```ts
@@ -41,10 +41,10 @@ export declare const each_concurrent: <T>(items: Iterable<T>, concurrency: numbe
41
41
  /**
42
42
  * Maps over items with controlled concurrency, preserving input order.
43
43
  *
44
- * @param items items to process
45
- * @param concurrency maximum number of concurrent operations
46
- * @param fn function to apply to each item
47
- * @param signal optional `AbortSignal` to cancel processing
44
+ * @param items - items to process
45
+ * @param concurrency - maximum number of concurrent operations
46
+ * @param fn - function to apply to each item
47
+ * @param signal - optional `AbortSignal` to cancel processing
48
48
  * @returns promise resolving to array of results in same order as input
49
49
  *
50
50
  * @example
@@ -64,10 +64,10 @@ export declare const map_concurrent: <T, R>(items: Iterable<T>, concurrency: num
64
64
  * On abort, resolves with partial results: completed items keep their real settlements,
65
65
  * in-flight and un-started items are settled as rejected with the abort reason.
66
66
  *
67
- * @param items items to process
68
- * @param concurrency maximum number of concurrent operations
69
- * @param fn function to apply to each item
70
- * @param signal optional `AbortSignal` to cancel processing
67
+ * @param items - items to process
68
+ * @param concurrency - maximum number of concurrent operations
69
+ * @param fn - function to apply to each item
70
+ * @param signal - optional `AbortSignal` to cancel processing
71
71
  * @returns promise resolving to array of `PromiseSettledResult` objects in input order
72
72
  *
73
73
  * @example
package/dist/async.js CHANGED
@@ -22,10 +22,10 @@ export const create_deferred = () => {
22
22
  * Runs a function on each item with controlled concurrency.
23
23
  * Like `map_concurrent` but doesn't collect results (more efficient for side effects).
24
24
  *
25
- * @param items items to process
26
- * @param concurrency maximum number of concurrent operations
27
- * @param fn function to apply to each item
28
- * @param signal optional `AbortSignal` to cancel processing
25
+ * @param items - items to process
26
+ * @param concurrency - maximum number of concurrent operations
27
+ * @param fn - function to apply to each item
28
+ * @param signal - optional `AbortSignal` to cancel processing
29
29
  *
30
30
  * @example
31
31
  * ```ts
@@ -95,10 +95,10 @@ export const each_concurrent = async (items, concurrency, fn, signal) => {
95
95
  /**
96
96
  * Maps over items with controlled concurrency, preserving input order.
97
97
  *
98
- * @param items items to process
99
- * @param concurrency maximum number of concurrent operations
100
- * @param fn function to apply to each item
101
- * @param signal optional `AbortSignal` to cancel processing
98
+ * @param items - items to process
99
+ * @param concurrency - maximum number of concurrent operations
100
+ * @param fn - function to apply to each item
101
+ * @param signal - optional `AbortSignal` to cancel processing
102
102
  * @returns promise resolving to array of results in same order as input
103
103
  *
104
104
  * @example
@@ -175,10 +175,10 @@ export const map_concurrent = async (items, concurrency, fn, signal) => {
175
175
  * On abort, resolves with partial results: completed items keep their real settlements,
176
176
  * in-flight and un-started items are settled as rejected with the abort reason.
177
177
  *
178
- * @param items items to process
179
- * @param concurrency maximum number of concurrent operations
180
- * @param fn function to apply to each item
181
- * @param signal optional `AbortSignal` to cancel processing
178
+ * @param items - items to process
179
+ * @param concurrency - maximum number of concurrent operations
180
+ * @param fn - function to apply to each item
181
+ * @param signal - optional `AbortSignal` to cancel processing
182
182
  * @returns promise resolving to array of `PromiseSettledResult` objects in input order
183
183
  *
184
184
  * @example
@@ -26,10 +26,10 @@ import type { BenchmarkConfig, BenchmarkTask, BenchmarkResult, BenchmarkFormatTa
26
26
  * Warmup function by running it multiple times.
27
27
  * Detects whether the function is async based on return value.
28
28
  *
29
- * @param fn - Function to warmup (sync or async)
30
- * @param iterations - Number of warmup iterations
31
- * @param async_hint - If provided, use this instead of detecting
32
- * @returns Whether the function is async
29
+ * @param fn - function to warmup (sync or async)
30
+ * @param iterations - number of warmup iterations
31
+ * @param async_hint - if provided, use this instead of detecting
32
+ * @returns whether the function is async
33
33
  *
34
34
  * @example
35
35
  * ```ts
@@ -45,9 +45,9 @@ export declare class Benchmark {
45
45
  constructor(config?: BenchmarkConfig);
46
46
  /**
47
47
  * Add a benchmark task.
48
- * @param name - Task name or full task object
48
+ * @param name - task name or full task object
49
49
  * @param fn - Function to benchmark (if name is string). Return values are ignored.
50
- * @returns This Benchmark instance for chaining
50
+ * @returns this `Benchmark` instance for chaining
51
51
  *
52
52
  * @example
53
53
  * ```ts
@@ -66,8 +66,8 @@ export declare class Benchmark {
66
66
  add(task: BenchmarkTask): this;
67
67
  /**
68
68
  * Remove a benchmark task by name.
69
- * @param name - Name of the task to remove
70
- * @returns This Benchmark instance for chaining
69
+ * @param name - name of the task to remove
70
+ * @returns this `Benchmark` instance for chaining
71
71
  * @throws Error if task with given name doesn't exist
72
72
  *
73
73
  * @example
@@ -81,8 +81,8 @@ export declare class Benchmark {
81
81
  remove(name: string): this;
82
82
  /**
83
83
  * Mark a task to be skipped during benchmark runs.
84
- * @param name - Name of the task to skip
85
- * @returns This Benchmark instance for chaining
84
+ * @param name - name of the task to skip
85
+ * @returns this `Benchmark` instance for chaining
86
86
  * @throws Error if task with given name doesn't exist
87
87
  *
88
88
  * @example
@@ -96,8 +96,8 @@ export declare class Benchmark {
96
96
  skip(name: string): this;
97
97
  /**
98
98
  * Mark a task to run exclusively (along with other `only` tasks).
99
- * @param name - Name of the task to run exclusively
100
- * @returns This Benchmark instance for chaining
99
+ * @param name - name of the task to run exclusively
100
+ * @returns this `Benchmark` instance for chaining
101
101
  * @throws Error if task with given name doesn't exist
102
102
  *
103
103
  * @example
@@ -112,13 +112,13 @@ export declare class Benchmark {
112
112
  only(name: string): this;
113
113
  /**
114
114
  * Run all benchmark tasks.
115
- * @returns Array of benchmark results
115
+ * @returns array of benchmark results
116
116
  */
117
117
  run(): Promise<Array<BenchmarkResult>>;
118
118
  /**
119
119
  * Format results as an ASCII table with percentiles, min/max, and relative performance.
120
- * @param options - Formatting options
121
- * @returns Formatted table string
120
+ * @param options - formatting options
121
+ * @returns formatted table string
122
122
  *
123
123
  * @example
124
124
  * ```ts
@@ -137,8 +137,8 @@ export declare class Benchmark {
137
137
  table(options?: BenchmarkFormatTableOptions): string;
138
138
  /**
139
139
  * Format results as a Markdown table.
140
- * @param options - Formatting options (groups for organized output with optional baselines)
141
- * @returns Formatted markdown string
140
+ * @param options - formatting options (groups for organized output with optional baselines)
141
+ * @returns formatted markdown string
142
142
  *
143
143
  * @example
144
144
  * ```ts
@@ -157,19 +157,19 @@ export declare class Benchmark {
157
157
  markdown(options?: BenchmarkFormatTableOptions): string;
158
158
  /**
159
159
  * Format results as JSON.
160
- * @param options - Formatting options (pretty, include_timings)
160
+ * @param options - formatting options (pretty, include_timings)
161
161
  * @returns JSON string
162
162
  */
163
163
  json(options?: BenchmarkFormatJsonOptions): string;
164
164
  /**
165
165
  * Get the benchmark results.
166
166
  * Returns a shallow copy to prevent external mutation.
167
- * @returns Array of benchmark results
167
+ * @returns array of benchmark results
168
168
  */
169
169
  results(): Array<BenchmarkResult>;
170
170
  /**
171
171
  * Check if the benchmark has been run and has results.
172
- * @returns True if results are available
172
+ * @returns true if results are available
173
173
  *
174
174
  * @example
175
175
  * ```ts
@@ -182,7 +182,7 @@ export declare class Benchmark {
182
182
  /**
183
183
  * Get results as a map for convenient lookup by task name.
184
184
  * Returns a new Map each call to prevent external mutation.
185
- * @returns Map of task name to benchmark result
185
+ * @returns map of task name to benchmark result
186
186
  *
187
187
  * @example
188
188
  * ```ts
@@ -197,18 +197,18 @@ export declare class Benchmark {
197
197
  /**
198
198
  * Reset the benchmark results.
199
199
  * Keeps tasks intact so benchmarks can be rerun.
200
- * @returns This Benchmark instance for chaining
200
+ * @returns this `Benchmark` instance for chaining
201
201
  */
202
202
  reset(): this;
203
203
  /**
204
204
  * Clear everything (results and tasks).
205
205
  * Use this to start fresh with a new set of benchmarks.
206
- * @returns This Benchmark instance for chaining
206
+ * @returns this `Benchmark` instance for chaining
207
207
  */
208
208
  clear(): this;
209
209
  /**
210
210
  * Get a quick text summary of the fastest task.
211
- * @returns Human-readable summary string
211
+ * @returns human-readable summary string
212
212
  *
213
213
  * @example
214
214
  * ```ts
package/dist/benchmark.js CHANGED
@@ -28,8 +28,8 @@ import { benchmark_format_table, benchmark_format_table_grouped, benchmark_forma
28
28
  const DEFAULT_DURATION_MS = 1000;
29
29
  const DEFAULT_WARMUP_ITERATIONS = 10;
30
30
  const DEFAULT_COOLDOWN_MS = 100;
31
- const DEFAULT_MIN_ITERATIONS = 10;
32
- const DEFAULT_MAX_ITERATIONS = 100_000;
31
+ const DEFAULT_ITERATIONS_MIN = 10;
32
+ const DEFAULT_ITERATIONS_MAX = 100_000;
33
33
  /**
34
34
  * Validate and normalize benchmark configuration.
35
35
  * Throws if configuration is invalid.
@@ -60,10 +60,10 @@ const validate_config = (config) => {
60
60
  * Warmup function by running it multiple times.
61
61
  * Detects whether the function is async based on return value.
62
62
  *
63
- * @param fn - Function to warmup (sync or async)
64
- * @param iterations - Number of warmup iterations
65
- * @param async_hint - If provided, use this instead of detecting
66
- * @returns Whether the function is async
63
+ * @param fn - function to warmup (sync or async)
64
+ * @param iterations - number of warmup iterations
65
+ * @param async_hint - if provided, use this instead of detecting
66
+ * @returns whether the function is async
67
67
  *
68
68
  * @example
69
69
  * ```ts
@@ -108,8 +108,8 @@ export class Benchmark {
108
108
  duration_ms: config.duration_ms ?? DEFAULT_DURATION_MS,
109
109
  warmup_iterations: config.warmup_iterations ?? DEFAULT_WARMUP_ITERATIONS,
110
110
  cooldown_ms: config.cooldown_ms ?? DEFAULT_COOLDOWN_MS,
111
- min_iterations: config.min_iterations ?? DEFAULT_MIN_ITERATIONS,
112
- max_iterations: config.max_iterations ?? DEFAULT_MAX_ITERATIONS,
111
+ min_iterations: config.min_iterations ?? DEFAULT_ITERATIONS_MIN,
112
+ max_iterations: config.max_iterations ?? DEFAULT_ITERATIONS_MAX,
113
113
  timer: config.timer ?? timer_default,
114
114
  on_iteration: config.on_iteration,
115
115
  on_task_complete: config.on_task_complete,
@@ -133,8 +133,8 @@ export class Benchmark {
133
133
  }
134
134
  /**
135
135
  * Remove a benchmark task by name.
136
- * @param name - Name of the task to remove
137
- * @returns This Benchmark instance for chaining
136
+ * @param name - name of the task to remove
137
+ * @returns this `Benchmark` instance for chaining
138
138
  * @throws Error if task with given name doesn't exist
139
139
  *
140
140
  * @example
@@ -155,8 +155,8 @@ export class Benchmark {
155
155
  }
156
156
  /**
157
157
  * Mark a task to be skipped during benchmark runs.
158
- * @param name - Name of the task to skip
159
- * @returns This Benchmark instance for chaining
158
+ * @param name - name of the task to skip
159
+ * @returns this `Benchmark` instance for chaining
160
160
  * @throws Error if task with given name doesn't exist
161
161
  *
162
162
  * @example
@@ -177,8 +177,8 @@ export class Benchmark {
177
177
  }
178
178
  /**
179
179
  * Mark a task to run exclusively (along with other `only` tasks).
180
- * @param name - Name of the task to run exclusively
181
- * @returns This Benchmark instance for chaining
180
+ * @param name - name of the task to run exclusively
181
+ * @returns this `Benchmark` instance for chaining
182
182
  * @throws Error if task with given name doesn't exist
183
183
  *
184
184
  * @example
@@ -200,7 +200,7 @@ export class Benchmark {
200
200
  }
201
201
  /**
202
202
  * Run all benchmark tasks.
203
- * @returns Array of benchmark results
203
+ * @returns array of benchmark results
204
204
  */
205
205
  async run() {
206
206
  this.#results = [];
@@ -306,8 +306,8 @@ export class Benchmark {
306
306
  }
307
307
  /**
308
308
  * Format results as an ASCII table with percentiles, min/max, and relative performance.
309
- * @param options - Formatting options
310
- * @returns Formatted table string
309
+ * @param options - formatting options
310
+ * @returns formatted table string
311
311
  *
312
312
  * @example
313
313
  * ```ts
@@ -330,8 +330,8 @@ export class Benchmark {
330
330
  }
331
331
  /**
332
332
  * Format results as a Markdown table.
333
- * @param options - Formatting options (groups for organized output with optional baselines)
334
- * @returns Formatted markdown string
333
+ * @param options - formatting options (groups for organized output with optional baselines)
334
+ * @returns formatted markdown string
335
335
  *
336
336
  * @example
337
337
  * ```ts
@@ -354,7 +354,7 @@ export class Benchmark {
354
354
  }
355
355
  /**
356
356
  * Format results as JSON.
357
- * @param options - Formatting options (pretty, include_timings)
357
+ * @param options - formatting options (pretty, include_timings)
358
358
  * @returns JSON string
359
359
  */
360
360
  json(options) {
@@ -363,14 +363,14 @@ export class Benchmark {
363
363
  /**
364
364
  * Get the benchmark results.
365
365
  * Returns a shallow copy to prevent external mutation.
366
- * @returns Array of benchmark results
366
+ * @returns array of benchmark results
367
367
  */
368
368
  results() {
369
369
  return [...this.#results];
370
370
  }
371
371
  /**
372
372
  * Check if the benchmark has been run and has results.
373
- * @returns True if results are available
373
+ * @returns true if results are available
374
374
  *
375
375
  * @example
376
376
  * ```ts
@@ -385,7 +385,7 @@ export class Benchmark {
385
385
  /**
386
386
  * Get results as a map for convenient lookup by task name.
387
387
  * Returns a new Map each call to prevent external mutation.
388
- * @returns Map of task name to benchmark result
388
+ * @returns map of task name to benchmark result
389
389
  *
390
390
  * @example
391
391
  * ```ts
@@ -402,7 +402,7 @@ export class Benchmark {
402
402
  /**
403
403
  * Reset the benchmark results.
404
404
  * Keeps tasks intact so benchmarks can be rerun.
405
- * @returns This Benchmark instance for chaining
405
+ * @returns this `Benchmark` instance for chaining
406
406
  */
407
407
  reset() {
408
408
  this.#results = [];
@@ -411,7 +411,7 @@ export class Benchmark {
411
411
  /**
412
412
  * Clear everything (results and tasks).
413
413
  * Use this to start fresh with a new set of benchmarks.
414
- * @returns This Benchmark instance for chaining
414
+ * @returns this `Benchmark` instance for chaining
415
415
  */
416
416
  clear() {
417
417
  this.#results = [];
@@ -420,7 +420,7 @@ export class Benchmark {
420
420
  }
421
421
  /**
422
422
  * Get a quick text summary of the fastest task.
423
- * @returns Human-readable summary string
423
+ * @returns human-readable summary string
424
424
  *
425
425
  * @example
426
426
  * ```ts
@@ -83,6 +83,12 @@ export interface BenchmarkBaselineCompareOptions extends BenchmarkBaselineLoadOp
83
83
  * Default: undefined (no staleness warning)
84
84
  */
85
85
  staleness_warning_days?: number;
86
+ /**
87
+ * Minimum percentage difference to consider meaningful, as a ratio.
88
+ * Passed through to `benchmark_stats_compare`. See `BenchmarkCompareOptions`.
89
+ * Default: 0.10 (10%)
90
+ */
91
+ min_percent_difference?: number;
86
92
  }
87
93
  /**
88
94
  * Result of comparing current results against a baseline.
@@ -123,8 +129,8 @@ export interface BenchmarkBaselineTaskComparison {
123
129
  /**
124
130
  * Save benchmark results as the current baseline.
125
131
  *
126
- * @param results - Benchmark results to save
127
- * @param options - Save options
132
+ * @param results - benchmark results to save
133
+ * @param options - save options
128
134
  *
129
135
  * @example
130
136
  * ```ts
@@ -138,8 +144,8 @@ export declare const benchmark_baseline_save: (results: Array<BenchmarkResult>,
138
144
  /**
139
145
  * Load the current baseline from disk.
140
146
  *
141
- * @param options - Load options
142
- * @returns The baseline, or null if not found or invalid
147
+ * @param options - load options
148
+ * @returns the baseline, or null if not found or invalid
143
149
  *
144
150
  * @example
145
151
  * ```ts
@@ -153,9 +159,9 @@ export declare const benchmark_baseline_load: (options?: BenchmarkBaselineLoadOp
153
159
  /**
154
160
  * Compare benchmark results against the stored baseline.
155
161
  *
156
- * @param results - Current benchmark results
157
- * @param options - Comparison options including regression threshold and staleness warning
158
- * @returns Comparison result with regressions, improvements, and unchanged tasks
162
+ * @param results - current benchmark results
163
+ * @param options - comparison options including regression threshold and staleness warning
164
+ * @returns comparison result with regressions, improvements, and unchanged tasks
159
165
  *
160
166
  * @example
161
167
  * ```ts
@@ -180,15 +186,15 @@ export declare const benchmark_baseline_compare: (results: Array<BenchmarkResult
180
186
  /**
181
187
  * Format a baseline comparison result as a human-readable string.
182
188
  *
183
- * @param result - Comparison result from benchmark_baseline_compare
184
- * @returns Formatted string summary
189
+ * @param result - comparison result from `benchmark_baseline_compare`
190
+ * @returns formatted string summary
185
191
  */
186
192
  export declare const benchmark_baseline_format: (result: BenchmarkBaselineComparisonResult) => string;
187
193
  /**
188
194
  * Format a baseline comparison result as JSON for programmatic consumption.
189
195
  *
190
- * @param result - Comparison result from benchmark_baseline_compare
191
- * @param options - Formatting options
196
+ * @param result - comparison result from `benchmark_baseline_compare`
197
+ * @param options - formatting options
192
198
  * @returns JSON string
193
199
  */
194
200
  export declare const benchmark_baseline_format_json: (result: BenchmarkBaselineComparisonResult, options?: {
@@ -1 +1 @@
1
- {"version":3,"file":"benchmark_baseline.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/benchmark_baseline.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"benchmark_baseline.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/benchmark_baseline.ts"],"names":[],"mappings":"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"}