z-duration 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zachary Lysobey
+
+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,149 @@
-# Temporary Holding Version
+# duration
 
-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.
+A small, dependency-light TypeScript library for representing, converting,
+and normalizing fixed durations. It builds on
+[`time-units`](../time-units), reusing its scalar unit-conversion
+constants and functions rather than duplicating them.
+
+The entire implementation is a single TypeScript file:
+[`index.ts`](https://github.com/zachlysobey/z-megarepo/blob/master/duration/index.ts).
+
+## Usage
+
+```ts
+import {
+  balanceDuration,
+  durationToHours,
+  durationToMilliseconds,
+  hoursToDuration,
+  millisecondsToDuration,
+} from "z-duration";
+
+durationToMilliseconds({ minutes: 1, seconds: 30 }); // 90_000
+durationToHours({ days: 1, hours: 12 }); // 36
+
+millisecondsToDuration(90_000); // { minutes: 1, seconds: 30 }
+hoursToDuration(49); // { days: 2, hours: 1 }
+
+balanceDuration({ days: 3, hours: 48 }); // { days: 5 }
+```
+
+## The `Duration` type
+
+A `Duration` is a plain object with one or more of the supported unit
+fields: `milliseconds`, `seconds`, `minutes`, `hours`, `days`. It must
+contain at least one field, and it is not required to be balanced:
+
+```ts
+const a: Duration = { days: 3 };
+const b: Duration = { hours: 2, minutes: 30 };
+const c: Duration = { days: 3, hours: 48 }; // valid, unbalanced
+const invalid: Duration = {}; // type error
+```
+
+Field values are ordinary `number`s: fractional and negative values are
+valid and are never rounded, rejected, or coerced.
+
+A day always means exactly 24 elapsed hours — this package has no
+calendar, timezone, or date awareness (see [Package boundaries](#package-boundaries)).
+
+## API
+
+### Duration to scalar
+
+Each function reduces a full, possibly-unbalanced `Duration` into a
+single scalar unit. Missing fields count as zero.
+
+- `durationToMilliseconds(duration)`
+- `durationToSeconds(duration)`
+- `durationToMinutes(duration)`
+- `durationToHours(duration)`
+- `durationToDays(duration)`
+
+```ts
+durationToDays({ days: 3, hours: 48 }); // 5
+```
+
+### Scalar to Duration
+
+Each function converts a scalar quantity into a balanced `Duration`,
+expressed using the largest appropriate units, with any remainder carried
+into smaller units rather than rounded away.
+
+- `millisecondsToDuration(milliseconds)`
+- `secondsToDuration(seconds)`
+- `minutesToDuration(minutes)`
+- `hoursToDuration(hours)`
+- `daysToDuration(days)`
+
+```ts
+hoursToDuration(1.5); // { hours: 1, minutes: 30 }
+```
+
+### `balanceDuration(duration)`
+
+Normalizes an arbitrary, possibly-unbalanced `Duration` into canonical
+form: the largest appropriate units, zero-valued fields omitted.
+
+```ts
+balanceDuration({ minutes: 90, seconds: 30 });
+// { hours: 1, minutes: 30, seconds: 30 }
+```
+
+`balanceDuration` is normalization, not rounding — it never discards
+part of the represented value.
+
+## Semantics
+
+- **Balancing order**: days → hours → minutes → seconds → milliseconds,
+  using the fixed relationships from `time-units` (1 day = 24 hours,
+  1 hour = 60 minutes, 1 minute = 60 seconds, 1 second = 1000
+  milliseconds).
+- **Zero-valued fields are omitted** from a balanced result, e.g.
+  `hoursToDuration(24)` returns `{ days: 1 }`, not
+  `{ days: 1, hours: 0, minutes: 0, seconds: 0, milliseconds: 0 }`. The
+  one exception is a duration that nets to exactly zero, which is
+  reported as `{ milliseconds: 0 }` so the result still satisfies the
+  `Duration` type's at-least-one-field requirement.
+- **Negative durations** are valid and unrestricted. Balancing truncates
+  toward zero at each unit, so every field in a balanced result shares
+  the same sign — e.g. `minutesToDuration(-1.5)` returns
+  `{ minutes: -1, seconds: -30 }`, never a duration whose fields disagree
+  in sign or that changes the represented value.
+- **Fractional values** are valid and are never rounded. Any remainder
+  that can't be expressed in a larger unit is carried down to smaller
+  units, and a remainder too small even for milliseconds is left exactly
+  as ordinary JavaScript floating-point arithmetic produces it.
+
+## Package boundaries
+
+`duration` represents and transforms fixed elapsed-time durations. It
+does not know about dates, timestamps, timezones, or calendars, and it
+has no parsing, formatting, or rounding policy. Operations like
+`addDuration(duration)(date)`, `nextMonday(...)`, `parseDuration(...)`,
+`formatDuration(...)`, or `roundDuration(...)` belong in a separate,
+higher-level package.
+
+## Mutability
+
+All operations are pure: no argument is mutated, and every function
+returns a new value.
+
+## Contributing
+
+See the
+[CONTRIBUTING guide](https://github.com/zachlysobey/z-megarepo/blob/master/duration/docs/CONTRIBUTING.md)
+for setup and development scripts.
+
+## Packaging
+
+Published as ESM-only with bundled type declarations, built into `dist/`
+by `npm run build`. Runtime-agnostic (browsers, Node, Bun, Deno,
+workers), with `sideEffects: false` so bundlers can tree-shake unused
+exports.
+
+## License
+
+[MIT](https://github.com/zachlysobey/z-megarepo/blob/master/duration/LICENSE)
+— unlike the rest of the surrounding monorepo, which is GPL-3.0-or-later,
+this package is MIT-licensed to encourage adoption.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/** Requires at least one property of `T` to be present. */
+type RequireAtLeastOne<T> = {
+    [K in keyof T]: Required<Pick<T, K>> & Partial<Omit<T, K>>;
+}[keyof T];
+export type Duration = RequireAtLeastOne<{
+    milliseconds: number;
+    seconds: number;
+    minutes: number;
+    hours: number;
+    days: number;
+}>;
+export declare const durationToMilliseconds: (duration: Duration) => number;
+export declare const durationToSeconds: (duration: Duration) => number;
+export declare const durationToMinutes: (duration: Duration) => number;
+export declare const durationToHours: (duration: Duration) => number;
+export declare const durationToDays: (duration: Duration) => number;
+export declare const millisecondsToDuration: (milliseconds: number) => Duration;
+export declare const secondsToDuration: (seconds: number) => Duration;
+export declare const minutesToDuration: (minutes: number) => Duration;
+export declare const hoursToDuration: (hours: number) => Duration;
+export declare const daysToDuration: (days: number) => Duration;
+export declare const balanceDuration: (duration: Duration) => Duration;
+export {};

package/dist/index.js

@@ -0,0 +1,47 @@
+import { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, daysToMilliseconds, hoursToMilliseconds, minutesToMilliseconds, secondsToMilliseconds, millisecondsToSeconds, millisecondsToMinutes, millisecondsToHours, millisecondsToDays, } from 'z-time-units';
+export const durationToMilliseconds = (duration) => daysToMilliseconds(duration.days ?? 0) +
+    hoursToMilliseconds(duration.hours ?? 0) +
+    minutesToMilliseconds(duration.minutes ?? 0) +
+    secondsToMilliseconds(duration.seconds ?? 0) +
+    (duration.milliseconds ?? 0);
+export const durationToSeconds = (duration) => millisecondsToSeconds(durationToMilliseconds(duration));
+export const durationToMinutes = (duration) => millisecondsToMinutes(durationToMilliseconds(duration));
+export const durationToHours = (duration) => millisecondsToHours(durationToMilliseconds(duration));
+export const durationToDays = (duration) => millisecondsToDays(durationToMilliseconds(duration));
+export const millisecondsToDuration = (milliseconds) => {
+    const result = {};
+    let remaining = milliseconds;
+    const days = Math.trunc(remaining / MILLISECONDS_PER_DAY);
+    if (days !== 0) {
+        result.days = days;
+        remaining -= days * MILLISECONDS_PER_DAY;
+    }
+    const hours = Math.trunc(remaining / MILLISECONDS_PER_HOUR);
+    if (hours !== 0) {
+        result.hours = hours;
+        remaining -= hours * MILLISECONDS_PER_HOUR;
+    }
+    const minutes = Math.trunc(remaining / MILLISECONDS_PER_MINUTE);
+    if (minutes !== 0) {
+        result.minutes = minutes;
+        remaining -= minutes * MILLISECONDS_PER_MINUTE;
+    }
+    const seconds = Math.trunc(remaining / MILLISECONDS_PER_SECOND);
+    if (seconds !== 0) {
+        result.seconds = seconds;
+        remaining -= seconds * MILLISECONDS_PER_SECOND;
+    }
+    // `remaining` may be a legitimate 0, or -0 from truncating a negative
+    // fraction; `|| 0` collapses -0 to 0 without disturbing any other value.
+    // At least one field is required, so an all-zero result still reports
+    // `{ milliseconds: 0 }` rather than an empty object.
+    if (remaining !== 0 || Object.keys(result).length === 0) {
+        result.milliseconds = remaining || 0;
+    }
+    return result;
+};
+export const secondsToDuration = (seconds) => millisecondsToDuration(secondsToMilliseconds(seconds));
+export const minutesToDuration = (minutes) => millisecondsToDuration(minutesToMilliseconds(minutes));
+export const hoursToDuration = (hours) => millisecondsToDuration(hoursToMilliseconds(hours));
+export const daysToDuration = (days) => millisecondsToDuration(daysToMilliseconds(days));
+export const balanceDuration = (duration) => millisecondsToDuration(durationToMilliseconds(duration));

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "z-duration",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Tiny TypeScript library for representing, converting, and normalizing fixed durations",
+  "scripts": {
+    "test": "node --test \"*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "prepack": "npm run build"
+  },
+  "author": "Zachary Lysobey <zach@lysobey.com> (https://github.com/zachlysobey)",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10"
+  },
+  "dependencies": {
+    "z-time-units": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^7.0.2"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=24 <25",
+      "onFail": "error"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachlysobey/z-megarepo.git",
+    "directory": "duration"
+  }
+}