@vaibhavt07/pace-utils 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vaibhav Tyagi
+
+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,34 @@
+# @vaibhavt07/pace-utils
+
+Tiny utilities for formatting running pace and duration. Zero dependencies. ESM + CJS + TypeScript types.
+
+## Install
+
+```bash
+npm install @vaibhavt07/pace-utils
+```
+
+## Usage
+
+```ts
+import { formatPace, formatDuration } from '@vaibhavt07/pace-utils'
+
+formatPace(330)        // "5:30 /km"
+formatDuration(5025)   // "1h 23m 45s"
+formatDuration(125)    // "2m 5s"
+formatDuration(30)     // "30s"
+```
+
+## API
+
+### `formatPace(secondsPerKm: number): string`
+
+Formats a pace value (seconds per kilometer) as a runner-friendly string. Throws `RangeError` on negative or non-finite input.
+
+### `formatDuration(seconds: number): string`
+
+Formats a duration (in seconds) as a human-readable string. Omits leading zero units. Throws `RangeError` on negative or non-finite input.
+
+## License
+
+MIT © [Vaibhav Tyagi](https://vaibhavt07.com)

package/dist/index.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Format a pace value (seconds per kilometer) as a runner-friendly string.
+ *
+ * @param secondsPerKm - Pace in seconds per kilometer. Must be a non-negative finite number.
+ * @returns Formatted string like `"5:30 /km"`.
+ *
+ * @example
+ * formatPace(330) // "5:30 /km"
+ * formatPace(285) // "4:45 /km"
+ */
+function formatPace(secondsPerKm) {
+    if (!Number.isFinite(secondsPerKm) || secondsPerKm < 0) {
+        throw new RangeError(`secondsPerKm must be a non-negative finite number, received: ${secondsPerKm}`);
+    }
+    const total = Math.round(secondsPerKm);
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
+    return `${minutes}:${seconds.toString().padStart(2, '0')} /km`;
+}
+/**
+ * Format a duration (in seconds) as a human-readable string.
+ *
+ * Always emits the largest non-zero unit and everything below it down to seconds.
+ *
+ * @param seconds - Duration in seconds. Must be a non-negative finite number.
+ * @returns Formatted string like `"1h 23m 45s"`, `"2m 5s"`, or `"30s"`.
+ *
+ * @example
+ * formatDuration(5025) // "1h 23m 45s"
+ * formatDuration(125)  // "2m 5s"
+ * formatDuration(30)   // "30s"
+ */
+function formatDuration(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new RangeError(`seconds must be a non-negative finite number, received: ${seconds}`);
+    }
+    const total = Math.round(seconds);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h > 0)
+        return `${h}h ${m}m ${s}s`;
+    if (m > 0)
+        return `${m}m ${s}s`;
+    return `${s}s`;
+}
+
+exports.formatDuration = formatDuration;
+exports.formatPace = formatPace;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;AASG;AACG,SAAU,UAAU,CAAC,YAAoB,EAAA;AAC7C,IAAA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE;AACtD,QAAA,MAAM,IAAI,UAAU,CAClB,gEAAgE,YAAY,CAAA,CAAE,CAC/E;IACH;IAEA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;AACtC,IAAA,MAAM,OAAO,GAAG,KAAK,GAAG,EAAE;AAE1B,IAAA,OAAO,CAAA,EAAG,OAAO,CAAA,CAAA,EAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM;AAChE;AAEA;;;;;;;;;;;;AAYG;AACG,SAAU,cAAc,CAAC,OAAe,EAAA;AAC5C,IAAA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE;AAC5C,QAAA,MAAM,IAAI,UAAU,CAClB,2DAA2D,OAAO,CAAA,CAAE,CACrE;IACH;IAEA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;IACjC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;AAClC,IAAA,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;AACzC,IAAA,MAAM,CAAC,GAAG,KAAK,GAAG,EAAE;IAEpB,IAAI,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,GAAG,CAAC,CAAA,EAAA,EAAK,CAAC,CAAA,EAAA,EAAK,CAAC,GAAG;IACrC,IAAI,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,CAAA,EAAG,CAAC,CAAA,EAAA,EAAK,CAAC,GAAG;IAC/B,OAAO,CAAA,EAAG,CAAC,CAAA,CAAA,CAAG;AAChB;;;;;"}

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Format a pace value (seconds per kilometer) as a runner-friendly string.
+ *
+ * @param secondsPerKm - Pace in seconds per kilometer. Must be a non-negative finite number.
+ * @returns Formatted string like `"5:30 /km"`.
+ *
+ * @example
+ * formatPace(330) // "5:30 /km"
+ * formatPace(285) // "4:45 /km"
+ */
+declare function formatPace(secondsPerKm: number): string;
+/**
+ * Format a duration (in seconds) as a human-readable string.
+ *
+ * Always emits the largest non-zero unit and everything below it down to seconds.
+ *
+ * @param seconds - Duration in seconds. Must be a non-negative finite number.
+ * @returns Formatted string like `"1h 23m 45s"`, `"2m 5s"`, or `"30s"`.
+ *
+ * @example
+ * formatDuration(5025) // "1h 23m 45s"
+ * formatDuration(125)  // "2m 5s"
+ * formatDuration(30)   // "30s"
+ */
+declare function formatDuration(seconds: number): string;
+
+export { formatDuration, formatPace };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Format a pace value (seconds per kilometer) as a runner-friendly string.
+ *
+ * @param secondsPerKm - Pace in seconds per kilometer. Must be a non-negative finite number.
+ * @returns Formatted string like `"5:30 /km"`.
+ *
+ * @example
+ * formatPace(330) // "5:30 /km"
+ * formatPace(285) // "4:45 /km"
+ */
+declare function formatPace(secondsPerKm: number): string;
+/**
+ * Format a duration (in seconds) as a human-readable string.
+ *
+ * Always emits the largest non-zero unit and everything below it down to seconds.
+ *
+ * @param seconds - Duration in seconds. Must be a non-negative finite number.
+ * @returns Formatted string like `"1h 23m 45s"`, `"2m 5s"`, or `"30s"`.
+ *
+ * @example
+ * formatDuration(5025) // "1h 23m 45s"
+ * formatDuration(125)  // "2m 5s"
+ * formatDuration(30)   // "30s"
+ */
+declare function formatDuration(seconds: number): string;
+
+export { formatDuration, formatPace };

