timelang

Smart autocomplete

Intelligent suggestions for date and time inputs

this morningSat, Jan 17, 9:00 AM
this afternoonSat, Jan 17, 2:00 PM
in 30 minutesSat, Jan 17, 2:09 PM
in an hourSat, Jan 17, 2:39 PM
this eveningSat, Jan 17, 6:00 PM
tomorrow at 9amSun, Jan 18, 9:00 AM
 
npm install @timelang/suggest

API

suggest(input, options?)

Returns suggestions with pre-resolved dates based on user input. 

import { suggest } from '@timelang/suggest'


const suggestions = suggest('tom')
// → [
//   { label: 'tomorrow', date: Date },
//   { label: 'tomorrow morning', date: Date },
//   { label: 'tomorrow afternoon', date: Date },
//   ...
// ]


// Each suggestion includes:
// - label: The suggestion text
// - date: The resolved Date object

suggestTime(input, options?)

Returns time-only suggestions for dedicated time input fields. 

import { suggestTime } from '@timelang/suggest'


const suggestions = suggestTime('9')
// → [
//   { label: '09:00 am', hour: 9, minute: 0, period: 'am' },
//   { label: '09:00 pm', hour: 9, minute: 0, period: 'pm' },
//   ...
// ]


// Supports various input formats:
suggestTime('930')   // 9:30
suggestTime('750pm') // 7:50 PM
suggestTime('14')    // 14:00 (2 PM)

Options

suggest('next', {
  referenceDate: new Date(),  // Base date for resolving expressions
  limit: 5,                   // Maximum suggestions (default: 5)
  mode: 'datetime',           // 'date' | 'datetime' | 'time'
  minDate: new Date(),        // Filter out dates before this
  maxDate: new Date(),        // Filter out dates after this
  sortPreference: 'closest',  // 'closest' | 'future' | 'past'
})

mode

Controls which types of suggestions are returned. 

// Only date suggestions (excludes time-only like "in 2 hours")
suggest('next', { mode: 'date' })


// Only time suggestions (excludes date-only like "next week")
suggest('morning', { mode: 'time' })


// All suggestions (default)
suggest('next', { mode: 'datetime' })

minDate / maxDate

Constrain suggestions to a date range. 

// Future dates only
suggest('', { minDate: new Date() })


// Past dates only
suggest('', { maxDate: new Date() })


// Within a specific range
suggest('', {
  minDate: new Date('2025-01-01'),
  maxDate: new Date('2025-12-31')
})

sortPreference

Controls how suggestions are ordered. 

// Closest to reference date first (default)
suggest('', { sortPreference: 'closest' })


// Future dates first, then chronological
suggest('', { sortPreference: 'future' })


// Past dates first, then reverse chronological
suggest('', { sortPreference: 'past' })

Time Options

Options for the suggestTime function.

suggestTime('9', {
  step: 15,       // Minute intervals (default: 15)
  limit: 10,      // Maximum suggestions (default: 10)
  format: '12h',  // '12h' or '24h' (default: '12h')
})

step

Controls the minute intervals for suggestions. 

suggestTime('9', { step: 30 })
// → 9:00, 9:30, 10:00...


suggestTime('9', { step: 5 })
// → 9:00, 9:05, 9:10...

format

Controls the output format and returned values. 

// 12-hour format (default)
suggestTime('9', { format: '12h' })
// → { label: '09:00 am', hour: 9, minute: 0, period: 'am' }


// 24-hour format
suggestTime('9', { format: '24h' })
// → { label: '09:00', hour: 9, minute: 0 }

Types

// suggest() types
interface Suggestion {
  label: string
  date: Date
}


type SuggestMode = 'date' | 'datetime' | 'time'
type SortPreference = 'closest' | 'future' | 'past'


interface SuggestOptions {
  referenceDate?: Date
  limit?: number
  mode?: SuggestMode
  minDate?: Date
  maxDate?: Date
  sortPreference?: SortPreference
}


// suggestTime() types
interface TimeSuggestion {
  label: string
  hour: number       // 1-12 for '12h', 0-23 for '24h'
  minute: number
  period?: 'am' | 'pm'  // Only present when format is '12h'
}


type TimeFormat = '12h' | '24h'


interface SuggestTimeOptions {
  step?: number      // Minute intervals (default: 15)
  limit?: number     // Max suggestions (default: 10)
  format?: TimeFormat  // '12h' or '24h' (default: '12h')
}