@rbxts/timespan

A simple TimeSpan implementation for roblox-ts that stores time units down to millisecond precision. This utility facilitates time arithmetic, comparisons, and custom string formatting.

It also automatically registers Luau metamethods, making it seamless to use in mixed TypeScript/Luau environments.

Installation

npm i @rbxts/timespan

Basic Usage

Creating TimeSpans

You can create a TimeSpan from specific units or by calculating the difference between two DateTime objects.

import { TimeSpan } from "@rbxts/timespan";

// From specific units
const fiveSeconds = TimeSpan.fromSeconds(5);
const oneHour = TimeSpan.fromHours(1);

// From component parts (Days, Hours, Minutes, Seconds, Milliseconds)
const specific = TimeSpan.create(1, 4, 30, 0, 0); // 1 day, 4 hours, 30 mins

// Zero TimeSpan
const zero = TimeSpan.zero; // 0 milliseconds

// From DateTime delta (b - a)
const now = DateTime.now();
const later = DateTime.fromUnixTimestamp(now.UnixTimestamp + 60);
const diff = TimeSpan.fromBetweenDateTimes(now, later); // 60 seconds

Arithmetic

TimeSpans are immutable; operations return a new TimeSpan instance.

const t1 = TimeSpan.fromMinutes(5);
const t2 = TimeSpan.fromSeconds(30);

const total = t1.add(t2);       // 5m 30s
const doubled = total.mul(2);   // 11m 0s

// Division (Scaling)
const half = total.div(2);      // 2m 45s

// Ratio (TimeSpan / TimeSpan)
const ratio = t1.ratio(t2);     // 10 (300s / 30s)

// DateTime integration
const futureDate = total.addTo(DateTime.now());

Reading Values

There is a distinction between Total values (the whole span converted to a unit) and Component values (the partial unit, like the "30" in "1 hour 30 minutes").

const span = TimeSpan.fromMinutes(90); // 1 hour, 30 minutes

// Total values
print(span.totalMinutes()); // 90
print(span.totalHours());   // 1.5

// Component values
print(span.hours());        // 1
print(span.minutes());      // 30

Comparison

Includes standard comparisons and short-hand aliases (eq, gt, lte).

const t1 = TimeSpan.fromSeconds(10);
const t2 = TimeSpan.fromSeconds(20);

if (t2.gt(t1)) {
    print("t2 is greater than t1");
}

// Check with epsilon tolerance (defaults to 2^-10 ms)
if (t1.isCloseTo(t2)) { ... }

Luau Support (Metatables)

This package automatically sets up metatables for the TimeSpan object. This allows you (or other scripts in your game) to use standard Lua operators.

| Operator | Action | Logic | | --- | --- | --- | | + | Add | TimeSpan + TimeSpan | | - | Subtract | TimeSpan - TimeSpan | | * | Multiply | TimeSpan * number (Commutative) | | / | Scale | TimeSpan / number (Returns TimeSpan) | | / | Ratio | TimeSpan / TimeSpan (Returns number) | | tostring | Format | Calls .toString() default | | ==, <, <= | Compare | Equality and Order checks |

Luau Example:

local t1 = TimeSpan.fromSeconds(10)
local t2 = TimeSpan.fromSeconds(5)

print(t1 + t2) -- 15s (TimeSpan)
print(t1 * 2)  -- 20s (TimeSpan)
print(2 * t1)  -- 20s (TimeSpan)

-- Division behavior depends on the operand
print(t1 / 2)  -- 5s (TimeSpan)
print(t1 / t2) -- 2  (number: how many times t2 fits in t1)

-- String conversion
print(t1)      -- "00.00:00:10.000" (default format)

String Formatting

The toString(format?) method accepts a custom format string. If no format is provided, it defaults to %{S}%{DD}.%{HH}:%{MM}:%{ss}.%{mmm}.

| Token | Description | Example | | --- | --- | --- | | %{S} | Sign (- or empty) | - | | %{D} | Days | 1 | | %{DD} | Days (min 2 digits) | 01 | | %{H} | Hours | 5 | | %{HH} | Hours (min 2 digits) | 05 | | %{M} | Minutes | 9 | | %{MM} | Minutes (min 2 digits) | 09 | | %{s} | Seconds | 4 | | %{ss} | Seconds (min 2 digits) | 04 | | %{m} | Milliseconds | 50 | | %{mmm} | Milliseconds (min 3 digits) | 050 |

Example:

const t = TimeSpan.fromSeconds(65.5);
print(t.toString("%{m}m %{s}s")); // "1m 5s"

List of API Methods

| Category | Methods | | --- | --- | | Constructors | fromMilliseconds, fromSeconds, fromMinutes, fromHours, fromDays, fromBetweenDateTimes, create, zero | | Accessors | totalMilliseconds, totalSeconds, totalMinutes, totalHours, totalDays | | Components | milliseconds, seconds, minutes, hours, days | | Absolute Components | absMilliseconds, absSeconds, absMinutes, absHours, absDays | | Arithmetic | add, sub, mul, div, ratio, addTo, subtractFrom | | Logic | isEqualTo (eq), isGreaterThan (gt), isLessThan (lt), isGreaterThanOrEqualTo (gte), isLessThanOrEqualTo (lte), isCloseTo (close) |