@prexjs/ms 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prexjs (https://prexjs.com)
+
+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

@@ -1,3 +1,342 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @prexjs/ms
+
+**A lightweight TypeScript utility for converting time durations to milliseconds and formatting milliseconds into human-readable strings.**
+
+[![npm version](https://img.shields.io/npm/v/@prexjs/ms)](https://www.npmjs.com/package/@prexjs/ms)
+[![npm downloads](https://img.shields.io/npm/dm/@prexjs/ms)](https://www.npmjs.com/package/@prexjs/ms)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-supported-blue)](https://www.typescriptlang.org/)
+
+`@prexjs/ms` converts human-readable time strings such as `2 days`, `10h`, and `5s` into milliseconds. It can also format millisecond values into compact or human-readable duration strings.
+
+## Features
+
+- Convert time strings into milliseconds.
+- Convert milliseconds into short or long duration strings.
+- Support positive, negative, and fractional durations.
+- Support years, months, weeks, days, hours, minutes, seconds, and milliseconds.
+- Accept common unit aliases and case variations.
+- Provide TypeScript definitions and template literal types.
+- Export separate `parse`, `parseStrict`, and `format` helpers.
+- Work without runtime dependencies.
+- Suitable for browser and JavaScript runtime environments when built for those targets.
+
+## Installation
+
+Install using your preferred package manager.
+
+```bash
+# npm
+npm install @prexjs/ms
+
+# pnpm
+pnpm add @prexjs/ms
+
+# Yarn
+yarn add @prexjs/ms
+
+# Bun
+bun add @prexjs/ms
+```
+
+## Quick start
+
+```ts
+import ms from '@prexjs/ms';
+
+ms('2 days');  // 172800000
+ms('10h');     // 36000000
+ms('2h');      // 7200000
+ms('1m');      // 60000
+ms('5s');      // 5000
+
+ms(60000);     // '1m'
+ms(7200000);   // '2h'
+
+ms(60000, { long: true }); // '1 minute'
+ms(7200000, { long: true }); // '2 hours'
+```
+
+Named imports are also supported:
+
+```ts
+import { ms, parse, format, parseStrict } from '@prexjs/ms';
+
+parse('1h');                 // 3600000
+format(60000);               // '1m'
+parseStrict('5s');           // 5000
+ms(60000, { long: true });   // '1 minute'
+```
+
+## Examples
+
+### Convert time strings to milliseconds
+
+```ts
+import ms from '@prexjs/ms';
+
+ms('2 days');  // 172800000
+ms('1d');      // 86400000
+ms('10h');     // 36000000
+ms('2.5 hrs'); // 9000000
+ms('2h');      // 7200000
+ms('1m');      // 60000
+ms('5s');      // 5000
+ms('1y');      // 31557600000
+
+// A unit is optional; the default is milliseconds.
+ms('100');     // 100
+
+// Negative durations
+ms('-3 days'); // -259200000
+ms('-1h');     // -3600000
+ms('-200');    // -200
+
+// Fractional durations
+ms('0.5m');    // 30000
+ms('-0.5m');   // -30000
+ms('.5m');     // 30000
+ms('-.5m');    // -30000
+```
+
+### Convert milliseconds to a short string
+
+```ts
+import ms from '@prexjs/ms';
+
+ms(1000);       // '1s'
+ms(60000);      // '1m'
+ms(2 * 60000);  // '2m'
+ms(-3 * 60000); // '-3m'
+ms(3600000);    // '1h'
+ms(86400000);   // '1d'
+```
+
+The formatter selects the largest applicable unit and rounds to the nearest whole unit. Values smaller than one second are represented in milliseconds.
+
+### Use long formatting
+
+```ts
+import ms from '@prexjs/ms';
+
+ms(60000, { long: true });       // '1 minute'
+ms(2 * 60000, { long: true });   // '2 minutes'
+ms(-3 * 60000, { long: true });  // '-3 minutes'
+
+ms(ms('10 hours'), { long: true }); // '10 hours'
+ms(1000, { long: true });           // '1 second'
+ms(2000, { long: true });           // '2 seconds'
+```
+
+### Use the helper functions
+
+```ts
+import { parse, parseStrict, format } from '@prexjs/ms';
+
+// Parse a string into milliseconds.
+parse('1h'); // 3600000
+
+// Format milliseconds.
+format(2000); // '2s'
+
+// Long formatting.
+format(60000, { long: true }); // '1 minute'
+
+// Type-safe parsing.
+parseStrict('1h'); // 3600000
+```
+
+## Supported units
+
+| Unit | Supported aliases |
+|---|---|
+| Years | `years`, `year`, `yrs`, `yr`, `y` |
+| Months | `months`, `month`, `mo` |
+| Weeks | `weeks`, `week`, `w` |
+| 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` |
+
+### Spacing and capitalization
+
+Unit matching is case-insensitive.
+
+```ts
+ms('2 minutes'); // 120000
+ms('2minutes');  // 120000
+ms('2 MINUTES'); // 120000
+ms('2 Minutes'); // 120000
+ms('2 H');       // 7200000
+```
+
+If no unit is specified, the value defaults to milliseconds.
+
+### Duration constants
+
+The implementation uses these duration definitions:
+
+- 1 second = 1,000 milliseconds
+- 1 minute = 60 seconds
+- 1 hour = 60 minutes
+- 1 day = 24 hours
+- 1 week = 7 days
+- 1 year = 365.25 days
+- 1 month = one-twelfth of a year
+
+Months and years are fixed-duration approximations, not calendar-aware date calculations.
+
+## TypeScript support
+
+The package includes TypeScript declarations and a `StringValue` template literal type.
+
+```ts
+import { ms, type StringValue } from '@prexjs/ms';
+
+function convertDuration(value: StringValue): number {
+  return ms(value);
+}
+
+convertDuration('1 h');         // 3600000
+convertDuration('5.2 days');    // 449280000
+convertDuration('500');         // 500
+```
+
+### Custom duration types
+
+You can restrict accepted duration strings using your own template literal types.
+
+```ts
+import { ms } from '@prexjs/ms';
+
+type DaysOrWeeks = `${number} ${'days' | 'weeks'}`;
+
+function convertLongDuration(value: DaysOrWeeks): number {
+  return ms(value);
+}
+
+convertLongDuration('5.2 days');  // 449280000
+convertLongDuration('2 weeks');   // 1209600000
+```
+
+### Dynamic strings
+
+When a value comes from a runtime source, TypeScript cannot automatically guarantee that it matches `StringValue`.
+
+Validate untrusted input at runtime before passing it to the parser. Avoid using type assertions as a substitute for validation.
+
+```ts
+import { parse } from '@prexjs/ms';
+
+const input: string = "5 minutesx";
+const result = parse(input);
+
+if (Number.isNaN(result)) {
+  console.error("Invalid duration"); // Invalid duration
+} else {
+  console.log(result);               // 300000
+}
+```
+
+## API reference
+
+### `ms(value, options?)`
+
+The main overloaded conversion function.
+
+**String input:** returns the duration in milliseconds.
+
+```ts
+ms('5s'); // 5000
+```
+
+**Number input:** returns a formatted duration string.
+
+```ts
+ms(5000); // '5s'
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `long` | `boolean` | `false` | Use verbose formatting when `true` |
+
+### `parse(value)`
+
+Parses a string and returns its duration in milliseconds.
+
+```ts
+parse('1h');      // 3600000
+parse('invalid'); // NaN
+```
+
+The parser throws for empty strings, non-string values, and strings longer than its configured limit. Unrecognized duration syntax returns `NaN`.
+
+### `parseStrict(value)`
+
+Parses a `StringValue` input with compile-time type checking.
+
+```ts
+parseStrict('1h'); // 3600000
+```
+
+The function provides type safety at compile time. It does not replace runtime validation for untrusted input.
+
+### `format(value, options?)`
+
+Formats a finite number of milliseconds as a short or long duration string.
+
+```ts
+format(2000);                // '2s'
+format(60000, { long: true }); // '1 minute'
+```
+
+Non-finite numeric inputs such as `NaN` and `Infinity` cause an error.
+
+
+## Error handling
+
+For values received from users, environment variables, API requests, or configuration files, validate the result before using it.
+
+```ts
+import { parse } from '@prexjs/ms';
+
+function parseDuration(input: string): number | undefined {
+  try {
+    const duration = parse(input);
+
+    if (!Number.isFinite(duration)) {
+      return undefined;
+    }
+
+    return duration;
+  } catch {
+    return undefined;
+  }
+}
+
+const timeout = parseDuration("30s");    // 30000
+
+if (timeout !== undefined) {
+  console.log(`Timeout: ${timeout}ms`);    // Timeout: 30000ms
+}
+```
+
+## Compatibility
+
+`@prexjs/ms` is designed for JavaScript and TypeScript projects. Browser, Node.js, Deno, Bun, and edge-runtime compatibility depends on the package's published build formats and the target runtime's supported JavaScript features.
+
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.
+
+## Related projects
+
+- [prex.js](https://github.com/prexjs/prex.js) — prex.js monorepo and ecosystem.
+
+---
+
+**Note:** This package documents duration conversion, not calendar arithmetic or timezone-aware date calculations.

package/lib/index.cjs

@@ -0,0 +1,186 @@
+/*!
+ * @prexjs/ms
+ * Copyright(c) 2026 Sorabh <sorabh@backady.com>
+ * MIT Licensed
+ */
+
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const s = 1000;
+const m = s * 60;
+const h = m * 60;
+const d = h * 24;
+const w = d * 7;
+const y = d * 365.25;
+const mo = y / 12;
+function ms(value, options) {
+    if (typeof value === "string") {
+        return parse(value);
+    }
+    else if (typeof value === "number") {
+        return format(value, options);
+    }
+    throw new Error(`Value provided to ms() must be a string or number. value=${JSON.stringify(value)}`);
+}
+/**
+ * Parse the given string and return milliseconds.
+ *
+ * @param str - A string to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+function parse(str) {
+    if (typeof str !== "string" || str.length === 0 || str.length > 100) {
+        throw new Error(`Value provided to ms.parse() must be a string with length between 1 and 99. value=${JSON.stringify(str)}`);
+    }
+    const match = /^(?<value>-?\d*\.?\d+) *(?<unit>milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|months?|mo|years?|yrs?|y)?$/i.exec(str);
+    if (!match?.groups) {
+        return NaN;
+    }
+    // Named capture groups need to be manually typed today.
+    // https://github.com/microsoft/TypeScript/issues/32098
+    const { value, unit = "ms" } = match.groups;
+    const n = parseFloat(value);
+    const matchUnit = unit.toLowerCase();
+    /* istanbul ignore next - istanbul doesn't understand, but thankfully the TypeScript the exhaustiveness check in the default case keeps us type safe here */
+    switch (matchUnit) {
+        case "years":
+        case "year":
+        case "yrs":
+        case "yr":
+        case "y":
+            return n * y;
+        case "months":
+        case "month":
+        case "mo":
+            return n * mo;
+        case "weeks":
+        case "week":
+        case "w":
+            return n * w;
+        case "days":
+        case "day":
+        case "d":
+            return n * d;
+        case "hours":
+        case "hour":
+        case "hrs":
+        case "hr":
+        case "h":
+            return n * h;
+        case "minutes":
+        case "minute":
+        case "mins":
+        case "min":
+        case "m":
+            return n * m;
+        case "seconds":
+        case "second":
+        case "secs":
+        case "sec":
+        case "s":
+            return n * s;
+        case "milliseconds":
+        case "millisecond":
+        case "msecs":
+        case "msec":
+        case "ms":
+            return n;
+        default:
+            throw new Error(`Unknown unit "${matchUnit}" provided to ms.parse(). value=${JSON.stringify(str)}`);
+    }
+}
+/**
+ * Parse the given StringValue and return milliseconds.
+ *
+ * @param value - A typesafe StringValue to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+function parseStrict(value) {
+    return parse(value);
+}
+/**
+ * Short format for `ms`.
+ */
+function fmtShort(ms) {
+    const msAbs = Math.abs(ms);
+    if (msAbs >= y) {
+        return `${Math.round(ms / y)}y`;
+    }
+    if (msAbs >= mo) {
+        return `${Math.round(ms / mo)}mo`;
+    }
+    if (msAbs >= w) {
+        return `${Math.round(ms / w)}w`;
+    }
+    if (msAbs >= d) {
+        return `${Math.round(ms / d)}d`;
+    }
+    if (msAbs >= h) {
+        return `${Math.round(ms / h)}h`;
+    }
+    if (msAbs >= m) {
+        return `${Math.round(ms / m)}m`;
+    }
+    if (msAbs >= s) {
+        return `${Math.round(ms / s)}s`;
+    }
+    return `${ms}ms`;
+}
+/**
+ * Long format for `ms`.
+ */
+function fmtLong(ms) {
+    const msAbs = Math.abs(ms);
+    if (msAbs >= y) {
+        return plural(ms, msAbs, y, "year");
+    }
+    if (msAbs >= mo) {
+        return plural(ms, msAbs, mo, "month");
+    }
+    if (msAbs >= w) {
+        return plural(ms, msAbs, w, "week");
+    }
+    if (msAbs >= d) {
+        return plural(ms, msAbs, d, "day");
+    }
+    if (msAbs >= h) {
+        return plural(ms, msAbs, h, "hour");
+    }
+    if (msAbs >= m) {
+        return plural(ms, msAbs, m, "minute");
+    }
+    if (msAbs >= s) {
+        return plural(ms, msAbs, s, "second");
+    }
+    return `${ms} ms`;
+}
+/**
+ * Format the given integer as a string.
+ *
+ * @param ms - milliseconds
+ * @param options - Options for the conversion
+ * @returns The formatted string
+ */
+function format(ms, options) {
+    if (typeof ms !== "number" || !Number.isFinite(ms)) {
+        throw new Error("Value provided to ms.format() must be of type number.");
+    }
+    return options?.long ? fmtLong(ms) : fmtShort(ms);
+}
+/**
+ * Pluralization helper.
+ */
+function plural(ms, msAbs, n, name) {
+    const isPlural = msAbs >= n * 1.5;
+    return `${Math.round(ms / n)} ${name}${isPlural ? "s" : ""}`;
+}
+
+exports.default = ms;
+exports.format = format;
+exports.ms = ms;
+exports.parse = parse;
+exports.parseStrict = parseStrict;

package/lib/index.d.cts

@@ -0,0 +1,53 @@
+type Years = "years" | "year" | "yrs" | "yr" | "y";
+type Months = "months" | "month" | "mo";
+type Weeks = "weeks" | "week" | "w";
+type Days = "days" | "day" | "d";
+type Hours = "hours" | "hour" | "hrs" | "hr" | "h";
+type Minutes = "minutes" | "minute" | "mins" | "min" | "m";
+type Seconds = "seconds" | "second" | "secs" | "sec" | "s";
+type Milliseconds = "milliseconds" | "millisecond" | "msecs" | "msec" | "ms";
+type Unit = Years | Months | Weeks | Days | Hours | Minutes | Seconds | Milliseconds;
+type UnitAnyCase = Capitalize<Unit> | Uppercase<Unit> | Unit;
+type StringValue = `${number}` | `${number}${UnitAnyCase}` | `${number} ${UnitAnyCase}`;
+interface Options {
+    /**
+     * Set to `true` to use verbose formatting. Defaults to `false`.
+     */
+    long?: boolean;
+}
+/**
+ * Parse or format the given value.
+ *
+ * @param value - The string or number to convert
+ * @param options - Options for the conversion
+ * @throws Error if `value` is not a non-empty string or a number
+ */
+declare function ms(value: StringValue, options?: Options): number;
+declare function ms(value: number, options?: Options): string;
+/**
+ * Parse the given string and return milliseconds.
+ *
+ * @param str - A string to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+declare function parse(str: string): number;
+/**
+ * Parse the given StringValue and return milliseconds.
+ *
+ * @param value - A typesafe StringValue to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+declare function parseStrict(value: StringValue): number;
+/**
+ * Format the given integer as a string.
+ *
+ * @param ms - milliseconds
+ * @param options - Options for the conversion
+ * @returns The formatted string
+ */
+declare function format(ms: number, options?: Options): string;
+
+export { ms as default, format, ms, parse, parseStrict };
+export type { StringValue };

package/lib/index.d.mts

@@ -0,0 +1,53 @@
+type Years = "years" | "year" | "yrs" | "yr" | "y";
+type Months = "months" | "month" | "mo";
+type Weeks = "weeks" | "week" | "w";
+type Days = "days" | "day" | "d";
+type Hours = "hours" | "hour" | "hrs" | "hr" | "h";
+type Minutes = "minutes" | "minute" | "mins" | "min" | "m";
+type Seconds = "seconds" | "second" | "secs" | "sec" | "s";
+type Milliseconds = "milliseconds" | "millisecond" | "msecs" | "msec" | "ms";
+type Unit = Years | Months | Weeks | Days | Hours | Minutes | Seconds | Milliseconds;
+type UnitAnyCase = Capitalize<Unit> | Uppercase<Unit> | Unit;
+type StringValue = `${number}` | `${number}${UnitAnyCase}` | `${number} ${UnitAnyCase}`;
+interface Options {
+    /**
+     * Set to `true` to use verbose formatting. Defaults to `false`.
+     */
+    long?: boolean;
+}
+/**
+ * Parse or format the given value.
+ *
+ * @param value - The string or number to convert
+ * @param options - Options for the conversion
+ * @throws Error if `value` is not a non-empty string or a number
+ */
+declare function ms(value: StringValue, options?: Options): number;
+declare function ms(value: number, options?: Options): string;
+/**
+ * Parse the given string and return milliseconds.
+ *
+ * @param str - A string to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+declare function parse(str: string): number;
+/**
+ * Parse the given StringValue and return milliseconds.
+ *
+ * @param value - A typesafe StringValue to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+declare function parseStrict(value: StringValue): number;
+/**
+ * Format the given integer as a string.
+ *
+ * @param ms - milliseconds
+ * @param options - Options for the conversion
+ * @returns The formatted string
+ */
+declare function format(ms: number, options?: Options): string;
+
+export { ms as default, format, ms, parse, parseStrict };
+export type { StringValue };

package/lib/index.mjs

@@ -0,0 +1,178 @@
+/*!
+ * @prexjs/ms
+ * Copyright(c) 2026 Sorabh <sorabh@backady.com>
+ * MIT Licensed
+ */
+
+const s = 1000;
+const m = s * 60;
+const h = m * 60;
+const d = h * 24;
+const w = d * 7;
+const y = d * 365.25;
+const mo = y / 12;
+function ms(value, options) {
+    if (typeof value === "string") {
+        return parse(value);
+    }
+    else if (typeof value === "number") {
+        return format(value, options);
+    }
+    throw new Error(`Value provided to ms() must be a string or number. value=${JSON.stringify(value)}`);
+}
+/**
+ * Parse the given string and return milliseconds.
+ *
+ * @param str - A string to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+function parse(str) {
+    if (typeof str !== "string" || str.length === 0 || str.length > 100) {
+        throw new Error(`Value provided to ms.parse() must be a string with length between 1 and 99. value=${JSON.stringify(str)}`);
+    }
+    const match = /^(?<value>-?\d*\.?\d+) *(?<unit>milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|months?|mo|years?|yrs?|y)?$/i.exec(str);
+    if (!match?.groups) {
+        return NaN;
+    }
+    // Named capture groups need to be manually typed today.
+    // https://github.com/microsoft/TypeScript/issues/32098
+    const { value, unit = "ms" } = match.groups;
+    const n = parseFloat(value);
+    const matchUnit = unit.toLowerCase();
+    /* istanbul ignore next - istanbul doesn't understand, but thankfully the TypeScript the exhaustiveness check in the default case keeps us type safe here */
+    switch (matchUnit) {
+        case "years":
+        case "year":
+        case "yrs":
+        case "yr":
+        case "y":
+            return n * y;
+        case "months":
+        case "month":
+        case "mo":
+            return n * mo;
+        case "weeks":
+        case "week":
+        case "w":
+            return n * w;
+        case "days":
+        case "day":
+        case "d":
+            return n * d;
+        case "hours":
+        case "hour":
+        case "hrs":
+        case "hr":
+        case "h":
+            return n * h;
+        case "minutes":
+        case "minute":
+        case "mins":
+        case "min":
+        case "m":
+            return n * m;
+        case "seconds":
+        case "second":
+        case "secs":
+        case "sec":
+        case "s":
+            return n * s;
+        case "milliseconds":
+        case "millisecond":
+        case "msecs":
+        case "msec":
+        case "ms":
+            return n;
+        default:
+            throw new Error(`Unknown unit "${matchUnit}" provided to ms.parse(). value=${JSON.stringify(str)}`);
+    }
+}
+/**
+ * Parse the given StringValue and return milliseconds.
+ *
+ * @param value - A typesafe StringValue to parse to milliseconds
+ * @returns The parsed value in milliseconds, or `NaN` if the string can't be
+ * parsed
+ */
+function parseStrict(value) {
+    return parse(value);
+}
+/**
+ * Short format for `ms`.
+ */
+function fmtShort(ms) {
+    const msAbs = Math.abs(ms);
+    if (msAbs >= y) {
+        return `${Math.round(ms / y)}y`;
+    }
+    if (msAbs >= mo) {
+        return `${Math.round(ms / mo)}mo`;
+    }
+    if (msAbs >= w) {
+        return `${Math.round(ms / w)}w`;
+    }
+    if (msAbs >= d) {
+        return `${Math.round(ms / d)}d`;
+    }
+    if (msAbs >= h) {
+        return `${Math.round(ms / h)}h`;
+    }
+    if (msAbs >= m) {
+        return `${Math.round(ms / m)}m`;
+    }
+    if (msAbs >= s) {
+        return `${Math.round(ms / s)}s`;
+    }
+    return `${ms}ms`;
+}
+/**
+ * Long format for `ms`.
+ */
+function fmtLong(ms) {
+    const msAbs = Math.abs(ms);
+    if (msAbs >= y) {
+        return plural(ms, msAbs, y, "year");
+    }
+    if (msAbs >= mo) {
+        return plural(ms, msAbs, mo, "month");
+    }
+    if (msAbs >= w) {
+        return plural(ms, msAbs, w, "week");
+    }
+    if (msAbs >= d) {
+        return plural(ms, msAbs, d, "day");
+    }
+    if (msAbs >= h) {
+        return plural(ms, msAbs, h, "hour");
+    }
+    if (msAbs >= m) {
+        return plural(ms, msAbs, m, "minute");
+    }
+    if (msAbs >= s) {
+        return plural(ms, msAbs, s, "second");
+    }
+    return `${ms} ms`;
+}
+/**
+ * Format the given integer as a string.
+ *
+ * @param ms - milliseconds
+ * @param options - Options for the conversion
+ * @returns The formatted string
+ */
+function format(ms, options) {
+    if (typeof ms !== "number" || !Number.isFinite(ms)) {
+        throw new Error("Value provided to ms.format() must be of type number.");
+    }
+    return options?.long ? fmtLong(ms) : fmtShort(ms);
+}
+/**
+ * Pluralization helper.
+ */
+function plural(ms, msAbs, n, name) {
+    const isPlural = msAbs >= n * 1.5;
+    return `${Math.round(ms / n)} ${name}${isPlural ? "s" : ""}`;
+}
+
+export { ms as default, format, ms, parse, parseStrict };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@prexjs/ms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Lightweight TypeScript utility for converting time durations to milliseconds and formatting milliseconds to human-readable strings.",
+  "author": "Sorabh <sorabh@prexjs.com> (https://prexjs.com)",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.mjs",
+  "types": "./lib/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prexjs/prex.js.git",
+    "directory": "packages/ms"
+  },
+  "homepage": "https://github.com/prexjs/prex.js/tree/main/packages/ms#readme",
+  "bugs": {
+    "url": "https://github.com/prexjs/prex.js/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ms",
+    "milliseconds",
+    "duration",
+    "time",
+    "parse",
+    "format",
+    "units",
+    "convert",
+    "timestamp",
+    "typescript"
+  ]
+}