chrono-ms 1.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Francisco Luis Rios Vega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,334 @@
+# chrono-ms
+
+A lightweight, TypeScript-first library for parsing and formatting time durations.
+
+[![NPM version](https://img.shields.io/npm/v/chrono-ms?color=32A9C3&labelColor=1B3C4A&label=npm&logo=npm)](https://www.npmjs.com/package/chrono-ms)
+[![NPM downloads](https://img.shields.io/npm/dm/chrono-ms?color=32A9C3&labelColor=1B3C4A&label=downloads&logo=npm)](https://www.npmjs.com/package/chrono-ms)
+[![NPM License](https://img.shields.io/npm/l/chrono-ms?color=32A9C3&labelColor=1B3C4A&label=license&logo=github)](https://www.npmjs.com/package/chrono-ms)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/iscodex/chrono-ms/ci.yml?color=32A9C3&labelColor=1B3C4A&label=CI&logo=github)](https://github.com/iscodex/chrono-ms/actions)
+
+## Features
+
+- 🚀 **Lightweight**: Zero dependencies
+- 📝 **TypeScript-first**: Full type safety and IntelliSense support
+- 🔄 **Bidirectional**: Parse strings to milliseconds and format milliseconds to strings
+- 🎯 **Precise**: Handles decimal values and negative numbers
+- 📚 **Comprehensive**: Supports all common time units including months
+- 🧪 **Well-tested**: >95% test coverage
+
+## Installation
+
+```bash
+npm install chrono-ms
+```
+
+```bash
+yarn add chrono-ms
+```
+
+```bash
+pnpm add chrono-ms
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import ms from 'chrono-ms';
+
+// Parse string to milliseconds
+ms('2 hours'); // 7200000
+ms('1d'); // 86400000
+ms('10h'); // 36000000
+ms('2.5 hrs'); // 9000000
+ms('1y'); // 31557600000
+
+// Format milliseconds to string
+ms(60000); // "1m"
+ms(2 * 60 * 1000); // "2m"
+ms(ms('10 hours') as number); // "10h"
+ms(60000, { long: true }); // "1 minute"
+ms(2 * 60 * 1000, { long: true }); // "2 minutes"
+```
+
+### Individual Functions
+
+```typescript
+import { parse, format } from 'chrono-ms';
+
+// Parse only
+const milliseconds = parse('1.5h'); // 5400000
+
+// Format only
+const shortFormat = format(3600000); // "1h"
+const longFormat = format(3600000, { long: true }); // "1 hour"
+```
+
+### Compound Strings with `parseMultiple`
+
+```typescript
+import { parseMultiple } from 'chrono-ms';
+
+parseMultiple('1h 30m'); // 5400000
+parseMultiple('2d 4h 30m'); // 189000000
+parseMultiple('1w 3d'); // 864000000
+```
+
+### Safe Parsing with `tryParse`
+
+```typescript
+import { tryParse } from 'chrono-ms';
+
+// Returns null instead of throwing on invalid input
+tryParse('2h'); // 7200000
+tryParse('invalid'); // null
+tryParse(''); // null
+```
+
+### Verbose Format
+
+```typescript
+import { format } from 'chrono-ms';
+
+format(5400000, { verbose: true }); // "1h 30m"
+format(5400000, { verbose: true, long: true }); // "1 hour 30 minutes"
+format(3661000, { verbose: true }); // "1h 1m 1s"
+format(90000, { verbose: true }); // "1m 30s"
+```
+
+### Advanced Usage
+
+```typescript
+import ms, {
+  parse,
+  format,
+  type FormatOptions,
+  type ParseOptions,
+} from 'chrono-ms';
+
+// Custom parsing options
+const result = parse('30m', { maxLength: 50 });
+
+// Custom formatting options
+const formatted = format(7200000, { long: true });
+
+// Type-safe string values
+type TimeString = `${number}h` | `${number}m` | `${number}s`;
+const timeValue: TimeString = '2h';
+const parsed = ms(timeValue); // 7200000
+```
+
+## Supported Units
+
+| Unit         | Long Format                                    | Short Format |
+| ------------ | ---------------------------------------------- | ------------ |
+| Years        | `years`, `year`, `yrs`, `yr`                   | `y`          |
+| Weeks        | `weeks`, `week`                                | `w`          |
+| Months       | `months`, `month`                              | `mo`         |
+| Days         | `days`, `day`                                  | `d`          |
+| Hours        | `hours`, `hour`, `hrs`, `hr`                   | `h`          |
+| Minutes      | `minutes`, `minute`, `mins`, `min`             | `m`          |
+| Seconds      | `seconds`, `second`, `secs`, `sec`             | `s`          |
+| Milliseconds | `milliseconds`, `millisecond`, `msecs`, `msec` | `ms`         |
+
+> **Note:** `mo` is used for months to avoid ambiguity with `m` (minutes). Month is defined as exactly 30 days.
+
+All units are case-insensitive and support both singular and plural forms.
+
+## API Reference
+
+### `ms(value, options?)`
+
+Main function that can parse strings or format numbers.
+
+**Parameters:**
+
+- `value: string | number` - String to parse or number to format
+- `options?: FormatOptions | ParseOptions` - Configuration options
+
+**Returns:**
+
+- `number` when parsing strings
+- `string` when formatting numbers
+
+### `parse(value, options?)`
+
+Parse a time string into milliseconds.
+
+**Parameters:**
+
+- `value: string` - Time string to parse
+- `options?: ParseOptions` - Parsing configuration
+
+**Returns:** `number` - Parsed time in milliseconds
+
+**Options:**
+
+- `maxLength?: number` - Maximum string length, must be a positive number (default: 100)
+
+### `tryParse(value, options?)`
+
+Parse a time string and return `null` instead of throwing on invalid input.
+
+**Parameters:**
+
+- `value: string` - Time string to parse
+- `options?: ParseOptions` - Parsing configuration
+
+**Returns:** `number | null` - Parsed milliseconds, or `null` on failure
+
+### `parseMultiple(value, options?)`
+
+Parse a compound time string with multiple space-separated tokens.
+
+**Parameters:**
+
+- `value: string` - Compound time string (e.g., `"1h 30m"`, `"2d 4h 30m"`)
+- `options?: ParseOptions` - Parsing configuration applied to each token
+
+**Returns:** `number` - Total duration in milliseconds
+
+### `format(ms, options?)`
+
+Format milliseconds into a human-readable string.
+
+**Parameters:**
+
+- `ms: number` - Milliseconds to format
+- `options?: FormatOptions` - Formatting configuration
+
+**Returns:** `string` - Formatted time string
+
+**Options:**
+
+- `long?: boolean` - Use long format (default: false)
+- `verbose?: boolean` - Show all non-zero components decomposed (default: false)
+
+## Examples
+
+### Basic Parsing
+
+```typescript
+ms('1s'); // 1000
+ms('1m'); // 60000
+ms('1h'); // 3600000
+ms('1d'); // 86400000
+ms('1w'); // 604800000
+ms('1y'); // 31557600000
+```
+
+### Decimal Values
+
+```typescript
+ms('1.5h'); // 5400000
+ms('0.5d'); // 43200000
+ms('2.5 hours'); // 9000000
+```
+
+### Negative Values
+
+```typescript
+ms('-1h'); // -3600000
+ms('-30m'); // -1800000
+```
+
+### Different Formats
+
+```typescript
+// Short format (default)
+ms(60000); // "1m"
+ms(3600000); // "1h"
+ms(604800000); // "1w"
+ms(31557600000); // "1y"
+
+// Long format
+ms(60000, { long: true }); // "1 minute"
+ms(120000, { long: true }); // "2 minutes"
+ms(3600000, { long: true }); // "1 hour"
+ms(7200000, { long: true }); // "2 hours"
+
+// Verbose format (decomposed)
+format(5400000, { verbose: true }); // "1h 30m"
+format(5400000, { verbose: true, long: true }); // "1 hour 30 minutes"
+```
+
+### Months
+
+```typescript
+parse('1mo'); // 2592000000  (30 days)
+parse('6 months'); // 15552000000
+```
+
+## Error Handling
+
+The library throws descriptive errors for invalid inputs:
+
+```typescript
+try {
+  ms('invalid');
+} catch (error) {
+  console.log(error.message); // "Invalid time format: "invalid""
+}
+
+try {
+  ms('a'.repeat(101));
+} catch (error) {
+  console.log(error.message); // "String too long. Maximum length is 100 characters"
+}
+
+try {
+  format(NaN);
+} catch (error) {
+  console.log(error.message); // "Value must be a finite number"
+}
+```
+
+## Limitations
+
+- Maximum string length is 100 characters by default (configurable via `maxLength`)
+- Uses approximate year length (365.25 days)
+- Month is defined as exactly 30 days (not calendar-aware)
+- `format()` does not output months; use `parse('1mo')` for input only
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm run test:watch
+
+# Run tests with coverage
+pnpm run test:coverage
+
+# Build the package
+pnpm run build
+
+# Lint the code
+pnpm run lint
+
+# Type check
+pnpm run type-check
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+- Supports ES Modules
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT © [Francisco Luis Rios Vega](https://github.com/alckordev)

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Time constants in milliseconds
+ */
+export declare const SECOND = 1000;
+export declare const MINUTE: number;
+export declare const HOUR: number;
+export declare const DAY: number;
+export declare const WEEK: number;
+export declare const MONTH: number;
+export declare const YEAR: number;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,MAAM,OAAO,CAAC;AAC3B,eAAO,MAAM,MAAM,QAAc,CAAC;AAClC,eAAO,MAAM,IAAI,QAAc,CAAC;AAChC,eAAO,MAAM,GAAG,QAAY,CAAC;AAC7B,eAAO,MAAM,IAAI,QAAU,CAAC;AAC5B,eAAO,MAAM,KAAK,QAAW,CAAC;AAC9B,eAAO,MAAM,IAAI,QAAe,CAAC"}

package/dist/format.d.ts

@@ -0,0 +1,19 @@
+import type { FormatOptions } from './types';
+/**
+ * Format milliseconds to a human-readable string.
+ *
+ * @param ms - Milliseconds to format
+ * @param options - Formatting options
+ * @returns Formatted string
+ * @throws {Error} When the input is not a finite number
+ *
+ * @example
+ * ```ts
+ * format(7200000);                              // "2h"
+ * format(7200000, { long: true });              // "2 hours"
+ * format(5400000, { verbose: true });           // "1h 30m"
+ * format(5400000, { verbose: true, long: true }); // "1 hour 30 minutes"
+ * ```
+ */
+export declare function format(ms: number, options?: FormatOptions): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAUtE"}

package/dist/index.cjs

@@ -0,0 +1,264 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Time constants in milliseconds
+ */
+const SECOND = 1000;
+const MINUTE = SECOND * 60;
+const HOUR = MINUTE * 60;
+const DAY = HOUR * 24;
+const WEEK = DAY * 7;
+const MONTH = DAY * 30;
+const YEAR = DAY * 365.25;
+
+/**
+ * Parse a time string and return milliseconds.
+ *
+ * @param value - Time string to parse (e.g., "2h", "30 minutes", "1d", "1mo")
+ * @param options - Parsing options
+ * @returns Parsed time in milliseconds
+ * @throws {Error} When the string format is invalid
+ *
+ * @example
+ * ```ts
+ * parse("2h");        // 7200000
+ * parse("30 minutes"); // 1800000
+ * parse("1d");        // 86400000
+ * parse("1mo");       // 2592000000
+ * ```
+ */
+function parse(value, options = {}) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error('Value must be a non-empty string');
+    }
+    const { maxLength } = options;
+    if (maxLength !== undefined && maxLength <= 0) {
+        throw new Error('maxLength must be a positive number');
+    }
+    const resolvedMaxLength = maxLength ?? 100;
+    if (value.length > resolvedMaxLength) {
+        throw new Error(`String too long. Maximum length is ${resolvedMaxLength} characters`);
+    }
+    // months?|mo must appear before minutes?|mins?|m to avoid partial match ambiguity
+    const match = /^(-?(?:\d+)?\.?\d+) *(milliseconds?|msecs?|ms|seconds?|secs?|s|months?|mo|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)?$/i.exec(value.trim());
+    if (!match) {
+        throw new Error(`Invalid time format: "${value}"`);
+    }
+    const num = parseFloat(match[1]);
+    /* istanbul ignore next */
+    if (!isFinite(num)) {
+        throw new Error(`Invalid number: "${match[1]}"`);
+    }
+    const unit = (match[2] || 'ms').toLowerCase();
+    switch (unit) {
+        case 'years':
+        case 'year':
+        case 'yrs':
+        case 'yr':
+        case 'y':
+            return num * YEAR;
+        case 'weeks':
+        case 'week':
+        case 'w':
+            return num * WEEK;
+        case 'months':
+        case 'month':
+        case 'mo':
+            return num * MONTH;
+        case 'days':
+        case 'day':
+        case 'd':
+            return num * DAY;
+        case 'hours':
+        case 'hour':
+        case 'hrs':
+        case 'hr':
+        case 'h':
+            return num * HOUR;
+        case 'minutes':
+        case 'minute':
+        case 'mins':
+        case 'min':
+        case 'm':
+            return num * MINUTE;
+        case 'seconds':
+        case 'second':
+        case 'secs':
+        case 'sec':
+        case 's':
+            return num * SECOND;
+        case 'milliseconds':
+        case 'millisecond':
+        case 'msecs':
+        case 'msec':
+        case 'ms':
+            return num;
+        /* istanbul ignore next */
+        default:
+            throw new Error(`Unknown unit: "${unit}"`);
+    }
+}
+/**
+ * Parse a time string and return milliseconds, or `null` if the input is invalid.
+ * Useful when input is untrusted and exception handling would be verbose.
+ *
+ * @param value - Time string to parse
+ * @param options - Parsing options
+ * @returns Parsed time in milliseconds, or `null` on failure
+ *
+ * @example
+ * ```ts
+ * tryParse("2h");      // 7200000
+ * tryParse("invalid"); // null
+ * ```
+ */
+function tryParse(value, options) {
+    try {
+        return parse(value, options);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse a compound time string with multiple space-separated tokens.
+ *
+ * @param value - Compound time string (e.g., "1h 30m", "2d 4h 30m")
+ * @param options - Parsing options applied to each token
+ * @returns Total duration in milliseconds
+ * @throws {Error} When any token has an invalid format
+ *
+ * @example
+ * ```ts
+ * parseMultiple("1h 30m");    // 5400000
+ * parseMultiple("2d 4h 30m"); // 189000000
+ * ```
+ */
+function parseMultiple(value, options) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error('Value must be a non-empty string');
+    }
+    return value
+        .trim()
+        .split(/\s+/)
+        .reduce((acc, token) => acc + parse(token, options), 0);
+}
+
+/**
+ * Format milliseconds to a human-readable string.
+ *
+ * @param ms - Milliseconds to format
+ * @param options - Formatting options
+ * @returns Formatted string
+ * @throws {Error} When the input is not a finite number
+ *
+ * @example
+ * ```ts
+ * format(7200000);                              // "2h"
+ * format(7200000, { long: true });              // "2 hours"
+ * format(5400000, { verbose: true });           // "1h 30m"
+ * format(5400000, { verbose: true, long: true }); // "1 hour 30 minutes"
+ * ```
+ */
+function format(ms, options = {}) {
+    if (typeof ms !== 'number' || !isFinite(ms)) {
+        throw new Error('Value must be a finite number');
+    }
+    if (options.verbose) {
+        return formatVerbose(ms, options.long ?? false);
+    }
+    return options.long ? formatLong(ms) : formatShort(ms);
+}
+function formatShort(ms) {
+    const absMs = Math.abs(ms);
+    if (absMs >= YEAR)
+        return Math.round(ms / YEAR) + 'y';
+    if (absMs >= WEEK)
+        return Math.round(ms / WEEK) + 'w';
+    if (absMs >= DAY)
+        return Math.round(ms / DAY) + 'd';
+    if (absMs >= HOUR)
+        return Math.round(ms / HOUR) + 'h';
+    if (absMs >= MINUTE)
+        return Math.round(ms / MINUTE) + 'm';
+    if (absMs >= SECOND)
+        return Math.round(ms / SECOND) + 's';
+    return ms + 'ms';
+}
+function formatLong(ms) {
+    const absMs = Math.abs(ms);
+    if (absMs >= YEAR)
+        return plural(ms, absMs, YEAR, 'year');
+    if (absMs >= WEEK)
+        return plural(ms, absMs, WEEK, 'week');
+    if (absMs >= DAY)
+        return plural(ms, absMs, DAY, 'day');
+    if (absMs >= HOUR)
+        return plural(ms, absMs, HOUR, 'hour');
+    if (absMs >= MINUTE)
+        return plural(ms, absMs, MINUTE, 'minute');
+    if (absMs >= SECOND)
+        return plural(ms, absMs, SECOND, 'second');
+    return ms + ' ms';
+}
+/**
+ * Format milliseconds showing all non-zero components decomposed by unit.
+ * Handles negative values by prefixing the result with "-".
+ */
+function formatVerbose(ms, long) {
+    const negative = ms < 0;
+    let remaining = Math.abs(ms);
+    const parts = [];
+    const units = [
+        [YEAR, 'y', 'year'],
+        [WEEK, 'w', 'week'],
+        [DAY, 'd', 'day'],
+        [HOUR, 'h', 'hour'],
+        [MINUTE, 'm', 'minute'],
+        [SECOND, 's', 'second'],
+    ];
+    for (const [unit, short, name] of units) {
+        if (remaining >= unit) {
+            const count = Math.floor(remaining / unit);
+            remaining -= count * unit;
+            parts.push(long
+                ? `${count} ${count === 1 ? name : name + 's'}`
+                : `${count}${short}`);
+        }
+    }
+    if (remaining > 0 || parts.length === 0) {
+        parts.push(long ? `${remaining} ms` : `${remaining}ms`);
+    }
+    const result = parts.join(' ');
+    return negative ? `-${result}` : result;
+}
+function plural(ms, absMs, unit, name) {
+    const isPlural = absMs >= unit * 1.5;
+    return Math.round(ms / unit) + ' ' + name + (isPlural ? 's' : '');
+}
+
+function ms(value, options) {
+    if (typeof value === 'string') {
+        return parse(value, options);
+    }
+    if (typeof value === 'number') {
+        return format(value, options);
+    }
+    throw new Error('Value must be a string or number');
+}
+
+exports.DAY = DAY;
+exports.HOUR = HOUR;
+exports.MINUTE = MINUTE;
+exports.MONTH = MONTH;
+exports.SECOND = SECOND;
+exports.WEEK = WEEK;
+exports.YEAR = YEAR;
+exports.default = ms;
+exports.format = format;
+exports.parse = parse;
+exports.parseMultiple = parseMultiple;
+exports.tryParse = tryParse;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/constants.ts","../src/parse.ts","../src/format.ts","../src/ms.ts"],"sourcesContent":[null,null,null,null],"names":[],"mappings":";;;;AAAA;;AAEG;AACI,MAAM,MAAM,GAAG;AACf,MAAM,MAAM,GAAG,MAAM,GAAG;AACxB,MAAM,IAAI,GAAG,MAAM,GAAG;AACtB,MAAM,GAAG,GAAG,IAAI,GAAG;AACnB,MAAM,IAAI,GAAG,GAAG,GAAG;AACnB,MAAM,KAAK,GAAG,GAAG,GAAG;AACpB,MAAM,IAAI,GAAG,GAAG,GAAG;;ACN1B;;;;;;;;;;;;;;;AAeG;SACa,KAAK,CAAC,KAAa,EAAE,UAAwB,EAAE,EAAA;AAC7D,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE;AAC1D,QAAA,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC;IACrD;AAEA,IAAA,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO;IAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,IAAI,CAAC,EAAE;AAC7C,QAAA,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC;IACxD;AAEA,IAAA,MAAM,iBAAiB,GAAG,SAAS,IAAI,GAAG;AAC1C,IAAA,IAAI,KAAK,CAAC,MAAM,GAAG,iBAAiB,EAAE;AACpC,QAAA,MAAM,IAAI,KAAK,CACb,sCAAsC,iBAAiB,CAAA,WAAA,CAAa,CACrE;IACH;;IAGA,MAAM,KAAK,GACT,6IAA6I,CAAC,IAAI,CAChJ,KAAK,CAAC,IAAI,EAAE,CACb;IAEH,IAAI,CAAC,KAAK,EAAE;AACV,QAAA,MAAM,IAAI,KAAK,CAAC,yBAAyB,KAAK,CAAA,CAAA,CAAG,CAAC;IACpD;IAEA,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;;AAEhC,IAAA,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;QAClB,MAAM,IAAI,KAAK,CAAC,CAAA,iBAAA,EAAoB,KAAK,CAAC,CAAC,CAAC,CAAA,CAAA,CAAG,CAAC;IAClD;AAEA,IAAA,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,WAAW,EAAE;IAE7C,QAAQ,IAAI;AACV,QAAA,KAAK,OAAO;AACZ,QAAA,KAAK,MAAM;AACX,QAAA,KAAK,KAAK;AACV,QAAA,KAAK,IAAI;AACT,QAAA,KAAK,GAAG;YACN,OAAO,GAAG,GAAG,IAAI;AACnB,QAAA,KAAK,OAAO;AACZ,QAAA,KAAK,MAAM;AACX,QAAA,KAAK,GAAG;YACN,OAAO,GAAG,GAAG,IAAI;AACnB,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,OAAO;AACZ,QAAA,KAAK,IAAI;YACP,OAAO,GAAG,GAAG,KAAK;AACpB,QAAA,KAAK,MAAM;AACX,QAAA,KAAK,KAAK;AACV,QAAA,KAAK,GAAG;YACN,OAAO,GAAG,GAAG,GAAG;AAClB,QAAA,KAAK,OAAO;AACZ,QAAA,KAAK,MAAM;AACX,QAAA,KAAK,KAAK;AACV,QAAA,KAAK,IAAI;AACT,QAAA,KAAK,GAAG;YACN,OAAO,GAAG,GAAG,IAAI;AACnB,QAAA,KAAK,SAAS;AACd,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,MAAM;AACX,QAAA,KAAK,KAAK;AACV,QAAA,KAAK,GAAG;YACN,OAAO,GAAG,GAAG,MAAM;AACrB,QAAA,KAAK,SAAS;AACd,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,MAAM;AACX,QAAA,KAAK,KAAK;AACV,QAAA,KAAK,GAAG;YACN,OAAO,GAAG,GAAG,MAAM;AACrB,QAAA,KAAK,cAAc;AACnB,QAAA,KAAK,aAAa;AAClB,QAAA,KAAK,OAAO;AACZ,QAAA,KAAK,MAAM;AACX,QAAA,KAAK,IAAI;AACP,YAAA,OAAO,GAAG;;AAEZ,QAAA;AACE,YAAA,MAAM,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAA,CAAA,CAAG,CAAC;;AAEhD;AAEA;;;;;;;;;;;;;AAaG;AACG,SAAU,QAAQ,CAAC,KAAa,EAAE,OAAsB,EAAA;AAC5D,IAAA,IAAI;AACF,QAAA,OAAO,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC;IAC9B;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,IAAI;IACb;AACF;AAEA;;;;;;;;;;;;;AAaG;AACG,SAAU,aAAa,CAAC,KAAa,EAAE,OAAsB,EAAA;AACjE,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE;AAC1D,QAAA,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC;IACrD;AAEA,IAAA,OAAO;AACJ,SAAA,IAAI;SACJ,KAAK,CAAC,KAAK;AACX,SAAA,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,GAAG,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AAC3D;;ACjJA;;;;;;;;;;;;;;;AAeG;SACa,MAAM,CAAC,EAAU,EAAE,UAAyB,EAAE,EAAA;IAC5D,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE;AAC3C,QAAA,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC;IAClD;AAEA,IAAA,IAAI,OAAO,CAAC,OAAO,EAAE;QACnB,OAAO,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC;IACjD;AAEA,IAAA,OAAO,OAAO,CAAC,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC;AACxD;AAEA,SAAS,WAAW,CAAC,EAAU,EAAA;IAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAE1B,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG;IACrD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG;IACrD,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,GAAG;IACnD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG;IACrD,IAAI,KAAK,IAAI,MAAM;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,GAAG;IACzD,IAAI,KAAK,IAAI,MAAM;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,GAAG;IACzD,OAAO,EAAE,GAAG,IAAI;AAClB;AAEA,SAAS,UAAU,CAAC,EAAU,EAAA;IAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAE1B,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC;IACzD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC;IACzD,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC;IACtD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC;IACzD,IAAI,KAAK,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC;IAC/D,IAAI,KAAK,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC;IAC/D,OAAO,EAAE,GAAG,KAAK;AACnB;AAEA;;;AAGG;AACH,SAAS,aAAa,CAAC,EAAU,EAAE,IAAa,EAAA;AAC9C,IAAA,MAAM,QAAQ,GAAG,EAAE,GAAG,CAAC;IACvB,IAAI,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAa,EAAE;AAE1B,IAAA,MAAM,KAAK,GAAoC;AAC7C,QAAA,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC;AACnB,QAAA,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC;AACnB,QAAA,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC;AACjB,QAAA,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC;AACnB,QAAA,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC;AACvB,QAAA,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC;KACxB;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE;AACvC,QAAA,IAAI,SAAS,IAAI,IAAI,EAAE;YACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;AAC1C,YAAA,SAAS,IAAI,KAAK,GAAG,IAAI;YACzB,KAAK,CAAC,IAAI,CACR;AACE,kBAAE,CAAA,EAAG,KAAK,CAAA,CAAA,EAAI,KAAK,KAAK,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,CAAA;AAC7C,kBAAE,CAAA,EAAG,KAAK,GAAG,KAAK,CAAA,CAAE,CACvB;QACH;IACF;IAEA,IAAI,SAAS,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;AACvC,QAAA,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAA,EAAG,SAAS,CAAA,GAAA,CAAK,GAAG,GAAG,SAAS,CAAA,EAAA,CAAI,CAAC;IACzD;IAEA,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;IAC9B,OAAO,QAAQ,GAAG,CAAA,CAAA,EAAI,MAAM,CAAA,CAAE,GAAG,MAAM;AACzC;AAEA,SAAS,MAAM,CAAC,EAAU,EAAE,KAAa,EAAE,IAAY,EAAE,IAAY,EAAA;AACnE,IAAA,MAAM,QAAQ,GAAG,KAAK,IAAI,IAAI,GAAG,GAAG;IACpC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,IAAI,IAAI,QAAQ,GAAG,GAAG,GAAG,EAAE,CAAC;AACnE;;AC5EA,SAAS,EAAE,CACT,KAA2B,EAC3B,OAAsC,EAAA;AAEtC,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;AAC7B,QAAA,OAAO,KAAK,CAAC,KAAK,EAAE,OAAuB,CAAC;IAC9C;AAEA,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;AAC7B,QAAA,OAAO,MAAM,CAAC,KAAK,EAAE,OAAwB,CAAC;IAChD;AAEA,IAAA,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC;AACrD;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './constants';
+export * from './types';
+export * from './parse';
+export * from './format';
+export { default } from './ms';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC"}

package/dist/index.esm.js

@@ -0,0 +1,249 @@
+/**
+ * Time constants in milliseconds
+ */
+const SECOND = 1000;
+const MINUTE = SECOND * 60;
+const HOUR = MINUTE * 60;
+const DAY = HOUR * 24;
+const WEEK = DAY * 7;
+const MONTH = DAY * 30;
+const YEAR = DAY * 365.25;
+
+/**
+ * Parse a time string and return milliseconds.
+ *
+ * @param value - Time string to parse (e.g., "2h", "30 minutes", "1d", "1mo")
+ * @param options - Parsing options
+ * @returns Parsed time in milliseconds
+ * @throws {Error} When the string format is invalid
+ *
+ * @example
+ * ```ts
+ * parse("2h");        // 7200000
+ * parse("30 minutes"); // 1800000
+ * parse("1d");        // 86400000
+ * parse("1mo");       // 2592000000
+ * ```
+ */
+function parse(value, options = {}) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error('Value must be a non-empty string');
+    }
+    const { maxLength } = options;
+    if (maxLength !== undefined && maxLength <= 0) {
+        throw new Error('maxLength must be a positive number');
+    }
+    const resolvedMaxLength = maxLength ?? 100;
+    if (value.length > resolvedMaxLength) {
+        throw new Error(`String too long. Maximum length is ${resolvedMaxLength} characters`);
+    }
+    // months?|mo must appear before minutes?|mins?|m to avoid partial match ambiguity
+    const match = /^(-?(?:\d+)?\.?\d+) *(milliseconds?|msecs?|ms|seconds?|secs?|s|months?|mo|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)?$/i.exec(value.trim());
+    if (!match) {
+        throw new Error(`Invalid time format: "${value}"`);
+    }
+    const num = parseFloat(match[1]);
+    /* istanbul ignore next */
+    if (!isFinite(num)) {
+        throw new Error(`Invalid number: "${match[1]}"`);
+    }
+    const unit = (match[2] || 'ms').toLowerCase();
+    switch (unit) {
+        case 'years':
+        case 'year':
+        case 'yrs':
+        case 'yr':
+        case 'y':
+            return num * YEAR;
+        case 'weeks':
+        case 'week':
+        case 'w':
+            return num * WEEK;
+        case 'months':
+        case 'month':
+        case 'mo':
+            return num * MONTH;
+        case 'days':
+        case 'day':
+        case 'd':
+            return num * DAY;
+        case 'hours':
+        case 'hour':
+        case 'hrs':
+        case 'hr':
+        case 'h':
+            return num * HOUR;
+        case 'minutes':
+        case 'minute':
+        case 'mins':
+        case 'min':
+        case 'm':
+            return num * MINUTE;
+        case 'seconds':
+        case 'second':
+        case 'secs':
+        case 'sec':
+        case 's':
+            return num * SECOND;
+        case 'milliseconds':
+        case 'millisecond':
+        case 'msecs':
+        case 'msec':
+        case 'ms':
+            return num;
+        /* istanbul ignore next */
+        default:
+            throw new Error(`Unknown unit: "${unit}"`);
+    }
+}
+/**
+ * Parse a time string and return milliseconds, or `null` if the input is invalid.
+ * Useful when input is untrusted and exception handling would be verbose.
+ *
+ * @param value - Time string to parse
+ * @param options - Parsing options
+ * @returns Parsed time in milliseconds, or `null` on failure
+ *
+ * @example
+ * ```ts
+ * tryParse("2h");      // 7200000
+ * tryParse("invalid"); // null
+ * ```
+ */
+function tryParse(value, options) {
+    try {
+        return parse(value, options);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse a compound time string with multiple space-separated tokens.
+ *
+ * @param value - Compound time string (e.g., "1h 30m", "2d 4h 30m")
+ * @param options - Parsing options applied to each token
+ * @returns Total duration in milliseconds
+ * @throws {Error} When any token has an invalid format
+ *
+ * @example
+ * ```ts
+ * parseMultiple("1h 30m");    // 5400000
+ * parseMultiple("2d 4h 30m"); // 189000000
+ * ```
+ */
+function parseMultiple(value, options) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error('Value must be a non-empty string');
+    }
+    return value
+        .trim()
+        .split(/\s+/)
+        .reduce((acc, token) => acc + parse(token, options), 0);
+}
+
+/**
+ * Format milliseconds to a human-readable string.
+ *
+ * @param ms - Milliseconds to format
+ * @param options - Formatting options
+ * @returns Formatted string
+ * @throws {Error} When the input is not a finite number
+ *
+ * @example
+ * ```ts
+ * format(7200000);                              // "2h"
+ * format(7200000, { long: true });              // "2 hours"
+ * format(5400000, { verbose: true });           // "1h 30m"
+ * format(5400000, { verbose: true, long: true }); // "1 hour 30 minutes"
+ * ```
+ */
+function format(ms, options = {}) {
+    if (typeof ms !== 'number' || !isFinite(ms)) {
+        throw new Error('Value must be a finite number');
+    }
+    if (options.verbose) {
+        return formatVerbose(ms, options.long ?? false);
+    }
+    return options.long ? formatLong(ms) : formatShort(ms);
+}
+function formatShort(ms) {
+    const absMs = Math.abs(ms);
+    if (absMs >= YEAR)
+        return Math.round(ms / YEAR) + 'y';
+    if (absMs >= WEEK)
+        return Math.round(ms / WEEK) + 'w';
+    if (absMs >= DAY)
+        return Math.round(ms / DAY) + 'd';
+    if (absMs >= HOUR)
+        return Math.round(ms / HOUR) + 'h';
+    if (absMs >= MINUTE)
+        return Math.round(ms / MINUTE) + 'm';
+    if (absMs >= SECOND)
+        return Math.round(ms / SECOND) + 's';
+    return ms + 'ms';
+}
+function formatLong(ms) {
+    const absMs = Math.abs(ms);
+    if (absMs >= YEAR)
+        return plural(ms, absMs, YEAR, 'year');
+    if (absMs >= WEEK)
+        return plural(ms, absMs, WEEK, 'week');
+    if (absMs >= DAY)
+        return plural(ms, absMs, DAY, 'day');
+    if (absMs >= HOUR)
+        return plural(ms, absMs, HOUR, 'hour');
+    if (absMs >= MINUTE)
+        return plural(ms, absMs, MINUTE, 'minute');
+    if (absMs >= SECOND)
+        return plural(ms, absMs, SECOND, 'second');
+    return ms + ' ms';
+}
+/**
+ * Format milliseconds showing all non-zero components decomposed by unit.
+ * Handles negative values by prefixing the result with "-".
+ */
+function formatVerbose(ms, long) {
+    const negative = ms < 0;
+    let remaining = Math.abs(ms);
+    const parts = [];
+    const units = [
+        [YEAR, 'y', 'year'],
+        [WEEK, 'w', 'week'],
+        [DAY, 'd', 'day'],
+        [HOUR, 'h', 'hour'],
+        [MINUTE, 'm', 'minute'],
+        [SECOND, 's', 'second'],
+    ];
+    for (const [unit, short, name] of units) {
+        if (remaining >= unit) {
+            const count = Math.floor(remaining / unit);
+            remaining -= count * unit;
+            parts.push(long
+                ? `${count} ${count === 1 ? name : name + 's'}`
+                : `${count}${short}`);
+        }
+    }
+    if (remaining > 0 || parts.length === 0) {
+        parts.push(long ? `${remaining} ms` : `${remaining}ms`);
+    }
+    const result = parts.join(' ');
+    return negative ? `-${result}` : result;
+}
+function plural(ms, absMs, unit, name) {
+    const isPlural = absMs >= unit * 1.5;
+    return Math.round(ms / unit) + ' ' + name + (isPlural ? 's' : '');
+}
+
+function ms(value, options) {
+    if (typeof value === 'string') {
+        return parse(value, options);
+    }
+    if (typeof value === 'number') {
+        return format(value, options);
+    }
+    throw new Error('Value must be a string or number');
+}
+
+export { DAY, HOUR, MINUTE, MONTH, SECOND, WEEK, YEAR, ms as default, format, parse, parseMultiple, tryParse };
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/constants.ts","../src/parse.ts","../src/format.ts","../src/ms.ts"],"sourcesContent":[null,null,null,null],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,168 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Time constants in milliseconds
+ */
+const SECOND = 1000;
+const MINUTE = SECOND * 60;
+const HOUR = MINUTE * 60;
+const DAY = HOUR * 24;
+const WEEK = DAY * 7;
+const YEAR = DAY * 365.25;
+/**
+ * Parse a time string and return milliseconds
+ *
+ * @param value - Time string to parse (e.g., "2h", "30 minutes", "1d")
+ * @param options - Parsing options
+ * @returns Parsed time in milliseconds
+ * @throws {Error} When the string format is invalid
+ *
+ * @example
+ * ```ts
+ * parse("2h"); // 7200000
+ * parse("30 minutes"); // 1800000
+ * parse("1d"); // 86400000
+ * ```
+ */
+function parse(value, options = {}) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error('Value must be a non-empty string');
+    }
+    const maxLength = options.maxLength ?? 100;
+    if (value.length > maxLength) {
+        throw new Error(`String too long. Maximum length is ${maxLength} characters`);
+    }
+    const match = /^(-?(?:\d+)?\.?\d+) *(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)?$/i.exec(value.trim());
+    if (!match) {
+        throw new Error(`Invalid time format: "${value}"`);
+    }
+    const num = parseFloat(match[1]);
+    if (!isFinite(num)) {
+        throw new Error(`Invalid number: "${match[1]}"`);
+    }
+    const unit = (match[2] || 'ms').toLowerCase();
+    switch (unit) {
+        case 'years':
+        case 'year':
+        case 'yrs':
+        case 'yr':
+        case 'y':
+            return num * YEAR;
+        case 'weeks':
+        case 'week':
+        case 'w':
+            return num * WEEK;
+        case 'days':
+        case 'day':
+        case 'd':
+            return num * DAY;
+        case 'hours':
+        case 'hour':
+        case 'hrs':
+        case 'hr':
+        case 'h':
+            return num * HOUR;
+        case 'minutes':
+        case 'minute':
+        case 'mins':
+        case 'min':
+        case 'm':
+            return num * MINUTE;
+        case 'seconds':
+        case 'second':
+        case 'secs':
+        case 'sec':
+        case 's':
+            return num * SECOND;
+        case 'milliseconds':
+        case 'millisecond':
+        case 'msecs':
+        case 'msec':
+        case 'ms':
+            return num;
+        default:
+            throw new Error(`Unknown unit: "${unit}"`);
+    }
+}
+/**
+ * Format milliseconds to a human-readable string
+ *
+ * @param ms - Milliseconds to format
+ * @param options - Formatting options
+ * @returns Formatted string
+ * @throws {Error} When the input is not a finite number
+ *
+ * @example
+ * ```ts
+ * format(7200000); // "2h"
+ * format(7200000, { long: true }); // "2 hours"
+ * format(1800000); // "30m"
+ * ```
+ */
+function format(ms, options = {}) {
+    if (typeof ms !== 'number' || !isFinite(ms)) {
+        throw new Error('Value must be a finite number');
+    }
+    return options.long ? formatLong(ms) : formatShort(ms);
+}
+/**
+ * Format milliseconds in short format (e.g., "2h", "30m")
+ */
+function formatShort(ms) {
+    const absMs = Math.abs(ms);
+    if (absMs >= DAY) {
+        return Math.round(ms / DAY) + 'd';
+    }
+    if (absMs >= HOUR) {
+        return Math.round(ms / HOUR) + 'h';
+    }
+    if (absMs >= MINUTE) {
+        return Math.round(ms / MINUTE) + 'm';
+    }
+    if (absMs >= SECOND) {
+        return Math.round(ms / SECOND) + 's';
+    }
+    return ms + 'ms';
+}
+/**
+ * Format milliseconds in long format (e.g., "2 hours", "30 minutes")
+ */
+function formatLong(ms) {
+    const absMs = Math.abs(ms);
+    if (absMs >= DAY) {
+        return plural(ms, absMs, DAY, 'day');
+    }
+    if (absMs >= HOUR) {
+        return plural(ms, absMs, HOUR, 'hour');
+    }
+    if (absMs >= MINUTE) {
+        return plural(ms, absMs, MINUTE, 'minute');
+    }
+    if (absMs >= SECOND) {
+        return plural(ms, absMs, SECOND, 'second');
+    }
+    return ms + ' ms';
+}
+/**
+ * Helper function for pluralization
+ */
+function plural(ms, absMs, unit, name) {
+    const isPlural = absMs >= unit * 1.5;
+    return Math.round(ms / unit) + ' ' + name + (isPlural ? 's' : '');
+}
+function ms(value, options) {
+    if (typeof value === 'string') {
+        return parse(value, options);
+    }
+    if (typeof value === 'number') {
+        return format(value, options);
+    }
+    throw new Error('Value must be a string or number');
+}
+
+exports.default = ms;
+exports.format = format;
+exports.parse = parse;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/ms.d.ts

@@ -0,0 +1,19 @@
+import type { StringValue, FormatOptions } from './types';
+/**
+ * Main function that can either parse a string or format a number.
+ *
+ * @param value - String to parse or number to format
+ * @param options - Options for parsing or formatting
+ * @returns Parsed milliseconds or formatted string
+ *
+ * @example
+ * ```ts
+ * ms("2h");                    // 7200000
+ * ms(7200000);                 // "2h"
+ * ms(7200000, { long: true }); // "2 hours"
+ * ```
+ */
+declare function ms(value: StringValue): number;
+declare function ms(value: number, options?: FormatOptions): string;
+export default ms;
+//# sourceMappingURL=ms.d.ts.map

package/dist/ms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ms.d.ts","sourceRoot":"","sources":["../src/ms.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAgB,MAAM,SAAS,CAAC;AAExE;;;;;;;;;;;;;GAaG;AACH,iBAAS,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAAC;AACxC,iBAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;AAgB5D,eAAe,EAAE,CAAC"}

package/dist/parse.d.ts

@@ -0,0 +1,49 @@
+import type { ParseOptions } from './types';
+/**
+ * Parse a time string and return milliseconds.
+ *
+ * @param value - Time string to parse (e.g., "2h", "30 minutes", "1d", "1mo")
+ * @param options - Parsing options
+ * @returns Parsed time in milliseconds
+ * @throws {Error} When the string format is invalid
+ *
+ * @example
+ * ```ts
+ * parse("2h");        // 7200000
+ * parse("30 minutes"); // 1800000
+ * parse("1d");        // 86400000
+ * parse("1mo");       // 2592000000
+ * ```
+ */
+export declare function parse(value: string, options?: ParseOptions): number;
+/**
+ * Parse a time string and return milliseconds, or `null` if the input is invalid.
+ * Useful when input is untrusted and exception handling would be verbose.
+ *
+ * @param value - Time string to parse
+ * @param options - Parsing options
+ * @returns Parsed time in milliseconds, or `null` on failure
+ *
+ * @example
+ * ```ts
+ * tryParse("2h");      // 7200000
+ * tryParse("invalid"); // null
+ * ```
+ */
+export declare function tryParse(value: string, options?: ParseOptions): number | null;
+/**
+ * Parse a compound time string with multiple space-separated tokens.
+ *
+ * @param value - Compound time string (e.g., "1h 30m", "2d 4h 30m")
+ * @param options - Parsing options applied to each token
+ * @returns Total duration in milliseconds
+ * @throws {Error} When any token has an invalid format
+ *
+ * @example
+ * ```ts
+ * parseMultiple("1h 30m");    // 5400000
+ * parseMultiple("2d 4h 30m"); // 189000000
+ * ```
+ */
+export declare function parseMultiple(value: string, options?: ParseOptions): number;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAkFvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAM7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM,CAS3E"}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Time units supported by the parser
+ */
+export type Unit = 'Years' | 'Year' | 'Yrs' | 'Yr' | 'Y' | 'Weeks' | 'Week' | 'W' | 'Months' | 'Month' | 'Mo' | 'Days' | 'Day' | 'D' | 'Hours' | 'Hour' | 'Hrs' | 'Hr' | 'H' | 'Minutes' | 'Minute' | 'Mins' | 'Min' | 'M' | 'Seconds' | 'Second' | 'Secs' | 'Sec' | 's' | 'Milliseconds' | 'Millisecond' | 'Msecs' | 'Msec' | 'Ms';
+export type UnitAnyCase = Unit | Uppercase<Unit> | Lowercase<Unit>;
+export type StringValue = `${number}` | `${number}${UnitAnyCase}` | `${number} ${UnitAnyCase}`;
+/**
+ * Configuration options for formatting
+ */
+export interface FormatOptions {
+    /**
+     * Use long format (e.g., "1 day" instead of "1d")
+     * @default false
+     */
+    long?: boolean;
+    /**
+     * Use verbose format, showing all non-zero components (e.g., "1h 30m" instead of "2h")
+     * @default false
+     */
+    verbose?: boolean;
+}
+/**
+ * Configuration options for parsing
+ */
+export interface ParseOptions {
+    /**
+     * Maximum string length to parse. Must be a positive number.
+     * @default 100
+     */
+    maxLength?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,IAAI,GACZ,OAAO,GACP,MAAM,GACN,KAAK,GACL,IAAI,GACJ,GAAG,GACH,OAAO,GACP,MAAM,GACN,GAAG,GACH,QAAQ,GACR,OAAO,GACP,IAAI,GACJ,MAAM,GACN,KAAK,GACL,GAAG,GACH,OAAO,GACP,MAAM,GACN,KAAK,GACL,IAAI,GACJ,GAAG,GACH,SAAS,GACT,QAAQ,GACR,MAAM,GACN,KAAK,GACL,GAAG,GACH,SAAS,GACT,QAAQ,GACR,MAAM,GACN,KAAK,GACL,GAAG,GACH,cAAc,GACd,aAAa,GACb,OAAO,GACP,MAAM,GACN,IAAI,CAAC;AAET,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAEnE,MAAM,MAAM,WAAW,GACnB,GAAG,MAAM,EAAE,GACX,GAAG,MAAM,GAAG,WAAW,EAAE,GACzB,GAAG,MAAM,IAAI,WAAW,EAAE,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "chrono-ms",
+  "version": "1.2.0",
+  "type": "module",
+  "description": "A lightweight, TypeScript-first library for parsing and formatting time durations",
+  "main": "dist/index.cjs",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "time",
+    "duration",
+    "parser",
+    "formatter",
+    "chrono",
+    "ms",
+    "milliseconds",
+    "typescript"
+  ],
+  "author": "Francisco Luis Rios Vega <alckordev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iscodex/chrono-ms.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iscodex/chrono-ms/issues"
+  },
+  "homepage": "https://github.com/iscodex/chrono-ms#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/jest": "^30.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.44.0",
+    "@typescript-eslint/parser": "^8.44.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "globals": "^16.4.0",
+    "jest": "^30.1.3",
+    "np": "^10.2.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.50.2",
+    "ts-jest": "^29.4.3",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "test": "jest --verbose",
+    "test:watch": "jest --watch --verbose",
+    "test:coverage": "jest --coverage --verbose",
+    "test:debug": "jest --detectOpenHandles --forceExit --verbose",
+    "lint": "eslint src/**/*.{js,ts}",
+    "lint:fix": "eslint src/**/*.{js,ts} --fix",
+    "type-check": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "release": "np"
+  }
+}