AkiDate

A lightweight date utility library for Akinon applications. Wraps Day.js with built-in localization support and convenient parsing/formatting methods.

Installation

pnpm add @akinon/akidate

Basic Usage

import { akidate } from '@akinon/akidate';

// Format an ISO date string
const formatted = akidate.formatIsoDate('2024-01-15T14:30:00.000Z', 'LL');
// Output: "January 15, 2024"

// Set locale for localized formatting
akidate.setLocale('tr');
const turkishDate = akidate.formatIsoDate('2024-01-15T14:30:00.000Z', 'LL');
// Output: "15 Ocak 2024"

API Reference

setLocale

Sets the global locale for date formatting.

akidate.setLocale('tr');

Parameters

Parameter	Type	Description
locale	string	Two-letter locale code

Supported Locales

Code	Language
en	English (default)
tr	Turkish
de	German
fr	French
es	Spanish
pt	Portuguese
ru	Russian
ar	Arabic

---

formatIsoDate

Formats an ISO date string using localized format templates.

const date = '2024-01-15T14:30:00.000Z';

// Default format (L LT): "01/15/2024 2:30 PM"
akidate.formatIsoDate(date);

// Long date format: "January 15, 2024"
akidate.formatIsoDate(date, 'LL');

// Long date with time: "January 15, 2024 2:30 PM"
akidate.formatIsoDate(date, 'LLL');

Parameters

Parameter	Type	Default	Description
date	string	-	ISO date string
template	string	'L LT'	Localized format template

Returns

Type	Description
string	Formatted date string

Format Templates

Template	Example (en)	Description
L	01/15/2024	Date (numeric)
LL	January 15, 2024	Date (long)
LLL	January 15, 2024 2:30 PM	Date and time
LLLL	Monday, January 15, 2024 2:30 PM	Full date with weekday
LT	2:30 PM	Time
LTS	2:30:45 PM	Time with seconds
l	1/15/2024	Date (short)
ll	Jan 15, 2024	Date (abbreviated)
lll	Jan 15, 2024 2:30 PM	Date and time (short)

---

toIsoDate

Converts various date inputs into an ISO string. Useful for normalizing different date formats before sending to an API.

// From string
akidate.toIsoDate('2024-01-15');
// Output: "2024-01-15T00:00:00.000Z"

// From Date object
akidate.toIsoDate(new Date(2024, 0, 15));
// Output: "2024-01-15T00:00:00.000Z"

// From Day.js instance
import dayjs from 'dayjs';
akidate.toIsoDate(dayjs('2024-01-15'));
// Output: "2024-01-15T00:00:00.000Z"

// Invalid input returns undefined
akidate.toIsoDate('invalid-date');
// Output: undefined

Parameters

Parameter	Type	Description
value	unknown	Date input (string, Date, Day.js, or object with toISOString)

Returns

Type	Description
string | undefined	ISO date string, or undefined if invalid

---

parse

Parses various date inputs into a Day.js instance. Useful for date manipulation and comparison.

// Parse a string
const date = akidate.parse('2024-01-15');
date?.format('YYYY-MM-DD'); // "2024-01-15"
date?.add(7, 'day').format('YYYY-MM-DD'); // "2024-01-22"

// Parse a Date object
const fromDate = akidate.parse(new Date(2024, 0, 15));

// Invalid input returns undefined
const invalid = akidate.parse('not-a-date');
// Output: undefined

Parameters

Parameter	Type	Description
value	unknown	Date input (string, Date, Day.js, or object with toISOString)

Returns

Type	Description
Dayjs | undefined	Day.js instance, or undefined if invalid

---

Usage with Akilocale

Integrate with @akinon/akilocale for automatic locale synchronization:

import { akidate } from '@akinon/akidate';
import { useAkilocale } from '@akinon/akilocale';
import { useEffect } from 'react';

const DateDisplay = ({ isoDate }: { isoDate: string }) => {
  const { locale } = useAkilocale();

  useEffect(() => {
    akidate.setLocale(locale.lng);
  }, [locale.lng]);

  return <span>{akidate.formatIsoDate(isoDate, 'LL')}</span>;
};

Common Use Cases

Table Column Formatting

import { akidate } from '@akinon/akidate';
import type { AkitableColumn } from '@akinon/akitable';

const columns: AkitableColumn<Order>[] = [
  {
    title: 'Order Date',
    dataIndex: 'createdAt',
    render: (value) => akidate.formatIsoDate(value, 'L LT')
  },
  {
    title: 'Delivery Date',
    dataIndex: 'deliveryDate',
    render: (value) => value ? akidate.formatIsoDate(value, 'LL') : '-'
  }
];

Form Date Handling

import { akidate } from '@akinon/akidate';

const handleSubmit = (values: FormValues) => {
  const payload = {
    ...values,
    // Normalize date picker value to ISO string
    startDate: akidate.toIsoDate(values.startDate),
    endDate: akidate.toIsoDate(values.endDate)
  };
  
  api.createEvent(payload);
};

Date Comparison

import { akidate } from '@akinon/akidate';

const isExpired = (expiryDate: string): boolean => {
  const expiry = akidate.parse(expiryDate);
  const now = akidate.parse(new Date());
  
  if (!expiry || !now) return false;
  
  return expiry.isBefore(now);
};

Relative Time Calculation

import { akidate } from '@akinon/akidate';

const getDaysRemaining = (targetDate: string): number | undefined => {
  const target = akidate.parse(targetDate);
  const now = akidate.parse(new Date());
  
  if (!target || !now) return undefined;
  
  return target.diff(now, 'day');
};

Best Practices

1. Set locale once at app initialization - Call setLocale in your app's root component or initialization logic

2. Use toIsoDate for API payloads - Always normalize dates before sending to APIs

3. Handle undefined returns - Both toIsoDate and parse can return undefined for invalid input

4. Use localized templates - Prefer templates like LL over YYYY-MM-DD for user-facing dates

5. Sync with Akilocale - Keep akidate locale in sync with your app's language setting