measure-fn 3.11.1 → 3.11.2

package/index.ts

@@ -3,10 +3,12 @@
 const toAlpha = (num: number): string => {
   let result = '';
   let n = num;
+
   do {
     result = String.fromCharCode(97 + (n % 26)) + result;
     n = Math.floor(n / 26) - 1;
   } while (n >= 0);
+
   return result;
 };
 
@@ -16,29 +18,65 @@ let maxResultLen = 0;
 
 export const safeStringify = (value: unknown, limit?: number): string => {
   const cap = limit ?? maxResultLen;
+
   if (value === undefined) return '';
   if (value === null) return 'null';
-  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-  if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`;
-  if (typeof value === 'symbol') return value.toString();
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+
+  if (typeof value === 'bigint') {
+    return `${value}n`;
+  }
+
+  if (typeof value === 'function') {
+    return `[Function: ${value.name || 'anonymous'}]`;
+  }
+
+  if (typeof value === 'symbol') {
+    return value.toString();
+  }
+
   if (typeof value === 'string') {
-    const q = JSON.stringify(value);
-    if (cap === 0) return q;
-    return q.length > cap ? q.slice(0, cap - 1) + '…"' : q;
+    const quoted = JSON.stringify(value);
+
+    if (cap === 0) {
+      return quoted;
+    }
+
+    return quoted.length > cap ? quoted.slice(0, Math.max(0, cap - 1)) + '…"' : quoted;
   }
+
   try {
-    const seen = new WeakSet();
+    const seen = new WeakSet<object>();
+
     const str = JSON.stringify(value, (_key, val) => {
+      if (typeof val === 'bigint') {
+        return `${val}n`;
+      }
+
+      if (typeof val === 'function') {
+        return `[Function: ${val.name || 'anonymous'}]`;
+      }
+
+      if (typeof val === 'symbol') {
+        return val.toString();
+      }
+
       if (typeof val === 'object' && val !== null) {
         if (seen.has(val)) return '[Circular]';
         seen.add(val);
       }
-      if (typeof val === 'function') return `[Function: ${val.name || 'anonymous'}]`;
-      if (typeof val === 'bigint') return `${val}n`;
+
       return val;
     });
-    if (cap === 0) return str;
-    return str.length > cap ? str.slice(0, cap) + '…' : str;
+
+    if (cap === 0) {
+      return str;
+    }
+
+    return str.length > cap ? str.slice(0, Math.max(0, cap)) + '…' : str;
   } catch {
     return String(value);
   }
@@ -46,26 +84,32 @@ export const safeStringify = (value: unknown, limit?: number): string => {
 
 // ─── Duration Formatting ─────────────────────────────────────────────
 
-const formatDuration = (ms: number): string => {
+export const formatDuration = (ms: number): string => {
   if (ms < 1000) return `${ms.toFixed(2)}ms`;
   if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+
   const mins = Math.floor(ms / 60000);
   const secs = Math.round((ms % 60000) / 1000);
+
   return `${mins}m ${secs}s`;
 };
 
 // ─── Timestamps ──────────────────────────────────────────────────────
 
 let timestamps =
-  typeof process !== 'undefined' && (process.env.MEASURE_TIMESTAMPS === '1' || process.env.MEASURE_TIMESTAMPS === 'true');
+  typeof process !== 'undefined' &&
+  (process.env.MEASURE_TIMESTAMPS === '1' ||
+    process.env.MEASURE_TIMESTAMPS === 'true');
 
 const ts = (): string => {
   if (!timestamps) return '';
+
   const now = new Date();
   const h = String(now.getHours()).padStart(2, '0');
   const m = String(now.getMinutes()).padStart(2, '0');
   const s = String(now.getSeconds()).padStart(2, '0');
   const ms = String(now.getMilliseconds()).padStart(3, '0');
+
   return `[${h}:${m}:${s}.${ms}] `;
 };
 
@@ -84,10 +128,24 @@ export type MeasureEvent = {
   maxResultLength?: number;
 };
 
+export type MeasureAction<T = unknown> =
+  | string
+  | {
+      label: string;
+      budget?: number;
+      timeout?: number;
+      maxResultLength?: number;
+      result?: (value: T) => unknown;
+      meta?: Record<string, unknown>;
+      [key: string]: unknown;
+    };
+
 // ─── Configuration ───────────────────────────────────────────────────
 
 export let silent =
-  typeof process !== 'undefined' && (process.env.MEASURE_SILENT === '1' || process.env.MEASURE_SILENT === 'true');
+  typeof process !== 'undefined' &&
+  (process.env.MEASURE_SILENT === '1' ||
+    process.env.MEASURE_SILENT === 'true');
 
 let dotEndLabel = true;
 let dotChar = '·';
@@ -114,118 +172,233 @@ export const configure = (opts: ConfigureOpts) => {
 
 // ─── Shared Helpers ──────────────────────────────────────────────────
 
-const buildActionLabel = (actionInternal: string | object): string => {
-  return typeof actionInternal === 'object' && actionInternal !== null && 'label' in actionInternal
-    ? String(actionInternal.label)
-    : String(actionInternal);
+const isActionObject = (value: unknown): value is Exclude<MeasureAction, string> => {
+  return typeof value === 'object' && value !== null;
 };
 
-const extractBudget = (actionInternal: string | object): number | undefined => {
-  if (typeof actionInternal !== 'object' || actionInternal === null) return undefined;
-  if ('budget' in actionInternal) return Number((actionInternal as any).budget);
-  return undefined;
+const buildActionLabel = (actionInternal: MeasureAction): string => {
+  if (isActionObject(actionInternal) && 'label' in actionInternal) {
+    return String(actionInternal.label);
+  }
+
+  return String(actionInternal);
 };
 
-const extractTimeout = (actionInternal: string | object): number | undefined => {
-  if (typeof actionInternal !== 'object' || actionInternal === null) return undefined;
-  if ('timeout' in actionInternal) return Number((actionInternal as any).timeout);
-  return undefined;
+const extractBudget = (actionInternal: MeasureAction): number | undefined => {
+  if (!isActionObject(actionInternal)) return undefined;
+  if (!('budget' in actionInternal)) return undefined;
+  if (actionInternal.budget === undefined) return undefined;
+
+  return Number(actionInternal.budget);
 };
 
-const extractMaxResultLength = (actionInternal: string | object): number | undefined => {
-  if (typeof actionInternal !== 'object' || actionInternal === null) return undefined;
-  if ('maxResultLength' in actionInternal) return Number((actionInternal as any).maxResultLength);
-  return undefined;
+const extractTimeout = (actionInternal: MeasureAction): number | undefined => {
+  if (!isActionObject(actionInternal)) return undefined;
+  if (!('timeout' in actionInternal)) return undefined;
+  if (actionInternal.timeout === undefined) return undefined;
+
+  return Number(actionInternal.timeout);
 };
 
-const extractMeta = (actionInternal: string | object): Record<string, unknown> | undefined => {
-  if (typeof actionInternal !== 'object' || actionInternal === null) return undefined;
-  const details = { ...actionInternal };
-  if ('label' in details) delete (details as any).label;
-  if ('budget' in details) delete (details as any).budget;
-  if ('maxResultLength' in details) delete (details as any).maxResultLength;
-  if (Object.keys(details).length === 0) return undefined;
-  return details as Record<string, unknown>;
+const extractMaxResultLength = (actionInternal: MeasureAction): number | undefined => {
+  if (!isActionObject(actionInternal)) return undefined;
+  if (!('maxResultLength' in actionInternal)) return undefined;
+  if (actionInternal.maxResultLength === undefined) return undefined;
+
+  return Number(actionInternal.maxResultLength);
+};
+
+const extractResultMapper = <T>(
+  actionInternal: MeasureAction<T>,
+): ((value: T) => unknown) | undefined => {
+  if (!isActionObject(actionInternal)) return undefined;
+  if (typeof actionInternal.result !== 'function') return undefined;
+
+  return actionInternal.result;
+};
+
+const extractMeta = (actionInternal: MeasureAction): Record<string, unknown> | undefined => {
+  if (!isActionObject(actionInternal)) return undefined;
+
+  const details: Record<string, unknown> = { ...actionInternal };
+
+  delete details.label;
+  delete details.budget;
+  delete details.timeout;
+  delete details.maxResultLength;
+  delete details.result;
+
+  const explicitMeta =
+    typeof details.meta === 'object' && details.meta !== null
+      ? (details.meta as Record<string, unknown>)
+      : undefined;
+
+  delete details.meta;
+
+  const merged = {
+    ...details,
+    ...(explicitMeta ?? {}),
+  };
+
+  if (Object.keys(merged).length === 0) {
+    return undefined;
+  }
+
+  return merged;
 };
 
 const formatMeta = (meta?: Record<string, unknown>): string => {
   if (!meta) return '';
+
   const params = Object.entries(meta)
-    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .map(([key, value]) => `${key}=${safeStringify(value, 0)}`)
     .join(' ');
+
   return ` (${params})`;
 };
 
+const mapResultForLog = <T>(actionInternal: MeasureAction<T>, result: T): unknown => {
+  const mapper = extractResultMapper(actionInternal);
+
+  if (!mapper) {
+    return result;
+  }
+
+  try {
+    return mapper(result);
+  } catch (error) {
+    return {
+      resultMapperError:
+        error instanceof Error ? error.message : String(error),
+    };
+  }
+};
+
 const emit = (event: MeasureEvent, prefix?: string) => {
   if (silent) return;
+
   if (logger) {
     logger(event);
     return;
   }
+
   defaultLogger(event, prefix);
 };
 
-
 const defaultLogger = (event: MeasureEvent, prefix?: string) => {
   const pfx = prefix ? `${prefix}:` : '';
   const id = `[${pfx}${event.id}]`;
   const t = ts();
 
   switch (event.type) {
-    case 'start':
+    case 'start': {
       console.log(`${t}${id} ... ${event.label}${formatMeta(event.meta)}`);
       break;
+    }
+
     case 'success': {
-      const endLabel = dotEndLabel ? dotChar.repeat(event.label.length + 5) : `    ${event.label}`;
-      const resultStr = event.result !== undefined ? safeStringify(event.result, event.maxResultLength) : '';
+      const endLabel = dotEndLabel
+        ? dotChar.repeat(event.label.length + 5)
+        : `    ${event.label}`;
+
+      const resultStr =
+        event.result !== undefined
+          ? safeStringify(event.result, event.maxResultLength)
+          : '';
+
       const arrow = resultStr ? ` → ${resultStr}` : '';
-      const budgetWarn = event.budget && event.duration! > event.budget
-        ? ` ⚠ OVER BUDGET (${formatDuration(event.budget)})`
-        : '';
-      console.log(`${t}${id} ${endLabel} ${formatDuration(event.duration!)}${arrow}${budgetWarn}`);
+
+      const budgetWarn =
+        event.budget && event.duration !== undefined && event.duration > event.budget
+          ? ` ⚠ OVER BUDGET (${formatDuration(event.budget)})`
+          : '';
+
+      console.log(
+        `${t}${id} ${endLabel} ${formatDuration(event.duration ?? 0)}${arrow}${budgetWarn}`,
+      );
+
       break;
     }
+
     case 'error': {
-      // Added + 3 to the repeat count because ' ✗ ' takes up 3 characters, needing 5 total to match ' ... '
-      const endLabel = dotEndLabel ? dotChar.repeat(event.label.length + 3) : `  ${event.label}`;
-      const errorMsg = event.error instanceof Error ? event.error.message : String(event.error);
-      const budgetWarn = event.budget && event.duration! > event.budget
-        ? ` ⚠ OVER BUDGET (${formatDuration(event.budget)})`
-        : '';
-      console.log(`${t}${id} ✗ ${endLabel} ${formatDuration(event.duration!)} (${errorMsg})${budgetWarn}`);
+      const endLabel = dotEndLabel
+        ? dotChar.repeat(event.label.length + 3)
+        : `  ${event.label}`;
+
+      const errorMsg =
+        event.error instanceof Error ? event.error.message : String(event.error);
+
+      const budgetWarn =
+        event.budget && event.duration !== undefined && event.duration > event.budget
+          ? ` ⚠ OVER BUDGET (${formatDuration(event.budget)})`
+          : '';
+
+      console.log(
+        `${t}${id} ✗ ${endLabel} ${formatDuration(event.duration ?? 0)} (${errorMsg})${budgetWarn}`,
+      );
+
       if (event.error instanceof Error) {
         console.error(`${id}`, event.error.stack ?? event.error.message);
+
         if (event.error.cause) {
           console.error(`${id} Cause:`, event.error.cause);
         }
       } else {
         console.error(`${id}`, event.error);
       }
+
       break;
     }
-    case 'annotation':
+
+    case 'annotation': {
       console.log(`${t}${id} = ${event.label}${formatMeta(event.meta)}`);
       break;
+    }
   }
 };
 
 // ─── Types ───────────────────────────────────────────────────────────
 
-
 export type MeasureFn = {
-  <U>(label: string | object, fn: () => Promise<U>): Promise<U | null>;
-  <U>(label: string | object, fn: (m: MeasureFn, ms: MeasureSyncFn) => Promise<U>): Promise<U | null>;
-  <U>(label: string | object, fn: (m: MeasureFn) => Promise<U>): Promise<U | null>;
-  (label: string | object): Promise<null>;
+  <U>(label: MeasureAction<U>, fn: () => Promise<U>): Promise<U | null>;
+
+  <U>(
+    label: MeasureAction<U>,
+    fn: (m: MeasureFn, ms: MeasureSyncFn) => Promise<U>,
+  ): Promise<U | null>;
+
+  <U>(
+    label: MeasureAction<U>,
+    fn: (m: MeasureFn) => Promise<U>,
+  ): Promise<U | null>;
+
+  <U>(
+    label: MeasureAction<U>,
+    fn: () => Promise<U>,
+    onError: (error: unknown) => U | null | Promise<U | null>,
+  ): Promise<U | null>;
+
+  (label: MeasureAction): Promise<null>;
 };
 
 export type MeasureSyncFn = {
-  <U>(label: string | object, fn: () => U): U | null;
-  <U>(label: string | object, fn: (m: MeasureSyncFn) => U): U | null;
-  (label: string | object): null;
+  <U>(label: MeasureAction<U>, fn: () => U): U | null;
+
+  <U>(label: MeasureAction<U>, fn: (m: MeasureSyncFn) => U): U | null;
+
+  <U>(
+    label: MeasureAction<U>,
+    fn: () => U,
+    onError: (error: unknown) => U | null,
+  ): U | null;
+
+  (label: MeasureAction): null;
 };
 
-export type TimedResult<T> = { result: T | null; duration: number };
+export type TimedResult<T> = {
+  result: T | null;
+  duration: number;
+};
 
 export type RetryOpts = {
   attempts?: number;
@@ -244,28 +417,47 @@ const createNestedResolver = (
   fullIdChain: string[],
   childCounterRef: { value: number },
   depth: number,
-  resolver: <U>(fn: any, action: any, chain: (string | number)[], depth: number, onError?: (error: unknown) => any, inheritedMaxLen?: number) => Promise<U | null> | (U | null),
+  resolver: <U>(
+    fn: any,
+    action: MeasureAction<U>,
+    chain: (string | number)[],
+    depth: number,
+    onError?: (error: unknown) => any,
+    inheritedMaxLen?: number,
+  ) => Promise<U | null> | (U | null),
   prefix?: string,
-  inheritedMaxLen?: number
+  inheritedMaxLen?: number,
 ) => {
   return (...args: any[]) => {
-    const label = args[0];
+    const label = args[0] as MeasureAction;
     const fn = args[1];
     const onError = args[2];
 
     if (typeof fn === 'function') {
       const childParentChain = [...fullIdChain, childCounterRef.value++];
-      return resolver(fn, label, childParentChain, depth + 1, typeof onError === 'function' ? onError : undefined, inheritedMaxLen);
-    } else {
-      emit({
+
+      return resolver(
+        fn,
+        label,
+        childParentChain,
+        depth + 1,
+        typeof onError === 'function' ? onError : undefined,
+        inheritedMaxLen,
+      );
+    }
+
+    emit(
+      {
         type: 'annotation',
         id: fullIdChain.join('-'),
         label: buildActionLabel(label),
         depth: depth + 1,
         meta: extractMeta(label),
-      }, prefix);
-      return isAsync ? Promise.resolve(null) : null;
-    }
+      },
+      prefix,
+    );
+
+    return isAsync ? Promise.resolve(null) : null;
   };
 };
 
@@ -281,18 +473,32 @@ export type ScopeOpts = {
   maxResultLength?: number;
 };
 
-const createMeasureImpl = (prefix?: string, counterRef?: { value: number }, scopeOpts?: ScopeOpts) => {
-  const counter = counterRef ?? { get value() { return globalRootCounter; }, set value(v) { globalRootCounter = v; } };
+const createMeasureImpl = (
+  prefix?: string,
+  counterRef?: { value: number },
+  scopeOpts?: ScopeOpts,
+) => {
+  const counter =
+    counterRef ??
+    {
+      get value() {
+        return globalRootCounter;
+      },
+      set value(value: number) {
+        globalRootCounter = value;
+      },
+    };
+
   const scopeMaxLen = scopeOpts?.maxResultLength;
   let _lastError: unknown = null;
 
   const _measureInternal = async <U>(
     fnInternal: (measure: MeasureFn, measureSync: MeasureSyncFn) => Promise<U>,
-    actionInternal: string | object,
+    actionInternal: MeasureAction<U>,
     parentIdChain: (string | number)[],
     depth: number,
-    onError?: (error: unknown) => any,
-    inheritedMaxLen?: number
+    onError?: (error: unknown) => U | null | Promise<U | null>,
+    inheritedMaxLen?: number,
   ): Promise<U | null> => {
     const start = performance.now();
     const childCounterRef = { value: 0 };
@@ -302,316 +508,604 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }, scop
     const localMaxLen = extractMaxResultLength(actionInternal);
     const effectiveMaxLen = localMaxLen ?? inheritedMaxLen;
 
-    const currentId = toAlpha(Number(parentIdChain.pop() ?? 0) as number);
-    const fullIdChain: string[] = [...parentIdChain.map(v => String(v)) as string[], currentId];
+    const currentId = toAlpha(Number(parentIdChain.pop() ?? 0));
+    const fullIdChain: string[] = [
+      ...parentIdChain.map((value) => String(value)),
+      currentId,
+    ];
     const idStr = fullIdChain.join('-');
 
-    emit({
-      type: 'start',
-      id: idStr,
-      label,
+    emit(
+      {
+        type: 'start',
+        id: idStr,
+        label,
+        depth,
+        meta: extractMeta(actionInternal),
+      },
+      prefix,
+    );
+
+    const measureForNextLevel = createNestedResolver(
+      true,
+      fullIdChain,
+      childCounterRef,
       depth,
-      meta: extractMeta(actionInternal),
-    }, prefix);
-
-    const measureForNextLevel = createNestedResolver(true, fullIdChain, childCounterRef, depth, _measureInternal, prefix, effectiveMaxLen);
-    const measureSyncForNextLevel = createNestedResolver(false, fullIdChain, childCounterRef, depth, _measureInternalSync, prefix, effectiveMaxLen);
+      _measureInternal,
+      prefix,
+      effectiveMaxLen,
+    );
+
+    const measureSyncForNextLevel = createNestedResolver(
+      false,
+      fullIdChain,
+      childCounterRef,
+      depth,
+      _measureInternalSync,
+      prefix,
+      effectiveMaxLen,
+    );
 
     try {
       let result: U;
+
       if (timeout && timeout > 0) {
         result = await Promise.race([
-          fnInternal(measureForNextLevel as MeasureFn, measureSyncForNextLevel as MeasureSyncFn),
-          new Promise<never>((_, reject) =>
-            setTimeout(() => reject(new Error(`Timeout (${formatDuration(timeout)})`)), timeout)
+          fnInternal(
+            measureForNextLevel as MeasureFn,
+            measureSyncForNextLevel as MeasureSyncFn,
           ),
+          new Promise<never>((_resolve, reject) => {
+            setTimeout(
+              () => reject(new Error(`Timeout (${formatDuration(timeout)})`)),
+              timeout,
+            );
+          }),
         ]);
       } else {
-        result = await fnInternal(measureForNextLevel as MeasureFn, measureSyncForNextLevel as MeasureSyncFn);
+        result = await fnInternal(
+          measureForNextLevel as MeasureFn,
+          measureSyncForNextLevel as MeasureSyncFn,
+        );
       }
+
       const duration = performance.now() - start;
-      emit({ type: 'success', id: idStr, label, depth, duration, result, budget, maxResultLength: effectiveMaxLen }, prefix);
+
+      emit(
+        {
+          type: 'success',
+          id: idStr,
+          label,
+          depth,
+          duration,
+          result: mapResultForLog(actionInternal, result),
+          budget,
+          maxResultLength: effectiveMaxLen,
+        },
+        prefix,
+      );
+
       return result;
     } catch (error) {
       const duration = performance.now() - start;
-      emit({ type: 'error', id: idStr, label, depth, duration, error, budget, maxResultLength: effectiveMaxLen }, prefix);
+
+      emit(
+        {
+          type: 'error',
+          id: idStr,
+          label,
+          depth,
+          duration,
+          error,
+          budget,
+          maxResultLength: effectiveMaxLen,
+        },
+        prefix,
+      );
+
       _lastError = error;
+
       if (onError) {
         try {
-          return onError(error);
+          return await onError(error);
         } catch (onErrorError) {
-          emit({ type: 'error', id: idStr, label: `${label} (onError)`, depth, duration: performance.now() - start, error: onErrorError, budget, maxResultLength: effectiveMaxLen }, prefix);
+          emit(
+            {
+              type: 'error',
+              id: idStr,
+              label: `${label} (onError)`,
+              depth,
+              duration: performance.now() - start,
+              error: onErrorError,
+              budget,
+              maxResultLength: effectiveMaxLen,
+            },
+            prefix,
+          );
+
           _lastError = onErrorError;
           return null;
         }
       }
+
       return null;
     }
   };
 
   const _measureInternalSync = <U>(
     fnInternal: (measure: MeasureSyncFn) => U,
-    actionInternal: string | object,
+    actionInternal: MeasureAction<U>,
     parentIdChain: (string | number)[],
     depth: number,
-    _onError?: ((error: unknown) => any) | undefined,
-    inheritedMaxLen?: number
+    onError?: (error: unknown) => U | null,
+    inheritedMaxLen?: number,
   ): U | null => {
     const start = performance.now();
     const childCounterRef = { value: 0 };
     const label = buildActionLabel(actionInternal);
-    const hasNested = fnInternal.length > 0;
     const budget = extractBudget(actionInternal);
     const localMaxLen = extractMaxResultLength(actionInternal);
     const effectiveMaxLen = localMaxLen ?? inheritedMaxLen;
 
-    const currentId = toAlpha(Number(parentIdChain.pop() ?? 0) as number);
-    const fullIdChain: string[] = [...parentIdChain.map(v => String(v)) as string[], currentId];
+    const currentId = toAlpha(Number(parentIdChain.pop() ?? 0));
+    const fullIdChain: string[] = [
+      ...parentIdChain.map((value) => String(value)),
+      currentId,
+    ];
     const idStr = fullIdChain.join('-');
 
-    if (hasNested) {
-      emit({
+    emit(
+      {
         type: 'start',
         id: idStr,
         label,
         depth,
         meta: extractMeta(actionInternal),
-      }, prefix);
-    }
-
-    const measureForNextLevel = createNestedResolver(false, fullIdChain, childCounterRef, depth, _measureInternalSync, prefix, effectiveMaxLen);
+      },
+      prefix,
+    );
+
+    const measureForNextLevel = createNestedResolver(
+      false,
+      fullIdChain,
+      childCounterRef,
+      depth,
+      _measureInternalSync,
+      prefix,
+      effectiveMaxLen,
+    );
 
     try {
       const result = fnInternal(measureForNextLevel as MeasureSyncFn);
       const duration = performance.now() - start;
-      emit({ type: 'success', id: idStr, label, depth, duration, result, budget, maxResultLength: effectiveMaxLen }, prefix);
+
+      emit(
+        {
+          type: 'success',
+          id: idStr,
+          label,
+          depth,
+          duration,
+          result: mapResultForLog(actionInternal, result),
+          budget,
+          maxResultLength: effectiveMaxLen,
+        },
+        prefix,
+      );
+
       return result;
     } catch (error) {
       const duration = performance.now() - start;
-      emit({ type: 'error', id: idStr, label, depth, duration, error, budget, maxResultLength: effectiveMaxLen }, prefix);
+
+      emit(
+        {
+          type: 'error',
+          id: idStr,
+          label,
+          depth,
+          duration,
+          error,
+          budget,
+          maxResultLength: effectiveMaxLen,
+        },
+        prefix,
+      );
+
       _lastError = error;
+
+      if (onError) {
+        try {
+          return onError(error);
+        } catch (onErrorError) {
+          emit(
+            {
+              type: 'error',
+              id: idStr,
+              label: `${label} (onError)`,
+              depth,
+              duration: performance.now() - start,
+              error: onErrorError,
+              budget,
+              maxResultLength: effectiveMaxLen,
+            },
+            prefix,
+          );
+
+          _lastError = onErrorError;
+          return null;
+        }
+      }
+
       return null;
     }
   };
 
-  // ─── measure (async) ───────────────────────────────────────────
+  // ─── measure Async ─────────────────────────────────────────────
 
   const measureFn = async <T = null>(
-    arg1: string | object,
-    arg2?: ((measure: MeasureFn, measureSync: MeasureSyncFn) => Promise<T>) | ((measure: MeasureFn) => T),
-    arg3?: (error: unknown) => any
+    arg1: MeasureAction<T>,
+    arg2?:
+      | ((measure: MeasureFn, measureSync: MeasureSyncFn) => Promise<T>)
+      | ((measure: MeasureFn) => Promise<T>)
+      | (() => Promise<T>),
+    arg3?: (error: unknown) => T | null | Promise<T | null>,
   ): Promise<T | null> => {
     if (typeof arg2 === 'function') {
-      return _measureInternal(arg2 as any, arg1, [counter.value++], 0, arg3, scopeMaxLen) as Promise<T | null>;
-    } else {
-      const currentId = toAlpha(counter.value++);
-      emit({
+      return _measureInternal(
+        arg2 as any,
+        arg1,
+        [counter.value++],
+        0,
+        arg3,
+        scopeMaxLen,
+      ) as Promise<T | null>;
+    }
+
+    const currentId = toAlpha(counter.value++);
+
+    emit(
+      {
         type: 'annotation',
         id: currentId,
         label: buildActionLabel(arg1),
         depth: 0,
         meta: extractMeta(arg1),
-      }, prefix);
-      return Promise.resolve(null);
-    }
+      },
+      prefix,
+    );
+
+    return Promise.resolve(null);
   };
 
   measureFn.timed = async <T = null>(
-    arg1: string | object,
-    arg2?: ((measure: MeasureFn) => Promise<T>)
+    arg1: MeasureAction<T>,
+    arg2?: ((measure: MeasureFn) => Promise<T>) | (() => Promise<T>),
   ): Promise<TimedResult<T>> => {
     const start = performance.now();
-    const result = await measureFn(arg1, arg2);
+    const result = await measureFn(arg1, arg2 as any);
     const duration = performance.now() - start;
-    return { result, duration };
+
+    return {
+      result,
+      duration,
+    };
   };
 
   measureFn.retry = async <T = null>(
-    label: string | object,
+    label: MeasureAction<T>,
     opts: RetryOpts,
-    fn: () => Promise<T>
+    fn: () => Promise<T>,
   ): Promise<T | null> => {
     const attempts = opts.attempts ?? 3;
     const delay = opts.delay ?? 1000;
     const backoff = opts.backoff ?? 1;
     const lbl = buildActionLabel(label);
     const budget = extractBudget(label);
+    const effectiveMaxLen = extractMaxResultLength(label) ?? scopeMaxLen;
 
-    for (let i = 0; i < attempts; i++) {
+    for (let i = 0; i < attempts; i += 1) {
       const attempt = i + 1;
       const attemptLabel = `${lbl} [${attempt}/${attempts}]`;
       const start = performance.now();
       const currentId = toAlpha(counter.value++);
 
-      emit({
-        type: 'start',
-        id: currentId,
-        label: attemptLabel,
-        depth: 0,
-        meta: extractMeta(label),
-      }, prefix);
+      emit(
+        {
+          type: 'start',
+          id: currentId,
+          label: attemptLabel,
+          depth: 0,
+          meta: extractMeta(label),
+        },
+        prefix,
+      );
 
       try {
         const result = await fn();
         const duration = performance.now() - start;
-        emit({ type: 'success', id: currentId, label: attemptLabel, depth: 0, duration, result, budget }, prefix);
+
+        emit(
+          {
+            type: 'success',
+            id: currentId,
+            label: attemptLabel,
+            depth: 0,
+            duration,
+            result: mapResultForLog(label, result),
+            budget,
+            maxResultLength: effectiveMaxLen,
+          },
+          prefix,
+        );
+
         return result;
       } catch (error) {
         const duration = performance.now() - start;
-        emit({ type: 'error', id: currentId, label: attemptLabel, depth: 0, duration, error, budget }, prefix);
+
+        emit(
+          {
+            type: 'error',
+            id: currentId,
+            label: attemptLabel,
+            depth: 0,
+            duration,
+            error,
+            budget,
+            maxResultLength: effectiveMaxLen,
+          },
+          prefix,
+        );
+
+        _lastError = error;
+
         if (attempt < attempts) {
-          await new Promise(r => setTimeout(r, delay * Math.pow(backoff, i)));
+          await new Promise((resolve) => {
+            setTimeout(resolve, delay * Math.pow(backoff, i));
+          });
         }
       }
     }
+
     return null;
   };
 
   measureFn.assert = async <T>(
-    arg1: string | object,
-    arg2: ((measure: MeasureFn) => Promise<T>) | (() => Promise<T>)
+    arg1: MeasureAction<T>,
+    arg2: ((measure: MeasureFn) => Promise<T>) | (() => Promise<T>),
   ): Promise<T> => {
     const result = await measureFn(arg1, arg2 as any);
+
     if (result === null) {
       const cause = _lastError;
       _lastError = null;
-      throw new Error(`measure.assert: "${buildActionLabel(arg1)}" failed`, { cause });
+
+      throw new Error(`measure.assert: "${buildActionLabel(arg1)}" failed`, {
+        cause,
+      });
     }
+
     return result;
   };
 
   measureFn.wrap = <A extends any[], R>(
-    label: string | object,
-    fn: (...args: A) => Promise<R>
+    label: MeasureAction<R>,
+    fn: (...args: A) => Promise<R>,
   ): ((...args: A) => Promise<R | null>) => {
     return (...args: A) => measureFn(label, () => fn(...args));
   };
 
   measureFn.batch = async <T, R>(
-    label: string | object,
+    label: MeasureAction<R>,
     items: T[],
     fn: (item: T, index: number) => Promise<R>,
-    opts?: BatchOpts
+    opts?: BatchOpts,
   ): Promise<(R | null)[]> => {
     const lbl = buildActionLabel(label);
     const total = items.length;
     const every = opts?.every ?? Math.max(1, Math.ceil(total / 5));
     const currentId = toAlpha(counter.value++);
     const startTime = performance.now();
+    const budget = extractBudget(label);
 
-    emit({
-      type: 'start',
-      id: currentId,
-      label: `${lbl} (${total} items)`,
-      depth: 0,
-      meta: extractMeta(label),
-    }, prefix);
+    emit(
+      {
+        type: 'start',
+        id: currentId,
+        label: `${lbl} (${total} items)`,
+        depth: 0,
+        meta: extractMeta(label),
+      },
+      prefix,
+    );
 
     const results: (R | null)[] = [];
-    for (let i = 0; i < items.length; i++) {
+
+    for (let i = 0; i < items.length; i += 1) {
       try {
         results.push(await fn(items[i]!, i));
-      } catch {
+      } catch (error) {
+        _lastError = error;
         results.push(null);
       }
+
       if ((i + 1) % every === 0 && i + 1 < total) {
         const elapsed = (performance.now() - startTime) / 1000;
         const rate = ((i + 1) / elapsed).toFixed(0);
-        emit({
-          type: 'annotation',
-          id: currentId,
-          label: `${i + 1}/${total} (${elapsed.toFixed(1)}s, ${rate}/s)`,
-          depth: 0,
-        }, prefix);
+
+        emit(
+          {
+            type: 'annotation',
+            id: currentId,
+            label: `${i + 1}/${total} (${elapsed.toFixed(1)}s, ${rate}/s)`,
+            depth: 0,
+          },
+          prefix,
+        );
       }
     }
 
     const duration = performance.now() - startTime;
-    const budget = extractBudget(label);
-    emit({
-      type: 'success',
-      id: currentId,
-      label: `${lbl} (${total} items)`,
-      depth: 0,
-      duration,
-      result: `${results.filter(r => r !== null).length}/${total} ok`,
-      budget,
-    }, prefix);
+    const okCount = results.filter((result) => result !== null).length;
+
+    emit(
+      {
+        type: 'success',
+        id: currentId,
+        label: `${lbl} (${total} items)`,
+        depth: 0,
+        duration,
+        result: `${okCount}/${total} ok`,
+        budget,
+      },
+      prefix,
+    );
+
     return results;
   };
 
   // ─── measureSync ───────────────────────────────────────────────
 
   const measureSyncFn = <T = null>(
-    arg1: string | object,
-    arg2?: ((measure: MeasureSyncFn) => T)
+    arg1: MeasureAction<T>,
+    arg2?: ((measure: MeasureSyncFn) => T) | (() => T),
+    arg3?: (error: unknown) => T | null,
   ): T | null => {
     if (typeof arg2 === 'function') {
-      return _measureInternalSync(arg2, arg1, [counter.value++], 0, undefined, scopeMaxLen) as T | null;
-    } else {
-      const currentId = toAlpha(counter.value++);
-      emit({
+      return _measureInternalSync(
+        arg2 as any,
+        arg1,
+        [counter.value++],
+        0,
+        arg3,
+        scopeMaxLen,
+      ) as T | null;
+    }
+
+    const currentId = toAlpha(counter.value++);
+
+    emit(
+      {
         type: 'annotation',
         id: currentId,
         label: buildActionLabel(arg1),
         depth: 0,
         meta: extractMeta(arg1),
-      }, prefix);
-      return null;
-    }
+      },
+      prefix,
+    );
+
+    return null;
   };
 
   measureSyncFn.timed = <T = null>(
-    arg1: string | object,
-    arg2?: ((measure: MeasureSyncFn) => T)
+    arg1: MeasureAction<T>,
+    arg2?: ((measure: MeasureSyncFn) => T) | (() => T),
   ): TimedResult<T> => {
     const start = performance.now();
-    const result = measureSyncFn(arg1, arg2);
+    const result = measureSyncFn(arg1, arg2 as any);
     const duration = performance.now() - start;
-    return { result, duration };
+
+    return {
+      result,
+      duration,
+    };
   };
 
   measureSyncFn.assert = <T>(
-    arg1: string | object,
-    arg2: ((measure: MeasureSyncFn) => T) | (() => T)
+    arg1: MeasureAction<T>,
+    arg2: ((measure: MeasureSyncFn) => T) | (() => T),
   ): T => {
     const result = measureSyncFn(arg1, arg2 as any);
+
     if (result === null) {
       const cause = _lastError;
       _lastError = null;
-      throw new Error(`measureSync.assert: "${buildActionLabel(arg1)}" failed`, { cause });
+
+      throw new Error(`measureSync.assert: "${buildActionLabel(arg1)}" failed`, {
+        cause,
+      });
     }
+
     return result;
   };
 
   measureSyncFn.wrap = <A extends any[], R>(
-    label: string | object,
-    fn: (...args: A) => R
+    label: MeasureAction<R>,
+    fn: (...args: A) => R,
   ): ((...args: A) => R | null) => {
     return (...args: A) => measureSyncFn(label, () => fn(...args));
   };
 
-  return { measure: measureFn, measureSync: measureSyncFn };
+  return {
+    measure: measureFn as MeasureFn & {
+      timed: <T = null>(
+        arg1: MeasureAction<T>,
+        arg2?: ((measure: MeasureFn) => Promise<T>) | (() => Promise<T>),
+      ) => Promise<TimedResult<T>>;
+
+      retry: <T = null>(
+        label: MeasureAction<T>,
+        opts: RetryOpts,
+        fn: () => Promise<T>,
+      ) => Promise<T | null>;
+
+      assert: <T>(
+        arg1: MeasureAction<T>,
+        arg2: ((measure: MeasureFn) => Promise<T>) | (() => Promise<T>),
+      ) => Promise<T>;
+
+      wrap: <A extends any[], R>(
+        label: MeasureAction<R>,
+        fn: (...args: A) => Promise<R>,
+      ) => (...args: A) => Promise<R | null>;
+
+      batch: <T, R>(
+        label: MeasureAction<R>,
+        items: T[],
+        fn: (item: T, index: number) => Promise<R>,
+        opts?: BatchOpts,
+      ) => Promise<(R | null)[]>;
+    },
+
+    measureSync: measureSyncFn as MeasureSyncFn & {
+      timed: <T = null>(
+        arg1: MeasureAction<T>,
+        arg2?: ((measure: MeasureSyncFn) => T) | (() => T),
+      ) => TimedResult<T>;
+
+      assert: <T>(
+        arg1: MeasureAction<T>,
+        arg2: ((measure: MeasureSyncFn) => T) | (() => T),
+      ) => T;
+
+      wrap: <A extends any[], R>(
+        label: MeasureAction<R>,
+        fn: (...args: A) => R,
+      ) => (...args: A) => R | null;
+    },
+  };
 };
 
-// ─── Default (global) instance ───────────────────────────────────────
+// ─── Default Global Instance ─────────────────────────────────────────
 
 const globalInstance = createMeasureImpl();
 
 export const measure = globalInstance.measure;
 export const measureSync = globalInstance.measureSync;
 
-// ─── Scoped instances ────────────────────────────────────────────────
+// ─── Scoped Instances ────────────────────────────────────────────────
 
 export const createMeasure = (scopePrefix: string, opts?: ScopeOpts) => {
-  const scopeCounter = { value: 0 };
+  const scopeCounter = {
+    value: 0,
+  };
+
   const scoped = createMeasureImpl(scopePrefix, scopeCounter, opts);
+
   return {
     ...scoped,
-    resetCounter: () => { scopeCounter.value = 0; },
+    resetCounter: () => {
+      scopeCounter.value = 0;
+    },
   };
 };
-
-// ─── Utility exports ─────────────────────────────────────────────────
-
-export { formatDuration };

package/package.json

@@ -3,7 +3,7 @@
   "module": "index.ts",
   "main": "./index.ts",
   "types": "./index.ts",
-  "version": "3.11.1",
+  "version": "3.11.2",
   "type": "module",
   "private": false,
   "description": "Zero-dependency function performance measurement with hierarchical logging",