Duration
The Duration class provides time duration values with nanosecond precision and support for human-readable formats like "5h30m".
Import:
import { Duration } from 'surrealdb';
Source: value/duration.ts
Constructor
new Duration(value)
Create a new duration value.
Syntax
new Duration(duration)
new Duration(string)
new Duration([seconds, nanoseconds])
Parameters
| Parameter | Type | Description |
|---|
value required | Duration | string | [bigint, bigint] | Value to create duration from. |
Examples
const fiveMinutes = new Duration('5m');
const oneHour = new Duration('1h');
const complex = new Duration('2h30m15s');
const precise = new Duration('1s500ms250us125ns');
const duration = new Duration([300n, 0n]);
const clone = new Duration(fiveMinutes);
Supported Units
| Unit | Symbol | Example |
|---|
| Nanoseconds | ns | ”500ns” |
| Microseconds | us, µs | ”250us” |
| Milliseconds | ms | ”100ms” |
| Seconds | s | ”30s” |
| Minutes | m | ”5m” |
| Hours | h | ”2h” |
| Days | d | ”7d” |
| Weeks | w | ”4w” |
| Years | y | ”1y” |
Static Methods
Duration.parse(string)
Parse a duration from a human-readable string.
Syntax
Duration.parse(str)
Parameters
| Parameter | Type | Description |
|---|
str required | string | Duration string (e.g., “5h30m”). |
Returns
Duration - Parsed duration
Examples
const fiveMinutes = Duration.parse('5m');
const oneHour = Duration.parse('1h');
const oneDay = Duration.parse('1d');
const sessionTimeout = Duration.parse('2h30m');
const cacheExpiry = Duration.parse('1d12h');
const precise = Duration.parse('1h30m45s500ms');
const measurement = Duration.parse('1s250ms500us750ns');
Instance Methods
.toMilliseconds()
Convert duration to milliseconds.
Syntax
duration.toMilliseconds()
Returns
number - Duration in milliseconds
Example
const duration = Duration.parse('5m30s');
console.log(duration.toMilliseconds());
.toSeconds()
Convert duration to seconds.
Syntax
duration.toSeconds()
Returns
number - Duration in seconds
Example
const duration = Duration.parse('2h30m');
console.log(duration.toSeconds());
.toString()
Convert to human-readable string.
Syntax
duration.toString()
Returns
string - Human-readable duration string
Example
const duration = Duration.parse('2h30m15s');
console.log(duration.toString());
.toJSON()
Serialize for JSON.
Syntax
duration.toJSON()
Returns
string - Duration string for JSON
.plus(duration)
Add another duration.
Syntax
duration.plus(other)
Parameters
| Parameter | Type | Description |
|---|
other required | Duration | Duration to add. |
Returns
Duration - Sum of durations
Example
const base = Duration.parse('1h');
const extra = Duration.parse('30m');
const total = base.plus(extra);
console.log(total.toString());
.minus(duration)
Subtract another duration.
Syntax
duration.minus(other)
Returns
Duration - Difference of durations
.equals(other)
Check if two durations are equal.
Syntax
duration.equals(other)
Returns
boolean - True if equal
Complete Examples
Timeouts and Expiration
import { Surreal, Duration, DateTime, Table } from 'surrealdb';
const db = new Surreal();
await db.connect('ws://localhost:8000');
const session = await db.create(new Table('sessions')).content({
user: userId,
created_at: DateTime.now(),
timeout: Duration.parse('24h')
});
const expiresAt = session.created_at.plus(session.timeout);
Query Timeouts
const users = await db.select(new Table('users'))
.timeout(Duration.parse('5s'));
const result = await db.query(`
SELECT * FROM complex_view
`).timeout(Duration.parse('30s')).collect();
Rate Limiting
const rateLimit = {
window: Duration.parse('1m'),
maxRequests: 100
};
await db.create(new Table('rate_limits')).content({
user: userId,
window: rateLimit.window,
requests: 1,
window_start: DateTime.now()
});
Scheduled Tasks
const task = await db.create(new Table('tasks')).content({
name: 'Send email',
delay: Duration.parse('5m'),
created_at: DateTime.now()
});
const executeAt = task.created_at.plus(task.delay);
console.log('Execute at:', executeAt.toString());
Cache TTL
const cacheEntry = await db.create(new Table('cache')).content({
key: 'user:123',
value: userData,
ttl: Duration.parse('1h'),
cached_at: DateTime.now()
});
function isCacheValid(entry: typeof cacheEntry): boolean {
const expiresAt = entry.cached_at.plus(entry.ttl);
return DateTime.now().getTime() < expiresAt.getTime();
}
const start = DateTime.now();
const end = DateTime.now();
const elapsed = Duration.parse(
`${end.getTime() - start.getTime()}ms`
);
console.log('Operation took:', elapsed.toString());
Conversion Examples
const duration = Duration.parse('2h30m');
const ms = duration.toMilliseconds();
const seconds = duration.toSeconds();
const str = duration.toString();
const doubled = duration.plus(duration);
console.log(doubled.toString());
Complex Durations
const precise = Duration.parse('1s500ms250us125ns');
const complex = Duration.parse('1d2h30m15s');
const extended = complex.plus(Duration.parse('12h'));
console.log(extended.toString());
Best Practices
const timeout = Duration.parse('30s');
const cacheTTL = Duration.parse('1h');
const timeout = new Duration([30n, 0n]);
2. Use Duration for Time Arithmetic
const now = DateTime.now();
const future = now.plus(Duration.parse('1h'));
const future = new DateTime(now.getTime() + 3600000);
3. Store Durations in Database
await db.create(table).content({
timeout: Duration.parse('24h')
});
await db.create(table).content({
timeout: 86400000
});
4. Use Appropriate Units
const oneDay = Duration.parse('1d');
const oneWeek = Duration.parse('1w');
const oneDay = Duration.parse('24h');
const oneWeek = Duration.parse('168h');
See Also
