nano-profiler 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Köhler
+
+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,118 @@
+# NanoProfiler
+
+NanoProfiler is a small, dependency-free profiler implemented in TypeScript.
+It provides a single `NanoProfiler` class with utilities to measure execution time (and optionally memory) for synchronous and asynchronous code blocks.
+The library works in Node.js and browser environments.
+
+The profiler is designed to produce as little overhead as possible, making it suitable for profiling high-frequency code paths.
+It supports manual start/end profiling as well as automatic profiling of functions and code blocks.
+
+## Installation
+
+Install from npm:
+
+```
+npm install nano-profiler
+```
+
+## Quick usage
+
+Import the class and create an instance (or use the singleton):
+
+```ts
+import { NanoProfiler } from 'nano-profiler';
+
+const profiler = new NanoProfiler( { trackMem: true } );
+
+// profile a synchronous function
+profiler.run( () => {
+	// work
+}, 'syncTask' );
+
+// profile an async function
+await profiler.runAsync( async () => {
+	await doSomething();
+}, 'asyncTask' );
+
+// manual start/end
+const session = profiler.start( 'manual' );
+// work
+profiler.end( session );
+
+// get results
+const entries = profiler.report();
+const summary = profiler.summary();
+```
+
+## API reference
+
+### Instantiate
+
+- `NanoProfiler.global()`  
+  Returns the global singleton instance of `NanoProfiler`. This is useful for simple use cases where you don't need multiple profilers.
+- `new NanoProfiler( options?, hooks? )`  
+  Creates a new instance of `NanoProfiler` with optional configuration options and hooks.
+
+### Control
+
+- `enable() : boolean`  
+  Enables the profiler. Returns `true` to indicate that profiling is now active.
+- `disable() : boolean`  
+  Disables the profiler. Returns `false` to indicate that profiling is now inactive.
+- `flush () : ProfilerEntry[]`  
+  Clears all stored profiling entries and returns them as an array. This is useful for resetting the profiler state or retrieving results before starting a new profiling session.
+- `genEnv() : 'node' | 'browser' | 'unknown'`  
+  Returns the detected runtime environment. This can be used for environment-specific profiling logic or optimizations.
+- `isActive() : boolean`  
+  Returns `true` if the profiler is currently enabled and active, or `false` if it is disabled.
+- `getEntryCount() : number`  
+  Returns the total number of profiling entries that have been recorded since the last flush.
+
+### Profiling
+
+- `run< T >( fn: () => T, label?: string, meta?: any ) : T`  
+  Profiles the execution of a synchronous function `fn`. Optionally accepts a `label` for categorization and `meta` for additional data. Returns the result of the function.
+- `async runAsync< T >( fn: () => Promise< T >, label?: string, meta?: any ) : Promise< T >`  
+  Profiles the execution of an asynchronous function `fn`. Optionally accepts a `label` for categorization and `meta` for additional data. Returns a promise that resolves to the result of the function.
+- `start( label?: string ) : string`  
+  Starts profiling for a code block with an optional `label` and returns a unique identifier for the profiling session. This can be used for manual profiling of code blocks that don't fit well with the `run` or `runAsync` methods.
+- `end( session: string ) : void`  
+  Ends the profiling session identified by the `session` string returned from `start()`. This will record the profiling data for that session. If the provided session identifier does not correspond to an active profiling session, an error will be thrown.
+
+### Reports
+
+- `report( label?: string ) : ProfilerEntry[]`  
+  Returns an array of profiling entries. If a `label` is provided, only entries with that label will be returned.
+- `summary( label?: string ) : ProfilerSummary`  
+  Returns a summary of profiling results, including total time, average time, count, and optionally memory usage. If a `label` is provided, the summary will be for entries with that label.
+- `hotspot( label?: string ) : ProfilerEntry | undefined`  
+  Returns the single profiling entry with the longest execution time. If a `label` is provided, only entries with that label will be considered.
+- `histogram( label?: string, bins: number = 10 ) : HistogramEntry[]`  
+  Returns a histogram of execution times for the profiled entries. The `bins` parameter determines how many bins the histogram will have. If a `label` is provided, only entries with that label will be included in the histogram.
+- `percentiles( label?: string, ps: number[] = [ 50, 90, 95, 99 ] ) : PercentileEntry[]`  
+  Returns the specified percentiles of execution times for the profiled entries. The `ps` parameter is an array of percentiles to calculate (e.g., 50 for median, 90 for 90th percentile). If a `label` is provided, only entries with that label will be included in the percentile calculations.
+
+## Options
+
+- `enabled` (boolean, default: `true`)  
+  Whether the profiler is enabled by default.
+- `trackMem` (boolean, default: `false`)  
+  Whether to track memory usage in addition to execution time. Enabling this may have a performance impact.
+- `storeResults` (boolean, default: `false`)  
+  If set to `true`, the profiler stores results of profiled blocks/functions.
+- `sampleRate` (number, default: `1`)  
+  A value between `0` and `1` that determines the percentage of blocks/functions getting profiled. Useful for reducing overhead in high-frequency code.
+- `maxEntries` (number, default: `10000`)  
+  Maximum number of profiled time/memory entries. If the limit is reached, no more entries will be recorded until `flush()`.
+
+### Hooks
+
+- `onEntry( entry: ProfileEntry ) : void`  
+  A callback function that gets called whenever a new profile entry is recorded. Useful for real-time monitoring or custom logging.
+- `onFlush( entries: ProfileEntry[] ) : void`  
+  A callback function that gets called when the profiler is flushed. Receives all stored entries as an argument.
+
+----
+
+Copyright (c) 2026 Paul Köhler (komed3). All rights reserved.  
+Released under the MIT license. See LICENSE file in the project root for details.

