@design-edito/tools 0.5.2 → 0.5.3

package/agnostic/time/dates/format-date/parts.js

@@ -0,0 +1,136 @@
+/**
+ * The localised weekday names, indexed the way `Date.prototype.getDay` numbers
+ * them. January 1st 2023 was a Sunday, so the week is walked from there.
+ */
+function weekdayNames(locale, weekday) {
+    const formatter = new Intl.DateTimeFormat(locale, { weekday });
+    return [...Array(7)].map((_, i) => formatter.format(new Date(2023, 0, i + 1)));
+}
+/**
+ * The localised month names, indexed the way `Date.prototype.getMonth` numbers
+ * them — January at 0.
+ */
+function monthNames(locale, month) {
+    const formatter = new Intl.DateTimeFormat(locale, { month });
+    return [...Array(12)].map((_, i) => formatter.format(new Date(2023, i, 1)));
+}
+/** The ordinal suffix a locale appends to a day number, empty when it has none. */
+function dayOrdinalSuffix(day, locale) {
+    if (locale.startsWith('fr'))
+        return day === 1 ? 'er' : '';
+    if (!locale.startsWith('en'))
+        return '';
+    const mod10 = day % 10;
+    const mod100 = day % 100;
+    if (mod10 === 1 && mod100 !== 11)
+        return 'st';
+    if (mod10 === 2 && mod100 !== 12)
+        return 'nd';
+    if (mod10 === 3 && mod100 !== 13)
+        return 'rd';
+    return 'th';
+}
+/**
+ * Breaks a `Date` down into every fragment `formatDate` knows how to render,
+ * localised and ready to concatenate.
+ *
+ * Reach for this over `formatDate` when the fragments go somewhere a template
+ * string can't — separate DOM nodes, a `<time>` element's parts, an object
+ * handed to a view layer.
+ *
+ * @param date - The `Date` to break down.
+ * @param locale - Optional locale code, falling back to `'en'` when the runtime
+ * doesn't support it.
+ * @returns The parts, each one reachable under its unit token and under its
+ * readable name. Quantities come out as numbers — `formatDate` is what pads
+ * them.
+ * @see {@link DateParts}
+ *
+ * @remarks
+ * Every fragment is read off the `Date` in the runtime's local timezone, since a
+ * `Date` carries no timezone of its own.
+ *
+ * @example
+ * const parts = getDateParts(new Date(2026, 0, 1, 15, 5), 'fr')
+ * parts.MMMM            // => 'janvier'
+ * parts.fullMonthName   // => 'janvier', the same value
+ * parts.D               // => 1, the number — '01' is formatDate's business
+ */
+export function getDateParts(date, locale = 'en') {
+    const safeLocale = Intl.DateTimeFormat.supportedLocalesOf(locale).length === 0
+        ? 'en'
+        : locale;
+    const day = date.getDate();
+    const dayOfWeek = date.getDay();
+    const month = date.getMonth();
+    const hours = date.getHours();
+    const isPM = hours >= 12;
+    const tokens = {
+        'D': day,
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'd': weekdayNames(safeLocale, 'short')[dayOfWeek],
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'dd': weekdayNames(safeLocale, 'long')[dayOfWeek],
+        'M': month + 1,
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'MMM': monthNames(safeLocale, 'short')[month],
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'MMMM': monthNames(safeLocale, 'long')[month],
+        'YYYY': date.getFullYear(),
+        'H': hours,
+        'h': hours % 12 === 0 ? 12 : hours % 12,
+        'm': date.getMinutes(),
+        's': date.getSeconds(),
+        'ms': date.getMilliseconds(),
+        'A': isPM ? 'PM' : 'AM',
+        'a': isPM ? 'pm' : 'am',
+        'th': dayOrdinalSuffix(day, safeLocale)
+    };
+    return {
+        ...tokens,
+        dayOfMonth: tokens.D,
+        shortWeekdayName: tokens.d,
+        fullWeekdayName: tokens.dd,
+        monthNumber: tokens.M,
+        shortMonthName: tokens.MMM,
+        fullMonthName: tokens.MMMM,
+        year: tokens.YYYY,
+        hours24: tokens.H,
+        hours12: tokens.h,
+        minutes: tokens.m,
+        seconds: tokens.s,
+        milliseconds: tokens.ms,
+        upperCaseMeridiem: tokens.A,
+        lowerCaseMeridiem: tokens.a,
+        dayOrdinalSuffix: tokens.th
+    };
+}
+// [WIP] timezone tokens were removed since JavaScript's Date object doesn't hold
+// timezone data — those templates would only reflect the current client's
+// timezone, no matter what the input Date obj was
+// 'ZZ': () => {
+//   const timezoneOffset = date.getTimezoneOffset()
+//   const offsetHours = Math.floor(Math.abs(timezoneOffset) / 60)
+//   const offsetMinutes = Math.abs(timezoneOffset) % 60
+//   const sign = timezoneOffset > 0 ? '-' : '+'
+//   return `${sign}${String(offsetHours).padStart(2, '0')}:${String(offsetMinutes).padStart(2, '0')}`
+// },
+// 'Z': () => {
+//   const timezoneOffset = date.getTimezoneOffset()
+//   if (timezoneOffset === 0) return 'Z'
+//   const offsetHours = Math.floor(Math.abs(timezoneOffset) / 60)
+//   const offsetMinutes = Math.abs(timezoneOffset) % 60
+//   const sign = timezoneOffset > 0 ? '-' : '+'
+//   return `${sign}${String(offsetHours).padStart(2, '0')}:${String(offsetMinutes).padStart(2, '0')}`
+// },
+// 'z': () => {
+//   return Intl.DateTimeFormat(locale, { timeZoneName: 'short' })
+//     .formatToParts(date)
+//     .find(part => part.type === 'timeZoneName')?.value || ''
+// },
+// 'zz': () => {
+//   return Intl.DateTimeFormat(locale, { timeZoneName: 'long' })
+//     .formatToParts(date)
+//     .find(part => part.type === 'timeZoneName')?.value || ''
+// },
+// 'tz': () => Intl.DateTimeFormat().resolvedOptions().timeZone || ''

