@universal-packages/time-measurer 1.6.0 → 2.1.0

package/README.md

@@ -6,108 +6,610 @@
 
 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"
+```
+
+### Constructor <small><small>`constructor`</small></small>
 
-getAll()
-// > All records - 2.23ms
+```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
+```
 
-async function getAll() {
-  const measurer = new TimeMeasurer()
+Finishes the time measurement and returns a `Measurement` instance containing the elapsed time.
 
-  measurer.start()
+```ts
+const measurer = new TimeMeasurer()
+measurer.start()
+// ... some operation
+const measurement = measurer.finish()
+```
 
-  const data = await myDB.getAllRecords()
-  const measurement = measurer.finish()
+### Static Methods
 
-  console.log('All records - ', measurement.toString())
-}
+#### start
+
+```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, convenient accessors for different time units, arithmetic operations, and comparison capabilities.
+
+```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
+
+// Arithmetic operations
+const measurement1 = new Measurement(1000000000n) // 1 second
+const measurement2 = new Measurement(2000000000n) // 2 seconds
+
+const sum = measurement1.add(measurement2)
+console.log(sum.toString()) // "3.000sec"
+
+// Comparison operations
+console.log(measurement1 < measurement2) // true
+console.log(measurement1.lessThan(measurement2)) // true
+```
+
+### 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)
+- **`nanoseconds`**: `bigint` - The total nanoseconds of the measurement
+
+### Instance Methods
+
+#### Arithmetic Operations
+
+##### add
+
+```ts
+add(other: Measurement): Measurement
+```
+
+Adds another measurement to this one and returns a new measurement with the sum of both times.
+
+```ts
+const measurement1 = new Measurement(1000000000n) // 1 second
+const measurement2 = new Measurement(500000000n)  // 0.5 seconds
+const sum = measurement1.add(measurement2)
+console.log(sum.toString()) // "1.500sec"
+```
+
+##### subtract
+
+```ts
+subtract(other: Measurement): Measurement
+```
+
+Subtracts another measurement from this one and returns a new measurement with the difference. If the result would be negative, returns a zero measurement.
+
+```ts
+const measurement1 = new Measurement(2000000000n) // 2 seconds
+const measurement2 = new Measurement(500000000n)  // 0.5 seconds
+const difference = measurement1.subtract(measurement2)
+console.log(difference.toString()) // "1.500sec"
+
+// Negative results are clamped to zero
+const negative = measurement2.subtract(measurement1)
+console.log(negative.toString()) // "0.00ms"
+```
+
+#### Comparison Methods
+
+##### equals
+
+```ts
+equals(other: Measurement): boolean
+```
+
+Checks if this measurement is equal to another measurement.
+
+```ts
+const measurement1 = new Measurement(1000000000n)
+const measurement2 = new Measurement(1000000000n)
+console.log(measurement1.equals(measurement2)) // true
+```
+
+##### lessThan
+
+```ts
+lessThan(other: Measurement): boolean
+```
+
+Checks if this measurement is less than another measurement.
+
+```ts
+const measurement1 = new Measurement(500000000n)  // 0.5 seconds
+const measurement2 = new Measurement(1000000000n) // 1 second
+console.log(measurement1.lessThan(measurement2)) // true
+```
+
+##### greaterThan
+
+```ts
+greaterThan(other: Measurement): boolean
+```
+
+Checks if this measurement is greater than another measurement.
+
+```ts
+console.log(measurement2.greaterThan(measurement1)) // true
+```
+
+##### lessThanOrEqual
+
+```ts
+lessThanOrEqual(other: Measurement): boolean
+```
+
+Checks if this measurement is less than or equal to another measurement.
+
+##### greaterThanOrEqual
+
+```ts
+greaterThanOrEqual(other: Measurement): boolean
+```
+
+Checks if this measurement is greater than or equal to another measurement.
+
+#### Operator Overloading
+
+The `Measurement` class supports JavaScript's native comparison and arithmetic operators through `Symbol.toPrimitive`:
+
+```ts
+const measurement1 = new Measurement(1000000000n) // 1 second
+const measurement2 = new Measurement(2000000000n) // 2 seconds
+
+// Comparison operators (recommended)
+console.log(measurement1 < measurement2)  // true
+console.log(measurement1 > measurement2)  // false
+console.log(measurement1 <= measurement2) // true
+console.log(measurement1 >= measurement2) // false
+console.log(measurement1 == measurement2) // false
+console.log(measurement1 != measurement2) // true
+
+// Arithmetic operators (returns numbers in nanoseconds)
+console.log(measurement1 + measurement2) // 3000000000 (nanoseconds)
+console.log(measurement2 - measurement1) // 1000000000 (nanoseconds)
+
+// For arithmetic operations that return Measurement objects, use methods:
+const sum = measurement1.add(measurement2)     // Returns Measurement
+const diff = measurement2.subtract(measurement1) // Returns Measurement
+```
+
+#### Method Chaining
+
+All arithmetic methods return new `Measurement` instances, allowing for method chaining:
+
+```ts
+const base = new Measurement(1000000000n)    // 1 second
+const half = new Measurement(500000000n)     // 0.5 seconds
+const quarter = new Measurement(250000000n)  // 0.25 seconds
+
+const result = base.add(half).subtract(quarter)
+console.log(result.toString()) // "1.250sec"
+```
+
+#### 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
+
+## 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)
+```
+
+Creates a new TimeProfiler instance with the specified options.
+
+#### ProfilerOptions
+
+- **`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.
+
+### Properties
+
+#### checkpoints
+
+```ts
+readonly checkpoints: ProfilerCheckpoint[]
+```
+
+Returns a copy of all checkpoints recorded so far.
+
+#### lastCheckpoint
+
+```ts
+readonly lastCheckpoint: ProfilerCheckpoint | undefined
+```
+
+Returns the most recently recorded checkpoint, or undefined if none exist.
+
+#### isRunning
+
+```ts
+readonly isRunning: boolean
+```
+
+Returns true if the profiler is currently active and measuring time.
+
+#### elapsed
+
+```ts
+readonly elapsed: Measurement | undefined
+```
+
+Returns the current elapsed time since the profiler was started, or undefined if not started.
 
