nanoduration 1.0.0

package/README.md

@@ -0,0 +1,153 @@
+# Duration
+
+An immutable, non-negative, Rust-inspired `Duration` type for JavaScript and TypeScript.
+
+This library provides a small, predictable abstraction for representing spans of time with explicit units, saturating arithmetic, and strong invariants—without calendars, time zones, or parsing logic.
+
+---
+
+## Summary
+
+`Duration` is a value-type abstraction for time intervals, modeled after Rust’s `std::time::Duration`.
+
+It is designed for:
+
+- timeouts
+- delays
+- retry/backoff logic
+- infrastructure and systems-oriented code
+
+The library prioritizes correctness, explicitness, and simplicity over feature breadth.
+
+---
+
+## What this library does
+
+- Represents time as an immutable value (internally stored in nanoseconds)
+- Enforces **non-negative durations**
+- Provides **explicit unit constructors** (`seconds`, `milliseconds`, etc.)
+- Supports **saturating arithmetic** (durations never go negative)
+- Avoids all calendar, timezone, and locale concerns
+- Ships with **full TypeScript type definitions**
+
+### What it intentionally does not do
+
+- Date/time manipulation
+- Parsing human-readable strings
+- Time zones or calendars
+- Implicit unit coercion
+
+---
+
+## Installation
+
+```sh
+npm install nanoduration
+```
+
+---
+
+## Usage
+
+### Creating durations
+
+```ts
+import { Duration } from "nanoduration";
+
+const a = Duration.fromSecs(2);
+const b = Duration.fromMillis(500);
+```
+
+### Arithmetic
+
+```ts
+const total = a.add(b); // 2.5 seconds
+const remaining = total.sub(Duration.fromSecs(5)); // saturates to 0
+```
+
+### Conversions
+
+```ts
+total.asMillis(); // 2500
+total.asSecs(); // 2.5
+```
+
+### Comparisons
+
+```ts
+total.gt(Duration.fromSecs(2)); // true
+total.eq(Duration.fromMillis(2500)); // true
+```
+
+### Utilities
+
+```ts
+Duration.ZERO.isZero(); // true
+
+const clamped = total.clamp(Duration.fromSecs(1), Duration.fromSecs(3));
+```
+
+### Interop with Node.js APIs
+
+```ts
+setTimeout(() => {
+  // ...
+}, total.asMillis());
+```
+
+---
+
+## Benefits of using this library
+
+### Predictable semantics
+
+- Durations never become negative
+- No silent unit conversions
+- No hidden calendar logic
+
+### Safer than raw numbers
+
+- Units are explicit at construction
+- Arithmetic behavior is well-defined
+- Fewer “milliseconds vs seconds” bugs
+
+### Lightweight
+
+- No dependencies
+- Small API surface
+- Tree-shakable
+- Minimal runtime overhead
+
+### TypeScript-first
+
+- Strict typings included
+- Works out of the box with modern ESM setups
+
+---
+
+## Design notes
+
+- Internal unit: **nanoseconds**
+- Arithmetic: **saturating**
+- Mutability: **immutable**
+- Module format: **ESM**
+- Inspired by: Rust’s `std::time::Duration`
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+### Guidelines
+
+1. Keep the API minimal and explicit
+2. Maintain non-negative duration invariants
+3. Preserve backward compatibility where possible
+4. Run `npm run build` before submitting changes
+
+## License
+
+MIT License.
+
+See the `LICENSE` file for details.

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Represents an immutable, non-negative span of time.
+ *
+ * ## Design characteristics
+ * - Internally stored as nanoseconds
+ * - Saturating arithmetic (never becomes negative)
+ * - No calendar, timezone, or locale semantics
+ * - Explicit unit construction and observation
+ *
+ * This type is intended for:
+ * - Timeouts
+ * - Intervals
+ * - Backoff calculations
+ * - System and infrastructure code
+ */
+export declare class Duration {
+    /** Nanoseconds per microsecond */
+    private static readonly NS_PER_MICRO;
+    /** Nanoseconds per millisecond */
+    private static readonly NS_PER_MILLI;
+    /** Nanoseconds per second */
+    private static readonly NS_PER_SECOND;
+    /** Nanoseconds per minute */
+    private static readonly NS_PER_MINUTE;
+    /** Nanoseconds per hour */
+    private static readonly NS_PER_HOUR;
+    /**
+     * A duration of zero length.
+     */
+    static readonly ZERO: Duration;
+    private readonly nanoseconds;
+    /**
+     * Internal constructor.
+     *
+     * All instances are guaranteed to contain a non-negative,
+     * finite number of nanoseconds.
+     */
+    private constructor();
+    /**
+     * Creates a duration from nanoseconds.
+     *
+     * @param nanos - Number of nanoseconds
+     */
+    static fromNanos(nanos: number): Duration;
+    /**
+     * Creates a duration from microseconds.
+     *
+     * @param micros - Number of microseconds
+     */
+    static fromMicros(micros: number): Duration;
+    /**
+     * Creates a duration from milliseconds.
+     *
+     * @param millis - Number of milliseconds
+     */
+    static fromMillis(millis: number): Duration;
+    /**
+     * Creates a duration from seconds.
+     *
+     * @param secs - Number of seconds
+     */
+    static fromSecs(secs: number): Duration;
+    /**
+     * Creates a duration from minutes.
+     *
+     * @param minutes - Number of minutes
+     */
+    static fromMinutes(minutes: number): Duration;
+    /**
+     * Creates a duration from hours.
+     *
+     * @param hours - Number of hours
+     */
+    static fromHours(hours: number): Duration;
+    /**
+     * Returns the total duration in nanoseconds.
+     */
+    asNanos(): number;
+    /**
+     * Returns the total duration in microseconds.
+     */
+    asMicros(): number;
+    /**
+     * Returns the total duration in milliseconds.
+     */
+    asMillis(): number;
+    /**
+     * Returns the total duration in seconds.
+     */
+    asSecs(): number;
+    /**
+     * Returns the total duration in minutes.
+     */
+    asMinutes(): number;
+    /**
+     * Returns the total duration in hours.
+     */
+    asHours(): number;
+    /**
+     * Returns the sum of this duration and another.
+     *
+     * If the result would be negative or overflow, it saturates at zero
+     * or throws respectively.
+     */
+    add(other: Duration): Duration;
+    /**
+     * Returns the difference between this duration and another.
+     *
+     * If the result would be negative, it saturates at zero.
+     */
+    sub(other: Duration): Duration;
+    /**
+     * Multiplies this duration by a factor.
+     *
+     * Negative or non-finite results saturate at zero or throw.
+     */
+    mul(factor: number): Duration;
+    /**
+     * Divides this duration by a divisor.
+     *
+     * @throws {RangeError} If divisor is zero
+     */
+    div(divisor: number): Duration;
+    /**
+     * Returns true if both durations are equal.
+     */
+    eq(other: Duration): boolean;
+    /**
+     * Returns true if this duration is less than the other.
+     */
+    lt(other: Duration): boolean;
+    /**
+     * Returns true if this duration is less than or equal to the other.
+     */
+    le(other: Duration): boolean;
+    /**
+     * Returns true if this duration is greater than the other.
+     */
+    gt(other: Duration): boolean;
+    /**
+     * Returns true if this duration is greater than or equal to the other.
+     */
+    ge(other: Duration): boolean;
+    /**
+     * Returns true if this duration is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Clamps this duration between a minimum and maximum.
+     *
+     * @throws {RangeError} If min is greater than max
+     */
+    clamp(min: Duration, max: Duration): Duration;
+    /**
+     * Returns a human-readable string representation.
+     *
+     * Chooses the largest unit that divides evenly.
+     * Values are rounded to 6 decimal places when needed.
+     */
+    toString(): string;
+}
+//# 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":"AAwCA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;IACnB,kCAAkC;IAClC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAO;IAE3C,kCAAkC;IAClC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAO;IAE3C,6BAA6B;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAO;IAE5C,6BAA6B;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAA+B;IAEpE,2BAA2B;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAElE;;OAEG;IACH,gBAAuB,IAAI,WAA+B;IAE1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAE7C;;;;;OAKG;IACH,OAAO;IAQP;;;;OAIG;WACW,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IAIhD;;;;OAIG;WACW,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAIlD;;;;OAIG;WACW,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAIlD;;;;OAIG;WACW,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAI9C;;;;OAIG;WACW,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;IAIpD;;;;OAIG;WACW,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IAQhD;;OAEG;IACI,OAAO,IAAI,MAAM;IAIxB;;OAEG;IACI,QAAQ,IAAI,MAAM;IAIzB;;OAEG;IACI,QAAQ,IAAI,MAAM;IAIzB;;OAEG;IACI,MAAM,IAAI,MAAM;IAIvB;;OAEG;IACI,SAAS,IAAI,MAAM;IAI1B;;OAEG;IACI,OAAO,IAAI,MAAM;IAUxB;;;;;OAKG;IACI,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ;IAIrC;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ;IAIrC;;;;OAIG;IACI,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAIpC;;;;OAIG;IACI,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;IAYrC;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAInC;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAInC;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAInC;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAInC;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAQnC;;OAEG;IACI,MAAM,IAAI,OAAO;IAIxB;;;;OAIG;IACI,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,GAAG,QAAQ;IAYpD;;;;;OAKG;IACI,QAAQ,IAAI,MAAM;CAqB1B"}

