@universal-packages/time-measurer 1.5.0 → 2.0.0

package/README.md

@@ -6,108 +6,466 @@
 
 Time Measurer is a simple wrap for `process.hrtime.bigint` to measure time with procession and express that time easily through formatted representations, anytime you want to express how much a query or a request took at code level you may want to give this a try.
 
-## Install
+# Getting Started
 
 ```shell
 npm install @universal-packages/time-measurer
 ```
 
-## Global methods
+# Usage
 
-#### **`startMeasurement()`**
+## TimeMeasurer `class`
 
-Creates a new TimeMeasurer instance to start a measurement.
+The `TimeMeasurer` class is a simple utility for measuring time with precision. It wraps `process.hrtime.bigint()` for Node.js environments and falls back to `performance.now()` in browser environments.
 
 ```ts
-import { startMeasurement } from '@universal-packages/time-measurer'
+import { TimeMeasurer } from '@universal-packages/time-measurer'
 
-async function getAll() {
-  const measurer = startMeasurement()
-  const data = await myDB.getAllRecords()
-  const measurement = measurer.finish()
+const measurer = TimeMeasurer.start()
+// ... some operation
+const measurement = measurer.finish()
 
-  console.log('All records - ', measurement.toString())
-}
+console.log(measurement.toString()) // "123.456ms"
+```
 
-getAll()
-// > All records - 2.23ms
+### Constructor <small><small>`constructor`</small></small>
+
+```ts
+new TimeMeasurer()
 ```
 
-#### **`sleep(milliseconds: number)`**
+Creates a new TimeMeasurer instance. The measurer is not started automatically.
 
-Time measurer ships with a convenient sleep function that takes a single parameter `time` in milliseconds, internally it is just a promise with a timeout that resolves it.
+### Instance Methods
 
-```js
-import { sleep } from '@universal-packages/time-measurer'
+#### start
 
-async function awaitable() {
-  await sleep(2000)
-}
+```ts
+start(): void
 ```
 
-## TimeMeasurer
+Starts the time measurement. This method will throw an error if the measurer has already been started.
+
+```ts
+const measurer = new TimeMeasurer()
+measurer.start()
+// ... some operation
+const measurement = measurer.finish()
+```
 
-Class `TimeMeasurer` provides an instantiable interface to start measuring time from any part of your code. The measurement starts at instancing time.
+#### finish
 
-```js
-import { TimeMeasurer } from '@universal-packages/time-measurer'
+```ts
+finish(): Measurement
+```
+
+Finishes the time measurement and returns a `Measurement` instance containing the elapsed time.
 