package/agnostic/time/dates/format-date/types.d.ts

@@ -0,0 +1,84 @@
+/** Every token `formatDate` substitutes in a template. */
+export type DateToken = 'D' | 'DD' | 'd' | 'dd' | 'M' | 'MM' | 'MMM' | 'MMMM' | 'YY' | 'YYYY' | 'H' | 'HH' | 'h' | 'hh' | 'm' | 'mm' | 's' | 'ss' | 'ms' | 'A' | 'a' | 'th';
+/**
+ * A date's parts, keyed by unit token.
+ *
+ * Quantities are **numbers** — a day of month is `1`, not `'01'`. Padding and
+ * truncation are rendering concerns and belong to `formatDate`, which is why the
+ * `DD`, `MM`, `YY`, `HH`, `hh`, `mm` and `ss` tokens have no entry here: they
+ * render the same quantity as their unpadded twin. The parts that are localised
+ * text rather than a quantity stay strings.
+ */
+export type DateTokenParts = {
+    /** Day of month, 1–31. */
+    D: number;
+    /** Short weekday name, localised. */
+    d: string;
+    /** Full weekday name, localised. */
+    dd: string;
+    /** Month number, 1–12 — January is `1`, not `0`. */
+    M: number;
+    /** Short month name, localised. */
+    MMM: string;
+    /** Full month name, localised. */
+    MMMM: string;
+    /** Full year. */
+    YYYY: number;
+    /** Hours on a 24-hour clock, 0–23. */
+    H: number;
+    /** Hours on a 12-hour clock, 1–12. Midnight and noon are both `12`. */
+    h: number;
+    /** Minutes, 0–59. */
+    m: number;
+    /** Seconds, 0–59. */
+    s: number;
+    /** Milliseconds, 0–999. */
+    ms: number;
+    /** Upper-case meridiem, `'AM'` or `'PM'`. */
+    A: string;
+    /** Lower-case meridiem, `'am'` or `'pm'`. */
+    a: string;
+    /**
+     * Day ordinal suffix — `'st'`, `'nd'`, `'rd'` or `'th'` in English, `'er'` for
+     * the French 1st. Empty for every other locale, and for French days 2 onwards.
+     */
+    th: string;
+};
+/**
+ * The same parts as {@link DateTokenParts}, under names that read on their own —
+ * one per token, same value.
+ */
+export type NamedDateParts = {
+    /** {@link DateTokenParts.D} */
+    dayOfMonth: number;
+    /** {@link DateTokenParts.d} */
+    shortWeekdayName: string;
+    /** {@link DateTokenParts.dd} */
+    fullWeekdayName: string;
+    /** {@link DateTokenParts.M} */
+    monthNumber: number;
+    /** {@link DateTokenParts.MMM} */
+    shortMonthName: string;
+    /** {@link DateTokenParts.MMMM} */
+    fullMonthName: string;
+    /** {@link DateTokenParts.YYYY} */
+    year: number;
+    /** {@link DateTokenParts.H} */
+    hours24: number;
+    /** {@link DateTokenParts.h} */
+    hours12: number;
+    /** {@link DateTokenParts.m} */
+    minutes: number;
+    /** {@link DateTokenParts.s} */
+    seconds: number;
+    /** {@link DateTokenParts.ms} */
+    milliseconds: number;
+    /** {@link DateTokenParts.A} */
+    upperCaseMeridiem: string;
+    /** {@link DateTokenParts.a} */
+    lowerCaseMeridiem: string;
+    /** {@link DateTokenParts.th} */
+    dayOrdinalSuffix: string;
+};
+/** Every part of a date, reachable both by unit token and by name. */
+export type DateParts = DateTokenParts & NamedDateParts;

