Operations

All operations in useTemporal are pure functions that work with Period objects.

Navigation Operations

Move through time periods:

next()

Move to the next period of the same type:

import { next } from '@allystudio/usetemporal/operations'

const month = usePeriod(temporal, 'month')
const nextMonth = next(temporal.adapter, month.value)

// Update browsing to navigate
temporal.browsing.value = nextMonth

previous()

Move to the previous period:

import { previous } from '@allystudio/usetemporal'

const prevMonth = previous(temporal.adapter, month.value)

go()

Navigate by multiple steps:

import { go } from '@allystudio/usetemporal'

// Move forward 3 months
const future = go(temporal.adapter, month.value, 3)

// Move backward 2 months
const past = go(temporal.adapter, month.value, -2)

Comparison Operations

contains()

Check if a date or period is within another period:

import { contains } from '@allystudio/usetemporal'

const month = usePeriod(temporal, 'month')
const today = new Date()

if (contains(month.value, today)) {
  console.log('Today is in this month')
}

// Also works with periods
const day = usePeriod(temporal, 'day')
if (contains(month.value, day.value)) {
  console.log('Day is within month')
}

isSame()

Check if two dates fall within the same period:

import { isSame } from '@allystudio/usetemporal/operations'

const date1 = new Date('2024-01-15')
const date2 = new Date('2024-01-20')

console.log(isSame(temporal.adapter, date1, date2, 'day'))   // false
console.log(isSame(temporal.adapter, date1, date2, 'month')) // true
console.log(isSame(temporal.adapter, date1, date2, 'year'))  // true

Division Operations

divide()

The signature operation - divide any period into smaller units:

import { divide } from '@allystudio/usetemporal/operations'

const year = usePeriod(temporal, 'year')
const months = divide(temporal.adapter, year.value, 'month')     // 12 periods

const month = months[0]
const days = divide(temporal.adapter, month, 'day')              // 28-31 periods

const day = days[0]  
const hours = divide(temporal.adapter, day, 'hour')              // 24 periods

Zooming Operations

Navigate between hierarchy levels using composition:

Zoom Pattern (v2.0+)

The zoom operations have been removed in v2.0.0. Use these patterns instead:

Zoom In Pattern:

import { divide, contains } from '@allystudio/usetemporal'

const year = usePeriod(temporal, 'year')

// Get all months in the year
const months = divide(temporal.adapter, year.value, 'month')

// Find March (3rd month, 0-indexed)
const march = months[2]

// Or find the month containing a specific date
const targetMonth = months.find(m => contains(m, someDate)) || months[0]

Zoom Out Pattern:

import { period } from '@allystudio/usetemporal/operations'

const day = usePeriod(temporal, 'day')

// Zoom out to the containing month (Builder API)
const month = temporal.period(day.value.date, 'month')

// Zoom out to the containing year
const year = temporal.period(day.value.date, 'year')

// Or using pure functions (Level 1)
const month = period(temporal.adapter, day.value.date, 'month')

Direct Navigation Pattern:

import { period } from '@allystudio/usetemporal/operations'

const hour = usePeriod(temporal, 'hour')

// Navigate from hour to its year (Builder API)
const year = temporal.period(hour.value.date, 'year')

// Navigate from hour to its month
const month = temporal.period(hour.value.date, 'month')

Advanced Operations

split()

Split a period into custom segments:

import { split } from '@allystudio/usetemporal'

const month = usePeriod(temporal, 'month')

// Split into 3 equal parts
const thirds = split(temporal, month.value, { count: 3 })

// Split by duration
const biweekly = split(temporal, month.value, { 
  duration: { weeks: 2 } 
})

merge()

Combine adjacent periods:

import { merge } from '@allystudio/usetemporal'

const week1 = usePeriod(temporal, 'week')
const week2 = next(temporal.adapter, week1.value)

const fortnight = merge(temporal.adapter, [week1.value, week2.value])

Creating Periods

period()

Create a period from any date:

import { period } from '@allystudio/usetemporal/operations'

const someDate = new Date('2024-06-15')

// Level 1: Pure function
const june = period(adapter, someDate, 'month')
const year2024 = period(adapter, someDate, 'year')

// Level 2: Builder API
const june = temporal.period(someDate, 'month')
const year2024 = temporal.period(someDate, 'year')

Best Practices

1. Operations are pure - They don't modify inputs
2. Chain operations - Combine for complex navigation
3. Use proper unit - Match the unit to your use case
4. Cache results - Operations can be memoized

Next Steps

• See API Reference for detailed signatures
• Check Examples for real usage
• Learn about Performance optimization