Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor Duration #165

Merged
merged 1 commit into from
Jul 7, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
"react-dom": "18.2.0"
},
"devDependencies": {
"@effect/data": "^0.13.2",
"@effect/data": "^0.13.3",
"@effect/io": "^0.31.1",
"@mdx-js/mdx": "^2.3.0",
"@types/node": "^18.16.1",
Expand Down
75 changes: 64 additions & 11 deletions pages/docs/data-types/duration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,36 +9,91 @@ The `Duration` module provides several constructors to create durations of diffe
```ts
import * as Duration from "@effect/data/Duration"

const duration1 = Duration.millis(500) // Create a duration of 500 milliseconds
const duration1 = Duration.millis(100) // Create a duration of 100 milliseconds
const duration2 = Duration.seconds(2) // Create a duration of 2 seconds
const duration3 = Duration.minutes(5) // Create a duration of 5 minutes
```

You can create durations using units such as milliseconds, seconds, minutes, hours, days, and weeks.
You can create durations using units such as nanoseconds, microsecond, milliseconds, seconds, minutes, hours, days, and weeks.

If you want to create an infinite duration, you can use `Duration.infinity`:

```ts
import * as Duration from "@effect/data/Duration"

console.log(String(Duration.infinity)) // Duration(Infinity)
```

Another option for creating durations is using the `Duration.decode` helper:

- `number`s are treated as milliseconds
- `bigint`s are treated as nanoseconds
- strings must be formatted as `"${number} ${unit}"`

```ts
import * as Duration from "@effect/data/Duration"

Duration.decode(10n) // same as Duration.nanos(10)
Duration.decode(100) // same as Duration.millis(100)
Duration.decode(Infinity) // same as Duration.infinity

Duration.decode("10 nanos") // same as Duration.nanos(10)
Duration.decode("20 micros") // same as Duration.micros(20)
Duration.decode("100 millis") // same as Duration.millis(100)
Duration.decode("2 seconds") // same as Duration.seconds(2)
Duration.decode("5 minutes") // same as Duration.minutes(5)
Duration.decode("7 hours") // same as Duration.hours(7)
Duration.decode("3 weeks") // same as Duration.weeks(3)
```

## Getting the Duration Value

You can retrieve the value of a duration in milliseconds using the `millis` property:
You can retrieve the value of a duration in milliseconds using the `toMillis` function:

```ts
import * as Duration from "@effect/data/Duration"

const duration = Duration.seconds(30)
console.log(Duration.toMillis(Duration.seconds(30))) // Output: 30000
```

You can retrieve the value of a duration in nanoseconds using the `toNanos` function:

```ts
import * as Duration from "@effect/data/Duration"

console.log(Duration.toNanos(Duration.millis(100))) // Output: Some(100000000n)
```

Note that `toNanos` returns an `Option<bigint>` since the duration might be infinite. If you want a `bigint` as a return type, you can use `unsafeToNanos`. However, note that it will throw an error for infinite durations:

```ts
import * as Duration from "@effect/data/Duration"

console.log(Duration.toMillis(duration)) // Output: 30000
console.log(Duration.unsafeToNanos(Duration.millis(100))) // Output: 100000000n
console.log(Duration.unsafeToNanos(Duration.infinity)) // throws "Cannot convert infinite duration to nanos"
```

## Comparing Durations

You can compare two durations using the `Order` instance provided by the `@effect/data/Duration` module. The `Order` instance defines the `compare` method, which returns a negative number if the first duration is less than the second, a positive number if it is greater, and zero if they are equal.
You can compare two durations using the following functions:

| **Function** | **Description** |
| ---------------------- | --------------------------------------------------------------------------- |
| `lessThan` | returns `true` if the first duration is less than the second |
| `lessThanOrEqualTo` | returns `true` if the first duration is less than or equal to the second |
| `greaterThan` | returns `true` if the first duration is greater than the second |
| `greaterThanOrEqualTo` | returns `true` if the first duration is greater than or equal to the second |

```ts
import * as Duration from "@effect/data/Duration"

const duration1 = Duration.seconds(30)
const duration2 = Duration.minutes(1)

console.log(Duration.Order(duration1, duration2)) // Output: -1 (duration1 is less than duration2)
console.log(Duration.lessThan(duration1, duration2)) // Output: true
console.log(Duration.lessThanOrEqualTo(duration1, duration2)) // Output: true
console.log(Duration.greaterThan(duration1, duration2)) // Output: false
console.log(Duration.greaterThanOrEqualTo(duration1, duration2)) // Output: false
```

## Performing Arithmetic Operations
Expand All @@ -51,9 +106,7 @@ import * as Duration from "@effect/data/Duration"
const duration1 = Duration.seconds(30)
const duration2 = Duration.minutes(1)

const sum = Duration.sum(duration1, duration2)
console.log(sum) // Output: Duration(90000)
console.log(String(Duration.sum(duration1, duration2))) // Output: Duration("90000 millis")

const multiplied = Duration.times(2)(duration1)
console.log(multiplied) // Output: Duration(60000)
console.log(String(Duration.times(duration1, 2))) // Output: Duration("60000 millis")
```
10 changes: 5 additions & 5 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading