> For the complete documentation index, see [llms.txt](https://katxupa.gitbook.io/katxupa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://katxupa.gitbook.io/katxupa/get-a-taste-of-katxupa/dip-dive/duration.md).

# Duration

represents a duration of time with support for various units (nanoseconds, microseconds, milliseconds, seconds, minutes, hours, and days). 

It provides methods to create, manipulate, and compare durations, as well as convert them to different units and formats.

{% code title="Example Usage" %}

```typescript
// Create a duration of 5 seconds
const duration = Duration.seconds(5);

// Convert the duration to minutes
const minutes = duration.inWholeMinutes();

console.log(minutes);
// Output: 0

// Add another duration of 2 minutes
const sum = duration.add(Duration.minutes(2));

console.log(sum.inWholeSeconds());
// Output: 420
```

{% endcode %}

## Main functionalities 

* Create a duration object from different units of time (*nanoseconds*, *microseconds*, *milliseconds*, *seconds*, *minutes*, *hours*, and *days*) 
* Convert the duration to different units (*seconds*, *minutes*, *hours*, and *days*) 
* Perform arithmetic operations on durations (*addition*, *subtraction*, *multiplication*, *division*)
* Compare durations (*equality*, l*ess than*, *greater than*) 
* Format the duration as a string representation

## Global Functions

### durationOf

Creates a Duration object from a duration in milliseconds.

```typescript
const duration = durationOf(5000);
console.log(duration.toSeconds()); // Output: 5
```

## Static Functions

### nanoseconds

Creates a Duration object from a duration in nanoseconds.

```typescript
const duration = Duration.nanoseconds(1e9);
```

### microseconds

Creates a Duration object from a duration in microseconds.

```typescript
const duration = Duration.microseconds(5000000);
```

### milliseconds

Creates a Duration object from a duration in milliseconds.

```typescript
const duration = Duration.milliseconds(5000);
```

### seconds

Creates a Duration object from a duration in seconds.

```typescript
const duration = Duration.seconds(60);
```

### minutes

Creates a Duration object from a duration in minutes.

```typescript
const duration = Duration.minutes(60);
```

### hours

Creates a Duration object from a duration in hours.

```typescript
const duration = Duration.hours(24);
```

### days

Creates a Duration object from a duration in days.

```typescript
const duration = Duration.days(7);
```

## Class Functions

### inWholeSeconds

Converts the duration to seconds.

```typescript
const seconds = (2).minutes().inWholeSeconds();
console.log(seconds);
// Output: 120
```

### inWholeMinutes

Converts the duration to minutes.

```typescript
const minutes = (2).hours().inWholeMinutes();
console.log(minutes);
// Output: 120
```

### inWholeHours

Converts the duration to hours.

```typescript
const hours = (1).days().inWholeHours();
console.log(hours);
// Output: 24
```

### inWholeDays

Converts the duration to days.

```typescript
const days = (48).hours().inWholeDays();
console.log(days);
// Output: 2
```

### toObject

Converts the duration to an object with properties for each time unit.

```typescript
const durationObject = (123).seconds().toObject();
console.log(durationObject);
// Output: { nanoseconds: 123000000000, microseconds: 123000000, milliseconds: 123000, seconds: 123, minutes: 2, hours: 0, days: 0 }
```

### toComponents

Splits this duration into days, hours, minutes, seconds, and nanoseconds.

```typescript
const components = (2).days().add((12).hours()).toComponents();
console.log(components);
// Output: { days: 2, hours: 12, minutes: 0, seconds: 0, nanoseconds: 0 }
```

### add

Adds another duration to this duration.

```typescript
const sum = (12).hours().add((30).minutes());
console.log(sum.toMinutes());
// Output: 750
```

### subtract

Subtracts another duration from this duration.

```typescript
const difference = (12).hours().subtract((30).minutes());
console.log(difference.toMinutes());
// Output: 630
```

### multiply

Multiplies this duration by a scalar factor.

```typescript
const multiplied = (10).minutes().multiply(2);
console.log(multiplied.toMinutes());
// Output: 20
```

### divide

Divides this duration by a scalar divisor.

```typescript
const divided = (1).hours().divide(2);
console.log(divided.toMinutes());
// Output: 30
```

### equals

Checks if this duration is equal to another duration.

```typescript
const duration1 = (5).hours();
const duration2 = (5).hours();
console.log(duration1.equals(duration2)); // Output: true
```

### lessThan

Checks if this duration is less than another duration.

```typescript
const duration1 = (10).seconds();
const duration2 = (20).seconds();

console.log(duration1.lessThan(duration2)); // Output: true
```

### greaterThan

Checks if this duration is greater than another duration.

```typescript
const duration1 = (10).seconds();
const duration2 = (5).seconds();
const result = duration1.greaterThan(duration2);
console.log(result); // Output: true
```

### compareTo

Compares this duration with another duration.

```typescript
const duration1 = (1).days();
const duration2 = (24).hours();
console.log(duration1.compareTo(duration2)); // Output: 0
```

### runIt

Splits this duration into days, hours, minutes, seconds, and nanoseconds and executes the given action with these components. The result of the action is returned.

```typescript
const result = (3600).seconds()
    .runIt((days, hours, minutes, seconds, nanoseconds) => {
        return `${days}d ${hours}h ${minutes}m ${seconds}s ${nanoseconds}ns`;
    });
console.log(result);
// Output: 0d 1h 0m 0s 0ns
```

### toString

Formats the duration as a string.

```typescript
const duration = (1).days().add((6).hours());
const formattedString = duration.toString();
console.log(formattedString);
// Output: 1d 6h 0m 0s 0ns
```