Duration

import { Duration } from 'surrealdb';

Syntax

new Duration(duration) // Clone existing
new Duration(string) // Parse human-readable string
new Duration([seconds, nanoseconds]) // From tuple

// Parse human-readable durations
const fiveMinutes = new Duration('5m');
const oneHour = new Duration('1h');
const complex = new Duration('2h30m15s');
const precise = new Duration('1s500ms250us125ns');

// From tuple [seconds, nanoseconds]
const duration = new Duration([300n, 0n]); // 5 minutes

// Clone existing
const clone = new Duration(fiveMinutes);

Syntax

Duration.nanoseconds(ns)

const d = Duration.nanoseconds(500);

Syntax

Duration.microseconds(µs)

const d = Duration.microseconds(250);

Syntax

Duration.milliseconds(ms)

const d = Duration.milliseconds(1500);
console.log(d.toString()); // '1s500ms'

Syntax

Duration.seconds(s)

const d = Duration.seconds(90);
console.log(d.toString()); // '1m30s'

Syntax

Duration.minutes(m)

const d = Duration.minutes(5);
console.log(d.toString()); // '5m'

Syntax

Duration.hours(h)

const d = Duration.hours(2);
console.log(d.toString()); // '2h'

Syntax

Duration.days(d)

const d = Duration.days(7);
console.log(d.toString()); // '1w'

Syntax

Duration.weeks(w)

const d = Duration.weeks(4);
console.log(d.toString()); // '4w'

Syntax

Duration.years(y)

const d = Duration.years(1);
console.log(d.toString()); // '1y'

Syntax

Duration.parseFloat(input)

const d = Duration.parseFloat('1.5s');
console.log(d.milliseconds); // 1500n

Syntax

Duration.measure()

const elapsed = Duration.measure();

// ... perform some operation ...

const duration = elapsed();
console.log('Operation took:', duration.toString());

const duration = new Duration('2h30m');

console.log(duration.hours);        // 2n
console.log(duration.minutes);      // 150n
console.log(duration.seconds);      // 9000n
console.log(duration.milliseconds); // 9000000n
console.log(duration.nanoseconds);  // 9000000000000n

Syntax

duration.toString()

const duration = new Duration('2h30m15s');
console.log(duration.toString()); // '2h30m15s'

Syntax

duration.toJSON()

Syntax

duration.toCompact()

const d = new Duration('5m30s');
console.log(d.toCompact()); // [330n, 0n] or [330n]

Syntax

duration.add(other)

const base = new Duration('1h');
const extra = new Duration('30m');
const total = base.add(extra);
console.log(total.toString()); // '1h30m'

Syntax

duration.sub(other)

const total = new Duration('2h');
const part = new Duration('30m');
const remaining = total.sub(part);
console.log(remaining.toString()); // '1h30m'

Syntax

duration.mul(factor)

const base = new Duration('30m');
const doubled = base.mul(2);
console.log(doubled.toString()); // '1h'

Syntax

duration.div(divisor: Duration)       // Returns bigint (ratio)
duration.div(divisor: number | bigint) // Returns Duration

const total = new Duration('2h');
const unit = new Duration('30m');

// Ratio: how many 30m intervals in 2h?
const ratio = total.div(unit); // 4n

// Scalar division
const half = total.div(2);
console.log(half.toString()); // '1h'

Syntax

duration.mod(mod)

const total = new Duration('2h20m');
const interval = new Duration('1h');
const remainder = total.mod(interval);
console.log(remainder.toString()); // '20m'

Syntax

duration.equals(other)

import { Surreal, Duration, DateTime, Table } from 'surrealdb';

const db = new Surreal();
await db.connect('ws://localhost:8000');

// Set session timeout
const session = await db.create(new Table('sessions')).content({
    user: userId,
    created_at: DateTime.now(),
    timeout: new Duration('24h')
});

// Set timeout on queries
const users = await db.select(new Table('users'))
    .timeout(new Duration('5s'));

// Timeout on complex query
const result = await db.query(`
    SELECT * FROM complex_view
`).timeout(new Duration('30s')).collect();

// Define rate limit window
const rateLimit = {
    window: new Duration('1m'),
    maxRequests: 100
};

// Store rate limit data
await db.create(new Table('rate_limits')).content({
    user: userId,
    window: rateLimit.window,
    requests: 1,
    window_start: DateTime.now()
});

// Schedule task with delay
const task = await db.create(new Table('tasks')).content({
    name: 'Send email',
    delay: new Duration('5m'),
    created_at: DateTime.now()
});

// Set cache entry with TTL
const cacheEntry = await db.create(new Table('cache')).content({
    key: 'user:123',
    value: userData,
    ttl: new Duration('1h'),
    cached_at: DateTime.now()
});

// Check if cache is still valid
function isCacheValid(entry: typeof cacheEntry): boolean {
    const elapsed = DateTime.now().milliseconds - entry.cached_at.milliseconds;
    return elapsed < entry.ttl.milliseconds;
}

// Measure operation duration
const elapsed = Duration.measure();

// ... perform operation ...

const duration = elapsed();
console.log('Operation took:', duration.toString());

// Parse from string
const duration = new Duration('2h30m');

// Access as different units
const ms = duration.milliseconds; // 9000000n
const secs = duration.seconds;    // 9000n
const mins = duration.minutes;    // 150n
const hrs = duration.hours;       // 2n

// Back to string
const str = duration.toString(); // '2h30m'

// Arithmetic
const doubled = duration.add(duration);
console.log(doubled.toString()); // '5h'

// Very precise timing
const precise = new Duration('1s500ms250us125ns');

// Multiple units
const complex = new Duration('1d2h30m15s');

// Arithmetic
const extended = complex.add(new Duration('12h'));
console.log(extended.toString()); // '1d14h30m15s'

// Create durations from numeric values
const timeout = Duration.seconds(30);
const cacheTTL = Duration.hours(1);
const retryDelay = Duration.milliseconds(500);
const oneWeek = Duration.weeks(1);

// Useful when values come from config or computation
const maxRetries = 3;
const backoff = Duration.seconds(2).mul(maxRetries);

// Good: Clear intent
const timeout = new Duration('30s');
const cacheTTL = new Duration('1h');

// Avoid: Raw numbers
const timeout = new Duration([30n, 0n]);

// Good: Type-safe duration arithmetic
const base = new Duration('1h');
const extended = base.add(new Duration('30m'));

// Good: Use static factories for computed values
const delay = Duration.seconds(retryCount * 2);

// Good: Store as Duration for type safety
await db.create(table).content({
    timeout: new Duration('24h')
});

// Avoid: Store as number
await db.create(table).content({
    timeout: 86400000 // What unit is this?
});

// Good: Use largest appropriate unit
const oneDay = new Duration('1d');
const oneWeek = new Duration('1w');

// Avoid: Unnecessary smaller units
const oneDay = new Duration('24h');
const oneWeek = new Duration('168h');

// Good: Built-in measurement
const elapsed = Duration.measure();
await performOperation();
console.log('Took:', elapsed().toString());