/**
 * @file Recording-side helpers — `perfTimer` (returns a stop() closure),
 *   `measure` / `measureSync` (timed wrappers around an async / sync function),
 *   `perfCheckpoint` (zero-duration marker), and `trackMemory` (records
 *   heap-used at a label). All push rows into the shared metrics array when
 *   `isPerfEnabled()` is true.
 */
/**
 * Measure execution time of an async function.
 *
 * @example
 *   import { measure } from '@socketsecurity/lib/perf/timer'
 *
 *   const { result, duration } = await measure('fetch-packages', async () => {
 *     return await fetchPackages()
 *   })
 *   console.log(`Fetched packages in ${duration}ms`)
 *
 * @param operation - Name of the operation.
 * @param fn - Async function to measure.
 * @param metadata - Optional metadata.
 *
 * @returns Result of the function and duration
 */
export declare function measure<T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<{
    result: T;
    duration: number;
}>;
/**
 * Measure synchronous function execution time.
 *
 * @example
 *   import { measureSync } from '@socketsecurity/lib/perf/timer'
 *
 *   const { result, duration } = measureSync('parse-json', () => {
 *     return JSON.parse(data)
 *   })
 *
 * @param operation - Name of the operation.
 * @param fn - Synchronous function to measure.
 * @param metadata - Optional metadata.
 *
 * @returns Result of the function and duration
 */
export declare function measureSync<T>(operation: string, fn: () => T, metadata?: Record<string, unknown>): {
    result: T;
    duration: number;
};
/**
 * Mark a checkpoint in performance tracking. Useful for tracking progress
 * through complex operations.
 *
 * @example
 *   import { perfCheckpoint } from '@socketsecurity/lib/perf/timer'
 *
 *   perfCheckpoint('start-scan')
 *   // ... do work ...
 *   perfCheckpoint('fetch-packages', { count: 50 })
 *   // ... do work ...
 *   perfCheckpoint('analyze-issues', { issueCount: 10 })
 *   perfCheckpoint('end-scan')
 *
 * @param checkpoint - Name of the checkpoint.
 * @param metadata - Optional metadata.
 */
export declare function perfCheckpoint(checkpoint: string, metadata?: Record<string, unknown>): void;
/**
 * Start a performance timer for an operation. Returns a stop function that
 * records the duration.
 *
 * @example
 *   import { perfTimer } from '@socketsecurity/lib/perf/timer'
 *
 *   const stop = perfTimer('api-call')
 *   await fetchData()
 *   stop({ endpoint: '/npm/lodash/score' })
 *
 * @param operation - Name of the operation being timed.
 * @param metadata - Optional metadata to attach to the metric.
 *
 * @returns Stop function that completes the timing
 */
export declare function perfTimer(operation: string, metadata?: Record<string, unknown>): (additionalMetadata?: Record<string, unknown>) => void;
/**
 * Track memory usage at a specific point. Only available when DEBUG=perf is
 * enabled.
 *
 * @example
 *   import { trackMemory } from '@socketsecurity/lib/perf/timer'
 *
 *   const memBefore = trackMemory('before-operation')
 *   await heavyOperation()
 *   const memAfter = trackMemory('after-operation')
 *   console.log(`Memory increased by ${memAfter - memBefore}MB`)
 *
 * @param label - Label for this memory snapshot.
 *
 * @returns Memory usage in MB
 */
export declare function trackMemory(label: string): number;