package/dist/NanoProfiler.d.ts

@@ -0,0 +1,251 @@
+/**
+ * NanoProfiler is a lightweight and efficient profiling library for JavaScript and TypeScript.
+ *
+ * It provides functionality to measure execution time and memory usage of code blocks,
+ * with support for both synchronous and asynchronous functions.
+ *
+ * The profiler is designed to work in both Node.js and browser environments, automatically
+ * detecting the environment and using appropriate timing and memory measurement functions.
+ *
+ * @author Paul Köhler
+ * @license MIT
+ */
+/** Environment types for the NanoProfiler. */
+export type Env = 'node' | 'browser' | 'unknown';
+/** Configuration options for the NanoProfiler. */
+export interface ProfilerOptions {
+    enabled?: boolean;
+    trackMem?: boolean;
+    storeResults?: boolean;
+    sampleRate?: number;
+    maxEntries?: number;
+}
+/** Hooks for custom behavior on entry recording and flushing. */
+export interface ProfilerHooks {
+    onEntry?: (entry: ProfilerEntry) => void;
+    onFlush?: (entry: ProfilerEntry[]) => void;
+}
+/** Profiling entry representing single measurement of time and memory usage. */
+export interface ProfilerEntry<T = any> {
+    label?: string;
+    time: number;
+    mem?: number;
+    res?: T;
+    meta?: any;
+}
+/** Summary of profiling data, including total, max, min, and avg time and memory usage. */
+export interface ProfilerSummary {
+    calls: number;
+    time: {
+        total: number;
+        max: number;
+        min: number;
+        avg: number;
+    };
+    mem?: {
+        total: number;
+        max: number;
+        min: number;
+        avg: number;
+    };
+}
+/** Histogram entry representing range of times and number of calls whin that range. */
+export interface HistogramEntry {
+    bin: number;
+    calls: number;
+}
+/** Percentile entry representing a specific percentile and its corresponding time. */
+export interface PercentileEntry {
+    percentile: number;
+    time: number;
+}
+/** Function type for running profiled code. */
+export type RunnerFn<T = any> = (fn: () => T, label?: string, meta?: any) => T;
+export type AsyncRunnerFn<T = any> = (fn: () => Promise<T>, label?: string, meta?: any) => Promise<T>;
+/** Function type for timer functions that return the current time or memory usage. */
+export type TimerFn = () => number;
+/** The main NanoProfiler class that provides profiling functionality. */
+export declare class NanoProfiler {
+    /** A singleton instance of NanoProfiler for global use. */
+    private static globalInstance?;
+    /**
+     * Returns the global instance of NanoProfiler, creating it if it doesn't already exist.
+     *
+     * @returns {NanoProfiler} The global NanoProfiler instance.
+     */
+    static global(): NanoProfiler;
+    /** Internal state and configuration. */
+    private readonly options;
+    private readonly maxEntries;
+    private readonly sampleRate;
+    private readonly hooks?;
+    private readonly env;
+    /** Timer functions for measuring time and memory usage, set up based on the detected environment. */
+    private now;
+    private mem;
+    /** Runner functions for executing profiled code, set up to record profiling data. */
+    private runner;
+    private runnerAsync;
+    /** Indicates whether the profiler is currently active (enabled) or not. */
+    private active;
+    /** An array to store profiling entries, and an index to keep track of the current position in the array. */
+    private entries;
+    private index;
+    /** A map to track active labels for manual start/end profiling. */
+    private tl;
+    /**
+     * Detects the current environment (Node.js, browser, or unknown).
+     *
+     * @returns {Env} The detected environment.
+     */
+    private detectEnv;
+    /**
+     * Sets up the appropriate timer function based on the detected environment.
+     *
+     * @returns {TimerFn} A function that returns the current time in milliseconds.
+     */
+    private setupNow;
+    /**
+     * Sets up the appropriate memory usage function based on the detected environment.
+     *
+     * @returns {TimerFn} A function that returns the current memory usage in bytes.
+     */
+    private setupMem;
+    /**
+     * Records a profiling entry with the given time, memory usage, result, label, and metadata.
+     *
+     * @param {number} time - The time taken for the profiled code to execute.
+     * @param {number | undefined} mem - The memory used during the execution (if tracking is enabled).
+     * @param {T} res - The result of the profiled code (if storing results is enabled).
+     * @param {string} [label] - An optional label for the profiling entry.
+     * @param {any} [meta] - Optional metadata to associate with the profiling entry.
+     */
+    private record;
+    /**
+     * Creates a new instance of NanoProfiler with the given options and hooks.
+     *
+     * @param {ProfilerOptions} [options] - Configuration options for the profiler.
+     * @param {ProfilerHooks} [hooks] - Hooks for custom behavior on entry recording and flushing.
+     */
+    constructor(options?: ProfilerOptions, hooks?: ProfilerHooks);
+    /**
+     * Enables the profiler.
+     *
+     * Sets up the runner functions to record profiling data when executing code,
+     * and returns true to indicate that the profiler is now active.
+     *
+     * @returns {boolean} True if the profiler was successfully enabled, false otherwise.
+     */
+    enable(): boolean;
+    /**
+     * Disables the profiler.
+     *
+     * @returns {boolean} False, indicating that the profiler is now disabled.
+     */
+    disable(): boolean;
+    /**
+     * Returns the detected environment in which the profiler is running.
+     *
+     * @returns {Env} The detected environment ('node', 'browser', or 'unknown').
+     */
+    getEnv(): Env;
+    /**
+     * Checks if the profiler is currently active (enabled).
+     *
+     * @returns {boolean} True if the profiler is active, false otherwise.
+     */
+    isActive(): boolean;
+    /**
+     * Returns the number of profiling entries that have been logged so far.
+     *
+     * @returns {number} The number of logged profiling entries.
+     */
+    getEntryCount(): number;
+    /**
+     * Runs the provided function while recording profiling data, using the configured runner function.
+     *
+     * @param {() => T} fn - The function to execute and profile.
+     * @param {string} [label] - An optional label to associate with the profiling entry.
+     * @param {any} [meta] - Optional metadata to associate with the profiling entry.
+     * @returns {T} The result of the executed function.
+     */
+    run<T>(fn: () => T, label?: string, meta?: any): T;
+    /**
+     * Runs the provided asynchronous function while recording profiling data,
+     * using the configured asynchronous runner function.
+     *
+     * @param {() => Promise<T>} fn - The asynchronous function to execute and profile.
+     * @param {string} [label] - Optional label to associate with the profiling entry.
+     * @param {any} [meta] - Optional metadata to associate with the profiling entry.
+     * @returns {Promise<T>} A promise that resolves to the result of the executed asynchronous function.
+     */
+    runAsync<T>(fn: () => Promise<T>, label?: string, meta?: any): Promise<T>;
+    /**
+     * Starts a manual profiling session with an optional label and returns
+     * a unique identifier for the session.
+     *
+     * @param {string} [label] - An optional label to associate with the profiling session.
+     * @return {string} A unique identifier for the profiling session.
+     */
+    start(label?: string): string;
+    /**
+     * Ends a manual profiling session with the given label and records the profiling data.
+     *
+     * @param {string} session - The unique identifier for the profiling session to end.
+     * @throws {Error} If the provided session does not correspond to an active profiling session.
+     */
+    end(session: string): void;
+    /**
+     * Retrieves profiling entries, optionally filtered by a specific label.
+     *
+     * @param {string} [label] - An optional label to filter the profiling entries.
+     * @returns {ProfilerEntry[]} An array of profiling entries that match the specified label.
+     */
+    report(label?: string): ProfilerEntry[];
+    /**
+     * Generates a summary of profiling data, optionally filtered by a specific label.
+     *
+     * Calculates total, maximum, minimum, and average time (and memory usage if tracking
+     * is enabled) for the profiling entries that match the specified label.
+     *
+     * @param {string} [label] - An optional label to filter the profiling entries.
+     * @returns {ProfilerSummary} A summary object containing aggregated profiling data.
+     */
+    summary(label?: string): ProfilerSummary;
+    /**
+     * Identifies the profiling entry with the longest execution time,
+     * optionally filtered by a specific label.
+     *
+     * @param {string} [label] - An optional label to filter the profiling entries.
+     * @returns {ProfilerEntry | undefined} The profiling entry with the longest execution time.
+     */
+    hotspot(label?: string): ProfilerEntry | undefined;
+    /**
+     * Generates a histogram of execution times for profiling entries,
+     * optionally filtered by a specific label.
+     *
+     * Calculates the minimum and maximum execution times, divides the range into
+     * specified bins, and counts the number of entries that fall into each bin to
+     * create a histogram representation of the execution times.
+     *
+     * @param {string} [label] - An optional label to filter the profiling entries.
+     * @param {number} [bins=10] - The number of bins to use for the histogram.
+     * @returns {HistogramEntry[]} An array of histogram entries.
+     */
+    histogram(label?: string, bins?: number): HistogramEntry[];
+    /**
+     * Calculates specific percentiles of execution times for profiling entries,
+     * optionally filtered by a specific label.
+     *
+     * @param {string} [label] - An optional label to filter the profiling entries.
+     * @param {number[]} [ps=[50, 90, 95, 99]] - An array of percentiles to calculate.
+     * @returns {PercentileEntry[]} An array of objects representing the calculated percentiles.
+     */
+    percentiles(label?: string, ps?: number[]): PercentileEntry[];
+    /**
+     * Flushes the recorded profiling entries, returning them and resetting the internal state.
+     *
+     * @returns {ProfilerEntry[]} An array of profiling entries that were flushed.
+     */
+    flush(): ProfilerEntry[];
+}