-async function getAll() {
-  const measurer = new TimeMeasurer()
+```ts
+const measurer = new TimeMeasurer()
+measurer.start()
+// ... some operation
+const measurement = measurer.finish()
+```
 
-  measurer.start()
+### Static Methods
 
-  const data = await myDB.getAllRecords()
-  const measurement = measurer.finish()
+#### start
 
-  console.log('All records - ', measurement.toString())
-}
+```ts
+static start(): TimeMeasurer
+```
+
+Creates a new TimeMeasurer instance and immediately starts it. This is a convenience method for quick measurements.
+
+```ts
+const measurer = TimeMeasurer.start()
+// ... some operation
+const measurement = measurer.finish()
+```
+
+## Measurement `class`
+
+The `Measurement` class represents a measured time duration with various formatting options and convenient accessors for different time units.
+
+```ts
+import { Measurement, TimeMeasurer } from '@universal-packages/time-measurer'
+
+const measurer = TimeMeasurer.start()
+// ... some operation
+const measurement = measurer.finish()
+
+console.log(measurement.hours) // 0
+console.log(measurement.minutes) // 0
+console.log(measurement.seconds) // 1
+console.log(measurement.milliseconds) // 234.567
+```
+
+### Constructor <small><small>`constructor`</small></small>
+
+```ts
+new Measurement(nanoseconds: bigint)
+```
+
+Creates a new Measurement instance from nanoseconds. This is typically called internally by TimeMeasurer.
+
+### Properties
+
+- **`hours`**: `number` - The hours component of the measurement
+- **`minutes`**: `number` - The minutes component of the measurement
+- **`seconds`**: `number` - The seconds component of the measurement
+- **`milliseconds`**: `number` - The milliseconds component (including fractional part)
+
+### Instance Methods
+
+#### toString
+
+```ts
+toString(format?: TimeFormat): string
+```
+
+Converts the measurement to a formatted string representation.
+
+```ts
+const measurement = new Measurement(1234567890n)
+
+console.log(measurement.toString('Human')) // "1.234sec"
+console.log(measurement.toString('Condensed')) // "1.234"
+console.log(measurement.toString('Expressive')) // "1.234 Seconds"
+```
+
+##### TimeFormat
+
+- **`'Human'`** (default): User-friendly format like "1.234sec", "2min 30.500sec", "1hrs 15min 30.250sec"
+- **`'Condensed'`**: Compact format like "1.234", "02:30.500", "01:15:30.250"
+- **`'Expressive'`**: Verbose format like "1.234 Seconds", "2 Minutes, and 30.500 Seconds"
+
+#### toDate
+
+```ts
+toDate(): Date
+```
+
+Converts the measurement to a JavaScript Date object with the time components.
+
+```ts
+const measurement = new Measurement(3661000000000n) // 1 hour, 1 minute, 1 second
+const date = measurement.toDate()
+console.log(date.getHours()) // 1
+console.log(date.getMinutes()) // 1
+console.log(date.getSeconds()) // 1
+```
+
+## Benchmark `class`
+
+The `Benchmark` class provides functionality for running performance benchmarks with support for multiple iterations, warmup runs, and statistical analysis.
+
+```ts
+import { Benchmark } from '@universal-packages/time-measurer'
+
+const benchmark = new Benchmark({
+  iterations: 1000,
+  warmupIterations: 100,
+  name: 'Array sorting benchmark'
+})
+
+const result = benchmark.run(() => {
+  const arr = Array.from({ length: 1000 }, () => Math.random())
+  arr.sort()
+})
+
+console.log(`Average: ${result.average.toString()}`)
+console.log(`Min: ${result.min.toString()}`)
+console.log(`Max: ${result.max.toString()}`)
+```
+
+### Constructor <small><small>`constructor`</small></small>
+
+```ts
+new Benchmark(options?: BenchmarkOptions)
+```
+
+Creates a new Benchmark instance with the specified options.
+
+#### BenchmarkOptions
+
+- **`iterations`**: `number` (default: `1`)
+  Number of iterations to run for the actual benchmark measurement.
+- **`warmupIterations`**: `number` (default: `0`)
+  Number of warmup iterations to run before the actual measurement to stabilize performance.
+- **`name`**: `string` (default: `'Unnamed Benchmark'`)
+  A descriptive name for the benchmark.
+
+### Instance Methods
+
+#### run
+
+```ts
+run(fn: () => void): BenchmarkResult
+```
+
+Runs a synchronous function benchmark and returns detailed results including statistics.
+
+```ts
+const benchmark = new Benchmark({ iterations: 100 })
+
+const result = benchmark.run(() => {
+  // Your code to benchmark
+  heavyComputation()
+})
+
+console.log(`Completed ${result.iterations} iterations`)
+console.log(`Average time: ${result.average.toString()}`)
+```
+
+#### runAsync
+
+```ts
+runAsync(fn: () => Promise<void>): Promise<BenchmarkResult>
+```
+
+Runs an asynchronous function benchmark and returns detailed results including statistics.
+
+```ts
+const benchmark = new Benchmark({ iterations: 50 })
+
+const result = await benchmark.runAsync(async () => {
+  // Your async code to benchmark
+  await asyncOperation()
+})
+
+console.log(`Average time: ${result.average.toString()}`)
+```
+
+#### BenchmarkResult
+
+The result object returned by `run()` and `runAsync()` contains:
+
+- **`name`**: `string` - Name of the benchmark
+- **`iterations`**: `number` - Number of iterations performed
+- **`warmupIterations`**: `number` - Number of warmup iterations performed
+- **`measurements`**: `Measurement[]` - Array of all individual measurements
+- **`min`**: `Measurement` - Fastest measurement
+- **`max`**: `Measurement` - Slowest measurement
+- **`average`**: `Measurement` - Average of all measurements
+- **`total`**: `Measurement` - Total time for all iterations
 