package/agnostic/time/dates/format-date/types.js

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

package/agnostic/time/duration/format-duration/index.d.ts

@@ -0,0 +1,42 @@
+import type { Duration } from '../index.js';
+import type { FormatDurationOptions } from './types.js';
+/**
+ * Formats a duration into a string according to a custom template.
+ *
+ * The breakdown follows the template: the units it mentions are the units the
+ * duration is split across, each taking its whole part and handing the rest
+ * down. `'{{h}}:{{mm}}:{{ss}}'` therefore reads a duration as hours, minutes and
+ * seconds, while `'{{s}}s'` puts the whole duration on seconds.
+ *
+ * Supported tokens (placeholders must be wrapped in `{{...}}`). The bare form is
+ * the plain number, the doubled form the same number padded to two digits:
+ *
+ * - `Y` / `YY` : Years
+ * - `M` / `MM` : Months
+ * - `w` / `ww` : Weeks
+ * - `d` / `dd` : Days
+ * - `h` / `hh` : Hours
+ * - `m` / `mm` : Minutes
+ * - `s` / `ss` : Seconds
+ * - `ms` : Milliseconds, padded to three digits
+ *
+ * @param duration - The duration to format, as a {@link Duration} or a number of
+ * milliseconds.
+ * @param format - The template string containing tokens.
+ * @param options - How to handle the remainder and the month/year approximation.
+ * @returns Formatted duration string. An unknown token is left untouched, braces
+ * included.
+ * @see {@link getDurationParts} to reach the same parts as plain values.
+ *
+ * @remarks
+ * A negative duration yields negative parts, so every token renders a signed
+ * number — `'{{m}}:{{ss}}'` gives `-1:-30`, not `-1:30`. This is deliberate: the
+ * output stays faithful to the parts, and keeping a duration positive is the
+ * caller's business. Format the magnitude and write the sign yourself when a
+ * single leading minus is what you need.
+ *
+ * @example
+ * formatDuration(seconds(3725), '{{h}}:{{mm}}:{{ss}}')
+ * // => "1:02:05"
+ */
+export declare function formatDuration(duration: Duration | number, format: string, options?: FormatDurationOptions): string;

package/agnostic/time/duration/format-duration/index.js