package/dist/index.js

@@ -0,0 +1,267 @@
+/* ===========================
+ * PositiveNumber (unforgeable)
+ * =========================== */
+/**
+ * Converts a number into a {@link PositiveNumber} using saturating semantics.
+ *
+ * - Non-finite values (`NaN`, `Infinity`, `-Infinity`) throw.
+ * - Negative values are clamped to `0`.
+ *
+ * @param num - Input number
+ * @returns A non-negative finite number
+ * @throws {RangeError} If the value is not finite
+ */
+function toPositive(num) {
+    if (!Number.isFinite(num)) {
+        throw new RangeError("Value must be finite");
+    }
+    // Saturating semantics: never negative
+    return (num <= 0 ? 0 : num);
+}
+/* ===========================
+ * Duration
+ * =========================== */
+/**
+ * Represents an immutable, non-negative span of time.
+ *
+ * ## Design characteristics
+ * - Internally stored as nanoseconds
+ * - Saturating arithmetic (never becomes negative)
+ * - No calendar, timezone, or locale semantics
+ * - Explicit unit construction and observation
+ *
+ * This type is intended for:
+ * - Timeouts
+ * - Intervals
+ * - Backoff calculations
+ * - System and infrastructure code
+ */
+export class Duration {
+    /**
+     * Internal constructor.
+     *
+     * All instances are guaranteed to contain a non-negative,
+     * finite number of nanoseconds.
+     */
+    constructor(nanoseconds) {
+        this.nanoseconds = nanoseconds;
+    }
+    /* ============
+     * Constructors
+     * ============ */
+    /**
+     * Creates a duration from nanoseconds.
+     *
+     * @param nanos - Number of nanoseconds
+     */
+    static fromNanos(nanos) {
+        return new Duration(toPositive(nanos));
+    }
+    /**
+     * Creates a duration from microseconds.
+     *
+     * @param micros - Number of microseconds
+     */
+    static fromMicros(micros) {
+        return new Duration(toPositive(micros * Duration.NS_PER_MICRO));
+    }
+    /**
+     * Creates a duration from milliseconds.
+     *
+     * @param millis - Number of milliseconds
+     */
+    static fromMillis(millis) {
+        return new Duration(toPositive(millis * Duration.NS_PER_MILLI));
+    }
+    /**
+     * Creates a duration from seconds.
+     *
+     * @param secs - Number of seconds
+     */
+    static fromSecs(secs) {
+        return new Duration(toPositive(secs * Duration.NS_PER_SECOND));
+    }
+    /**
+     * Creates a duration from minutes.
+     *
+     * @param minutes - Number of minutes
+     */
+    static fromMinutes(minutes) {
+        return new Duration(toPositive(minutes * Duration.NS_PER_MINUTE));
+    }
+    /**
+     * Creates a duration from hours.
+     *
+     * @param hours - Number of hours
+     */
+    static fromHours(hours) {
+        return new Duration(toPositive(hours * Duration.NS_PER_HOUR));
+    }
+    /* =========
+     * Observers
+     * ========= */
+    /**
+     * Returns the total duration in nanoseconds.
+     */
+    asNanos() {
+        return this.nanoseconds;
+    }
+    /**
+     * Returns the total duration in microseconds.
+     */
+    asMicros() {
+        return this.nanoseconds / Duration.NS_PER_MICRO;
+    }
+    /**
+     * Returns the total duration in milliseconds.
+     */
+    asMillis() {
+        return this.nanoseconds / Duration.NS_PER_MILLI;
+    }
+    /**
+     * Returns the total duration in seconds.
+     */
+    asSecs() {
+        return this.nanoseconds / Duration.NS_PER_SECOND;
+    }
+    /**
+     * Returns the total duration in minutes.
+     */
+    asMinutes() {
+        return this.nanoseconds / Duration.NS_PER_MINUTE;
+    }
+    /**
+     * Returns the total duration in hours.
+     */
+    asHours() {
+        return this.nanoseconds / Duration.NS_PER_HOUR;
+    }
+    /* ==========
+     * Arithmetic
+     * ==========
+     * Saturating semantics
+     */
+    /**
+     * Returns the sum of this duration and another.
+     *
+     * If the result would be negative or overflow, it saturates at zero
+     * or throws respectively.
+     */
+    add(other) {
+        return new Duration(toPositive(this.nanoseconds + other.nanoseconds));
+    }
+    /**
+     * Returns the difference between this duration and another.
+     *
+     * If the result would be negative, it saturates at zero.
+     */
+    sub(other) {
+        return new Duration(toPositive(this.nanoseconds - other.nanoseconds));
+    }
+    /**
+     * Multiplies this duration by a factor.
+     *
+     * Negative or non-finite results saturate at zero or throw.
+     */
+    mul(factor) {
+        return new Duration(toPositive(this.nanoseconds * factor));
+    }
+    /**
+     * Divides this duration by a divisor.
+     *
+     * @throws {RangeError} If divisor is zero
+     */
+    div(divisor) {
+        if (divisor === 0) {
+            throw new RangeError("Division by zero");
+        }
+        return new Duration(toPositive(this.nanoseconds / divisor));
+    }
+    /* ===========
+     * Comparisons
+     * =========== */
+    /**
+     * Returns true if both durations are equal.
+     */
+    eq(other) {
+        return this.nanoseconds === other.nanoseconds;
+    }
+    /**
+     * Returns true if this duration is less than the other.
+     */
+    lt(other) {
+        return this.nanoseconds < other.nanoseconds;
+    }
+    /**
+     * Returns true if this duration is less than or equal to the other.
+     */
+    le(other) {
+        return this.nanoseconds <= other.nanoseconds;
+    }
+    /**
+     * Returns true if this duration is greater than the other.
+     */
+    gt(other) {
+        return this.nanoseconds > other.nanoseconds;
+    }
+    /**
+     * Returns true if this duration is greater than or equal to the other.
+     */
+    ge(other) {
+        return this.nanoseconds >= other.nanoseconds;
+    }
+    /* =========
+     * Utilities
+     * ========= */
+    /**
+     * Returns true if this duration is zero.
+     */
+    isZero() {
+        return this.nanoseconds === 0;
+    }
+    /**
+     * Clamps this duration between a minimum and maximum.
+     *
+     * @throws {RangeError} If min is greater than max
+     */
+    clamp(min, max) {
+        if (min.gt(max)) {
+            throw new RangeError("min must be <= max");
+        }
+        return new Duration(toPositive(Math.min(Math.max(this.nanoseconds, min.nanoseconds), max.nanoseconds)));
+    }
+    /**
+     * Returns a human-readable string representation.
+     *
+     * Chooses the largest unit that divides evenly.
+     * Values are rounded to 6 decimal places when needed.
+     */
+    toString() {
+        const round = (n) => Number.isInteger(n) ? n : Number(n.toFixed(6));
+        if (this.nanoseconds % Duration.NS_PER_HOUR === 0)
+            return `${round(this.asHours())}h`;
+        if (this.nanoseconds % Duration.NS_PER_MINUTE === 0)
+            return `${round(this.asMinutes())}m`;
+        if (this.nanoseconds % Duration.NS_PER_SECOND === 0)
+            return `${round(this.asSecs())}s`;
+        if (this.nanoseconds % Duration.NS_PER_MILLI === 0)
+            return `${round(this.asMillis())}ms`;
+        if (this.nanoseconds % Duration.NS_PER_MICRO === 0)
+            return `${round(this.asMicros())}µs`;
+        return `${this.nanoseconds}ns`;
+    }
+}
+/** Nanoseconds per microsecond */
+Duration.NS_PER_MICRO = 1e3;
+/** Nanoseconds per millisecond */
+Duration.NS_PER_MILLI = 1e6;
+/** Nanoseconds per second */
+Duration.NS_PER_SECOND = 1e9;
+/** Nanoseconds per minute */
+Duration.NS_PER_MINUTE = 60 * Duration.NS_PER_SECOND;
+/** Nanoseconds per hour */
+Duration.NS_PER_HOUR = 60 * Duration.NS_PER_MINUTE;
+/**
+ * A duration of zero length.
+ */
+Duration.ZERO = new Duration(toPositive(0));

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "nanoduration",
+  "version": "1.0.0",
+  "description": "An immutable, non-negative, Rust-inspired `Duration` type for JavaScript and TypeScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "duration",
+    "time",
+    "typescript",
+    "immutable",
+    "esm",
+    "rust",
+    "value-object"
+  ],
+  "license": "MIT"
+}