-getAll()
-// > All records - 2.23ms
+## TimeProfiler `class`
+
+The `TimeProfiler` class provides advanced profiling capabilities with named checkpoints, memory tracking, and session management for detailed performance analysis.
+
+```ts
+import { TimeProfiler } from '@universal-packages/time-measurer'
+
+const profiler = TimeProfiler.start('Database Operations')
+
+// Start some operation
+const users = await db.users.findMany()
+profiler.checkpoint('Users loaded')
+
+// Another operation
+const posts = await db.posts.findMany()
+profiler.checkpoint('Posts loaded')
+
+// Finish profiling
+const checkpoints = profiler.stop('Complete')
+
+checkpoints.forEach((cp) => {
+  console.log(`${cp.name}: ${cp.measurement.toString()}`)
+})
+```
+
+### Constructor <small><small>`constructor`</small></small>
+
+```ts
+new TimeProfiler(options?: ProfilerOptions)
 ```
 
-### Instance methods
+Creates a new TimeProfiler instance with the specified options.
 
-#### **`start()`**
+#### ProfilerOptions
 
-Resets the initial time.
+- **`name`**: `string` (default: `'Profiler Session'`)
+  A descriptive name for the profiling session.
+- **`trackMemory`**: `boolean` (default: `false`)
+  Whether to track memory usage and deltas between checkpoints.
 
-#### **`stop()`**
+### Properties
 
-Returns a measurement representing the time passed from when start was called.
+#### checkpoints
 
-## Measurement
+```ts
+readonly checkpoints: ProfilerCheckpoint[]
+```
 
-A `Measurement` object is the time representation after a measure, it provides the interface to express time as a formatted string or even as a date object.
+Returns a copy of all checkpoints recorded so far.
 
-### Instance methods
+#### lastCheckpoint
 
-#### **`toString(format: TimeFormat)`**
+```ts
+readonly lastCheckpoint: ProfilerCheckpoint | undefined
+```
 
-Get the time representation as a string, this function takes one param `TimeFormat`, that can be one of `Condensed`, `Human`, `Expressive`, default: `Human`.
+Returns the most recently recorded checkpoint, or undefined if none exist.
 
-Example output
+#### isRunning
 
+```ts
+readonly isRunning: boolean
 ```
-2hrs 35min 51.235sec
-2:35:51.235
-2hrs 35min 51.235sec
-2 Hours, 35 Minutes, and 51.235 Seconds
+
+Returns true if the profiler is currently active and measuring time.
+
+#### elapsed
+
+```ts
+readonly elapsed: Measurement | undefined
 ```
 
-It will take into account parts of the representation that are not contributing to the time, like if the measurement only took seconds, minutes and hours will not be included.
+Returns the current elapsed time since the profiler was started, or undefined if not started.
 
+### Instance Methods
+
+#### start
+
+```ts
+start(): void
 ```