@@ -0,0 +1,94 @@
+import { getDurationParts } from './parts.js';
+// Alternation is ordered, and the first branch that fits wins — so the longest
+// tokens come first. `m` ahead of `ms` or `mm` would swallow them.
+const tokenRegexp = /\{\{(YY|MM|ww|dd|hh|mm|ss|ms|Y|M|w|d|h|m|s)\}\}/gv;
+/** Which tokens read which unit, longest unit first. */
+const unitTokens = [
+    ['Y', ['Y', 'YY']],
+    ['M', ['M', 'MM']],
+    ['w', ['w', 'ww']],
+    ['d', ['d', 'dd']],
+    ['h', ['h', 'hh']],
+    ['m', ['m', 'mm']],
+    ['s', ['s', 'ss']],
+    ['ms', ['ms']]
+];
+function pad(value, length) {
+    return `${value}`.padStart(length, '0');
+}
+/**
+ * How each token renders the parts it reads. This is where padding lives —
+ * {@link getDurationParts} hands over plain quantities, and a doubled token is
+ * the same quantity written on two digits.
+ */
+const renderers = {
+    'Y': parts => `${parts.Y}`,
+    'YY': parts => pad(parts.Y, 2),
+    'M': parts => `${parts.M}`,
+    'MM': parts => pad(parts.M, 2),
+    'w': parts => `${parts.w}`,
+    'ww': parts => pad(parts.w, 2),
+    'd': parts => `${parts.d}`,
+    'dd': parts => pad(parts.d, 2),
+    'h': parts => `${parts.h}`,
+    'hh': parts => pad(parts.h, 2),
+    'm': parts => `${parts.m}`,
+    'mm': parts => pad(parts.m, 2),
+    's': parts => `${parts.s}`,
+    'ss': parts => pad(parts.s, 2),
+    'ms': parts => pad(parts.ms, 3)
+};
+/** The units a template asks for, read off the tokens it actually uses. */
+function unitsInFormat(format) {
+    return unitTokens
+        .filter(([, tokens]) => tokens.some(token => format.includes(`{{${token}}}`)))
+        .map(([unit]) => unit);
+}
+/**
+ * Formats a duration into a string according to a custom template.
+ *
+ * The breakdown follows the template: the units it mentions are the units the
+ * duration is split across, each taking its whole part and handing the rest
+ * down. `'{{h}}:{{mm}}:{{ss}}'` therefore reads a duration as hours, minutes and
+ * seconds, while `'{{s}}s'` puts the whole duration on seconds.
+ *
+ * Supported tokens (placeholders must be wrapped in `{{...}}`). The bare form is
+ * the plain number, the doubled form the same number padded to two digits:
+ *
+ * - `Y` / `YY` : Years
+ * - `M` / `MM` : Months
+ * - `w` / `ww` : Weeks
+ * - `d` / `dd` : Days
+ * - `h` / `hh` : Hours
+ * - `m` / `mm` : Minutes
+ * - `s` / `ss` : Seconds
+ * - `ms` : Milliseconds, padded to three digits
+ *
+ * @param duration - The duration to format, as a {@link Duration} or a number of
+ * milliseconds.
+ * @param format - The template string containing tokens.
+ * @param options - How to handle the remainder and the month/year approximation.
+ * @returns Formatted duration string. An unknown token is left untouched, braces
+ * included.
+ * @see {@link getDurationParts} to reach the same parts as plain values.
+ *
+ * @remarks
+ * A negative duration yields negative parts, so every token renders a signed
+ * number — `'{{m}}:{{ss}}'` gives `-1:-30`, not `-1:30`. This is deliberate: the
+ * output stays faithful to the parts, and keeping a duration positive is the
+ * caller's business. Format the magnitude and write the sign yourself when a
+ * single leading minus is what you need.
+ *
+ * @example
+ * formatDuration(seconds(3725), '{{h}}:{{mm}}:{{ss}}')
+ * // => "1:02:05"
+ */
+export function formatDuration(duration, format, options = {}) {
+    const { floorSmallestUnit = true, useApproximateMonthAndYear = true } = options;
+    const parts = getDurationParts(duration, {
+        units: unitsInFormat(format),
+        floorSmallestUnit,
+        useApproximateMonthAndYear
+    });
+    return format.replace(tokenRegexp, (_match, token) => renderers[token](parts));
+}

package/agnostic/time/duration/format-duration/index.test.d.ts

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

