@fuzdev/fuz_util 0.55.0 → 0.56.0

package/src/lib/testing.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared test assertions for the `@fuzdev` ecosystem.
+ *
+ * Extends the fuz-stack testing conventions (`assert` from vitest, tests in `src/test/`,
+ * plain object mocks) with reusable helpers for patterns that appear across multiple repos.
+ * Only depends on vitest — safe for fuz_util's zero-runtime-deps constraint.
+ *
+ * @module
+ */
+
+import {assert, vi} from 'vitest';
+
+import type {Logger} from './log.js';
+
+/**
+ * Asserts that `fn` rejects with an `Error`.
+ * Optionally matches the error message against `pattern`.
+ * Returns the caught `Error` for further assertions by the caller.
+ *
+ * `assert.fail` is placed after the catch block so that assertion failures
+ * from the test itself are not swallowed by the catch.
+ *
+ * @param fn - async function expected to reject
+ * @param pattern - optional regex to match against the error message
+ * @returns the caught `Error`
+ */
+export const assert_rejects = async (
+	fn: () => Promise<unknown>,
+	pattern?: RegExp,
+): Promise<Error> => {
+	try {
+		await fn();
+	} catch (err) {
+		assert(err instanceof Error, 'Expected rejection to be an Error');
+		if (pattern) {
+			assert.match(err.message, pattern);
+		}
+		return err;
+	}
+	assert.fail('Expected to throw');
+};
+
+/**
+ * A mock `Logger` with `vi.fn()` methods and call tracking arrays.
+ * Assignable to `Logger` for use in code under test.
+ * Each tracking array captures the first argument of each call.
+ * For full call details, use `vi.fn()` introspection on the methods directly.
+ */
+export type MockLogger = Logger & {
+	error_calls: Array<unknown>;
+	warn_calls: Array<unknown>;
+	info_calls: Array<unknown>;
+	debug_calls: Array<unknown>;
+};
+
+/**
+ * Creates a mock `Logger` with `vi.fn()` on each logging method
+ * and tracking arrays for inspecting logged messages.
+ * Follows the fuz-stack convention of plain object mocks over mocking libraries.
+ *
+ * @returns a `MockLogger` assignable to `Logger`
+ */
+export const create_mock_logger = (): MockLogger => {
+	const error_calls: Array<unknown> = [];
+	const warn_calls: Array<unknown> = [];
+	const info_calls: Array<unknown> = [];
+	const debug_calls: Array<unknown> = [];
+
+	return {
+		error: vi.fn((msg: unknown) => error_calls.push(msg)),
+		warn: vi.fn((msg: unknown) => warn_calls.push(msg)),
+		info: vi.fn((msg: unknown) => info_calls.push(msg)),
+		debug: vi.fn((msg: unknown) => debug_calls.push(msg)),
+		raw: vi.fn(),
+		error_calls,
+		warn_calls,
+		info_calls,
+		debug_calls,
+	} as unknown as MockLogger;
+};

package/src/lib/time.ts

