@fuzdev/fuz_util 0.54.0 → 0.56.0

package/src/lib/benchmark_baseline.ts

@@ -89,6 +89,12 @@ export interface BenchmarkBaselineCompareOptions extends BenchmarkBaselineLoadOp
 	 * Default: undefined (no staleness warning)
 	 */
 	staleness_warning_days?: number;
+	/**
+	 * Minimum percentage difference to consider meaningful, as a ratio.
+	 * Passed through to `benchmark_stats_compare`. See `BenchmarkCompareOptions`.
+	 * Default: 0.10 (10%)
+	 */
+	min_percent_difference?: number;
 }
 
 /**
@@ -155,8 +161,8 @@ const results_to_entries = (results: Array<BenchmarkResult>): Array<BenchmarkBas
 /**
  * Save benchmark results as the current baseline.
  *
- * @param results - Benchmark results to save
- * @param options - Save options
+ * @param results - benchmark results to save
+ * @param options - save options
  *
  * @example
  * ```ts
@@ -198,8 +204,8 @@ export const benchmark_baseline_save = async (
 /**
  * Load the current baseline from disk.
  *
- * @param options - Load options
- * @returns The baseline, or null if not found or invalid
+ * @param options - load options
+ * @returns the baseline, or null if not found or invalid
  *
  * @example
  * ```ts
@@ -249,9 +255,9 @@ export const benchmark_baseline_load = async (
 /**
  * Compare benchmark results against the stored baseline.
  *
- * @param results - Current benchmark results
- * @param options - Comparison options including regression threshold and staleness warning
- * @returns Comparison result with regressions, improvements, and unchanged tasks
+ * @param results - current benchmark results
+ * @param options - comparison options including regression threshold and staleness warning
+ * @returns comparison result with regressions, improvements, and unchanged tasks
  *
  * @example
  * ```ts
@@ -344,7 +350,9 @@ export const benchmark_baseline_compare = async (
 			),
 		};
 
-		const comparison = benchmark_stats_compare(baseline_stats, current_stats);
+		const comparison = benchmark_stats_compare(baseline_stats, current_stats, {
+			min_percent_difference: options.min_percent_difference,
+		});
 
 		const task_comparison: BenchmarkBaselineTaskComparison = {
 			name: current.name,
@@ -357,7 +365,8 @@ export const benchmark_baseline_compare = async (
 
 		// Categorize based on comparison result
 		// Note: comparison.faster is 'a' (baseline) or 'b' (current)
-		if (comparison.significant && comparison.effect_magnitude !== 'negligible') {
+		// significant implies percent_difference >= min_pct, which implies effect_magnitude !== 'negligible'
+		if (comparison.significant) {
 			if (comparison.faster === 'a') {
 				// Baseline was faster = potential regression
 				// Only count as regression if it exceeds the threshold
@@ -384,14 +393,14 @@ export const benchmark_baseline_compare = async (
 		}
 	}
 
-	// Sort regressions and improvements by effect size (largest first)
-	const sort_by_effect_size = (
+	// Sort regressions and improvements by percentage difference (largest first)
+	const sort_by_percent_difference = (
 		a: BenchmarkBaselineTaskComparison,
 		b: BenchmarkBaselineTaskComparison,
-	) => b.comparison.effect_size - a.comparison.effect_size;
+	) => b.comparison.percent_difference - a.comparison.percent_difference;
 
-	regressions.sort(sort_by_effect_size);
-	improvements.sort(sort_by_effect_size);
+	regressions.sort(sort_by_percent_difference);
+	improvements.sort(sort_by_percent_difference);
 
 	return {
 		baseline_found: true,
@@ -411,8 +420,8 @@ export const benchmark_baseline_compare = async (
 /**
  * Format a baseline comparison result as a human-readable string.
  *
- * @param result - Comparison result from benchmark_baseline_compare
- * @returns Formatted string summary
+ * @param result - comparison result from `benchmark_baseline_compare`
+ * @returns formatted string summary
  */
 export const benchmark_baseline_format = (result: BenchmarkBaselineComparisonResult): string => {
 	if (!result.baseline_found) {
@@ -440,8 +449,11 @@ export const benchmark_baseline_format = (result: BenchmarkBaselineComparisonRes
 		lines.push(`Regressions (${result.regressions.length}):`);
 		for (const r of result.regressions) {
 			const ratio = r.comparison.speedup_ratio.toFixed(2);
+			const pct = (r.comparison.percent_difference * 100).toFixed(1);
 			const p = r.comparison.p_value.toFixed(3);
-			lines.push(`  ${r.name}: ${ratio}x slower (p=${p}, ${r.comparison.effect_magnitude})`);
+			lines.push(
+				`  ${r.name}: ${ratio}x slower (${pct}%, p=${p}, ${r.comparison.effect_magnitude})`,
+			);
 		}
 		lines.push('');
 	}
@@ -450,8 +462,11 @@ export const benchmark_baseline_format = (result: BenchmarkBaselineComparisonRes
 		lines.push(`Improvements (${result.improvements.length}):`);
 		for (const r of result.improvements) {
 			const ratio = r.comparison.speedup_ratio.toFixed(2);
+			const pct = (r.comparison.percent_difference * 100).toFixed(1);
 			const p = r.comparison.p_value.toFixed(3);
-			lines.push(`  ${r.name}: ${ratio}x faster (p=${p}, ${r.comparison.effect_magnitude})`);
+			lines.push(
+				`  ${r.name}: ${ratio}x faster (${pct}%, p=${p}, ${r.comparison.effect_magnitude})`,
+			);
 		}
 		lines.push('');
 	}
@@ -491,8 +506,8 @@ export const benchmark_baseline_format = (result: BenchmarkBaselineComparisonRes
 /**
  * Format a baseline comparison result as JSON for programmatic consumption.
  *
- * @param result - Comparison result from benchmark_baseline_compare
- * @param options - Formatting options
+ * @param result - comparison result from `benchmark_baseline_compare`
+ * @param options - formatting options
  * @returns JSON string
  */
 export const benchmark_baseline_format_json = (
@@ -516,6 +531,7 @@ export const benchmark_baseline_format_json = (
 		regressions: result.regressions.map((r) => ({
 			name: r.name,
 			speedup_ratio: r.comparison.speedup_ratio,
+			percent_difference: r.comparison.percent_difference,
 			effect_size: r.comparison.effect_size,
 			effect_magnitude: r.comparison.effect_magnitude,
 			p_value: r.comparison.p_value,
@@ -525,6 +541,7 @@ export const benchmark_baseline_format_json = (
 		improvements: result.improvements.map((r) => ({
 			name: r.name,
 			speedup_ratio: r.comparison.speedup_ratio,
+			percent_difference: r.comparison.percent_difference,
 			effect_size: r.comparison.effect_size,
 			effect_magnitude: r.comparison.effect_magnitude,
 			p_value: r.comparison.p_value,

package/src/lib/benchmark_format.ts

@@ -6,9 +6,9 @@ import {format_number} from './maths.js';
 /**
  * Format results as an ASCII table with percentiles, min/max, and relative performance.
  * All times use the same unit for easy comparison.
- * @param results - Array of benchmark results
- * @param baseline - Optional task name to use as baseline for comparison (defaults to fastest)
- * @returns Formatted table string with enhanced metrics
+ * @param results - array of benchmark results
+ * @param baseline - optional task name to use as baseline for comparison (defaults to fastest)
+ * @returns formatted table string with enhanced metrics
  *
  * @example
  * ```ts
@@ -126,9 +126,9 @@ export const benchmark_format_table = (
 /**
  * Format results as a Markdown table with key metrics.
  * All times use the same unit for easy comparison.
- * @param results - Array of benchmark results
- * @param baseline - Optional task name to use as baseline for comparison (defaults to fastest)
- * @returns Formatted markdown table string
+ * @param results - array of benchmark results
+ * @param baseline - optional task name to use as baseline for comparison (defaults to fastest)
+ * @returns formatted markdown table string
  *
  * @example
  * ```ts
@@ -238,9 +238,9 @@ export const benchmark_format_markdown = (
 
 /**
  * Format results as grouped Markdown tables with headers between groups.
- * @param results - Array of benchmark results
- * @param groups - Array of group definitions
- * @returns Formatted markdown string with group headers and tables
+ * @param results - array of benchmark results
+ * @param groups - array of group definitions
+ * @returns formatted markdown string with group headers and tables
  *
  * @example
  * ```ts
@@ -301,8 +301,8 @@ export interface BenchmarkFormatJsonOptions {
 
 /**
  * Format results as JSON.
- * @param results - Array of benchmark results
- * @param options - Formatting options
+ * @param results - array of benchmark results
+ * @param options - formatting options
  * @returns JSON string
  *
  * @example
@@ -348,9 +348,9 @@ export const benchmark_format_json = (
 
 /**
  * Format results as a grouped table with visual separators between groups.
- * @param results - Array of benchmark results
- * @param groups - Array of group definitions
- * @returns Formatted table string with group separators
+ * @param results - array of benchmark results
+ * @param groups - array of group definitions
+ * @returns formatted table string with group separators
  *
  * @example
  * ```ts
@@ -405,6 +405,6 @@ export const benchmark_format_table_grouped = (
 
 /**
  * Format a number with fixed decimal places and thousands separators.
- * @see {@link format_number} in maths.ts for the underlying implementation.
+ * @see `format_number` in `maths.ts` for the underlying implementation.
  */
 export const benchmark_format_number = format_number;

package/src/lib/benchmark_stats.ts

@@ -1,6 +1,6 @@
 /**
  * Benchmark-specific statistical analysis.
- * Uses the general stats utilities from stats.ts for timing/performance analysis.
+ * Uses the general stats utilities from `stats.ts` for timing/performance analysis.
  * All timing values are in nanoseconds.
  *
  * @module
@@ -44,13 +44,15 @@ export interface BenchmarkComparison {
 	faster: 'a' | 'b' | 'equal';
 	/** How much faster the winner is (e.g., 1.5 means 1.5x faster) */
 	speedup_ratio: number;
-	/** Whether the difference is statistically significant at the given alpha */
+	/** Whether the difference is both statistically and practically significant */
 	significant: boolean;
 	/** P-value from Welch's t-test (lower = more confident the difference is real) */
 	p_value: number;
-	/** Cohen's d effect size (magnitude of difference independent of sample size) */
+	/** Percentage difference between means as a ratio (0.05 = 5%, 1.0 = 100%) */
+	percent_difference: number;
+	/** Cohen's d effect size (informational — not used for classification) */
 	effect_size: number;
-	/** Interpretation of effect size */
+	/** Interpretation of practical significance based on percentage difference */
 	effect_magnitude: EffectMagnitude;
 	/** Whether the 95% confidence intervals overlap */
 	ci_overlap: boolean;
@@ -64,6 +66,20 @@ export interface BenchmarkComparison {
 export interface BenchmarkCompareOptions {
 	/** Significance level for hypothesis testing (default: 0.05) */
 	alpha?: number;
+	/**
+	 * Minimum percentage difference to consider practically meaningful, as a ratio.
+	 * Below this threshold, differences are classified as 'negligible' and
+	 * `significant` is forced to `false`, regardless of p-value.
+	 * This prevents the t-test's oversensitivity at large sample sizes from
+	 * flagging system-level noise (thermal throttle, OS scheduler, cache pressure)
+	 * as meaningful differences.
+	 *
+	 * Effect magnitude thresholds scale from this value:
+	 * negligible < min, small < min*3, medium < min*5, large >= min*5.
+	 *
+	 * Default: 0.10 (10%).
+	 */
+	min_percent_difference?: number;
 }
 
 /**
@@ -181,13 +197,17 @@ export class BenchmarkStats {
 }
 
 /**
- * Compare two benchmark results for statistical significance.
- * Uses Welch's t-test (handles unequal variances) and Cohen's d effect size.
+ * Compare two benchmark results for practical and statistical significance.
+ * Uses percentage difference for effect magnitude classification, with Welch's
+ * t-test for statistical confidence. Cohen's d is computed as an informational
+ * metric but does not drive classification — its thresholds (0.2/0.5/0.8) are
+ * calibrated for social science and produce false positives in benchmarking
+ * where within-run variance is tight.
  *
- * @param a - First benchmark stats (or any object with required properties)
- * @param b - Second benchmark stats (or any object with required properties)
- * @param options - Comparison options
- * @returns Comparison result with significance, effect size, and recommendation
+ * @param a - first benchmark stats (or any object with required properties)
+ * @param b - second benchmark stats (or any object with required properties)
+ * @param options - comparison options
+ * @returns comparison result with significance, effect size, and recommendation
  *
  * @example
  * ```ts
@@ -203,6 +223,7 @@ export const benchmark_stats_compare = (
 	options?: BenchmarkCompareOptions,
 ): BenchmarkComparison => {
 	const alpha = options?.alpha ?? 0.05;
+	const min_pct = options?.min_percent_difference ?? 0.1;
 
 	// Handle edge cases
 	if (a.sample_size === 0 || b.sample_size === 0) {
@@ -211,6 +232,7 @@ export const benchmark_stats_compare = (
 			speedup_ratio: 1,
 			significant: false,
 			p_value: 1,
+			percent_difference: 0,
 			effect_size: 0,
 			effect_magnitude: 'negligible',
 			ci_overlap: true,
@@ -223,6 +245,9 @@ export const benchmark_stats_compare = (
 	const faster: 'a' | 'b' | 'equal' =
 		a.mean_ns < b.mean_ns ? 'a' : a.mean_ns > b.mean_ns ? 'b' : 'equal';
 
+	// Percentage difference relative to the faster mean (always >= 0)
+	const percent_difference = speedup_ratio - 1;
+
 	// Welch's t-test (handles unequal variances)
 	// Special case: if both have zero variance, t-test is undefined
 	let p_value: number;
@@ -242,38 +267,33 @@ export const benchmark_stats_compare = (
 		p_value = stats_t_distribution_p_value(Math.abs(t_statistic), degrees_of_freedom);
 	}
 
-	// Cohen's d effect size
+	// Cohen's d effect size (informational only — not used for classification)
 	const pooled_std_dev = Math.sqrt(
 		((a.sample_size - 1) * a.std_dev_ns ** 2 + (b.sample_size - 1) * b.std_dev_ns ** 2) /
 			(a.sample_size + b.sample_size - 2),
 	);
-
-	// When pooled_std_dev is 0 but means differ, effect is maximal (infinite)
-	// When means are equal, effect is 0
 	let effect_size: number;
-	let effect_magnitude: EffectMagnitude;
-
 	if (pooled_std_dev === 0) {
-		// Zero variance case - if means differ, it's a definitive difference
-		if (a.mean_ns === b.mean_ns) {
-			effect_size = 0;
-			effect_magnitude = 'negligible';
-		} else {
-			// Any difference is 100% reliable when there's no variance
-			effect_size = Infinity;
-			effect_magnitude = 'large';
-		}
+		effect_size = a.mean_ns === b.mean_ns ? 0 : Infinity;
 	} else {
 		effect_size = Math.abs(a.mean_ns - b.mean_ns) / pooled_std_dev;
-		// Interpret effect size (Cohen's conventions)
-		effect_magnitude =
-			effect_size < 0.2
-				? 'negligible'
-				: effect_size < 0.5
-					? 'small'
-					: effect_size < 0.8
-						? 'medium'
-						: 'large';
+	}
+
+	// Effect magnitude based on percentage difference, not Cohen's d.
+	// Cohen's d thresholds (0.2/0.5/0.8) are calibrated for social science, not benchmarking.
+	// Within-run variance is tight, so even small system noise (thermal throttle, OS scheduler)
+	// produces large Cohen's d. Percentage thresholds directly answer "is this difference
+	// meaningful in practice?" Thresholds scale with min_percent_difference so users can
+	// tune one knob for their system's noise floor.
+	let effect_magnitude: EffectMagnitude;
+	if (percent_difference < min_pct) {
+		effect_magnitude = 'negligible';
+	} else if (percent_difference < min_pct * 3) {
+		effect_magnitude = 'small';
+	} else if (percent_difference < min_pct * 5) {
+		effect_magnitude = 'medium';
+	} else {
+		effect_magnitude = 'large';
 	}
 
 	// Check confidence interval overlap
@@ -281,20 +301,21 @@ export const benchmark_stats_compare = (
 		a.confidence_interval_ns[0] <= b.confidence_interval_ns[1] &&
 		b.confidence_interval_ns[0] <= a.confidence_interval_ns[1];
 
-	// Determine significance
-	const significant = p_value < alpha;
+	// Significance requires both statistical significance (p < alpha)
+	// AND practical significance (percent_difference >= min_pct).
+	// With large n, the t-test finds p≈0 for any difference because
+	// SE = std_dev/sqrt(n) → 0. Gating on practical significance
+	// prevents system noise from being flagged as meaningful.
+	const significant = p_value < alpha && percent_difference >= min_pct;
 
 	// Generate recommendation
 	let recommendation: string;
-	if (!significant) {
-		recommendation =
-			effect_magnitude === 'negligible'
-				? 'No meaningful difference detected'
-				: `Difference not statistically significant (p=${p_value.toFixed(3)}), but effect size suggests ${effect_magnitude} practical difference`;
-	} else if (effect_magnitude === 'negligible') {
-		recommendation = `Statistically significant but negligible practical difference (${speedup_ratio.toFixed(2)}x)`;
+	if (percent_difference < min_pct) {
+		recommendation = 'No meaningful difference detected';
+	} else if (!significant) {
+		recommendation = `${(percent_difference * 100).toFixed(1)}% difference observed but not statistically significant (p=${p_value.toFixed(3)})`;
 	} else {
-		recommendation = `${faster === 'a' ? 'First' : 'Second'} is ${speedup_ratio.toFixed(2)}x faster with ${effect_magnitude} effect size (p=${p_value.toFixed(3)})`;
+		recommendation = `${faster === 'a' ? 'First' : 'Second'} is ${speedup_ratio.toFixed(2)}x faster with ${effect_magnitude} effect size (${(percent_difference * 100).toFixed(1)}%, p=${p_value.toFixed(3)})`;
 	}
 
 	// Adjust 'faster' to 'equal' if effect is negligible
@@ -305,6 +326,7 @@ export const benchmark_stats_compare = (
 		speedup_ratio,
 		significant,
 		p_value,
+		percent_difference,
 		effect_size,
 		effect_magnitude,
 		ci_overlap,

package/src/lib/benchmark_types.ts

@@ -41,7 +41,7 @@ export interface BenchmarkConfig {
 
 	/**
 	 * Custom timer to use for measurements.
-	 * Default: timer_default (auto-detects environment)
+	 * Default: `timer_default` (auto-detects environment)
 	 */
 	timer?: Timer;
 
@@ -54,9 +54,9 @@ export interface BenchmarkConfig {
 	 * after the timing capture. However, frequent GC calls will slow overall benchmark
 	 * execution time.
 	 *
-	 * @param task_name - Name of the current task being benchmarked
-	 * @param iteration - Current iteration number (1-indexed)
-	 * @param abort - Call to stop the benchmark early for this task
+	 * @param task_name - name of the current task being benchmarked
+	 * @param iteration - current iteration number (1-indexed)
+	 * @param abort - call to stop the benchmark early for this task
 	 *
 	 * @example
 	 * ```ts
@@ -90,9 +90,9 @@ export interface BenchmarkConfig {
 	 * Callback invoked after each task completes.
 	 * Useful for logging progress during long benchmark runs.
 	 *
-	 * @param result - The completed benchmark result
-	 * @param index - Zero-based index of the completed task
-	 * @param total - Total number of tasks to run
+	 * @param result - the completed benchmark result
+	 * @param index - zero-based index of the completed task
+	 * @param total - total number of tasks to run
 	 *
 	 * @example
 	 * ```ts

package/src/lib/bytes.ts

@@ -10,8 +10,8 @@ const encoder = new TextEncoder();
  * Converts string or binary data to a `Uint8Array`.
  * Strings are UTF-8 encoded. `Uint8Array` inputs are returned as-is.
  *
- * @param data - String or `BufferSource` to convert.
- * @returns `Uint8Array` view of the data.
+ * @param data - string or `BufferSource` to convert
+ * @returns `Uint8Array` view of the data
  */
 export const to_bytes = (data: BufferSource | string): Uint8Array => {
 	if (typeof data === 'string') return encoder.encode(data);
@@ -23,8 +23,8 @@ export const to_bytes = (data: BufferSource | string): Uint8Array => {
 /**
  * Formats a byte count as a human-readable string.
  *
- * @param n - byte count.
- * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`.
+ * @param n - byte count
+ * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`
  */
 export const format_bytes = (n: number): string => {
 	if (n < 1024) return n + ' B';

package/src/lib/dag.ts

@@ -80,8 +80,8 @@ export interface DagResult {
  * eligible to start. Failure cascading and stop-on-failure are handled
  * per the options.
  *
- * @param options - DAG execution options.
- * @returns Aggregated result with per-node details.
+ * @param options - DAG execution options
+ * @returns aggregated result with per-node details
  */
 export const run_dag = async <T extends DagNode>(options: DagOptions<T>): Promise<DagResult> => {
 	const {

package/src/lib/deep_equal.ts

@@ -10,8 +10,8 @@
  * - Promises always return false (cannot be meaningfully compared)
  * - Maps/Sets compare by reference for object keys/values
  *
- * @param a first value to compare
- * @param b second value to compare
+ * @param a - first value to compare
+ * @param b - second value to compare
  * @returns true if deeply equal, false otherwise
  */
 export const deep_equal = (a: unknown, b: unknown): boolean => {

package/src/lib/diff.ts

@@ -15,9 +15,9 @@ export interface DiffLine {
 /**
  * Generate a line-based diff between two strings using LCS algorithm.
  *
- * @param a - The original/current content.
- * @param b - The new/desired content.
- * @returns Array of diff lines with type annotations.
+ * @param a - the original/current content
+ * @param b - the new/desired content
+ * @returns array of diff lines with type annotations
  */
 export const diff_lines = (a: string, b: string): Array<DiffLine> => {
 	const a_lines = a.split('\n');
@@ -94,9 +94,9 @@ const compute_lcs = (a: Array<string>, b: Array<string>): Array<string> => {
 /**
  * Filter diff to only include lines within N lines of context around changes.
  *
- * @param diff - The full diff lines.
- * @param context_lines - Number of context lines to show around changes (default: 3).
- * @returns Filtered diff with ellipsis markers for skipped regions.
+ * @param diff - the full diff lines
+ * @param context_lines - number of context lines to show around changes (default: 3)
+ * @returns filtered diff with ellipsis markers for skipped regions
  */
 export const filter_diff_context = (diff: Array<DiffLine>, context_lines = 3): Array<DiffLine> => {
 	if (diff.length === 0) return [];
@@ -163,11 +163,11 @@ export interface FormatDiffOptions {
 /**
  * Format a diff for display.
  *
- * @param diff - The diff lines to format.
- * @param current_path - Path label for "current" content.
- * @param desired_path - Path label for "desired" content.
- * @param options - Formatting options.
- * @returns Formatted diff string.
+ * @param diff - the diff lines to format
+ * @param current_path - path label for "current" content
+ * @param desired_path - path label for "desired" content
+ * @param options - formatting options
+ * @returns formatted diff string
  */
 export const format_diff = (
 	diff: Array<DiffLine>,
@@ -208,14 +208,14 @@ export const format_diff = (
 /**
  * Generate a formatted diff between two strings.
  *
- * Combines diff_lines, filter_diff_context, and format_diff for convenience.
+ * Combines `diff_lines`, `filter_diff_context`, and `format_diff` for convenience.
  * Returns null if content is binary.
  *
- * @param current - Current content.
- * @param desired - Desired content.
- * @param path - File path for labels.
- * @param options - Formatting options.
- * @returns Formatted diff string, or null if binary.
+ * @param current - current content
+ * @param desired - desired content
+ * @param path - file path for labels
+ * @param options - formatting options
+ * @returns formatted diff string, or null if binary
  */
 export const generate_diff = (
 	current: string,

package/src/lib/dom.ts

@@ -60,11 +60,11 @@ export const is_interactive = (el: any): boolean => {
 
 /**
  * Stops an event from bubbling and doing default behavior.
- * @param event
- * @param immediate defaults to `true` to use `stopImmediatePropagation` over `stopPropagation`
- * @param preventDefault defaults to `true`
+ * @param event - the event to swallow
+ * @param immediate - defaults to `true` to use `stopImmediatePropagation` over `stopPropagation`
+ * @param preventDefault - defaults to `true`
+ * @returns the swallowed event
  * @mutates event - calls preventDefault(), stopPropagation(), or stopImmediatePropagation()
- * @returns
  */
 export const swallow = <
 	T extends Pick<Event, 'preventDefault' | 'stopPropagation' | 'stopImmediatePropagation'>,

package/src/lib/fetch.ts

@@ -34,7 +34,7 @@ export interface FetchValueOptions<TValue, TParams = undefined> {
  *   (you can still provide headers directly)
  *
  * Unlike `fetch`, this throws on ratelimits (status code 429)
- * to halt whatever is happpening in its tracks to avoid accidental abuse,
+ * to halt whatever is happening in its tracks to avoid accidental abuse,
  * but returns a `Result` in all other cases.
  * Handling ratelimit headers with more sophistication gets tricky because behavior
  * differs across services.

package/src/lib/git.ts

@@ -122,7 +122,7 @@ export interface GitWorkspaceStatus {
  * Note: This implementation treats submodules the same as regular files.
  * Submodule-specific status codes (lowercase m, ?) are interpreted as changes.
  *
- * @param stdout - The raw output from `git status --porcelain -z`
+ * @param stdout - the raw output from `git status --porcelain -z`
  * @returns status object with flags for unstaged changes, staged changes, and untracked files
  */
 export const git_parse_workspace_status = (stdout: string | null): GitWorkspaceStatus => {

package/src/lib/hash.ts

@@ -15,9 +15,9 @@ const encoder = new TextEncoder();
 /**
  * Computes a hash using Web Crypto API.
  *
- * @param algorithm - Web Crypto algorithm name (e.g. `'SHA-256'`).
+ * @param algorithm - Web Crypto algorithm name (e.g. `'SHA-256'`)
  * @param data - String or binary data to hash. Strings are UTF-8 encoded.
- * @returns hexadecimal hash string.
+ * @returns hexadecimal hash string
  */
 const hash_webcrypto = async (algorithm: string, data: BufferSource | string): Promise<string> => {
 	const buffer = typeof data === 'string' ? encoder.encode(data) : data;
@@ -29,7 +29,7 @@ const hash_webcrypto = async (algorithm: string, data: BufferSource | string): P
  * Computes a SHA-1 hash using Web Crypto API.
  *
  * @param data - String or binary data to hash. Strings are UTF-8 encoded.
- * @returns 40-character hexadecimal hash string.
+ * @returns 40-character hexadecimal hash string
  */
 export const hash_sha1 = (data: BufferSource | string): Promise<string> =>
 	hash_webcrypto('SHA-1', data);
@@ -38,7 +38,7 @@ export const hash_sha1 = (data: BufferSource | string): Promise<string> =>
  * Computes a SHA-256 hash using Web Crypto API.
  *
  * @param data - String or binary data to hash. Strings are UTF-8 encoded.
- * @returns 64-character hexadecimal hash string.
+ * @returns 64-character hexadecimal hash string
  */
 export const hash_sha256 = (data: BufferSource | string): Promise<string> =>
 	hash_webcrypto('SHA-256', data);
@@ -47,7 +47,7 @@ export const hash_sha256 = (data: BufferSource | string): Promise<string> =>
  * Computes a SHA-384 hash using Web Crypto API.
  *
  * @param data - String or binary data to hash. Strings are UTF-8 encoded.
- * @returns 96-character hexadecimal hash string.
+ * @returns 96-character hexadecimal hash string
  */
 export const hash_sha384 = (data: BufferSource | string): Promise<string> =>
 	hash_webcrypto('SHA-384', data);
@@ -56,7 +56,7 @@ export const hash_sha384 = (data: BufferSource | string): Promise<string> =>
  * Computes a SHA-512 hash using Web Crypto API.
  *
  * @param data - String or binary data to hash. Strings are UTF-8 encoded.
- * @returns 128-character hexadecimal hash string.
+ * @returns 128-character hexadecimal hash string
  */
 export const hash_sha512 = (data: BufferSource | string): Promise<string> =>
 	hash_webcrypto('SHA-512', data);
@@ -68,8 +68,8 @@ export const hash_sha512 = (data: BufferSource | string): Promise<string> =>
  * Note: Strings use UTF-16 code units, buffers use raw bytes.
  * For non-ASCII, `hash_insecure(str) !== hash_insecure(encoder.encode(str))`.
  *
- * @param data - String or binary data to hash.
- * @returns 8-character hex-encoded unsigned 32-bit hash.
+ * @param data - string or binary data to hash
+ * @returns 8-character hex-encoded unsigned 32-bit hash
  */
 export const hash_insecure = (data: BufferSource | string): string => {
 	let hash = 5381; // DJB2 initial value, chosen empirically for good distribution