Skip to main content

​
Overview

The debug module provides utilities for measuring execution time and performance profiling with stopwatch functionality and timing wrappers.

​
Import

import { createStopwatch, withTiming, measureSync, measureAsync } from "bytekit";
// or
import { createStopwatch } from "bytekit/debug";

​
createStopwatch

Create a stopwatch for measuring operation duration.
​
options
StopwatchOptions

​
Returns

​
Stopwatch
object

​
Usage

import { createStopwatch, createLogger } from "bytekit";

const logger = createLogger({ namespace: "perf" });
const stopwatch = createStopwatch({
  label: "database-query",
  logger,
  precision: 2,
  autoLog: true
});

// Perform operation
const results = await db.query("SELECT * FROM users");

// Stop and get duration
const duration = stopwatch.stop();
console.log(`Query took ${duration}ms`);

// Or log with context
stopwatch.log({ rowCount: results.length });

​
withTiming

Execute a function while measuring its execution time. 
withTiming<T>(
  label: string,
  fn: () => Promise<T> | T,
  options?: StopwatchOptions
): Promise<T>

​
Usage

import { withTiming, createLogger } from "bytekit";

const logger = createLogger({ namespace: "api" });

const users = await withTiming(
  "fetch-users",
  async () => {
    return await api.get("/users");
  },
  { logger }
);
// Logs: "fetch-users took 123.45ms"

​
measureSync

Measure a synchronous function’s execution time. 
measureSync<T>(
  label: string,
  fn: () => T,
  options?: StopwatchOptions
): T

​
Usage

import { measureSync } from "bytekit";

const result = measureSync(
  "compute",
  () => {
    return complexCalculation();
  },
  { logger }
);

​
measureAsync

Measure an async function and return both result and duration. 
measureAsync<T>(
  label: string,
  fn: () => Promise<T> | T,
  options?: StopwatchOptions
): Promise<{ result: T; durationMs: number }>

​
Usage

import { measureAsync } from "bytekit";

const { result, durationMs } = await measureAsync(
  "api-call",
  async () => {
    return await api.get("/data");
  },
  { logger }
);

console.log(`Operation took ${durationMs}ms`);
console.log("Result:", result);

​
captureDebug

Capture execution time without logging, useful for internal measurements. 
captureDebug<T>(
  fn: () => Promise<T> | T
): Promise<{ result: T; durationMs: number }>

​
Usage

import { captureDebug } from "bytekit";

const { result, durationMs } = await captureDebug(async () => {
  return await expensiveOperation();
});

if (durationMs > 1000) {
  console.warn(`Operation was slow: ${durationMs}ms`);
}

​
Complete Example

import { 
  createStopwatch, 
  withTiming, 
  measureAsync,
  createLogger 
} from "bytekit";

const logger = createLogger({ namespace: "performance" });

// Manual stopwatch
const stopwatch = createStopwatch({
  label: "batch-process",
  logger,
  autoLog: true
});

for (const item of items) {
  await processItem(item);
}

stopwatch.stop();
// Logs: "batch-process took 1234.56ms"

// Automatic timing wrapper
const data = await withTiming(
  "fetch-data",
  async () => api.get("/data"),
  { logger }
);

// Measure with result
const { result, durationMs } = await measureAsync(
  "transform",
  async () => transform(data),
  { logger }
);

​
See Also