package/dist/nano-profiler.cjs

@@ -0,0 +1,276 @@
+'use strict';
+
+const DEFAULT_OPTIONS = {
+  enabled: true,
+  trackMem: false,
+  storeResults: false,
+  sampleRate: 1,
+  maxEntries: 10_000
+};
+class NanoProfiler {
+  static globalInstance;
+  static global() {
+    return (NanoProfiler.globalInstance ??= new NanoProfiler());
+  }
+  options;
+  maxEntries;
+  sampleRate;
+  hooks;
+  env;
+  now;
+  mem;
+  runner;
+  runnerAsync;
+  active;
+  entries;
+  index = 0;
+  tl = new Map();
+  detectEnv() {
+    if (typeof process !== 'undefined' && process.versions?.node) return 'node';
+    else if (typeof performance !== 'undefined') return 'browser';
+    return 'unknown';
+  }
+  setupNow() {
+    switch (this.env) {
+      case 'node':
+        return () => {
+          const t = process.hrtime();
+          return t[0] * 1e3 + t[1] * 1e-6;
+        };
+      case 'browser':
+        return () => performance.now();
+      default:
+        return () => Date.now();
+    }
+  }
+  setupMem() {
+    switch (this.env) {
+      case 'node':
+        return () => process.memoryUsage().heapUsed;
+      case 'browser':
+        return () => performance.memory?.usedJSHeapSize ?? 0;
+      default:
+        return () => 0;
+    }
+  }
+  record(time, mem, res, label, meta) {
+    if (this.index >= this.maxEntries) return;
+    const entry = this.entries[this.index] ?? (this.entries[this.index] = {});
+    this.index++;
+    entry.time = time;
+    entry.label = label;
+    entry.mem = mem;
+    entry.res = this.options.storeResults ? res : undefined;
+    entry.meta = meta;
+    this.hooks?.onEntry?.(entry);
+  }
+  constructor(options = {}, hooks) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.maxEntries = Number(this.options.maxEntries ?? 10_000);
+    this.sampleRate = Math.max(
+      0,
+      Math.min(1, Number(this.options.sampleRate ?? 1))
+    );
+    this.hooks = hooks;
+    this.env = this.detectEnv();
+    this.now = this.setupNow();
+    this.mem = this.setupMem();
+    this.entries = new Array(this.maxEntries);
+    this.active = this.options.enabled ? this.enable() : this.disable();
+  }
+  enable() {
+    if (this.active) return true;
+    const trackMem = this.options.trackMem;
+    const sampleRate = this.sampleRate;
+    const self = this,
+      now = this.now,
+      mem = this.mem;
+    this.runner = (fn, label, meta) => {
+      if (sampleRate < 1 && Math.random() >= sampleRate) return fn();
+      const t0 = now(),
+        m0 = trackMem ? mem() : undefined;
+      let res;
+      try {
+        return (res = fn());
+      } finally {
+        self.record(
+          now() - t0,
+          trackMem ? mem() - m0 : undefined,
+          res,
+          label,
+          meta
+        );
+      }
+    };
+    this.runnerAsync = async (fn, label, meta) => {
+      if (sampleRate < 1 && Math.random() >= sampleRate) return await fn();
+      const t0 = now(),
+        m0 = trackMem ? mem() : undefined;
+      let res;
+      try {
+        return (res = await fn());
+      } finally {
+        self.record(
+          now() - t0,
+          trackMem ? mem() - m0 : undefined,
+          res,
+          label,
+          meta
+        );
+      }
+    };
+    return (this.active = true);
+  }
+  disable() {
+    this.runner = (fn) => fn();
+    this.runnerAsync = (fn) => fn();
+    return (this.active = false);
+  }
+  getEnv() {
+    return this.env;
+  }
+  isActive() {
+    return this.active;
+  }
+  getEntryCount() {
+    return this.index;
+  }
+  run(fn, label, meta) {
+    return this.runner(fn, label, meta);
+  }
+  async runAsync(fn, label, meta) {
+    return this.runnerAsync(fn, label, meta);
+  }
+  start(label) {
+    const session = crypto.randomUUID();
+    this.tl.set(session, {
+      label,
+      time: this.now(),
+      mem: this.options.trackMem ? this.mem() : undefined
+    });
+    return session;
+  }
+  end(session) {
+    const start = this.tl.get(session);
+    if (!start)
+      throw new Error(
+        `No active profiling session found for label: ${session}`
+      );
+    this.tl.delete(session);
+    this.record(
+      this.now() - start.time,
+      this.options.trackMem ? this.mem() - start.mem : undefined,
+      undefined,
+      start.label
+    );
+  }
+  report(label) {
+    const { entries, index } = this;
+    if (!label) return entries.slice(0, index);
+    const result = [];
+    for (let i = 0; i < index; i++) {
+      const e = entries[i];
+      if (e.label === label) result.push(e);
+    }
+    return result;
+  }
+  summary(label) {
+    const entries = this.report(label);
+    const calls = entries.length;
+    let tTotal = 0,
+      tMax = 0,
+      tMin = Infinity,
+      mTotal = 0,
+      mMax = 0,
+      mMin = Infinity;
+    for (const e of entries) {
+      const { time, mem } = e;
+      tTotal += time;
+      if (time > tMax) tMax = time;
+      if (time < tMin) tMin = time;
+      if (mem !== undefined) {
+        mTotal += mem;
+        if (mem > mMax) mMax = mem;
+        if (mem < mMin) mMin = mem;
+      }
+    }
+    const summary = {
+      calls,
+      time: {
+        total: tTotal,
+        max: tMax,
+        min: tMin === Infinity ? 0 : tMin,
+        avg: calls > 0 ? tTotal / calls : 0
+      }
+    };
+    if (mTotal > 0)
+      summary.mem = {
+        total: mTotal,
+        max: mMax,
+        min: mMin === Infinity ? 0 : mMin,
+        avg: calls > 0 ? mTotal / calls : 0
+      };
+    return summary;
+  }
+  hotspot(label) {
+    const entries = this.report(label);
+    if (entries.length === 0) return undefined;
+    let max;
+    for (const e of entries) if (!max || e.time > max.time) max = e;
+    return max;
+  }
+  histogram(label, bins = 10) {
+    const entries = this.report(label);
+    if (entries.length === 0) return [];
+    let min = Infinity;
+    let max = -Infinity;
+    for (const e of entries) {
+      const t = e.time;
+      if (t < min) min = t;
+      if (t > max) max = t;
+    }
+    if (min === Infinity) return [];
+    if (max === min) return [{ bin: min, calls: entries.length }];
+    const binSize = (max - min) / bins;
+    const histogram = new Array(bins);
+    for (let i = 0; i < bins; i++)
+      histogram[i] = { bin: min + i * binSize, calls: 0 };
+    for (const e of entries) {
+      const t = e.time;
+      let i = ((t - min) / binSize) | 0;
+      if (i >= bins) i = bins - 1;
+      histogram[i].calls++;
+    }
+    return histogram;
+  }
+  percentiles(label, ps = [50, 90, 95, 99]) {
+    const entries = this.report(label);
+    const n = entries.length;
+    if (n === 0) return [];
+    const times = new Array(n);
+    for (let i = 0; i < n; i++) times[i] = entries[i].time;
+    times.sort((a, b) => a - b);
+    const result = new Array(ps.length);
+    for (let i = 0; i < ps.length; i++) {
+      const p = ps[i];
+      const cp = p < 0 ? 0 : p > 100 ? 100 : p;
+      const idx = (cp / 100) * (n - 1);
+      const lo = idx | 0;
+      const hi = Math.ceil(idx);
+      const time =
+        lo === hi
+          ? times[lo]
+          : times[lo] + (times[hi] - times[lo]) * (idx - lo);
+      result[i] = { percentile: cp, time };
+    }
+    return result;
+  }
+  flush() {
+    const data = this.entries.slice(0, this.index);
+    this.hooks?.onFlush?.(data);
+    this.index = 0;
+    return data;
+  }
+}
+
+exports.NanoProfiler = NanoProfiler;