-getAll()
-// > All records - 2.23ms
+### Instance Methods
+
+#### start
+
+```ts
+start(): void
+```
+
+Starts the profiling session. Throws an error if already started.
+
+```ts
+const profiler = new TimeProfiler()
+profiler.start()
 ```
 
-### Instance methods
+#### checkpoint
 
-#### **`start()`**
+```ts
+checkpoint(name: string): Measurement
+```
 
-Resets the initial time.
+Creates a named checkpoint and returns the measurement from the start time. Throws an error if not started.
 
-#### **`stop()`**
+```ts
+profiler.checkpoint('Database connected')
+// ... more operations
+profiler.checkpoint('Data processed')
+```
 
-Returns a measurement representing the time passed from when start was called.
+#### getCheckpoint
 
-## Measurement
+```ts
+getCheckpoint(name: string): ProfilerCheckpoint | undefined
+```
 
-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.
+Retrieves a specific checkpoint by name.
 
-### Instance methods
+```ts
+const dbCheckpoint = profiler.getCheckpoint('Database connected')
+if (dbCheckpoint) {
+  console.log(`DB connection took: ${dbCheckpoint.measurement.toString()}`)
+}
+```
 
-#### **`toString(format: TimeFormat)`**
+#### stop
 
-Get the time representation as a string, this function takes one param `TimeFormat`, that can be one of `Condensed`, `Human`, `Expressive`, default: `Human`.
+```ts
+stop(finalCheckpointName?: string): ProfilerCheckpoint[]
+```
 
-Example output
+Stops the profiler, creates a final checkpoint, and returns all checkpoints.
 
+```ts
+const allCheckpoints = profiler.stop('Session Complete')
 ```
-2hrs 35min 51.235sec
-2:35:51.235
-2hrs 35min 51.235sec
-2 Hours, 35 Minutes, and 51.235 Seconds
+
+#### reset
+
+```ts
+reset(): void
 ```
 
-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.
+Resets the profiler state to start a new session.
 
+```ts
+profiler.reset()
+profiler.start() // Ready for a new session
 ```
-51.235sec
-51.235
-51.235sec
-51.235 Seconds
+
+### 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"}