@williamthorsen/toolbelt.datetime 3.2.8 → 4.0.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project will be documented in this file.
 
+## 4.0.0 — 2026-08-12
+
+### Features
+
+- 🚨 **Breaking:** Rename get* functions by return kind and verb specificity (#119)
+
+  Renames thirteen functions across various packages to align with a consistent naming pattern.
+
+### Refactoring
+
+- Align stray modules with layout and TypeScript conventions (#118)
+
+  Aligns all packages with code-layout and annotation conventions, ending a handful of long-standing exceptions. Documentation has been updated to make the conventions clear.
+
+## 3.3.0 — 2026-08-08
+
+### Features
+
+- Add elapsed-time measurement and multi-unit duration formatting (#95)
+
+  Adds two functions for measuring and formatting durations to `@williamthorsen/toolbelt.datetime` at the "proposed" stage. `startTimer` measures how long a span of work takes, returning a reader that reports whole elapsed milliseconds and can be read repeatedly during the span; it measures independently of the system clock, so a clock adjustment partway through does not skew the result. `formatDuration` renders a millisecond count as a short labeled duration and picks the unit itself, so 240,000 becomes `4m`; an option raises the ceiling on how many components appear, so 250,300 becomes `4m 10s 300ms`.
+
+  `TimeUnit`, in `@williamthorsen/toolbelt.datetime/draft`, now converts to a coarser unit exactly: an hour expressed in milliseconds converts to one hour, where it previously came back a fraction short and could truncate to zero. `TimeUnit` also now exposes its units as a list ordered from coarsest to finest.
+
+- Use underscore separator at 4 digits or more
+
+  Changes the `unicorn/numeric-separators-style` rule config so that separators are consistently used in base 10 numbers, instead of exempting numbers of 5 digits or less.
+
+### Refactoring
+
+- Fixes violations surfaced by newly active lint rules (#84)
+- Fix slug punctuation and require safe integers (#86)
+
+  - Fixes an issue where the use of certain letters as the slug separator in `slugify` would leave punctuation marks in the result.
+  - Time-unit conversions, scaling range bounds, normal-distribution interval counts, and array indices in object paths now reject values too large to represent exactly instead of silently losing precision.
+  - Seeded number generators now produce distinct sequences for seeds at or beyond 2^53, where adjacent seeds previously collapsed onto nearly identical output. A seed of that size saved before this release no longer reproduces the same output.
+
+- Fix deferred violations of unicorn lint rules (#88)
+
+  Fixes issues surfaced by `unicorn` lint rules that were temporarily downgraded to warnings and restores the rules to "error" severity. Separately, the `Queue` class in `dstructs` has been modified to hide its internal array.
+
+### Tooling
+
+- Migrate Vitest configs to the nmr projects model (#73)
+
+  Packages no longer need to declare their own Vitest config. Test suites are now selected by a test file's name suffix rather than by choosing a config file: `*.app.test.ts` and `*.int.test.ts` route to the app and integration suites, and everything else runs as a unit test. Local development is now declared to require Node 24.16 or later.
+
+- Adopt the mechanical-syntax deferred unicorn rules (#82)
+
+  Promotes ten deferred lint rules from warnings to errors and fixes the issues surfaced by those rules. One published behavior changes as well: Converting a Map to a plain object no longer drops an entry keyed `__proto__`.
+
+- Use identical compiler settings for all packages (#105)
+
+  All packages now have identical compiler settings, using the settings from the `@williamthorsen/tsconfig` base config without modification.
+
+### Dependencies
+
+- Upgrade all deps to latest version
+
 ## 3.2.8 — 2026-07-27
 
 ### Tooling

package/README.md

@@ -2,7 +2,15 @@
 
 Date and time utilities.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v4.0.0 (2026-08-12)
+
+### Features
+
+- 🚨 **Breaking:** Rename get* functions by return kind and verb specificity (#119)
+
+  Renames thirteen functions across various packages to align with a consistent naming pattern.
+<!-- /section:release-notes -->
 
 ## Installation
 

package/dist/esm/1-proposed/formatDuration.d.ts

@@ -0,0 +1,4 @@
+export declare function formatDuration(milliseconds: number, options?: FormatDurationOptions): string;
+export interface FormatDurationOptions {
+    maxUnits?: number | undefined;
+}

package/dist/esm/1-proposed/formatDuration.js

@@ -0,0 +1,48 @@
+import { TimeUnit } from "../2-draft/index.js";
+const FINEST_INDEX = TimeUnit.coarsestFirst.length - 1;
+export function formatDuration(milliseconds, options = {}) {
+    const { maxUnits = 1 } = options;
+    assertValidArguments(milliseconds, maxUnits);
+    const components = selectComponents(milliseconds, maxUnits);
+    return components.map(({ count, unit }) => unit.formatLabeledCount(count, { format: 'short' })).join(' ');
+}
+function selectComponents(milliseconds, maxUnits) {
+    let leadingIndex = selectLeadingIndex(milliseconds);
+    for (;;) {
+        const shownUnits = TimeUnit.coarsestFirst.slice(leadingIndex, leadingIndex + maxUnits);
+        const rounded = roundToFinest(milliseconds, shownUnits);
+        const carriedIndex = selectLeadingIndex(rounded);
+        if (carriedIndex >= leadingIndex) {
+            return decompose(rounded, shownUnits);
+        }
+        leadingIndex = carriedIndex;
+    }
+}
+function selectLeadingIndex(milliseconds) {
+    const index = TimeUnit.coarsestFirst.findIndex((unit) => milliseconds >= unit.inMillis);
+    return index === -1 ? FINEST_INDEX : index;
+}
+function roundToFinest(milliseconds, shownUnits) {
+    const finestInMillis = Math.min(...shownUnits.map((unit) => unit.inMillis));
+    return Math.round(milliseconds / finestInMillis) * finestInMillis;
+}
+function decompose(milliseconds, shownUnits) {
+    const components = [];
+    let remainder = milliseconds;
+    for (const [index, unit] of shownUnits.entries()) {
+        const count = Math.floor(remainder / unit.inMillis);
+        remainder -= count * unit.inMillis;
+        if (index === 0 || count > 0) {
+            components.push({ count, unit });
+        }
+    }
+    return components;
+}
+function assertValidArguments(milliseconds, maxUnits) {
+    if (!Number.isFinite(milliseconds) || milliseconds < 0) {
+        throw new RangeError(`Duration must be a non-negative finite number of milliseconds, but was ${milliseconds}.`);
+    }
+    if (!Number.isSafeInteger(maxUnits) || maxUnits < 1) {
+        throw new RangeError(`maxUnits must be a positive integer, but was ${maxUnits}.`);
+    }
+}

package/dist/esm/1-proposed/index.d.ts

@@ -1,3 +1,5 @@
-export { getDecadesContainingRange } from './getDecadesContainingRange.js';
-export { getDecadesContainingYears } from './getDecadesContainingYears.js';
+export { formatDuration, type FormatDurationOptions } from './formatDuration.js';
+export { listDecadesContainingRange } from './listDecadesContainingRange.js';
+export { listDecadesContainingYears } from './listDecadesContainingYears.js';
+export { startTimer } from './startTimer.js';
 export * from './types.js';

package/dist/esm/1-proposed/index.js

@@ -1,3 +1,5 @@
-export { getDecadesContainingRange } from "./getDecadesContainingRange.js";
-export { getDecadesContainingYears } from "./getDecadesContainingYears.js";
+export { formatDuration } from "./formatDuration.js";
+export { listDecadesContainingRange } from "./listDecadesContainingRange.js";
+export { listDecadesContainingYears } from "./listDecadesContainingYears.js";
+export { startTimer } from "./startTimer.js";
 export * from "./types.js";

package/dist/esm/1-proposed/listDecadesContainingRange.d.ts

@@ -0,0 +1,5 @@
+import type { Decade } from './listDecadesContainingYears.js';
+export declare function listDecadesContainingRange(range: {
+    start: number;
+    end: number;
+}): Decade[];

package/dist/esm/1-proposed/{getDecadesContainingRange.js → listDecadesContainingRange.js}

@@ -1,4 +1,4 @@
-export function getDecadesContainingRange(range) {
+export function listDecadesContainingRange(range) {
     const { start, end } = range;
     if (start < 0 || end < 0) {
         throw new RangeError(`Negative years are not supported: start = ${start}, end = ${end}.`);

package/dist/esm/1-proposed/{getDecadesContainingYears.d.ts → listDecadesContainingYears.d.ts}

@@ -1,4 +1,4 @@
-export declare function getDecadesContainingYears(years: number[]): Decade[];
+export declare function listDecadesContainingYears(years: number[]): Decade[];
 export interface Decade {
     start: number;
     end: number;

package/dist/esm/1-proposed/{getDecadesContainingYears.js → listDecadesContainingYears.js}

@@ -1,4 +1,4 @@
-export function getDecadesContainingYears(years) {
+export function listDecadesContainingYears(years) {
     const uniqueYears = [...new Set(years)].toSorted((a, b) => a - b);
     const decadesMap = new Map();
     const [firstYear] = uniqueYears;
@@ -18,5 +18,5 @@ export function getDecadesContainingYears(years) {
             });
         }
     }
-    return [...decadesMap.values()];
+    return decadesMap.values().toArray();
 }

package/dist/esm/1-proposed/startTimer.d.ts

@@ -0,0 +1 @@
+export declare function startTimer(): () => number;

package/dist/esm/1-proposed/startTimer.js

@@ -0,0 +1,4 @@
+export function startTimer() {
+    const startedAt = performance.now();
+    return () => Math.round(performance.now() - startedAt);
+}

package/dist/esm/1-proposed/types.d.ts

@@ -1 +1 @@
-export type { Decade } from './getDecadesContainingYears.js';
+export type { Decade } from './listDecadesContainingYears.js';

package/dist/esm/2-draft/TimeUnit.d.ts

@@ -5,13 +5,14 @@ export declare class TimeUnit {
     static readonly Minutes: TimeUnit;
     static readonly Hours: TimeUnit;
     static readonly Days: TimeUnit;
+    static readonly coarsestFirst: ReadonlyArray<TimeUnit>;
     readonly abbrev: string;
     readonly plural: string;
     readonly singular: string;
     private constructor();
     static convert(amount: number, fromUnit: TimeUnit, toUnit: TimeUnit, options?: TimeUnitConversionOptions): number;
-    getLabeledCount(amount: number, options?: TimeUnitLabelOptions): string;
-    getInflectedLabel(amount: number): string;
+    formatLabeledCount(amount: number, options?: TimeUnitLabelOptions): string;
+    inflectLabel(amount: number): string;
     toString(): string;
 }
 export interface TimeUnitConversionOptions {

package/dist/esm/2-draft/TimeUnit.js

@@ -1,10 +1,17 @@
 export class TimeUnit {
     inMillis;
     static Millis = new TimeUnit(1, { singular: 'millisecond', abbrev: 'ms' });
-    static Seconds = new TimeUnit(1000, { singular: 'second', abbrev: 's' });
+    static Seconds = new TimeUnit(1_000, { singular: 'second', abbrev: 's' });
     static Minutes = new TimeUnit(60_000, { singular: 'minute', abbrev: 'm' });
     static Hours = new TimeUnit(3_600_000, { singular: 'hour', abbrev: 'h' });
     static Days = new TimeUnit(86_400_000, { singular: 'day', abbrev: 'd' });
+    static coarsestFirst = [
+        TimeUnit.Days,
+        TimeUnit.Hours,
+        TimeUnit.Minutes,
+        TimeUnit.Seconds,
+        TimeUnit.Millis,
+    ];
     abbrev;
     plural;
     singular;
@@ -19,23 +26,24 @@ export class TimeUnit {
         if (fromUnit.inMillis === toUnit.inMillis) {
             return amount;
         }
-        const multiplier = fromUnit.inMillis / toUnit.inMillis;
-        const value = amount * multiplier;
-        if (!Number.isInteger(value) && throwOnFractional) {
-            throw new Error(`${fromUnit.getLabeledCount(amount)} cannot be converted into a whole number of ${toUnit.plural}.`);
+        const value = fromUnit.inMillis > toUnit.inMillis
+            ? amount * (fromUnit.inMillis / toUnit.inMillis)
+            : amount / (toUnit.inMillis / fromUnit.inMillis);
+        if (throwOnFractional && !Number.isSafeInteger(value)) {
+            throw new Error(`${fromUnit.formatLabeledCount(amount)} cannot be converted into an exact whole number of ${toUnit.plural}.`);
         }
         if (decimalPlaces !== undefined) {
             return Math.round(value * 10 ** decimalPlaces) / 10 ** decimalPlaces;
         }
         return value;
     }
-    getLabeledCount(amount, options = {}) {
+    formatLabeledCount(amount, options = {}) {
         if (options.format === 'short') {
             return `${amount}${this.abbrev}`;
         }
-        return `${amount} ${this.getInflectedLabel(amount)}`;
+        return `${amount} ${this.inflectLabel(amount)}`;
     }
-    getInflectedLabel(amount) {
+    inflectLabel(amount) {
         return amount === 1 ? this.singular : this.plural;
     }
     toString() {

package/dist/esm/2-draft/Timestamp.d.ts

@@ -3,14 +3,14 @@ export declare class Timestamp {
     private _format;
     private readonly _millis;
     private _timeUnit;
-    static fromMillis(milliseconds: number): Timestamp;
-    static fromSeconds(seconds: number): Timestamp;
-    static now(options?: TimestampOptions): Timestamp;
     constructor(dateTime?: TimestampInput, options?: TimestampOptions);
     get format(): TimestampFormatEnum;
     get millis(): number;
     get seconds(): number;
     get timeUnit(): TimeUnit;
+    static fromMillis(milliseconds: number): Timestamp;
+    static fromSeconds(seconds: number): Timestamp;
+    static now(options?: TimestampOptions): Timestamp;
     clone(options?: TimestampOptions): Timestamp;
     setOptions(options?: TimestampOptions): this;
     toCompactString(options?: Options): string;

package/dist/esm/2-draft/Timestamp.js

@@ -3,15 +3,6 @@ export class Timestamp {
     _format;
     _millis;
     _timeUnit;
-    static fromMillis(milliseconds) {
-        return new Timestamp(new Date(milliseconds));
-    }
-    static fromSeconds(seconds) {
-        return new Timestamp(new Date(seconds * 1000), { timeUnit: TimeUnit.Seconds });
-    }
-    static now(options = {}) {
-        return new Timestamp(undefined, options);
-    }
     constructor(dateTime, options = {}) {
         const { format = 'iso', timeUnit = TimeUnit.Millis } = options;
         if (dateTime instanceof Timestamp) {
@@ -38,6 +29,15 @@ export class Timestamp {
     get timeUnit() {
         return this._timeUnit;
     }
+    static fromMillis(milliseconds) {
+        return new Timestamp(new Date(milliseconds));
+    }
+    static fromSeconds(seconds) {
+        return new Timestamp(new Date(seconds * 1_000), { timeUnit: TimeUnit.Seconds });
+    }
+    static now(options = {}) {
+        return new Timestamp(undefined, options);
+    }
     clone(options = {}) {
         return new Timestamp(this._millis, options);
     }
@@ -48,7 +48,7 @@ export class Timestamp {
         return this;
     }
     toCompactString(options = {}) {
-        const [datePart = '', timePart = ''] = this.toIsoString(options).split('T');
+        const [datePart = '', timePart = ''] = this.toIsoString(options).split('T', 2);
         const formattedDatePart = datePart.replaceAll(/[-Z]/g, '');
         const formattedTimePart = timePart.replaceAll(/[:Z]/g, '');
         return timePart.length > 0 ? `${formattedDatePart}-${formattedTimePart}` : formattedDatePart;
@@ -75,7 +75,7 @@ export class Timestamp {
             case TimeUnit.Hours:
                 return isoDateTime.replace(/:\d{2}:\d{2}\.\d{3}Z$/, 'Z');
             case TimeUnit.Days: {
-                const [datePart] = isoDateTime.split('T');
+                const [datePart] = isoDateTime.split('T', 1);
                 return `${datePart}Z`;
             }
             case TimeUnit.Millis:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.datetime",
-  "version": "3.2.8",
+  "version": "4.0.0",
   "description": "API",
   "keywords": [],
   "homepage": "https://github.com/williamthorsen/toolbelt/tree/main/packages/datetime#readme",

package/dist/esm/1-proposed/getDecadesContainingRange.d.ts

@@ -1,5 +0,0 @@
-import type { Decade } from './getDecadesContainingYears.js';
-export declare function getDecadesContainingRange(range: {
-    start: number;
-    end: number;
-}): Decade[];