package/dist/nano-profiler.mjs

@@ -0,0 +1,274 @@
+const DEFAULT_OPTIONS = {
+  enabled: true,
+  trackMem: false,
+  storeResults: false,
+  sampleRate: 1,
+  maxEntries: 10_000
+};
+class NanoProfiler {
+  static globalInstance;
+  static global() {
+    return (NanoProfiler.globalInstance ??= new NanoProfiler());
+  }
+  options;
+  maxEntries;
+  sampleRate;
+  hooks;
+  env;
+  now;
+  mem;
+  runner;
+  runnerAsync;
+  active;
+  entries;
+  index = 0;
+  tl = new Map();
+  detectEnv() {
+    if (typeof process !== 'undefined' && process.versions?.node) return 'node';
+    else if (typeof performance !== 'undefined') return 'browser';
+    return 'unknown';
+  }
+  setupNow() {
+    switch (this.env) {
+      case 'node':
+        return () => {
+          const t = process.hrtime();
+          return t[0] * 1e3 + t[1] * 1e-6;
+        };
+      case 'browser':
+        return () => performance.now();
+      default:
+        return () => Date.now();
+    }
+  }
+  setupMem() {
+    switch (this.env) {
+      case 'node':
+        return () => process.memoryUsage().heapUsed;
+      case 'browser':
+        return () => performance.memory?.usedJSHeapSize ?? 0;
+      default:
+        return () => 0;
+    }
+  }
+  record(time, mem, res, label, meta) {
+    if (this.index >= this.maxEntries) return;
+    const entry = this.entries[this.index] ?? (this.entries[this.index] = {});
+    this.index++;
+    entry.time = time;
+    entry.label = label;
+    entry.mem = mem;
+    entry.res = this.options.storeResults ? res : undefined;
+    entry.meta = meta;
+    this.hooks?.onEntry?.(entry);
+  }
+  constructor(options = {}, hooks) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.maxEntries = Number(this.options.maxEntries ?? 10_000);
+    this.sampleRate = Math.max(
+      0,
+      Math.min(1, Number(this.options.sampleRate ?? 1))
+    );
+    this.hooks = hooks;
+    this.env = this.detectEnv();
+    this.now = this.setupNow();
+    this.mem = this.setupMem();
+    this.entries = new Array(this.maxEntries);
+    this.active = this.options.enabled ? this.enable() : this.disable();
+  }
+  enable() {
+    if (this.active) return true;
+    const trackMem = this.options.trackMem;
+    const sampleRate = this.sampleRate;
+    const self = this,
+      now = this.now,
+      mem = this.mem;
+    this.runner = (fn, label, meta) => {
+      if (sampleRate < 1 && Math.random() >= sampleRate) return fn();
+      const t0 = now(),
+        m0 = trackMem ? mem() : undefined;
+      let res;
+      try {
+        return (res = fn());
+      } finally {
+        self.record(
+          now() - t0,
+          trackMem ? mem() - m0 : undefined,
+          res,
+          label,
+          meta
+        );
+      }
+    };
+    this.runnerAsync = async (fn, label, meta) => {
+      if (sampleRate < 1 && Math.random() >= sampleRate) return await fn();
+      const t0 = now(),
+        m0 = trackMem ? mem() : undefined;
+      let res;
+      try {
+        return (res = await fn());
+      } finally {
+        self.record(
+          now() - t0,
+          trackMem ? mem() - m0 : undefined,
+          res,
+          label,
+          meta
+        );
+      }
+    };
+    return (this.active = true);
+  }
+  disable() {
+    this.runner = (fn) => fn();
+    this.runnerAsync = (fn) => fn();
+    return (this.active = false);
+  }
+  getEnv() {
+    return this.env;
+  }
+  isActive() {
+    return this.active;
+  }
+  getEntryCount() {
+    return this.index;
+  }
+  run(fn, label, meta) {
+    return this.runner(fn, label, meta);
+  }
+  async runAsync(fn, label, meta) {
+    return this.runnerAsync(fn, label, meta);
+  }
+  start(label) {
+    const session = crypto.randomUUID();
+    this.tl.set(session, {
+      label,
+      time: this.now(),
+      mem: this.options.trackMem ? this.mem() : undefined
+    });
+    return session;
+  }
+  end(session) {
+    const start = this.tl.get(session);
+    if (!start)
+      throw new Error(
+        `No active profiling session found for label: ${session}`
+      );
+    this.tl.delete(session);
+    this.record(
+      this.now() - start.time,
+      this.options.trackMem ? this.mem() - start.mem : undefined,
+      undefined,
+      start.label
+    );
+  }
+  report(label) {
+    const { entries, index } = this;
+    if (!label) return entries.slice(0, index);
+    const result = [];
+    for (let i = 0; i < index; i++) {
+      const e = entries[i];
+      if (e.label === label) result.push(e);
+    }
+    return result;
+  }
+  summary(label) {
+    const entries = this.report(label);
+    const calls = entries.length;
+    let tTotal = 0,
+      tMax = 0,
+      tMin = Infinity,
+      mTotal = 0,
+      mMax = 0,
+      mMin = Infinity;
+    for (const e of entries) {
+      const { time, mem } = e;
+      tTotal += time;
+      if (time > tMax) tMax = time;
+      if (time < tMin) tMin = time;
+      if (mem !== undefined) {
+        mTotal += mem;
+        if (mem > mMax) mMax = mem;
+        if (mem < mMin) mMin = mem;
+      }
+    }
+    const summary = {
+      calls,
+      time: {
+        total: tTotal,
+        max: tMax,
+        min: tMin === Infinity ? 0 : tMin,
+        avg: calls > 0 ? tTotal / calls : 0
+      }
+    };
+    if (mTotal > 0)
+      summary.mem = {
+        total: mTotal,
+        max: mMax,
+        min: mMin === Infinity ? 0 : mMin,
+        avg: calls > 0 ? mTotal / calls : 0
+      };
+    return summary;
+  }
+  hotspot(label) {
+    const entries = this.report(label);
+    if (entries.length === 0) return undefined;
+    let max;
+    for (const e of entries) if (!max || e.time > max.time) max = e;
+    return max;
+  }
+  histogram(label, bins = 10) {
+    const entries = this.report(label);
+    if (entries.length === 0) return [];
+    let min = Infinity;
+    let max = -Infinity;
+    for (const e of entries) {
+      const t = e.time;
+      if (t < min) min = t;
+      if (t > max) max = t;
+    }
+    if (min === Infinity) return [];
+    if (max === min) return [{ bin: min, calls: entries.length }];
+    const binSize = (max - min) / bins;
+    const histogram = new Array(bins);
+    for (let i = 0; i < bins; i++)
+      histogram[i] = { bin: min + i * binSize, calls: 0 };
+    for (const e of entries) {
+      const t = e.time;
+      let i = ((t - min) / binSize) | 0;
+      if (i >= bins) i = bins - 1;
+      histogram[i].calls++;
+    }
+    return histogram;
+  }
+  percentiles(label, ps = [50, 90, 95, 99]) {
+    const entries = this.report(label);
+    const n = entries.length;
+    if (n === 0) return [];
+    const times = new Array(n);
+    for (let i = 0; i < n; i++) times[i] = entries[i].time;
+    times.sort((a, b) => a - b);
+    const result = new Array(ps.length);
+    for (let i = 0; i < ps.length; i++) {
+      const p = ps[i];
+      const cp = p < 0 ? 0 : p > 100 ? 100 : p;
+      const idx = (cp / 100) * (n - 1);
+      const lo = idx | 0;
+      const hi = Math.ceil(idx);
+      const time =
+        lo === hi
+          ? times[lo]
+          : times[lo] + (times[hi] - times[lo]) * (idx - lo);
+      result[i] = { percentile: cp, time };
+    }
+    return result;
+  }
+  flush() {
+    const data = this.entries.slice(0, this.index);
+    this.hooks?.onFlush?.(data);
+    this.index = 0;
+    return data;
+  }
+}
+
+export { NanoProfiler };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "nano-profiler",
+  "description": "Fast and lightweight JavaScript profiler for measuring time and memory consumption",
+  "license": "MIT",
+  "version": "1.0.0",
+  "author": {
+    "name": "komed3 (Paul Köhler)",
+    "email": "webmaster@komed3.de",
+    "url": "https://komed3.de"
+  },
+  "homepage": "https://github.com/komed3/nano-profiler",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/komed3/nano-profiler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/komed3/nano-profiler/issues"
+  },
+  "funding": {
+    "type": "ko-fi",
+    "url": "https://ko-fi.com/komed3"
+  },
+  "files": [
+    "dist",
+    "README",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "types": "dist/NanoProfiler.d.ts",
+  "main": "dist/nano-profiler.cjs.js",
+  "module": "dist/nano-profiler.esm.js",
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^25.5.0",
+    "rollup": "^4.59.0",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-prettier": "^4.1.2",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3"
+  }
+}