@williamthorsen/toolbelt.datetime 3.3.0 → 4.0.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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

package/README.md

@@ -3,19 +3,13 @@
 Date and time utilities.
 
 <!-- section:release-notes -->
-## Release notes — v3.3.0 (2026-08-08)
+## Release notes — v4.0.0 (2026-08-12)
 
 ### Features
 
-- Add elapsed-time measurement and multi-unit duration formatting (#95)
+- 🚨 **Breaking:** Rename get* functions by return kind and verb specificity (#119)
 
-  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.
+  Renames thirteen functions across various packages to align with a consistent naming pattern.
 <!-- /section:release-notes -->
 
 ## Installation

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

@@ -4,7 +4,7 @@ export function formatDuration(milliseconds, options = {}) {
     const { maxUnits = 1 } = options;
     assertValidArguments(milliseconds, maxUnits);
     const components = selectComponents(milliseconds, maxUnits);
-    return components.map(({ count, unit }) => unit.getLabeledCount(count, { format: 'short' })).join(' ');
+    return components.map(({ count, unit }) => unit.formatLabeledCount(count, { format: 'short' })).join(' ');
 }
 function selectComponents(milliseconds, maxUnits) {
     let leadingIndex = selectLeadingIndex(milliseconds);

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

@@ -1,5 +1,5 @@
 export { formatDuration, type FormatDurationOptions } from './formatDuration.js';
-export { getDecadesContainingRange } from './getDecadesContainingRange.js';
-export { getDecadesContainingYears } from './getDecadesContainingYears.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,5 +1,5 @@
 export { formatDuration } from "./formatDuration.js";
-export { getDecadesContainingRange } from "./getDecadesContainingRange.js";
-export { getDecadesContainingYears } from "./getDecadesContainingYears.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;

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

@@ -11,8 +11,8 @@ export declare class TimeUnit {
     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

@@ -30,20 +30,20 @@ export class TimeUnit {
             ? amount * (fromUnit.inMillis / toUnit.inMillis)
             : amount / (toUnit.inMillis / fromUnit.inMillis);
         if (throwOnFractional && !Number.isSafeInteger(value)) {
-            throw new Error(`${fromUnit.getLabeledCount(amount)} cannot be converted into an exact whole number of ${toUnit.plural}.`);
+            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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.datetime",
-  "version": "3.3.0",
+  "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[];