@@ -120,8 +120,8 @@ export const TIME_UNIT_DISPLAY: Record<TimeUnit, string> = {ns: 'ns', us: 'μs',
 /**
  * Detect the best time unit for a set of nanosecond values.
  * Chooses the unit where most values fall in the range 1-9999.
- * @param values_ns - Array of times in nanoseconds
- * @returns Best unit to use for all values
+ * @param values_ns - array of times in nanoseconds
+ * @returns best unit to use for all values
  */
 export const time_unit_detect_best = (values_ns: Array<number>): TimeUnit => {
 	if (values_ns.length === 0) return 'ms';
@@ -148,10 +148,10 @@ export const time_unit_detect_best = (values_ns: Array<number>): TimeUnit => {
 
 /**
  * Format time with a specific unit.
- * @param ns - Time in nanoseconds
- * @param unit - Unit to use ('ns', 'us', 'ms', 's')
- * @param decimals - Number of decimal places (default: 2)
- * @returns Formatted string like "3.87μs"
+ * @param ns - time in nanoseconds
+ * @param unit - unit to use ('ns', 'us', 'ms', 's')
+ * @param decimals - number of decimal places (default: 2)
+ * @returns formatted string like "3.87μs"
  */
 export const time_format = (ns: number, unit: TimeUnit, decimals: number = 2): string => {
 	if (!isFinite(ns)) return String(ns);
@@ -170,9 +170,9 @@ export const time_format = (ns: number, unit: TimeUnit, decimals: number = 2): s
 
 /**
  * Format time with adaptive units (ns/μs/ms/s) based on magnitude.
- * @param ns - Time in nanoseconds
- * @param decimals - Number of decimal places (default: 2)
- * @returns Formatted string like "3.87μs" or "1.23ms"
+ * @param ns - time in nanoseconds
+ * @param decimals - number of decimal places (default: 2)
+ * @returns formatted string like "3.87μs" or "1.23ms"
  *
  * @example
  * ```ts
@@ -216,9 +216,9 @@ export interface TimeResult {
 
 /**
  * Time an asynchronous function execution.
- * @param fn - Async function to time
- * @param timer - Timer to use (defaults to timer_default)
- * @returns Object containing the function result and timing information
+ * @param fn - async function to time
+ * @param timer - timer to use (defaults to `timer_default`)
+ * @returns object containing the function result and timing information
  *
  * @example
  * ```ts
@@ -252,9 +252,9 @@ export const time_async = async <T>(
 
 /**
  * Time a synchronous function execution.
- * @param fn - Sync function to time
- * @param timer - Timer to use (defaults to timer_default)
- * @returns Object containing the function result and timing information
+ * @param fn - sync function to time
+ * @param timer - timer to use (defaults to `timer_default`)
+ * @returns object containing the function result and timing information
  *
  * @example
  * ```ts
@@ -287,10 +287,10 @@ export const time_sync = <T>(
 
 /**
  * Measure multiple executions of a function and return all timings.
- * @param fn - Function to measure (sync or async)
- * @param iterations - Number of times to execute
- * @param timer - Timer to use (defaults to timer_default)
- * @returns Array of elapsed times in nanoseconds
+ * @param fn - function to measure (sync or async)
+ * @param iterations - number of times to execute
+ * @param timer - timer to use (defaults to `timer_default`)
+ * @returns array of elapsed times in nanoseconds
  *
  * @example
  * ```ts

package/src/lib/zod.ts

@@ -16,8 +16,8 @@ import type {z} from 'zod';
 /**
  * Unwrap nested schema types (optional, default, nullable, etc).
  *
- * @param def - Zod type definition to unwrap.
- * @returns Inner schema if wrapped, undefined otherwise.
+ * @param def - Zod type definition to unwrap
+ * @returns inner schema if wrapped, undefined otherwise
  */
 export const zod_to_subschema = (def: z.core.$ZodTypeDef): z.ZodType | undefined => {
 	if ('innerType' in def) {
@@ -48,7 +48,7 @@ export const ZOD_WRAPPER_TYPES = new Set([
  * @returns the innermost non-wrapper type definition
  */
 export const zod_unwrap_def = (schema: z.ZodType): z.core.$ZodTypeDef => {
-	const def = schema._zod.def;
+	const {def} = schema;
 	if (ZOD_WRAPPER_TYPES.has(def.type)) {
 		const sub = zod_to_subschema(def);
 		if (sub) return zod_unwrap_def(sub);
@@ -69,7 +69,7 @@ export const zod_get_base_type = (schema: z.ZodType): string => zod_unwrap_def(s
  *
  * @param schema - Zod schema to check
  */
-export const zod_is_optional = (schema: z.ZodType): boolean => schema._zod.def.type === 'optional';
+export const zod_is_optional = (schema: z.ZodType): boolean => schema.def.type === 'optional';
 
 /**
  * Check if a schema accepts null at any wrapping level.
@@ -77,7 +77,7 @@ export const zod_is_optional = (schema: z.ZodType): boolean => schema._zod.def.t
  * @param schema - Zod schema to check
  */
 export const zod_is_nullable = (schema: z.ZodType): boolean => {
-	const def = schema._zod.def;
+	const {def} = schema;
 	if (def.type === 'nullable') return true;
 	if (ZOD_WRAPPER_TYPES.has(def.type)) {
 		const sub = zod_to_subschema(def);
@@ -95,7 +95,7 @@ export const zod_is_nullable = (schema: z.ZodType): boolean => {
  * @param schema - Zod schema to check
  */
 export const zod_has_default = (schema: z.ZodType): boolean => {
-	const def = schema._zod.def;
+	const {def} = schema;
 	if ('defaultValue' in def) return true;
 	const sub = zod_to_subschema(def);
 	if (sub) return zod_has_default(sub);
@@ -113,8 +113,8 @@ export const zod_unwrap_to_object = (schema: z.ZodType): z.ZodObject | null => {
 	const def = zod_unwrap_def(schema);
 	if (def.type !== 'object') return null;
 	let s: z.ZodType = schema;
-	while (s._zod.def.type !== 'object') {
-		const sub = zod_to_subschema(s._zod.def);
+	while (s.def.type !== 'object') {
+		const sub = zod_to_subschema(s.def);
 		if (!sub) return null;
 		s = sub;
 	}
@@ -158,8 +158,8 @@ export const zod_extract_fields = (schema: z.ZodObject): Array<ZodFieldInfo> =>
 /**
  * Get the description from a schema's metadata, unwrapping if needed.
  *
- * @param schema - Zod schema to extract description from.
- * @returns Description string or null if not found.
+ * @param schema - Zod schema to extract description from
+ * @returns description string or null if not found
  */
 export const zod_to_schema_description = (schema: z.ZodType): string | null => {
 	const meta = schema.meta();
@@ -176,11 +176,11 @@ export const zod_to_schema_description = (schema: z.ZodType): string | null => {
 /**
  * Get the default value from a schema, unwrapping if needed.
  *
- * @param schema - Zod schema to extract default from.
- * @returns Default value or undefined.
+ * @param schema - Zod schema to extract default from
+ * @returns default value or undefined
  */
 export const zod_to_schema_default = (schema: z.ZodType): unknown => {
-	const {def} = schema._zod;
+	const {def} = schema;
 	if ('defaultValue' in def) {
 		return def.defaultValue;
 	}
@@ -194,8 +194,8 @@ export const zod_to_schema_default = (schema: z.ZodType): unknown => {
 /**
  * Get aliases from a schema's metadata, unwrapping if needed.
  *
- * @param schema - Zod schema to extract aliases from.
- * @returns Array of alias strings.
+ * @param schema - Zod schema to extract aliases from
+ * @returns array of alias strings
  */
 export const zod_to_schema_aliases = (schema: z.ZodType): Array<string> => {
 	const meta = schema.meta();
@@ -212,11 +212,11 @@ export const zod_to_schema_aliases = (schema: z.ZodType): Array<string> => {
 /**
  * Get the type string for a schema, suitable for display.
  *
- * @param schema - Zod schema to get type string for.
- * @returns Human-readable type string.
+ * @param schema - Zod schema to get type string for
+ * @returns human-readable type string
  */
 export const zod_to_schema_type_string = (schema: z.ZodType): string => {
-	const {def} = schema._zod;
+	const {def} = schema;
 	switch (def.type) {
 		case 'string':
 			return 'string';
@@ -264,8 +264,8 @@ export const zod_to_schema_type_string = (schema: z.ZodType): string => {
 /**
  * Format a value for display in help text.
  *
- * @param value - Value to format.
- * @returns Formatted string representation.
+ * @param value - value to format
+ * @returns formatted string representation
  */
 export const zod_format_value = (value: unknown): string => {
 	if (value === undefined) return '';
@@ -295,8 +295,8 @@ export interface ZodSchemaProperty {
 /**
  * Extract properties from a Zod object schema.
  *
- * @param schema - Zod object schema to extract from.
- * @returns Array of property definitions.
+ * @param schema - Zod object schema to extract from
+ * @returns array of property definitions
  */
 export const zod_to_schema_properties = (schema: z.ZodType): Array<ZodSchemaProperty> => {
 	const {def} = schema;
@@ -326,8 +326,8 @@ export const zod_to_schema_properties = (schema: z.ZodType): Array<ZodSchemaProp
 /**
  * Get all property names and their aliases from an object schema.
  *
- * @param schema - Zod object schema.
- * @returns Set of all names and aliases.
+ * @param schema - Zod object schema
+ * @returns set of all names and aliases
  */
 export const zod_to_schema_names_with_aliases = (schema: z.ZodType): Set<string> => {
 	const names: Set<string> = new Set();