https://github.com/noahwillcrow/roblox-ts_timespan
https://github.com/noahwillcrow/roblox-ts_timespan
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/noahwillcrow/roblox-ts_timespan
- Owner: noahwillcrow
- License: mit
- Created: 2025-04-28T01:14:08.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2026-01-24T02:29:23.000Z (5 months ago)
- Last Synced: 2026-01-24T06:44:12.395Z (5 months ago)
- Language: TypeScript
- Size: 70.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @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
```bash
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.
```typescript
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.
```typescript
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").
```typescript
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`).
```typescript
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:**
```lua
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:**
```typescript
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`) |