Native Adapter Guide

The Native adapter is the default adapter for useTemporal. It uses JavaScript's built-in Date object with zero dependencies.

Overview

• Bundle Size: 0KB (no additional code)
• Performance: Fastest option
• Timezone Support: Local timezone only
• Best For: Applications prioritizing performance and bundle size

Installation

The native adapter is included by default:

npm install @allystudio/usetemporal

Or use only the core with explicit native adapter:

npm install @allystudio/usetemporal @allystudio/usetemporal-adapter-native

Basic Usage

Default Setup (Recommended)

import { createTemporal } from '@allystudio/usetemporal'

// Native adapter is used automatically
const temporal = createTemporal()

Explicit Setup

import { createTemporal } from '@allystudio/usetemporal'
import { createNativeAdapter } from '@allystudio/usetemporal-adapter-native'

const temporal = createTemporal({
  adapter: createNativeAdapter()
})

Features

Core Operations

All standard useTemporal operations work seamlessly:

// Create periods
const year = temporal.period( new Date(), 'year')
const month = temporal.period( new Date(), 'month')
const week = temporal.period( new Date(), 'week')

// Divide operations
const months = divide(temporal.adapter, year, 'month') // 12 months
const weeks = divide(temporal.adapter, month, 'week') // 4-6 weeks
const days = divide(temporal.adapter, week, 'day')    // 7 days

// Navigation
const nextMonth = next(temporal.adapter, month)
const prevWeek = previous(temporal.adapter, week)
const futureDate = go(temporal.adapter, month, 3) // 3 months ahead

Date Creation

// From various inputs
const period1 = temporal.period( new Date(), 'day')
const period2 = temporal.period( '2025-07-25', 'day')
const period3 = temporal.period( Date.now(), 'day')

Comparisons

const today = temporal.period( new Date(), 'day')
const tomorrow = next(temporal.adapter, today)

// Check relationships
contains(temporal.adapter, today, new Date())              // true
isSame(temporal.adapter, today, new Date(), 'day')       // true
contains(temporal.adapter, today, tomorrow.start)         // false

Limitations

No Timezone Support

The native adapter only works with the system's local timezone:

// Always uses local timezone
const period = temporal.period( new Date(), 'day')
console.log(period.start) // Local midnight

Basic Formatting

Limited formatting options compared to other adapters:

const period = temporal.period( new Date(), 'month')

// Basic string representation
console.log(period.start.toLocaleDateString()) // "7/1/2025"

// For advanced formatting, consider date-fns adapter

No Locale Support

The native adapter uses the system locale:

// Uses browser/system locale
const date = new Date()
console.log(date.toLocaleDateString()) // Depends on system

Performance Benefits

The native adapter offers the best performance:

// Benchmark example
const start = performance.now()

// Create 10,000 periods
for (let i = 0; i < 10000; i++) {
  const period = temporal.period( new Date(), 'day')
  const hours = divide(temporal.adapter, period, 'hour')
}

const end = performance.now()
console.log(`Time: ${end - start}ms`) // Typically < 50ms

Common Patterns

Calendar Generation

function generateMonthCalendar(temporal, date) {
  const month = temporal.period( date, 'month')
  const weeks = divide(temporal.adapter, month, 'week')
  
  return weeks.map(week => ({
    week,
    days: divide(temporal.adapter, week, 'day')
  }))
}

Date Range Iteration

function* dateRange(temporal, start, end, unit = 'day') {
  let current = temporal.period( start, unit)
  const endPeriod = temporal.period( end, unit)
  
  while (current.start <= endPeriod.start) {
    yield current
    current = next(temporal.adapter, current)
  }
}

// Usage
for (const day of dateRange(temporal, '2025-01-01', '2025-01-31')) {
  console.log(day.date)
}

Working with Today

const temporal = createTemporal()

// Various "today" operations
const today = temporal.period( new Date(), 'day')
const thisWeek = temporal.period( new Date(), 'week')
const thisMonth = temporal.period( new Date(), 'month')

// Check if a date is today
function isToday(temporal, date) {
  return isSame(temporal.adapter, date, new Date(), 'day')
}

Best Practices

1. Use for Local Dates Only

// ✅ Good: Local dates
const meeting = temporal.period( meetingDate, 'hour')

// ❌ Bad: Timezone-sensitive operations
// const nycTime = ... // Not possible with native

2. Leverage Zero-Dependency

// ✅ Good: Keep bundle minimal
import { createTemporal } from '@allystudio/usetemporal'

// ❌ Avoid: Don't add complexity if not needed
// import moment from 'moment' // Unnecessary

3. Consider Future Migration

// Structure code for easy adapter switching
const createCalendar = (temporal) => {
  // All logic uses temporal parameter
  return {
    getMonth: (date) => temporal.period( date, 'month'),
    getWeeks: (month) => divide(temporal.adapter, month, 'week')
  }
}

// Easy to switch adapters later
const calendar = createCalendar(temporal)

When to Use Native Adapter

✅ Perfect for:

• Static websites
• Small web applications
• Performance-critical applications
• Projects with strict bundle size limits
• Local-only date operations
• Prototypes and MVPs

❌ Not suitable for:

• Multi-timezone applications
• International applications needing locale support
• Applications requiring complex date formatting
• Projects needing timezone-aware calculations

Migration Path

If you outgrow the native adapter, switching is straightforward:

// Step 1: Install new adapter
// npm install @allystudio/usetemporal-adapter-date-fns date-fns

// Step 2: Update initialization
import { createDateFnsAdapter } from '@allystudio/usetemporal-adapter-date-fns'

const temporal = createTemporal({
  adapter: createDateFnsAdapter()
})

// Step 3: All existing code continues to work!

Next Steps

• Learn about divide pattern
• Explore calendar examples
• Check performance guide
• Consider date-fns adapter for formatting
• Consider Luxon adapter for timezones