package/agnostic/time/duration/format-duration/index.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { days, minutes, seconds } from '../index.js';
+import { formatDuration } from './index.js';
+import { getDurationParts } from './parts.js';
+const DAY = 86400000;
+describe('formatDuration', () => {
+    describe('template', () => {
+        it('splits the duration across the units the template mentions', () => {
+            expect(formatDuration(seconds(3725), '{{h}}:{{mm}}:{{ss}}')).toBe('1:02:05');
+        });
+        it('puts the whole duration on the only unit a template asks for', () => {
+            expect(formatDuration(seconds(3725), '{{s}}s')).toBe('3725s');
+            expect(formatDuration(days(400), '{{d}} days')).toBe('400 days');
+        });
+        it('accepts a plain number of milliseconds in place of a Duration', () => {
+            expect(formatDuration(3725000, '{{h}}:{{mm}}:{{ss}}')).toBe('1:02:05');
+        });
+        it('pads a doubled token to two digits and leaves its bare twin alone', () => {
+            expect(formatDuration(minutes(5), '{{mm}}:{{ss}}')).toBe('05:00');
+            expect(formatDuration(minutes(5), '{{m}}:{{s}}')).toBe('5:0');
+        });
+        it('pads milliseconds to three digits', () => {
+            expect(formatDuration(1042, '{{s}}.{{ms}}')).toBe('1.042');
+        });
+        it('substitutes every occurrence of a repeated token', () => {
+            expect(formatDuration(seconds(5), '{{s}}/{{s}}')).toBe('5/5');
+        });
+        it('leaves an unknown token untouched, braces included', () => {
+            expect(formatDuration(seconds(5), '{{ZZ}} {{s}}')).toBe('{{ZZ}} 5');
+        });
+        it('does not substitute a bare letter outside a placeholder', () => {
+            expect(formatDuration(seconds(5), 'd h m s {{s}}')).toBe('d h m s 5');
+        });
+    });
+    describe('remainder', () => {
+        it('drops the fraction of the smallest unit by default', () => {
+            expect(formatDuration(119600, '{{m}}:{{s}}')).toBe('1:59');
+        });
+        it('keeps the fraction when floorSmallestUnit is off', () => {
+            expect(formatDuration(119600, '{{m}}:{{s}}', { floorSmallestUnit: false })).toBe('1:59.6');
+        });
+    });
+    describe('month and year approximation', () => {
+        it('counts 365 days as a full year by default', () => {
+            expect(formatDuration(days(365), '{{Y}}')).toBe('1');
+        });
+        it('falls one year short of the Gregorian mean year when the approximation is off', () => {
+            expect(formatDuration(days(365), '{{Y}}', { useApproximateMonthAndYear: false })).toBe('0');
+        });
+    });
+    describe('negative durations', () => {
+        it('signs every part rather than the string as a whole', () => {
+            expect(formatDuration(seconds(-90), '{{m}}:{{ss}}')).toBe('-1:-30');
+        });
+    });
+});
+describe('getDurationParts', () => {
+    describe('breakdown', () => {
+        it('cascades the remainder from each unit down to the next', () => {
+            expect(getDurationParts(days(400), { units: ['Y', 'd'] })).toMatchObject({
+                Y: 1,
+                M: 0,
+                w: 0,
+                d: 35,
+                h: 0,
+                m: 0,
+                s: 0,
+                ms: 0
+            });
+        });
+        it('orders the units itself, whatever order they are given in', () => {
+            expect(getDurationParts(3725000, { units: ['s', 'h', 'm'] })).toMatchObject({ h: 1, m: 2, s: 5 });
+        });
+        it('ignores a unit listed twice', () => {
+            expect(getDurationParts(3725000, { units: ['h', 'm', 's', 'h'] })).toMatchObject({ h: 1, m: 2, s: 5 });
+        });
+        it('reaches every part under its readable name too', () => {
+            const parts = getDurationParts(3725000, { units: ['h', 'm', 's'] });
+            expect(parts).toMatchObject({
+                hours: parts.h,
+                minutes: parts.m,
+                seconds: parts.s,
+                milliseconds: parts.ms,
+                days: parts.d,
+                weeks: parts.w,
+                months: parts.M,
+                years: parts.Y
+            });
+        });
+    });
+    describe('units left out', () => {
+        it('puts the whole duration, fraction included, on the largest unit it reaches', () => {
+            const parts = getDurationParts(days(400));
+            expect(parts.Y).toBeCloseTo(1.0959, 4);
+            expect(parts.d).toBe(0);
+        });
+        it('picks the unit off the duration, not off the largest one that exists', () => {
+            expect(getDurationParts(90000).m).toBe(1.5);
+            expect(getDurationParts(500).ms).toBe(500);
+        });
+        it('falls back to milliseconds for a duration shorter than one', () => {
+            expect(getDurationParts(0.5)).toMatchObject({ ms: 0.5, s: 0 });
+        });
+        it('leaves every part at zero for a zero duration', () => {
+            expect(getDurationParts(0)).toMatchObject({
+                Y: 0, M: 0, w: 0, d: 0, h: 0, m: 0, s: 0, ms: 0
+            });
+        });
+    });
+    describe('floorSmallestUnit', () => {
+        it('leaves the remainder on the smallest unit by default', () => {
+            expect(getDurationParts(119600, { units: ['m', 's'] })).toMatchObject({ m: 1, s: 59.6 });
+        });
+        it('truncates the whole duration, so the missing fraction leaves every part', () => {
+            expect(getDurationParts(119600, { units: ['m', 's'], floorSmallestUnit: true })).toMatchObject({ m: 1, s: 59 });
+        });
+        it('rounds off the floating-point dust the cascade leaves behind', () => {
+            // 30 days on ['M', 'd'] divides exactly, but only in decimal.
+            expect(getDurationParts(30 * DAY, { units: ['M', 'd'], floorSmallestUnit: true })).toMatchObject({ M: 1, d: 0 });
+        });
+    });
+    describe('month and year approximation', () => {
+        it('uses 30-day months and 365-day years by default', () => {
+            expect(getDurationParts(365 * DAY, { units: ['Y', 'd'] })).toMatchObject({ Y: 1, d: 0 });
+            expect(getDurationParts(30 * DAY, { units: ['M', 'd'] })).toMatchObject({ M: 1, d: 0 });
+        });
+        it('uses the Gregorian mean year when the approximation is off', () => {
+            expect(getDurationParts(365 * DAY, {
+                units: ['Y', 'd'],
+                useApproximateMonthAndYear: false
+            })).toMatchObject({ Y: 0, d: 365 });
+            expect(getDurationParts(30 * DAY, {
+                units: ['M'],
+                useApproximateMonthAndYear: false
+            }).M).toBeCloseTo(0.9856, 4);
+        });
+    });
+    describe('negative durations', () => {
+        it('breaks the magnitude down, then negates every part', () => {
+            expect(getDurationParts(seconds(-90), { units: ['m', 's'] })).toMatchObject({ m: -1, s: -30 });
+        });
+        it('leaves an empty part at zero rather than at negative zero', () => {
+            const parts = getDurationParts(-30000, { units: ['m', 's'] });
+            expect(Object.is(parts.m, 0)).toBe(true);
+            expect(parts.s).toBe(-30);
+        });
+    });
+});