package/dist/index.mjs

@@ -0,0 +1,49 @@
+/**
+ * Format a pace value (seconds per kilometer) as a runner-friendly string.
+ *
+ * @param secondsPerKm - Pace in seconds per kilometer. Must be a non-negative finite number.
+ * @returns Formatted string like `"5:30 /km"`.
+ *
+ * @example
+ * formatPace(330) // "5:30 /km"
+ * formatPace(285) // "4:45 /km"
+ */
+function formatPace(secondsPerKm) {
+    if (!Number.isFinite(secondsPerKm) || secondsPerKm < 0) {
+        throw new RangeError(`secondsPerKm must be a non-negative finite number, received: ${secondsPerKm}`);
+    }
+    const total = Math.round(secondsPerKm);
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
+    return `${minutes}:${seconds.toString().padStart(2, '0')} /km`;
+}
+/**
+ * Format a duration (in seconds) as a human-readable string.
+ *
+ * Always emits the largest non-zero unit and everything below it down to seconds.
+ *
+ * @param seconds - Duration in seconds. Must be a non-negative finite number.
+ * @returns Formatted string like `"1h 23m 45s"`, `"2m 5s"`, or `"30s"`.
+ *
+ * @example
+ * formatDuration(5025) // "1h 23m 45s"
+ * formatDuration(125)  // "2m 5s"
+ * formatDuration(30)   // "30s"
+ */
+function formatDuration(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new RangeError(`seconds must be a non-negative finite number, received: ${seconds}`);
+    }
+    const total = Math.round(seconds);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h > 0)
+        return `${h}h ${m}m ${s}s`;
+    if (m > 0)
+        return `${m}m ${s}s`;
+    return `${s}s`;
+}
+
+export { formatDuration, formatPace };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;AASG;AACG,SAAU,UAAU,CAAC,YAAoB,EAAA;AAC7C,IAAA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE;AACtD,QAAA,MAAM,IAAI,UAAU,CAClB,gEAAgE,YAAY,CAAA,CAAE,CAC/E;IACH;IAEA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;AACtC,IAAA,MAAM,OAAO,GAAG,KAAK,GAAG,EAAE;AAE1B,IAAA,OAAO,CAAA,EAAG,OAAO,CAAA,CAAA,EAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM;AAChE;AAEA;;;;;;;;;;;;AAYG;AACG,SAAU,cAAc,CAAC,OAAe,EAAA;AAC5C,IAAA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE;AAC5C,QAAA,MAAM,IAAI,UAAU,CAClB,2DAA2D,OAAO,CAAA,CAAE,CACrE;IACH;IAEA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;IACjC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;AAClC,IAAA,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;AACzC,IAAA,MAAM,CAAC,GAAG,KAAK,GAAG,EAAE;IAEpB,IAAI,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,GAAG,CAAC,CAAA,EAAA,EAAK,CAAC,CAAA,EAAA,EAAK,CAAC,GAAG;IACrC,IAAI,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,CAAA,EAAG,CAAC,CAAA,EAAA,EAAK,CAAC,GAAG;IAC/B,OAAO,CAAA,EAAG,CAAC,CAAA,CAAA,CAAG;AAChB;;;;"}

package/package.json

@@ -0,0 +1,67 @@
+{
+ "name": "@vaibhavt07/pace-utils",
+  "version": "0.0.1",
+  "description": "Tiny utilities for formatting running pace and duration.",
+  "keywords": ["running", "pace", "duration", "format", "strava", "fitness"],
+  "license": "MIT",
+  "author": "Vaibhav Tyagi <vaibhavtyagi438@gmail.com> (https://vaibhavt07.com)",
+  "homepage": "https://github.com/mrtyagi07/pace-utils#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrtyagi07/pace-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mrtyagi07/pace-utils/issues"
+  },
+
+  "type": "module",
+  "sideEffects": false,
+
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+
+  "engines": {
+    "node": ">=18"
+  },
+
+  "publishConfig": {
+    "access": "public"
+  },
+
+  "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "build": "rollup -c",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^25.9.1",
+    "rollup": "^4.60.4",
+    "rollup-plugin-dts": "^6.4.1",
+    "tslib": "^2.8.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  }
+}