merge

Merge multiple periods into a single larger period.

API Levels

This function is available in multiple API levels:

Level 1: Pure Function

import { period, divide, merge } from '@allystudio/usetemporal/operations'
import { createNativeAdapter } from '@allystudio/usetemporal/native'

const adapter = createNativeAdapter()
const week = period(adapter, new Date(), 'week')
const days = divide(adapter, week, 'day')
const merged = merge(adapter, days)

Level 2: Builder Method

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

const temporal = createTemporal({ adapter: createNativeAdapter() })
const week = temporal.period(new Date(), 'week')
const days = temporal.divide(week, 'day')
const merged = temporal.merge(days)

Signatures

// Level 1 (Pure Function)
function merge(
  adapter: Adapter,
  periods: Period[],
  targetUnit?: Unit
): Period | null

// Level 2 (Builder Method)
temporal.merge(periods: Period[], targetUnit?: Unit): Period | null

Parameters

Level 1 (Pure Function)

• adapter - Adapter - The date adapter instance
• periods - Period[] - Array of periods to merge
• targetUnit - Unit (optional) - Force the resulting period to have this unit type

Level 2 (Builder Method)

• periods - Period[] - Array of periods to merge
• targetUnit - Unit (optional) - Force the resulting period to have this unit type

Returns

Period | null - A merged period, or the current day period if array is empty

Description

The merge function combines multiple periods into a single period. It intelligently detects when periods form natural units (like 7 days forming a week) and creates the appropriate period type. Otherwise, it creates a custom period spanning from the earliest start to the latest end.

Examples

Basic Usage (Level 1)

import { period, divide, merge } from '@allystudio/usetemporal/operations'
import { createNativeAdapter } from '@allystudio/usetemporal/native'

const adapter = createNativeAdapter()

// Get all days in a week
const week = period(adapter, new Date(), 'week')
const days = divide(adapter, week, 'day')

// Merge back into a week
const mergedWeek = merge(adapter, days)
// Result: Period with type 'week' (natural unit detected)

console.log(mergedWeek.type) // 'week'

Builder API (Level 2)

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

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

const week = temporal.period(new Date(), 'week')
const days = temporal.divide(week, 'day')
const mergedWeek = temporal.merge(days)

console.log(mergedWeek.type) // 'week'

Custom Period Merge

import { period, merge } from '@allystudio/usetemporal/operations'
import { createNativeAdapter } from '@allystudio/usetemporal/native'

const adapter = createNativeAdapter()

// Merge arbitrary periods
const period1 = period(adapter, { start: new Date('2024-01-01'), end: new Date('2024-01-10') })
const period2 = period(adapter, { start: new Date('2024-01-11'), end: new Date('2024-01-20') })

const merged = merge(adapter, [period1, period2])
console.log(merged.type) // 'custom'
console.log(merged.start) // 2024-01-01
console.log(merged.end) // 2024-01-20

Force Target Unit

import { period, divide, merge } from '@allystudio/usetemporal/operations'
import { createNativeAdapter } from '@allystudio/usetemporal/native'

const adapter = createNativeAdapter()

// Get 3 days
const week = period(adapter, new Date(), 'week')
const days = divide(adapter, week, 'day').slice(0, 3)

// Force merge as 'week' unit (even though it's only 3 days)
const merged = merge(adapter, days, 'week')
console.log(merged.type) // 'week'

Natural Unit Detection

The function recognizes these patterns:

Period Count	Period Type	Result Type	Condition
7	day	week	Must form complete week
3	month	quarter	Must be consecutive quarter months
Other	any	custom	Always creates custom period

See Also

• divide() - Split periods into smaller units
• period() - Create periods
• split() - Split period at specific point
• Period Type - Period interface
• Choosing API Level - Which level to use
• Level 1 API - Pure functions documentation
• Level 2 API - Builder pattern documentation