Feat: Add toDuration Coercion (#345)

Author: jlukic

CHANGELOG.md

@@ -115,7 +115,8 @@ xx.xx.xxxx
 * **Breaking** - `kebabToCamel` and `camelToKebab` now use lossless encoding — digit-leading segments are preserved with `_` (e.g. `grid-2x2` → `grid_2x2`), and every uppercase letter gets its own hyphen (e.g. `arrowDownAZ` → `arrow-down-a-z`). Both accept a `separator` option to customize the digit-boundary character. `camelToKebab` now normalizes leading uppercase by default for DOM-safe output (e.g. `FooBar` → `foo-bar`); pass `{ lossless: true }` to preserve it for exact round-trips.
 * **Feature** - Added [`humanize`](https://next.semantic-ui.com/docs/api/utils/strings#humanize) — turns a machine identifier (`snake_case`, `kebab-case`, `camelCase`, `PascalCase`) into human-readable label text, keeping acronym runs whole including plurals (`getURLsFromPage` → `Get URLs from page`), dropping a trailing `id` (`user_id` → `User`), and sentence-casing by default. `titleCase` switches to header casing, `constantCase` sentence-cases shouting enums (`IN_PROGRESS` → `In progress`). The display-side inverse of `tokenize`
 * **Enhancement** - `humanize` rescues common lowercase acronyms out of the box (`api_url` → `API URL`) through a `humanize.config` vocabulary seeded with `id`/`url`/`api`. Extend it once at app boot and every call inherits it, or pass a per-call `terms` map that layers over the global. `humanize.config` also carries the default `titleCase`/`dropId`/`constantCase`
-* **Feature** - Added a coercion suite — [`toBoolean`](https://next.semantic-ui.com/docs/api/utils/coercion#toboolean), [`toNumber`](https://next.semantic-ui.com/docs/api/utils/coercion#tonumber), [`toInteger`](https://next.semantic-ui.com/docs/api/utils/coercion#tointeger), [`toDate`](https://next.semantic-ui.com/docs/api/utils/coercion#todate), [`toString`](https://next.semantic-ui.com/docs/api/utils/coercion#tostring), with `coerceX` aliases — best-effort conversion of loose input to a target type. Each returns the type or `null` when there is no clean reading, never a poison value, so results compose with `??`. `toBoolean` reads a generous set of true/false spellings, `toNumber` never yields `NaN` or `Infinity`, `toDate` takes ISO strings and epoch-ms numbers only (ambiguous formats like `01/15/2024` return null rather than a guessed Date), and `toString` returns null for objects instead of `"[object Object]"`. `toBoolean` and `toString` take `{ loose: true }` to fall back to native truthiness or JSON rendering. Every helper takes `{ onInvalid: 'passthrough' }` to return the original value on a failed coercion instead of `null`, so a schema or validator sees the bad input rather than an erasing `null` (the passthrough return widens the TypeScript type to include the input). `toBoolean` reads its vocabulary and defaults from an editable `toBoolean.config` (mirroring `humanize.config`), so a locale or domain teaches it new true/false spellings once at boot instead of on every call
+* **Feature** - Added a coercion suite — [`toBoolean`](https://next.semantic-ui.com/docs/api/utils/coercion#toboolean), [`toNumber`](https://next.semantic-ui.com/docs/api/utils/coercion#tonumber), [`toInteger`](https://next.semantic-ui.com/docs/api/utils/coercion#tointeger), [`toDate`](https://next.semantic-ui.com/docs/api/utils/coercion#todate), [`toDuration`](https://next.semantic-ui.com/docs/api/utils/coercion#toduration), [`toString`](https://next.semantic-ui.com/docs/api/utils/coercion#tostring), with `coerceX` aliases — best-effort conversion of loose input to a target type. Each returns the type or `null` when there is no clean reading, never a poison value, so results compose with `??`. `toBoolean` reads a generous set of true/false spellings, `toNumber` never yields `NaN` or `Infinity`, `toDate` takes ISO strings and epoch-ms numbers only (ambiguous formats like `01/15/2024` return null rather than a guessed Date), and `toString` returns null for objects instead of `"[object Object]"`. `toBoolean` and `toString` take `{ loose: true }` to fall back to native truthiness or JSON rendering. Every helper takes `{ onInvalid: 'passthrough' }` to return the original value on a failed coercion instead of `null`, so a schema or validator sees the bad input rather than an erasing `null` (the passthrough return widens the TypeScript type to include the input). `toBoolean` reads its vocabulary and defaults from an editable `toBoolean.config` (mirroring `humanize.config`), so a locale or domain teaches it new true/false spellings once at boot instead of on every call
+* **Feature** - Added [`toDuration`](https://next.semantic-ui.com/docs/api/utils/coercion#toduration) — reads a duration expression as milliseconds, so `'5s'`, `'1.5h'`, and `'300msecs'` all become numbers a timer or TTL takes directly. One number and one optional unit, case-insensitive, with the space optional, and unit words, abbreviations, and plurals all read (`'10 minutes'`, `'2hrs'`, `'.5d'`). A unitless string reads as milliseconds so `'1500'` and `1500` agree, the sign is kept, and a compound form like `'1h 30m'` returns `null` rather than a partial reading. Milliseconds through weeks are built in because each is a fixed span. Years and months are not: a year is a judgment call (the `ms` package reads it as 365.25 days) and a month has no length without a calendar date, so `toDuration.config.units` names your own value once at boot rather than inheriting someone else's guess
 * **Feature** - Added a bytes module — [`toBase64`](https://next.semantic-ui.com/docs/api/utils/bytes#tobase64) and [`fromBase64`](https://next.semantic-ui.com/docs/api/utils/bytes#frombase64) — unicode-safe base64 encode/decode, the pair `btoa`/`atob` never were. A string round-trips through its UTF-8 bytes (emoji and accents survive), `toBase64` also takes an `ArrayBuffer` or typed array and a `{ urlSafe }` option, and `fromBase64` decodes both alphabets, strips MIME/PEM line wrapping, and returns a string or `Uint8Array` — or `null` on malformed input, never a throw
 * **Feature** - Added [`configured`](https://next.semantic-ui.com/docs/api/utils/functions#configured) — attaches an editable `fn.config` to a function as one tree-shakable expression. All configured utilities (`humanize`, `toTitleCase`, `getArticle`, `toBoolean`, `formatDate`) use it, so a bundle only pays for the vocabularies it imports — the attribute-codec path that pulls in string casing no longer carries any of them
 * **Feature** - Arbitrary vocabularies now live in editable configs, set once at app boot: [`toTitleCase.config.stopWords`](https://next.semantic-ui.com/docs/api/utils/strings#totitlecase) (style guides disagree on the list, `humanize`'s `titleCase` reads the same one), [`getArticle.config.exceptions`](https://next.semantic-ui.com/docs/api/utils/strings#getarticle) for sound-contradicts-spelling words (`an hour`, `a university` now correct out of the box), and [`formatDate.config.timezones`](https://next.semantic-ui.com/docs/api/utils/dates#formatdate) for remapping an ambiguous shorthand like `IST`. `toDate` reads unix-second timestamps (a JWT `exp`) via `{ epoch: 'seconds' }`

ai/skills/authoring/utility-functions.md

@@ -577,10 +577,10 @@ suggest('stirng', ['strong', 'string'], { count: 3 }); // ['string', 'strong'] b
 
 ## Coercion Utilities (coercion.js)
 
-Best-effort conversion of loose input (attribute strings, query params, JSON) to a target type. Each returns the type or `null` when there is no clean reading, so results compose with `??`. Also exported as `coerceBoolean`/`coerceNumber`/`coerceInteger`/`coerceDate`/`coerceString`.
+Best-effort conversion of loose input (attribute strings, query params, JSON) to a target type. Each returns the type or `null` when there is no clean reading, so results compose with `??`. Also exported as `coerceBoolean`/`coerceNumber`/`coerceInteger`/`coerceDate`/`coerceDuration`/`coerceString`.
 
 ```javascript
-import { toBoolean, toNumber, toInteger, toDate, toString } from '@semantic-ui/utils';
+import { toBoolean, toNumber, toInteger, toDate, toDuration, toString } from '@semantic-ui/utils';
 
 toBoolean('yes');                       // true (generous: true/t/yes/y/on/enabled, false/f/no/n/off/disabled, numeric)
 toBoolean('banana');                    // null (unrecognized, composes with ??)
@@ -602,6 +602,13 @@ toDate('2024-01-01');                   // Date (ISO strings, epoch-ms numbers,
 toDate(1700000000, { epoch: 'seconds' }); // Date from a unix-second timestamp (a JWT exp)
 toDate('01/15/2024');                   // null (ambiguous format, never a guessed date)
 
+toDuration('5s');                       // 5000 (ms/s/m/h/d/w, plus word and abbreviation spellings)
+toDuration('10 minutes');               // 600000 (case-insensitive, space optional)
+toDuration('1500');                     // 1500 (no unit reads as milliseconds, same as the number)
+toDuration('1h 30m');                   // null (compound expressions are a different grammar)
+// years and months have no fixed length, so neither is built in. name your own value once at boot
+toDuration.config.units.y = 365 * 24 * 60 * 60 * 1000;
+
 toString(42);                           // '42'
 toString({ a: 1 });                     // null (never "[object Object]")
 toString({ a: 1 }, { loose: true });    // '{"a":1}' (render objects for display)

docs/src/content/examples/utils-toduration.mdx

@@ -0,0 +1,12 @@
+---
+title: 'toDuration'
+id: 'utils-toduration'
+sortIndex: 5
+exampleType: 'log'
+category: 'Utils'
+subcategory: 'Coercion'
+description: 'Coerce a duration expression to milliseconds, or null when it reads as no duration'
+tags: ['utils', 'coercion', 'toduration', 'duration', 'time', 'parse']
+selectedFile: 'index.js'
+tip: 'Unit words and abbreviations both read, so 10 minutes, 2hrs, and 300msecs all work. Years and months have no fixed length, so name your own value with toDuration.config.units'
+---

docs/src/examples/utils/coercion/utils-toduration/index.js

@@ -0,0 +1,9 @@
+import { toDuration } from '@semantic-ui/utils';
+
+console.log(toDuration('5s'));
+console.log(toDuration('1.5h'));
+console.log(toDuration('10 minutes'));
+console.log(toDuration('300msecs'));
+console.log(toDuration(1500));
+console.log(toDuration('1h 30m'));
+console.log(toDuration('soon') ?? 1000);

docs/src/pages/docs/api/utils/coercion.mdx

@@ -3,7 +3,7 @@ layout: '@layouts/Guide.astro'
 pageType: 'API Reference'
 title: Coercion Utilities
 package: "@semantic-ui/utils"
-methods: [toBoolean, toNumber, toInteger, toDate, toString]
+methods: [toBoolean, toNumber, toInteger, toDate, toDuration, toString]
 icon: replace
 description: API reference for best-effort type coercion functions
 ---
@@ -15,7 +15,7 @@ const page = toNumber(params.get('page')) ?? 1;
 const when = toDate(input.value) ?? new Date();
 ```
 
-Each helper is also exported as `coerceBoolean`, `coerceNumber`, `coerceInteger`, `coerceDate`, and `coerceString` for callers who think in coercion terms.
+Each helper is also exported as `coerceBoolean`, `coerceNumber`, `coerceInteger`, `coerceDate`, `coerceDuration`, and `coerceString` for callers who think in coercion terms.
 
 Every helper accepts an `onInvalid` setting. It defaults to `'null'` (the failed coercion returns `null`, composing with `??`). Pass `{ onInvalid: 'passthrough' }` to return the *original* value instead, so a schema or validator can flag the bad input rather than see an erasing `null` — and the TypeScript return widens to include the input type (`number | string` for `toNumber(str, { onInvalid: 'passthrough' })`).
 
@@ -192,6 +192,68 @@ console.log(toDate('banana')); // null (never an Invalid Date)
 const when = toDate(userInput) ?? new Date();
 ```
 
+### toDuration
+
+```javascript
+function toDuration(value, { onInvalid = 'null' } = {})
+```
+
+Coerces a duration expression to milliseconds, or `null` when it reads as no duration at all. A number is already milliseconds, and a string takes one number followed by one optional unit, case-insensitively, with an optional space between the two: `'5s'`, `'1.5h'`, `'10 minutes'`, `'2hrs'`, `'300msecs'`, `'.5d'`. Leave the unit off and the number reads as milliseconds, so `'1500'` and `1500` agree.
+
+The sign is kept, so `'-1.5h'` is `-5400000`. Compound expressions like `'1h 30m'` are a different grammar and return `null` rather than a partial reading, as do unknown units, bare numbers with trailing junk, and exponent notation.
+
+#### Units
+
+| Unit | Accepted spellings |
+|------|--------------------|
+| Milliseconds | `ms`, `msec`, `msecs`, `millisecond`, `milliseconds` |
+| Seconds | `s`, `sec`, `secs`, `second`, `seconds` |
+| Minutes | `m`, `min`, `mins`, `minute`, `minutes` |
+| Hours | `h`, `hr`, `hrs`, `hour`, `hours` |
+| Days | `d`, `day`, `days` |
+| Weeks | `w`, `week`, `weeks` |
+
+Every unit here is a fixed span. Years and months are absent because neither has one: a year is a judgment call (the `ms` package reads it as 365.25 days) and a month has no length without a calendar date to anchor it. Name your own value in `toDuration.config.units` rather than inheriting someone else's guess.
+
+#### Parameters
+
+| Name     | Type    | Description |
+|----------|---------|-------------|
+| value    | unknown | The value to coerce |
+| settings | object  | Optional configuration (`onInvalid`, see above) |
+
+#### Returns
+
+The duration in milliseconds, or `null` if unreadable.
+
+#### Example
+
+```javascript
+import { toDuration } from '@semantic-ui/utils';
+
+console.log(toDuration('5s')); // 5000
+console.log(toDuration('1.5h')); // 5400000
+console.log(toDuration('10 minutes')); // 600000
+console.log(toDuration(1500)); // 1500 (already milliseconds)
+console.log(toDuration('1500')); // 1500 (no unit reads as milliseconds)
+console.log(toDuration('1h 30m')); // null (compound expressions are a different grammar)
+
+setTimeout(retry, toDuration(config.retryAfter) ?? 1000);
+```
+
+#### toDuration.config
+
+`toDuration.config.units` holds the milliseconds per unit, keyed by the lowercase spelling accepted after the number. Edit it once at app boot to teach the grammar a unit your domain uses, and every call inherits it.
+
+```javascript
+import { toDuration } from '@semantic-ui/utils';
+
+toDuration.config.units.y = 365 * 24 * 60 * 60 * 1000;
+toDuration.config.units.years = toDuration.config.units.y;
+
+console.log(toDuration('1y')); // 31536000000
+```
+
 ### toString
 
 ```javascript

packages/utils/src/coercion.js

@@ -10,6 +10,16 @@ import { isArray, isBoolean, isDate, isNumber, isObject, isString } from './type
 // client), returned as a UTC instant, matching what native new Date does with an <input type=datetime-local>
 const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
 
+// one number, an optional space, one optional unit, mirroring the ecosystem's ms(). a compound form
+// like '1h 30m' is a different grammar and reads as junk here
+const DURATION_RE = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*([a-z]*)$/i;
+
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+
 // fold -0 to 0 so a coerced value never trips Object.is or 1/x downstream
 const normalizeZero = (number) => (number === 0 ? 0 : number);
 
@@ -112,6 +122,60 @@ export const toDate = (value, { onInvalid = 'null', epoch = 'milliseconds' } = {
   return onInvalidResult(value, onInvalid);
 };
 
+// only fixed-length spans are listed. a week is always 7 days, but a year is a pick (ms() reads it
+// as 365.25 days) and a month has no length at all, so neither is guessed here. add one at boot with
+// toDuration.config.units.y = 365 * 24 * 60 * 60 * 1000, where keys are matched lowercase
+export const toDuration = /* @__PURE__ */ configured(
+  (value, { onInvalid = 'null' } = {}) => {
+    // a number is already milliseconds, the unit taken by timers, TTLs, and animation APIs
+    if (isNumber(value)) { return Number.isFinite(value) ? normalizeZero(value) : onInvalidResult(value, onInvalid); }
+    if (isString(value)) {
+      const match = DURATION_RE.exec(value.trim());
+      if (match) {
+        const units = toDuration.config.units;
+        const unit = match[2].toLowerCase() || 'ms';
+        // an inherited key ('5constructor') or a 300-digit overflow would otherwise produce NaN or
+        // Infinity, which this family never returns
+        if (Object.hasOwn(units, unit)) {
+          const milliseconds = Number(match[1]) * units[unit];
+          if (Number.isFinite(milliseconds)) { return normalizeZero(milliseconds); }
+        }
+      }
+    }
+    return onInvalidResult(value, onInvalid);
+  },
+  {
+    units: {
+      ms: 1,
+      msec: 1,
+      msecs: 1,
+      millisecond: 1,
+      milliseconds: 1,
+      s: SECOND,
+      sec: SECOND,
+      secs: SECOND,
+      second: SECOND,
+      seconds: SECOND,
+      m: MINUTE,
+      min: MINUTE,
+      mins: MINUTE,
+      minute: MINUTE,
+      minutes: MINUTE,
+      h: HOUR,
+      hr: HOUR,
+      hrs: HOUR,
+      hour: HOUR,
+      hours: HOUR,
+      d: DAY,
+      day: DAY,
+      days: DAY,
+      w: WEEK,
+      week: WEEK,
+      weeks: WEEK,
+    },
+  },
+);
+
 export const toString = (value, { loose = false, onInvalid = 'null' } = {}) => {
   if (isString(value)) { return value; }
   if (value == null) { return onInvalidResult(value, onInvalid); }
@@ -135,4 +199,5 @@ export const coerceBoolean = toBoolean;
 export const coerceNumber = toNumber;
 export const coerceInteger = toInteger;
 export const coerceDate = toDate;
+export const coerceDuration = toDuration;
 export const coerceString = toString;