# AkiDate

### <mark style="color:red;">Installation</mark>

```bash
pnpm add @akinon/akidate
```

### <mark style="color:red;">Basic Usage</mark>

```tsx
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"
```

### <mark style="color:red;">API Reference</mark>

#### setLocale

Sets the global locale for date formatting.

```tsx
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.

```tsx
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.

```tsx
// 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.

```tsx
// 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 |

***

### <mark style="color:red;">Usage with Akilocale</mark>

Integrate with `@akinon/akilocale` for automatic locale synchronization:

```tsx
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>;
};
```

### <mark style="color:red;">Common Use Cases</mark>

#### Table Column Formatting

```tsx
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

```tsx
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

```tsx
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

```tsx
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');
};
```

### <mark style="color:red;">Best Practices</mark>

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/akinon-ui/ui-kit/utilities/akidate.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.