Date and Time Implementation Skill

Guide for implementing date/time operations using dayjs utility with unix timestamps.

Purpose

USE this skill when:

• Adding date/time functionality to components
• Implementing API endpoints with date fields
• Working with scheduled dates or timestamps
• Formatting dates for display

Critical Rules

⚠️ ALWAYS import from ~/app/utils/date.ts - NEVER import dayjs directly ⚠️ USE unix timestamps (seconds) - For API communication and database storage ⚠️ STORE as integer - Database columns use integer type for unix timestamps ⚠️ USE Polish locale - Pre-configured in app/utils/date.ts

Import Pattern

// ✅ CORRECT: Import pre-configured dayjs
import { dayjs, formatDatePL, dateToUnixTimestamp, unixTimestampToDate } from "~/app/utils/date"

// ❌ WRONG: Direct import bypasses configuration
import dayjs from "dayjs"

Unix Timestamp Strategy

Converting to Unix Timestamp

import { dateToUnixTimestamp, dayjs } from "~/app/utils/date"

// From Date object
const timestamp = dateToUnixTimestamp(new Date()) // Returns seconds

// From dayjs object
const timestamp = dayjs().unix()

// From ISO string
const timestamp = dayjs("2025-01-15").unix()

Converting from Unix Timestamp

import { unixTimestampToDate, dayjs } from "~/app/utils/date"

// To Date object
const date = unixTimestampToDate(1736942400)

// To dayjs for manipulation
const dayjsDate = dayjs.unix(1736942400)
const formatted = dayjsDate.format("YYYY-MM-DD")

API Data Exchange

Sending to API

import { dateToUnixTimestamp } from "~/app/utils/date"

const formData = {
  title: "Meeting",
  scheduledDate: dateToUnixTimestamp(selectedDate), // seconds
}

await $fetch("/api/meetings", {
  method: "POST",
  body: formData,
})

Receiving from API

import { formatDatePL } from "~/app/utils/date"

const { data: meetings } = await useFetch<Meeting[]>("/api/meetings")

const displayDate = computed(() => {
  if (!meetings.value?.[0]) return ""
  return formatDatePL(meetings.value[0].scheduledDate)
})

Database Schema Pattern

// server/database/schema.ts
export const meetings = sqliteTable("meetings", {
  id: text("id").primaryKey(),
  scheduledDate: integer("scheduled_date").notNull(), // Unix timestamp (seconds)
  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
})

Formatting Dates

import { formatDatePL, dayjs } from "~/app/utils/date"

// Polish locale formatting
const formatted = formatDatePL(timestamp) // "15 stycznia 2025"

// Custom formatting
const custom = dayjs.unix(timestamp).format("DD.MM.YYYY") // "15.01.2025"

Component Integration with CalendarDate

import { CalendarDate } from "@internationalized/date"
import { dateToUnixTimestamp, unixTimestampToDate, dayjs } from "~/app/utils/date"

// Convert CalendarDate to unix timestamp
function calendarDateToUnixTimestamp(calDate: CalendarDate): number {
  const jsDate = new Date(calDate.year, calDate.month - 1, calDate.day)
  return dateToUnixTimestamp(jsDate)
}

// Convert unix timestamp to CalendarDate
function unixTimestampToCalendarDate(timestamp: number): CalendarDate {
  const dayjsDate = dayjs.unix(timestamp)
  return new CalendarDate(
    dayjsDate.year(),
    dayjsDate.month() + 1,
    dayjsDate.date()
  )
}

Anti-Patterns

❌ Direct dayjs import ❌ Using milliseconds instead of seconds ❌ Storing ISO strings in database ❌ Using Date.now() / 1000 (use dateToUnixTimestamp)

References

• Full patterns: .agents/date-time-patterns.md
• dayjs documentation: Official docs (Context7)