@philiprehberger/timer 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @philiprehberger/timer
+
+[![CI](https://github.com/philiprehberger/ts-timer/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/ts-timer/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@philiprehberger/timer.svg)](https://www.npmjs.com/package/@philiprehberger/timer)
+[![License](https://img.shields.io/github/license/philiprehberger/ts-timer)](LICENSE)
+
+Precise timing utilities — measure, benchmark, countdown
+
+## Requirements
+
+- Node.js >= 18
+
+## Installation
+
+```bash
+npm install @philiprehberger/timer
+```
+
+## Usage
+
+### Timer
+
+```ts
+import { timer } from '@philiprehberger/timer';
+
+const t = timer();
+
+// Do some work...
+t.lap();
+// Do more work...
+t.lap();
+
+console.log(t.format()); // "245ms"
+console.log(t.laps());   // [{ index: 1, split: 120, elapsed: 120 }, ...]
+
+const total = t.stop();
+```
+
+### Measure
+
+```ts
+import { measure, measureAsync } from '@philiprehberger/timer';
+
+const { result, duration } = measure(() => heavyComputation());
+console.log(`Result: ${result}, took ${duration}ms`);
+
+const { result: data, duration: ms } = await measureAsync(() => fetch('/api'));
+console.log(`Fetched in ${ms}ms`);
+```
+
+### Benchmark
+
+```ts
+import { benchmark } from '@philiprehberger/timer';
+
+const stats = benchmark(() => JSON.parse('{"a":1}'), {
+  iterations: 5000,
+  warmup: 500,
+});
+
+console.log(`Mean: ${stats.mean.toFixed(4)}ms`);
+console.log(`Median: ${stats.median.toFixed(4)}ms`);
+console.log(`P95: ${stats.p95.toFixed(4)}ms`);
+console.log(`P99: ${stats.p99.toFixed(4)}ms`);
+console.log(`Min: ${stats.min.toFixed(4)}ms`);
+console.log(`Max: ${stats.max.toFixed(4)}ms`);
+console.log(`Ops/sec: ${stats.ops.toFixed(0)}`);
+```
+
+### Format Duration
+
+```ts
+import { formatDuration } from '@philiprehberger/timer';
+
+formatDuration(0);         // "0ms"
+formatDuration(1500);      // "1s 500ms"
+formatDuration(3_661_500); // "1h 1m 1s 500ms"
+```
+
+## API
+
+### `timer(): Timer`
+
+Creates a high-resolution timer.
+
+- `.elapsed(): number` — Current elapsed time in milliseconds.
+- `.stop(): number` — Stops the timer; returns elapsed time.
+- `.reset(): void` — Resets and restarts the timer.
+- `.lap(): Lap` — Records a lap; returns `{ index, split, elapsed }`.
+- `.laps(): Lap[]` — Returns all recorded laps.
+- `.format(): string` — Formats the elapsed time as a human-readable string.
+
+### `measure<T>(fn: () => T): MeasureResult<T>`
+
+Measures execution time of a synchronous function. Returns `{ result, duration }`.
+
+### `measureAsync<T>(fn: () => Promise<T>): Promise<MeasureResult<T>>`
+
+Measures execution time of an asynchronous function. Returns `{ result, duration }`.
+
+### `benchmark(fn: () => void, options?: BenchmarkOptions): BenchmarkResult`
+
+Benchmarks a function over many iterations.
+
+**Options:**
+- `iterations` — Number of measured iterations (default: `1000`).
+- `warmup` — Number of warmup iterations (default: `100`).
+
+**Result:**
+- `mean` — Arithmetic mean in ms.
+- `median` — Median in ms.
+- `p95` — 95th percentile in ms.
+- `p99` — 99th percentile in ms.
+- `min` — Minimum duration in ms.
+- `max` — Maximum duration in ms.
+- `ops` — Operations per second.
+- `iterations` — Number of iterations run.
+
+### `formatDuration(ms: number): string`
+
+Formats a millisecond value into a human-readable string (e.g. `"1h 2m 3s 45ms"`).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run typecheck
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+// src/timer.ts
+function formatDuration(ms) {
+  const parts = decompose(ms);
+  const segments = [];
+  if (parts.hours > 0) segments.push(`${parts.hours}h`);
+  if (parts.minutes > 0) segments.push(`${parts.minutes}m`);
+  if (parts.seconds > 0) segments.push(`${parts.seconds}s`);
+  if (parts.milliseconds > 0 || segments.length === 0) {
+    segments.push(`${parts.milliseconds}ms`);
+  }
+  return segments.join(" ");
+}
+function decompose(ms) {
+  const totalMs = Math.max(0, Math.round(ms));
+  const hours = Math.floor(totalMs / 36e5);
+  const minutes = Math.floor(totalMs % 36e5 / 6e4);
+  const seconds = Math.floor(totalMs % 6e4 / 1e3);
+  const milliseconds = totalMs % 1e3;
+  return { hours, minutes, seconds, milliseconds };
+}
+function timer() {
+  let startTime = performance.now();
+  let stopTime = null;
+  const lapRecords = [];
+  let lastLapTime = startTime;
+  function elapsed() {
+    if (stopTime !== null) {
+      return stopTime - startTime;
+    }
+    return performance.now() - startTime;
+  }
+  function stop() {
+    if (stopTime === null) {
+      stopTime = performance.now();
+    }
+    return stopTime - startTime;
+  }
+  function reset() {
+    startTime = performance.now();
+    stopTime = null;
+    lapRecords.length = 0;
+    lastLapTime = startTime;
+  }
+  function lap() {
+    const now = stopTime !== null ? stopTime : performance.now();
+    const split = now - lastLapTime;
+    const totalElapsed = now - startTime;
+    const record = {
+      index: lapRecords.length + 1,
+      split,
+      elapsed: totalElapsed
+    };
+    lapRecords.push(record);
+    lastLapTime = now;
+    return record;
+  }
+  function laps() {
+    return [...lapRecords];
+  }
+  function format() {
+    return formatDuration(elapsed());
+  }
+  return { elapsed, stop, reset, lap, laps, format };
+}
+
+// src/measure.ts
+function measure(fn) {
+  const start = performance.now();
+  const result = fn();
+  const duration = performance.now() - start;
+  return { result, duration };
+}
+async function measureAsync(fn) {
+  const start = performance.now();
+  const result = await fn();
+  const duration = performance.now() - start;
+  return { result, duration };
+}
+
+// src/benchmark.ts
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const index = p / 100 * (sorted.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return sorted[lower];
+  const weight = index - lower;
+  return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+function benchmark(fn, options = {}) {
+  const { iterations = 1e3, warmup = 100 } = options;
+  for (let i = 0; i < warmup; i++) {
+    fn();
+  }
+  const durations = new Array(iterations);
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    fn();
+    durations[i] = performance.now() - start;
+  }
+  durations.sort((a, b) => a - b);
+  const sum = durations.reduce((acc, d) => acc + d, 0);
+  const mean = sum / iterations;
+  const median = percentile(durations, 50);
+  const p95 = percentile(durations, 95);
+  const p99 = percentile(durations, 99);
+  const min = durations[0];
+  const max = durations[durations.length - 1];
+  const ops = mean > 0 ? 1e3 / mean : Infinity;
+  return { mean, median, p95, p99, min, max, ops, iterations };
+}
+
+exports.benchmark = benchmark;
+exports.formatDuration = formatDuration;
+exports.measure = measure;
+exports.measureAsync = measureAsync;
+exports.timer = timer;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/timer.ts","../src/measure.ts","../src/benchmark.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { Timer, Lap, FormattedDuration } from './types.js';\n\n/**\n * Formats a millisecond duration into a human-readable string.\n *\n * @param ms - Duration in milliseconds.\n * @returns A formatted string like \"1h 2m 3s 45ms\" or \"0ms\".\n */\nexport function formatDuration(ms: number): string {\n  const parts = decompose(ms);\n  const segments: string[] = [];\n\n  if (parts.hours > 0) segments.push(`${parts.hours}h`);\n  if (parts.minutes > 0) segments.push(`${parts.minutes}m`);\n  if (parts.seconds > 0) segments.push(`${parts.seconds}s`);\n  if (parts.milliseconds > 0 || segments.length === 0) {\n    segments.push(`${parts.milliseconds}ms`);\n  }\n\n  return segments.join(' ');\n}\n\n/**\n * Decomposes milliseconds into hours, minutes, seconds, and remaining milliseconds.\n */\nfunction decompose(ms: number): FormattedDuration {\n  const totalMs = Math.max(0, Math.round(ms));\n  const hours = Math.floor(totalMs / 3_600_000);\n  const minutes = Math.floor((totalMs % 3_600_000) / 60_000);\n  const seconds = Math.floor((totalMs % 60_000) / 1_000);\n  const milliseconds = totalMs % 1_000;\n\n  return { hours, minutes, seconds, milliseconds };\n}\n\n/**\n * Creates a high-resolution timer.\n *\n * @returns A `Timer` object with `elapsed`, `stop`, `reset`, `lap`, `laps`, and `format` methods.\n *\n * @example\n * ```ts\n * const t = timer();\n * // ... do work ...\n * console.log(t.format()); // \"123ms\"\n * t.lap();\n * // ... more work ...\n * t.lap();\n * console.log(t.laps());\n * const total = t.stop();\n * ```\n */\nexport function timer(): Timer {\n  let startTime = performance.now();\n  let stopTime: number | null = null;\n  const lapRecords: Lap[] = [];\n  let lastLapTime = startTime;\n\n  function elapsed(): number {\n    if (stopTime !== null) {\n      return stopTime - startTime;\n    }\n    return performance.now() - startTime;\n  }\n\n  function stop(): number {\n    if (stopTime === null) {\n      stopTime = performance.now();\n    }\n    return stopTime - startTime;\n  }\n\n  function reset(): void {\n    startTime = performance.now();\n    stopTime = null;\n    lapRecords.length = 0;\n    lastLapTime = startTime;\n  }\n\n  function lap(): Lap {\n    const now = stopTime !== null ? stopTime : performance.now();\n    const split = now - lastLapTime;\n    const totalElapsed = now - startTime;\n    const record: Lap = {\n      index: lapRecords.length + 1,\n      split,\n      elapsed: totalElapsed,\n    };\n    lapRecords.push(record);\n    lastLapTime = now;\n    return record;\n  }\n\n  function laps(): Lap[] {\n    return [...lapRecords];\n  }\n\n  function format(): string {\n    return formatDuration(elapsed());\n  }\n\n  return { elapsed, stop, reset, lap, laps, format };\n}\n","import type { MeasureResult } from './types.js';\n\n/**\n * Measures the execution time of a synchronous function.\n *\n * @param fn - The function to measure.\n * @returns An object containing the function's return value and the duration in milliseconds.\n *\n * @example\n * ```ts\n * const { result, duration } = measure(() => heavyComputation());\n * console.log(`Took ${duration}ms`);\n * ```\n */\nexport function measure<T>(fn: () => T): MeasureResult<T> {\n  const start = performance.now();\n  const result = fn();\n  const duration = performance.now() - start;\n  return { result, duration };\n}\n\n/**\n * Measures the execution time of an asynchronous function.\n *\n * @param fn - The async function to measure.\n * @returns A promise resolving to an object with the return value and duration in milliseconds.\n *\n * @example\n * ```ts\n * const { result, duration } = await measureAsync(() => fetch('/api/data'));\n * console.log(`Took ${duration}ms`);\n * ```\n */\nexport async function measureAsync<T>(fn: () => Promise<T>): Promise<MeasureResult<T>> {\n  const start = performance.now();\n  const result = await fn();\n  const duration = performance.now() - start;\n  return { result, duration };\n}\n","import type { BenchmarkOptions, BenchmarkResult } from './types.js';\n\n/**\n * Computes a percentile value from a **sorted** array of numbers.\n */\nfunction percentile(sorted: number[], p: number): number {\n  if (sorted.length === 0) return 0;\n  const index = (p / 100) * (sorted.length - 1);\n  const lower = Math.floor(index);\n  const upper = Math.ceil(index);\n  if (lower === upper) return sorted[lower];\n  const weight = index - lower;\n  return sorted[lower] * (1 - weight) + sorted[upper] * weight;\n}\n\n/**\n * Benchmarks a synchronous function over many iterations.\n *\n * @param fn - The function to benchmark.\n * @param options - Configuration for iterations and warmup.\n * @returns Statistics including mean, median, p95, p99, min, max, and ops/sec.\n *\n * @example\n * ```ts\n * const stats = benchmark(() => JSON.parse('{\"a\":1}'));\n * console.log(`Mean: ${stats.mean.toFixed(4)}ms, Ops: ${stats.ops.toFixed(0)}/sec`);\n * ```\n */\nexport function benchmark(\n  fn: () => void,\n  options: BenchmarkOptions = {},\n): BenchmarkResult {\n  const { iterations = 1000, warmup = 100 } = options;\n\n  // Warmup phase\n  for (let i = 0; i < warmup; i++) {\n    fn();\n  }\n\n  // Measurement phase\n  const durations: number[] = new Array(iterations);\n  for (let i = 0; i < iterations; i++) {\n    const start = performance.now();\n    fn();\n    durations[i] = performance.now() - start;\n  }\n\n  durations.sort((a, b) => a - b);\n\n  const sum = durations.reduce((acc, d) => acc + d, 0);\n  const mean = sum / iterations;\n  const median = percentile(durations, 50);\n  const p95 = percentile(durations, 95);\n  const p99 = percentile(durations, 99);\n  const min = durations[0];\n  const max = durations[durations.length - 1];\n  const ops = mean > 0 ? 1000 / mean : Infinity;\n\n  return { mean, median, p95, p99, min, max, ops, iterations };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,146 @@
+/**
+ * Represents a duration broken down into units.
+ */
+interface FormattedDuration {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}
+/**
+ * A lap record captured by the timer.
+ */
+interface Lap {
+    /** Lap index (1-based). */
+    index: number;
+    /** Time since the previous lap (or start), in milliseconds. */
+    split: number;
+    /** Total elapsed time at the moment the lap was recorded, in milliseconds. */
+    elapsed: number;
+}
+/**
+ * The object returned by `timer()`.
+ */
+interface Timer {
+    /** Returns the elapsed time in milliseconds. */
+    elapsed(): number;
+    /** Stops the timer and returns the elapsed time in milliseconds. */
+    stop(): number;
+    /** Resets the timer to zero and starts it again. */
+    reset(): void;
+    /** Records a lap and returns the lap data. */
+    lap(): Lap;
+    /** Returns all recorded laps. */
+    laps(): Lap[];
+    /** Formats the current elapsed time into a human-readable string. */
+    format(): string;
+}
+/**
+ * Options for the `benchmark` function.
+ */
+interface BenchmarkOptions {
+    /** Number of measured iterations (default: 1000). */
+    iterations?: number;
+    /** Number of warmup iterations before measurement (default: 100). */
+    warmup?: number;
+}
+/**
+ * Result of a benchmark run.
+ */
+interface BenchmarkResult {
+    /** Arithmetic mean in milliseconds. */
+    mean: number;
+    /** Median in milliseconds. */
+    median: number;
+    /** 95th percentile in milliseconds. */
+    p95: number;
+    /** 99th percentile in milliseconds. */
+    p99: number;
+    /** Minimum duration in milliseconds. */
+    min: number;
+    /** Maximum duration in milliseconds. */
+    max: number;
+    /** Operations per second based on mean. */
+    ops: number;
+    /** Total number of measured iterations. */
+    iterations: number;
+}
+/**
+ * Result of `measure` or `measureAsync`.
+ */
+interface MeasureResult<T> {
+    /** The return value of the measured function. */
+    result: T;
+    /** Duration in milliseconds. */
+    duration: number;
+}
+
+/**
+ * Formats a millisecond duration into a human-readable string.
+ *
+ * @param ms - Duration in milliseconds.
+ * @returns A formatted string like "1h 2m 3s 45ms" or "0ms".
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Creates a high-resolution timer.
+ *
+ * @returns A `Timer` object with `elapsed`, `stop`, `reset`, `lap`, `laps`, and `format` methods.
+ *
+ * @example
+ * ```ts
+ * const t = timer();
+ * // ... do work ...
+ * console.log(t.format()); // "123ms"
+ * t.lap();
+ * // ... more work ...
+ * t.lap();
+ * console.log(t.laps());
+ * const total = t.stop();
+ * ```
+ */
+declare function timer(): Timer;
+
+/**
+ * Measures the execution time of a synchronous function.
+ *
+ * @param fn - The function to measure.
+ * @returns An object containing the function's return value and the duration in milliseconds.
+ *
+ * @example
+ * ```ts
+ * const { result, duration } = measure(() => heavyComputation());
+ * console.log(`Took ${duration}ms`);
+ * ```
+ */
+declare function measure<T>(fn: () => T): MeasureResult<T>;
+/**
+ * Measures the execution time of an asynchronous function.
+ *
+ * @param fn - The async function to measure.
+ * @returns A promise resolving to an object with the return value and duration in milliseconds.
+ *
+ * @example
+ * ```ts
+ * const { result, duration } = await measureAsync(() => fetch('/api/data'));
+ * console.log(`Took ${duration}ms`);
+ * ```
+ */
+declare function measureAsync<T>(fn: () => Promise<T>): Promise<MeasureResult<T>>;
+
+/**
+ * Benchmarks a synchronous function over many iterations.
+ *
+ * @param fn - The function to benchmark.
+ * @param options - Configuration for iterations and warmup.
+ * @returns Statistics including mean, median, p95, p99, min, max, and ops/sec.
+ *
+ * @example
+ * ```ts
+ * const stats = benchmark(() => JSON.parse('{"a":1}'));
+ * console.log(`Mean: ${stats.mean.toFixed(4)}ms, Ops: ${stats.ops.toFixed(0)}/sec`);
+ * ```
+ */
+declare function benchmark(fn: () => void, options?: BenchmarkOptions): BenchmarkResult;
+
+export { type BenchmarkOptions, type BenchmarkResult, type FormattedDuration, type Lap, type MeasureResult, type Timer, benchmark, formatDuration, measure, measureAsync, timer };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Represents a duration broken down into units.
+ */
+interface FormattedDuration {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}
+/**
+ * A lap record captured by the timer.
+ */
+interface Lap {
+    /** Lap index (1-based). */
+    index: number;
+    /** Time since the previous lap (or start), in milliseconds. */
+    split: number;
+    /** Total elapsed time at the moment the lap was recorded, in milliseconds. */
+    elapsed: number;
+}
+/**
+ * The object returned by `timer()`.
+ */
+interface Timer {
+    /** Returns the elapsed time in milliseconds. */
+    elapsed(): number;
+    /** Stops the timer and returns the elapsed time in milliseconds. */
+    stop(): number;
+    /** Resets the timer to zero and starts it again. */
+    reset(): void;
+    /** Records a lap and returns the lap data. */
+    lap(): Lap;
+    /** Returns all recorded laps. */
+    laps(): Lap[];
+    /** Formats the current elapsed time into a human-readable string. */
+    format(): string;
+}
+/**
+ * Options for the `benchmark` function.
+ */
+interface BenchmarkOptions {
+    /** Number of measured iterations (default: 1000). */
+    iterations?: number;
+    /** Number of warmup iterations before measurement (default: 100). */
+    warmup?: number;
+}
+/**
+ * Result of a benchmark run.
+ */
+interface BenchmarkResult {
+    /** Arithmetic mean in milliseconds. */
+    mean: number;
+    /** Median in milliseconds. */
+    median: number;
+    /** 95th percentile in milliseconds. */
+    p95: number;
+    /** 99th percentile in milliseconds. */
+    p99: number;
+    /** Minimum duration in milliseconds. */
+    min: number;
+    /** Maximum duration in milliseconds. */
+    max: number;
+    /** Operations per second based on mean. */
+    ops: number;
+    /** Total number of measured iterations. */
+    iterations: number;
+}
+/**
+ * Result of `measure` or `measureAsync`.
+ */
+interface MeasureResult<T> {
+    /** The return value of the measured function. */
+    result: T;
+    /** Duration in milliseconds. */
+    duration: number;
+}
+
+/**
+ * Formats a millisecond duration into a human-readable string.
+ *
+ * @param ms - Duration in milliseconds.
+ * @returns A formatted string like "1h 2m 3s 45ms" or "0ms".
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Creates a high-resolution timer.
+ *
+ * @returns A `Timer` object with `elapsed`, `stop`, `reset`, `lap`, `laps`, and `format` methods.
+ *
+ * @example
+ * ```ts
+ * const t = timer();
+ * // ... do work ...
+ * console.log(t.format()); // "123ms"
+ * t.lap();
+ * // ... more work ...
+ * t.lap();
+ * console.log(t.laps());
+ * const total = t.stop();
+ * ```
+ */
+declare function timer(): Timer;
+
+/**
+ * Measures the execution time of a synchronous function.
+ *
+ * @param fn - The function to measure.
+ * @returns An object containing the function's return value and the duration in milliseconds.
+ *
+ * @example
+ * ```ts
+ * const { result, duration } = measure(() => heavyComputation());
+ * console.log(`Took ${duration}ms`);
+ * ```
+ */
+declare function measure<T>(fn: () => T): MeasureResult<T>;
+/**
+ * Measures the execution time of an asynchronous function.
+ *
+ * @param fn - The async function to measure.
+ * @returns A promise resolving to an object with the return value and duration in milliseconds.
+ *
+ * @example
+ * ```ts
+ * const { result, duration } = await measureAsync(() => fetch('/api/data'));
+ * console.log(`Took ${duration}ms`);
+ * ```
+ */
+declare function measureAsync<T>(fn: () => Promise<T>): Promise<MeasureResult<T>>;
+
+/**
+ * Benchmarks a synchronous function over many iterations.
+ *
+ * @param fn - The function to benchmark.
+ * @param options - Configuration for iterations and warmup.
+ * @returns Statistics including mean, median, p95, p99, min, max, and ops/sec.
+ *
+ * @example
+ * ```ts
+ * const stats = benchmark(() => JSON.parse('{"a":1}'));
+ * console.log(`Mean: ${stats.mean.toFixed(4)}ms, Ops: ${stats.ops.toFixed(0)}/sec`);
+ * ```
+ */
+declare function benchmark(fn: () => void, options?: BenchmarkOptions): BenchmarkResult;
+
+export { type BenchmarkOptions, type BenchmarkResult, type FormattedDuration, type Lap, type MeasureResult, type Timer, benchmark, formatDuration, measure, measureAsync, timer };

package/dist/index.js

@@ -0,0 +1,115 @@
+// src/timer.ts
+function formatDuration(ms) {
+  const parts = decompose(ms);
+  const segments = [];
+  if (parts.hours > 0) segments.push(`${parts.hours}h`);
+  if (parts.minutes > 0) segments.push(`${parts.minutes}m`);
+  if (parts.seconds > 0) segments.push(`${parts.seconds}s`);
+  if (parts.milliseconds > 0 || segments.length === 0) {
+    segments.push(`${parts.milliseconds}ms`);
+  }
+  return segments.join(" ");
+}
+function decompose(ms) {
+  const totalMs = Math.max(0, Math.round(ms));
+  const hours = Math.floor(totalMs / 36e5);
+  const minutes = Math.floor(totalMs % 36e5 / 6e4);
+  const seconds = Math.floor(totalMs % 6e4 / 1e3);
+  const milliseconds = totalMs % 1e3;
+  return { hours, minutes, seconds, milliseconds };
+}
+function timer() {
+  let startTime = performance.now();
+  let stopTime = null;
+  const lapRecords = [];
+  let lastLapTime = startTime;
+  function elapsed() {
+    if (stopTime !== null) {
+      return stopTime - startTime;
+    }
+    return performance.now() - startTime;
+  }
+  function stop() {
+    if (stopTime === null) {
+      stopTime = performance.now();
+    }
+    return stopTime - startTime;
+  }
+  function reset() {
+    startTime = performance.now();
+    stopTime = null;
+    lapRecords.length = 0;
+    lastLapTime = startTime;
+  }
+  function lap() {
+    const now = stopTime !== null ? stopTime : performance.now();
+    const split = now - lastLapTime;
+    const totalElapsed = now - startTime;
+    const record = {
+      index: lapRecords.length + 1,
+      split,
+      elapsed: totalElapsed
+    };
+    lapRecords.push(record);
+    lastLapTime = now;
+    return record;
+  }
+  function laps() {
+    return [...lapRecords];
+  }
+  function format() {
+    return formatDuration(elapsed());
+  }
+  return { elapsed, stop, reset, lap, laps, format };
+}
+
+// src/measure.ts
+function measure(fn) {
+  const start = performance.now();
+  const result = fn();
+  const duration = performance.now() - start;
+  return { result, duration };
+}
+async function measureAsync(fn) {
+  const start = performance.now();
+  const result = await fn();
+  const duration = performance.now() - start;
+  return { result, duration };
+}
+
+// src/benchmark.ts
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const index = p / 100 * (sorted.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return sorted[lower];
+  const weight = index - lower;
+  return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+function benchmark(fn, options = {}) {
+  const { iterations = 1e3, warmup = 100 } = options;
+  for (let i = 0; i < warmup; i++) {
+    fn();
+  }
+  const durations = new Array(iterations);
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    fn();
+    durations[i] = performance.now() - start;
+  }
+  durations.sort((a, b) => a - b);
+  const sum = durations.reduce((acc, d) => acc + d, 0);
+  const mean = sum / iterations;
+  const median = percentile(durations, 50);
+  const p95 = percentile(durations, 95);
+  const p99 = percentile(durations, 99);
+  const min = durations[0];
+  const max = durations[durations.length - 1];
+  const ops = mean > 0 ? 1e3 / mean : Infinity;
+  return { mean, median, p95, p99, min, max, ops, iterations };
+}
+
+export { benchmark, formatDuration, measure, measureAsync, timer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/timer.ts","../src/measure.ts","../src/benchmark.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Timer, Lap, FormattedDuration } from './types.js';\n\n/**\n * Formats a millisecond duration into a human-readable string.\n *\n * @param ms - Duration in milliseconds.\n * @returns A formatted string like \"1h 2m 3s 45ms\" or \"0ms\".\n */\nexport function formatDuration(ms: number): string {\n  const parts = decompose(ms);\n  const segments: string[] = [];\n\n  if (parts.hours > 0) segments.push(`${parts.hours}h`);\n  if (parts.minutes > 0) segments.push(`${parts.minutes}m`);\n  if (parts.seconds > 0) segments.push(`${parts.seconds}s`);\n  if (parts.milliseconds > 0 || segments.length === 0) {\n    segments.push(`${parts.milliseconds}ms`);\n  }\n\n  return segments.join(' ');\n}\n\n/**\n * Decomposes milliseconds into hours, minutes, seconds, and remaining milliseconds.\n */\nfunction decompose(ms: number): FormattedDuration {\n  const totalMs = Math.max(0, Math.round(ms));\n  const hours = Math.floor(totalMs / 3_600_000);\n  const minutes = Math.floor((totalMs % 3_600_000) / 60_000);\n  const seconds = Math.floor((totalMs % 60_000) / 1_000);\n  const milliseconds = totalMs % 1_000;\n\n  return { hours, minutes, seconds, milliseconds };\n}\n\n/**\n * Creates a high-resolution timer.\n *\n * @returns A `Timer` object with `elapsed`, `stop`, `reset`, `lap`, `laps`, and `format` methods.\n *\n * @example\n * ```ts\n * const t = timer();\n * // ... do work ...\n * console.log(t.format()); // \"123ms\"\n * t.lap();\n * // ... more work ...\n * t.lap();\n * console.log(t.laps());\n * const total = t.stop();\n * ```\n */\nexport function timer(): Timer {\n  let startTime = performance.now();\n  let stopTime: number | null = null;\n  const lapRecords: Lap[] = [];\n  let lastLapTime = startTime;\n\n  function elapsed(): number {\n    if (stopTime !== null) {\n      return stopTime - startTime;\n    }\n    return performance.now() - startTime;\n  }\n\n  function stop(): number {\n    if (stopTime === null) {\n      stopTime = performance.now();\n    }\n    return stopTime - startTime;\n  }\n\n  function reset(): void {\n    startTime = performance.now();\n    stopTime = null;\n    lapRecords.length = 0;\n    lastLapTime = startTime;\n  }\n\n  function lap(): Lap {\n    const now = stopTime !== null ? stopTime : performance.now();\n    const split = now - lastLapTime;\n    const totalElapsed = now - startTime;\n    const record: Lap = {\n      index: lapRecords.length + 1,\n      split,\n      elapsed: totalElapsed,\n    };\n    lapRecords.push(record);\n    lastLapTime = now;\n    return record;\n  }\n\n  function laps(): Lap[] {\n    return [...lapRecords];\n  }\n\n  function format(): string {\n    return formatDuration(elapsed());\n  }\n\n  return { elapsed, stop, reset, lap, laps, format };\n}\n","import type { MeasureResult } from './types.js';\n\n/**\n * Measures the execution time of a synchronous function.\n *\n * @param fn - The function to measure.\n * @returns An object containing the function's return value and the duration in milliseconds.\n *\n * @example\n * ```ts\n * const { result, duration } = measure(() => heavyComputation());\n * console.log(`Took ${duration}ms`);\n * ```\n */\nexport function measure<T>(fn: () => T): MeasureResult<T> {\n  const start = performance.now();\n  const result = fn();\n  const duration = performance.now() - start;\n  return { result, duration };\n}\n\n/**\n * Measures the execution time of an asynchronous function.\n *\n * @param fn - The async function to measure.\n * @returns A promise resolving to an object with the return value and duration in milliseconds.\n *\n * @example\n * ```ts\n * const { result, duration } = await measureAsync(() => fetch('/api/data'));\n * console.log(`Took ${duration}ms`);\n * ```\n */\nexport async function measureAsync<T>(fn: () => Promise<T>): Promise<MeasureResult<T>> {\n  const start = performance.now();\n  const result = await fn();\n  const duration = performance.now() - start;\n  return { result, duration };\n}\n","import type { BenchmarkOptions, BenchmarkResult } from './types.js';\n\n/**\n * Computes a percentile value from a **sorted** array of numbers.\n */\nfunction percentile(sorted: number[], p: number): number {\n  if (sorted.length === 0) return 0;\n  const index = (p / 100) * (sorted.length - 1);\n  const lower = Math.floor(index);\n  const upper = Math.ceil(index);\n  if (lower === upper) return sorted[lower];\n  const weight = index - lower;\n  return sorted[lower] * (1 - weight) + sorted[upper] * weight;\n}\n\n/**\n * Benchmarks a synchronous function over many iterations.\n *\n * @param fn - The function to benchmark.\n * @param options - Configuration for iterations and warmup.\n * @returns Statistics including mean, median, p95, p99, min, max, and ops/sec.\n *\n * @example\n * ```ts\n * const stats = benchmark(() => JSON.parse('{\"a\":1}'));\n * console.log(`Mean: ${stats.mean.toFixed(4)}ms, Ops: ${stats.ops.toFixed(0)}/sec`);\n * ```\n */\nexport function benchmark(\n  fn: () => void,\n  options: BenchmarkOptions = {},\n): BenchmarkResult {\n  const { iterations = 1000, warmup = 100 } = options;\n\n  // Warmup phase\n  for (let i = 0; i < warmup; i++) {\n    fn();\n  }\n\n  // Measurement phase\n  const durations: number[] = new Array(iterations);\n  for (let i = 0; i < iterations; i++) {\n    const start = performance.now();\n    fn();\n    durations[i] = performance.now() - start;\n  }\n\n  durations.sort((a, b) => a - b);\n\n  const sum = durations.reduce((acc, d) => acc + d, 0);\n  const mean = sum / iterations;\n  const median = percentile(durations, 50);\n  const p95 = percentile(durations, 95);\n  const p99 = percentile(durations, 99);\n  const min = durations[0];\n  const max = durations[durations.length - 1];\n  const ops = mean > 0 ? 1000 / mean : Infinity;\n\n  return { mean, median, p95, p99, min, max, ops, iterations };\n}\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@philiprehberger/timer",
+  "version": "0.1.3",
+  "description": "Precise timing utilities — measure, benchmark, countdown",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "timer",
+    "benchmark",
+    "measure",
+    "performance",
+    "stopwatch",
+    "duration"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/philiprehberger/ts-timer.git"
+  },
+  "homepage": "https://github.com/philiprehberger/ts-timer#readme",
+  "bugs": {
+    "url": "https://github.com/philiprehberger/ts-timer/issues"
+  },
+  "author": "Philip Rehberger",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false
+}