package/agnostic/time/duration/format-duration/parts.d.ts

@@ -0,0 +1,32 @@
+import { Duration } from '../index.js';
+import type { DurationParts, GetDurationPartsOptions } from './types.js';
+/**
+ * Breaks a duration down into its parts, cascading the remainder from each unit
+ * to the next.
+ *
+ * With several units, each one takes its whole part and hands the rest down, so
+ * `['M', 'd', 's']` reads as *X months and Y days and Z.mmm seconds*. With a
+ * single unit — including the one picked when `units` is omitted — that unit
+ * carries the whole duration, fraction included.
+ *
+ * @param duration - The duration to break down, as a {@link Duration} or a
+ * number of milliseconds.
+ * @param options - Which units to use, and how to handle the remainder.
+ * @returns The parts, each one reachable under its unit token and under its
+ * readable name. Units left out of the breakdown are `0`.
+ * @see {@link DurationParts}
+ *
+ * @remarks
+ * A negative duration is broken down by magnitude, then every part is negated.
+ * `floorSmallestUnit` truncates the duration *before* the cascade, so the whole
+ * breakdown describes the truncated duration rather than the original one —
+ * `1m 59.6s` gives `1m 59s`, and the missing `.6s` is gone from every part.
+ *
+ * @example
+ * getDurationParts(days(400), { units: ['Y', 'd'] })
+ * // => { Y: 1, years: 1, d: 35, days: 35, … every other unit at 0 }
+ *
+ * getDurationParts(days(400))
+ * // => { Y: 1.0958…, years: 1.0958…, … } — the largest unit it reaches
+ */
+export declare function getDurationParts(duration: Duration | number, options?: GetDurationPartsOptions): DurationParts;

package/agnostic/time/duration/format-duration/parts.js