-51.235sec
-51.235
-51.235sec
-51.235 Seconds
+
+Starts the profiling session. Throws an error if already started.
+
+```ts
+const profiler = new TimeProfiler()
+profiler.start()
+```
+
+#### checkpoint
+
+```ts
+checkpoint(name: string): Measurement
+```
+
+Creates a named checkpoint and returns the measurement from the start time. Throws an error if not started.
+
+```ts
+profiler.checkpoint('Database connected')
+// ... more operations
+profiler.checkpoint('Data processed')
+```
+
+#### getCheckpoint
+
+```ts
+getCheckpoint(name: string): ProfilerCheckpoint | undefined
+```
+
+Retrieves a specific checkpoint by name.
+
+```ts
+const dbCheckpoint = profiler.getCheckpoint('Database connected')
+if (dbCheckpoint) {
+  console.log(`DB connection took: ${dbCheckpoint.measurement.toString()}`)
+}
+```
+
+#### stop
+
+```ts
+stop(finalCheckpointName?: string): ProfilerCheckpoint[]
+```
+
+Stops the profiler, creates a final checkpoint, and returns all checkpoints.
+
+```ts
+const allCheckpoints = profiler.stop('Session Complete')
+```
+
+#### reset
+
+```ts
+reset(): void
+```
+
+Resets the profiler state to start a new session.
+
+```ts
+profiler.reset()
+profiler.start() // Ready for a new session
+```
+
+### Static Methods
+
+#### start
+
+```ts
+static start(name?: string): TimeProfiler
+```
+
+Creates and immediately starts a new TimeProfiler instance.
+
+```ts
+const profiler = TimeProfiler.start('API Request Processing')
+```
+
+#### ProfilerCheckpoint
+
+Each checkpoint contains:
+
+- **`name`**: `string` - Name/label for the checkpoint
+- **`measurement`**: `Measurement` - Time elapsed from start to this checkpoint
+- **`timestamp`**: `Date` - When the checkpoint was created
+- **`memoryUsage`**: `number` (optional) - Memory usage in bytes (if tracking enabled)
+- **`memoryDelta`**: `number` (optional) - Memory change from previous checkpoint (if tracking enabled)
+
+### Memory Tracking Example
+
+```ts
+const profiler = new TimeProfiler({ trackMemory: true })
+profiler.start()
+
+// Create some data
+const largeArray = new Array(1000000).fill('data')
+const checkpoint1 = profiler.checkpoint('Array created')
+
+// Process data
+largeArray.forEach((item) => item.toUpperCase())
+const checkpoint2 = profiler.checkpoint('Array processed')
+
+console.log(`Memory at checkpoint 1: ${checkpoint1.memoryUsage} bytes`)
+console.log(`Memory delta: ${checkpoint2.memoryDelta} bytes`)
+```
+
+## Sleep `class`
+
+The `Sleep` class provides a simple utility for creating delays in asynchronous code using human-readable time strings. It leverages the `ms` library for flexible time string parsing.
+
+```ts
+import { Sleep } from '@universal-packages/time-measurer'
+
+// Wait for 2 seconds
+await Sleep.for('2s')
+
+// Wait for 1.5 seconds
+await Sleep.for('1500ms')
+
+// Wait for 2 minutes
+await Sleep.for('2m')
+
+// Wait for 1 hour
+await Sleep.for('1h')
+```
+
+### Static Methods
+
+#### for
+
+```ts
+static for(timeString: StringValue): Promise<void>
 ```
 
-#### **`toDate()`**
+Creates a delay for the specified duration using a human-readable time string. Returns a Promise that resolves after the specified time has elapsed.
 
-Get the time representation as a date object this can be helpful if you want to use the `Date` api to format or do whatever with the date.
+The `timeString` parameter accepts the same format as the `ms` library
 
 ## Typescript
 

package/Sleep.d.ts

@@ -0,0 +1,5 @@
+import { StringValue } from 'ms';
+export declare class Sleep {
+    static for(timeString: StringValue): Promise<void>;
+}
+//# sourceMappingURL=Sleep.d.ts.map

package/Sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sleep.d.ts","sourceRoot":"","sources":["../src/Sleep.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,WAAW,EAAE,MAAM,IAAI,CAAA;AAEpC,qBAAa,KAAK;WACI,GAAG,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAIhE"}

package/Sleep.js

@@ -0,0 +1,8 @@
+import ms from 'ms';
+export class Sleep {
+    static async for(timeString) {
+        const duration = ms(timeString);
+        return new Promise((resolve) => setTimeout(resolve, duration));
+    }
+}
+//# sourceMappingURL=Sleep.js.map

package/Sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sleep.js","sourceRoot":"","sources":["../src/Sleep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,MAAM,IAAI,CAAA;AAEpC,MAAM,OAAO,KAAK;IACT,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAuB;QAC7C,MAAM,QAAQ,GAAG,EAAE,CAAC,UAAU,CAAC,CAAA;QAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAA;IAChE,CAAC;CACF"}

package/TimeMeasurer.d.ts

