@pawells/typescript-common 2.0.0 → 2.1.6

package/dist/time/elapsed-time/types.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Represents a single time unit with its numeric value.
+ * Used internally for formatting operations to map unit names to their calculated values.
+ *
+ * @example
+ * ```typescript
+ * const hour: ITimeUnitValue = { unit: 'hour', value: 2 };
+ * const minutes: ITimeUnitValue = { unit: 'minute', value: 30 };
+ * ```
+ */
+export interface ITimeUnitValue {
+    /** The time unit type (week, day, hour, minute, second, millisecond) */
+    unit: TTimeUnit;
+    /** The numeric value for this time unit */
+    value: number;
+}
+/**
+ * Complete formatting options for elapsed time output.
+ * Controls how time values are displayed, including negative value handling, unit visibility, and label customization.
+ *
+ * @example
+ * ```typescript
+ * // Show at most 2 units, hide zero-valued units, wrap negative values in parentheses
+ * const options: ITimeElapsedFormatOptions = {
+ *   maxUnits: 2,
+ *   showZeroValues: false,
+ *   negativeValueFormat: 'Parenthesis'
+ * };
+ *
+ * const elapsed = new ElapsedTime(-3661000);
+ * elapsed.Format('medium', options); // "(1 hour 1 min)"
+ * ```
+ */
+export interface ITimeElapsedFormatOptions {
+    /** How to format negative values: 'Empty' (no indicator), 'NegativeSign' (prefix with -), 'Parenthesis' (wrap in parentheses), or 'Brackets' (wrap in brackets) */
+    negativeValueFormat?: 'Empty' | 'NegativeSign' | 'Parenthesis' | 'Brackets' | undefined;
+    /** Show zero value units in formatter output (default: false) */
+    showZeroValues?: boolean | undefined;
+    /** Maximum number of units to include in formatter output (default: unlimited) */
+    maxUnits?: number | undefined;
+    /** Custom unit labels for formatter */
+    unitLabels?: {
+        week?: string | ((_value: number) => string) | undefined;
+        day?: string | ((_value: number) => string) | undefined;
+        hour?: string | ((_value: number) => string) | undefined;
+        minute?: string | ((_value: number) => string) | undefined;
+        second?: string | ((_value: number) => string) | undefined;
+        millisecond?: string | ((_value: number) => string) | undefined;
+    } | undefined;
+}
+/**
+ * Predefined time format styles for elapsed time display.
+ *
+ * - `concise` - Ultra-compact single-letter units: "1h 30m 45s"
+ * - `short` - Abbreviated readable units: "1hr 30min 45sec"
+ * - `medium` - Balanced readability: "1 hour 30 min 45 sec"
+ * - `long` - Full English words with pluralization: "1 hour 30 minutes 45 seconds"
+ * - `mostSignificant` - Only the 2 most significant units: "1 hour 30 min"
+ * - `time` - Clock format with hours and minutes: "1:30"
+ * - `timeWithSeconds` - Extended clock format: "1:30:45"
+ *
+ * @example
+ * ```typescript
+ * const elapsed = new ElapsedTime(5425000); // 1h 30m 25s
+ *
+ * elapsed.Format('concise');      // "1h 30m 25s"
+ * elapsed.Format('short');        // "1hr 30min 25sec"
+ * elapsed.Format('medium');       // "1 hour 30 min 25 sec"
+ * elapsed.Format('long');         // "1 hour 30 minutes 25 seconds"
+ * ```
+ */
+export type TTimeElapsedFormats = 'concise' | 'short' | 'medium' | 'long' | 'mostSignificant' | 'time' | 'timeWithSeconds';
+/**
+ * Available time unit types for elapsed time calculations and formatting.
+ * Each unit represents a standard time component used in duration decomposition.
+ *
+ * @example
+ * ```typescript
+ * const units: TTimeUnit[] = ['week', 'day', 'hour', 'minute', 'second', 'millisecond'];
+ * ```
+ */
+export type TTimeUnit = 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+/**
+ * Static string label for a time unit.
+ * Used for format styles that use fixed labels regardless of value (e.g., "h", "min", "sec").
+ *
+ * @example
+ * ```typescript
+ * const label: TUnitLabelString = "h";
+ * const label2: TUnitLabelString = "hour";
+ * ```
+ */
+export type TUnitLabelString = string;
+/**
+ * Function that generates a time unit label with support for pluralization.
+ * Accepts the numeric value and returns the appropriate label string.
+ *
+ * @param value - The numeric value to determine singular/plural form
+ * @returns The appropriate label string (e.g., "hour" or "hours")
+ *
+ * @example
+ * ```typescript
+ * const pluralize: TUnitLabelFunction = (value: number) =>
+ *   value === 1 ? 'hour' : 'hours';
+ *
+ * console.log(pluralize(1)); // "hour"
+ * console.log(pluralize(2)); // "hours"
+ * ```
+ */
+export type TUnitLabelFunction = (value: number) => string;
+/**
+ * Unit label as either a static string or a function with pluralization support.
+ * Allows flexible label definitions for different formatting styles.
+ *
+ * @example
+ * ```typescript
+ * // Static string label
+ * const label1: TUnitLabel = "h";
+ *
+ * // Function-based label with pluralization
+ * const label2: TUnitLabel = (value: number) => value === 1 ? 'hour' : 'hours';
+ * ```
+ */
+export type TUnitLabel = TUnitLabelString | TUnitLabelFunction;
+/**
+ * Mapping of time units to their corresponding labels.
+ * Base interface that all unit label configurations implement.
+ *
+ * @example
+ * ```typescript
+ * const labels: IUnitLabelMap = {
+ *   millisecond: 'ms',
+ *   second: 's',
+ *   minute: 'm',
+ *   hour: 'h',
+ *   day: 'd',
+ *   week: 'w'
+ * };
+ * ```
+ */
+export interface IUnitLabelMap {
+    /** Label for milliseconds */
+    millisecond: TUnitLabel;
+    /** Label for seconds */
+    second: TUnitLabel;
+    /** Label for minutes */
+    minute: TUnitLabel;
+    /** Label for hours */
+    hour: TUnitLabel;
+    /** Label for days */
+    day: TUnitLabel;
+    /** Label for weeks */
+    week: TUnitLabel;
+}
+/**
+ * Concise format style with single-character unit labels.
+ * Used for ultra-compact time representations (e.g., "1h 30m 45s").
+ *
+ * @example
+ * ```typescript
+ * const labels: IConciseUnitLabels = {
+ *   style: 'concise',
+ *   millisecond: 'ms',
+ *   second: 's',
+ *   minute: 'm',
+ *   hour: 'h',
+ *   day: 'd',
+ *   week: 'w'
+ * };
+ * ```
+ */
+export interface IConciseUnitLabels extends IUnitLabelMap {
+    readonly style?: 'concise';
+    millisecond: 'ms';
+    second: 's';
+    minute: 'm';
+    hour: 'h';
+    day: 'd';
+    week: 'w';
+}
+/**
+ * Long format style with full English words and proper pluralization support.
+ * Used for readable time representations (e.g., "1 hour 30 minutes 45 seconds").
+ * All labels are functions that handle singular/plural forms based on the value.
+ *
+ * @example
+ * ```typescript
+ * const labels: ILongUnitLabels = {
+ *   style: 'long',
+ *   hour: (value) => value === 1 ? 'hour' : 'hours',
+ *   minute: (value) => value === 1 ? 'minute' : 'minutes'
+ * };
+ *
+ * labels.hour(1);  // "hour"
+ * labels.hour(2);  // "hours"
+ * ```
+ */
+export interface ILongUnitLabels extends IUnitLabelMap {
+    readonly style?: 'long';
+    millisecond: TUnitLabelFunction;
+    second: TUnitLabelFunction;
+    minute: TUnitLabelFunction;
+    hour: TUnitLabelFunction;
+    day: TUnitLabelFunction;
+    week: TUnitLabelFunction;
+}
+/**
+ * Medium format style with abbreviated but readable unit labels.
+ * Provides a balanced middle ground between concise and long formats.
+ * Used for moderately compact time representations (e.g., "1 hour 30 min 45 sec").
+ *
+ * @example
+ * ```typescript
+ * const labels: IMediumUnitLabels = {
+ *   style: 'medium',
+ *   millisecond: 'ms',
+ *   second: 'sec',
+ *   minute: 'min',
+ *   hour: 'hour',
+ *   day: 'day',
+ *   week: 'week'
+ * };
+ * ```
+ */
+export interface IMediumUnitLabels extends IUnitLabelMap {
+    readonly style?: 'medium';
+    millisecond: 'ms';
+    second: 'sec';
+    minute: 'min';
+    hour: 'hour';
+    day: 'day';
+    week: 'week';
+}
+/**
+ * Short format style with short but readable abbreviations.
+ * Provides compact labels that remain more readable than concise format.
+ * Used for semi-compact time representations (e.g., "1hr 30min 45sec").
+ *
+ * @example
+ * ```typescript
+ * const labels: IShortUnitLabels = {
+ *   style: 'short',
+ *   millisecond: 'ms',
+ *   second: 'sec',
+ *   minute: 'min',
+ *   hour: 'hr',
+ *   day: 'd',
+ *   week: 'wk'
+ * };
+ * ```
+ */
+export interface IShortUnitLabels extends IUnitLabelMap {
+    readonly style?: 'short';
+    millisecond: 'ms';
+    second: 'sec';
+    minute: 'min';
+    hour: 'hr';
+    day: 'd';
+    week: 'wk';
+}
+/**
+ * Complete set of default unit label configurations for all predefined formatting styles.
+ * Maps format style names to their corresponding unit label sets.
+ *
+ * @example
+ * ```typescript
+ * const conciseLabels = {
+ *   concise: { style: 'concise', hour: 'h', minute: 'm', second: 's' },
+ *   long: { style: 'long', hour: (v) => v === 1 ? 'hour' : 'hours' },
+ *   medium: { style: 'medium', hour: 'hour', minute: 'min', second: 'sec' },
+ *   short: { style: 'short', hour: 'hr', minute: 'min', second: 'sec' }
+ * };
+ * ```
+ */
+export interface IDefaultUnitLabels {
+    concise: IConciseUnitLabels;
+    long: ILongUnitLabels;
+    medium: IMediumUnitLabels;
+    short: IShortUnitLabels;
+}
+/**
+ * Configuration options for the FormatElapsedTime convenience function.
+ * Allows customization of the output format through maxUnits and custom unit labels.
+ * Always formats using the 'concise' style with optional overrides.
+ *
+ * @example
+ * ```typescript
+ * // Limit to 2 units
+ * const config1: IFormatConfig = { maxUnits: 2 };
+ * FormatElapsedTime(5425000, config1); // "1h 30m"
+ *
+ * // Custom labels
+ * const config2: IFormatConfig = {
+ *   unitLabels: { hour: 'hrs', minute: 'mins', second: 'secs' }
+ * };
+ * FormatElapsedTime(3661000, config2); // "1 hrs 1 mins 1 secs"
+ * ```
+ */
+export interface IFormatConfig {
+    /** Maximum number of units to display */
+    maxUnits?: number;
+    /** Unit labels to use for formatting. When omitted, the format's default labels are used. */
+    unitLabels?: Partial<IUnitLabelMap>;
+}
+/**
+ * Mapping of all predefined elapsed time format styles to their configurations.
+ * Each format provides a complete IFormatConfig with specific unitLabels and optional settings.
+ *
+ * @example
+ * ```typescript
+ * const config: IFormatConfig = {
+ *   unitLabels: { hour: 'h', minute: 'm', second: 's' },
+ *   maxUnits: undefined
+ * };
+ *
+ * const elapsed = new ElapsedTime(5425000);
+ * elapsed.Format('concise'); // Uses FORMATS.concise configuration
+ * ```
+ */
+export interface IFormats {
+    /** Format like "1h 30m 45s" */
+    concise: IFormatConfig;
+    /** Format like "1 hour 30 minutes 45 seconds" with proper pluralization */
+    long: IFormatConfig;
+    /** Format like "1 hour 30 min 45 sec" */
+    medium: IFormatConfig;
+    /** Format showing only the most significant 2 units */
+    mostSignificant: IFormatConfig;
+    /** Format like "1hr 30min 45sec" */
+    short: IFormatConfig;
+    /** Format showing only hours and minutes like "1:30" */
+    time: IFormatConfig;
+    /** Format showing hours, minutes and seconds like "1:30:45" */
+    timeWithSeconds: IFormatConfig;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/time/elapsed-time/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/time/elapsed-time/types.ts"],"names":[],"mappings":"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"}

package/dist/time/elapsed-time/types.js

@@ -0,0 +1 @@
+export {};

package/{build → dist}/time/elapsed-time/utils.d.ts

@@ -1,4 +1,4 @@
-import { ITimeElapsedFormatOptions } from './types.js';
+import type { ITimeElapsedFormatOptions } from './types.js';
 /**
  * Apply default options to format options object.
  * Merges user-provided options with sensible defaults for time formatting.

package/dist/time/elapsed-time/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/time/elapsed-time/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,iBAAS,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAOnG;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/{build → dist}/time/elapsed-time/utils.js

@@ -21,4 +21,3 @@ function ApplyDefaultOptions(options) {
     };
 }
 export { ApplyDefaultOptions };
-//# sourceMappingURL=utils.js.map

package/dist/time/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Time measurement utilities.
+ *
+ * Provides the {@link ElapsedTime} value-object for representing and formatting
+ * durations, and the {@link Stopwatch} class for recording timestamped events
+ * such as starts, stops, pauses, resumes, and laps.
+ *
+ * @module time
+ */
+export * from './elapsed-time/elapsed-time.js';
+export type { ITimeUnitValue, ITimeElapsedFormatOptions, TTimeElapsedFormats, TTimeUnit, IUnitLabelMap, } from './elapsed-time/types.js';
+export * from './stopwatch/stopwatch.js';
+export * from './stopwatch/entry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/time/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/time/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,gCAAgC,CAAC;AAC/C,YAAY,EACX,cAAc,EACd,yBAAyB,EACzB,mBAAmB,EACnB,SAAS,EACT,aAAa,GACb,MAAM,yBAAyB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC"}

package/{build → dist}/time/index.js

@@ -8,10 +8,5 @@
  * @module time
  */
 export * from './elapsed-time/elapsed-time.js';
-export * from './elapsed-time/types.js';
-export * from './elapsed-time/constants.js';
-export * from './elapsed-time/utils.js';
 export * from './stopwatch/stopwatch.js';
 export * from './stopwatch/entry.js';
-export * from './stopwatch/entry-types.js';
-//# sourceMappingURL=index.js.map

package/{build → dist}/time/stopwatch/entry.d.ts

@@ -1,5 +1,5 @@
 import { ElapsedTime } from '../elapsed-time/elapsed-time.js';
-import { Stopwatch } from './stopwatch.js';
+import type { Stopwatch } from './stopwatch.js';
 /**
  * Represents a single timestamped entry recorded by a {@link Stopwatch}.
  *

package/dist/time/stopwatch/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../../src/time/stopwatch/entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;IAed,OAAO,CAAC,QAAQ,CAAC,UAAU;IAdvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IAErD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;;;;;;OASG;gBAC0B,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM;IAOtF;;;;;;;;;OASG;IACH,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAW,OAAO,IAAI,WAAW,CAUhC;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAW,YAAY,IAAI,WAAW,CAUrC;CACD"}

package/{build → dist}/time/stopwatch/entry.js

@@ -102,4 +102,3 @@ export class StopwatchEntry {
         return new ElapsedTime(this._timestamp - firstEntry.timestamp);
     }
 }
-//# sourceMappingURL=entry.js.map

package/{build → dist}/time/stopwatch/stopwatch.d.ts

@@ -1,5 +1,23 @@
 import { ElapsedTime } from '../elapsed-time/elapsed-time.js';
 import { StopwatchEntry } from './entry.js';
+import { SimpleError } from '../../asserts/errors.js';
+/**
+ * Error thrown by Stopwatch when an invalid operation is attempted.
+ *
+ * @example
+ * ```typescript
+ * const sw = new Stopwatch();
+ * sw.Start();
+ * sw.Stop();
+ * sw.Resume(); // Throws StopwatchError
+ * ```
+ */
+export declare class StopwatchError extends SimpleError {
+    /**
+     * @param message - Description of the stopwatch state error
+     */
+    constructor(message: string);
+}
 /**
  * Represents a stopwatch for measuring time intervals.
  *
@@ -117,11 +135,12 @@ export declare class Stopwatch {
     /**
      * Starts the stopwatch by recording an initial timestamp entry.
      *
-     * If the stopwatch has already been started, this is a no-op and the
+     * If the stopwatch has already been started, this is idempotent and the
      * existing latest entry is returned without creating a new one.
      *
-     * @returns The start {@link StopwatchEntry} that was recorded, or `undefined`
-     *   if the stopwatch was already running (should not happen in practice).
+     * @returns The new start entry if the stopwatch was not running,
+     *   or the existing latest entry if `Start()` was called while already running.
+     *   Check `this.Running` before calling to distinguish the two cases.
      *
      * @example
      * ```typescript
@@ -181,6 +200,11 @@ export declare class Stopwatch {
      * After resuming, elapsed-time calculations continue to accumulate from where
      * they left off.
      *
+     * @remarks
+     * Calling `Resume()` after {@link Stop} has no effect and returns `null`, since
+     * `Stop()` sets the internal `_pausedAt` flag to a non-null value. The stopwatch
+     * must be explicitly {@link Reset} and {@link Start}ed again to begin timing anew.
+     *
      * @returns A new {@link StopwatchEntry} recording the resume time, or `null`
      *   if the stopwatch was not paused.
      *

package/dist/time/stopwatch/stopwatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stopwatch.d.ts","sourceRoot":"","sources":["../../../src/time/stopwatch/stopwatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC9C;;OAEG;gBACS,OAAO,EAAE,MAAM;CAG3B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,qBAAa,SAAS;IACrB,OAAO,CAAC,MAAM,CAAwB;IAEtC,OAAO,CAAC,SAAS,CAAuB;IAExC,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;;;;;;OAYG;gBACS,gBAAgB,UAAQ;IAMpC;;;;OAIG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;;OAKG;IACH,IAAW,KAAK,IAAI,cAAc,GAAG,SAAS,CAE7C;IAED;;;;;OAKG;IACH,IAAW,MAAM,IAAI,cAAc,GAAG,SAAS,CAE9C;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,IAAW,OAAO,IAAI,WAAW,CAUhC;IAED;;;;;OAKG;IACH,IAAW,KAAK,IAAI,cAAc,EAAE,CAEnC;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,cAAc,EAAE,CAErC;IAED;;;OAGG;IACH,IAAW,QAAQ,IAAI,MAAM,GAAG,IAAI,CAEnC;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,KAAK,IAAI,cAAc,GAAG,SAAS;IAU1C;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,IAAI,IAAI,cAAc,GAAG,SAAS;IAmBzC;;;;;;;;;;;;;;;;;;;OAmBG;IACI,KAAK,IAAI,cAAc,GAAG,IAAI;IAQrC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,MAAM,IAAI,cAAc,GAAG,IAAI;IActC;;;;;;;;;;;;;;;;OAgBG;IACI,KAAK,IAAI,cAAc;IAW9B;;;;;;;;;;;;;;;;;;OAkBG;IACI,GAAG,IAAI,WAAW;IAUzB;;;;;;;;;;;;;;;OAeG;IACI,KAAK,IAAI,IAAI;CAKpB"}

package/{build → dist}/time/stopwatch/stopwatch.js

@@ -1,5 +1,25 @@
 import { ElapsedTime } from '../elapsed-time/elapsed-time.js';
 import { StopwatchEntry } from './entry.js';
+import { SimpleError } from '../../asserts/errors.js';
+/**
+ * Error thrown by Stopwatch when an invalid operation is attempted.
+ *
+ * @example
+ * ```typescript
+ * const sw = new Stopwatch();
+ * sw.Start();
+ * sw.Stop();
+ * sw.Resume(); // Throws StopwatchError
+ * ```
+ */
+export class StopwatchError extends SimpleError {
+    /**
+     * @param message - Description of the stopwatch state error
+     */
+    constructor(message) {
+        super(message);
+    }
+}
 /**
  * Represents a stopwatch for measuring time intervals.
  *
@@ -144,11 +164,12 @@ export class Stopwatch {
     /**
      * Starts the stopwatch by recording an initial timestamp entry.
      *
-     * If the stopwatch has already been started, this is a no-op and the
+     * If the stopwatch has already been started, this is idempotent and the
      * existing latest entry is returned without creating a new one.
      *
-     * @returns The start {@link StopwatchEntry} that was recorded, or `undefined`
-     *   if the stopwatch was already running (should not happen in practice).
+     * @returns The new start entry if the stopwatch was not running,
+     *   or the existing latest entry if `Start()` was called while already running.
+     *   Check `this.Running` before calling to distinguish the two cases.
      *
      * @example
      * ```typescript
@@ -238,6 +259,11 @@ export class Stopwatch {
      * After resuming, elapsed-time calculations continue to accumulate from where
      * they left off.
      *
+     * @remarks
+     * Calling `Resume()` after {@link Stop} has no effect and returns `null`, since
+     * `Stop()` sets the internal `_pausedAt` flag to a non-null value. The stopwatch
+     * must be explicitly {@link Reset} and {@link Start}ed again to begin timing anew.
+     *
      * @returns A new {@link StopwatchEntry} recording the resume time, or `null`
      *   if the stopwatch was not paused.
      *
@@ -250,6 +276,9 @@ export class Stopwatch {
      * ```
      */
     Resume() {
+        if (this._stopped) {
+            throw new StopwatchError('Cannot resume after stopwatch has been stopped');
+        }
         if (this._pausedAt === null)
             return null;
         const current = Date.now();
@@ -334,4 +363,3 @@ export class Stopwatch {
         this._stopped = false;
     }
 }
-//# sourceMappingURL=stopwatch.js.map