@@ -0,0 +1,107 @@
+import { Duration } from '../index.js';
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const APPROXIMATE_YEAR = 365 * DAY;
+const APPROXIMATE_MONTH = 30 * DAY;
+/** The Gregorian mean year — 365.2425 days, the calendar's actual average. */
+const EXACT_YEAR = 365.2425 * DAY;
+const EXACT_MONTH = EXACT_YEAR / 12;
+/** Units from the longest to the shortest, in both approximation modes. */
+const unitsLongestFirst = ['Y', 'M', 'w', 'd', 'h', 'm', 's', 'ms'];
+/** How many milliseconds each unit is worth, under the chosen approximation. */
+function unitLengths(useApproximateMonthAndYear) {
+    return {
+        ms: 1,
+        s: SECOND,
+        m: MINUTE,
+        h: HOUR,
+        d: DAY,
+        w: WEEK,
+        M: useApproximateMonthAndYear ? APPROXIMATE_MONTH : EXACT_MONTH,
+        Y: useApproximateMonthAndYear ? APPROXIMATE_YEAR : EXACT_YEAR
+    };
+}
+/**
+ * The requested units, deduplicated and ordered longest first. Falls back to the
+ * single largest unit the duration reaches, and to `'ms'` for a duration shorter
+ * than a millisecond.
+ */
+function resolveUnits(units, absoluteMs, lengths) {
+    if (units !== undefined && units.length > 0) {
+        return unitsLongestFirst.filter(unit => units.includes(unit));
+    }
+    return [unitsLongestFirst.find(unit => absoluteMs >= lengths[unit]) ?? 'ms'];
+}
+/**
+ * Breaks a duration down into its parts, cascading the remainder from each unit
+ * to the next.
+ *
+ * With several units, each one takes its whole part and hands the rest down, so
+ * `['M', 'd', 's']` reads as *X months and Y days and Z.mmm seconds*. With a
+ * single unit — including the one picked when `units` is omitted — that unit
+ * carries the whole duration, fraction included.
+ *
+ * @param duration - The duration to break down, as a {@link Duration} or a
+ * number of milliseconds.
+ * @param options - Which units to use, and how to handle the remainder.
+ * @returns The parts, each one reachable under its unit token and under its
+ * readable name. Units left out of the breakdown are `0`.
+ * @see {@link DurationParts}
+ *
+ * @remarks
+ * A negative duration is broken down by magnitude, then every part is negated.
+ * `floorSmallestUnit` truncates the duration *before* the cascade, so the whole
+ * breakdown describes the truncated duration rather than the original one —
+ * `1m 59.6s` gives `1m 59s`, and the missing `.6s` is gone from every part.
+ *
+ * @example
+ * getDurationParts(days(400), { units: ['Y', 'd'] })
+ * // => { Y: 1, years: 1, d: 35, days: 35, … every other unit at 0 }
+ *
+ * getDurationParts(days(400))
+ * // => { Y: 1.0958…, years: 1.0958…, … } — the largest unit it reaches
+ */
+export function getDurationParts(duration, options = {}) {
+    const { units, floorSmallestUnit = false, useApproximateMonthAndYear = true } = options;
+    const totalMs = duration instanceof Duration ? duration.toMs() : duration;
+    const sign = totalMs < 0 ? -1 : 1;
+    const lengths = unitLengths(useApproximateMonthAndYear);
+    const usedUnits = resolveUnits(units, Math.abs(totalMs), lengths);
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const smallestUnit = usedUnits[usedUnits.length - 1];
+    const smallestLength = lengths[smallestUnit];
+    let remaining = Math.abs(totalMs);
+    if (floorSmallestUnit) {
+        remaining = Math.floor(remaining / smallestLength) * smallestLength;
+    }
+    const values = {
+        ms: 0, s: 0, m: 0, h: 0, d: 0, w: 0, M: 0, Y: 0
+    };
+    usedUnits.forEach((unit, pos) => {
+        const isSmallest = pos === usedUnits.length - 1;
+        const exact = remaining / lengths[unit];
+        // Math.round, not Math.floor, and deliberately so: the truncation already
+        // happened above, on the whole duration, so this value is a whole one by
+        // now. Rounding only clears the floating-point dust the divisions leave —
+        // flooring here would turn a 29.999999999 that means 30 into a 29.
+        const value = isSmallest
+            ? (floorSmallestUnit ? Math.round(exact) : exact)
+            : Math.floor(exact);
+        values[unit] = value === 0 ? 0 : value * sign;
+        remaining -= value * lengths[unit];
+    });
+    return {
+        ...values,
+        milliseconds: values.ms,
+        seconds: values.s,
+        minutes: values.m,
+        hours: values.h,
+        days: values.d,
+        weeks: values.w,
+        months: values.M,
+        years: values.Y
+    };
+}