@@ -1,15 +1,20 @@
-import Measurement from './Measurement';
-/**
- *
- * It measures the time a process takes from the time start is called
- * to when the finish method is called
- *
- */
-export default class TimeMeasurer {
+import { Measurement } from './Measurement';
+export declare class TimeMeasurer {
     private hrStart;
     private startTime;
-    /** Resets the initial time */
+    /**
+     * Start a new measurer
+     * @returns Measurer instance
+     */
+    static start(): TimeMeasurer;
+    /**
+     * Start the measurer
+     */
     start(): void;
-    /** Returns a measurement representing the time passed from when start was called */
+    /**
+     * Finish the measurer
+     * @returns Measurement instance
+     */
     finish(): Measurement;
 }
+//# sourceMappingURL=TimeMeasurer.d.ts.map

package/TimeMeasurer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeMeasurer.d.ts","sourceRoot":"","sources":["../src/TimeMeasurer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,SAAS,CAAY;IAE7B;;;OAGG;WACW,KAAK,IAAI,YAAY;IAMnC;;OAEG;IACI,KAAK,IAAI,IAAI;IAYpB;;;OAGG;IACI,MAAM,IAAI,WAAW;CAW7B"}

package/TimeMeasurer.js

@@ -1,22 +1,23 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const Measurement_1 = __importDefault(require("./Measurement"));
-/**
- *
- * It measures the time a process takes from the time start is called
- * to when the finish method is called
- *
- */
-class TimeMeasurer {
-    constructor() {
-        this.hrStart = 0n;
-        this.startTime = 0;
+import { Measurement } from './Measurement';
+export class TimeMeasurer {
+    hrStart = 0n;
+    startTime = 0;
+    /**
+     * Start a new measurer
+     * @returns Measurer instance
+     */
+    static start() {
+        const measurer = new TimeMeasurer();
+        measurer.start();
+        return measurer;
     }
-    /** Resets the initial time */
+    /**
+     * Start the measurer
+     */
     start() {
+        if (this.hrStart || this.startTime) {
+            throw new Error('Measurer already started');
+        }
         if (typeof process !== 'undefined' && process.hrtime) {
             this.hrStart = process.hrtime.bigint();
         }
@@ -24,7 +25,10 @@ class TimeMeasurer {
             this.startTime = performance.now();
         }
     }
-    /** Returns a measurement representing the time passed from when start was called */
+    /**
+     * Finish the measurer
+     * @returns Measurement instance
+     */
     finish() {
         let nanoseconds;
         if (typeof process !== 'undefined' && process.hrtime) {
@@ -34,8 +38,7 @@ class TimeMeasurer {
             const milliseconds = performance.now() - this.startTime;
             nanoseconds = BigInt(Math.round(milliseconds * 1e6));
         }
-        return new Measurement_1.default(nanoseconds);
+        return new Measurement(nanoseconds);
     }
 }
-exports.default = TimeMeasurer;
 //# sourceMappingURL=TimeMeasurer.js.map

package/TimeMeasurer.js.map

@@ -1 +1 @@
-{"version":3,"file":"TimeMeasurer.js","sourceRoot":"","sources":["../src/TimeMeasurer.ts"],"names":[],"mappings":";;;;;AAAA,gEAAuC;AAEvC;;;;;GAKG;AACH,MAAqB,YAAY;IAAjC;QACU,YAAO,GAAW,EAAE,CAAA;QACpB,cAAS,GAAW,CAAC,CAAA;IAuB/B,CAAC;IArBC,8BAA8B;IACvB,KAAK;QACV,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACrD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAA;QACxC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;QACpC,CAAC;IACH,CAAC;IAED,oFAAoF;IAC7E,MAAM;QACX,IAAI,WAAmB,CAAA;QACvB,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACrD,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAA;QACtD,CAAC;aAAM,CAAC;YACN,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAA;YACvD,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,CAAA;QACtD,CAAC;QAED,OAAO,IAAI,qBAAW,CAAC,WAAW,CAAC,CAAA;IACrC,CAAC;CACF;AAzBD,+BAyBC"}
+{"version":3,"file":"TimeMeasurer.js","sourceRoot":"","sources":["../src/TimeMeasurer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,MAAM,OAAO,YAAY;IACf,OAAO,GAAW,EAAE,CAAA;IACpB,SAAS,GAAW,CAAC,CAAA;IAE7B;;;OAGG;IACI,MAAM,CAAC,KAAK;QACjB,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAA;QACnC,QAAQ,CAAC,KAAK,EAAE,CAAA;QAChB,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED;;OAEG;IACI,KAAK;QACV,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;QAC7C,CAAC;QAED,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACrD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAA;QACxC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;QACpC,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,MAAM;QACX,IAAI,WAAmB,CAAA;QACvB,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACrD,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAA;QACtD,CAAC;aAAM,CAAC;YACN,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAA;YACvD,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,CAAA;QACtD,CAAC;QAED,OAAO,IAAI,WAAW,CAAC,WAAW,CAAC,CAAA;IACrC,CAAC;CACF"}